feat(project): add gateway resources

src/core/project/manager.tsx

@@ -153,18 +153,37 @@ export class FsProjectManager implements ProjectManager {
  const existingProjectSpec = await this.json.read(agentCoreSpecPath, ProjectSpecSchema);
 
  const existingResources = existingProjectSpec[projectSpecKey];
- if (existingResources.find((r) => r.name === resourceConfig.name))
+ if (resourceType === "gateway-target") {
+ // Current L3 outputs are keyed only by Target name, so names must remain
+ // project-unique until those outputs include the parent Gateway.
+ const gateway = existingProjectSpec.agentCoreGateways.find((candidate) =>
+ candidate.targets.some((target) => target.name === resourceConfig.name),
+ );
+ if (gateway) {
+ throw new InputValidationError(
+ `a gateway target with name '${resourceConfig.name}' already exists in gateway '${gateway.name}'`,
+ );
+ }
+ if (
+ existingProjectSpec.unassignedTargets?.some((target) => target.name === resourceConfig.name)
+ ) {
+ throw new InputValidationError(
+ `an unassigned gateway target with name '${resourceConfig.name}' already exists`,
+ );
+ }
+ } else if (existingResources.find((resource) => resource.name === resourceConfig.name)) {
  throw new InputValidationError(
  `a ${resourceType} with name '${resourceConfig.name}' already exists`,
  );
+ }
 
  // Widened: arms push their own shapes; the whole-spec safeParse below validates.
  const newResources: unknown[] = [...existingResources];
  const scaffoldedPaths: string[] = [];
  // Non-file work that a failed spec write must also reverse.
  let envFile: EnvLocalFile | undefined;
 
- switch (resourceType) {
+ switch (input.resourceType) {
  case "harness": {
  yield { message: `Scaffolding harness in project` };
  const outputPath = join(project.rootPath, "app", resourceConfig.name);
@@ -202,9 +221,25 @@ export class FsProjectManager implements ProjectManager {
  case "online-eval":
  case "online-insight":
  case "memory":
+ case "gateway":
  newResources.push(resourceConfig);
  break;
-
+ case "gateway-target": {
+ const gatewayIndex = existingProjectSpec.agentCoreGateways.findIndex(
+ (gateway) => gateway.name === input.gatewayName,
+ );
+ if (gatewayIndex < 0) {
+ throw new InputValidationError(
+ `gateway '${input.gatewayName}' does not exist in this project; check agentCoreGateways in agentcore.json`,
+ );
+ }
+ const gateway = existingProjectSpec.agentCoreGateways[gatewayIndex]!;
+ newResources[gatewayIndex] = {
+ ...gateway,
+ targets: [...gateway.targets, resourceConfig],
+ };
+ break;
+ }
  default: {
  const unhandled: never = input;
  throw new NotImplementedError(`unsupported project resource: ${String(unhandled)}`);
@@ -260,22 +295,34 @@ export class FsProjectManager implements ProjectManager {
 
  public async removeResource(project: Project, input: RemoveResourceInput): Promise<Project> {
  const agentCoreSpecPath = this.getProjectSpecPath(project);
- const projectSpecKey = toProjectSpecKey(input.resourceType);
-
  const existingProjectSpec = await this.json.read(agentCoreSpecPath, ProjectSpecSchema);
 
- const existingResources = existingProjectSpec[projectSpecKey];
- const newResources = existingResources.filter((r) => r.name !== input.name);
+ let removed = false;
+ let newSpec: unknown;
+ if (input.resourceType === "gateway-target") {
+ const gateways = [...existingProjectSpec.agentCoreGateways];
+ const gatewayIndex = gateways.findIndex((gateway) => gateway.name === input.gatewayName);
+ if (gatewayIndex >= 0) {
+ const gateway = gateways[gatewayIndex]!;
+ const targets = gateway.targets.filter((target) => target.name !== input.name);
+ removed = targets.length !== gateway.targets.length;
+ gateways[gatewayIndex] = { ...gateway, targets };
+ }
+ newSpec = { ...existingProjectSpec, agentCoreGateways: gateways };
+ } else {
+ const projectSpecKey = toProjectSpecKey(input.resourceType);
+ const existingResources = existingProjectSpec[projectSpecKey];
+ const newResources = existingResources.filter((resource) => resource.name !== input.name);
+ removed = newResources.length !== existingResources.length;
+ newSpec = { ...existingProjectSpec, [projectSpecKey]: newResources };
+ }
 
- if (newResources.length === existingResources.length)
+ if (!removed)
  this.logger
  .child({ input })
  .warn(`unable to remove resource from project that does not exist.`);
 
- const newSpecParseResult = ProjectSpecSchema.safeParse({
- ...existingProjectSpec,
- [projectSpecKey]: newResources,
- });
+ const newSpecParseResult = ProjectSpecSchema.safeParse(newSpec);
 
  if (!newSpecParseResult.success)
  throw new InputValidationError(z.prettifyError(newSpecParseResult.error), {
@@ -385,5 +432,8 @@ function toProjectSpecKey(resourceType: ProjectResource) {
  return "onlineEvalConfigs";
  case "memory":
  return "memories";
+ case "gateway":
+ case "gateway-target":
+ return "agentCoreGateways";
  }
 }

src/handlers/project/add/gateway-connector/index.test.ts

@@ -0,0 +1,168 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createGatewayProjectTestHarness } from "../gateway-test-support";
+
+const COMPLETE_CONNECTOR = JSON.stringify({
+ name: "configured",
+ targetType: "connector",
+ connectorId: "web-search",
+});
+
+const { addGateway, cleanup, inProject, projectSpec, run } =
+ createGatewayProjectTestHarness("gateway-connector");
+
+afterEach(cleanup);
+
+describe("project add gateway-connector", () => {
+ test("adds Web Search and external Knowledge Base connectors", async () => {
+ const projectRoot = await inProject();
+ await addGateway();
+
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ ]);
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--name",
+ "knowledge",
+ "--connector",
+ "bedrock-knowledge-bases",
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ]);
+
+ expect((await projectSpec(projectRoot)).agentCoreGateways[0].targets).toEqual([
+ {
+ name: "web",
+ targetType: "connector",
+ connectorId: "web-search",
+ configurations: [{ name: "WebSearch", parameterValues: { maxResults: 10 } }],
+ },
+ {
+ name: "knowledge",
+ targetType: "connector",
+ connectorId: "bedrock-knowledge-bases",
+ configurations: [{ name: "Retrieve", parameterValues: { knowledgeBaseId: "ABCDEFGHIJ" } }],
+ },
+ ]);
+ });
+
+ test("reads a complete connector Target from a file", async () => {
+ const projectRoot = await inProject();
+ await addGateway();
+ const target = {
+ name: "configured",
+ targetType: "connector",
+ connectorId: "web-search",
+ configurations: [{ name: "WebSearch", parameterValues: { maxResults: 3 } }],
+ };
+ const path = join(projectRoot, "connector.json");
+ await writeFile(path, JSON.stringify(target));
+
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ `file://${path}`,
+ ]);
+
+ expect((await projectSpec(projectRoot)).agentCoreGateways[0].targets[0]).toEqual(target);
+ });
+
+ test("rejects a non-connector project Target", async () => {
+ await inProject();
+ await addGateway();
+
+ await expect(
+ run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ '{"name":"server","targetType":"mcpServer","endpoint":"https://mcp.example.com"}',
+ ]),
+ ).rejects.toThrow('targetType: "connector"');
+ });
+
+ test.each([
+ [
+ "missing parent Gateway",
+ ["--name", "web", "--connector", "web-search"],
+ "required option '--gateway",
+ ],
+ ["no connector mode", ["--gateway", "tools", "--name", "web"], "specify exactly one"],
+ [
+ "both connector modes",
+ [
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ "--connector-configuration",
+ COMPLETE_CONNECTOR,
+ ],
+ "specify exactly one",
+ ],
+ [
+ "name with complete connector JSON",
+ ["--gateway", "tools", "--name", "web", "--connector-configuration", COMPLETE_CONNECTOR],
+ "--name is part of --connector-configuration",
+ ],
+ [
+ "knowledge base with complete connector JSON",
+ [
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ COMPLETE_CONNECTOR,
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ],
+ "--knowledge-base cannot be combined",
+ ],
+ [
+ "shortcut without name",
+ ["--gateway", "tools", "--connector", "web-search"],
+ "required option '--name",
+ ],
+ [
+ "knowledge base with Web Search",
+ [
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ],
+ "--knowledge-base requires --connector bedrock-knowledge-bases",
+ ],
+ [
+ "Knowledge Base connector without Knowledge Base",
+ ["--gateway", "tools", "--name", "knowledge", "--connector", "bedrock-knowledge-bases"],
+ "requires --knowledge-base",
+ ],
+ ])("rejects %s", async (_label, flags, message) => {
+ await inProject();
+ await addGateway();
+ await expect(run(["add", "gateway-connector", ...flags])).rejects.toThrow(message);
+ });
+});

