feat(project): implement add functionality.

src/core/project/manager.test.ts

@@ -180,7 +180,7 @@ describe("FsProjectManager.create", () => {
     ]);
     expect(project.name).toBe("example");
     expect(project.rootPath).toContain("example");
-    expect(project.runtimes).toHaveLength(1);
+    expect(project.spec.runtimes).toHaveLength(1);
   });
 
   test("a failed step propagates and leaves the scaffolded files in place", async () => {
@@ -280,7 +280,10 @@ describe("FsProjectManager.build", () => {
     commands.length = 0;
 
     // CDK is the only backend today; the cast stands in for a future one.
-    const foreign = { ...project, managedBy: "Terraform" as Project["managedBy"] };
+    const foreign = {
+      ...project,
+      spec: { ...project.spec, managedBy: "Terraform" as Project["spec"]["managedBy"] },
+    };
     await expect(drain(subject.build(foreign))).rejects.toThrow(/unsupported backend: Terraform/);
     expect(commands).toEqual([]);
   });
@@ -312,8 +315,8 @@ describe("FsProjectManager.resolve", () => {
 
     expect(resolved?.name).toBe("example");
     expect(resolved?.rootPath).toBe(join(root, "example"));
-    expect(resolved?.managedBy).toBe("CDK");
-    expect(resolved?.runtimes).toHaveLength(1);
+    expect(resolved?.spec.managedBy).toBe("CDK");
+    expect(resolved?.spec.runtimes).toHaveLength(1);
   });
 
   test("returns undefined when no project encloses the path", async () => {

src/core/project/manager.tsx

@@ -1,13 +1,14 @@
 import { existsSync } from "node:fs";
-import { join } from "node:path";
+import { copyFile, rm } from "node:fs/promises";
+import { join, relative } from "node:path";
 import type {
+  AddResourceInput,
   CreateProjectInput,
   ResolveProjectInput,
   Project,
   ProjectManager,
   ProjectEvent,
   ProjectResource,
-  ProjectResourceConfig,
 } from "../../handlers/project/types";
 import type { Logger } from "../../logging";
 import {
@@ -18,15 +19,18 @@ import {
   type ReadWriteJson,
 } from "../../io";
 import { defaultSource, type AssetSource } from "./source";
-import { createProjectTreeFromTemplate, TEMPLATES } from "./templates";
+import { createHarnessTreeFromSpec, createProjectTreeFromTemplate, TEMPLATES } from "./templates";
 import { ProjectSpecSchema } from "../../projectSchemas/project";
 import { enclosingProjectRoot } from "./fsUtils";
 import {
+  AgentCoreCLIError,
   DeserializationError,
   InputValidationError,
   NotImplementedError,
   ProjectStateError,
 } from "../../errors/errors";
+import type { HarnessSpecSchema } from "../../projectSchemas/harness";
+import type z from "zod";
 
 type ProjectManagerConfig = {
   logger: Logger;
@@ -64,8 +68,7 @@ export class FsProjectManager implements ProjectManager {
       return {
         name: spec.name,
         rootPath,
-        managedBy: spec.managedBy,
-        runtimes: spec.runtimes,
+        spec,
       };
     } catch (error) {
       // A malformed agentcore.json is a user-correctable problem, not a crash.
@@ -130,26 +133,111 @@ export class FsProjectManager implements ProjectManager {
     return project;
   }
 
-  // eslint-disable-next-line require-yield
-  public async *addResource<TResource extends ProjectResource>(
-    _project: Project,
-    _resourceType: TResource,
-    _resourceConfig: ProjectResourceConfig<TResource>,
+  public async *addResource(
+    project: Project,
+    input: AddResourceInput,
   ): AsyncGenerator<ProjectEvent, Project> {
-    throw new NotImplementedError("FsProjectManager.addResource is not yet implemented");
+    const { resourceType, resourceConfig } = input;
+    const agentCoreSpecPath = join(project.rootPath, "agentcore", "agentcore.json");
+    const projectSpecKey = toProjectSpecKey(resourceType);
+
+    yield { message: `Reading project spec file at '${agentCoreSpecPath}'` };
+    const existingProjectSpec = await this.json.read(agentCoreSpecPath, ProjectSpecSchema);
+
+    const existingResources = existingProjectSpec[projectSpecKey];
+    if (existingResources.find((r) => r.name === resourceConfig.name))
+      throw new InputValidationError(
+        `a ${resourceType} with name '${resourceConfig.name}' already exists`,
+      );
+
+    const newResources = [...existingResources];
+    const scaffoldedPaths: string[] = [];
+
+    switch (resourceType) {
+      case "harness": {
+        yield { message: `Scaffolding harness in project` };
+        const outputPath = join(project.rootPath, "app", resourceConfig.name);
+        scaffoldedPaths.push(outputPath);
+        const harnessPath = await this.scaffoldHarness(outputPath, input.resourceConfig);
+
+        newResources.push({
+          name: input.resourceConfig.name,
+          path: relative(project.rootPath, harnessPath),
+        });
+        break;
+      }
+      case "runtime": {
+        throw new NotImplementedError(
+          "runtime case not yet implemented in FsProjectManager.addResource",
+        );
+      }
+      // TODO: add limited special casing for runtime and default for other resources that proxy directly to spec changes.
+    }
+
+    yield { message: `Updating project spec file at '${agentCoreSpecPath}'` };
+
+    // rollback scaffolding changes on failed config writes to prevent bad state.
+    try {
+      const newProjectSpec = await this.json.write(agentCoreSpecPath, {
+        ...existingProjectSpec,
+        [projectSpecKey]: newResources,
+      });
+
+      return {
+        ...project,
+        spec: newProjectSpec,
+      };
+    } catch (err) {
+      this.logger.warn(
+        `failed to update ${agentCoreSpecPath}; attempting best-effort cleanup of scaffolded files`,
+      );
+      await Promise.all(
+        scaffoldedPaths.map((p) =>
+          rm(p, { recursive: true, force: true }).catch((e) => {
+            const error = AgentCoreCLIError.fromError(e);
+            this.logger
+              .child({ errorName: error.name, errorMessage: error.message })
+              .warn(`failed to clean up ${p}`);
+          }),
+        ),
+      );
+      throw err;
+    }
+  }
+
+  private async scaffoldHarness(
+    outputPath: string,
+    harnessSpec: z.input<typeof HarnessSpecSchema>,
+  ): Promise<string> {
+    const harness = await createHarnessTreeFromSpec({
+      ...harnessSpec,
+      dockerfile: harnessSpec.dockerfile ? "Dockerfile" : undefined,
+    });
+
+    if (harnessSpec.dockerfile) {
+      if (!existsSync(harnessSpec.dockerfile))
+        throw new InputValidationError(`dockerfile not found: '${harnessSpec.dockerfile}'`);
+    }
+
+    await harness.write(outputPath);
+
+    if (harnessSpec.dockerfile) {
+      await copyFile(harnessSpec.dockerfile, join(outputPath, "Dockerfile"));
+    }
+    return outputPath;
   }
 
   public async *build(project: Project): AsyncGenerator<ProjectEvent, void> {
     // agentcore.json records which backend owns the project's artifacts. CDK is the
     // only one today; a terraform or no-IaC backend adds an arm here rather than
     // editing the CDK path.
-    switch (project.managedBy) {
+    switch (project.spec.managedBy) {
       case "CDK":
         yield* this.buildWithCdk(project);
         break;
       default: {
         // Exhaustiveness: a new ManagedBy member fails to compile until it is handled.
-        const unsupported: never = project.managedBy;
+        const unsupported: never = project.spec.managedBy;
         throw new ProjectStateError(
           `project '${project.name}' declares an unsupported backend: ${String(unsupported)}`,
         );
@@ -183,3 +271,15 @@ export class FsProjectManager implements ProjectManager {
     return this.runner(command, { cwd, onOutput: (chunk) => this.logger.debug(chunk) });
   }
 }
+
+/** Map {@link ProjectResource} to keys in the project spec.
+ * Note: we let TS infer the return type to avoid pulling in keys that do not correspond to resources (ex. name, managedBy, etc.)
+ */
+function toProjectSpecKey(resourceType: ProjectResource) {
+  switch (resourceType) {
+    case "harness":
+      return "harnesses";
+    case "runtime":
+      return "runtimes";
+  }
+}

src/core/project/templates.ts

@@ -1,6 +1,9 @@
+import { ZodError, z } from "zod";
 import { PROJECT_TEMPLATES, type ProjectTemplate } from "../../handlers/project/types";
+import { HarnessSpecSchema } from "../../projectSchemas/harness";
 import { FsTreeNode } from "./fsTree";
 import type { AssetSource } from "./source";
+import { InputValidationError } from "../../errors/errors";
 
 type TemplateSpec = {
   runtimes?: unknown[];
@@ -90,3 +93,30 @@ export async function createProjectTreeFromTemplate(
     FsTreeNode.createDirectory("app", [await FsTreeNode.fromAssetSource(src, assetDir, appDir)]),
   ]);
 }
+
+const DEFAULT_HARNESS_SYSTEM_PROMPT = "You are a helpful assistant";
+
+export async function createHarnessTreeFromSpec(
+  spec: z.input<typeof HarnessSpecSchema>,
+): Promise<FsTreeNode> {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { systemPrompt, ...rest } = spec;
+  // strip system prompt such that markdown file is source of truth.
+  const parsed = parseHarnessSpec(rest);
+  return FsTreeNode.createDirectory(".", [
+    FsTreeNode.createFile("harness.json", async () => json(parsed)),
+    FsTreeNode.createFile(
+      "system-prompt.md",
+      async () => spec.systemPrompt ?? DEFAULT_HARNESS_SYSTEM_PROMPT,
+    ),
+  ]);
+}
+
+function parseHarnessSpec(spec: z.input<typeof HarnessSpecSchema>) {
+  try {
+    return HarnessSpecSchema.parse(spec);
+  } catch (err) {
+    if (err instanceof ZodError) throw new InputValidationError(z.prettifyError(err));
+    throw err;
+  }
+}

src/core/types.tsx

@@ -37,7 +37,7 @@ export type CoreFetch = (
 // full ClientConfig so callers can request any client customization (region,
 // endpoint, ...).
 export interface AwsClients {
-  control(config: ClientConfig): BedrockAgentCoreControlClient
+  control(config: ClientConfig): BedrockAgentCoreControlClient;
   data(config: ClientConfig): BedrockAgentCoreClient;
   iam(config: ClientConfig): IAMClient;
   // logs reads the CloudWatch Logs streams AgentCore writes batch-evaluation

src/handlers/eval/ondemand/ondemand.test.tsx

@@ -24,7 +24,9 @@ const TRACE: SessionTrace = {
 const RESULT: EvaluateResult = {
   sessionsRequested: 1,
   sessionsEvaluated: 1,
-  results: [{ evaluatorId: "Builtin.Helpfulness", value: 0.9 } as EvaluateResult["results"][number]],
+  results: [
+    { evaluatorId: "Builtin.Helpfulness", value: 0.9 } as EvaluateResult["results"][number],
+  ],
 };
 
 async function run(args: string[], configure?: (core: TestCoreClient) => void) {

src/handlers/project/add/harness/index.ts

@@ -7,13 +7,15 @@ import type {
   AuthorizerConfiguration as SdkAuthorizerConfiguration,
   HarnessEnvironmentArtifact,
   HarnessEnvironmentProviderRequest,
+  HarnessGatewayOutboundAuth as SdkHarnessGatewayOutboundAuth,
   HarnessMemoryConfiguration as SdkMemoryConfiguration,
   HarnessModelConfiguration,
   HarnessSkill as SdkHarnessSkill,
   HarnessTool as SdkHarnessTool,
   HarnessTruncationConfiguration as SdkTruncationConfiguration,
 } from "@aws-sdk/client-bedrock-agentcore-control";
 import type {
+  HarnessGatewayOutboundAuth,
   HarnessMemoryRef,
   HarnessModel,
   HarnessSkill,
@@ -82,6 +84,11 @@ export const createAddHarnessHandler = (config: AddProjectResourceConfig) =>
         "path to local dockerfile to use as the container image for the harness",
         z.string().optional(),
       ),
+      flag(
+        "vpc-id",
+        "VPC ID for Dockerfile builds in VPC mode (required when combining --dockerfile with VPC networking)",
+        z.string().optional(),
+      ),
     ],
     handle: async (ctx, flags) => {
       if (!flags.name)
@@ -110,9 +117,17 @@ export const createAddHarnessHandler = (config: AddProjectResourceConfig) =>
       const env = inputEnvironment ? toEnvironment(inputEnvironment) : undefined;
       const artifact = inputArtifact ? toEnvironmentArtifact(inputArtifact) : undefined;
 
+      const inputVpcId = flags["vpc-id"];
+
       if (inputArtifact?.containerConfiguration?.containerUri && flags.dockerfile)
         throw new InputValidationError(`containerUri and dockerfile are mutually exclusive`);
 
+      if (inputVpcId && !env?.networkConfig) {
+        throw new InputValidationError(
+          "--vpc-id requires --environment with VPC network configuration",
+        );
+      }
+
       const harnessConfig = {
         name: flags.name,
         model: inputModelConfig
@@ -136,7 +151,9 @@ export const createAddHarnessHandler = (config: AddProjectResourceConfig) =>
         timeoutSeconds: flags["timeout-seconds"],
         tags: parseJsonFlag<Record<string, string>>("tags", flags["tags"]),
         networkMode: env?.networkMode,
-        networkConfig: env?.networkConfig,
+        networkConfig: env?.networkConfig
+          ? { ...env.networkConfig, ...(inputVpcId ? { vpcId: inputVpcId } : {}) }
+          : undefined,
         lifecycleConfig: env?.lifecycleConfig,
         sessionStoragePath: env?.sessionStoragePath,
         efsAccessPoints: env?.efsAccessPoints,
@@ -146,11 +163,10 @@ export const createAddHarnessHandler = (config: AddProjectResourceConfig) =>
       };
 
       const project = ctx.require(ProjectKey);
-      for await (const event of config.projectManager.addResource(
-        project,
-        "harness",
-        harnessConfig,
-      )) {
+      for await (const event of config.projectManager.addResource(project, {
+        resourceType: "harness",
+        resourceConfig: harnessConfig,
+      })) {
         config.io.stderr.write(`${event.message}\n`);
       }
 
@@ -233,6 +249,9 @@ function toTool(tool: SdkHarnessTool): HarnessTool {
       config: {
         agentCoreGateway: {
           gatewayArn: requireField(c.agentCoreGateway.gatewayArn, "agentCoreGateway.gatewayArn"),
+          outboundAuth: c.agentCoreGateway.outboundAuth
+            ? toOutboundAuth(c.agentCoreGateway.outboundAuth)
+            : undefined,
         },
       },
     };
@@ -263,6 +282,27 @@ function toTool(tool: SdkHarnessTool): HarnessTool {
   return { type: tool.type, name: tool.name };
 }
 
+/** Converts an SDK HarnessGatewayOutboundAuth tagged union into the project-schema shape. */
+function toOutboundAuth(auth: SdkHarnessGatewayOutboundAuth): HarnessGatewayOutboundAuth {
+  if ("awsIam" in auth && auth.awsIam) return { awsIam: {} };
+  if ("none" in auth && auth.none) return { none: {} };
+  if ("oauth" in auth && auth.oauth) {
+    return {
+      oauth: {
+        providerArn: requireField(auth.oauth.providerArn, "outboundAuth.oauth.providerArn"),
+        scopes: requireField(auth.oauth.scopes, "outboundAuth.oauth.scopes"),
+        // SDK does not expose this type directly.
+        grantType: auth.oauth.grantType as Extract<
+          HarnessGatewayOutboundAuth,
+          { oauth: unknown }
+        >["oauth"]["grantType"],
+        customParameters: auth.oauth.customParameters,
+      },
+    };
+  }
+  throw new InputValidationError("unrecognized outboundAuth variant");
+}
+
 /** Converts an SDK HarnessSkill tagged union into the project-schema shape. */
 function toSkill(skill: SdkHarnessSkill): HarnessSkill {
   if ("path" in skill && skill.path) {
@@ -277,7 +317,7 @@ function toSkill(skill: SdkHarnessSkill): HarnessSkill {
       path: skill.git.path,
       auth: skill.git.auth
         ? {
-            credentialName: requireField(
+            credentialArn: requireField(
               skill.git.auth.credentialArn,
               "skill.git.auth.credentialArn",
             ),