diff --git a/src/core/project/backends/cdk.test.ts b/src/core/project/backends/cdk.test.ts index d405690c4..8466da265 100644 --- a/src/core/project/backends/cdk.test.ts +++ b/src/core/project/backends/cdk.test.ts @@ -1603,6 +1603,174 @@ describe("CdkBackend.resolveProjectResources", () => { expect(subject.accountCredentials).toEqual([]); }); + /** Each gateway's targets as `[gateway, [[target, id]...]]`; a target with no id has none. */ + const gatewayTargetIds = (resources: ResolvedProjectResource[]) => + resources + .filter(({ resourceType }) => resourceType === "gateway") + .map(({ name, children }) => [ + name, + (children ?? []).map((child) => [ + child.name, + child.deploymentState === "deployed" && "id" in child ? child.id : undefined, + ]), + ]); + + const ONE = boxGatewaySpec("agent").name; + const TWO = boxGatewaySpec("second_agent").name; + /** A gateway and its target names; a deployed gateway, the target id exports, and the ids expected. */ + test.each([ + { + title: "a target name that two gateways share gets the id of its own gateway", + gateways: [ + [ONE, ["bedrock", "egress-github"]], + [TWO, ["bedrock"]], + ], + deployed: [ONE, TWO], + exports: { + [`${ONE}:bedrock`]: "bedrock-of-one", + [`${TWO}:bedrock`]: "bedrock-of-two", + "egress-github": "github-of-one", + }, + expected: [ + [ + ONE, + [ + ["bedrock", "bedrock-of-one"], + ["egress-github", "github-of-one"], + ], + ], + [TWO, [["bedrock", "bedrock-of-two"]]], + ], + }, + { + title: "the target of one gateway gets the export name without the gateway", + gateways: [[ONE, ["bedrock"]]], + deployed: [ONE], + exports: { bedrock: "bedrock-1" }, + expected: [[ONE, [["bedrock", "bedrock-1"]]]], + }, + { + title: + "a target name with a hyphen does not take the id of a gateway and target joined by a hyphen", + gateways: [ + ["a", ["b"]], + ["tools", ["a-b"]], + ], + deployed: ["a", "tools"], + exports: { b: "b-of-a", "a-b": "a-b-of-tools" }, + expected: [ + ["a", [["b", "b-of-a"]]], + ["tools", [["a-b", "a-b-of-tools"]]], + ], + }, + { + title: "a target of one gateway does not take the id of a target named after the gateway", + gateways: [["tools", ["search", "tools-search"]]], + deployed: ["tools"], + exports: { search: "search-1", "tools-search": "tools-search-1" }, + expected: [ + [ + "tools", + [ + ["search", "search-1"], + ["tools-search", "tools-search-1"], + ], + ], + ], + }, + { + title: + "a shared target name with a hyphen does not give its id to the target of another gateway", + gateways: [ + ["a", ["b-c"]], + ["x", ["b-c"]], + ["a-b", ["c"]], + ], + deployed: ["a", "x", "a-b"], + exports: { "a:b-c": "b-c-of-a", "x:b-c": "b-c-of-x", c: "c-of-a-b" }, + expected: [ + ["a", [["b-c", "b-c-of-a"]]], + ["x", [["b-c", "b-c-of-x"]]], + ["a-b", [["c", "c-of-a-b"]]], + ], + }, + { + title: + "a shared target name of a gateway with an underscore gets the export name with a hyphen", + gateways: [ + ["my_tools", ["search"]], + ["other", ["search"]], + ], + deployed: ["my_tools", "other"], + exports: { "my-tools:search": "search-of-my-tools", "other:search": "search-of-other" }, + expected: [ + ["my_tools", [["search", "search-of-my-tools"]]], + ["other", [["search", "search-of-other"]]], + ], + }, + { + title: + "a target name that two gateways share gives no id while the stack has only the export without the gateway", + gateways: [ + [ONE, ["bedrock"]], + [TWO, ["bedrock"]], + ], + deployed: [ONE], + exports: { bedrock: "bedrock-of-one" }, + expected: [ + [ONE, [["bedrock", undefined]]], + [TWO, [["bedrock", undefined]]], + ], + }, + { + title: + "a target of a gateway that is not deployed gives no id, also when an export has its name", + gateways: [ + [ONE, ["bedrock"]], + [TWO, ["egress-github"]], + ], + deployed: [ONE], + exports: { bedrock: "bedrock-of-one", "egress-github": "github-of-a-previous-deploy" }, + expected: [ + [ONE, [["bedrock", "bedrock-of-one"]]], + [TWO, [["egress-github", undefined]]], + ], + }, + ] as { + title: string; + gateways: [string, string[]][]; + deployed: string[]; + exports: Record; + expected: [string, [string, string | undefined][]][]; + }[])("$title", async ({ gateways, deployed, exports, expected }) => { + const input = await project(); + input.spec = { + ...input.spec, + agentCoreGateways: gateways.map(([name, targets]) => ({ + name, + targets: targets.map((target) => ({ name: target })), + })), + } as unknown as typeof input.spec; + await updateTargetState(json, input.rootPath, TARGET.name, { stackArn: STACK_ARN }); + const subject = harness({ + describedStack: { + StackName: S, + CreationTime: new Date(0), + StackStatus: "CREATE_COMPLETE", + Outputs: [ + ...deployed.map((gateway) => + out(`${S}-Gateway-${gateway.replace(/_/g, "-")}-Arn`, `arn:gateway/${gateway}`), + ), + ...Object.entries(exports).map(([name, id]) => out(`${S}-GatewayTarget-${name}-Id`, id)), + ], + }, + }); + + const resources = await subject.backend.resolveProjectResources(input, { target: TARGET }); + + expect(gatewayTargetIds(resources)).toEqual(expected); + }); + test("nests a gateway's targets under the gateway", async () => { const input = await project(); input.spec = { diff --git a/src/core/project/backends/cdk.ts b/src/core/project/backends/cdk.ts index 06bf27cd1..ea65fd5ad 100644 --- a/src/core/project/backends/cdk.ts +++ b/src/core/project/backends/cdk.ts @@ -654,6 +654,14 @@ export class CdkBackend implements ProjectBackend { const asArn = (value: string | undefined) => (value ? { arn: value } : undefined); const asId = (value: string | undefined) => (value ? { id: value } : undefined); + // The L3 joins a target name that two or more gateways have to its gateway with a colon. + const gatewaysByTargetName = new Map(); + for (const gateway of spec.agentCoreGateways) { + for (const name of new Set((gateway.targets ?? []).map((target) => target.name))) { + gatewaysByTargetName.set(name, (gatewaysByTargetName.get(name) ?? 0) + 1); + } + } + const identifierOf = ( resourceType: DeployableResource, name: string, @@ -675,8 +683,12 @@ export class CdkBackend implements ProjectBackend { case "gateway": return asArn(byExportName("Gateway", name, "Arn")); case "gateway-target": - // The L3 exports an id for targets and never an ARN - return asId(byExportName("GatewayTarget", name, "Id")); + // The L3 exports an id for targets and never an ARN. + return asId( + (gatewaysByTargetName.get(name) ?? 0) > 1 + ? byExportName("GatewayTarget", `${owner ?? ""}:${name}`, "Id") + : byExportName("GatewayTarget", name, "Id"), + ); case "policy": // ExportName: -Policy---Arn return asArn(byExportName("Policy", owner ?? "", name, "Arn")); @@ -742,13 +754,21 @@ export class CdkBackend implements ProjectBackend { ...spec.credentials.map(({ name }) => resolve("credential", name)), ...spec.evaluators.map(({ name }) => resolve("evaluator", name)), ...spec.onlineEvalConfigs.map(({ name }) => resolve("online-eval", name)), - ...spec.agentCoreGateways.map((gateway) => - resolve("gateway", gateway.name, { + ...spec.agentCoreGateways.map((gateway) => { + // A target of a gateway that is not deployed has no id, even when an export has its name. + const deployed = identifierOf("gateway", gateway.name) !== undefined; + return resolve("gateway", gateway.name, { children: (gateway.targets ?? []).map(({ name }) => - resolve("gateway-target", name, { owner: gateway.name }), + deployed + ? resolve("gateway-target", name, { owner: gateway.name }) + : { + resourceType: "gateway-target" as const, + name, + deploymentState: "local-only" as const, + }, ), - }), - ), + }); + }), ...spec.policyEngines.map((engine) => resolve("policy-engine", engine.name, { children: (engine.policies ?? []).map(({ name }) => diff --git a/src/core/project/manager.box.test.ts b/src/core/project/manager.box.test.ts index cf5d01099..9fe6b1320 100644 --- a/src/core/project/manager.box.test.ts +++ b/src/core/project/manager.box.test.ts @@ -9,7 +9,7 @@ import type { AddResourceInput, Project } from "../../handlers/project/types"; import { resolveRuntimeTemplateShortcut } from "../../handlers/project/shortcuts"; import { createSilentLogger, TestIdentityClient } from "../../testing"; import { BOX_RELEASE } from "./backends/boxRelease"; -import { FsProjectManager } from "./manager"; +import { boxGatewayLogsNotice, FsProjectManager } from "./manager"; import { newProjectSpec } from "./templates/project"; import { defaultLogTargetNotice } from "./runtimeProfile/rules/additions"; import { boxStartFolder } from "./templates/boxProfile"; @@ -44,6 +44,18 @@ function subject(json?: ReadWriteJson): FsProjectManager { }); } +/** A JSON reader and writer that refuses each write of `specFile`, for each user, root too. */ +function refusingSpecWrites(specFile: string): ReadWriteJson { + const files = new FsReadWriteJson({ logger: createSilentLogger() }); + return { + read: (path, schema) => files.read(path, schema), + write: async (path, data) => { + if (path === specFile) throw new Error(`the test refuses the write of ${path}`); + return files.write(path, data); + }, + }; +} + async function drain(generator: AsyncGenerator): Promise { while (true) { const next = await generator.next(); @@ -202,14 +214,18 @@ describe("agentcore create", () => { tempDirectories.push(directory); process.chdir(directory); - const project = await drain( - manager.create({ - name: "example", - skipInstall: true, - skipGit: true, - scaffoldRuntimeInput: resolveRuntimeTemplateShortcut(template, { runtimeName: "agent" }), - }), - ); + const warnings: string[] = []; + const generator = manager.create({ + name: "example", + skipInstall: true, + skipGit: true, + scaffoldRuntimeInput: resolveRuntimeTemplateShortcut(template, { runtimeName: "agent" }), + }); + let next = await generator.next(); + for (; !next.done; next = await generator.next()) { + if (next.value.type === "warning") warnings.push(next.value.message); + } + const project = next.value; // Only a box template runs its agent in a box, so only it makes a Box project. const spec = await specOnDisk(project); @@ -217,6 +233,7 @@ describe("agentcore create", () => { expect((spec.agentCoreGateways ?? []).map(({ name }) => name)).toEqual( projectType ? ["agent-box-egress"] : [], ); + expect(warnings.includes(boxGatewayLogsNotice("agent-box-egress"))).toBe(projectType === "box"); }); test('a Box template writes "projectType": "box" and a Box gateway for each runtime', () => { @@ -236,6 +253,7 @@ describe("agentcore create", () => { protocolType: "None", boundRuntime: "my_agent", discoveryPrefix: "AGENTCORE_GATEWAY_BOX", + enableApplicationLogs: true, targets: [], }); }); @@ -399,6 +417,24 @@ describe("gateway targets in a Box project", () => { ]); }); + test("add runtime says that the new Box gateway sends its logs, and how to stop them", async () => { + const manager = subject(); + const project = await createdProject(manager); + + 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()) { + const event = next.value as { type: string; message?: string }; + if (event.type === "warning") warnings.push(event.message!); + } + + const notices = warnings.filter((warning) => warning.includes("APPLICATION_LOGS")); + expect(notices).toEqual([boxGatewayLogsNotice(boxGatewaySpec("search").name)]); + }); + test("add runtime refuses a Bedrock Agent import in a Box project, and changes nothing", async () => { const manager = subject(); const project = await createdProject(manager); @@ -592,16 +628,7 @@ describe("gateway targets in a Box project", () => { test("a failed write of agentcore.json gives no notice of the default log target", async () => { const project = await createdProject(subject()); const specFile = join(project.rootPath, "agentcore", "agentcore.json"); - // The write of agentcore.json fails for each user, root too; each other file is written. - const files = new FsReadWriteJson({ logger: createSilentLogger() }); - const json: ReadWriteJson = { - read: (path, schema) => files.read(path, schema), - write: async (path, data) => { - if (path === specFile) throw new Error(`the test refuses the write of ${path}`); - return files.write(path, data); - }, - }; - const generator = subject(json).addResource(project, { + const generator = subject(refusingSpecWrites(specFile)).addResource(project, { resourceType: "runtime", resourceConfig: { name: "search", language: "Python", protocol: "HTTP" }, } as never); @@ -617,6 +644,30 @@ describe("gateway targets in a Box project", () => { expect(events.some((event) => (event as { type?: string }).type === "warning")).toBe(false); }); + test("a failed write of agentcore.json gives no notice that the new Box gateway sends its logs", async () => { + const project = await createdProject(subject()); + const specFile = join(project.rootPath, "agentcore", "agentcore.json"); + const before = await specText(project); + const generator = subject(refusingSpecWrites(specFile)).addResource(project, { + resourceType: "runtime", + resourceConfig: { name: "search", language: "Python", protocol: "HTTP" }, + } as never); + const messages: (string | undefined)[] = []; + + await expect( + (async () => { + for (let next = await generator.next(); !next.done; next = await generator.next()) { + messages.push((next.value as { message?: string }).message); + } + })(), + ).rejects.toThrow(`the test refuses the write of ${specFile}`); + // The add wrote the box profile of the new runtime, and then the write of agentcore.json failed. + const profile = join(project.rootPath, ".box", "search", "local", "profile.toml"); + expect(messages).toContain(`writing box profile ${profile}`); + expect(messages).not.toContain(boxGatewayLogsNotice(boxGatewaySpec("search").name)); + expect(await specText(project)).toBe(before); + }); + test("add runtime warns when the kept box profile is for another protocol", async () => { const manager = subject(); let project = await createdProject(manager, ["agent", "search"]); diff --git a/src/core/project/manager.boxNetwork.test.ts b/src/core/project/manager.boxNetwork.test.ts index 8916890df..006c052d4 100644 --- a/src/core/project/manager.boxNetwork.test.ts +++ b/src/core/project/manager.boxNetwork.test.ts @@ -13,7 +13,7 @@ import type { DeployBackendInput, ProjectBackend } from "./backends/types"; import { boxShowOf, FakeBoxProfileResolver } from "./boxProfileResolver-test-support"; import type { ResolvedBoxProfile } from "./boxProfileResolver"; import { seedBoxCache } from "./backends/box-release-test-support"; -import { FsProjectManager } from "./manager"; +import { boxGatewayLogsNotice, FsProjectManager } from "./manager"; /** The golden files of this suite; `RECORD=1 bun test ` rewrites them, with no AWS call. */ const FIXTURES = join(import.meta.dir, "__fixtures__"); @@ -163,7 +163,7 @@ async function strandsProject( boxProfileResolver: box, ...(options.backends && { backends: options.backends }), }); - const { value: created } = await drain( + const { value: created, warnings: createWarnings } = await drain( manager.create({ name: "demo", scaffoldRuntimeInput: resolveRuntimeTemplateShortcut("agent-python-strands-box", { @@ -176,7 +176,7 @@ async function strandsProject( const root = created.rootPath; await mkdir(join(root, "agentcore", "cdk", "node_modules"), { recursive: true }); counter.specWrites = 0; - return { manager, root, counter, box }; + return { manager, root, counter, box, createWarnings }; } const path = (root: string, relative: string) => join(root, ...relative.split("/")); @@ -206,6 +206,7 @@ async function boxGateway(root: string) { const spec = JSON.parse(await text(root, SPEC)); return spec.agentCoreGateways.find(({ name }: { name: string }) => name === GATEWAY) as { targets: Record[]; + enableApplicationLogs?: boolean; }; } @@ -312,6 +313,34 @@ describe("build writes the Box network of the box profile", () => { expect(Object.keys(await boxGateway(root))).not.toContain("enableSemanticSearch"); }); + test("create says that the Box gateway sends its logs, and how to stop them", async () => { + const { createWarnings } = await strandsProject(); + + expect(createWarnings).toContain(boxGatewayLogsNotice(GATEWAY)); + }); + + test("keeps the enableApplicationLogs of the Box gateway as the user wrote it", async () => { + const { manager, root, box } = await strandsProject({ env: { GITHUB_TOKEN: "ghp_123" } }); + await editProfile(root, { tables: GITHUB_ROUTE }); + box.answer = shows({ github: GITHUB }); + expect((await boxGateway(root)).enableApplicationLogs).toBe(true); + + await editGateway(root, (gateway) => Object.assign(gateway, { enableApplicationLogs: false })); + await build(manager, root); + expect(await targetNames(root)).toContain("egress-github"); + expect((await boxGateway(root)).enableApplicationLogs).toBe(false); + + await editGateway(root, (gateway) => { + delete (gateway as { enableApplicationLogs?: boolean }).enableApplicationLogs; + }); + const profile = await text(root, PROFILE); + await writeFile(path(root, PROFILE), profile.replace(GITHUB_ROUTE, "")); + box.answer = shows(); + await build(manager, root); + expect(await targetNames(root)).not.toContain("egress-github"); + expect("enableApplicationLogs" in (await boxGateway(root))).toBe(false); + }); + test("writes no target for an env:// route whose key build cannot find, and says what to set", async () => { const { manager, root, box } = await strandsProject(); await editProfile(root, { tables: GITHUB_ROUTE }); diff --git a/src/core/project/manager.tsx b/src/core/project/manager.tsx index 1fc546099..d7c3b9bbe 100644 --- a/src/core/project/manager.tsx +++ b/src/core/project/manager.tsx @@ -632,6 +632,7 @@ export class FsProjectManager implements ProjectManager { ); } yield* defaultLogTargetNotices(project.spec, project.spec.runtimes); + if (isBoxProject(project.spec)) yield* boxGatewayLogsWarnings(project.spec.agentCoreGateways); return project; } @@ -1094,9 +1095,13 @@ export class FsProjectManager implements ProjectManager { } // 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; yield* defaultLogTargetNotices( newProjectSpec, - newProjectSpec.runtimes.filter(({ name }) => name === input.resourceConfig.name), + newProjectSpec.runtimes.filter(({ name }) => name === added), + ); + yield* boxGatewayLogsWarnings( + newProjectSpec.agentCoreGateways.filter(({ boundRuntime }) => boundRuntime === added), ); } @@ -2376,6 +2381,28 @@ function isInside(path: string, dir: string): boolean { ); } +/** What the CLI tells the user about the `APPLICATION_LOGS` of a Box gateway that it writes. */ +export function boxGatewayLogsNotice(gatewayName: string): string { + return ( + `the Box gateway '${gatewayName}' sends its APPLICATION_LOGS to CloudWatch Logs, which keeps ` + + "them for 90 days. They can hold the request and response bodies of its calls, prompts and " + + `completions included. To stop them, set "enableApplicationLogs": false on that gateway in ` + + "agentcore/agentcore.json" + ); +} + +/** + * A warning for each gateway of `gateways` that is a Box gateway and sends its `APPLICATION_LOGS`. + * Each command that writes a new Box gateway gives these warnings: `create` and `add runtime`. + */ +function boxGatewayLogsWarnings( + gateways: readonly { name: string; boundRuntime?: string; enableApplicationLogs?: boolean }[], +): ProjectEvent[] { + return gateways + .filter((gateway) => isBoundGateway(gateway) && gateway.enableApplicationLogs) + .map((gateway) => ({ type: "warning", message: boxGatewayLogsNotice(gateway.name) })); +} + /** The strands-agents requirement from the rendered pyproject.toml, for EXPORT_NOTES.md. */ async function readStrandsVersion(agentDir: string): Promise { try { diff --git a/src/projectSchemas/gateway.test.ts b/src/projectSchemas/gateway.test.ts index f4c788bf1..3695d44e2 100644 --- a/src/projectSchemas/gateway.test.ts +++ b/src/projectSchemas/gateway.test.ts @@ -441,3 +441,25 @@ describe("gateway custom validation", () => { expect(imported.error?.issues[0]?.path).toEqual(["additionalPolicies"]); }); }); + +describe("gateway application logs and traces", () => { + const gateway = { name: "gateway", targets: [] }; + // FsReadWriteJson writes the parsed spec with JSON.stringify, so this is what agentcore.json keeps. + const roundTrip = (input: object) => + JSON.parse(JSON.stringify(AgentCoreGatewaySchema.parse(input))) as Record; + + it.each([true, false])("keeps enableApplicationLogs and enableTraces set to %p", (value) => { + const written = roundTrip({ ...gateway, enableApplicationLogs: value, enableTraces: value }); + + expect(written.enableApplicationLogs).toBe(value); + expect(written.enableTraces).toBe(value); + expect(roundTrip(written)).toEqual(written); + }); + + it("writes neither field back when the gateway does not set it", () => { + const written = roundTrip(gateway); + + expect("enableApplicationLogs" in written).toBe(false); + expect("enableTraces" in written).toBe(false); + }); +}); diff --git a/src/projectSchemas/gateway.ts b/src/projectSchemas/gateway.ts index 48137dc0c..b456a9c3d 100644 --- a/src/projectSchemas/gateway.ts +++ b/src/projectSchemas/gateway.ts @@ -520,6 +520,18 @@ export const AgentCoreGatewaySchema = z * files relative to the project root. */ additionalPolicies: z.array(z.string().min(1)).optional(), + /** + * Deliver the gateway's `APPLICATION_LOGS` to the CloudWatch Logs group + * `/aws/vendedlogs/bedrock-agentcore/gateway/APPLICATION_LOGS/`. Defaults to false + * for every gateway, because the logs can hold the request and response bodies of its MCP + * operations. + */ + enableApplicationLogs: z.boolean().optional(), + /** + * Deliver the gateway's `TRACES` to X-Ray. Defaults to false for every gateway, because the + * deploy fails in an account and Region without CloudWatch Transaction Search. + */ + enableTraces: z.boolean().optional(), tags: TagsSchema.optional(), }) .strict() diff --git a/src/projectSchemas/project.ts b/src/projectSchemas/project.ts index 4d17612d0..d0c472422 100644 --- a/src/projectSchemas/project.ts +++ b/src/projectSchemas/project.ts @@ -47,8 +47,9 @@ export const boxGatewayName = (runtimeName: string): string => `${runtimeName.replace(/_/g, "-")}${BOX_GATEWAY_SUFFIX}`; /** * The Box gateway entry of a runtime, as the CLI writes it: bound to that runtime, under the fixed - * variable prefix, `AWS_IAM` auth and `protocolType: "None"`. The CDK library binds it from - * `boundRuntime` and `discoveryPrefix`. + * variable prefix, `AWS_IAM` auth, `protocolType: "None"` and its `APPLICATION_LOGS` on. The CDK + * library binds it from `boundRuntime` and `discoveryPrefix`. Build changes only its targets, so a + * user's `enableApplicationLogs: false` stays. */ export const boxGatewaySpec = (runtimeName: string) => ({ name: boxGatewayName(runtimeName), @@ -56,6 +57,7 @@ export const boxGatewaySpec = (runtimeName: string) => ({ protocolType: "None" as const, boundRuntime: runtimeName, discoveryPrefix: BOX_GATEWAY_DISCOVERY_PREFIX, + enableApplicationLogs: true, targets: [], }); /**