src/core/project/manager.tsx

@@ -153,18 +153,37 @@ export class FsProjectManager implements ProjectManager {
  const existingProjectSpec = await this.json.read(agentCoreSpecPath, ProjectSpecSchema);
 
  const existingResources = existingProjectSpec[projectSpecKey];
- if (existingResources.find((r) => r.name === resourceConfig.name))
+ if (resourceType === "gateway-target") {
+ // Current L3 outputs are keyed only by Target name, so names must remain
+ // project-unique until those outputs include the parent Gateway.
+ const gateway = existingProjectSpec.agentCoreGateways.find((candidate) =>
+ candidate.targets.some((target) => target.name === resourceConfig.name),
+ );
+ if (gateway) {
+ throw new InputValidationError(
+ `a gateway target with name '${resourceConfig.name}' already exists in gateway '${gateway.name}'`,
+ );
+ }
+ if (
+ existingProjectSpec.unassignedTargets?.some((target) => target.name === resourceConfig.name)
+ ) {
+ throw new InputValidationError(
+ `an unassigned gateway target with name '${resourceConfig.name}' already exists`,
+ );
+ }
+ } else if (existingResources.find((resource) => resource.name === resourceConfig.name)) {
  throw new InputValidationError(
  `a ${resourceType} with name '${resourceConfig.name}' already exists`,
  );
+ }
 
  // Widened: arms push their own shapes; the whole-spec safeParse below validates.
  const newResources: unknown[] = [...existingResources];
  const scaffoldedPaths: string[] = [];
  // Non-file work that a failed spec write must also reverse.
  let envFile: EnvLocalFile | undefined;
 
- switch (resourceType) {
+ switch (input.resourceType) {
  case "harness": {
  yield { message: `Scaffolding harness in project` };
  const outputPath = join(project.rootPath, "app", resourceConfig.name);
@@ -202,9 +221,25 @@ export class FsProjectManager implements ProjectManager {
  case "online-eval":
  case "online-insight":
  case "memory":
+ case "gateway":
  newResources.push(resourceConfig);
  break;
-
+ case "gateway-target": {
+ const gatewayIndex = existingProjectSpec.agentCoreGateways.findIndex(
+ (gateway) => gateway.name === input.gatewayName,
+ );
+ if (gatewayIndex < 0) {
+ throw new InputValidationError(
+ `gateway '${input.gatewayName}' does not exist in this project; check agentCoreGateways in agentcore.json`,
+ );
+ }
+ const gateway = existingProjectSpec.agentCoreGateways[gatewayIndex]!;
+ newResources[gatewayIndex] = {
+ ...gateway,
+ targets: [...gateway.targets, resourceConfig],
+ };
+ break;
+ }
  default: {
  const unhandled: never = input;
  throw new NotImplementedError(`unsupported project resource: ${String(unhandled)}`);
@@ -260,22 +295,34 @@ export class FsProjectManager implements ProjectManager {
 
  public async removeResource(project: Project, input: RemoveResourceInput): Promise<Project> {
  const agentCoreSpecPath = this.getProjectSpecPath(project);
- const projectSpecKey = toProjectSpecKey(input.resourceType);
-
  const existingProjectSpec = await this.json.read(agentCoreSpecPath, ProjectSpecSchema);
 
- const existingResources = existingProjectSpec[projectSpecKey];
- const newResources = existingResources.filter((r) => r.name !== input.name);
+ let removed = false;
+ let newSpec: unknown;
+ if (input.resourceType === "gateway-target") {
+ const gateways = [...existingProjectSpec.agentCoreGateways];
+ const gatewayIndex = gateways.findIndex((gateway) => gateway.name === input.gatewayName);
+ if (gatewayIndex >= 0) {
+ const gateway = gateways[gatewayIndex]!;
+ const targets = gateway.targets.filter((target) => target.name !== input.name);
+ removed = targets.length !== gateway.targets.length;
+ gateways[gatewayIndex] = { ...gateway, targets };
+ }
+ newSpec = { ...existingProjectSpec, agentCoreGateways: gateways };
+ } else {
+ const projectSpecKey = toProjectSpecKey(input.resourceType);
+ const existingResources = existingProjectSpec[projectSpecKey];
+ const newResources = existingResources.filter((resource) => resource.name !== input.name);
+ removed = newResources.length !== existingResources.length;
+ newSpec = { ...existingProjectSpec, [projectSpecKey]: newResources };
+ }
 
- if (newResources.length === existingResources.length)
+ if (!removed)
  this.logger
  .child({ input })
  .warn(`unable to remove resource from project that does not exist.`);
 
- const newSpecParseResult = ProjectSpecSchema.safeParse({
- ...existingProjectSpec,
- [projectSpecKey]: newResources,
- });
+ const newSpecParseResult = ProjectSpecSchema.safeParse(newSpec);
 
  if (!newSpecParseResult.success)
  throw new InputValidationError(z.prettifyError(newSpecParseResult.error), {
@@ -385,5 +432,8 @@ function toProjectSpecKey(resourceType: ProjectResource) {
  return "onlineEvalConfigs";
  case "memory":
  return "memories";
+ case "gateway":
+ case "gateway-target":
+ return "agentCoreGateways";
  }
 }

src/handlers/project/add/gateway-connector/index.test.ts

@@ -0,0 +1,168 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createGatewayProjectTestHarness } from "../gateway-test-support";
+
+const COMPLETE_CONNECTOR = JSON.stringify({
+ name: "configured",
+ targetType: "connector",
+ connectorId: "web-search",
+});
+
+const { addGateway, cleanup, inProject, projectSpec, run } =
+ createGatewayProjectTestHarness("gateway-connector");
+
+afterEach(cleanup);
+
+describe("project add gateway-connector", () => {
+ test("adds Web Search and external Knowledge Base connectors", async () => {
+ const projectRoot = await inProject();
+ await addGateway();
+
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ ]);
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--name",
+ "knowledge",
+ "--connector",
+ "bedrock-knowledge-bases",
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ]);
+
+ expect((await projectSpec(projectRoot)).agentCoreGateways[0].targets).toEqual([
+ {
+ name: "web",
+ targetType: "connector",
+ connectorId: "web-search",
+ configurations: [{ name: "WebSearch", parameterValues: { maxResults: 10 } }],
+ },
+ {
+ name: "knowledge",
+ targetType: "connector",
+ connectorId: "bedrock-knowledge-bases",
+ configurations: [{ name: "Retrieve", parameterValues: { knowledgeBaseId: "ABCDEFGHIJ" } }],
+ },
+ ]);
+ });
+
+ test("reads a complete connector Target from a file", async () => {
+ const projectRoot = await inProject();
+ await addGateway();
+ const target = {
+ name: "configured",
+ targetType: "connector",
+ connectorId: "web-search",
+ configurations: [{ name: "WebSearch", parameterValues: { maxResults: 3 } }],
+ };
+ const path = join(projectRoot, "connector.json");
+ await writeFile(path, JSON.stringify(target));
+
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ `file://${path}`,
+ ]);
+
+ expect((await projectSpec(projectRoot)).agentCoreGateways[0].targets[0]).toEqual(target);
+ });
+
+ test("rejects a non-connector project Target", async () => {
+ await inProject();
+ await addGateway();
+
+ await expect(
+ run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ '{"name":"server","targetType":"mcpServer","endpoint":"https://mcp.example.com"}',
+ ]),
+ ).rejects.toThrow('targetType: "connector"');
+ });
+
+ test.each([
+ [
+ "missing parent Gateway",
+ ["--name", "web", "--connector", "web-search"],
+ "required option '--gateway",
+ ],
+ ["no connector mode", ["--gateway", "tools", "--name", "web"], "specify exactly one"],
+ [
+ "both connector modes",
+ [
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ "--connector-configuration",
+ COMPLETE_CONNECTOR,
+ ],
+ "specify exactly one",
+ ],
+ [
+ "name with complete connector JSON",
+ ["--gateway", "tools", "--name", "web", "--connector-configuration", COMPLETE_CONNECTOR],
+ "--name is part of --connector-configuration",
+ ],
+ [
+ "knowledge base with complete connector JSON",
+ [
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ COMPLETE_CONNECTOR,
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ],
+ "--knowledge-base cannot be combined",
+ ],
+ [
+ "shortcut without name",
+ ["--gateway", "tools", "--connector", "web-search"],
+ "required option '--name",
+ ],
+ [
+ "knowledge base with Web Search",
+ [
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ],
+ "--knowledge-base requires --connector bedrock-knowledge-bases",
+ ],
+ [
+ "Knowledge Base connector without Knowledge Base",
+ ["--gateway", "tools", "--name", "knowledge", "--connector", "bedrock-knowledge-bases"],
+ "requires --knowledge-base",
+ ],
+ ])("rejects %s", async (_label, flags, message) => {
+ await inProject();
+ await addGateway();
+ await expect(run(["add", "gateway-connector", ...flags])).rejects.toThrow(message);
+ });
+});

src/core/project/manager.tsx

