fix(project): validate runtimeVersion on CodeZip runtimes

src/core/project/manager.test.ts

@@ -333,4 +333,29 @@ describe("FsProjectManager.resolve", () => {
       DeserializationError,
     );
   });
+
+  test("names the offending field when the spec fails validation", async () => {
+    const root = await inTempDirectory();
+    await mkdir(join(root, "agentcore"), { recursive: true });
+    // Valid JSON, invalid spec: a CodeZip runtime with no runtimeVersion.
+    await writeFile(
+      join(root, "agentcore", "agentcore.json"),
+      JSON.stringify({
+        name: "example",
+        version: 1,
+        runtimes: [
+          {
+            name: "hello_world",
+            build: "CodeZip",
+            entrypoint: "main.py",
+            codeLocation: "app/hello-world",
+          },
+        ],
+      }),
+    );
+
+    await expect(manager().manager.resolve({ filePath: root })).rejects.toThrow(
+      "runtimeVersion is required for CodeZip builds",
+    );
+  });
 });

src/errors/errors.tsx

@@ -108,8 +108,18 @@ export class SourceResolutionError extends InputValidationError {
 }
 
 export class DeserializationError extends AgentCoreCLIError {
-  constructor(path: string, options?: Omit<AgentCoreCLIErrorOptions, "source">) {
-    super(`Failed to deserialize file at "${path}"`, { ...options, source: ERROR_SOURCE.USER });
+  constructor(
+    path: string,
+    options?: Omit<AgentCoreCLIErrorOptions, "source"> & {
+      /** Rendered reasons the payload was rejected, appended so the user sees which field to fix. */
+      detail?: string;
+    },
+  ) {
+    const detail = options?.detail ? `\n${options.detail}` : "";
+    super(`Failed to deserialize file at "${path}"${detail}`, {
+      ...options,
+      source: ERROR_SOURCE.USER,
+    });
     this.name = "DeserializationError";
   }
 }

src/io/json.ts

@@ -2,6 +2,7 @@ import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 
 import type z from "zod";
+import { prettifyError } from "zod";
 
 import { DeserializationError } from "../errors";
 import type { Logger } from "../logging";
@@ -52,7 +53,10 @@ export class FsReadWriteJson implements ReadWriteJson {
           errorMessage: parseResult.error.message,
         })
         .error(`failed to validate parsed json file`);
-      throw new DeserializationError(filePath, { cause: parseResult.error });
+      throw new DeserializationError(filePath, {
+        cause: parseResult.error,
+        detail: prettifyError(parseResult.error),
+      });
     }
 
     return parseResult.data;

src/projectSchemas/project.test.ts

@@ -8,6 +8,7 @@ const runtime = {
   build: "CodeZip" as const,
   entrypoint: "main.py",
   codeLocation: "./agent",
+  runtimeVersion: "PYTHON_3_12" as const,
   endpoints: { LIVE: { version: 1 } },
 };
 

src/projectSchemas/runtime.test.ts

@@ -11,6 +11,7 @@ const codeZipAgent = {
   build: "CodeZip" as const,
   entrypoint: "main.py",
   codeLocation: "./agent",
+  runtimeVersion: "PYTHON_3_12" as const,
 };
 const containerAgent = {
   name: "agent",
@@ -72,6 +73,15 @@ describe("runtime custom validation", () => {
       }).success,
     ).toBe(false);
   });
+  it("requires runtimeVersion for CodeZip builds only", () => {
+    const { runtimeVersion: _omitted, ...withoutVersion } = codeZipAgent;
+    const result = ProjectRuntimeSchema.safeParse(withoutVersion);
+    expect(result.success).toBe(false);
+    expect(result.error?.issues[0]?.path).toEqual(["runtimeVersion"]);
+
+    // Container builds take their version from the image.
+    expect(ProjectRuntimeSchema.safeParse(containerAgent).success).toBe(true);
+  });
   it("restricts container-only fields to container builds", () => {
     for (const field of [
       { dockerfile: "Dockerfile" },

src/projectSchemas/runtime.ts

@@ -308,6 +308,17 @@ export const ProjectRuntimeSchema = z
         path: ["authorizerConfiguration"],
       });
     }
+    // Mirrors the CDK construct library, which rejects a CodeZip runtime with no
+    // runtimeVersion: it is the field that selects the packager. Validating it here
+    // means the CLI reports it against agentcore.json instead of letting synthesis
+    // fail later with the same rule.
+    if (data.build !== "Container" && !data.runtimeVersion) {
+      ctx.addIssue({
+        code: "custom",
+        message: "runtimeVersion is required for CodeZip builds",
+        path: ["runtimeVersion"],
+      });
+    }
     for (const field of ["dockerfile", "buildContextPath", "customDockerBuildArgs"] as const) {
       if (data.build !== "Container" && data[field]) {
         ctx.addIssue({