diff --git a/docs/box-local-testing.md b/docs/box-local-testing.md index 5b147d5fb..2840af50b 100644 --- a/docs/box-local-testing.md +++ b/docs/box-local-testing.md @@ -213,6 +213,17 @@ 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 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. - **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,13 +252,18 @@ 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; - with `instrumentation.enableOtel` on, which is the default for a box template too, a command of the Python of the venv starts with `opentelemetry-instrument`. On CodeZip, the Python of the Runtime runs the script in the zip, `/bin/opentelemetry-instrument`. The `@box/agentcore` pack gives the agent the ADOT variables and the `OTEL_RESOURCE_ATTRIBUTES` that the Runtime sets. When your `[agent.env]` sets one of these variables, box uses your value. - The pack sets no `OTEL_EXPORTER_OTLP_*` variable, because box sets each one. + The pack sets no `OTEL_EXPORTER_OTLP_*` variable, because box sets each one; + - 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 @@ -286,7 +302,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/backends/cdk/compatibility.test.ts b/src/core/project/backends/cdk/compatibility.test.ts index 706562788..edbf83705 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,77 @@ describe("cdkCompatibilityWarning", () => { expect(await cdkCompatibilityWarning(directory)).toBeUndefined(); }); }); + +describe("cdkAcceptsPassthroughGateway", () => { + /** 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 (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"), 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 = exporting( + "{ safeParse: (target) => ({ success: typeof target.passthrough.gateway === 'string' }) }", + ); + const ENDPOINT_ONLY = exporting( + "{ safeParse: (target) => ({ success: typeof target.passthrough.endpoint === 'string' }) }", + ); + const withNode = test.skipIf(!Bun.which("node")); + + 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 3e56bf0b0..8e5f9b77d 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,70 @@ export async function cdkCompatibilityWarning(cdkDirectory: string): Promise { + let stdout: string; + try { + ({ 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/boxMemory.ts b/src/core/project/boxMemory.ts index fe0533d70..4a91d4a76 100644 --- a/src/core/project/boxMemory.ts +++ b/src/core/project/boxMemory.ts @@ -270,7 +270,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..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"; @@ -132,6 +133,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. */ @@ -154,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 @@ -191,6 +194,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 04e2b6dc9..058e28df4 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, @@ -7,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"; @@ -45,6 +47,11 @@ 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; + /** 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`. */ @@ -56,10 +63,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 +76,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,11 +98,12 @@ 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 ?? [], grantedActions: options.grantedActions ?? [], + projectGatewayCheck: options.projectGatewayCheck ?? { accepts: true }, }); return { spec, @@ -1190,3 +1200,238 @@ 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.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( + "", + {}, + { gateways: [TOOLS], runtime: { containment: "PRIVATE_VPC" } }, + ); + + expect(network.projectGateways).toEqual([]); + }); + + 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).toEqual([]); + }); + + 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( + "", + { "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 b23cbc380..f15b76524 100644 --- a/src/core/project/boxNetwork/network.ts +++ b/src/core/project/boxNetwork/network.ts @@ -31,6 +31,8 @@ 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 { MAX_GATEWAY_TARGETS, @@ -117,6 +119,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. @@ -160,6 +167,12 @@ 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[]; + /** + * 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 projectGatewayCheck?: PassthroughGatewayCheck; } /** The Box gateway of `runtime`: the gateway bound to it. */ @@ -198,7 +211,12 @@ 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, + project.projectGatewayCheck ?? { accepts: false, reason: "refuses" }, + ); + const targets = hostTargets(map.hosts, project, reached.gateways, located, parsed.profile.path); failures.push(...targets.failures); const telemetry = parsed.profile.telemetry && @@ -213,6 +231,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, }); @@ -231,6 +250,7 @@ export function buildBoxNetwork( region: project.region, hosts: targets.hosts, envRoutes: envRoutesOf(targets.hosts), + projectGateways: reached.gateways, policyFiles: parsed.profile.policyFiles, ...(sent && { telemetry: sent }), ...(derived && @@ -249,6 +269,7 @@ export function buildBoxNetwork( ); }), ...(telemetry?.warnings ?? []), + ...reached.warnings, ...(derived?.warnings ?? []), ], failures, @@ -278,7 +299,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; } @@ -327,6 +348,7 @@ function duplicateRule( function hostTargets( mapped: readonly MappedHost[], project: BoxNetworkProject, + gateways: readonly BoxProjectGateway[], located: (failure: ConversionFailure) => BoxNetworkFailure, profilePath: string, ): { hosts: BoxNetworkHost[]; failures: BoxNetworkFailure[] } { @@ -450,6 +472,23 @@ 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) => 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]!)); @@ -474,13 +513,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, }); } @@ -514,7 +559,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 = { @@ -540,7 +588,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 ( @@ -650,13 +698,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..cda03138f --- /dev/null +++ b/src/core/project/boxNetwork/projectGateways.test.ts @@ -0,0 +1,179 @@ +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 { + projectGatewaysOf, + 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, + ); + }); +}); + +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"], + ["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); + 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 }))); +}); + +/** 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"; + +/** 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", () => { + // 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"); + 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, { name: "agent", instrumentation: { enableOtel: false } }, [ + gateway, + ]), + ); + 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: [gateway], + 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, + [`${gateway.variablePrefix}_URL`]: `https://${HOST}/mcp`, + [`${gateway.variablePrefix}_HOST`]: HOST, + }, + }, + ); + expect(run.stderr.toString()).toBe(""); + const shown = JSON.parse(run.stdout.toString()) as { + box_toml: { + agent: { env: Record }; + mcp: Record; + }; + policy: string; + }; + 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[`${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) };`, + ); + }, + 120_000, + ); +}); diff --git a/src/core/project/boxNetwork/projectGateways.ts b/src/core/project/boxNetwork/projectGateways.ts new file mode 100644 index 000000000..256ad6197 --- /dev/null +++ b/src/core/project/boxNetwork/projectGateways.ts @@ -0,0 +1,144 @@ +/** + * 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 { 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. */ +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 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 + * gets none, and no `CUSTOM_JWT` gateway, because the Box gateway cannot get its token; + * `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, + runtime: Pick, + check: PassthroughGatewayCheck = { accepts: true }, +): { 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") continue; + gateways.push({ + name: gateway.name, + target: projectGatewayTargetName(gateway.name), + variablePrefix: gatewayDiscoveryPrefix(gateway), + auth: gateway.authorizerType === "AWS_IAM" ? "iam" : "none", + }); + } + 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 ${uncheckedBecause(check)}`, + ); + return { gateways: [], warnings }; + } + 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 }, + }), + }; +} + +/** 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` or `add runtime` 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; + readonly host: string; +} { + return { url: `gateways.${gateway.name}.url`, host: `gateways.${gateway.name}.host` }; +} diff --git a/src/core/project/boxNetworkSource.ts b/src/core/project/boxNetworkSource.ts index 0b18cb0c2..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,6 +56,8 @@ export async function readBoxNetworks( projectRoot: string, resolver: BoxProfileResolver, region: string = DEFAULT_EGRESS_BEDROCK_REGION, + /** 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 []; @@ -84,6 +87,7 @@ export async function readBoxNetworks( region, targets: entry.targets, grantedActions: granted.actions, + ...(projectGatewayCheck && { projectGatewayCheck }), }); networks.push({ ...network, diff --git a/src/core/project/boxNetworkWriters.test.ts b/src/core/project/boxNetworkWriters.test.ts index c1d957ba7..e502706d0 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" }]; @@ -501,6 +568,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 9a2d48c88..de575ae6f 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); @@ -408,7 +434,10 @@ export function runtimeProfileWriter(staged: readonly StagedRuntime[]): BoxNetwo const entry = spec.runtimes.find(({ name }) => name === runtime) ?? { name: runtime }; return [ { path: `${dist}/profile.toml`, text: runtimeProfileText(runtime, network, spec) }, - { path: `${dist}/${AGENTCORE_PACK_PATH}`, text: renderAgentCorePack(spec, entry) }, + { + path: `${dist}/${AGENTCORE_PACK_PATH}`, + text: renderAgentCorePack(spec, entry, network?.projectGateways), + }, ...(kind === "codezip" ? [ { 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.boxNetwork.test.ts b/src/core/project/manager.boxNetwork.test.ts index 9dff64eb3..570ce0ae0 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,8 @@ async function strandsProject( ...options.env, }, boxProfileResolver: box, + cdkAcceptsPassthroughGateway: async () => + options.acceptsPassthroughGateway ? { accepts: true } : { accepts: false, reason: "refuses" }, ...(options.backends && { backends: options.backends }), }); const { value: created, warnings: createWarnings } = await drain( @@ -640,6 +647,142 @@ 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("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("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("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); + + 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 480709beb..75710c1f5 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"; @@ -72,6 +72,7 @@ import { observabilityOff, renderBoxProfile, runsInBox, + runtimeRunsInBox, startsInBoxOnCodeZip, } from "./templates/boxProfile"; import { defaultLogTargetNotice } from "./runtimeProfile/rules/additions"; @@ -122,6 +123,11 @@ import { import { isChinaRegion } from "../partition"; import z from "zod"; import { CdkBackend, type TransactionSearchEnabler } from "./backends/cdk"; +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"; import { @@ -438,6 +444,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; /** @@ -462,6 +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; constructor(config: ProjectManagerConfig) { this.logger = config.logger; @@ -486,6 +500,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 { @@ -1094,6 +1110,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; @@ -1104,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 { @@ -1251,6 +1292,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) { @@ -1670,11 +1727,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 projectGatewayCheck = + unbound && boxed + ? await this.cdkAcceptsPassthroughGateway(join(project.rootPath, "agentcore", "cdk")) + : undefined; const networks = await readBoxNetworks( project.spec, project.rootPath, this.boxProfileResolver, region, + projectGatewayCheck, ); if (networks.some(({ failures }) => failures.length > 0)) { throw new InputValidationError(boxNetworkFailureMessage(networks, command)); @@ -1722,10 +1787,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 })), diff --git a/src/core/project/runtimeProfile/rules/gateway.test.ts b/src/core/project/runtimeProfile/rules/gateway.test.ts index 585b2e30d..97f452d87 100644 --- a/src/core/project/runtimeProfile/rules/gateway.test.ts +++ b/src/core/project/runtimeProfile/rules/gateway.test.ts @@ -707,3 +707,68 @@ 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("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`; + + 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..452f408f7 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 (Object.hasOwn(mcp, gateway.name)) { + 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 777c650b5..89d177b19 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; @@ -72,6 +73,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; @@ -98,6 +101,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 abebfc965..13dd27acd 100644 --- a/src/core/project/templates/boxProfile.test.ts +++ b/src/core/project/templates/boxProfile.test.ts @@ -411,6 +411,68 @@ 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, + { name: "agent", instrumentation: { enableOtel: false } }, + [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 }}", + }); + }); + + 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], + ["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], + [`https://${CHINA_HOST}/mcp`, 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 724cc560b..36e675899 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, 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([.]cn)?"; +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]+"; @@ -655,12 +665,16 @@ const RUNTIME_RESOURCE_ATTRIBUTES_ENV = "OTEL_RESOURCE_ATTRIBUTES"; * {@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. With OTEL on for `runtime`, * the agent gets {@link AGENT_OTEL_ENV} and the Runtime's resource attributes, so the console links - * its spans to the runtime; the profile merges after the pack, so a value of the user wins. box - * finds the pack beside its binary at {@link AGENTCORE_PACK_PATH}; build and deploy stage it there. + * its spans to the runtime; the profile merges after the pack, so a value of the user wins. 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, runtime: Pick, + gateways: readonly BoxProjectGateway[] = [], ): string { const otel = otelOn(runtime); const memories = spec.memories ?? []; @@ -693,7 +707,30 @@ description = "The OpenTelemetry resource attributes of the runtime." from = ${str(`env:${RUNTIME_RESOURCE_ATTRIBUTES_ENV}`)} default = ${str(`service.name=${runtime.name}`)}` : ""; - const env = [memoryEnv, otelEnv].filter((lines) => lines !== "").join("\n"); + 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} }}`)}`, + ) + .join("\n"); + const env = [memoryEnv, otelEnv, gatewayEnv].filter((lines) => lines !== "").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}. @@ -732,7 +769,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}${otelInput} +default = "http://localhost:9000/"${memoryInputs}${otelInput}${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..9ce82c0be 100644 --- a/src/projectSchemas/project.test.ts +++ b/src/projectSchemas/project.test.ts @@ -555,6 +555,104 @@ describe("gateway boundRuntime and discoveryPrefix", () => { }); }); +describe("a passthrough target that names a gateway", () => { + 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" }, + }); + 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?: string, + ) => ({ + name: "front", + authorizerType: "AWS_IAM", + protocolType: "None", + targets: [target(passthrough, name)], + ...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)); + }); + + 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([ + ["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..4852287cb 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"; /** @@ -161,6 +166,36 @@ 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. 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 || buildOwns(gateway, target)) 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)) {