@@ -153,18 +153,37 @@ export class FsProjectManager implements ProjectManager {
  const existingProjectSpec = await this.json.read(agentCoreSpecPath, ProjectSpecSchema);
 
  const existingResources = existingProjectSpec[projectSpecKey];
- if (existingResources.find((r) => r.name === resourceConfig.name))
+ if (resourceType === "gateway-target") {
+ // Current L3 outputs are keyed only by Target name, so names must remain
+ // project-unique until those outputs include the parent Gateway.
+ const gateway = existingProjectSpec.agentCoreGateways.find((candidate) =>
+ candidate.targets.some((target) => target.name === resourceConfig.name),
+ );
+ if (gateway) {
+ throw new InputValidationError(
+ `a gateway target with name '${resourceConfig.name}' already exists in gateway '${gateway.name}'`,
+ );
+ }
+ if (
+ existingProjectSpec.unassignedTargets?.some((target) => target.name === resourceConfig.name)
+ ) {
+ throw new InputValidationError(
+ `an unassigned gateway target with name '${resourceConfig.name}' already exists`,
+ );
+ }
+ } else if (existingResources.find((resource) => resource.name === resourceConfig.name)) {
  throw new InputValidationError(
  `a ${resourceType} with name '${resourceConfig.name}' already exists`,
  );
+ }
 
  // Widened: arms push their own shapes; the whole-spec safeParse below validates.
  const newResources: unknown[] = [...existingResources];
  const scaffoldedPaths: string[] = [];
  // Non-file work that a failed spec write must also reverse.
  let envFile: EnvLocalFile | undefined;
 
- switch (resourceType) {
+ switch (input.resourceType) {
  case "harness": {
  yield { message: `Scaffolding harness in project` };
  const outputPath = join(project.rootPath, "app", resourceConfig.name);
@@ -202,9 +221,25 @@ export class FsProjectManager implements ProjectManager {
  case "online-eval":
  case "online-insight":
  case "memory":
+ case "gateway":
  newResources.push(resourceConfig);
  break;
-
+ case "gateway-target": {
+ const gatewayIndex = existingProjectSpec.agentCoreGateways.findIndex(
+ (gateway) => gateway.name === input.gatewayName,
+ );
+ if (gatewayIndex < 0) {
+ throw new InputValidationError(
+ `gateway '${input.gatewayName}' does not exist in this project; check agentCoreGateways in agentcore.json`,
+ );
+ }
+ const gateway = existingProjectSpec.agentCoreGateways[gatewayIndex]!;
+ newResources[gatewayIndex] = {
+ ...gateway,
+ targets: [...gateway.targets, resourceConfig],
+ };
+ break;
+ }
  default: {
  const unhandled: never = input;
  throw new NotImplementedError(`unsupported project resource: ${String(unhandled)}`);
@@ -260,22 +295,34 @@ export class FsProjectManager implements ProjectManager {
 
  public async removeResource(project: Project, input: RemoveResourceInput): Promise<Project> {
  const agentCoreSpecPath = this.getProjectSpecPath(project);
- const projectSpecKey = toProjectSpecKey(input.resourceType);
-
  const existingProjectSpec = await this.json.read(agentCoreSpecPath, ProjectSpecSchema);
 
- const existingResources = existingProjectSpec[projectSpecKey];
- const newResources = existingResources.filter((r) => r.name !== input.name);
+ let removed = false;
+ let newSpec: unknown;
+ if (input.resourceType === "gateway-target") {
+ const gateways = [...existingProjectSpec.agentCoreGateways];
+ const gatewayIndex = gateways.findIndex((gateway) => gateway.name === input.gatewayName);
+ if (gatewayIndex >= 0) {
+ const gateway = gateways[gatewayIndex]!;
+ const targets = gateway.targets.filter((target) => target.name !== input.name);
+ removed = targets.length !== gateway.targets.length;
+ gateways[gatewayIndex] = { ...gateway, targets };
+ }
+ newSpec = { ...existingProjectSpec, agentCoreGateways: gateways };
+ } else {
+ const projectSpecKey = toProjectSpecKey(input.resourceType);
+ const existingResources = existingProjectSpec[projectSpecKey];
+ const newResources = existingResources.filter((resource) => resource.name !== input.name);
+ removed = newResources.length !== existingResources.length;
+ newSpec = { ...existingProjectSpec, [projectSpecKey]: newResources };
+ }
 
- if (newResources.length === existingResources.length)
+ if (!removed)
  this.logger
  .child({ input })
  .warn(`unable to remove resource from project that does not exist.`);
 
- const newSpecParseResult = ProjectSpecSchema.safeParse({
- ...existingProjectSpec,
- [projectSpecKey]: newResources,
- });
+ const newSpecParseResult = ProjectSpecSchema.safeParse(newSpec);
 
  if (!newSpecParseResult.success)
  throw new InputValidationError(z.prettifyError(newSpecParseResult.error), {
@@ -385,5 +432,8 @@ function toProjectSpecKey(resourceType: ProjectResource) {
  return "onlineEvalConfigs";
  case "memory":
  return "memories";
+ case "gateway":
+ case "gateway-target":
+ return "agentCoreGateways";
  }
 }

src/handlers/project/add/gateway-connector/index.test.ts

@@ -0,0 +1,168 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createGatewayProjectTestHarness } from "../gateway-test-support";
+
+const COMPLETE_CONNECTOR = JSON.stringify({
+ name: "configured",
+ targetType: "connector",
+ connectorId: "web-search",
+});
+
+const { addGateway, cleanup, inProject, projectSpec, run } =
+ createGatewayProjectTestHarness("gateway-connector");
+
+afterEach(cleanup);
+
+describe("project add gateway-connector", () => {
+ test("adds Web Search and external Knowledge Base connectors", async () => {
+ const projectRoot = await inProject();
+ await addGateway();
+
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ ]);
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--name",
+ "knowledge",
+ "--connector",
+ "bedrock-knowledge-bases",
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ]);
+
+ expect((await projectSpec(projectRoot)).agentCoreGateways[0].targets).toEqual([
+ {
+ name: "web",
+ targetType: "connector",
+ connectorId: "web-search",
+ configurations: [{ name: "WebSearch", parameterValues: { maxResults: 10 } }],
+ },
+ {
+ name: "knowledge",
+ targetType: "connector",
+ connectorId: "bedrock-knowledge-bases",
+ configurations: [{ name: "Retrieve", parameterValues: { knowledgeBaseId: "ABCDEFGHIJ" } }],
+ },
+ ]);
+ });
+
+ test("reads a complete connector Target from a file", async () => {
+ const projectRoot = await inProject();
+ await addGateway();
+ const target = {
+ name: "configured",
+ targetType: "connector",
+ connectorId: "web-search",
+ configurations: [{ name: "WebSearch", parameterValues: { maxResults: 3 } }],
+ };
+ const path = join(projectRoot, "connector.json");
+ await writeFile(path, JSON.stringify(target));
+
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ `file://${path}`,
+ ]);
+
+ expect((await projectSpec(projectRoot)).agentCoreGateways[0].targets[0]).toEqual(target);
+ });
+
+ test("rejects a non-connector project Target", async () => {
+ await inProject();
+ await addGateway();
+
+ await expect(
+ run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ '{"name":"server","targetType":"mcpServer","endpoint":"https://mcp.example.com"}',
+ ]),
+ ).rejects.toThrow('targetType: "connector"');
+ });
+
+ test.each([
+ [
+ "missing parent Gateway",
+ ["--name", "web", "--connector", "web-search"],
+ "required option '--gateway",
+ ],
+ ["no connector mode", ["--gateway", "tools", "--name", "web"], "specify exactly one"],
+ [
+ "both connector modes",
+ [
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ "--connector-configuration",
+ COMPLETE_CONNECTOR,
+ ],
+ "specify exactly one",
+ ],
+ [
+ "name with complete connector JSON",
+ ["--gateway", "tools", "--name", "web", "--connector-configuration", COMPLETE_CONNECTOR],
+ "--name is part of --connector-configuration",
+ ],
+ [
+ "knowledge base with complete connector JSON",
+ [
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ COMPLETE_CONNECTOR,
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ],
+ "--knowledge-base cannot be combined",
+ ],
+ [
+ "shortcut without name",
+ ["--gateway", "tools", "--connector", "web-search"],
+ "required option '--name",
+ ],
+ [
+ "knowledge base with Web Search",
+ [
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ],
+ "--knowledge-base requires --connector bedrock-knowledge-bases",
+ ],
+ [
+ "Knowledge Base connector without Knowledge Base",
+ ["--gateway", "tools", "--name", "knowledge", "--connector", "bedrock-knowledge-bases"],
+ "requires --knowledge-base",
+ ],
+ ])("rejects %s", async (_label, flags, message) => {
+ await inProject();
+ await addGateway();
+ await expect(run(["add", "gateway-connector", ...flags])).rejects.toThrow(message);
+ });
+});

src/core/project/manager.tsx

