From 55e6f4b453a65762a4bcc04d23290e5868494a77 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 15:46:01 -0800 Subject: [PATCH 01/15] feat(box): Let a boxed agent use the MCP tools of the other gateways of its project ## Problem A runtime without a box gets the URL of each gateway of its project in `AGENTCORE_GATEWAY__URL`, and its code uses the MCP tools of that gateway. A boxed agent on AgentCore Runtime cannot do this. Its box has no route to the host of the gateway, so the box refuses each request. The user cannot add the route. Build refuses `aws://` for a gateway host with `UNSIGNABLE_HOST`, and the ID of the gateway is not known before the first deploy. A target and a grant that you make by hand operate, but build does not keep them in `agentcore.json`. ## Solution - **Which gateways.** A box runtime gets each gateway without `boundRuntime`, the same gateways that the L3 binds to a runtime without a box (`projectGatewaysOf`). A `PRIVATE_VPC` runtime gets none. A `CUSTOM_JWT` gateway gets a warning and no target, because the Box gateway signs only with its role. - **The target.** Build writes `egress-gateway-` on the Box gateway of the runtime, with `passthrough.gateway: ""` and `GATEWAY_IAM_ROLE` for `bedrock-agentcore` in the build region. A `NONE` gateway gets no outbound auth. Build changes and removes the target as it does each other `egress-` target. A host of the profile cannot use its name (`TARGET_NAME_COLLISION`), and the limit of 100 targets counts it. - **The schema.** `passthrough` can have `gateway` or `endpoint`, but not the two. The name must be a gateway of the project without `boundRuntime`, and not the gateway of the target. - **The pack.** The `@box/agentcore` pack of each box runtime declares `gateways..url` from `env:_URL` and `gateways..host` from `env:_HOST`, each with a pattern. The agent gets `_URL` in `[agent.env]` from the input, so the code that uses the gateway without a box operates in the box. - **The Runtime profile.** Only the Runtime profile gets `[mcp.]`, with `destinations = ["${{ inputs.gateways..host }}"]` and one backend to the URL of the Box gateway and `/egress-gateway-`, signed with `aws://` for `bedrock-agentcore`. Box adds a permit for each tool of a declared server, and a forbid rule of the policy stays. The local profile does not change. A server of the local profile with the name of a gateway stops build (`RUNTIME_GATEWAY_SERVER_NAME_TAKEN`). - **Gateway hosts in the profile.** `AWS_ENDPOINTS` has the gateway host, with the service `bedrock-agentcore`. An entry that signs for a gateway host with `aws://` stops build with `UNSIGNABLE_HOST`, and the message names the route that build adds. Build cannot tell a gateway of this project from a gateway of a different project by its host, because the ID of a gateway is known only after deploy. - **IAM warnings.** `boxGatewayIamWarnings` gives no warning for a target with `passthrough.gateway`, because the L3 gives the grant. It gives a warning for a target to a gateway host when the role has no `bedrock-agentcore:InvokeGateway`. - **Interfaces that changed.** `PassthroughConfigSchema` (`endpoint` is optional, `gateway` is new), `BoxNetwork.projectGateways`, `RuntimeProfileContext.projectGateways`, `renderAgentCorePack(spec, gateways)`, and the problem code `RUNTIME_GATEWAY_SERVER_NAME_TAKEN`. - **Dependency.** The target needs the L3 branch `sa/box-gateway-to-gateway` of aws/agentcore-l3-cdk-constructs. That branch gives the endpoint, the grant, and `_HOST`. - **Not done.** box 0.1.11-preview.10 takes an input in `destinations` only when its value is a host. Thus the pack reads `_HOST` and not the URL. If the CLI wrote the target from `deployed-state.json`, each new project must deploy two times. ## Tests - `src/core/project/boxNetwork/network.test.ts`, "the gateways of the project": the gateways that the agent gets, a `PRIVATE_VPC` runtime, a `CUSTOM_JWT` gateway, the name collision, the target that build wrote, the limit of 100, and the refusal of a signed gateway host in `[egress]` and `[mcp]`. "boxGatewayIamWarnings for a gateway of the project" pins the two warnings. - `src/core/project/boxNetworkWriters.test.ts`, "gatewayTargetsWriter for the gateways of the project": the writer adds, changes, and removes the target. "stages the inputs of each gateway that the agent calls in the @box/agentcore pack" pins the staged pack. - `src/core/project/runtimeProfile/rules/gateway.test.ts`, "the gateway rule for a gateway of the project": the `[mcp.]` server, no server with no gateway, and the stop for a server name that a gateway has. - `src/core/project/templates/boxProfile.test.ts`, "for a gateway of the project that the agent calls" (a test name): the two inputs, the agent variable, and the host and URL patterns. - `src/projectSchemas/project.test.ts`, "a passthrough target that names a gateway": the spec that it accepts and the five refusals. - `src/core/project/boxNetwork/projectGateways.test.ts`: the two target shapes. "the box on PATH" operates box 0.1.11-preview.10 on the Runtime profile and the pack that build makes, with the variables that the L3 sets. Box resolves the server to the host, the backend to the target, the agent variable to the URL, and adds its `net:connect` permit for the host. The test skips when no box is on `PATH`. - Without the change in `src/`, 35 of the 265 tests of these six files fail. Each of 19 mutations of `src/` fails one or more of these tests. - `bun test` with box 0.1.11-preview.10 on `PATH`: 5867 pass, 6 skip, 1 fail. The one failure is "the box on PATH > resolves a profile into the rules the tests fake" in `boxProfileResolver.test.ts`. It fails on `upstream/box-integration` too, with this box. CI has no box, so CI skips it. - `bun run typecheck`, `bun run lint:check`, and `bun run format:check` pass. - Live test in a test account in us-west-2: a new project from this branch and the L3 branch, with a second gateway `toolsgw` (`AWS_IAM`) and one Lambda target that gives a known answer. I added the gateway and the target with `agentcore add gateway` and `agentcore add gateway-target`. I did not change the box profile, the targets of the Box gateway, or IAM. One deploy made the target, the grant, and the variables. The agent used `echo___known_answer` and gave the known answer `gw2gw-known-answer-7319`. Box logged a permit for `mcp:call toolsgw/echo___known_answer`, the Box gateway sent the request to `egress-gateway-toolsgw`, and `toolsgw` logged the tool call and the known answer. The test project only had these changes: agent code that uses the gateway, `enableApplicationLogs` on `toolsgw`. I did `agentcore deploy` two more times for that agent code. `add gateway` gives `protocolType: "None"`, so `_URL` has no `/mcp`, and the agent code must add it, the same as without a box. - I did not do these: `bun run test:e2e`, `bun run audit`, `bun run secrets:check`, and `bun run build`. --- docs/box-local-testing.md | 18 +- src/core/project/boxMemory.ts | 2 +- src/core/project/boxNetwork/egress.ts | 17 ++ src/core/project/boxNetwork/network.test.ts | 193 +++++++++++++++++- src/core/project/boxNetwork/network.ts | 45 +++- .../boxNetwork/projectGateways.test.ts | 123 +++++++++++ .../project/boxNetwork/projectGateways.ts | 85 ++++++++ src/core/project/boxNetworkWriters.test.ts | 87 ++++++++ src/core/project/boxNetworkWriters.ts | 47 ++++- .../runtimeProfile/rules/gateway.test.ts | 54 +++++ .../project/runtimeProfile/rules/gateway.ts | 42 +++- src/core/project/runtimeProfile/types.ts | 5 + src/core/project/templates/boxProfile.test.ts | 52 +++++ src/core/project/templates/boxProfile.ts | 58 +++++- src/projectSchemas/gateway.ts | 10 +- src/projectSchemas/project.test.ts | 54 +++++ src/projectSchemas/project.ts | 23 +++ 17 files changed, 875 insertions(+), 40 deletions(-) create mode 100644 src/core/project/boxNetwork/projectGateways.test.ts create mode 100644 src/core/project/boxNetwork/projectGateways.ts diff --git a/docs/box-local-testing.md b/docs/box-local-testing.md index adf6f7c22..15f84c569 100644 --- a/docs/box-local-testing.md +++ b/docs/box-local-testing.md @@ -213,6 +213,14 @@ A profile that names a pack `box/` fails: box refuses it and names the `@b `mcp:call`. A host the gateway already has a target for keeps that target. Build owns only the targets whose name starts with `egress-`: it adds them, changes them, and removes one when no host needs it. It never changes another target. +- **The other gateways of the project.** A runtime without a box gets each gateway without + `boundRuntime` in `AGENTCORE_GATEWAY__URL`. For a box runtime, each of these gateways gets + the target `egress-gateway-` on `-box-egress`, with `passthrough.gateway` set to + the gateway's name. The L3 sets the target's endpoint to that gateway's URL, gives the Box + gateway's role `bedrock-agentcore:InvokeGateway` on that gateway only, and sets + `AGENTCORE_GATEWAY__URL` and `_HOST` on the runtime. A `PRIVATE_VPC` runtime gets none of + them. A `CUSTOM_JWT` gateway gets a warning and no target. You write nothing for them. A profile + entry that signs for a gateway host with `aws://` stops build. - **Outbound auth.** An `aws://` secret signs with the gateway's role, an `env://` secret sends an API key from AgentCore Identity, and an entry with no secret sends no credential. - **Failures.** A profile Box refuses stops build and deploy with box's own error. A wildcard @@ -241,7 +249,12 @@ A profile that names a pack `box/` fails: box refuses it and names the `@b the Runtime's Python, in every table: the agent, each stdio `[mcp.]` server, each `[tool.]`; - the `@box/agentcore` packs, the project name, and the build region come in, and each CloudWatch - target signs with the execution role. + target signs with the execution role; + - each other gateway of the project gets `[mcp.]`, to the host that `@box/agentcore` + reads from `AGENTCORE_GATEWAY__HOST`, through its `egress-gateway-` target. The agent + gets `AGENTCORE_GATEWAY__URL`, so the code that calls the gateway without a box works in + the box. Box permits each tool of the server, and a forbid rule of your policy still applies. + A server of your profile with the name of a gateway stops build. **The default log target.** With no `cloudwatch_logs` target, the Runtime profile gets `[telemetry.agentcore]`: box sends its deny, permit, and trace records to the log group of the @@ -270,7 +283,8 @@ A profile that names a pack `box/` fails: box refuses it and names the `@b - **No-auth targets need a newer L3.** A passthrough target with no outbound auth synthesizes only with an `@aws/agentcore-cdk` that accepts it. Until that release is pinned, use a - local L3 build, as in step 5. + local L3 build, as in step 5. A target with `passthrough.gateway` also needs an L3 that + accepts that field. ## 5. Point the generated CDK app at the local L3 tarball diff --git a/src/core/project/boxMemory.ts b/src/core/project/boxMemory.ts index ce970bbb9..461119b1b 100644 --- a/src/core/project/boxMemory.ts +++ b/src/core/project/boxMemory.ts @@ -242,7 +242,7 @@ function boxGatewayFor(spec: ProjectSpec, runtime: ProjectRuntime): AgentCoreGat */ function servesTarget(targets: readonly AgentCoreGatewayTarget[], wanted: AgentCoreGatewayTarget) { const endpoint = (target: AgentCoreGatewayTarget) => - target.passthrough && new URL(target.passthrough.endpoint).host; + target.passthrough?.endpoint && new URL(target.passthrough.endpoint).host; return targets.some( (target) => target.name === wanted.name || endpoint(target) === endpoint(wanted), ); diff --git a/src/core/project/boxNetwork/egress.ts b/src/core/project/boxNetwork/egress.ts index 3a9dcbd16..ad1cf2f48 100644 --- a/src/core/project/boxNetwork/egress.ts +++ b/src/core/project/boxNetwork/egress.ts @@ -132,6 +132,12 @@ const AWS_ENDPOINTS = [ api: "lambda-url", service: "lambda", }, + { + pattern: + /^[a-z0-9][a-z0-9-]*\.gateway\.bedrock-agentcore\.([a-z0-9-]+)\.amazonaws\.com(?:\.cn)?$/, + api: "gateway", + service: "bedrock-agentcore", + }, ] as const; /** The API of an AWS endpoint that the gateway signs for. */ @@ -191,6 +197,17 @@ export function outboundAuthFor( if (!secret) return { ok: true, auth: { kind: "none" } }; const [scheme, value = ""] = secret.ref.split("://", 2); if (scheme === "aws") { + if (awsEndpoint(host)?.api === "gateway") { + return { + ok: false, + code: "UNSIGNABLE_HOST", + reason: + `signs requests to ${host}, the host of an AgentCore gateway, with ${secret.ref}. ` + + "Build signs only for the gateways of this project, and it adds the route to each of " + + "them on AgentCore Runtime itself, as [mcp.], with the host that the " + + "deploy gives the gateway. Remove this entry. To call a gateway, add it to this project.", + }; + } const signing = signingService(host); if (!signing) { return { diff --git a/src/core/project/boxNetwork/network.test.ts b/src/core/project/boxNetwork/network.test.ts index 52d1f16d3..123fd55be 100644 --- a/src/core/project/boxNetwork/network.test.ts +++ b/src/core/project/boxNetwork/network.test.ts @@ -45,6 +45,9 @@ interface Options { readonly credentials?: ProjectSpec["credentials"]; readonly grantedActions?: string[]; readonly executionRoleArn?: string; + /** The other gateways of the project, after the Box gateway. */ + readonly gateways?: Record[]; + readonly runtime?: Partial; } /** The local box profile of runtime `agent`. */ @@ -56,10 +59,11 @@ const PROFILE = ".box/agent/local/profile.toml"; * sets `packs` on line 1, then each entry of `egress` and `mcp` on a line of its own. */ function model(policy: string, egress: Record = {}, options: Options = {}) { + const runtime = { ...RUNTIME, ...options.runtime } as ProjectRuntime; const spec = { name: "demo", projectType: "box", - runtimes: [RUNTIME], + runtimes: [runtime], memories: [], credentials: options.credentials ?? [], agentCoreGateways: [ @@ -68,6 +72,7 @@ function model(policy: string, egress: Record = {}, options: Op targets: options.targets ?? [], ...(options.executionRoleArn && { executionRoleArn: options.executionRoleArn }), }, + ...(options.gateways ?? []), ], } as unknown as ProjectSpec; const mcp = options.mcp ?? {}; @@ -89,7 +94,7 @@ function model(policy: string, egress: Record = {}, options: Op ); const network = buildBoxNetwork(parsed, failures, { spec, - runtime: RUNTIME, + runtime, gateway: "agent-box-egress", region: "us-west-2", targets: options.targets ?? [], @@ -1163,3 +1168,187 @@ describe("warnings", () => { }); }); }); + +describe("the gateways of the project", () => { + const TOOLS = { name: "tools", authorizerType: "AWS_IAM", targets: [] }; + const OPEN = { name: "open-tools", authorizerType: "NONE", targets: [] }; + const JWT = { name: "jwt-tools", authorizerType: "CUSTOM_JWT", targets: [] }; + const OTHER_BOX = { ...boxGatewaySpec("other"), targets: [] }; + + test("gives the agent each gateway without boundRuntime, with its target and its variables", () => { + const { network } = model("", {}, { gateways: [TOOLS, OPEN, OTHER_BOX] }); + + expect(network.projectGateways).toEqual([ + { + name: "tools", + target: "egress-gateway-tools", + variablePrefix: "AGENTCORE_GATEWAY_TOOLS", + auth: "iam", + }, + { + name: "open-tools", + target: "egress-gateway-open-tools", + variablePrefix: "AGENTCORE_GATEWAY_OPEN_TOOLS", + auth: "none", + }, + ]); + expect(network.failures).toEqual([]); + }); + + test("gives a PRIVATE_VPC runtime no gateway, as the CDK library binds none to it", () => { + const { network } = model( + "", + {}, + { gateways: [TOOLS], runtime: { containment: "PRIVATE_VPC" } }, + ); + + expect(network.projectGateways).toEqual([]); + }); + + test("warns for a CUSTOM_JWT gateway, and gives the agent no route to it", () => { + const { network } = model("", {}, { gateways: [JWT] }); + + expect(network.projectGateways).toEqual([]); + expect(network.warnings).toContain( + "The gateway 'jwt-tools' takes CUSTOM_JWT tokens, and the Box gateway of runtime 'agent' " + + "signs only with its IAM role, so the boxed agent cannot call 'jwt-tools' on AgentCore " + + "Runtime. Set its authorizerType to AWS_IAM to let the agent call it.", + ); + }); + + test("fails an entry whose target would take the name of a gateway's target", () => { + const r = model( + "", + { "gateway-tools": { destinations: ["x.example.com"] } }, + { gateways: [TOOLS] }, + ); + + expect(r.failures()).toEqual([["TARGET_NAME_COLLISION", "gateway-tools"]]); + expect(r.reasons()[0]).toContain("the target that build adds for the gateway 'tools'"); + }); + + test("keeps the target that build wrote for a gateway as build's own", () => { + const written = { + name: "egress-gateway-tools", + targetType: "passthrough", + passthrough: { gateway: "tools", protocolType: "CUSTOM" }, + outboundAuth: { type: "GATEWAY_IAM_ROLE", service: "bedrock-agentcore", region: "us-west-2" }, + } as AgentCoreGatewayTarget; + + expect(model("", {}, { gateways: [TOOLS], targets: [written] }).failures()).toEqual([]); + }); + + test("counts the gateways' targets toward the limit of 100", () => { + const egress = Object.fromEntries( + Array.from({ length: 100 }, (_, i) => [`h${i}`, { destinations: [`h${i}.example.com`] }]), + ); + const r = model("", egress, { gateways: [TOOLS] }); + + expect(r.reasons()).toEqual([ + "The gateway 'agent-box-egress' needs 101 targets, 100 for the hosts of the Box profile, 1 " + + "for the gateways of the project, and 0 of your own, and a gateway can have at most 100. " + + "Remove hosts from the profile, or targets from the gateway.", + ]); + }); + + test.each([ + [ + "an [egress] entry", + { tools: { destinations: [GATEWAY_HOST], secret: { ref: "aws://" } } }, + {}, + ], + [ + "an HTTP [mcp] server", + {}, + { mcp: { tools: { type: "http", destinations: [GATEWAY_HOST], secret: { ref: "aws://" } } } }, + ], + ])( + "refuses %s that signs for a gateway host, and names the route build adds", + (_, egress, options) => { + const r = model("", egress, { ...options, gateways: [TOOLS] }); + + expect(r.failures().map(([code]) => code)).toEqual(["UNSIGNABLE_HOST"]); + expect(r.reasons()[0]).toContain( + `signs requests to ${GATEWAY_HOST}, the host of an AgentCore gateway, with aws://. Build ` + + "signs only for the gateways of this project, and it adds the route to each of them on " + + "AgentCore Runtime itself, as [mcp.]", + ); + }, + ); +}); + +const GATEWAY_HOST = + "other-project-tools-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com"; + +describe("boxGatewayIamWarnings for a gateway of the project", () => { + test("gives no warning for a target that names a gateway, which the CDK library grants", () => { + const spec = { + name: "demo", + projectType: "box", + runtimes: [RUNTIME], + agentCoreGateways: [ + { + ...boxGatewaySpec("agent"), + targets: [ + { + name: "egress-gateway-tools", + targetType: "passthrough", + passthrough: { gateway: "tools", protocolType: "CUSTOM" }, + outboundAuth: { + type: "GATEWAY_IAM_ROLE", + service: "bedrock-agentcore", + region: "us-west-2", + }, + }, + ], + }, + { name: "tools", authorizerType: "AWS_IAM", targets: [] }, + ], + } as unknown as ProjectSpec; + + expect( + boxGatewayIamWarnings(spec, { + runtime: "agent", + gateway: "agent-box-egress", + grantedActions: [], + region: "us-west-2", + }), + ).toEqual([]); + }); + + test("warns for a target to a gateway host that the role has no InvokeGateway for", () => { + const spec = { + name: "demo", + projectType: "box", + runtimes: [RUNTIME], + agentCoreGateways: [ + { + ...boxGatewaySpec("agent"), + targets: [ + passthrough("mine", `https://${GATEWAY_HOST}`, { + outboundAuth: { + type: "GATEWAY_IAM_ROLE", + service: "bedrock-agentcore", + region: "us-west-2", + }, + }), + ], + additionalPolicies: ["agentcore/box-memory-policy.json"], + }, + ], + } as unknown as ProjectSpec; + const network = { runtime: "agent", gateway: "agent-box-egress", region: "us-west-2" }; + + expect(boxGatewayIamWarnings(spec, { ...network, grantedActions: [] })).toEqual([ + `Target 'mine' calls ${GATEWAY_HOST} with the gateway's role, which has no bedrock-agentcore ` + + "permissions for that host. Add an IAM policy file to additionalPolicies of the " + + "'agent-box-egress' gateway.", + ]); + expect( + boxGatewayIamWarnings(spec, { + ...network, + grantedActions: ["bedrock-agentcore:InvokeGateway"], + }), + ).toEqual([]); + }); +}); diff --git a/src/core/project/boxNetwork/network.ts b/src/core/project/boxNetwork/network.ts index 534d8ba54..bebaa8baf 100644 --- a/src/core/project/boxNetwork/network.ts +++ b/src/core/project/boxNetwork/network.ts @@ -28,6 +28,7 @@ import { deriveRuntimeProfile } from "../runtimeProfile/derive"; import { runtimeProfileHeader } from "../runtimeProfile/rules/additions"; import type { TomlTable } from "../runtimeProfile/types"; import { withDeployRegion, type CloudWatchTelemetry } from "./telemetry"; +import { projectGatewaysOf, type BoxProjectGateway } from "./projectGateways"; import { outboundAuthWords, sameOutboundAuth, targetOutboundAuth } from "./projectSpec"; import { MAX_GATEWAY_TARGETS, @@ -114,6 +115,11 @@ export interface BoxNetwork { readonly hosts: readonly BoxNetworkHost[]; /** The `env://` route of each target that sends an API key, for the credentials writer. */ readonly envRoutes: readonly BoxEnvRoute[]; + /** + * The gateways of the project that the agent calls through the Box gateway, each with its + * target; absent means none. + */ + readonly projectGateways?: readonly BoxProjectGateway[]; /** * The policy files, relative to the agent's local box folder, to copy beside the AgentCore * Runtime profile. @@ -192,7 +198,8 @@ export function buildBoxNetwork( return { ...rest, reason: `${where.subject} ${reason}`, place: where.place }; }; const failures: BoxNetworkFailure[] = [...parseFailures, ...map.failures.map(located)]; - const targets = hostTargets(map.hosts, project, located, parsed.profile.path); + const reached = projectGatewaysOf(project.spec, project.runtime); + const targets = hostTargets(map.hosts, project, reached.gateways, located, parsed.profile.path); failures.push(...targets.failures); const telemetry = parsed.profile.telemetry && @@ -207,6 +214,7 @@ export function buildBoxNetwork( region: project.region, gateway: { name: project.gateway, targets: project.targets }, hosts: targets.hosts, + projectGateways: reached.gateways, telemetry: telemetry?.telemetry ?? [], places: source.places, }); @@ -220,6 +228,7 @@ export function buildBoxNetwork( region: project.region, hosts: targets.hosts, envRoutes: envRoutesOf(targets.hosts), + projectGateways: reached.gateways, policyFiles: parsed.profile.policyFiles, ...(telemetry && { telemetry: telemetry.telemetry }), ...(derived && @@ -238,6 +247,7 @@ export function buildBoxNetwork( ); }), ...(telemetry?.warnings ?? []), + ...reached.warnings, ...(derived?.warnings ?? []), ], failures, @@ -267,7 +277,7 @@ export function isManagedTarget(target: Pick): b /** The host map key of a passthrough target's endpoint, or `undefined` for another target. */ function endpointKey(target: AgentCoreGatewayTarget): string | undefined { - const at = target.passthrough && parseEndpoint(target.passthrough.endpoint); + const at = target.passthrough?.endpoint && parseEndpoint(target.passthrough.endpoint); return at ? hostKey(at.host, at.port) : undefined; } @@ -316,6 +326,7 @@ function duplicateRule( function hostTargets( mapped: readonly MappedHost[], project: BoxNetworkProject, + gateways: readonly BoxProjectGateway[], located: (failure: ConversionFailure) => BoxNetworkFailure, profilePath: string, ): { hosts: BoxNetworkHost[]; failures: BoxNetworkFailure[] } { @@ -439,6 +450,9 @@ function hostTargets( for (const target of existing) { if (!isManagedTarget(target)) owners.set(target.name, `the gateway target '${target.name}'`); } + for (const gateway of gateways) { + owners.set(gateway.target, `the target that build adds for the gateway '${gateway.name}'`); + } const describeHost = (host: MappedHost) => host.entry ? `${entryLabel(host.entry)} for ${host.authority}` : `the host ${host.authority}`; for (const index of reused) owners.set(hosts[index]!.target!, describeHost(mapped[index]!)); @@ -463,13 +477,19 @@ function hostTargets( const served = hosts.filter((host) => host.target !== undefined).length; const kept = existing.filter((target) => !isManagedTarget(target) && !claimed.has(target.name)); - if (served + kept.length > MAX_GATEWAY_TARGETS) { + const needed = served + gateways.length + kept.length; + if (needed > MAX_GATEWAY_TARGETS) { + const builds = + gateways.length === 0 + ? `${served} for the hosts of the Box profile and` + : `${served} for the hosts of the Box profile, ${gateways.length} for the gateways of ` + + "the project, and"; failures.push({ code: "TOO_MANY_TARGETS", reason: - `The gateway '${project.gateway}' needs ${served + kept.length} targets, ${served} for ` + - `the hosts of the Box profile and ${kept.length} of your own, and a gateway can have at ` + - `most ${MAX_GATEWAY_TARGETS}. Remove hosts from the profile, or targets from the gateway.`, + `The gateway '${project.gateway}' needs ${needed} targets, ${builds} ${kept.length} of ` + + `your own, and a gateway can have at most ${MAX_GATEWAY_TARGETS}. Remove hosts from the ` + + "profile, or targets from the gateway.", place: profilePath, }); } @@ -503,7 +523,10 @@ function unmanagedShape(target: AgentCoreGatewayTarget): string | undefined { const { endpoint, protocolType, stickinessConfiguration } = target.passthrough; if (protocolType !== "CUSTOM") return `has protocolType ${protocolType}`; if (stickinessConfiguration) return "has a stickinessConfiguration"; - if (!/^https:\/\/[a-z0-9.-]+(:\d+)?$/.test(endpoint)) return `has the endpoint ${endpoint}`; + // A target that names a gateway of the project has no endpoint. + if (endpoint !== undefined && !/^https:\/\/[a-z0-9.-]+(:\d+)?$/.test(endpoint)) { + return `has the endpoint ${endpoint}`; + } const auth = target.outboundAuth; const fields = auth ? Object.keys(auth).sort().join(",") : ""; const shapes: Record = { @@ -529,7 +552,7 @@ function targetConflict( auth: BoxEgressAuth, profilePath: string, ): string | undefined { - const endpoint = target.passthrough && parseEndpoint(target.passthrough.endpoint); + const endpoint = target.passthrough?.endpoint && parseEndpoint(target.passthrough.endpoint); const named = `The gateway target '${target.name}' for ${host.authority}`; if (target.passthrough?.protocolType !== "CUSTOM") { return ( @@ -635,13 +658,17 @@ export function boxGatewayIamWarnings( ); case "lambda-url": return grants("lambda:InvokeFunctionUrl"); + case "gateway": + return grants("bedrock-agentcore:InvokeGateway"); } }; const warnings: string[] = []; for (const target of gateway.targets) { const auth = target.outboundAuth; if (auth?.type !== "GATEWAY_IAM_ROLE" || !auth.service) continue; - const at = target.passthrough && parseEndpoint(target.passthrough.endpoint); + // The CDK library grants the role InvokeGateway on the gateway that the target names. + if (target.passthrough?.gateway !== undefined) continue; + const at = target.passthrough?.endpoint && parseEndpoint(target.passthrough.endpoint); const endpoint = at && awsEndpoint(at.host); const host = at && hostKey(at.host, at.port); if (endpoint && host ? allows(endpoint.api, host) : holds(auth.service)) continue; diff --git a/src/core/project/boxNetwork/projectGateways.test.ts b/src/core/project/boxNetwork/projectGateways.test.ts new file mode 100644 index 000000000..e6c703dbf --- /dev/null +++ b/src/core/project/boxNetwork/projectGateways.test.ts @@ -0,0 +1,123 @@ +import { afterEach, describe, expect, test } from "bun:test"; +import { cp, mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { dirname, join } from "node:path"; +import { parse } from "smol-toml"; +import type { ProjectSpec } from "../../../projectSchemas/project"; +import { profileKeyPlaces, runtimeProfileContext } from "../runtimeProfile/context"; +import { apply } from "../runtimeProfile/rules/gateway"; +import { serializeRuntimeProfile } from "../runtimeProfile/serialize"; +import type { TomlTable } from "../runtimeProfile/types"; +import { AGENTCORE_PACK_PATH, renderAgentCorePack } from "../templates/boxProfile"; +import { projectGatewayTargetFor, type BoxProjectGateway } from "./projectGateways"; + +const TOOLS: BoxProjectGateway = { + name: "tools", + target: "egress-gateway-tools", + variablePrefix: "AGENTCORE_GATEWAY_TOOLS", + auth: "iam", +}; + +describe("projectGatewayTargetFor", () => { + test("names the gateway and signs for AgentCore in the build region, for an AWS_IAM gateway", () => { + expect(projectGatewayTargetFor(TOOLS, "us-west-2")).toEqual({ + name: "egress-gateway-tools", + targetType: "passthrough", + passthrough: { gateway: "tools", protocolType: "CUSTOM" }, + outboundAuth: { type: "GATEWAY_IAM_ROLE", service: "bedrock-agentcore", region: "us-west-2" }, + }); + }); + + test("sends no credential to a gateway that takes none", () => { + expect(projectGatewayTargetFor({ ...TOOLS, auth: "none" }, "us-west-2").outboundAuth).toBe( + undefined, + ); + }); +}); + +const directories: string[] = []; +afterEach(async () => { + await Promise.all(directories.splice(0).map((d) => rm(d, { recursive: true, force: true }))); +}); + +/** The box on PATH, when it has `box profile show --format json --full`. */ +const box = (() => { + const path = Bun.which("box"); + if (!path) return undefined; + const help = Bun.spawnSync([path, "profile", "show", "--help"], { stderr: "ignore" }).stdout; + return ["--format", "--full"].every((flag) => help.toString().includes(flag)) ? path : undefined; +})(); + +const HOST = "demo-default-tools-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com"; +const BOX_GATEWAY_URL = + "https://demo-default-agent-box-egress-klmnopqrst.gateway.bedrock-agentcore.us-west-2.amazonaws.com"; + +describe("the box on PATH", () => { + test.skipIf(box === undefined)( + "resolves the server and the agent variable of a gateway from the variables the CDK library sets (skipped without a box with --format json --full on PATH)", + async () => { + const root = await mkdtemp(join(tmpdir(), "box-project-gateway-")); + directories.push(root); + const resources = join(root, "resources"); + await cp(join(dirname(await realpath(box!)), "resources"), resources, { recursive: true }); + const spec = { name: "demo", memories: [] } as unknown as ProjectSpec; + const pack = join(root, AGENTCORE_PACK_PATH); + await mkdir(dirname(pack), { recursive: true }); + await writeFile(pack, renderAgentCorePack(spec, [TOOLS])); + const local = + 'packs = ["@box/base", "@box/agentcore"]\n\n[profile]\nname = "demo"\n\n' + + '[agent]\ncommand = ["/bin/sh"]\n'; + const context = runtimeProfileContext({ + spec, + runtime: { name: "agent", build: "Container" } as never, + profileFile: ".box/profile.toml", + region: "us-west-2", + gateway: { name: "agent-box-egress", targets: [] }, + hosts: [], + projectGateways: [TOOLS], + telemetry: [], + places: profileKeyPlaces(local, ".box/profile.toml"), + }); + const runtimeProfile = apply(parse(local) as TomlTable, context).table; + const project = join(root, "project"); + await mkdir(join(project, ".box"), { recursive: true }); + await writeFile( + join(project, ".box", "profile.toml"), + serializeRuntimeProfile(runtimeProfile), + ); + + const run = Bun.spawnSync( + [box!, "profile", "show", ".box/profile.toml", "--format", "json", "--full"], + { + cwd: project, + env: { + PATH: process.env.PATH, + HOME: process.env.HOME, + BOX_RESOURCES: resources, + AWS_REGION: "us-west-2", + AGENTCORE_GATEWAY_BOX_URL: BOX_GATEWAY_URL, + AGENTCORE_GATEWAY_TOOLS_URL: `https://${HOST}/mcp`, + AGENTCORE_GATEWAY_TOOLS_HOST: HOST, + }, + }, + ); + expect(run.stderr.toString()).toBe(""); + const shown = JSON.parse(run.stdout.toString()) as { + box_toml: { + agent: { env: Record }; + mcp: Record; + }; + policy: string; + }; + expect(shown.box_toml.mcp.tools!.destinations).toEqual([HOST]); + expect(shown.box_toml.mcp.tools!.backends.map(({ url }) => url)).toEqual([ + `${BOX_GATEWAY_URL}/egress-gateway-tools`, + ]); + expect(shown.box_toml.agent.env.AGENTCORE_GATEWAY_TOOLS_URL).toBe(`https://${HOST}/mcp`); + expect(shown.policy).toContain( + `permit (principal, action == Box::Action::"net:connect", resource) when { (context.input.host == "${HOST}" && context.input.port == 443) };`, + ); + }, + 120_000, + ); +}); diff --git a/src/core/project/boxNetwork/projectGateways.ts b/src/core/project/boxNetwork/projectGateways.ts new file mode 100644 index 000000000..0d8a479ff --- /dev/null +++ b/src/core/project/boxNetwork/projectGateways.ts @@ -0,0 +1,85 @@ +/** + * The gateways of the project that a boxed agent calls through its runtime's Box gateway. A runtime + * without a box gets each gateway without `boundRuntime` in `AGENTCORE_GATEWAY__URL`. On + * AgentCore Runtime, the boxed agent gets the same variable, and box sends each call to the + * gateway's host to a Box gateway target that names that gateway (`passthrough.gateway`). + */ +import type { AgentCoreGatewayTarget } from "../../../projectSchemas/gateway"; +import { gatewayDiscoveryPrefix, type ProjectSpec } from "../../../projectSchemas/project"; +import type { ProjectRuntime } from "../../../projectSchemas/runtime"; +import { targetNameFor } from "./egress"; + +/** A gateway of the project that a boxed runtime calls through its Box gateway. */ +export interface BoxProjectGateway { + /** The gateway's name in agentcore.json, and the name of its `[mcp]` server on the Runtime. */ + readonly name: string; + /** The target of the Box gateway that calls it. */ + readonly target: string; + /** The prefix of the variables the CDK library sets for it: `_URL` and `_HOST`. */ + readonly variablePrefix: string; + /** How the Box gateway authenticates to it: with its role for `AWS_IAM`, with nothing for `NONE`. */ + readonly auth: "iam" | "none"; +} + +/** The start of the name of each Box gateway target that calls a gateway of the project. */ +const PROJECT_GATEWAY_TARGET_PREFIX = "gateway-"; + +/** + * The gateways of `spec` that `runtime` calls through its Box gateway: each gateway without + * `boundRuntime`, as the CDK library binds it to a runtime without a box. A `PRIVATE_VPC` runtime + * gets none, and a `CUSTOM_JWT` gateway gets a warning, because the Box gateway cannot get its + * token. + */ +export function projectGatewaysOf( + spec: ProjectSpec, + runtime: Pick, +): { gateways: BoxProjectGateway[]; warnings: string[] } { + const gateways: BoxProjectGateway[] = []; + const warnings: string[] = []; + if (runtime.containment === "PRIVATE_VPC") return { gateways, warnings }; + for (const gateway of spec.agentCoreGateways) { + if (gateway.boundRuntime !== undefined) continue; + if (gateway.authorizerType === "CUSTOM_JWT") { + warnings.push( + `The gateway '${gateway.name}' takes CUSTOM_JWT tokens, and the Box gateway of runtime ` + + `'${runtime.name}' signs only with its IAM role, so the boxed agent cannot call ` + + `'${gateway.name}' on AgentCore Runtime. Set its authorizerType to AWS_IAM to let the ` + + "agent call it.", + ); + continue; + } + gateways.push({ + name: gateway.name, + target: targetNameFor(`${PROJECT_GATEWAY_TARGET_PREFIX}${gateway.name}`)!, + variablePrefix: gatewayDiscoveryPrefix(gateway), + auth: gateway.authorizerType === "AWS_IAM" ? "iam" : "none", + }); + } + return { gateways, warnings }; +} + +/** + * The Box gateway target that calls `gateway`, signed for AgentCore in `region` for an `AWS_IAM` + * gateway. The CDK library sets its endpoint and grants the Box gateway's role `InvokeGateway`. + */ +export function projectGatewayTargetFor( + gateway: BoxProjectGateway, + region: string, +): AgentCoreGatewayTarget { + return { + name: gateway.target, + targetType: "passthrough", + passthrough: { gateway: gateway.name, protocolType: "CUSTOM" }, + ...(gateway.auth === "iam" && { + outboundAuth: { type: "GATEWAY_IAM_ROLE", service: "bedrock-agentcore", region }, + }), + }; +} + +/** The `@box/agentcore` inputs that carry the URL and the host of `gateway` on the Runtime. */ +export function projectGatewayInputs(gateway: Pick): { + readonly url: string; + readonly host: string; +} { + return { url: `gateways.${gateway.name}.url`, host: `gateways.${gateway.name}.host` }; +} diff --git a/src/core/project/boxNetworkWriters.test.ts b/src/core/project/boxNetworkWriters.test.ts index d63c5a501..6d1f94bdd 100644 --- a/src/core/project/boxNetworkWriters.test.ts +++ b/src/core/project/boxNetworkWriters.test.ts @@ -238,6 +238,73 @@ describe("gatewayTargetsWriter", () => { }); }); +describe("gatewayTargetsWriter for the gateways of the project", () => { + const TOOLS = { + name: "tools", + target: "egress-gateway-tools", + variablePrefix: "AGENTCORE_GATEWAY_TOOLS", + auth: "iam", + } as const; + const OPEN = { + name: "open", + target: "egress-gateway-open", + variablePrefix: "AGENTCORE_GATEWAY_OPEN", + auth: "none", + } as const; + const toolsTarget: AgentCoreGatewayTarget = { + name: "egress-gateway-tools", + targetType: "passthrough", + passthrough: { gateway: "tools", protocolType: "CUSTOM" }, + outboundAuth: { type: "GATEWAY_IAM_ROLE", service: "bedrock-agentcore", region: "us-west-2" }, + }; + + test("adds a target that names each gateway, signed with the role only for an AWS_IAM gateway", () => { + const edits = run([gatewayTargetsWriter], [network({ projectGateways: [TOOLS, OPEN] })]); + + expect(edits.spec.agentCoreGateways[0]!.targets).toEqual([ + MINE, + toolsTarget, + { + name: "egress-gateway-open", + targetType: "passthrough", + passthrough: { gateway: "open", protocolType: "CUSTOM" }, + }, + ]); + expect(edits.messages).toEqual([ + "adding gateway target 'egress-gateway-tools' to 'agent-box-egress', for the boxed agent's calls to the gateway 'tools'", + "adding gateway target 'egress-gateway-open' to 'agent-box-egress', for the boxed agent's calls to the gateway 'open'", + ]); + }); + + test("rewrites the target for the build region in place, and changes nothing the next time", () => { + const stale = { + ...toolsTarget, + outboundAuth: { ...toolsTarget.outboundAuth!, region: "us-east-1" }, + }; + const edits = run( + [gatewayTargetsWriter], + [network({ projectGateways: [TOOLS] })], + spec([stale, MINE]), + ); + + expect(edits.spec.agentCoreGateways[0]!.targets).toEqual([toolsTarget, MINE]); + expect(edits.messages).toEqual([ + "updating gateway target 'egress-gateway-tools' of 'agent-box-egress' for the gateway 'tools'", + ]); + const again = run([gatewayTargetsWriter], [network({ projectGateways: [TOOLS] })], edits.spec); + expect(again.specChanged).toBe(false); + }); + + test("removes the target of a gateway that the agent no longer calls", () => { + const edits = run([gatewayTargetsWriter], [network()], spec([toolsTarget, MINE])); + + expect(targetNames(edits.spec)).toEqual(["mine"]); + expect(edits.messages).toEqual([ + "removing gateway target 'egress-gateway-tools' from 'agent-box-egress': the boxed agent no longer calls the gateway 'tools'", + ]); + }); +}); + describe("credentialsWriter", () => { test("declares each credential once and seeds its key from the box variable", () => { const envRoutes = [{ route: "github", variable: "GITHUB_TOKEN" }]; @@ -485,6 +552,26 @@ describe("runtimeProfileWriter", () => { ); }); + test("stages the inputs of each gateway that the agent calls in the @box/agentcore pack", () => { + const writer = runtimeProfileWriter([ + { runtime: "agent", dist: "app/agent/.box-dist", kind: "container" }, + ]); + const tools = { + name: "tools", + target: "egress-gateway-tools", + variablePrefix: "AGENTCORE_GATEWAY_TOOLS", + auth: "iam", + } as const; + + const { files } = run([writer], [network({ projectGateways: [tools] })]); + + const pack = files.find(({ path }) => path.endsWith(AGENTCORE_PACK_PATH)); + expect(pack && "text" in pack && pack.text).toContain( + "[inputs.gateways.tools.host]\ndescription = \"The deployed 'tools' gateway host.\"\n" + + 'from = "env:AGENTCORE_GATEWAY_TOOLS_HOST"\n', + ); + }); + test("stages only the @box/agentcore pack for a container", () => { const writer = runtimeProfileWriter([ { runtime: "agent", dist: "app/agent/.box-dist", kind: "container" }, diff --git a/src/core/project/boxNetworkWriters.ts b/src/core/project/boxNetworkWriters.ts index cd8b28324..f18a784c1 100644 --- a/src/core/project/boxNetworkWriters.ts +++ b/src/core/project/boxNetworkWriters.ts @@ -19,6 +19,7 @@ import { type BoxNetwork, type BoxNetworkHost, } from "./boxNetwork"; +import { projectGatewayTargetFor } from "./boxNetwork/projectGateways"; import { addBoxGatewayTargets, BOX_BEDROCK_POLICY_FILE, @@ -208,11 +209,11 @@ export const gatewayTargetsWriter: BoxNetworkWriter = { }; /** - * Sets the build-owned targets of the network's Box gateway: a managed target that a host takes is - * rewritten in place, every other managed target goes, a host whose managed target the gateway - * lacks gets one at the end, and every target build does not manage stays. A host whose target - * sends an API key credential that agentcore.json does not declare gets no target. Returns the - * step messages. + * Sets the build-owned targets of the network's Box gateway: a managed target that a host or a + * gateway of the project takes is rewritten in place, every other managed target goes, a host or a + * gateway whose managed target the gateway lacks gets one at the end, and every target build does + * not manage stays. A host whose target sends an API key credential that agentcore.json does not + * declare gets no target. Returns the step messages. */ function writeGatewayTargets(spec: ProjectSpec, network: BoxNetwork): string[] { const gateway = boxGatewayOf(spec, network.runtime); @@ -228,18 +229,35 @@ function writeGatewayTargets(spec: ProjectSpec, network: BoxNetwork): string[] { const messages: string[] = []; const targets: AgentCoreGatewayTarget[] = []; const gatewayName = `'${gateway.name}'`; + const reached = network.projectGateways ?? []; for (const target of existing) { if (!isManagedTarget(target)) { targets.push(target); continue; } + const called = reached.find((candidate) => candidate.target === target.name); + if (called) { + const written = projectGatewayTargetFor(called, network.region); + if (!isDeepStrictEqual(written, target)) { + messages.push( + `updating gateway target '${target.name}' of ${gatewayName} for the gateway ` + + `'${called.name}'`, + ); + } + targets.push(written); + continue; + } const host = sent.find((candidate) => candidate.target === target.name); if (!host) { if (unsent.some((candidate) => candidate.target === target.name)) continue; - const at = target.passthrough && parseEndpoint(target.passthrough.endpoint); + const named = target.passthrough?.gateway; + const at = target.passthrough?.endpoint && parseEndpoint(target.passthrough.endpoint); messages.push( - `removing gateway target '${target.name}' from ${gatewayName}: the Box profile no ` + - `longer allows ${at ? hostKey(at.host, at.port) : "its host"}`, + named !== undefined + ? `removing gateway target '${target.name}' from ${gatewayName}: the boxed agent no ` + + `longer calls the gateway '${named}'` + : `removing gateway target '${target.name}' from ${gatewayName}: the Box profile no ` + + `longer allows ${at ? hostKey(at.host, at.port) : "its host"}`, ); continue; } @@ -256,6 +274,14 @@ function writeGatewayTargets(spec: ProjectSpec, network: BoxNetwork): string[] { targets.push(gatewayTargetFor(host)); messages.push(`adding gateway target '${host.target}' to ${gatewayName} for ${host.authority}`); } + for (const called of reached) { + if (existing.some(({ name }) => name === called.target)) continue; + targets.push(projectGatewayTargetFor(called, network.region)); + messages.push( + `adding gateway target '${called.target}' to ${gatewayName}, for the boxed agent's calls ` + + `to the gateway '${called.name}'`, + ); + } for (const host of unsent) { const auth = undeclaredKey(spec, host)!; const removed = existing.some(({ name }) => name === host.target); @@ -404,7 +430,10 @@ export function runtimeProfileWriter(staged: readonly StagedRuntime[]): BoxNetwo const network = networkOf(networks, runtime); return [ { path: `${dist}/profile.toml`, text: runtimeProfileText(runtime, network, spec) }, - { path: `${dist}/${AGENTCORE_PACK_PATH}`, text: renderAgentCorePack(spec) }, + { + path: `${dist}/${AGENTCORE_PACK_PATH}`, + text: renderAgentCorePack(spec, network?.projectGateways), + }, ...(kind === "codezip" ? [ { diff --git a/src/core/project/runtimeProfile/rules/gateway.test.ts b/src/core/project/runtimeProfile/rules/gateway.test.ts index 585b2e30d..77f07d137 100644 --- a/src/core/project/runtimeProfile/rules/gateway.test.ts +++ b/src/core/project/runtimeProfile/rules/gateway.test.ts @@ -707,3 +707,57 @@ describe("the gateway rule and the Runtime renderer it replaced", () => { expect(old.mcp).toBeUndefined(); }); }); + +describe("the gateway rule for a gateway of the project", () => { + const TOOLS = { + name: "tools", + target: "egress-gateway-tools", + variablePrefix: "AGENTCORE_GATEWAY_TOOLS", + auth: "iam", + } as const; + const PROFILE_TEXT = 'packs = ["@box/base"]\n\n[profile]\nname = "demo"\n'; + const withGateways = (text: string) => + apply(parse(text) as TomlTable, { ...contextOf(text, []), projectGateways: [TOOLS] }); + + test("adds an HTTP server under the gateway's name, to its host on the Runtime, through its target", () => { + const result = withGateways(PROFILE_TEXT); + + expect(result.problems).toEqual([]); + expect(serializeRuntimeProfile({ mcp: result.table.mcp as TomlTable })).toBe( + "[mcp.tools]\n" + + 'type = "http"\n' + + 'destinations = [ "${{ inputs.gateways.tools.host }}" ]\n\n' + + "[[mcp.tools.backends]]\n" + + 'url = "${{ inputs.gateway.url }}/egress-gateway-tools"\n\n' + + "[mcp.tools.backends.auth]\n" + + 'ref = "aws://"\n\n' + + "[mcp.tools.backends.auth.aws]\n" + + 'service = "bedrock-agentcore"\n' + + 'region = "${{ inputs.aws.region }}"\n\n', + ); + }); + + test("adds no server to the local profile's own tables when the project has no gateway", () => { + const result = apply(parse(PROFILE_TEXT) as TomlTable, contextOf(PROFILE_TEXT, [])); + + expect(result.table.mcp).toBeUndefined(); + }); + + test("stops for a server of the local profile with the gateway's name", () => { + const text = `${PROFILE_TEXT}\n[mcp.tools]\ncommand = ["/usr/bin/tools"]\n`; + + const result = withGateways(text); + + expect(result.problems).toEqual([ + { + code: "RUNTIME_GATEWAY_SERVER_NAME_TAKEN", + key: ["mcp", "tools"], + reason: + "[mcp.tools] has the name of the gateway 'tools' of this project. On AgentCore " + + "Runtime, build adds the server [mcp.tools] so the agent can call that gateway. Rename " + + "your server.", + place: `${PROFILE}:6:1`, + }, + ]); + }); +}); diff --git a/src/core/project/runtimeProfile/rules/gateway.ts b/src/core/project/runtimeProfile/rules/gateway.ts index 321e267b6..56778f9d3 100644 --- a/src/core/project/runtimeProfile/rules/gateway.ts +++ b/src/core/project/runtimeProfile/rules/gateway.ts @@ -13,6 +13,7 @@ * | a target that no entry of the profile names | `[egress.]`, or the `[mcp]` server it serves | * | an entry whose hosts the policy denies | removed; the Box network model warns for it | * | an entry with no host in the Box network model | removed; the model fails the entry, and build stops | + * | a gateway of the project that the agent calls (projectGatewaysOf) | `[mcp.]` to the host in `_HOST`, a backend to its target | * * A stdio `[mcp.]` stays as it is: the `refusals` and `paths` rules own it. */ @@ -20,6 +21,7 @@ import { InputValidationError } from "../../../../errors/errors"; import type { AgentCoreGatewayTarget } from "../../../../projectSchemas/gateway"; import type { BoxHostSource, BoxNetworkHost } from "../../boxNetwork"; import { BOX_EGRESS_TARGET_PREFIX } from "../../boxNetwork/egress"; +import { projectGatewayInputs, type BoxProjectGateway } from "../../boxNetwork/projectGateways"; import { gatewayTargetFor } from "../../boxNetwork/projectSpec"; import { isHttpServer, isTable } from "../projectPaths"; import { @@ -27,6 +29,7 @@ import { RUNTIME_INPUTS, type RuleResult, type RuntimeProfileContext, + type RuntimeProfileProblem, type TomlTable, } from "../types"; @@ -81,12 +84,42 @@ export function apply(table: Readonly, context: RuntimeProfileContext } } + const problems: RuntimeProfileProblem[] = []; + for (const gateway of context.projectGateways ?? []) { + if (gateway.name in mcp) { + problems.push({ + code: "RUNTIME_GATEWAY_SERVER_NAME_TAKEN", + key: ["mcp", gateway.name], + reason: + `[mcp.${gateway.name}] has the name of the gateway '${gateway.name}' of this project. ` + + `On AgentCore Runtime, build adds the server [mcp.${gateway.name}] so the agent can ` + + "call that gateway. Rename your server.", + place: context.placeOf(["mcp", gateway.name]), + }); + continue; + } + mcp[gateway.name] = projectGatewayServer(gateway); + } + // Each table keeps its place when the profile has it, and comes last when it does not. An empty // table goes. const result: TomlTable = { ...table, egress, mcp }; if (Object.keys(egress).length === 0) delete result.egress; if (Object.keys(mcp).length === 0) delete result.mcp; - return { table: result, problems: [], warnings: [] }; + return { table: result, problems, warnings: [] }; +} + +/** + * The HTTP `[mcp.]` server for a gateway of the project: the host the CDK library sets in + * `_HOST`, through the Box gateway target that calls the gateway. Box permits each tool of + * the server, and a forbid rule of the policy still applies. + */ +function projectGatewayServer(gateway: BoxProjectGateway): TomlTable { + return { + type: "http", + destinations: [`\${{ inputs.${projectGatewayInputs(gateway).host} }}`], + backends: [gatewayBackend({ target: gateway.target })], + }; } /** @@ -115,10 +148,11 @@ function gatewayRoutes(context: RuntimeProfileContext): GatewayRoute[] { if (!targets.some(({ name }) => name === host.target)) targets.push(gatewayTargetFor(host)); } + // A target that names a gateway of the project has no host here: that gateway's server does. const passthrough = targets.filter( - (target) => target.targetType === "passthrough" && target.passthrough, + (target) => target.targetType === "passthrough" && target.passthrough?.endpoint !== undefined, ); - const hostOf = (target: AgentCoreGatewayTarget) => new URL(target.passthrough!.endpoint).host; + const hostOf = (target: AgentCoreGatewayTarget) => new URL(target.passthrough!.endpoint!).host; const byHost = new Map(); for (const target of passthrough) { const other = byHost.get(hostOf(target)); @@ -226,7 +260,7 @@ function mcpServer(entry: Readonly, route: GatewayRoute, server: McpS * The backend of a route: the route's gateway target, signed for the gateway in the Runtime's own * region, which box reads from the `aws.region` input of the agentcore pack. */ -function gatewayBackend(route: GatewayRoute): TomlTable { +function gatewayBackend(route: Pick): TomlTable { return { url: `${RUNTIME_INPUTS.gatewayUrl}/${route.target}`, auth: { diff --git a/src/core/project/runtimeProfile/types.ts b/src/core/project/runtimeProfile/types.ts index 628d1520f..5cf56be9d 100644 --- a/src/core/project/runtimeProfile/types.ts +++ b/src/core/project/runtimeProfile/types.ts @@ -7,6 +7,7 @@ import type { AgentCoreGatewayTarget } from "../../../projectSchemas/gateway"; import type { ProjectSpec } from "../../../projectSchemas/project"; import type { ProjectRuntime } from "../../../projectSchemas/runtime"; import type { BoxNetworkHost, CloudWatchTelemetry } from "../boxNetwork"; +import type { BoxProjectGateway } from "../boxNetwork/projectGateways"; /** A TOML table as smol-toml parses it: a key holds a string, a number, a boolean, a list, or a table. */ export type TomlTable = Record; @@ -66,6 +67,8 @@ export interface RuntimeProfileContext { readonly gateway: { readonly name: string; readonly targets: readonly AgentCoreGatewayTarget[] }; /** The hosts of the Box network model, each with the gateway target it gets. */ readonly hosts: readonly BoxNetworkHost[]; + /** The gateways of the project that the agent calls through the Box gateway; absent means none. */ + readonly projectGateways?: readonly BoxProjectGateway[]; /** The CloudWatch targets of the local profile, with the deploy region set. */ readonly telemetry: readonly CloudWatchTelemetry[]; readonly paths: RuntimePaths; @@ -92,6 +95,8 @@ export const RUNTIME_PROFILE_PROBLEM_CODES = [ "RUNTIME_TELEMETRY_NOT_CLOUDWATCH", /** A CloudWatch telemetry target that box refuses when a run starts. */ "RUNTIME_TELEMETRY_REFUSED", + /** An `[mcp]` server with the name of a gateway of the project, which build adds on the Runtime. */ + "RUNTIME_GATEWAY_SERVER_NAME_TAKEN", ] as const; export type RuntimeProfileProblemCode = (typeof RUNTIME_PROFILE_PROBLEM_CODES)[number]; diff --git a/src/core/project/templates/boxProfile.test.ts b/src/core/project/templates/boxProfile.test.ts index b4f65b42a..3d29656dd 100644 --- a/src/core/project/templates/boxProfile.test.ts +++ b/src/core/project/templates/boxProfile.test.ts @@ -407,6 +407,58 @@ describe("renderAgentCorePack", () => { ) as Record; } + describe("for a gateway of the project that the agent calls", () => { + const TOOLS = { + name: "tools", + target: "egress-gateway-tools", + variablePrefix: "AGENTCORE_GATEWAY_TOOLS", + auth: "iam", + } as const; + const withTools = (memories: { name: string }[] = []) => + parse( + renderAgentCorePack({ name: "V3Demo", memories } as unknown as ProjectSpec, [TOOLS]), + ) as Record; + const HOST = + "v3demo-default-tools-abcdefghij.gateway.bedrock-agentcore.us-west-2.amazonaws.com"; + + test("reads its host and its URL from the variables the CDK library sets for it", () => { + const { inputs } = withTools(); + expect(inputs.gateways.tools.host.from).toBe("env:AGENTCORE_GATEWAY_TOOLS_HOST"); + expect(inputs.gateways.tools.url.from).toBe("env:AGENTCORE_GATEWAY_TOOLS_URL"); + }); + + test("gives the agent the URL under the name a runtime without a box reads, beside the memory IDs", () => { + expect(withTools([{ name: "notes" }]).agent.env).toEqual({ + MEMORY_NOTES_ID: "${{ inputs.memory.notes.id }}", + AGENTCORE_GATEWAY_TOOLS_URL: "${{ inputs.gateways.tools.url }}", + }); + }); + + test.each([ + [HOST, true], + [`https://${HOST}`, false], + [`${HOST}/mcp`, false], + ["evil.example.com", false], + ["x.gateway.bedrock-agentcore.us-west-2.amazonaws.com.evil.example.com", false], + ])("the host pattern takes %s: %p", (host, matches) => { + expect(new RegExp(`^${withTools().inputs.gateways.tools.host.pattern}$`).test(host)).toBe( + matches, + ); + }); + + test.each([ + [`https://${HOST}/mcp`, true], + [`https://${HOST}`, true], + [`http://${HOST}/mcp`, false], + [`https://${HOST}/mcp/x`, false], + ["https://evil.example.com/mcp", false], + ])("the URL pattern takes %s: %p", (url, matches) => { + expect(new RegExp(`^${withTools().inputs.gateways.tools.url.pattern}$`).test(url)).toBe( + matches, + ); + }); + }); + test("names itself @box/agentcore and ships as a support pack", () => { const toml = pack([]); expect(toml.pack).toEqual({ name: "@box/agentcore", version: 1, kind: "support" }); diff --git a/src/core/project/templates/boxProfile.ts b/src/core/project/templates/boxProfile.ts index 231f59ed8..ac4d196f9 100644 --- a/src/core/project/templates/boxProfile.ts +++ b/src/core/project/templates/boxProfile.ts @@ -11,6 +11,7 @@ import { DEFAULT_MODEL_IDS, type ProjectRuntime } from "../../../projectSchemas/ import { DEV_PORTS } from "../../dev/port"; import { PYTHON_ENV } from "../../dev/codezip"; import { modelProviderCredentialName } from "./runtime"; +import { projectGatewayInputs, type BoxProjectGateway } from "../boxNetwork/projectGateways"; /** Where a box template's venv gets its uv-managed Python, relative to the home folder. */ const UV_PYTHON_HOME_DIR = ".local/share/uv/python"; @@ -73,6 +74,15 @@ export const AGENTCORE_CODEZIP_PACK_PATH = "resources/packs/agentcore-codezip/pa const GATEWAY_URL_PATTERN = "https://[a-z0-9][-a-z0-9.]*[.]amazonaws[.]com(/[A-Za-z0-9_-][A-Za-z0-9_.-]*)*"; +/** + * The host of a gateway of the project, which the CDK library sets in `_HOST`, and that + * gateway's URL in `_URL`, with `/mcp` for an MCP gateway. Each input that reaches a route's + * destinations needs a pattern. + */ +const PROJECT_GATEWAY_HOST_PATTERN = + "[a-z0-9][-a-z0-9]*[.]gateway[.]bedrock-agentcore[.][a-z0-9-]+[.]amazonaws[.]com"; +const PROJECT_GATEWAY_URL_PATTERN = `https://${PROJECT_GATEWAY_HOST_PATTERN}(/mcp)?`; + /** As @box/bedrock bounds `bedrock.region`. */ const AWS_REGION_PATTERN = "[a-z]{2}(-[a-z]+)?-(central|north|south|east|west)+-[0-9]+"; @@ -612,10 +622,16 @@ export function boxProfileWarnings(runtime: ScaffoldRuntimeInput): string[] { * egress backend `url`, bounded by a pattern so a value from the environment names only the host the * profile expects. The `runtime.log_group` and `runtime.log_stream` inputs each read one key of * {@link RUNTIME_LOGS_HEADERS_ENV}, for the default telemetry target of the Runtime profile. One - * input per project memory carries its ID into the agent's environment. box finds the pack beside - * its binary at {@link AGENTCORE_PACK_PATH}; build and deploy stage it there. + * input per project memory carries its ID into the agent's environment. Each gateway of the project + * that the agent calls through the Box gateway gets two inputs: its host, for the destination of + * its `[mcp]` server, and its URL, which the agent gets under the variable name that a runtime + * without a box reads. box finds the pack beside its binary at {@link AGENTCORE_PACK_PATH}; build + * and deploy stage it there. */ -export function renderAgentCorePack(spec: ProjectSpec): string { +export function renderAgentCorePack( + spec: ProjectSpec, + gateways: readonly BoxProjectGateway[] = [], +): string { const memories = spec.memories ?? []; const memoryInputs = memories .map( @@ -625,13 +641,33 @@ description = ${str(`The deployed '${memory.name}' Memory ID.`)} from = ${str(`env:${memoryEnvVarName(memory.name)}`)}`, ) .join(""); - const memoryEnv = memories - .map( - (memory) => - `${memoryEnvVarName(memory.name)} = ${str(`\${{ inputs.memory.${tomlKey(memory.name)}.id }}`)}`, - ) - .join("\n"); - const agentEnv = memoryEnv ? `\n[agent.env]\n${memoryEnv}\n` : ""; + const memoryEnv = memories.map( + (memory) => + `${memoryEnvVarName(memory.name)} = ${str(`\${{ inputs.memory.${tomlKey(memory.name)}.id }}`)}`, + ); + const gatewayInputs = gateways + .map((gateway) => { + const inputs = projectGatewayInputs(gateway); + return ` + +# The '${gateway.name}' gateway of the project, which the agent calls through the Box gateway. +[inputs.${inputs.url}] +description = ${str(`The deployed '${gateway.name}' gateway URL.`)} +from = ${str(`env:${gateway.variablePrefix}_URL`)} +pattern = ${str(PROJECT_GATEWAY_URL_PATTERN)} + +[inputs.${inputs.host}] +description = ${str(`The deployed '${gateway.name}' gateway host.`)} +from = ${str(`env:${gateway.variablePrefix}_HOST`)} +pattern = ${str(PROJECT_GATEWAY_HOST_PATTERN)}`; + }) + .join(""); + const gatewayEnv = gateways.map( + (gateway) => + `${gateway.variablePrefix}_URL = ${str(`\${{ inputs.${projectGatewayInputs(gateway).url} }}`)}`, + ); + const env = [...memoryEnv, ...gatewayEnv].join("\n"); + const agentEnv = env ? `\n[agent.env]\n${env}\n` : ""; return `# The deployed AgentCore resources of '${spec.name}', read from the environment the Runtime sets. # Written by agentcore build and deploy. The runtime profile imports it as ${AGENTCORE_PACK_NAME}. [pack] @@ -669,7 +705,7 @@ key = "x-aws-log-stream" [inputs.runtime.url] description = "The URL an A2A agent card advertises on the Runtime." from = "env:AGENTCORE_RUNTIME_URL" -default = "http://localhost:9000/"${memoryInputs} +default = "http://localhost:9000/"${memoryInputs}${gatewayInputs} ${agentEnv}`; } diff --git a/src/projectSchemas/gateway.ts b/src/projectSchemas/gateway.ts index b456a9c3d..dcac12828 100644 --- a/src/projectSchemas/gateway.ts +++ b/src/projectSchemas/gateway.ts @@ -278,11 +278,17 @@ export const PassthroughConfigSchema = z endpoint: z .string() .min(1) - .regex(/^https:\/\/[a-zA-Z0-9\-.]+(:[0-9]{1,5})?(\/.*)?$/, "Must be a valid HTTPS URL"), + .regex(/^https:\/\/[a-zA-Z0-9\-.]+(:[0-9]{1,5})?(\/.*)?$/, "Must be a valid HTTPS URL") + .optional(), + /** A gateway of this project, in place of `endpoint`: the CDK library calls its URL. */ + gateway: GatewayNameSchema.optional(), protocolType: PassthroughProtocolTypeSchema.default("CUSTOM"), stickinessConfiguration: StickinessConfigSchema.optional(), }) - .strict(); + .strict() + .refine((config) => (config.endpoint === undefined) !== (config.gateway === undefined), { + message: "A passthrough configuration needs exactly one of endpoint and gateway.", + }); export type PassthroughConfig = z.infer; const TARGET_CONFIGURATION_FIELDS = [ "toolDefinitions", diff --git a/src/projectSchemas/project.test.ts b/src/projectSchemas/project.test.ts index d643bb33d..d57f041f3 100644 --- a/src/projectSchemas/project.test.ts +++ b/src/projectSchemas/project.test.ts @@ -555,6 +555,60 @@ describe("gateway boundRuntime and discoveryPrefix", () => { }); }); +describe("a passthrough target that names a gateway", () => { + const target = (passthrough: Record) => ({ + name: "egress-gateway-tools", + targetType: "passthrough", + passthrough: { protocolType: "CUSTOM", ...passthrough }, + outboundAuth: { type: "GATEWAY_IAM_ROLE", service: "bedrock-agentcore", region: "us-west-2" }, + }); + const messages = (gateways: unknown[]) => { + const result = ProjectSpecSchema.safeParse({ + ...minimalProject, + runtimes: [runtime], + agentCoreGateways: gateways, + }); + return result.success ? [] : result.error.issues.map(({ message }) => message); + }; + const front = (passthrough: Record, fields: Record = {}) => ({ + name: "front", + authorizerType: "AWS_IAM", + protocolType: "None", + targets: [target(passthrough)], + ...fields, + }); + const TOOLS = { name: "tools", authorizerType: "AWS_IAM", targets: [] }; + + test("accepts a gateway of the project without boundRuntime", () => { + expect(messages([front({ gateway: "tools" }), TOOLS])).toEqual([]); + }); + + test.each([ + [ + "no gateway of that name", + [front({ gateway: "gone" })], + 'names the gateway "gone" in passthrough.gateway, but the project has no gateway of that name', + ], + ["its own gateway", [front({ gateway: "front" })], "which is its own gateway"], + [ + "a gateway bound to a runtime", + [front({ gateway: "tools" }), { ...TOOLS, boundRuntime: "agent" }], + 'which is bound to the runtime "agent"', + ], + ])("refuses %s", (_, gateways, message) => { + expect(messages(gateways)).toContainEqual(expect.stringContaining(message)); + }); + + test.each([ + ["both endpoint and gateway", { endpoint: "https://api.example.com", gateway: "tools" }], + ["neither endpoint nor gateway", {}], + ])("refuses %s", (_, passthrough) => { + expect(messages([front(passthrough), TOOLS])).toContain( + "A passthrough configuration needs exactly one of endpoint and gateway.", + ); + }); +}); + describe("Box project gateways", () => { const runtimeNamed = (name: string) => ({ ...runtime, name, codeLocation: `./${name}` }); const parse = (runtimes: string[], gateways: unknown[]) => diff --git a/src/projectSchemas/project.ts b/src/projectSchemas/project.ts index d0c472422..a99d5691a 100644 --- a/src/projectSchemas/project.ts +++ b/src/projectSchemas/project.ts @@ -161,6 +161,29 @@ export const ProjectSpecSchema = z }); } } + // A passthrough target that names a gateway calls a gateway of this project. A gateway bound to + // a runtime belongs to that runtime, so no target of another gateway calls it. + for (const gateway of spec.agentCoreGateways) { + for (const target of gateway.targets) { + const reached = target.passthrough?.gateway; + if (reached === undefined) continue; + const named = spec.agentCoreGateways.find((other) => other.name === reached); + const problem = + named === undefined + ? "but the project has no gateway of that name" + : named === gateway + ? "which is its own gateway" + : named.boundRuntime !== undefined + ? `which is bound to the runtime "${named.boundRuntime}"` + : undefined; + if (problem === undefined) continue; + ctx.addIssue({ + code: "custom", + message: `Target "${target.name}" of gateway "${gateway.name}" names the gateway "${reached}" in passthrough.gateway, ${problem}. Name a gateway of this project without boundRuntime`, + path: ["agentCoreGateways"], + }); + } + } // A Box project keeps one Box gateway for each runtime. Without it, a deploy would delete the // deployed gateway, so every command stops here and prints the entry to add back. if (isBoxProject(spec)) { From 7c9536d1e4fd7f21595bd02b826451f9e6aedd98 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 16:43:06 -0800 Subject: [PATCH 02/15] fix(box): Accept a China host in the gateway host and URL inputs Review feedback: the `_HOST` and `_URL` patterns of `@box/agentcore` stopped at `amazonaws.com`, and the gateway host of `AWS_ENDPOINTS` also accepts `amazonaws.com.cn`. Thus box refused the two inputs in a China region. Each pattern now accepts `amazonaws.com.cn`. Test: "the host pattern takes ... amazonaws.com.cn: true" and "the URL pattern takes https://....amazonaws.com.cn/mcp: true" in `boxProfile.test.ts` fail before this change. --- src/core/project/templates/boxProfile.test.ts | 6 ++++++ src/core/project/templates/boxProfile.ts | 6 +++--- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/src/core/project/templates/boxProfile.test.ts b/src/core/project/templates/boxProfile.test.ts index 114cc3292..b12719225 100644 --- a/src/core/project/templates/boxProfile.test.ts +++ b/src/core/project/templates/boxProfile.test.ts @@ -434,8 +434,13 @@ describe("renderAgentCorePack", () => { }); }); + const CHINA_HOST = + "v3demo-default-tools-abcdefghij.gateway.bedrock-agentcore.cn-north-1.amazonaws.com.cn"; + test.each([ [HOST, true], + [CHINA_HOST, true], + [`${HOST}.cn.evil.example.com`, false], [`https://${HOST}`, false], [`${HOST}/mcp`, false], ["evil.example.com", false], @@ -449,6 +454,7 @@ describe("renderAgentCorePack", () => { test.each([ [`https://${HOST}/mcp`, true], [`https://${HOST}`, true], + [`https://${CHINA_HOST}/mcp`, true], [`http://${HOST}/mcp`, false], [`https://${HOST}/mcp/x`, false], ["https://evil.example.com/mcp", false], diff --git a/src/core/project/templates/boxProfile.ts b/src/core/project/templates/boxProfile.ts index 6f828117b..0d972f82e 100644 --- a/src/core/project/templates/boxProfile.ts +++ b/src/core/project/templates/boxProfile.ts @@ -76,11 +76,11 @@ const GATEWAY_URL_PATTERN = /** * The host of a gateway of the project, which the CDK library sets in `_HOST`, and that - * gateway's URL in `_URL`, with `/mcp` for an MCP gateway. Each input that reaches a route's - * destinations needs a pattern. + * gateway's URL in `_URL`, with `/mcp` for an MCP gateway, in the `aws` and `aws-cn` + * partitions. Each input that reaches a route's destinations needs a pattern. */ const PROJECT_GATEWAY_HOST_PATTERN = - "[a-z0-9][-a-z0-9]*[.]gateway[.]bedrock-agentcore[.][a-z0-9-]+[.]amazonaws[.]com"; + "[a-z0-9][-a-z0-9]*[.]gateway[.]bedrock-agentcore[.][a-z0-9-]+[.]amazonaws[.]com([.]cn)?"; const PROJECT_GATEWAY_URL_PATTERN = `https://${PROJECT_GATEWAY_HOST_PATTERN}(/mcp)?`; /** As @box/bedrock bounds `bedrock.region`. */ From 36d4d4a033899a3c26a99b63e4b46f50fa729f13 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 16:43:57 -0800 Subject: [PATCH 03/15] test(box): Resolve a gateway name with "-" and upper case with the box on PATH Review question: a gateway name can hold "-" and upper case, so the Runtime profile has `${{ inputs.gateways.My-Tools-GW.host }}` and `[mcp.My-Tools-GW]`. The test "the box on PATH" now also uses the gateway `My-Tools-GW`. box 0.1.11-preview.10 resolves the input, the server, the backend, the agent variable, and the permit `context.input.server == "My-Tools-GW"`. No code changes, because box accepts these names. This test does not fail before this commit. It pins the behaviour, and it skips when no box is on PATH. --- .../boxNetwork/projectGateways.test.ts | 35 +++++++++++++------ 1 file changed, 24 insertions(+), 11 deletions(-) diff --git a/src/core/project/boxNetwork/projectGateways.test.ts b/src/core/project/boxNetwork/projectGateways.test.ts index e6c703dbf..f13b0ac69 100644 --- a/src/core/project/boxNetwork/projectGateways.test.ts +++ b/src/core/project/boxNetwork/projectGateways.test.ts @@ -52,10 +52,21 @@ const HOST = "demo-default-tools-abcdefghij.gateway.bedrock-agentcore.us-west-2. const BOX_GATEWAY_URL = "https://demo-default-agent-box-egress-klmnopqrst.gateway.bedrock-agentcore.us-west-2.amazonaws.com"; +/** A gateway named `name`, with the variable prefix and the target that build gives it. */ +const gatewayNamed = (name: string, prefix: string): BoxProjectGateway => ({ + name, + target: `egress-gateway-${name}`, + variablePrefix: prefix, + auth: "iam", +}); + describe("the box on PATH", () => { - test.skipIf(box === undefined)( - "resolves the server and the agent variable of a gateway from the variables the CDK library sets (skipped without a box with --format json --full on PATH)", - async () => { + // A gateway name can hold "-" and upper case, which reach an input name and a server name. + test + .skipIf(box === undefined) + .each([[TOOLS], [gatewayNamed("My-Tools-GW", "AGENTCORE_GATEWAY_MY_TOOLS_GW")]])( + "resolves the server and the agent variable of the gateway %o from the variables the CDK library sets (skipped without a box with --format json --full on PATH)", + async (gateway) => { const root = await mkdtemp(join(tmpdir(), "box-project-gateway-")); directories.push(root); const resources = join(root, "resources"); @@ -63,7 +74,7 @@ describe("the box on PATH", () => { const spec = { name: "demo", memories: [] } as unknown as ProjectSpec; const pack = join(root, AGENTCORE_PACK_PATH); await mkdir(dirname(pack), { recursive: true }); - await writeFile(pack, renderAgentCorePack(spec, [TOOLS])); + await writeFile(pack, renderAgentCorePack(spec, [gateway])); const local = 'packs = ["@box/base", "@box/agentcore"]\n\n[profile]\nname = "demo"\n\n' + '[agent]\ncommand = ["/bin/sh"]\n'; @@ -74,7 +85,7 @@ describe("the box on PATH", () => { region: "us-west-2", gateway: { name: "agent-box-egress", targets: [] }, hosts: [], - projectGateways: [TOOLS], + projectGateways: [gateway], telemetry: [], places: profileKeyPlaces(local, ".box/profile.toml"), }); @@ -96,8 +107,8 @@ describe("the box on PATH", () => { BOX_RESOURCES: resources, AWS_REGION: "us-west-2", AGENTCORE_GATEWAY_BOX_URL: BOX_GATEWAY_URL, - AGENTCORE_GATEWAY_TOOLS_URL: `https://${HOST}/mcp`, - AGENTCORE_GATEWAY_TOOLS_HOST: HOST, + [`${gateway.variablePrefix}_URL`]: `https://${HOST}/mcp`, + [`${gateway.variablePrefix}_HOST`]: HOST, }, }, ); @@ -109,11 +120,13 @@ describe("the box on PATH", () => { }; policy: string; }; - expect(shown.box_toml.mcp.tools!.destinations).toEqual([HOST]); - expect(shown.box_toml.mcp.tools!.backends.map(({ url }) => url)).toEqual([ - `${BOX_GATEWAY_URL}/egress-gateway-tools`, + const server = shown.box_toml.mcp[gateway.name]!; + expect(server.destinations).toEqual([HOST]); + expect(server.backends.map(({ url }) => url)).toEqual([ + `${BOX_GATEWAY_URL}/${gateway.target}`, ]); - expect(shown.box_toml.agent.env.AGENTCORE_GATEWAY_TOOLS_URL).toBe(`https://${HOST}/mcp`); + expect(shown.box_toml.agent.env[`${gateway.variablePrefix}_URL`]).toBe(`https://${HOST}/mcp`); + expect(shown.policy).toContain(`context.input.server == "${gateway.name}"`); expect(shown.policy).toContain( `permit (principal, action == Box::Action::"net:connect", resource) when { (context.input.host == "${HOST}" && context.input.port == 443) };`, ); From 7545175a44a161bbf2a7739fdebb095136f0dc6a Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 16:44:49 -0800 Subject: [PATCH 04/15] fix(box): Give each gateway of the project its own Box gateway target name Review feedback: `targetNameFor` changes `--` to `-` and cuts a name at 100 characters. Thus the gateways `a--b` and `a-b`, or two long names with the same start, got the same target name, and the writer added two targets with one name. The target name stays `egress-gateway-` when that name keeps the gateway name whole. When `targetNameFor` changes the name, the target name ends in 8 hex digits of the SHA-256 of the gateway name, and it has at most 100 characters. The name is the same on each build. Test: "is not the same for a--b and a-b" and "is not the same for" two names of 96 characters with the same start, in `projectGateways.test.ts`, fail before this change. --- .../boxNetwork/projectGateways.test.ts | 39 ++++++++++++++++++- .../project/boxNetwork/projectGateways.ts | 25 +++++++++++- 2 files changed, 61 insertions(+), 3 deletions(-) diff --git a/src/core/project/boxNetwork/projectGateways.test.ts b/src/core/project/boxNetwork/projectGateways.test.ts index f13b0ac69..1e6f53e0f 100644 --- a/src/core/project/boxNetwork/projectGateways.test.ts +++ b/src/core/project/boxNetwork/projectGateways.test.ts @@ -9,7 +9,11 @@ import { apply } from "../runtimeProfile/rules/gateway"; import { serializeRuntimeProfile } from "../runtimeProfile/serialize"; import type { TomlTable } from "../runtimeProfile/types"; import { AGENTCORE_PACK_PATH, renderAgentCorePack } from "../templates/boxProfile"; -import { projectGatewayTargetFor, type BoxProjectGateway } from "./projectGateways"; +import { + projectGatewaysOf, + projectGatewayTargetFor, + type BoxProjectGateway, +} from "./projectGateways"; const TOOLS: BoxProjectGateway = { name: "tools", @@ -35,6 +39,39 @@ describe("projectGatewayTargetFor", () => { }); }); +describe("the target name of each gateway", () => { + const targetsOf = (...names: string[]) => + projectGatewaysOf( + { + agentCoreGateways: names.map((name) => ({ name, authorizerType: "AWS_IAM", targets: [] })), + } as unknown as ProjectSpec, + { name: "agent" }, + ).gateways.map(({ target }) => target); + + test("is egress-gateway- when the name fits as it is", () => { + expect(targetsOf("tools", "My-Tools-GW")).toEqual([ + "egress-gateway-tools", + "egress-gateway-My-Tools-GW", + ]); + }); + + test.each([ + ["a--b", "a-b"], + ["x".repeat(95) + "1", "x".repeat(95) + "2"], + ])("is not the same for %s and %s", (first, second) => { + const targets = targetsOf(first, second); + expect(new Set(targets).size).toBe(2); + for (const target of targets) { + expect(target.length).toBeLessThanOrEqual(100); + expect(target).toMatch(/^egress-gateway-[A-Za-z0-9]+(-[A-Za-z0-9]+)*$/); + } + }); + + test("is the same on each build", () => { + expect(targetsOf("a--b")).toEqual(targetsOf("a--b")); + }); +}); + const directories: string[] = []; afterEach(async () => { await Promise.all(directories.splice(0).map((d) => rm(d, { recursive: true, force: true }))); diff --git a/src/core/project/boxNetwork/projectGateways.ts b/src/core/project/boxNetwork/projectGateways.ts index 0d8a479ff..9540791b3 100644 --- a/src/core/project/boxNetwork/projectGateways.ts +++ b/src/core/project/boxNetwork/projectGateways.ts @@ -4,10 +4,11 @@ * AgentCore Runtime, the boxed agent gets the same variable, and box sends each call to the * gateway's host to a Box gateway target that names that gateway (`passthrough.gateway`). */ +import { createHash } from "node:crypto"; import type { AgentCoreGatewayTarget } from "../../../projectSchemas/gateway"; import { gatewayDiscoveryPrefix, type ProjectSpec } from "../../../projectSchemas/project"; import type { ProjectRuntime } from "../../../projectSchemas/runtime"; -import { targetNameFor } from "./egress"; +import { BOX_EGRESS_TARGET_PREFIX, targetNameFor } from "./egress"; /** A gateway of the project that a boxed runtime calls through its Box gateway. */ export interface BoxProjectGateway { @@ -24,6 +25,26 @@ export interface BoxProjectGateway { /** The start of the name of each Box gateway target that calls a gateway of the project. */ const PROJECT_GATEWAY_TARGET_PREFIX = "gateway-"; +/** The longest name of a gateway target, as AgentCore takes it. */ +const MAX_TARGET_NAME = 100; + +/** + * The Box gateway target name for the gateway `name`: `egress-gateway-` when that name keeps + * `name` whole. When {@link targetNameFor} changes it, as for `a--b` or a name that is too long, + * the name ends in 8 hex digits of the SHA-256 of `name`, so two gateways never share a target. + */ +function projectGatewayTargetName(name: string): string { + const plain = `${BOX_EGRESS_TARGET_PREFIX}${PROJECT_GATEWAY_TARGET_PREFIX}${name}`; + if (targetNameFor(`${PROJECT_GATEWAY_TARGET_PREFIX}${name}`) === plain) return plain; + const suffix = createHash("sha256").update(name).digest("hex").slice(0, 8); + const room = MAX_TARGET_NAME - BOX_EGRESS_TARGET_PREFIX.length - suffix.length - 1; + const kept = targetNameFor(`${PROJECT_GATEWAY_TARGET_PREFIX}${name}`)! + .slice(BOX_EGRESS_TARGET_PREFIX.length) + .slice(0, room) + .replace(/-+$/, ""); + return `${BOX_EGRESS_TARGET_PREFIX}${kept}-${suffix}`; +} + /** * The gateways of `spec` that `runtime` calls through its Box gateway: each gateway without * `boundRuntime`, as the CDK library binds it to a runtime without a box. A `PRIVATE_VPC` runtime @@ -50,7 +71,7 @@ export function projectGatewaysOf( } gateways.push({ name: gateway.name, - target: targetNameFor(`${PROJECT_GATEWAY_TARGET_PREFIX}${gateway.name}`)!, + target: projectGatewayTargetName(gateway.name), variablePrefix: gatewayDiscoveryPrefix(gateway), auth: gateway.authorizerType === "AWS_IAM" ? "iam" : "none", }); From 801cff588ef027456eac8236f90f78b6009ebe7a Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 16:48:05 -0800 Subject: [PATCH 05/15] fix(box): Write a gateway target only when the CDK library of the project accepts it Review feedback (blocking): `@aws/agentcore-cdk` 1.1.0, which `box-integration` pins, has a strict `PassthroughConfigSchema` that requires `endpoint`. It refuses `passthrough.gateway`. Build wrote that target for each gateway without `boundRuntime` of a Box project, so the synth of such a project failed until a new library ships. Build now asks the library of the CDK app, with `node` in `agentcore/cdk`, whether `PassthroughConfigSchema` accepts `{ gateway, protocolType }` (`cdkAcceptsPassthroughGateway`). Thus it reads the same library as synth, and a local build of the library works too. A version number cannot tell this, because aws/agentcore-l3-cdk-constructs has not released the change, and a local build of its `box-integration` branch has the version 1.0.2. Build asks only when a box runtime and a gateway without `boundRuntime` are in the project. When the library refuses the field, is not there, or the check fails, build writes no target, no server, and no pack input. It removes a target that it wrote before, and gives one warning that names the gateways. The manager takes the check in `cdkAcceptsPassthroughGateway`, so tests do not run `node`. Equal warnings of two box runtimes show once. Tests that fail before this change: - `compatibility.test.ts`, "cdkAcceptsPassthroughGateway": true for a library that accepts the field, false for one that requires `endpoint`, and false with no library or no schema. - `network.test.ts`, "gives the agent no gateway when the @aws/agentcore-cdk of the project refuses passthrough.gateway, and warns once". - `manager.boxNetwork.test.ts`, "writes no target and no server, and warns once, when it does not". The test "writes the target and the server when the @aws/agentcore-cdk of the project accepts passthrough.gateway" pins the other case. I also ran the check on two real libraries: `@aws/agentcore-cdk` 1.1.0 from npm gives false, and the build of aws/agentcore-l3-cdk-constructs branch `sa/box-gateway-to-gateway` gives true. --- docs/box-local-testing.md | 4 +- .../backends/cdk/compatibility.test.ts | 61 ++++++++++++++++++- .../project/backends/cdk/compatibility.ts | 28 +++++++++ src/core/project/boxNetwork/network.test.ts | 16 +++++ src/core/project/boxNetwork/network.ts | 11 +++- .../project/boxNetwork/projectGateways.ts | 16 ++++- src/core/project/boxNetworkSource.ts | 3 + src/core/project/manager.boxNetwork.test.ts | 56 ++++++++++++++++- src/core/project/manager.tsx | 31 ++++++++-- 9 files changed, 217 insertions(+), 9 deletions(-) diff --git a/docs/box-local-testing.md b/docs/box-local-testing.md index 65a8623c6..a6779d581 100644 --- a/docs/box-local-testing.md +++ b/docs/box-local-testing.md @@ -220,7 +220,9 @@ A profile that names a pack `box/` fails: box refuses it and names the `@b gateway's role `bedrock-agentcore:InvokeGateway` on that gateway only, and sets `AGENTCORE_GATEWAY__URL` and `_HOST` on the runtime. A `PRIVATE_VPC` runtime gets none of them. A `CUSTOM_JWT` gateway gets a warning and no target. You write nothing for them. A profile - entry that signs for a gateway host with `aws://` stops build. + entry that signs for a gateway host with `aws://` stops build. Build writes these targets only when + the `@aws/agentcore-cdk` in `agentcore/cdk` accepts `passthrough.gateway`: it asks that library + with `node`. Otherwise build writes none of them, and gives one warning. - **Outbound auth.** An `aws://` secret signs with the gateway's role, an `env://` secret sends an API key from AgentCore Identity, and an entry with no secret sends no credential. - **Failures.** A profile Box refuses stops build and deploy with box's own error. A wildcard diff --git a/src/core/project/backends/cdk/compatibility.test.ts b/src/core/project/backends/cdk/compatibility.test.ts index 706562788..e2091aedf 100644 --- a/src/core/project/backends/cdk/compatibility.test.ts +++ b/src/core/project/backends/cdk/compatibility.test.ts @@ -2,7 +2,11 @@ import { afterEach, describe, expect, test } from "bun:test"; import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises"; import { join } from "node:path"; import { tmpdir } from "node:os"; -import { cdkCompatibilityWarning, MINIMUM_COMPATIBLE_CDK_VERSION } from "./compatibility"; +import { + cdkAcceptsPassthroughGateway, + cdkCompatibilityWarning, + MINIMUM_COMPATIBLE_CDK_VERSION, +} from "./compatibility"; const tempDirectories: string[] = []; @@ -57,3 +61,58 @@ describe("cdkCompatibilityWarning", () => { expect(await cdkCompatibilityWarning(directory)).toBeUndefined(); }); }); + +describe("cdkAcceptsPassthroughGateway", () => { + /** A CDK app whose @aws/agentcore-cdk exports `PassthroughConfigSchema` as `schema`, a JS text. */ + async function cdkDirectoryExporting(schema: string | undefined): Promise { + const directory = await mkdtemp(join(tmpdir(), "agentcore-cdk-passthrough-gateway-")); + tempDirectories.push(directory); + if (schema === undefined) return directory; + const packageDirectory = join(directory, "node_modules", "@aws", "agentcore-cdk"); + await mkdir(packageDirectory, { recursive: true }); + await writeFile( + join(packageDirectory, "package.json"), + JSON.stringify({ name: "@aws/agentcore-cdk", version: "1.1.0", main: "index.js" }), + ); + await writeFile( + join(packageDirectory, "index.js"), + `exports.PassthroughConfigSchema = ${schema};\n`, + ); + return directory; + } + /** As each @aws/agentcore-cdk parses a passthrough: with `gateway`, or with `endpoint` only. */ + const WITH_GATEWAY = + "{ safeParse: (config) => ({ success: typeof config.gateway === 'string' }) }"; + const ENDPOINT_ONLY = + "{ safeParse: (config) => ({ success: typeof config.endpoint === 'string' }) }"; + + test.skipIf(!Bun.which("node"))( + "is true when the installed library accepts passthrough.gateway", + async () => { + expect(await cdkAcceptsPassthroughGateway(await cdkDirectoryExporting(WITH_GATEWAY))).toBe( + true, + ); + }, + ); + + test.skipIf(!Bun.which("node"))( + "is false when the installed library requires passthrough.endpoint", + async () => { + expect(await cdkAcceptsPassthroughGateway(await cdkDirectoryExporting(ENDPOINT_ONLY))).toBe( + false, + ); + }, + ); + + test.skipIf(!Bun.which("node"))( + "is false when the library is not installed, or has no PassthroughConfigSchema", + async () => { + expect(await cdkAcceptsPassthroughGateway(await cdkDirectoryExporting(undefined))).toBe( + false, + ); + expect(await cdkAcceptsPassthroughGateway(await cdkDirectoryExporting("undefined"))).toBe( + false, + ); + }, + ); +}); diff --git a/src/core/project/backends/cdk/compatibility.ts b/src/core/project/backends/cdk/compatibility.ts index 3e56bf0b0..d3f975e33 100644 --- a/src/core/project/backends/cdk/compatibility.ts +++ b/src/core/project/backends/cdk/compatibility.ts @@ -1,5 +1,7 @@ +import { execFile } from "node:child_process"; import { readFile } from "node:fs/promises"; import { join } from "node:path"; +import { promisify } from "node:util"; import semver from "semver"; export const MINIMUM_COMPATIBLE_CDK_VERSION = "1.0.0"; @@ -31,3 +33,29 @@ export async function cdkCompatibilityWarning(cdkDirectory: string): Promise { + try { + const { stdout } = await promisify(execFile)("node", ["-e", PASSTHROUGH_GATEWAY_CHECK], { + cwd: cdkDirectory, + timeout: 60_000, + }); + return stdout.trim() === "accepts"; + } catch { + return false; + } +} diff --git a/src/core/project/boxNetwork/network.test.ts b/src/core/project/boxNetwork/network.test.ts index 2d6db6354..730081fe4 100644 --- a/src/core/project/boxNetwork/network.test.ts +++ b/src/core/project/boxNetwork/network.test.ts @@ -48,6 +48,8 @@ interface Options { /** The other gateways of the project, after the Box gateway. */ readonly gateways?: Record[]; readonly runtime?: Partial; + /** Whether the @aws/agentcore-cdk of the project accepts `passthrough.gateway`; true here. */ + readonly projectGatewayTargets?: boolean; } /** The local box profile of runtime `agent`. */ @@ -99,6 +101,7 @@ function model(policy: string, egress: Record = {}, options: Op region: "us-west-2", targets: options.targets ?? [], grantedActions: options.grantedActions ?? [], + projectGatewayTargets: options.projectGatewayTargets ?? true, }); return { spec, @@ -1222,6 +1225,19 @@ describe("the gateways of the project", () => { expect(network.failures).toEqual([]); }); + test("gives the agent no gateway when the @aws/agentcore-cdk of the project refuses passthrough.gateway, and warns once", () => { + const { network } = model("", {}, { gateways: [TOOLS, OPEN], projectGatewayTargets: false }); + + expect(network.projectGateways).toEqual([]); + expect(network.failures).toEqual([]); + expect(network.warnings).toEqual([ + "The gateways 'tools' and 'open-tools' of this project get no route for a boxed agent on " + + "AgentCore Runtime, because the @aws/agentcore-cdk in agentcore/cdk does not accept " + + "passthrough.gateway. Update @aws/agentcore-cdk in agentcore/cdk/package.json to a " + + "version that accepts it, then build again.", + ]); + }); + test("gives a PRIVATE_VPC runtime no gateway, as the CDK library binds none to it", () => { const { network } = model( "", diff --git a/src/core/project/boxNetwork/network.ts b/src/core/project/boxNetwork/network.ts index 8f025440d..0a624be3b 100644 --- a/src/core/project/boxNetwork/network.ts +++ b/src/core/project/boxNetwork/network.ts @@ -163,6 +163,11 @@ export interface BoxNetworkProject { readonly targets: readonly AgentCoreGatewayTarget[]; /** The IAM actions that the gateway's `additionalPolicies` files grant, except build's own. */ readonly grantedActions: readonly string[]; + /** + * Whether the @aws/agentcore-cdk of the project accepts a target with `passthrough.gateway` + * (`cdkAcceptsPassthroughGateway`); absent means it does not, and no gateway gets a target. + */ + readonly projectGatewayTargets?: boolean; } /** The Box gateway of `runtime`: the gateway bound to it. */ @@ -201,7 +206,11 @@ export function buildBoxNetwork( return { ...rest, reason: `${where.subject} ${reason}`, place: where.place }; }; const failures: BoxNetworkFailure[] = [...parseFailures, ...map.failures.map(located)]; - const reached = projectGatewaysOf(project.spec, project.runtime); + const reached = projectGatewaysOf( + project.spec, + project.runtime, + project.projectGatewayTargets ?? false, + ); const targets = hostTargets(map.hosts, project, reached.gateways, located, parsed.profile.path); failures.push(...targets.failures); const telemetry = diff --git a/src/core/project/boxNetwork/projectGateways.ts b/src/core/project/boxNetwork/projectGateways.ts index 9540791b3..0e5b89646 100644 --- a/src/core/project/boxNetwork/projectGateways.ts +++ b/src/core/project/boxNetwork/projectGateways.ts @@ -49,11 +49,13 @@ function projectGatewayTargetName(name: string): string { * The gateways of `spec` that `runtime` calls through its Box gateway: each gateway without * `boundRuntime`, as the CDK library binds it to a runtime without a box. A `PRIVATE_VPC` runtime * gets none, and a `CUSTOM_JWT` gateway gets a warning, because the Box gateway cannot get its - * token. + * token. With `targets` false, because the @aws/agentcore-cdk of the project refuses + * `passthrough.gateway`, the runtime gets none, and one warning names them. */ export function projectGatewaysOf( spec: ProjectSpec, runtime: Pick, + targets = true, ): { gateways: BoxProjectGateway[]; warnings: string[] } { const gateways: BoxProjectGateway[] = []; const warnings: string[] = []; @@ -76,6 +78,18 @@ export function projectGatewaysOf( auth: gateway.authorizerType === "AWS_IAM" ? "iam" : "none", }); } + if (!targets && gateways.length > 0) { + const names = gateways.map(({ name }) => `'${name}'`); + const list = + names.length > 1 ? `${names.slice(0, -1).join(", ")} and ${names.at(-1)}` : names[0]; + warnings.push( + `The gateways ${list} of this project get no route for a boxed agent on AgentCore ` + + "Runtime, because the @aws/agentcore-cdk in agentcore/cdk does not accept " + + "passthrough.gateway. Update @aws/agentcore-cdk in agentcore/cdk/package.json to a " + + "version that accepts it, then build again.", + ); + return { gateways: [], warnings }; + } return { gateways, warnings }; } diff --git a/src/core/project/boxNetworkSource.ts b/src/core/project/boxNetworkSource.ts index 0b18cb0c2..0cbad886d 100644 --- a/src/core/project/boxNetworkSource.ts +++ b/src/core/project/boxNetworkSource.ts @@ -55,6 +55,8 @@ export async function readBoxNetworks( projectRoot: string, resolver: BoxProfileResolver, region: string = DEFAULT_EGRESS_BEDROCK_REGION, + /** Whether the @aws/agentcore-cdk of the project accepts `passthrough.gateway`. */ + projectGatewayTargets = false, ): Promise { const runtimes = spec.runtimes.filter((runtime) => runtimeRunsInBox(spec, runtime)); if (runtimes.length === 0) return []; @@ -84,6 +86,7 @@ export async function readBoxNetworks( region, targets: entry.targets, grantedActions: granted.actions, + projectGatewayTargets, }); networks.push({ ...network, diff --git a/src/core/project/manager.boxNetwork.test.ts b/src/core/project/manager.boxNetwork.test.ts index 91fa06fb8..cf05ad930 100644 --- a/src/core/project/manager.boxNetwork.test.ts +++ b/src/core/project/manager.boxNetwork.test.ts @@ -142,7 +142,12 @@ function countingJson() { /** A new Strands project, with the Box gateway entry and the box profile `create` writes. */ async function strandsProject( - options: { backends?: { CDK: ProjectBackend }; env?: NodeJS.ProcessEnv } = {}, + options: { + backends?: { CDK: ProjectBackend }; + env?: NodeJS.ProcessEnv; + /** What the probe of agentcore/cdk answers; it refuses passthrough.gateway when absent. */ + acceptsPassthroughGateway?: boolean; + } = {}, ) { const directory = await temporary("agentcore-box-network-"); process.chdir(directory); @@ -161,6 +166,7 @@ async function strandsProject( ...options.env, }, boxProfileResolver: box, + cdkAcceptsPassthroughGateway: async () => options.acceptsPassthroughGateway ?? false, ...(options.backends && { backends: options.backends }), }); const { value: created, warnings: createWarnings } = await drain( @@ -626,6 +632,54 @@ describe("build writes the Box network of the box profile", () => { }); }); +describe("build routes the other gateways of the project for the boxed agent", () => { + /** Adds the gateway `tools` without boundRuntime, as `agentcore add gateway` writes it. */ + async function addToolsGateway(root: string) { + const spec = JSON.parse(await text(root, SPEC)); + spec.agentCoreGateways.push({ + name: "tools", + authorizerType: "AWS_IAM", + protocolType: "None", + enableSemanticSearch: false, + exceptionLevel: "NONE", + targets: [], + }); + await writeFile(path(root, SPEC), JSON.stringify(spec, undefined, 2)); + } + + test("writes the target and the server when the @aws/agentcore-cdk of the project accepts passthrough.gateway", async () => { + const { manager, root } = await strandsProject({ acceptsPassthroughGateway: true }); + await addToolsGateway(root); + + const { warnings } = await build(manager, root); + + expect((await boxGateway(root)).targets).toContainEqual({ + name: "egress-gateway-tools", + targetType: "passthrough", + passthrough: { gateway: "tools", protocolType: "CUSTOM" }, + outboundAuth: { type: "GATEWAY_IAM_ROLE", service: "bedrock-agentcore", region: "us-west-2" }, + }); + expect((await runtimeProfile(root)).mcp).toHaveProperty("tools"); + expect(warnings.filter((warning) => warning.includes("passthrough.gateway"))).toEqual([]); + }); + + test("writes no target and no server, and warns once, when it does not", async () => { + const { manager, root } = await strandsProject({ acceptsPassthroughGateway: false }); + await addToolsGateway(root); + + const { warnings } = await build(manager, root); + + expect(await targetNames(root)).not.toContain("egress-gateway-tools"); + expect((await runtimeProfile(root)).mcp).toBeUndefined(); + expect(warnings.filter((warning) => warning.includes("passthrough.gateway"))).toEqual([ + "The gateways 'tools' of this project get no route for a boxed agent on AgentCore " + + "Runtime, because the @aws/agentcore-cdk in agentcore/cdk does not accept " + + "passthrough.gateway. Update @aws/agentcore-cdk in agentcore/cdk/package.json to a " + + "version that accepts it, then build again.", + ]); + }); +}); + describe("build writes the telemetry policy of the box profile", () => { const TELEMETRY_POLICY = "agentcore/box-telemetry-policy-agent_python_strands.json"; const ENTRY = "../../agentcore/box-telemetry-policy-agent_python_strands.json"; diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx index d7c3b9bbe..a6fdff6dd 100644 --- a/src/core/project/manager.tsx +++ b/src/core/project/manager.tsx @@ -71,6 +71,7 @@ import { hasBoxProfile, renderBoxProfile, runsInBox, + runtimeRunsInBox, startsInBoxOnCodeZip, } from "./templates/boxProfile"; import { defaultLogTargetNotice, observabilityOff } from "./runtimeProfile/rules/additions"; @@ -121,6 +122,7 @@ import { import { isChinaRegion } from "../partition"; import z from "zod"; import { CdkBackend, type TransactionSearchEnabler } from "./backends/cdk"; +import { cdkAcceptsPassthroughGateway } from "./backends/cdk/compatibility"; import { resolveAwsAccount } from "./backends/cdk/environment"; import type { ProjectBackend } from "./backends/types"; import { @@ -437,6 +439,11 @@ type ProjectManagerConfig = { * PATH by default. */ boxProfileResolver?: BoxProfileResolver; + /** + * Whether the @aws/agentcore-cdk of the CDK app in a folder accepts a passthrough target with + * `gateway`; build writes such a target only then. `cdkAcceptsPassthroughGateway` by default. + */ + cdkAcceptsPassthroughGateway?: (cdkDirectory: string) => Promise; backends?: Partial>; templateRenderer?: TemplateRenderer; /** @@ -461,6 +468,7 @@ export class FsProjectManager implements ProjectManager { private readonly resolveAccount: (region: string) => Promise; private readonly processEnv: NodeJS.ProcessEnv; private readonly boxProfileResolver: BoxProfileResolver; + private readonly cdkAcceptsPassthroughGateway: (cdkDirectory: string) => Promise; constructor(config: ProjectManagerConfig) { this.logger = config.logger; @@ -485,6 +493,8 @@ export class FsProjectManager implements ProjectManager { this.processEnv = config.processEnv ?? process.env; this.boxProfileResolver = config.boxProfileResolver ?? new BoxCliProfileResolver({ env: this.processEnv }); + this.cdkAcceptsPassthroughGateway = + config.cdkAcceptsPassthroughGateway ?? cdkAcceptsPassthroughGateway; } public async resolve(input: ResolveProjectInput): Promise { @@ -1669,11 +1679,19 @@ export class FsProjectManager implements ProjectManager { command: "build" | "deploy", region: string, ): Promise<{ project: Project; networks: BoxNetwork[]; events: ProjectEvent[] }> { + // Only a box runtime and a gateway without boundRuntime need the check of the CDK app. + const unbound = project.spec.agentCoreGateways.some(({ boundRuntime }) => !boundRuntime); + const boxed = project.spec.runtimes.some((runtime) => runtimeRunsInBox(project.spec, runtime)); + const projectGatewayTargets = + unbound && + boxed && + (await this.cdkAcceptsPassthroughGateway(join(project.rootPath, "agentcore", "cdk"))); const networks = await readBoxNetworks( project.spec, project.rootPath, this.boxProfileResolver, region, + projectGatewayTargets, ); if (networks.some(({ failures }) => failures.length > 0)) { throw new InputValidationError(boxNetworkFailureMessage(networks, command)); @@ -1721,10 +1739,15 @@ export class FsProjectManager implements ProjectManager { const { written } = await envLocal.upsert([...edits.envLocal]); for (const key of written) messages.push(`writing ${key} to ${ENV_LOCAL_RELATIVE_PATH}`); } - const warnings = networks.flatMap((network) => [ - ...network.warnings, - ...boxGatewayIamWarnings(edits.spec, network), - ]); + // Each box runtime gives the same warning for the CDK app, so it appears once. + const warnings = [ + ...new Set( + networks.flatMap((network) => [ + ...network.warnings, + ...boxGatewayIamWarnings(edits.spec, network), + ]), + ), + ]; const events: ProjectEvent[] = [ ...messages.map((message) => ({ type: "step" as const, message })), ...warnings.map((message) => ({ type: "warning" as const, message })), From 743cd84cfc4dcce6883f4b1fdcca35b3768d934a Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 16:49:11 -0800 Subject: [PATCH 06/15] fix(remove): Remove the Box gateway target of a gateway with the gateway Review feedback (blocking): after one build, each Box gateway has the target `egress-gateway-` with `passthrough.gateway: ""`. `agentcore remove gateway ` kept that target, the project schema refused the new spec because the target names no gateway, and thus the user could not remove the gateway, and build could not remove the target. `removeResource` now also removes, from each other gateway, each target that build owns (its name starts with `egress-`) and that names the removed gateway in `passthrough.gateway`. A target of the user's that names the gateway stays, and the schema still refuses it with its name, so build never removes a target that the user wrote. I did not make the schema accept a target that names no gateway, because the spec then is not valid for the CDK library until the next build. Test: `manager.boxNetwork.test.ts`, "lets remove gateway remove the gateway after a build, with the target build wrote for it", fails before this change with the schema error. It builds, removes the gateway, and then builds again. The user's own target stays. --- src/core/project/manager.boxNetwork.test.ts | 20 ++++++++++++++++++++ src/core/project/manager.tsx | 18 +++++++++++++++++- 2 files changed, 37 insertions(+), 1 deletion(-) diff --git a/src/core/project/manager.boxNetwork.test.ts b/src/core/project/manager.boxNetwork.test.ts index cf05ad930..66d8e82a9 100644 --- a/src/core/project/manager.boxNetwork.test.ts +++ b/src/core/project/manager.boxNetwork.test.ts @@ -663,6 +663,26 @@ describe("build routes the other gateways of the project for the boxed agent", ( expect(warnings.filter((warning) => warning.includes("passthrough.gateway"))).toEqual([]); }); + test("lets remove gateway remove the gateway after a build, with the target build wrote for it", async () => { + const { manager, root } = await strandsProject({ acceptsPassthroughGateway: true }); + await addToolsGateway(root); + const user = userTarget("mine", "https://mine.example.com"); + await editGateway(root, (gateway) => gateway.targets.push(user)); + await build(manager, root); + expect(await targetNames(root)).toContain("egress-gateway-tools"); + + const project = (await manager.resolve({ filePath: root })) as Project; + await manager.removeResource(project, { resourceType: "gateway", name: "tools" }); + + const spec = JSON.parse(await text(root, SPEC)); + expect(spec.agentCoreGateways.map(({ name }: { name: string }) => name)).toEqual([GATEWAY]); + expect(await targetNames(root)).not.toContain("egress-gateway-tools"); + expect((await boxGateway(root)).targets).toContainEqual(user); + // The next build writes no target for the gateway that is gone. + await build(manager, root); + expect(await targetNames(root)).not.toContain("egress-gateway-tools"); + }); + test("writes no target and no server, and warns once, when it does not", async () => { const { manager, root } = await strandsProject({ acceptsPassthroughGateway: false }); await addToolsGateway(root); diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx index a6fdff6dd..771e41549 100644 --- a/src/core/project/manager.tsx +++ b/src/core/project/manager.tsx @@ -54,7 +54,7 @@ import { harnessApiKeyCredentialName, validateHarnessTemplateSource, } from "./templates/harness"; -import { boxGatewayIamWarnings, type BoxNetwork } from "./boxNetwork"; +import { boxGatewayIamWarnings, isManagedTarget, type BoxNetwork } from "./boxNetwork"; import { boxNetworkFailureMessage, readBoxNetworks } from "./boxNetworkSource"; import { DEFAULT_REGION, regionFromConfigFile } from "../region"; import { BoxCliProfileResolver, type BoxProfileResolver } from "./boxProfileResolver"; @@ -1260,6 +1260,22 @@ export class FsProjectManager implements ProjectManager { const newResources = existingResources.filter((resource) => resource.name !== input.name); removed = newResources.length !== existingResources.length; newSpec = { ...existingProjectSpec, [projectSpecKey]: newResources }; + // Build writes a target on each Box gateway for each other gateway of the project. Such a + // target goes with its gateway; a target of the user's that names it stays, and fails. + if (input.resourceType === "gateway" && removed) { + newSpec = { + ...(newSpec as object), + agentCoreGateways: existingProjectSpec.agentCoreGateways + .filter((gateway) => gateway.name !== input.name) + .map((gateway) => ({ + ...gateway, + targets: gateway.targets.filter( + (target) => + !(isManagedTarget(target) && target.passthrough?.gateway === input.name), + ), + })), + }; + } // A gateway bound to the runtime (each Box gateway is) goes with the runtime, and its // targets go too. A gateway bound to a runtime that does not exist fails validation. if (input.resourceType === "runtime" && removed) { From ff0c48f75de8451ebefe12b1862151986647c437 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 17:32:06 -0800 Subject: [PATCH 07/15] fix(box): Read a project whose build-owned gateway target names a gateway that it cannot call Review feedback: after a build, a gateway of the project that gets `boundRuntime`, or that is removed from agentcore.json by hand, left the target `egress-gateway-` with a reference that the project schema refused. Each command then stopped when it read agentcore.json, so build could not remove the target. The schema does not do this check for a target whose name starts with `egress-` (`BOX_EGRESS_TARGET_PREFIX`), because build writes and removes each such target. The next build removes the target. A target of the user that names such a gateway is still refused. The prefix moves to `projectSchemas/project.ts`, and `boxNetwork/egress.ts` exports it from there. Tests that fail before this change: `manager.boxNetwork.test.ts`, "reads the project and removes the target after a build when the gateway gets boundRuntime" and "reads the project and removes the target when the gateway is gone from agentcore.json". `project.test.ts`, "accepts a target that build owns and that names ...", pins the schema. The refusals in that file now use a target of the user. --- src/core/project/boxNetwork/egress.ts | 7 ++--- src/core/project/manager.boxNetwork.test.ts | 34 +++++++++++++++++++++ src/projectSchemas/project.test.ts | 25 ++++++++++++--- src/projectSchemas/project.ts | 11 +++++-- 4 files changed, 66 insertions(+), 11 deletions(-) diff --git a/src/core/project/boxNetwork/egress.ts b/src/core/project/boxNetwork/egress.ts index ad1cf2f48..df3cb65d6 100644 --- a/src/core/project/boxNetwork/egress.ts +++ b/src/core/project/boxNetwork/egress.ts @@ -1,4 +1,5 @@ import { z } from "zod"; +import { BOX_EGRESS_TARGET_PREFIX } from "../../../projectSchemas/project"; import type { BoxEgressAuth } from "./network"; import type { FailureCode } from "./types"; @@ -160,11 +161,7 @@ export function signingService(host: string): { service: string; region: string return endpoint && { service: endpoint.service, region: endpoint.region }; } -/** - * The start of the name of each target that build adds to a Box gateway. Build manages every - * target whose name has it, and no other. - */ -export const BOX_EGRESS_TARGET_PREFIX = "egress-"; +export { BOX_EGRESS_TARGET_PREFIX }; /** * The gateway target name build gives `name`: {@link BOX_EGRESS_TARGET_PREFIX}, then the letters diff --git a/src/core/project/manager.boxNetwork.test.ts b/src/core/project/manager.boxNetwork.test.ts index 66d8e82a9..e38168b25 100644 --- a/src/core/project/manager.boxNetwork.test.ts +++ b/src/core/project/manager.boxNetwork.test.ts @@ -683,6 +683,40 @@ describe("build routes the other gateways of the project for the boxed agent", ( expect(await targetNames(root)).not.toContain("egress-gateway-tools"); }); + test("reads the project and removes the target after a build when the gateway gets boundRuntime", async () => { + const { manager, root } = await strandsProject({ acceptsPassthroughGateway: true }); + await addToolsGateway(root); + await build(manager, root); + expect(await targetNames(root)).toContain("egress-gateway-tools"); + const spec = JSON.parse(await text(root, SPEC)); + spec.agentCoreGateways.find(({ name }: { name: string }) => name === "tools").boundRuntime = + "agent_python_strands"; + await writeFile(path(root, SPEC), JSON.stringify(spec, undefined, 2)); + + const { steps } = await build(manager, root); + + expect(await targetNames(root)).not.toContain("egress-gateway-tools"); + expect(steps).toContain( + "removing gateway target 'egress-gateway-tools' from 'agent-python-strands-box-egress': " + + "the boxed agent no longer calls the gateway 'tools'", + ); + }); + + test("reads the project and removes the target when the gateway is gone from agentcore.json", async () => { + const { manager, root } = await strandsProject({ acceptsPassthroughGateway: true }); + await addToolsGateway(root); + await build(manager, root); + const spec = JSON.parse(await text(root, SPEC)); + spec.agentCoreGateways = spec.agentCoreGateways.filter( + ({ name }: { name: string }) => name !== "tools", + ); + await writeFile(path(root, SPEC), JSON.stringify(spec, undefined, 2)); + + await build(manager, root); + + expect(await targetNames(root)).not.toContain("egress-gateway-tools"); + }); + test("writes no target and no server, and warns once, when it does not", async () => { const { manager, root } = await strandsProject({ acceptsPassthroughGateway: false }); await addToolsGateway(root); diff --git a/src/projectSchemas/project.test.ts b/src/projectSchemas/project.test.ts index d57f041f3..be539bc8b 100644 --- a/src/projectSchemas/project.test.ts +++ b/src/projectSchemas/project.test.ts @@ -556,8 +556,8 @@ describe("gateway boundRuntime and discoveryPrefix", () => { }); describe("a passthrough target that names a gateway", () => { - const target = (passthrough: Record) => ({ - name: "egress-gateway-tools", + const target = (passthrough: Record, name = "tools-call") => ({ + name, targetType: "passthrough", passthrough: { protocolType: "CUSTOM", ...passthrough }, outboundAuth: { type: "GATEWAY_IAM_ROLE", service: "bedrock-agentcore", region: "us-west-2" }, @@ -570,11 +570,15 @@ describe("a passthrough target that names a gateway", () => { }); return result.success ? [] : result.error.issues.map(({ message }) => message); }; - const front = (passthrough: Record, fields: Record = {}) => ({ + const front = ( + passthrough: Record, + fields: Record = {}, + name?: string, + ) => ({ name: "front", authorizerType: "AWS_IAM", protocolType: "None", - targets: [target(passthrough)], + targets: [target(passthrough, name)], ...fields, }); const TOOLS = { name: "tools", authorizerType: "AWS_IAM", targets: [] }; @@ -599,6 +603,19 @@ describe("a passthrough target that names a gateway", () => { expect(messages(gateways)).toContainEqual(expect.stringContaining(message)); }); + test.each([ + ["no gateway of that name", [front({ gateway: "gone" }, {}, "egress-gateway-gone")]], + [ + "a gateway bound to a runtime", + [ + front({ gateway: "tools" }, {}, "egress-gateway-tools"), + { ...TOOLS, boundRuntime: "agent" }, + ], + ], + ])("accepts a target that build owns and that names %s, as build removes it", (_, gateways) => { + expect(messages(gateways)).toEqual([]); + }); + test.each([ ["both endpoint and gateway", { endpoint: "https://api.example.com", gateway: "tools" }], ["neither endpoint nor gateway", {}], diff --git a/src/projectSchemas/project.ts b/src/projectSchemas/project.ts index a99d5691a..fc95819af 100644 --- a/src/projectSchemas/project.ts +++ b/src/projectSchemas/project.ts @@ -31,6 +31,11 @@ export const ProjectNameSchema = z export const ProjectTypeSchema = z.enum(["box"]); /** Whether the project is a Box project, so the CLI keeps a Box gateway for each runtime. */ export const isBoxProject = (spec: { projectType?: string }) => spec.projectType === "box"; +/** + * The start of the name of each target that build adds to a Box gateway. Build manages every + * target whose name has it, and no other. + */ +export const BOX_EGRESS_TARGET_PREFIX = "egress-"; /** The suffix of each Box gateway name: the runtime `agent` gets the gateway `agent-box-egress`. */ export const BOX_GATEWAY_SUFFIX = "-box-egress"; /** @@ -162,11 +167,13 @@ export const ProjectSpecSchema = z } } // A passthrough target that names a gateway calls a gateway of this project. A gateway bound to - // a runtime belongs to that runtime, so no target of another gateway calls it. + // a runtime belongs to that runtime, so no target of another gateway calls it. Build writes + // and removes each target whose name starts with BOX_EGRESS_TARGET_PREFIX, so such a target + // that names no such gateway is not refused here: the next build removes it. for (const gateway of spec.agentCoreGateways) { for (const target of gateway.targets) { const reached = target.passthrough?.gateway; - if (reached === undefined) continue; + if (reached === undefined || target.name.startsWith(BOX_EGRESS_TARGET_PREFIX)) continue; const named = spec.agentCoreGateways.find((other) => other.name === reached); const problem = named === undefined From a04371824036bd72d5f34d02b3ce13947561a985 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 17:32:52 -0800 Subject: [PATCH 08/15] fix(box): Stop build when two gateways of the project get one target name Review feedback: `hostTargets` put the target of each gateway of the project in `owners` with `owners.set`. When two gateways got one target name, the second name replaced the first one with no report, and the writer added two targets with one name. The target names of 7545175a already differ for gateway names that share their first 90 characters: the test now has "a".repeat(90) + "x1" and + "x2". A gateway can still have, as its name, the name that a different gateway gets with its hash, for example `a--b` and `a-b-`. Build now stops with `TARGET_NAME_COLLISION` for two gateways with one target name, as it does for two hosts. Thus the writer never runs with two targets of one name. Test: `network.test.ts`, "fails two gateways whose targets still have one name, as for two hosts", fails before this change. `projectGateways.test.ts`, "is not the same for" the two names of 92 characters, passes before and after. --- src/core/project/boxNetwork/network.test.ts | 15 +++++++++++++++ src/core/project/boxNetwork/network.ts | 14 ++++++++++++++ .../project/boxNetwork/projectGateways.test.ts | 1 + 3 files changed, 30 insertions(+) diff --git a/src/core/project/boxNetwork/network.test.ts b/src/core/project/boxNetwork/network.test.ts index 730081fe4..e3af763d6 100644 --- a/src/core/project/boxNetwork/network.test.ts +++ b/src/core/project/boxNetwork/network.test.ts @@ -1,4 +1,5 @@ import { describe, expect, test } from "bun:test"; +import { createHash } from "node:crypto"; import { getBoxGatewayAgentCoreTargetSpec, getBoxGatewayBedrockTargetSpec, @@ -1259,6 +1260,20 @@ describe("the gateways of the project", () => { ); }); + test("fails two gateways whose targets still have one name, as for two hosts", () => { + // The target of "a--b" ends in the hash of its name, which a second gateway can have as a name. + const hash = createHash("sha256").update("a--b").digest("hex").slice(0, 8); + const first = { name: "a--b", authorizerType: "AWS_IAM", targets: [] }; + const second = { name: `a-b-${hash}`, authorizerType: "AWS_IAM", targets: [] }; + const r = model("", {}, { gateways: [first, second] }); + + expect(r.failures()).toEqual([["TARGET_NAME_COLLISION", `egress-gateway-a-b-${hash}`]]); + expect(r.reasons()).toEqual([ + `The gateways 'a--b' and 'a-b-${hash}' of this project would both get the gateway target ` + + `'egress-gateway-a-b-${hash}'. Rename one of the gateways.`, + ]); + }); + test("fails an entry whose target would take the name of a gateway's target", () => { const r = model( "", diff --git a/src/core/project/boxNetwork/network.ts b/src/core/project/boxNetwork/network.ts index 0a624be3b..19c54d40a 100644 --- a/src/core/project/boxNetwork/network.ts +++ b/src/core/project/boxNetwork/network.ts @@ -462,7 +462,21 @@ function hostTargets( for (const target of existing) { if (!isManagedTarget(target)) owners.set(target.name, `the gateway target '${target.name}'`); } + const gatewayOf = new Map(); for (const gateway of gateways) { + const other = gatewayOf.get(gateway.target); + if (other !== undefined) { + failures.push({ + code: "TARGET_NAME_COLLISION", + target: gateway.target, + reason: + `The gateways '${other}' and '${gateway.name}' of this project would both get the ` + + `gateway target '${gateway.target}'. Rename one of the gateways.`, + place: PROJECT_SPEC_PLACE, + }); + continue; + } + gatewayOf.set(gateway.target, gateway.name); owners.set(gateway.target, `the target that build adds for the gateway '${gateway.name}'`); } const describeHost = (host: MappedHost) => diff --git a/src/core/project/boxNetwork/projectGateways.test.ts b/src/core/project/boxNetwork/projectGateways.test.ts index 1e6f53e0f..bcbe602b8 100644 --- a/src/core/project/boxNetwork/projectGateways.test.ts +++ b/src/core/project/boxNetwork/projectGateways.test.ts @@ -58,6 +58,7 @@ describe("the target name of each gateway", () => { test.each([ ["a--b", "a-b"], ["x".repeat(95) + "1", "x".repeat(95) + "2"], + ["a".repeat(90) + "x1", "a".repeat(90) + "x2"], ])("is not the same for %s and %s", (first, second) => { const targets = targetsOf(first, second); expect(new Set(targets).size).toBe(2); From 869d590d0b50770738e79e9b7998622a2d21dbc4 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 17:33:21 -0800 Subject: [PATCH 09/15] fix(box): Add the server of a gateway named constructor to the Runtime profile Review feedback: the gateway rule checked `gateway.name in mcp`, which is true for a key that each object has from its prototype. Thus a gateway named `constructor` or `toString` stopped build with `RUNTIME_GATEWAY_SERVER_NAME_TAKEN`. The rule now uses `Object.hasOwn(mcp, gateway.name)`. Test: `gateway.test.ts`, "adds the server of a gateway whose name is a key of every object, such as constructor", fails before this change. --- src/core/project/runtimeProfile/rules/gateway.test.ts | 11 +++++++++++ src/core/project/runtimeProfile/rules/gateway.ts | 2 +- 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/src/core/project/runtimeProfile/rules/gateway.test.ts b/src/core/project/runtimeProfile/rules/gateway.test.ts index 77f07d137..97f452d87 100644 --- a/src/core/project/runtimeProfile/rules/gateway.test.ts +++ b/src/core/project/runtimeProfile/rules/gateway.test.ts @@ -743,6 +743,17 @@ describe("the gateway rule for a gateway of the project", () => { expect(result.table.mcp).toBeUndefined(); }); + test("adds the server of a gateway whose name is a key of every object, such as constructor", () => { + const named = { ...TOOLS, name: "constructor", target: "egress-gateway-constructor" }; + const result = apply(parse(PROFILE_TEXT) as TomlTable, { + ...contextOf(PROFILE_TEXT, []), + projectGateways: [named], + }); + + expect(result.problems).toEqual([]); + expect(Object.keys(result.table.mcp as TomlTable)).toEqual(["constructor"]); + }); + test("stops for a server of the local profile with the gateway's name", () => { const text = `${PROFILE_TEXT}\n[mcp.tools]\ncommand = ["/usr/bin/tools"]\n`; diff --git a/src/core/project/runtimeProfile/rules/gateway.ts b/src/core/project/runtimeProfile/rules/gateway.ts index 56778f9d3..452f408f7 100644 --- a/src/core/project/runtimeProfile/rules/gateway.ts +++ b/src/core/project/runtimeProfile/rules/gateway.ts @@ -86,7 +86,7 @@ export function apply(table: Readonly, context: RuntimeProfileContext const problems: RuntimeProfileProblem[] = []; for (const gateway of context.projectGateways ?? []) { - if (gateway.name in mcp) { + if (Object.hasOwn(mcp, gateway.name)) { problems.push({ code: "RUNTIME_GATEWAY_SERVER_NAME_TAKEN", key: ["mcp", gateway.name], From e095a842723fbe8d695afc9635f9e0f1f991949b Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 17:35:49 -0800 Subject: [PATCH 10/15] fix(box): Give the CUSTOM_JWT gateway notice once, at add gateway, and not on each build Review feedback: build gave the warning for a `CUSTOM_JWT` gateway on each build, one time for each boxed runtime. The CLI gives a notice about a resource when a command writes that resource: `create` and `add runtime` give the notices of the Box gateway logs and of the default log target. This change does the same. `agentcore add gateway` gives `customJwtGatewayNotice` one time, after it writes a `CUSTOM_JWT` gateway without `boundRuntime` to a project that has a boxed runtime that is not `PRIVATE_VPC`. Build gives no warning for the gateway. I did not add an opt-out, because a notice at the write is simpler and is what the CLI does for its other notices. Tests that fail before this change: `network.test.ts`, "gives the agent no route to a CUSTOM_JWT gateway, and no warning on each build", and `manager.boxNetwork.test.ts`, "add gateway gives one notice for a CUSTOM_JWT gateway, and build gives none". --- docs/box-local-testing.md | 2 +- src/core/project/boxNetwork/network.test.ts | 8 ++--- .../project/boxNetwork/projectGateways.ts | 23 +++++++------ src/core/project/manager.boxNetwork.test.ts | 34 +++++++++++++++++++ src/core/project/manager.tsx | 14 ++++++++ 5 files changed, 63 insertions(+), 18 deletions(-) diff --git a/docs/box-local-testing.md b/docs/box-local-testing.md index a6779d581..9d20632c4 100644 --- a/docs/box-local-testing.md +++ b/docs/box-local-testing.md @@ -219,7 +219,7 @@ A profile that names a pack `box/` fails: box refuses it and names the `@b the gateway's name. The L3 sets the target's endpoint to that gateway's URL, gives the Box gateway's role `bedrock-agentcore:InvokeGateway` on that gateway only, and sets `AGENTCORE_GATEWAY__URL` and `_HOST` on the runtime. A `PRIVATE_VPC` runtime gets none of - them. A `CUSTOM_JWT` gateway gets a warning and no target. You write nothing for them. A profile + them. A `CUSTOM_JWT` gateway gets no target, and `agentcore add gateway` gives one notice for it. You write nothing for them. A profile entry that signs for a gateway host with `aws://` stops build. Build writes these targets only when the `@aws/agentcore-cdk` in `agentcore/cdk` accepts `passthrough.gateway`: it asks that library with `node`. Otherwise build writes none of them, and gives one warning. diff --git a/src/core/project/boxNetwork/network.test.ts b/src/core/project/boxNetwork/network.test.ts index e3af763d6..76d0ad375 100644 --- a/src/core/project/boxNetwork/network.test.ts +++ b/src/core/project/boxNetwork/network.test.ts @@ -1249,15 +1249,11 @@ describe("the gateways of the project", () => { expect(network.projectGateways).toEqual([]); }); - test("warns for a CUSTOM_JWT gateway, and gives the agent no route to it", () => { + test("gives the agent no route to a CUSTOM_JWT gateway, and no warning on each build", () => { const { network } = model("", {}, { gateways: [JWT] }); expect(network.projectGateways).toEqual([]); - expect(network.warnings).toContain( - "The gateway 'jwt-tools' takes CUSTOM_JWT tokens, and the Box gateway of runtime 'agent' " + - "signs only with its IAM role, so the boxed agent cannot call 'jwt-tools' on AgentCore " + - "Runtime. Set its authorizerType to AWS_IAM to let the agent call it.", - ); + expect(network.warnings).toEqual([]); }); test("fails two gateways whose targets still have one name, as for two hosts", () => { diff --git a/src/core/project/boxNetwork/projectGateways.ts b/src/core/project/boxNetwork/projectGateways.ts index 0e5b89646..6bf2f4671 100644 --- a/src/core/project/boxNetwork/projectGateways.ts +++ b/src/core/project/boxNetwork/projectGateways.ts @@ -48,8 +48,8 @@ function projectGatewayTargetName(name: string): string { /** * The gateways of `spec` that `runtime` calls through its Box gateway: each gateway without * `boundRuntime`, as the CDK library binds it to a runtime without a box. A `PRIVATE_VPC` runtime - * gets none, and a `CUSTOM_JWT` gateway gets a warning, because the Box gateway cannot get its - * token. With `targets` false, because the @aws/agentcore-cdk of the project refuses + * gets none, and no `CUSTOM_JWT` gateway, because the Box gateway cannot get its token; + * `add gateway` gives {@link customJwtGatewayNotice} for it once. With `targets` false, because the @aws/agentcore-cdk of the project refuses * `passthrough.gateway`, the runtime gets none, and one warning names them. */ export function projectGatewaysOf( @@ -62,15 +62,7 @@ export function projectGatewaysOf( if (runtime.containment === "PRIVATE_VPC") return { gateways, warnings }; for (const gateway of spec.agentCoreGateways) { if (gateway.boundRuntime !== undefined) continue; - if (gateway.authorizerType === "CUSTOM_JWT") { - warnings.push( - `The gateway '${gateway.name}' takes CUSTOM_JWT tokens, and the Box gateway of runtime ` + - `'${runtime.name}' signs only with its IAM role, so the boxed agent cannot call ` + - `'${gateway.name}' on AgentCore Runtime. Set its authorizerType to AWS_IAM to let the ` + - "agent call it.", - ); - continue; - } + if (gateway.authorizerType === "CUSTOM_JWT") continue; gateways.push({ name: gateway.name, target: projectGatewayTargetName(gateway.name), @@ -111,6 +103,15 @@ export function projectGatewayTargetFor( }; } +/** What `add gateway` tells the user once about a `CUSTOM_JWT` gateway in a Box project. */ +export function customJwtGatewayNotice(gatewayName: string): string { + return ( + `the gateway '${gatewayName}' takes CUSTOM_JWT tokens, and a Box gateway signs only with its ` + + `IAM role, so a boxed agent cannot call '${gatewayName}' on AgentCore Runtime, and build adds ` + + "no route to it. Set its authorizerType to AWS_IAM to let a boxed agent call it" + ); +} + /** The `@box/agentcore` inputs that carry the URL and the host of `gateway` on the Runtime. */ export function projectGatewayInputs(gateway: Pick): { readonly url: string; diff --git a/src/core/project/manager.boxNetwork.test.ts b/src/core/project/manager.boxNetwork.test.ts index e38168b25..2ba0a065b 100644 --- a/src/core/project/manager.boxNetwork.test.ts +++ b/src/core/project/manager.boxNetwork.test.ts @@ -717,6 +717,40 @@ describe("build routes the other gateways of the project for the boxed agent", ( expect(await targetNames(root)).not.toContain("egress-gateway-tools"); }); + test("add gateway gives one notice for a CUSTOM_JWT gateway, and build gives none", async () => { + const { manager, root } = await strandsProject({ acceptsPassthroughGateway: true }); + const project = (await manager.resolve({ filePath: root })) as Project; + const jwt = { + name: "secure", + authorizerType: "CUSTOM_JWT", + authorizerConfiguration: { + customJwtAuthorizer: { + discoveryUrl: "https://idp.example.com/.well-known/openid-configuration", + allowedAudience: ["agentcore"], + }, + }, + enableSemanticSearch: false, + exceptionLevel: "NONE", + protocolType: "MCP", + targets: [], + }; + + const added = await drain( + manager.addResource(project, { + resourceType: "gateway", + resourceConfig: jwt, + } as unknown as Parameters[1]), + ); + const built = await build(manager, root); + + const notice = + "the gateway 'secure' takes CUSTOM_JWT tokens, and a Box gateway signs only with its IAM " + + "role, so a boxed agent cannot call 'secure' on AgentCore Runtime, and build adds no route " + + "to it. Set its authorizerType to AWS_IAM to let a boxed agent call it"; + expect(added.warnings).toEqual([notice]); + expect(built.warnings.filter((warning) => warning.includes("CUSTOM_JWT"))).toEqual([]); + }); + test("writes no target and no server, and warns once, when it does not", async () => { const { manager, root } = await strandsProject({ acceptsPassthroughGateway: false }); await addToolsGateway(root); diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx index 771e41549..3af7ec6c2 100644 --- a/src/core/project/manager.tsx +++ b/src/core/project/manager.tsx @@ -123,6 +123,7 @@ import { isChinaRegion } from "../partition"; import z from "zod"; import { CdkBackend, type TransactionSearchEnabler } from "./backends/cdk"; import { cdkAcceptsPassthroughGateway } from "./backends/cdk/compatibility"; +import { customJwtGatewayNotice } from "./boxNetwork/projectGateways"; import { resolveAwsAccount } from "./backends/cdk/environment"; import type { ProjectBackend } from "./backends/types"; import { @@ -1103,6 +1104,19 @@ export class FsProjectManager implements ProjectManager { ]); throw err; } + // After the write, so a failed write gives no notice for a gateway that was not written. + if (input.resourceType === "gateway") { + const added = newProjectSpec.agentCoreGateways.find( + ({ name }) => name === input.resourceConfig.name, + ); + const boxed = newProjectSpec.runtimes.some( + (runtime) => + runtimeRunsInBox(newProjectSpec, runtime) && runtime.containment !== "PRIVATE_VPC", + ); + if (added && !added.boundRuntime && added.authorizerType === "CUSTOM_JWT" && boxed) { + yield { type: "warning", message: customJwtGatewayNotice(added.name) }; + } + } // After the write, so a failed write gives no notice for a runtime that was not written. if (input.resourceType === "runtime") { const added = input.resourceConfig.name; From 52f88f162552a1d089863f3ffea2c85804cd6d11 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 17:55:52 -0800 Subject: [PATCH 11/15] fix(box): Ask the CDK library about a whole gateway target, as its schema now splits passthrough aws/agentcore-l3-cdk-constructs PR 478, commit a1c7d24 (for its review), keeps `PassthroughConfigSchema` with a required `endpoint`, and gives `passthrough.gateway` the schema `GatewayPassthroughConfigSchema`. Thus the check of 801cff58, which parsed `{ gateway }` with `PassthroughConfigSchema`, gave false for the library that accepts the field, and build wrote no target. `cdkAcceptsPassthroughGateway` now parses a whole target as build writes it with `AgentCoreGatewayTargetSchema`, which both libraries export. `@aws/agentcore-cdk` 1.1.0 from npm gives false, and the build of PR 478 at d57f789 gives true. Test: in `compatibility.test.ts`, "is true when the installed library accepts passthrough.gateway" fails before this change. Its fake library now exports `AgentCoreGatewayTargetSchema`. --- .../project/backends/cdk/compatibility.test.ts | 12 ++++++------ src/core/project/backends/cdk/compatibility.ts | 15 +++++++++++---- 2 files changed, 17 insertions(+), 10 deletions(-) diff --git a/src/core/project/backends/cdk/compatibility.test.ts b/src/core/project/backends/cdk/compatibility.test.ts index e2091aedf..ebf394965 100644 --- a/src/core/project/backends/cdk/compatibility.test.ts +++ b/src/core/project/backends/cdk/compatibility.test.ts @@ -63,7 +63,7 @@ describe("cdkCompatibilityWarning", () => { }); describe("cdkAcceptsPassthroughGateway", () => { - /** A CDK app whose @aws/agentcore-cdk exports `PassthroughConfigSchema` as `schema`, a JS text. */ + /** A CDK app whose @aws/agentcore-cdk exports `AgentCoreGatewayTargetSchema` as `schema`, a JS text. */ async function cdkDirectoryExporting(schema: string | undefined): Promise { const directory = await mkdtemp(join(tmpdir(), "agentcore-cdk-passthrough-gateway-")); tempDirectories.push(directory); @@ -76,15 +76,15 @@ describe("cdkAcceptsPassthroughGateway", () => { ); await writeFile( join(packageDirectory, "index.js"), - `exports.PassthroughConfigSchema = ${schema};\n`, + `exports.AgentCoreGatewayTargetSchema = ${schema};\n`, ); return directory; } - /** As each @aws/agentcore-cdk parses a passthrough: with `gateway`, or with `endpoint` only. */ + /** As each @aws/agentcore-cdk parses the passthrough of a target: with `gateway`, or `endpoint` only. */ const WITH_GATEWAY = - "{ safeParse: (config) => ({ success: typeof config.gateway === 'string' }) }"; + "{ safeParse: (target) => ({ success: typeof target.passthrough.gateway === 'string' }) }"; const ENDPOINT_ONLY = - "{ safeParse: (config) => ({ success: typeof config.endpoint === 'string' }) }"; + "{ safeParse: (target) => ({ success: typeof target.passthrough.endpoint === 'string' }) }"; test.skipIf(!Bun.which("node"))( "is true when the installed library accepts passthrough.gateway", @@ -105,7 +105,7 @@ describe("cdkAcceptsPassthroughGateway", () => { ); test.skipIf(!Bun.which("node"))( - "is false when the library is not installed, or has no PassthroughConfigSchema", + "is false when the library is not installed, or has no AgentCoreGatewayTargetSchema", async () => { expect(await cdkAcceptsPassthroughGateway(await cdkDirectoryExporting(undefined))).toBe( false, diff --git a/src/core/project/backends/cdk/compatibility.ts b/src/core/project/backends/cdk/compatibility.ts index d3f975e33..e6123fac8 100644 --- a/src/core/project/backends/cdk/compatibility.ts +++ b/src/core/project/backends/cdk/compatibility.ts @@ -36,14 +36,21 @@ export async function cdkCompatibilityWarning(cdkDirectory: string): Promise Date: Fri, 20 Nov 2026 18:00:53 -0800 Subject: [PATCH 12/15] fix(schema): Skip the passthrough.gateway check only for an egress- target of a Box gateway Review feedback on ff0c48f7: the schema skipped the check for each target whose name starts with `egress-`, on each gateway of each project. Build manages `egress-` targets only on the Box gateway of a runtime: a gateway with `boundRuntime` in a project with `"projectType": "box"`. The skip now applies only to such a target. An `egress-` target on a gateway without `boundRuntime`, or in a project that is not a Box project, gets the check, as each other target does. Tests: in `project.test.ts`, "is refused on a gateway without boundRuntime, which build does not write" and "is refused in a project that is not a Box project" fail before this change. "is accepted on the Box gateway of a Box project when it names ..." pins the case that build removes. --- src/projectSchemas/project.test.ts | 49 +++++++++++++++++++++++------- src/projectSchemas/project.ts | 13 +++++--- 2 files changed, 47 insertions(+), 15 deletions(-) diff --git a/src/projectSchemas/project.test.ts b/src/projectSchemas/project.test.ts index be539bc8b..9ce82c0be 100644 --- a/src/projectSchemas/project.test.ts +++ b/src/projectSchemas/project.test.ts @@ -603,17 +603,44 @@ describe("a passthrough target that names a gateway", () => { expect(messages(gateways)).toContainEqual(expect.stringContaining(message)); }); - test.each([ - ["no gateway of that name", [front({ gateway: "gone" }, {}, "egress-gateway-gone")]], - [ - "a gateway bound to a runtime", - [ - front({ gateway: "tools" }, {}, "egress-gateway-tools"), - { ...TOOLS, boundRuntime: "agent" }, - ], - ], - ])("accepts a target that build owns and that names %s, as build removes it", (_, gateways) => { - expect(messages(gateways)).toEqual([]); + describe("a target that build owns", () => { + /** The Box gateway of `agent`, with one egress- target that names `gateway`. */ + const boxGateway = (gateway: string) => ({ + ...boxGatewaySpec("agent"), + targets: [target({ gateway }, `egress-gateway-${gateway}`)], + }); + const parse = (projectType: string | undefined, gateways: unknown[]) => { + const result = ProjectSpecSchema.safeParse({ + ...minimalProject, + ...(projectType && { projectType }), + runtimes: [runtime], + agentCoreGateways: gateways, + }); + return result.success ? [] : result.error.issues.map(({ message }) => message); + }; + + test.each([ + ["no gateway of that name", [boxGateway("gone")]], + ["a gateway bound to a runtime", [boxGateway("tools"), { ...TOOLS, boundRuntime: "agent" }]], + ])( + "is accepted on the Box gateway of a Box project when it names %s, as build removes it", + (_, gateways) => { + expect(parse("box", gateways)).toEqual([]); + }, + ); + + test("is refused on a gateway without boundRuntime, which build does not write", () => { + const ordinary = front({ gateway: "gone" }, {}, "egress-foo"); + expect(parse("box", [boxGatewaySpec("agent"), ordinary])).toContainEqual( + expect.stringContaining('Target "egress-foo" of gateway "front" names the gateway "gone"'), + ); + }); + + test("is refused in a project that is not a Box project", () => { + expect(parse(undefined, [boxGateway("gone")])).toContainEqual( + expect.stringContaining('names the gateway "gone" in passthrough.gateway'), + ); + }); }); test.each([ diff --git a/src/projectSchemas/project.ts b/src/projectSchemas/project.ts index fc95819af..4852287cb 100644 --- a/src/projectSchemas/project.ts +++ b/src/projectSchemas/project.ts @@ -167,13 +167,18 @@ export const ProjectSpecSchema = z } } // A passthrough target that names a gateway calls a gateway of this project. A gateway bound to - // a runtime belongs to that runtime, so no target of another gateway calls it. Build writes - // and removes each target whose name starts with BOX_EGRESS_TARGET_PREFIX, so such a target - // that names no such gateway is not refused here: the next build removes it. + // a runtime belongs to that runtime, so no target of another gateway calls it. On the Box + // gateway of a runtime of a Box project, build writes and removes each target whose name starts + // with BOX_EGRESS_TARGET_PREFIX, so such a target that names no such gateway is not refused + // here: the next build removes it. + const buildOwns = (gateway: { boundRuntime?: string }, target: { name: string }) => + isBoxProject(spec) && + isBoundGateway(gateway) && + target.name.startsWith(BOX_EGRESS_TARGET_PREFIX); for (const gateway of spec.agentCoreGateways) { for (const target of gateway.targets) { const reached = target.passthrough?.gateway; - if (reached === undefined || target.name.startsWith(BOX_EGRESS_TARGET_PREFIX)) continue; + if (reached === undefined || buildOwns(gateway, target)) continue; const named = spec.agentCoreGateways.find((other) => other.name === reached); const problem = named === undefined From 2f55c313a954276673cd3811a290efb547d3dd9c Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 18:03:39 -0800 Subject: [PATCH 13/15] fix(box): Say why build could not check the CDK library for passthrough.gateway Review feedback: `cdkAcceptsPassthroughGateway` gave false for a library that refuses the field, and also when `node` is not there, when the check takes more than 60 seconds, and when the check fails. In each case, the warning told the user to update the library. The check now gives `PassthroughGatewayCheck`: `{ accepts: true }`, or `{ accepts: false, reason }` with the reason `refuses`, `not-installed`, `no-node`, `timed-out`, or `failed`, and for `failed` the first line of the error. The one warning of build says that reason and its fix. Build still writes no target, no server, and no pack input in each case that is not `accepts`. `cdkAcceptsPassthroughGateway` also takes `node` and `timeoutMs`, for tests. Tests that fail before this change: in `compatibility.test.ts`, one test for each answer, with a fake library, a library that throws, a library that does not stop, and a `node` that is not there; in `network.test.ts`, "gives the agent no gateway, and one warning that says why, when the check gives ..." for each reason. --- .../backends/cdk/compatibility.test.ts | 95 +++++++++++-------- .../project/backends/cdk/compatibility.ts | 68 +++++++++---- src/core/project/boxNetwork/network.test.ts | 59 +++++++++--- src/core/project/boxNetwork/network.ts | 10 +- .../project/boxNetwork/projectGateways.ts | 32 ++++++- src/core/project/boxNetworkSource.ts | 7 +- src/core/project/manager.boxNetwork.test.ts | 3 +- src/core/project/manager.tsx | 21 ++-- 8 files changed, 204 insertions(+), 91 deletions(-) diff --git a/src/core/project/backends/cdk/compatibility.test.ts b/src/core/project/backends/cdk/compatibility.test.ts index ebf394965..edbf83705 100644 --- a/src/core/project/backends/cdk/compatibility.test.ts +++ b/src/core/project/backends/cdk/compatibility.test.ts @@ -63,56 +63,75 @@ describe("cdkCompatibilityWarning", () => { }); describe("cdkAcceptsPassthroughGateway", () => { - /** A CDK app whose @aws/agentcore-cdk exports `AgentCoreGatewayTargetSchema` as `schema`, a JS text. */ - async function cdkDirectoryExporting(schema: string | undefined): Promise { + /** A CDK app whose @aws/agentcore-cdk has the module text `index`. */ + async function cdkDirectoryWithIndex(index: string | undefined): Promise { const directory = await mkdtemp(join(tmpdir(), "agentcore-cdk-passthrough-gateway-")); tempDirectories.push(directory); - if (schema === undefined) return directory; + if (index === undefined) return directory; const packageDirectory = join(directory, "node_modules", "@aws", "agentcore-cdk"); await mkdir(packageDirectory, { recursive: true }); await writeFile( join(packageDirectory, "package.json"), JSON.stringify({ name: "@aws/agentcore-cdk", version: "1.1.0", main: "index.js" }), ); - await writeFile( - join(packageDirectory, "index.js"), - `exports.AgentCoreGatewayTargetSchema = ${schema};\n`, - ); + await writeFile(join(packageDirectory, "index.js"), index); return directory; } + /** A library that exports `AgentCoreGatewayTargetSchema` as `schema`, a JS text. */ + const exporting = (schema: string) => `exports.AgentCoreGatewayTargetSchema = ${schema};\n`; /** As each @aws/agentcore-cdk parses the passthrough of a target: with `gateway`, or `endpoint` only. */ - const WITH_GATEWAY = - "{ safeParse: (target) => ({ success: typeof target.passthrough.gateway === 'string' }) }"; - const ENDPOINT_ONLY = - "{ safeParse: (target) => ({ success: typeof target.passthrough.endpoint === 'string' }) }"; - - test.skipIf(!Bun.which("node"))( - "is true when the installed library accepts passthrough.gateway", - async () => { - expect(await cdkAcceptsPassthroughGateway(await cdkDirectoryExporting(WITH_GATEWAY))).toBe( - true, - ); - }, + const WITH_GATEWAY = exporting( + "{ safeParse: (target) => ({ success: typeof target.passthrough.gateway === 'string' }) }", ); - - test.skipIf(!Bun.which("node"))( - "is false when the installed library requires passthrough.endpoint", - async () => { - expect(await cdkAcceptsPassthroughGateway(await cdkDirectoryExporting(ENDPOINT_ONLY))).toBe( - false, - ); - }, + const ENDPOINT_ONLY = exporting( + "{ safeParse: (target) => ({ success: typeof target.passthrough.endpoint === 'string' }) }", ); + const withNode = test.skipIf(!Bun.which("node")); - test.skipIf(!Bun.which("node"))( - "is false when the library is not installed, or has no AgentCoreGatewayTargetSchema", - async () => { - expect(await cdkAcceptsPassthroughGateway(await cdkDirectoryExporting(undefined))).toBe( - false, - ); - expect(await cdkAcceptsPassthroughGateway(await cdkDirectoryExporting("undefined"))).toBe( - false, - ); - }, - ); + withNode("accepts when the installed library accepts passthrough.gateway", async () => { + expect(await cdkAcceptsPassthroughGateway(await cdkDirectoryWithIndex(WITH_GATEWAY))).toEqual({ + accepts: true, + }); + }); + + withNode.each([ + ["requires passthrough.endpoint", ENDPOINT_ONLY], + ["has no AgentCoreGatewayTargetSchema", "exports.Other = 1;\n"], + ])("refuses when the installed library %s", async (_, index) => { + expect(await cdkAcceptsPassthroughGateway(await cdkDirectoryWithIndex(index))).toEqual({ + accepts: false, + reason: "refuses", + }); + }); + + withNode("says that the library is not installed", async () => { + expect(await cdkAcceptsPassthroughGateway(await cdkDirectoryWithIndex(undefined))).toEqual({ + accepts: false, + reason: "not-installed", + }); + }); + + withNode("says that the check failed, with the error of the library", async () => { + const directory = await cdkDirectoryWithIndex('throw new Error("the library is broken");\n'); + expect(await cdkAcceptsPassthroughGateway(directory)).toEqual({ + accepts: false, + reason: "failed", + detail: "the library is broken", + }); + }); + + withNode("says that the check took too long", async () => { + const directory = await cdkDirectoryWithIndex("while (true) {}\n"); + expect(await cdkAcceptsPassthroughGateway(directory, { timeoutMs: 500 })).toEqual({ + accepts: false, + reason: "timed-out", + }); + }); + + test("says that build cannot run node", async () => { + const directory = await cdkDirectoryWithIndex(WITH_GATEWAY); + expect( + await cdkAcceptsPassthroughGateway(directory, { node: "/nonexistent/agentcore-test/node" }), + ).toEqual({ accepts: false, reason: "no-node" }); + }); }); diff --git a/src/core/project/backends/cdk/compatibility.ts b/src/core/project/backends/cdk/compatibility.ts index e6123fac8..8e5f9b77d 100644 --- a/src/core/project/backends/cdk/compatibility.ts +++ b/src/core/project/backends/cdk/compatibility.ts @@ -35,34 +35,68 @@ export async function cdkCompatibilityWarning(cdkDirectory: string): Promise { +/** The answer of {@link cdkAcceptsPassthroughGateway}, with the reason when it is not `accepts`. */ +export type PassthroughGatewayCheck = + | { readonly accepts: true } + | { + readonly accepts: false; + readonly reason: "refuses" | "not-installed" | "no-node" | "timed-out" | "failed"; + readonly detail?: string; + }; + +/** + * Asks the @aws/agentcore-cdk of the CDK app in `cdkDirectory` whether it accepts + * `passthrough.gateway`. Node runs the check in that folder, so it loads the same library as synth. + * Each answer other than `accepts` says why: the library refuses the field, is not installed, the + * check took more than `timeoutMs`, `node` is not there, or the check failed. + */ +export async function cdkAcceptsPassthroughGateway( + cdkDirectory: string, + options: { readonly node?: string; readonly timeoutMs?: number } = {}, +): Promise { + let stdout: string; try { - const { stdout } = await promisify(execFile)("node", ["-e", PASSTHROUGH_GATEWAY_CHECK], { - cwd: cdkDirectory, - timeout: 60_000, - }); - return stdout.trim() === "accepts"; - } catch { - return false; + ({ stdout } = await promisify(execFile)( + options.node ?? "node", + ["-e", PASSTHROUGH_GATEWAY_CHECK], + { cwd: cdkDirectory, timeout: options.timeoutMs ?? 60_000 }, + )); + } catch (error) { + const failure = error as NodeJS.ErrnoException & { killed?: boolean; stderr?: string }; + if (failure.code === "ENOENT") return { accepts: false, reason: "no-node" }; + if (failure.killed) return { accepts: false, reason: "timed-out" }; + const detail = (failure.stderr ?? failure.message).trim().split("\n")[0]; + return { accepts: false, reason: "failed", ...(detail && { detail }) }; } + const answer = stdout.trim(); + if (answer === "accepts") return { accepts: true }; + if (answer === "refuses" || answer === "not-installed") return { accepts: false, reason: answer }; + const detail = answer.replace(/^failed\s*/, ""); + return { accepts: false, reason: "failed", ...(detail && { detail }) }; } diff --git a/src/core/project/boxNetwork/network.test.ts b/src/core/project/boxNetwork/network.test.ts index 76d0ad375..058e28df4 100644 --- a/src/core/project/boxNetwork/network.test.ts +++ b/src/core/project/boxNetwork/network.test.ts @@ -8,6 +8,7 @@ import type { AgentCoreGatewayTarget } from "../../../projectSchemas/gateway"; import { boxGatewaySpec, type ProjectSpec } from "../../../projectSchemas/project"; import type { ProjectRuntime } from "../../../projectSchemas/runtime"; import { boxNetworkRules } from "../boxProfileResolver-test-support"; +import type { PassthroughGatewayCheck } from "../backends/cdk/compatibility"; import { boxGatewayIamWarnings, buildBoxNetwork } from "./network"; import { parseResolvedPolicy } from "./policyParser"; import { profilePlaces } from "./profileParser"; @@ -49,8 +50,8 @@ interface Options { /** The other gateways of the project, after the Box gateway. */ readonly gateways?: Record[]; readonly runtime?: Partial; - /** Whether the @aws/agentcore-cdk of the project accepts `passthrough.gateway`; true here. */ - readonly projectGatewayTargets?: boolean; + /** What the check of the @aws/agentcore-cdk of the project gives; it accepts here. */ + readonly projectGatewayCheck?: PassthroughGatewayCheck; } /** The local box profile of runtime `agent`. */ @@ -102,7 +103,7 @@ function model(policy: string, egress: Record = {}, options: Op region: "us-west-2", targets: options.targets ?? [], grantedActions: options.grantedActions ?? [], - projectGatewayTargets: options.projectGatewayTargets ?? true, + projectGatewayCheck: options.projectGatewayCheck ?? { accepts: true }, }); return { spec, @@ -1226,18 +1227,46 @@ describe("the gateways of the project", () => { expect(network.failures).toEqual([]); }); - test("gives the agent no gateway when the @aws/agentcore-cdk of the project refuses passthrough.gateway, and warns once", () => { - const { network } = model("", {}, { gateways: [TOOLS, OPEN], projectGatewayTargets: false }); - - expect(network.projectGateways).toEqual([]); - expect(network.failures).toEqual([]); - expect(network.warnings).toEqual([ - "The gateways 'tools' and 'open-tools' of this project get no route for a boxed agent on " + - "AgentCore Runtime, because the @aws/agentcore-cdk in agentcore/cdk does not accept " + - "passthrough.gateway. Update @aws/agentcore-cdk in agentcore/cdk/package.json to a " + - "version that accepts it, then build again.", - ]); - }); + test.each([ + [ + { accepts: false, reason: "refuses" }, + "the @aws/agentcore-cdk in agentcore/cdk does not accept passthrough.gateway. Update " + + "@aws/agentcore-cdk in agentcore/cdk/package.json to a version that accepts it, then " + + "build again.", + ], + [ + { accepts: false, reason: "not-installed" }, + "build found no @aws/agentcore-cdk in agentcore/cdk. Run npm install in agentcore/cdk, " + + "then build again.", + ], + [ + { accepts: false, reason: "no-node" }, + "build cannot run node to check the @aws/agentcore-cdk in agentcore/cdk. Put node on " + + "PATH, then build again.", + ], + [ + { accepts: false, reason: "timed-out" }, + "the check of the @aws/agentcore-cdk in agentcore/cdk took more than 60 seconds. Build " + + "again.", + ], + [ + { accepts: false, reason: "failed", detail: "the library is broken" }, + "the check of the @aws/agentcore-cdk in agentcore/cdk failed: the library is broken. " + + "Build again.", + ], + ] as const)( + "gives the agent no gateway, and one warning that says why, when the check gives %o", + (projectGatewayCheck, why) => { + const { network } = model("", {}, { gateways: [TOOLS, OPEN], projectGatewayCheck }); + + expect(network.projectGateways).toEqual([]); + expect(network.failures).toEqual([]); + expect(network.warnings).toEqual([ + "The gateways 'tools' and 'open-tools' of this project get no route for a boxed agent " + + `on AgentCore Runtime, because ${why}`, + ]); + }, + ); test("gives a PRIVATE_VPC runtime no gateway, as the CDK library binds none to it", () => { const { network } = model( diff --git a/src/core/project/boxNetwork/network.ts b/src/core/project/boxNetwork/network.ts index b0ff649c5..f15b76524 100644 --- a/src/core/project/boxNetwork/network.ts +++ b/src/core/project/boxNetwork/network.ts @@ -31,6 +31,7 @@ import { deriveRuntimeProfile } from "../runtimeProfile/derive"; import { defaultTracesTelemetry, runtimeProfileHeader } from "../runtimeProfile/rules/additions"; import type { TomlTable } from "../runtimeProfile/types"; import { withDeployRegion, type CloudWatchTelemetry } from "./telemetry"; +import type { PassthroughGatewayCheck } from "../backends/cdk/compatibility"; import { projectGatewaysOf, type BoxProjectGateway } from "./projectGateways"; import { outboundAuthWords, sameOutboundAuth, targetOutboundAuth } from "./projectSpec"; import { @@ -167,10 +168,11 @@ export interface BoxNetworkProject { /** The IAM actions that the gateway's `additionalPolicies` files grant, except build's own. */ readonly grantedActions: readonly string[]; /** - * Whether the @aws/agentcore-cdk of the project accepts a target with `passthrough.gateway` - * (`cdkAcceptsPassthroughGateway`); absent means it does not, and no gateway gets a target. + * What the check of the @aws/agentcore-cdk of the project gives for a target with + * `passthrough.gateway` (`cdkAcceptsPassthroughGateway`). Absent means no check, and no gateway + * of the project gets a target. */ - readonly projectGatewayTargets?: boolean; + readonly projectGatewayCheck?: PassthroughGatewayCheck; } /** The Box gateway of `runtime`: the gateway bound to it. */ @@ -212,7 +214,7 @@ export function buildBoxNetwork( const reached = projectGatewaysOf( project.spec, project.runtime, - project.projectGatewayTargets ?? false, + project.projectGatewayCheck ?? { accepts: false, reason: "refuses" }, ); const targets = hostTargets(map.hosts, project, reached.gateways, located, parsed.profile.path); failures.push(...targets.failures); diff --git a/src/core/project/boxNetwork/projectGateways.ts b/src/core/project/boxNetwork/projectGateways.ts index 6bf2f4671..7a850e604 100644 --- a/src/core/project/boxNetwork/projectGateways.ts +++ b/src/core/project/boxNetwork/projectGateways.ts @@ -8,6 +8,7 @@ import { createHash } from "node:crypto"; import type { AgentCoreGatewayTarget } from "../../../projectSchemas/gateway"; import { gatewayDiscoveryPrefix, type ProjectSpec } from "../../../projectSchemas/project"; import type { ProjectRuntime } from "../../../projectSchemas/runtime"; +import type { PassthroughGatewayCheck } from "../backends/cdk/compatibility"; import { BOX_EGRESS_TARGET_PREFIX, targetNameFor } from "./egress"; /** A gateway of the project that a boxed runtime calls through its Box gateway. */ @@ -55,7 +56,7 @@ function projectGatewayTargetName(name: string): string { export function projectGatewaysOf( spec: ProjectSpec, runtime: Pick, - targets = true, + check: PassthroughGatewayCheck = { accepts: true }, ): { gateways: BoxProjectGateway[]; warnings: string[] } { const gateways: BoxProjectGateway[] = []; const warnings: string[] = []; @@ -70,15 +71,13 @@ export function projectGatewaysOf( auth: gateway.authorizerType === "AWS_IAM" ? "iam" : "none", }); } - if (!targets && gateways.length > 0) { + if (!check.accepts && gateways.length > 0) { const names = gateways.map(({ name }) => `'${name}'`); const list = names.length > 1 ? `${names.slice(0, -1).join(", ")} and ${names.at(-1)}` : names[0]; warnings.push( `The gateways ${list} of this project get no route for a boxed agent on AgentCore ` + - "Runtime, because the @aws/agentcore-cdk in agentcore/cdk does not accept " + - "passthrough.gateway. Update @aws/agentcore-cdk in agentcore/cdk/package.json to a " + - "version that accepts it, then build again.", + `Runtime, because ${uncheckedBecause(check)}`, ); return { gateways: [], warnings }; } @@ -103,6 +102,29 @@ export function projectGatewayTargetFor( }; } +/** Why build writes no gateway target, from the check of the CDK library, and how to fix it. */ +function uncheckedBecause(check: Extract): string { + const library = "the @aws/agentcore-cdk in agentcore/cdk"; + switch (check.reason) { + case "refuses": + return ( + `${library} does not accept passthrough.gateway. Update @aws/agentcore-cdk in ` + + "agentcore/cdk/package.json to a version that accepts it, then build again." + ); + case "not-installed": + return ( + "build found no @aws/agentcore-cdk in agentcore/cdk. Run npm install in agentcore/cdk, " + + "then build again." + ); + case "no-node": + return `build cannot run node to check ${library}. Put node on PATH, then build again.`; + case "timed-out": + return `the check of ${library} took more than 60 seconds. Build again.`; + case "failed": + return `the check of ${library} failed: ${check.detail ?? "no error message"}. Build again.`; + } +} + /** What `add gateway` tells the user once about a `CUSTOM_JWT` gateway in a Box project. */ export function customJwtGatewayNotice(gatewayName: string): string { return ( diff --git a/src/core/project/boxNetworkSource.ts b/src/core/project/boxNetworkSource.ts index 0cbad886d..477c3a6ab 100644 --- a/src/core/project/boxNetworkSource.ts +++ b/src/core/project/boxNetworkSource.ts @@ -12,6 +12,7 @@ import type { ProjectSpec } from "../../projectSchemas/project"; import type { ProjectRuntime } from "../../projectSchemas/runtime"; import { InvalidEnvironmentError, ProjectStateError } from "../../errors/errors"; import type { PolicyFileCopy } from "./backends/boxContainer"; +import type { PassthroughGatewayCheck } from "./backends/cdk/compatibility"; import { DEFAULT_EGRESS_BEDROCK_REGION } from "../../handlers/project/shortcuts"; import { addBoxGatewayTargets, BOX_BEDROCK_POLICY_FILE, BOX_MEMORY_POLICY_FILE } from "./boxMemory"; import { @@ -55,8 +56,8 @@ export async function readBoxNetworks( projectRoot: string, resolver: BoxProfileResolver, region: string = DEFAULT_EGRESS_BEDROCK_REGION, - /** Whether the @aws/agentcore-cdk of the project accepts `passthrough.gateway`. */ - projectGatewayTargets = false, + /** What the check of the @aws/agentcore-cdk of the project gives for `passthrough.gateway`. */ + projectGatewayCheck?: PassthroughGatewayCheck, ): Promise { const runtimes = spec.runtimes.filter((runtime) => runtimeRunsInBox(spec, runtime)); if (runtimes.length === 0) return []; @@ -86,7 +87,7 @@ export async function readBoxNetworks( region, targets: entry.targets, grantedActions: granted.actions, - projectGatewayTargets, + ...(projectGatewayCheck && { projectGatewayCheck }), }); networks.push({ ...network, diff --git a/src/core/project/manager.boxNetwork.test.ts b/src/core/project/manager.boxNetwork.test.ts index 7ffa216dc..570ce0ae0 100644 --- a/src/core/project/manager.boxNetwork.test.ts +++ b/src/core/project/manager.boxNetwork.test.ts @@ -166,7 +166,8 @@ async function strandsProject( ...options.env, }, boxProfileResolver: box, - cdkAcceptsPassthroughGateway: async () => options.acceptsPassthroughGateway ?? false, + cdkAcceptsPassthroughGateway: async () => + options.acceptsPassthroughGateway ? { accepts: true } : { accepts: false, reason: "refuses" }, ...(options.backends && { backends: options.backends }), }); const { value: created, warnings: createWarnings } = await drain( diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx index 384fb7006..570e902f6 100644 --- a/src/core/project/manager.tsx +++ b/src/core/project/manager.tsx @@ -123,7 +123,10 @@ import { import { isChinaRegion } from "../partition"; import z from "zod"; import { CdkBackend, type TransactionSearchEnabler } from "./backends/cdk"; -import { cdkAcceptsPassthroughGateway } from "./backends/cdk/compatibility"; +import { + cdkAcceptsPassthroughGateway, + type PassthroughGatewayCheck, +} from "./backends/cdk/compatibility"; import { customJwtGatewayNotice } from "./boxNetwork/projectGateways"; import { resolveAwsAccount } from "./backends/cdk/environment"; import type { ProjectBackend } from "./backends/types"; @@ -445,7 +448,7 @@ type ProjectManagerConfig = { * Whether the @aws/agentcore-cdk of the CDK app in a folder accepts a passthrough target with * `gateway`; build writes such a target only then. `cdkAcceptsPassthroughGateway` by default. */ - cdkAcceptsPassthroughGateway?: (cdkDirectory: string) => Promise; + cdkAcceptsPassthroughGateway?: (cdkDirectory: string) => Promise; backends?: Partial>; templateRenderer?: TemplateRenderer; /** @@ -470,7 +473,9 @@ export class FsProjectManager implements ProjectManager { private readonly resolveAccount: (region: string) => Promise; private readonly processEnv: NodeJS.ProcessEnv; private readonly boxProfileResolver: BoxProfileResolver; - private readonly cdkAcceptsPassthroughGateway: (cdkDirectory: string) => Promise; + private readonly cdkAcceptsPassthroughGateway: ( + cdkDirectory: string, + ) => Promise; constructor(config: ProjectManagerConfig) { this.logger = config.logger; @@ -1713,16 +1718,16 @@ export class FsProjectManager implements ProjectManager { // Only a box runtime and a gateway without boundRuntime need the check of the CDK app. const unbound = project.spec.agentCoreGateways.some(({ boundRuntime }) => !boundRuntime); const boxed = project.spec.runtimes.some((runtime) => runtimeRunsInBox(project.spec, runtime)); - const projectGatewayTargets = - unbound && - boxed && - (await this.cdkAcceptsPassthroughGateway(join(project.rootPath, "agentcore", "cdk"))); + const projectGatewayCheck = + unbound && boxed + ? await this.cdkAcceptsPassthroughGateway(join(project.rootPath, "agentcore", "cdk")) + : undefined; const networks = await readBoxNetworks( project.spec, project.rootPath, this.boxProfileResolver, region, - projectGatewayTargets, + projectGatewayCheck, ); if (networks.some(({ failures }) => failures.length > 0)) { throw new InputValidationError(boxNetworkFailureMessage(networks, command)); From 1721f474a3a40d828c131f16c1d6e60612740666 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 18:05:06 -0800 Subject: [PATCH 14/15] fix(box): Give the CUSTOM_JWT gateway notice also when add runtime adds a boxed runtime Review feedback: `customJwtGatewayNotice` came only from `add gateway`, when a boxed runtime was in the project already. A boxed runtime that `add runtime` adds after the gateway got no notice. `add runtime` now gives `customJwtGatewayNotice` after it writes agentcore.json, for each `CUSTOM_JWT` gateway without `boundRuntime`, when the new runtime runs in a box and is not `PRIVATE_VPC`. `docs/box-local-testing.md` says so. Test: in `manager.box.test.ts`, "add runtime gives the notice of each CUSTOM_JWT gateway without boundRuntime, as the new runtime is boxed" fails before this change. --- docs/box-local-testing.md | 3 ++- src/core/project/manager.box.test.ts | 31 ++++++++++++++++++++++++++++ src/core/project/manager.tsx | 12 +++++++++++ 3 files changed, 45 insertions(+), 1 deletion(-) diff --git a/docs/box-local-testing.md b/docs/box-local-testing.md index 273bb3f9d..2840af50b 100644 --- a/docs/box-local-testing.md +++ b/docs/box-local-testing.md @@ -219,7 +219,8 @@ A profile that names a pack `box/` fails: box refuses it and names the `@b the gateway's name. The L3 sets the target's endpoint to that gateway's URL, gives the Box gateway's role `bedrock-agentcore:InvokeGateway` on that gateway only, and sets `AGENTCORE_GATEWAY__URL` and `_HOST` on the runtime. A `PRIVATE_VPC` runtime gets none of - them. A `CUSTOM_JWT` gateway gets no target, and `agentcore add gateway` gives one notice for it. You write nothing for them. A profile + them. A `CUSTOM_JWT` gateway gets no target, and `agentcore add gateway`, and `agentcore add runtime` for a + box runtime, give one notice for it. You write nothing for them. A profile entry that signs for a gateway host with `aws://` stops build. Build writes these targets only when the `@aws/agentcore-cdk` in `agentcore/cdk` accepts `passthrough.gateway`: it asks that library with `node`. Otherwise build writes none of them, and gives one warning. diff --git a/src/core/project/manager.box.test.ts b/src/core/project/manager.box.test.ts index 9fe6b1320..92318231b 100644 --- a/src/core/project/manager.box.test.ts +++ b/src/core/project/manager.box.test.ts @@ -12,6 +12,7 @@ import { BOX_RELEASE } from "./backends/boxRelease"; import { boxGatewayLogsNotice, FsProjectManager } from "./manager"; import { newProjectSpec } from "./templates/project"; import { defaultLogTargetNotice } from "./runtimeProfile/rules/additions"; +import { customJwtGatewayNotice } from "./boxNetwork/projectGateways"; import { boxStartFolder } from "./templates/boxProfile"; import { boxGatewaySpec, ProjectSpecSchema } from "../../projectSchemas/project"; @@ -372,6 +373,36 @@ describe("gateway targets in a Box project", () => { expect(await specText(project)).toBe(before); }); + test("add runtime gives the notice of each CUSTOM_JWT gateway without boundRuntime, as the new runtime is boxed", async () => { + const manager = subject(); + const project = await createdProject(manager); + const spec = await specOnDisk(project); + spec.agentCoreGateways.push({ + name: "secure", + authorizerType: "CUSTOM_JWT", + authorizerConfiguration: { + customJwtAuthorizer: { + discoveryUrl: "https://idp.example.com/.well-known/openid-configuration", + allowedAudience: ["agentcore"], + }, + }, + protocolType: "MCP", + targets: [], + } as never); + await writeFile(join(project.rootPath, "agentcore", "agentcore.json"), JSON.stringify(spec)); + + const warnings: string[] = []; + const generator = manager.addResource(project, { + resourceType: "runtime", + resourceConfig: { name: "search", language: "Python", protocol: "HTTP" }, + } as never); + for (let next = await generator.next(); !next.done; next = await generator.next()) { + if (next.value.type === "warning") warnings.push(next.value.message); + } + + expect(warnings).toContain(customJwtGatewayNotice("secure")); + }); + test("add runtime gives the new runtime a box, its Box gateway, and its own box profile", async () => { const manager = subject(); const project = await createdProject(manager); diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx index 570e902f6..75710c1f5 100644 --- a/src/core/project/manager.tsx +++ b/src/core/project/manager.tsx @@ -1133,6 +1133,18 @@ export class FsProjectManager implements ProjectManager { yield* boxGatewayLogsWarnings( newProjectSpec.agentCoreGateways.filter(({ boundRuntime }) => boundRuntime === added), ); + // A new boxed runtime cannot call a CUSTOM_JWT gateway that is in the project already. + const runtime = newProjectSpec.runtimes.find(({ name }) => name === added); + if ( + runtime && + runtimeRunsInBox(newProjectSpec, runtime) && + runtime.containment !== "PRIVATE_VPC" + ) { + for (const gateway of newProjectSpec.agentCoreGateways) { + if (gateway.boundRuntime || gateway.authorizerType !== "CUSTOM_JWT") continue; + yield { type: "warning", message: customJwtGatewayNotice(gateway.name) }; + } + } } return { From 33c29a1c0d1e095e801df9de4c8708331d9320c6 Mon Sep 17 00:00:00 2001 From: Sai Abhishek Date: Fri, 20 Nov 2026 18:15:16 -0800 Subject: [PATCH 15/15] docs(box): Name the check parameter and add runtime in the comments of projectGateways.ts (comment of Leo on projectGateways.ts line 53) --- src/core/project/boxNetwork/projectGateways.ts | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/src/core/project/boxNetwork/projectGateways.ts b/src/core/project/boxNetwork/projectGateways.ts index 7a850e604..256ad6197 100644 --- a/src/core/project/boxNetwork/projectGateways.ts +++ b/src/core/project/boxNetwork/projectGateways.ts @@ -50,8 +50,9 @@ function projectGatewayTargetName(name: string): string { * The gateways of `spec` that `runtime` calls through its Box gateway: each gateway without * `boundRuntime`, as the CDK library binds it to a runtime without a box. A `PRIVATE_VPC` runtime * gets none, and no `CUSTOM_JWT` gateway, because the Box gateway cannot get its token; - * `add gateway` gives {@link customJwtGatewayNotice} for it once. With `targets` false, because the @aws/agentcore-cdk of the project refuses - * `passthrough.gateway`, the runtime gets none, and one warning names them. + * `add gateway` or `add runtime` gives {@link customJwtGatewayNotice} for it once. When `check` + * does not accept `passthrough.gateway`, the runtime gets none, and one warning names them and says + * why. */ export function projectGatewaysOf( spec: ProjectSpec, @@ -125,7 +126,7 @@ function uncheckedBecause(check: Extract