@@ -153,18 +153,37 @@ export class FsProjectManager implements ProjectManager {
  const existingProjectSpec = await this.json.read(agentCoreSpecPath, ProjectSpecSchema);
 
  const existingResources = existingProjectSpec[projectSpecKey];
- if (existingResources.find((r) => r.name === resourceConfig.name))
+ if (resourceType === "gateway-target") {
+ // Current L3 outputs are keyed only by Target name, so names must remain
+ // project-unique until those outputs include the parent Gateway.
+ const gateway = existingProjectSpec.agentCoreGateways.find((candidate) =>
+ candidate.targets.some((target) => target.name === resourceConfig.name),
+ );
+ if (gateway) {
+ throw new InputValidationError(
+ `a gateway target with name '${resourceConfig.name}' already exists in gateway '${gateway.name}'`,
+ );
+ }
+ if (
+ existingProjectSpec.unassignedTargets?.some((target) => target.name === resourceConfig.name)
+ ) {
+ throw new InputValidationError(
+ `an unassigned gateway target with name '${resourceConfig.name}' already exists`,
+ );
+ }
+ } else if (existingResources.find((resource) => resource.name === resourceConfig.name)) {
  throw new InputValidationError(
  `a ${resourceType} with name '${resourceConfig.name}' already exists`,
  );
+ }
 
  // Widened: arms push their own shapes; the whole-spec safeParse below validates.
  const newResources: unknown[] = [...existingResources];
  const scaffoldedPaths: string[] = [];
  // Non-file work that a failed spec write must also reverse.
  let envFile: EnvLocalFile | undefined;
 
- switch (resourceType) {
+ switch (input.resourceType) {
  case "harness": {
  yield { message: `Scaffolding harness in project` };
  const outputPath = join(project.rootPath, "app", resourceConfig.name);
@@ -202,9 +221,25 @@ export class FsProjectManager implements ProjectManager {
  case "online-eval":
  case "online-insight":
  case "memory":
+ case "gateway":
  newResources.push(resourceConfig);
  break;
-
+ case "gateway-target": {
+ const gatewayIndex = existingProjectSpec.agentCoreGateways.findIndex(
+ (gateway) => gateway.name === input.gatewayName,
+ );
+ if (gatewayIndex < 0) {
+ throw new InputValidationError(
+ `gateway '${input.gatewayName}' does not exist in this project; check agentCoreGateways in agentcore.json`,
+ );
+ }
+ const gateway = existingProjectSpec.agentCoreGateways[gatewayIndex]!;
+ newResources[gatewayIndex] = {
+ ...gateway,
+ targets: [...gateway.targets, resourceConfig],
+ };
+ break;
+ }
  default: {
  const unhandled: never = input;
  throw new NotImplementedError(`unsupported project resource: ${String(unhandled)}`);
@@ -260,22 +295,34 @@ export class FsProjectManager implements ProjectManager {
 
  public async removeResource(project: Project, input: RemoveResourceInput): Promise<Project> {
  const agentCoreSpecPath = this.getProjectSpecPath(project);
- const projectSpecKey = toProjectSpecKey(input.resourceType);
-
  const existingProjectSpec = await this.json.read(agentCoreSpecPath, ProjectSpecSchema);
 
- const existingResources = existingProjectSpec[projectSpecKey];
- const newResources = existingResources.filter((r) => r.name !== input.name);
+ let removed = false;
+ let newSpec: unknown;
+ if (input.resourceType === "gateway-target") {
+ const gateways = [...existingProjectSpec.agentCoreGateways];
+ const gatewayIndex = gateways.findIndex((gateway) => gateway.name === input.gatewayName);
+ if (gatewayIndex >= 0) {
+ const gateway = gateways[gatewayIndex]!;
+ const targets = gateway.targets.filter((target) => target.name !== input.name);
+ removed = targets.length !== gateway.targets.length;
+ gateways[gatewayIndex] = { ...gateway, targets };
+ }
+ newSpec = { ...existingProjectSpec, agentCoreGateways: gateways };
+ } else {
+ const projectSpecKey = toProjectSpecKey(input.resourceType);
+ const existingResources = existingProjectSpec[projectSpecKey];
+ const newResources = existingResources.filter((resource) => resource.name !== input.name);
+ removed = newResources.length !== existingResources.length;
+ newSpec = { ...existingProjectSpec, [projectSpecKey]: newResources };
+ }
 
- if (newResources.length === existingResources.length)
+ if (!removed)
  this.logger
  .child({ input })
  .warn(`unable to remove resource from project that does not exist.`);
 
- const newSpecParseResult = ProjectSpecSchema.safeParse({
- ...existingProjectSpec,
- [projectSpecKey]: newResources,
- });
+ const newSpecParseResult = ProjectSpecSchema.safeParse(newSpec);
 
  if (!newSpecParseResult.success)
  throw new InputValidationError(z.prettifyError(newSpecParseResult.error), {
@@ -385,5 +432,8 @@ function toProjectSpecKey(resourceType: ProjectResource) {
  return "onlineEvalConfigs";
  case "memory":
  return "memories";
+ case "gateway":
+ case "gateway-target":
+ return "agentCoreGateways";
  }
 }

src/handlers/project/add/gateway-connector/index.test.ts

@@ -0,0 +1,168 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createGatewayProjectTestHarness } from "../gateway-test-support";
+
+const COMPLETE_CONNECTOR = JSON.stringify({
+ name: "configured",
+ targetType: "connector",
+ connectorId: "web-search",
+});
+
+const { addGateway, cleanup, inProject, projectSpec, run } =
+ createGatewayProjectTestHarness("gateway-connector");
+
+afterEach(cleanup);
+
+describe("project add gateway-connector", () => {
+ test("adds Web Search and external Knowledge Base connectors", async () => {
+ const projectRoot = await inProject();
+ await addGateway();
+
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ ]);
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--name",
+ "knowledge",
+ "--connector",
+ "bedrock-knowledge-bases",
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ]);
+
+ expect((await projectSpec(projectRoot)).agentCoreGateways[0].targets).toEqual([
+ {
+ name: "web",
+ targetType: "connector",
+ connectorId: "web-search",
+ configurations: [{ name: "WebSearch", parameterValues: { maxResults: 10 } }],
+ },
+ {
+ name: "knowledge",
+ targetType: "connector",
+ connectorId: "bedrock-knowledge-bases",
+ configurations: [{ name: "Retrieve", parameterValues: { knowledgeBaseId: "ABCDEFGHIJ" } }],
+ },
+ ]);
+ });
+
+ test("reads a complete connector Target from a file", async () => {
+ const projectRoot = await inProject();
+ await addGateway();
+ const target = {
+ name: "configured",
+ targetType: "connector",
+ connectorId: "web-search",
+ configurations: [{ name: "WebSearch", parameterValues: { maxResults: 3 } }],
+ };
+ const path = join(projectRoot, "connector.json");
+ await writeFile(path, JSON.stringify(target));
+
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ `file://${path}`,
+ ]);
+
+ expect((await projectSpec(projectRoot)).agentCoreGateways[0].targets[0]).toEqual(target);
+ });
+
+ test("rejects a non-connector project Target", async () => {
+ await inProject();
+ await addGateway();
+
+ await expect(
+ run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ '{"name":"server","targetType":"mcpServer","endpoint":"https://mcp.example.com"}',
+ ]),
+ ).rejects.toThrow('targetType: "connector"');
+ });
+
+ test.each([
+ [
+ "missing parent Gateway",
+ ["--name", "web", "--connector", "web-search"],
+ "required option '--gateway",
+ ],
+ ["no connector mode", ["--gateway", "tools", "--name", "web"], "specify exactly one"],
+ [
+ "both connector modes",
+ [
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ "--connector-configuration",
+ COMPLETE_CONNECTOR,
+ ],
+ "specify exactly one",
+ ],
+ [
+ "name with complete connector JSON",
+ ["--gateway", "tools", "--name", "web", "--connector-configuration", COMPLETE_CONNECTOR],
+ "--name is part of --connector-configuration",
+ ],
+ [
+ "knowledge base with complete connector JSON",
+ [
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ COMPLETE_CONNECTOR,
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ],
+ "--knowledge-base cannot be combined",
+ ],
+ [
+ "shortcut without name",
+ ["--gateway", "tools", "--connector", "web-search"],
+ "required option '--name",
+ ],
+ [
+ "knowledge base with Web Search",
+ [
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ],
+ "--knowledge-base requires --connector bedrock-knowledge-bases",
+ ],
+ [
+ "Knowledge Base connector without Knowledge Base",
+ ["--gateway", "tools", "--name", "knowledge", "--connector", "bedrock-knowledge-bases"],
+ "requires --knowledge-base",
+ ],
+ ])("rejects %s", async (_label, flags, message) => {
+ await inProject();
+ await addGateway();
+ await expect(run(["add", "gateway-connector", ...flags])).rejects.toThrow(message);
+ });
+});

src/core/project/manager.tsx

@@ -153,18 +153,37 @@ export class FsProjectManager implements ProjectManager {
  const existingProjectSpec = await this.json.read(agentCoreSpecPath, ProjectSpecSchema);
 
  const existingResources = existingProjectSpec[projectSpecKey];
- if (existingResources.find((r) => r.name === resourceConfig.name))
+ if (resourceType === "gateway-target") {
+ // Current L3 outputs are keyed only by Target name, so names must remain
+ // project-unique until those outputs include the parent Gateway.
+ const gateway = existingProjectSpec.agentCoreGateways.find((candidate) =>
+ candidate.targets.some((target) => target.name === resourceConfig.name),
+ );
+ if (gateway) {
+ throw new InputValidationError(
+ `a gateway target with name '${resourceConfig.name}' already exists in gateway '${gateway.name}'`,
+ );
+ }
+ if (
+ existingProjectSpec.unassignedTargets?.some((target) => target.name === resourceConfig.name)
+ ) {
+ throw new InputValidationError(
+ `an unassigned gateway target with name '${resourceConfig.name}' already exists`,
+ );
+ }
+ } else if (existingResources.find((resource) => resource.name === resourceConfig.name)) {
  throw new InputValidationError(
  `a ${resourceType} with name '${resourceConfig.name}' already exists`,
  );
+ }
 
  // Widened: arms push their own shapes; the whole-spec safeParse below validates.
  const newResources: unknown[] = [...existingResources];
  const scaffoldedPaths: string[] = [];
  // Non-file work that a failed spec write must also reverse.
  let envFile: EnvLocalFile | undefined;
 
- switch (resourceType) {
+ switch (input.resourceType) {
  case "harness": {
  yield { message: `Scaffolding harness in project` };
  const outputPath = join(project.rootPath, "app", resourceConfig.name);
@@ -202,9 +221,25 @@ export class FsProjectManager implements ProjectManager {
  case "online-eval":
  case "online-insight":
  case "memory":
+ case "gateway":
  newResources.push(resourceConfig);
  break;
-
+ case "gateway-target": {
+ const gatewayIndex = existingProjectSpec.agentCoreGateways.findIndex(
+ (gateway) => gateway.name === input.gatewayName,
+ );
+ if (gatewayIndex < 0) {
+ throw new InputValidationError(
+ `gateway '${input.gatewayName}' does not exist in this project; check agentCoreGateways in agentcore.json`,
+ );
+ }
+ const gateway = existingProjectSpec.agentCoreGateways[gatewayIndex]!;
+ newResources[gatewayIndex] = {
+ ...gateway,
+ targets: [...gateway.targets, resourceConfig],
+ };
+ break;
+ }
  default: {
  const unhandled: never = input;
  throw new NotImplementedError(`unsupported project resource: ${String(unhandled)}`);
@@ -260,22 +295,34 @@ export class FsProjectManager implements ProjectManager {
 
  public async removeResource(project: Project, input: RemoveResourceInput): Promise<Project> {
  const agentCoreSpecPath = this.getProjectSpecPath(project);
- const projectSpecKey = toProjectSpecKey(input.resourceType);
-
  const existingProjectSpec = await this.json.read(agentCoreSpecPath, ProjectSpecSchema);
 
- const existingResources = existingProjectSpec[projectSpecKey];
- const newResources = existingResources.filter((r) => r.name !== input.name);
+ let removed = false;
+ let newSpec: unknown;
+ if (input.resourceType === "gateway-target") {
+ const gateways = [...existingProjectSpec.agentCoreGateways];
+ const gatewayIndex = gateways.findIndex((gateway) => gateway.name === input.gatewayName);
+ if (gatewayIndex >= 0) {
+ const gateway = gateways[gatewayIndex]!;
+ const targets = gateway.targets.filter((target) => target.name !== input.name);
+ removed = targets.length !== gateway.targets.length;
+ gateways[gatewayIndex] = { ...gateway, targets };
+ }
+ newSpec = { ...existingProjectSpec, agentCoreGateways: gateways };
+ } else {
+ const projectSpecKey = toProjectSpecKey(input.resourceType);
+ const existingResources = existingProjectSpec[projectSpecKey];
+ const newResources = existingResources.filter((resource) => resource.name !== input.name);
+ removed = newResources.length !== existingResources.length;
+ newSpec = { ...existingProjectSpec, [projectSpecKey]: newResources };
+ }
 
- if (newResources.length === existingResources.length)
+ if (!removed)
  this.logger
  .child({ input })
  .warn(`unable to remove resource from project that does not exist.`);
 
- const newSpecParseResult = ProjectSpecSchema.safeParse({
- ...existingProjectSpec,
- [projectSpecKey]: newResources,
- });
+ const newSpecParseResult = ProjectSpecSchema.safeParse(newSpec);
 
  if (!newSpecParseResult.success)
  throw new InputValidationError(z.prettifyError(newSpecParseResult.error), {
@@ -385,5 +432,8 @@ function toProjectSpecKey(resourceType: ProjectResource) {
  return "onlineEvalConfigs";
  case "memory":
  return "memories";
+ case "gateway":
+ case "gateway-target":
+ return "agentCoreGateways";
  }
 }

src/handlers/project/add/gateway-connector/index.test.ts

@@ -0,0 +1,168 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createGatewayProjectTestHarness } from "../gateway-test-support";
+
+const COMPLETE_CONNECTOR = JSON.stringify({
+ name: "configured",
+ targetType: "connector",
+ connectorId: "web-search",
+});
+
+const { addGateway, cleanup, inProject, projectSpec, run } =
+ createGatewayProjectTestHarness("gateway-connector");
+
+afterEach(cleanup);
+
+describe("project add gateway-connector", () => {
+ test("adds Web Search and external Knowledge Base connectors", async () => {
+ const projectRoot = await inProject();
+ await addGateway();
+
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ ]);
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--name",
+ "knowledge",
+ "--connector",
+ "bedrock-knowledge-bases",
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ]);
+
+ expect((await projectSpec(projectRoot)).agentCoreGateways[0].targets).toEqual([
+ {
+ name: "web",
+ targetType: "connector",
+ connectorId: "web-search",
+ configurations: [{ name: "WebSearch", parameterValues: { maxResults: 10 } }],
+ },
+ {
+ name: "knowledge",
+ targetType: "connector",
+ connectorId: "bedrock-knowledge-bases",
+ configurations: [{ name: "Retrieve", parameterValues: { knowledgeBaseId: "ABCDEFGHIJ" } }],
+ },
+ ]);
+ });
+
+ test("reads a complete connector Target from a file", async () => {
+ const projectRoot = await inProject();
+ await addGateway();
+ const target = {
+ name: "configured",
+ targetType: "connector",
+ connectorId: "web-search",
+ configurations: [{ name: "WebSearch", parameterValues: { maxResults: 3 } }],
+ };
+ const path = join(projectRoot, "connector.json");
+ await writeFile(path, JSON.stringify(target));
+
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ `file://${path}`,
+ ]);
+
+ expect((await projectSpec(projectRoot)).agentCoreGateways[0].targets[0]).toEqual(target);
+ });
+
+ test("rejects a non-connector project Target", async () => {
+ await inProject();
+ await addGateway();
+
+ await expect(
+ run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ '{"name":"server","targetType":"mcpServer","endpoint":"https://mcp.example.com"}',
+ ]),
+ ).rejects.toThrow('targetType: "connector"');
+ });
+
+ test.each([
+ [
+ "missing parent Gateway",
+ ["--name", "web", "--connector", "web-search"],
+ "required option '--gateway",
+ ],
+ ["no connector mode", ["--gateway", "tools", "--name", "web"], "specify exactly one"],
+ [
+ "both connector modes",
+ [
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ "--connector-configuration",
+ COMPLETE_CONNECTOR,
+ ],
+ "specify exactly one",
+ ],
+ [
+ "name with complete connector JSON",
+ ["--gateway", "tools", "--name", "web", "--connector-configuration", COMPLETE_CONNECTOR],
+ "--name is part of --connector-configuration",
+ ],
+ [
+ "knowledge base with complete connector JSON",
+ [
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ COMPLETE_CONNECTOR,
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ],
+ "--knowledge-base cannot be combined",
+ ],
+ [
+ "shortcut without name",
+ ["--gateway", "tools", "--connector", "web-search"],
+ "required option '--name",
+ ],
+ [
+ "knowledge base with Web Search",
+ [
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ],
+ "--knowledge-base requires --connector bedrock-knowledge-bases",
+ ],
+ [
+ "Knowledge Base connector without Knowledge Base",
+ ["--gateway", "tools", "--name", "knowledge", "--connector", "bedrock-knowledge-bases"],
+ "requires --knowledge-base",
+ ],
+ ])("rejects %s", async (_label, flags, message) => {
+ await inProject();
+ await addGateway();
+ await expect(run(["add", "gateway-connector", ...flags])).rejects.toThrow(message);
+ });
+});

src/core/project/manager.tsx

@@ -153,18 +153,37 @@ export class FsProjectManager implements ProjectManager {
  const existingProjectSpec = await this.json.read(agentCoreSpecPath, ProjectSpecSchema);
 
  const existingResources = existingProjectSpec[projectSpecKey];
- if (existingResources.find((r) => r.name === resourceConfig.name))
+ if (resourceType === "gateway-target") {
+ // Current L3 outputs are keyed only by Target name, so names must remain
+ // project-unique until those outputs include the parent Gateway.
+ const gateway = existingProjectSpec.agentCoreGateways.find((candidate) =>
+ candidate.targets.some((target) => target.name === resourceConfig.name),
+ );
+ if (gateway) {
+ throw new InputValidationError(
+ `a gateway target with name '${resourceConfig.name}' already exists in gateway '${gateway.name}'`,
+ );
+ }
+ if (
+ existingProjectSpec.unassignedTargets?.some((target) => target.name === resourceConfig.name)
+ ) {
+ throw new InputValidationError(
+ `an unassigned gateway target with name '${resourceConfig.name}' already exists`,
+ );
+ }
+ } else if (existingResources.find((resource) => resource.name === resourceConfig.name)) {
  throw new InputValidationError(
  `a ${resourceType} with name '${resourceConfig.name}' already exists`,
  );
+ }
 
  // Widened: arms push their own shapes; the whole-spec safeParse below validates.
  const newResources: unknown[] = [...existingResources];
  const scaffoldedPaths: string[] = [];
  // Non-file work that a failed spec write must also reverse.
  let envFile: EnvLocalFile | undefined;
 
- switch (resourceType) {
+ switch (input.resourceType) {
  case "harness": {
  yield { message: `Scaffolding harness in project` };
  const outputPath = join(project.rootPath, "app", resourceConfig.name);
@@ -202,9 +221,25 @@ export class FsProjectManager implements ProjectManager {
  case "online-eval":
  case "online-insight":
  case "memory":
+ case "gateway":
  newResources.push(resourceConfig);
  break;
-
+ case "gateway-target": {
+ const gatewayIndex = existingProjectSpec.agentCoreGateways.findIndex(
+ (gateway) => gateway.name === input.gatewayName,
+ );
+ if (gatewayIndex < 0) {
+ throw new InputValidationError(
+ `gateway '${input.gatewayName}' does not exist in this project; check agentCoreGateways in agentcore.json`,
+ );
+ }
+ const gateway = existingProjectSpec.agentCoreGateways[gatewayIndex]!;
+ newResources[gatewayIndex] = {
+ ...gateway,
+ targets: [...gateway.targets, resourceConfig],
+ };
+ break;
+ }
  default: {
  const unhandled: never = input;
  throw new NotImplementedError(`unsupported project resource: ${String(unhandled)}`);
@@ -260,22 +295,34 @@ export class FsProjectManager implements ProjectManager {
 
  public async removeResource(project: Project, input: RemoveResourceInput): Promise<Project> {
  const agentCoreSpecPath = this.getProjectSpecPath(project);
- const projectSpecKey = toProjectSpecKey(input.resourceType);
-
  const existingProjectSpec = await this.json.read(agentCoreSpecPath, ProjectSpecSchema);
 
- const existingResources = existingProjectSpec[projectSpecKey];
- const newResources = existingResources.filter((r) => r.name !== input.name);
+ let removed = false;
+ let newSpec: unknown;
+ if (input.resourceType === "gateway-target") {
+ const gateways = [...existingProjectSpec.agentCoreGateways];
+ const gatewayIndex = gateways.findIndex((gateway) => gateway.name === input.gatewayName);
+ if (gatewayIndex >= 0) {
+ const gateway = gateways[gatewayIndex]!;
+ const targets = gateway.targets.filter((target) => target.name !== input.name);
+ removed = targets.length !== gateway.targets.length;
+ gateways[gatewayIndex] = { ...gateway, targets };
+ }
+ newSpec = { ...existingProjectSpec, agentCoreGateways: gateways };
+ } else {
+ const projectSpecKey = toProjectSpecKey(input.resourceType);
+ const existingResources = existingProjectSpec[projectSpecKey];
+ const newResources = existingResources.filter((resource) => resource.name !== input.name);
+ removed = newResources.length !== existingResources.length;
+ newSpec = { ...existingProjectSpec, [projectSpecKey]: newResources };
+ }
 
- if (newResources.length === existingResources.length)
+ if (!removed)
  this.logger
  .child({ input })
  .warn(`unable to remove resource from project that does not exist.`);
 
- const newSpecParseResult = ProjectSpecSchema.safeParse({
- ...existingProjectSpec,
- [projectSpecKey]: newResources,
- });
+ const newSpecParseResult = ProjectSpecSchema.safeParse(newSpec);
 
  if (!newSpecParseResult.success)
  throw new InputValidationError(z.prettifyError(newSpecParseResult.error), {
@@ -385,5 +432,8 @@ function toProjectSpecKey(resourceType: ProjectResource) {
  return "onlineEvalConfigs";
  case "memory":
  return "memories";
+ case "gateway":
+ case "gateway-target":
+ return "agentCoreGateways";
  }
 }

src/handlers/project/add/gateway-connector/index.test.ts

@@ -0,0 +1,168 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createGatewayProjectTestHarness } from "../gateway-test-support";
+
+const COMPLETE_CONNECTOR = JSON.stringify({
+ name: "configured",
+ targetType: "connector",
+ connectorId: "web-search",
+});
+
+const { addGateway, cleanup, inProject, projectSpec, run } =
+ createGatewayProjectTestHarness("gateway-connector");
+
+afterEach(cleanup);
+
+describe("project add gateway-connector", () => {
+ test("adds Web Search and external Knowledge Base connectors", async () => {
+ const projectRoot = await inProject();
+ await addGateway();
+
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ ]);
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--name",
+ "knowledge",
+ "--connector",
+ "bedrock-knowledge-bases",
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ]);
+
+ expect((await projectSpec(projectRoot)).agentCoreGateways[0].targets).toEqual([
+ {
+ name: "web",
+ targetType: "connector",
+ connectorId: "web-search",
+ configurations: [{ name: "WebSearch", parameterValues: { maxResults: 10 } }],
+ },
+ {
+ name: "knowledge",
+ targetType: "connector",
+ connectorId: "bedrock-knowledge-bases",
+ configurations: [{ name: "Retrieve", parameterValues: { knowledgeBaseId: "ABCDEFGHIJ" } }],
+ },
+ ]);
+ });
+
+ test("reads a complete connector Target from a file", async () => {
+ const projectRoot = await inProject();
+ await addGateway();
+ const target = {
+ name: "configured",
+ targetType: "connector",
+ connectorId: "web-search",
+ configurations: [{ name: "WebSearch", parameterValues: { maxResults: 3 } }],
+ };
+ const path = join(projectRoot, "connector.json");
+ await writeFile(path, JSON.stringify(target));
+
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ `file://${path}`,
+ ]);
+
+ expect((await projectSpec(projectRoot)).agentCoreGateways[0].targets[0]).toEqual(target);
+ });
+
+ test("rejects a non-connector project Target", async () => {
+ await inProject();
+ await addGateway();
+
+ await expect(
+ run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ '{"name":"server","targetType":"mcpServer","endpoint":"https://mcp.example.com"}',
+ ]),
+ ).rejects.toThrow('targetType: "connector"');
+ });
+
+ test.each([
+ [
+ "missing parent Gateway",
+ ["--name", "web", "--connector", "web-search"],
+ "required option '--gateway",
+ ],
+ ["no connector mode", ["--gateway", "tools", "--name", "web"], "specify exactly one"],
+ [
+ "both connector modes",
+ [
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ "--connector-configuration",
+ COMPLETE_CONNECTOR,
+ ],
+ "specify exactly one",
+ ],
+ [
+ "name with complete connector JSON",
+ ["--gateway", "tools", "--name", "web", "--connector-configuration", COMPLETE_CONNECTOR],
+ "--name is part of --connector-configuration",
+ ],
+ [
+ "knowledge base with complete connector JSON",
+ [
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ COMPLETE_CONNECTOR,
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ],
+ "--knowledge-base cannot be combined",
+ ],
+ [
+ "shortcut without name",
+ ["--gateway", "tools", "--connector", "web-search"],
+ "required option '--name",
+ ],
+ [
+ "knowledge base with Web Search",
+ [
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ],
+ "--knowledge-base requires --connector bedrock-knowledge-bases",
+ ],
+ [
+ "Knowledge Base connector without Knowledge Base",
+ ["--gateway", "tools", "--name", "knowledge", "--connector", "bedrock-knowledge-bases"],
+ "requires --knowledge-base",
+ ],
+ ])("rejects %s", async (_label, flags, message) => {
+ await inProject();
+ await addGateway();
+ await expect(run(["add", "gateway-connector", ...flags])).rejects.toThrow(message);
+ });
+});

src/core/project/manager.tsx

@@ -153,18 +153,37 @@ export class FsProjectManager implements ProjectManager {
  const existingProjectSpec = await this.json.read(agentCoreSpecPath, ProjectSpecSchema);
 
  const existingResources = existingProjectSpec[projectSpecKey];
- if (existingResources.find((r) => r.name === resourceConfig.name))
+ if (resourceType === "gateway-target") {
+ // Current L3 outputs are keyed only by Target name, so names must remain
+ // project-unique until those outputs include the parent Gateway.
+ const gateway = existingProjectSpec.agentCoreGateways.find((candidate) =>
+ candidate.targets.some((target) => target.name === resourceConfig.name),
+ );
+ if (gateway) {
+ throw new InputValidationError(
+ `a gateway target with name '${resourceConfig.name}' already exists in gateway '${gateway.name}'`,
+ );
+ }
+ if (
+ existingProjectSpec.unassignedTargets?.some((target) => target.name === resourceConfig.name)
+ ) {
+ throw new InputValidationError(
+ `an unassigned gateway target with name '${resourceConfig.name}' already exists`,
+ );
+ }
+ } else if (existingResources.find((resource) => resource.name === resourceConfig.name)) {
  throw new InputValidationError(
  `a ${resourceType} with name '${resourceConfig.name}' already exists`,
  );
+ }
 
  // Widened: arms push their own shapes; the whole-spec safeParse below validates.
  const newResources: unknown[] = [...existingResources];
  const scaffoldedPaths: string[] = [];
  // Non-file work that a failed spec write must also reverse.
  let envFile: EnvLocalFile | undefined;
 
- switch (resourceType) {
+ switch (input.resourceType) {
  case "harness": {
  yield { message: `Scaffolding harness in project` };
  const outputPath = join(project.rootPath, "app", resourceConfig.name);
@@ -202,9 +221,25 @@ export class FsProjectManager implements ProjectManager {
  case "online-eval":
  case "online-insight":
  case "memory":
+ case "gateway":
  newResources.push(resourceConfig);
  break;
-
+ case "gateway-target": {
+ const gatewayIndex = existingProjectSpec.agentCoreGateways.findIndex(
+ (gateway) => gateway.name === input.gatewayName,
+ );
+ if (gatewayIndex < 0) {
+ throw new InputValidationError(
+ `gateway '${input.gatewayName}' does not exist in this project; check agentCoreGateways in agentcore.json`,
+ );
+ }
+ const gateway = existingProjectSpec.agentCoreGateways[gatewayIndex]!;
+ newResources[gatewayIndex] = {
+ ...gateway,
+ targets: [...gateway.targets, resourceConfig],
+ };
+ break;
+ }
  default: {
  const unhandled: never = input;
  throw new NotImplementedError(`unsupported project resource: ${String(unhandled)}`);
@@ -260,22 +295,34 @@ export class FsProjectManager implements ProjectManager {
 
  public async removeResource(project: Project, input: RemoveResourceInput): Promise<Project> {
  const agentCoreSpecPath = this.getProjectSpecPath(project);
- const projectSpecKey = toProjectSpecKey(input.resourceType);
-
  const existingProjectSpec = await this.json.read(agentCoreSpecPath, ProjectSpecSchema);
 
- const existingResources = existingProjectSpec[projectSpecKey];
- const newResources = existingResources.filter((r) => r.name !== input.name);
+ let removed = false;
+ let newSpec: unknown;
+ if (input.resourceType === "gateway-target") {
+ const gateways = [...existingProjectSpec.agentCoreGateways];
+ const gatewayIndex = gateways.findIndex((gateway) => gateway.name === input.gatewayName);
+ if (gatewayIndex >= 0) {
+ const gateway = gateways[gatewayIndex]!;
+ const targets = gateway.targets.filter((target) => target.name !== input.name);
+ removed = targets.length !== gateway.targets.length;
+ gateways[gatewayIndex] = { ...gateway, targets };
+ }
+ newSpec = { ...existingProjectSpec, agentCoreGateways: gateways };
+ } else {
+ const projectSpecKey = toProjectSpecKey(input.resourceType);
+ const existingResources = existingProjectSpec[projectSpecKey];
+ const newResources = existingResources.filter((resource) => resource.name !== input.name);
+ removed = newResources.length !== existingResources.length;
+ newSpec = { ...existingProjectSpec, [projectSpecKey]: newResources };
+ }
 
- if (newResources.length === existingResources.length)
+ if (!removed)
  this.logger
  .child({ input })
  .warn(`unable to remove resource from project that does not exist.`);
 
- const newSpecParseResult = ProjectSpecSchema.safeParse({
- ...existingProjectSpec,
- [projectSpecKey]: newResources,
- });
+ const newSpecParseResult = ProjectSpecSchema.safeParse(newSpec);
 
  if (!newSpecParseResult.success)
  throw new InputValidationError(z.prettifyError(newSpecParseResult.error), {
@@ -385,5 +432,8 @@ function toProjectSpecKey(resourceType: ProjectResource) {
  return "onlineEvalConfigs";
  case "memory":
  return "memories";
+ case "gateway":
+ case "gateway-target":
+ return "agentCoreGateways";
  }
 }

src/handlers/project/add/gateway-connector/index.test.ts

@@ -0,0 +1,168 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createGatewayProjectTestHarness } from "../gateway-test-support";
+
+const COMPLETE_CONNECTOR = JSON.stringify({
+ name: "configured",
+ targetType: "connector",
+ connectorId: "web-search",
+});
+
+const { addGateway, cleanup, inProject, projectSpec, run } =
+ createGatewayProjectTestHarness("gateway-connector");
+
+afterEach(cleanup);
+
+describe("project add gateway-connector", () => {
+ test("adds Web Search and external Knowledge Base connectors", async () => {
+ const projectRoot = await inProject();
+ await addGateway();
+
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ ]);
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--name",
+ "knowledge",
+ "--connector",
+ "bedrock-knowledge-bases",
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ]);
+
+ expect((await projectSpec(projectRoot)).agentCoreGateways[0].targets).toEqual([
+ {
+ name: "web",
+ targetType: "connector",
+ connectorId: "web-search",
+ configurations: [{ name: "WebSearch", parameterValues: { maxResults: 10 } }],
+ },
+ {
+ name: "knowledge",
+ targetType: "connector",
+ connectorId: "bedrock-knowledge-bases",
+ configurations: [{ name: "Retrieve", parameterValues: { knowledgeBaseId: "ABCDEFGHIJ" } }],
+ },
+ ]);
+ });
+
+ test("reads a complete connector Target from a file", async () => {
+ const projectRoot = await inProject();
+ await addGateway();
+ const target = {
+ name: "configured",
+ targetType: "connector",
+ connectorId: "web-search",
+ configurations: [{ name: "WebSearch", parameterValues: { maxResults: 3 } }],
+ };
+ const path = join(projectRoot, "connector.json");
+ await writeFile(path, JSON.stringify(target));
+
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ `file://${path}`,
+ ]);
+
+ expect((await projectSpec(projectRoot)).agentCoreGateways[0].targets[0]).toEqual(target);
+ });
+
+ test("rejects a non-connector project Target", async () => {
+ await inProject();
+ await addGateway();
+
+ await expect(
+ run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ '{"name":"server","targetType":"mcpServer","endpoint":"https://mcp.example.com"}',
+ ]),
+ ).rejects.toThrow('targetType: "connector"');
+ });
+
+ test.each([
+ [
+ "missing parent Gateway",
+ ["--name", "web", "--connector", "web-search"],
+ "required option '--gateway",
+ ],
+ ["no connector mode", ["--gateway", "tools", "--name", "web"], "specify exactly one"],
+ [
+ "both connector modes",
+ [
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ "--connector-configuration",
+ COMPLETE_CONNECTOR,
+ ],
+ "specify exactly one",
+ ],
+ [
+ "name with complete connector JSON",
+ ["--gateway", "tools", "--name", "web", "--connector-configuration", COMPLETE_CONNECTOR],
+ "--name is part of --connector-configuration",
+ ],
+ [
+ "knowledge base with complete connector JSON",
+ [
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ COMPLETE_CONNECTOR,
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ],
+ "--knowledge-base cannot be combined",
+ ],
+ [
+ "shortcut without name",
+ ["--gateway", "tools", "--connector", "web-search"],
+ "required option '--name",
+ ],
+ [
+ "knowledge base with Web Search",
+ [
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ],
+ "--knowledge-base requires --connector bedrock-knowledge-bases",
+ ],
+ [
+ "Knowledge Base connector without Knowledge Base",
+ ["--gateway", "tools", "--name", "knowledge", "--connector", "bedrock-knowledge-bases"],
+ "requires --knowledge-base",
+ ],
+ ])("rejects %s", async (_label, flags, message) => {
+ await inProject();
+ await addGateway();
+ await expect(run(["add", "gateway-connector", ...flags])).rejects.toThrow(message);
+ });
+});

src/core/project/manager.tsx

@@ -153,18 +153,37 @@ export class FsProjectManager implements ProjectManager {
  const existingProjectSpec = await this.json.read(agentCoreSpecPath, ProjectSpecSchema);
 
  const existingResources = existingProjectSpec[projectSpecKey];
- if (existingResources.find((r) => r.name === resourceConfig.name))
+ if (resourceType === "gateway-target") {
+ // Current L3 outputs are keyed only by Target name, so names must remain
+ // project-unique until those outputs include the parent Gateway.
+ const gateway = existingProjectSpec.agentCoreGateways.find((candidate) =>
+ candidate.targets.some((target) => target.name === resourceConfig.name),
+ );
+ if (gateway) {
+ throw new InputValidationError(
+ `a gateway target with name '${resourceConfig.name}' already exists in gateway '${gateway.name}'`,
+ );
+ }
+ if (
+ existingProjectSpec.unassignedTargets?.some((target) => target.name === resourceConfig.name)
+ ) {
+ throw new InputValidationError(
+ `an unassigned gateway target with name '${resourceConfig.name}' already exists`,
+ );
+ }
+ } else if (existingResources.find((resource) => resource.name === resourceConfig.name)) {
  throw new InputValidationError(
  `a ${resourceType} with name '${resourceConfig.name}' already exists`,
  );
+ }
 
  // Widened: arms push their own shapes; the whole-spec safeParse below validates.
  const newResources: unknown[] = [...existingResources];
  const scaffoldedPaths: string[] = [];
  // Non-file work that a failed spec write must also reverse.
  let envFile: EnvLocalFile | undefined;
 
- switch (resourceType) {
+ switch (input.resourceType) {
  case "harness": {
  yield { message: `Scaffolding harness in project` };
  const outputPath = join(project.rootPath, "app", resourceConfig.name);
@@ -202,9 +221,25 @@ export class FsProjectManager implements ProjectManager {
  case "online-eval":
  case "online-insight":
  case "memory":
+ case "gateway":
  newResources.push(resourceConfig);
  break;
-
+ case "gateway-target": {
+ const gatewayIndex = existingProjectSpec.agentCoreGateways.findIndex(
+ (gateway) => gateway.name === input.gatewayName,
+ );
+ if (gatewayIndex < 0) {
+ throw new InputValidationError(
+ `gateway '${input.gatewayName}' does not exist in this project; check agentCoreGateways in agentcore.json`,
+ );
+ }
+ const gateway = existingProjectSpec.agentCoreGateways[gatewayIndex]!;
+ newResources[gatewayIndex] = {
+ ...gateway,
+ targets: [...gateway.targets, resourceConfig],
+ };
+ break;
+ }
  default: {
  const unhandled: never = input;
  throw new NotImplementedError(`unsupported project resource: ${String(unhandled)}`);
@@ -260,22 +295,34 @@ export class FsProjectManager implements ProjectManager {
 
  public async removeResource(project: Project, input: RemoveResourceInput): Promise<Project> {
  const agentCoreSpecPath = this.getProjectSpecPath(project);
- const projectSpecKey = toProjectSpecKey(input.resourceType);
-
  const existingProjectSpec = await this.json.read(agentCoreSpecPath, ProjectSpecSchema);
 
- const existingResources = existingProjectSpec[projectSpecKey];
- const newResources = existingResources.filter((r) => r.name !== input.name);
+ let removed = false;
+ let newSpec: unknown;
+ if (input.resourceType === "gateway-target") {
+ const gateways = [...existingProjectSpec.agentCoreGateways];
+ const gatewayIndex = gateways.findIndex((gateway) => gateway.name === input.gatewayName);
+ if (gatewayIndex >= 0) {
+ const gateway = gateways[gatewayIndex]!;
+ const targets = gateway.targets.filter((target) => target.name !== input.name);
+ removed = targets.length !== gateway.targets.length;
+ gateways[gatewayIndex] = { ...gateway, targets };
+ }
+ newSpec = { ...existingProjectSpec, agentCoreGateways: gateways };
+ } else {
+ const projectSpecKey = toProjectSpecKey(input.resourceType);
+ const existingResources = existingProjectSpec[projectSpecKey];
+ const newResources = existingResources.filter((resource) => resource.name !== input.name);
+ removed = newResources.length !== existingResources.length;
+ newSpec = { ...existingProjectSpec, [projectSpecKey]: newResources };
+ }
 
- if (newResources.length === existingResources.length)
+ if (!removed)
  this.logger
  .child({ input })
  .warn(`unable to remove resource from project that does not exist.`);
 
- const newSpecParseResult = ProjectSpecSchema.safeParse({
- ...existingProjectSpec,
- [projectSpecKey]: newResources,
- });
+ const newSpecParseResult = ProjectSpecSchema.safeParse(newSpec);
 
  if (!newSpecParseResult.success)
  throw new InputValidationError(z.prettifyError(newSpecParseResult.error), {
@@ -385,5 +432,8 @@ function toProjectSpecKey(resourceType: ProjectResource) {
  return "onlineEvalConfigs";
  case "memory":
  return "memories";
+ case "gateway":
+ case "gateway-target":
+ return "agentCoreGateways";
  }
 }

src/handlers/project/add/gateway-connector/index.test.ts

@@ -0,0 +1,168 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { createGatewayProjectTestHarness } from "../gateway-test-support";
+
+const COMPLETE_CONNECTOR = JSON.stringify({
+ name: "configured",
+ targetType: "connector",
+ connectorId: "web-search",
+});
+
+const { addGateway, cleanup, inProject, projectSpec, run } =
+ createGatewayProjectTestHarness("gateway-connector");
+
+afterEach(cleanup);
+
+describe("project add gateway-connector", () => {
+ test("adds Web Search and external Knowledge Base connectors", async () => {
+ const projectRoot = await inProject();
+ await addGateway();
+
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ ]);
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--name",
+ "knowledge",
+ "--connector",
+ "bedrock-knowledge-bases",
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ]);
+
+ expect((await projectSpec(projectRoot)).agentCoreGateways[0].targets).toEqual([
+ {
+ name: "web",
+ targetType: "connector",
+ connectorId: "web-search",
+ configurations: [{ name: "WebSearch", parameterValues: { maxResults: 10 } }],
+ },
+ {
+ name: "knowledge",
+ targetType: "connector",
+ connectorId: "bedrock-knowledge-bases",
+ configurations: [{ name: "Retrieve", parameterValues: { knowledgeBaseId: "ABCDEFGHIJ" } }],
+ },
+ ]);
+ });
+
+ test("reads a complete connector Target from a file", async () => {
+ const projectRoot = await inProject();
+ await addGateway();
+ const target = {
+ name: "configured",
+ targetType: "connector",
+ connectorId: "web-search",
+ configurations: [{ name: "WebSearch", parameterValues: { maxResults: 3 } }],
+ };
+ const path = join(projectRoot, "connector.json");
+ await writeFile(path, JSON.stringify(target));
+
+ await run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ `file://${path}`,
+ ]);
+
+ expect((await projectSpec(projectRoot)).agentCoreGateways[0].targets[0]).toEqual(target);
+ });
+
+ test("rejects a non-connector project Target", async () => {
+ await inProject();
+ await addGateway();
+
+ await expect(
+ run([
+ "add",
+ "gateway-connector",
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ '{"name":"server","targetType":"mcpServer","endpoint":"https://mcp.example.com"}',
+ ]),
+ ).rejects.toThrow('targetType: "connector"');
+ });
+
+ test.each([
+ [
+ "missing parent Gateway",
+ ["--name", "web", "--connector", "web-search"],
+ "required option '--gateway",
+ ],
+ ["no connector mode", ["--gateway", "tools", "--name", "web"], "specify exactly one"],
+ [
+ "both connector modes",
+ [
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ "--connector-configuration",
+ COMPLETE_CONNECTOR,
+ ],
+ "specify exactly one",
+ ],
+ [
+ "name with complete connector JSON",
+ ["--gateway", "tools", "--name", "web", "--connector-configuration", COMPLETE_CONNECTOR],
+ "--name is part of --connector-configuration",
+ ],
+ [
+ "knowledge base with complete connector JSON",
+ [
+ "--gateway",
+ "tools",
+ "--connector-configuration",
+ COMPLETE_CONNECTOR,
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ],
+ "--knowledge-base cannot be combined",
+ ],
+ [
+ "shortcut without name",
+ ["--gateway", "tools", "--connector", "web-search"],
+ "required option '--name",
+ ],
+ [
+ "knowledge base with Web Search",
+ [
+ "--gateway",
+ "tools",
+ "--name",
+ "web",
+ "--connector",
+ "web-search",
+ "--knowledge-base",
+ "ABCDEFGHIJ",
+ ],
+ "--knowledge-base requires --connector bedrock-knowledge-bases",
+ ],
+ [
+ "Knowledge Base connector without Knowledge Base",
+ ["--gateway", "tools", "--name", "knowledge", "--connector", "bedrock-knowledge-bases"],
+ "requires --knowledge-base",
+ ],
+ ])("rejects %s", async (_label, flags, message) => {
+ await inProject();
+ await addGateway();
+ await expect(run(["add", "gateway-connector", ...flags])).rejects.toThrow(message);
+ });
+});