feat: add VPC network mode to schema

Fix NetworkModeSchema enum from PUBLIC|PRIVATE to PUBLIC|VPC to match
the AWS API. Add NetworkConfigSchema for subnet and security group
validation, and networkConfig field to AgentEnvSpec with cross-field
validation requiring networkConfig when networkMode is VPC.

Changes:
- Fix NetworkModeSchema enum: PRIVATE → VPC
- Add NetworkConfigSchema (subnet/SG ID regex, min/max array bounds)
- Add networkConfig optional field to AgentEnvSpec
- Add superRefine cross-field validation
- Update LLM-compacted schema documentation
- Add 13 new unit tests for VPC schema validation

Author: tejaskash

src/schema/__tests__/constants.test.ts

@@ -74,12 +74,12 @@ describe('NetworkModeSchema', () => {
     expect(NetworkModeSchema.safeParse('PUBLIC').success).toBe(true);
   });
 
-  it('accepts PRIVATE', () => {
-    expect(NetworkModeSchema.safeParse('PRIVATE').success).toBe(true);
+  it('accepts VPC', () => {
+    expect(NetworkModeSchema.safeParse('VPC').success).toBe(true);
   });
 
   it('rejects other modes', () => {
-    expect(NetworkModeSchema.safeParse('VPC').success).toBe(false);
+    expect(NetworkModeSchema.safeParse('PRIVATE').success).toBe(false);
   });
 });
 

src/schema/constants.ts

@@ -139,5 +139,5 @@ export type NodeRuntime = z.infer<typeof NodeRuntimeSchema>;
 export const RuntimeVersionSchema = z.union([PythonRuntimeSchema, NodeRuntimeSchema]);
 export type RuntimeVersion = z.infer<typeof RuntimeVersionSchema>;
 
-export const NetworkModeSchema = z.enum(['PUBLIC', 'PRIVATE']);
+export const NetworkModeSchema = z.enum(['PUBLIC', 'VPC']);
 export type NetworkMode = z.infer<typeof NetworkModeSchema>;

src/schema/llm-compacted/agentcore.ts

@@ -26,10 +26,19 @@ type BuildType = 'CodeZip' | 'Container';
 type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13';
 type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22';
 type RuntimeVersion = PythonRuntime | NodeRuntime;
-type NetworkMode = 'PUBLIC' | 'PRIVATE';
+type NetworkMode = 'PUBLIC' | 'VPC';
 type MemoryStrategyType = 'SEMANTIC' | 'SUMMARIZATION' | 'USER_PREFERENCE';
 type ModelProvider = 'Bedrock' | 'Gemini' | 'OpenAI' | 'Anthropic';
 
+// ─────────────────────────────────────────────────────────────────────────────
+// NETWORK CONFIG
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface NetworkConfig {
+  subnets: string[]; // @regex ^subnet-[0-9a-zA-Z]{8,17}$ @min 1 @max 16
+  securityGroups: string[]; // @regex ^sg-[0-9a-zA-Z]{8,17}$ @min 1 @max 16
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // AGENT
 // ─────────────────────────────────────────────────────────────────────────────
@@ -43,6 +52,7 @@ interface AgentEnvSpec {
   runtimeVersion: RuntimeVersion;
   envVars?: EnvVar[];
   networkMode?: NetworkMode; // default 'PUBLIC'
+  networkConfig?: NetworkConfig; // Required when networkMode is 'VPC'
   instrumentation?: Instrumentation; // OTel settings
   modelProvider?: ModelProvider; // Model provider used by this agent
 }

src/schema/llm-compacted/mcp.ts

@@ -145,4 +145,4 @@ interface IamPolicyDocument {
 type GatewayTargetType = 'lambda' | 'mcpServer' | 'openApiSchema' | 'smithyModel';
 type PythonRuntime = 'PYTHON_3_10' | 'PYTHON_3_11' | 'PYTHON_3_12' | 'PYTHON_3_13';
 type NodeRuntime = 'NODE_18' | 'NODE_20' | 'NODE_22';
-type NetworkMode = 'PUBLIC' | 'PRIVATE';
+type NetworkMode = 'PUBLIC' | 'VPC';

src/schema/schemas/__tests__/agent-env.test.ts

@@ -7,6 +7,7 @@ import {
   EnvVarSchema,
   GatewayNameSchema,
   InstrumentationSchema,
+  NetworkConfigSchema,
 } from '../agent-env.js';
 import { describe, expect, it } from 'vitest';
 
@@ -235,13 +236,51 @@ describe('AgentEnvSpecSchema', () => {
 
   it('accepts agent with network mode', () => {
     expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PUBLIC' }).success).toBe(true);
-    expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PRIVATE' }).success).toBe(true);
+    expect(
+      AgentEnvSpecSchema.safeParse({
+        ...validPythonAgent,
+        networkMode: 'VPC',
+        networkConfig: {
+          subnets: ['subnet-12345678'],
+          securityGroups: ['sg-12345678'],
+        },
+      }).success
+    ).toBe(true);
   });
 
   it('rejects invalid network mode', () => {
+    expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'PRIVATE' }).success).toBe(false);
+  });
+
+  it('rejects VPC mode without networkConfig', () => {
     expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, networkMode: 'VPC' }).success).toBe(false);
   });
 
+  it('rejects networkConfig without VPC mode', () => {
+    expect(
+      AgentEnvSpecSchema.safeParse({
+        ...validPythonAgent,
+        networkMode: 'PUBLIC',
+        networkConfig: {
+          subnets: ['subnet-12345678'],
+          securityGroups: ['sg-12345678'],
+        },
+      }).success
+    ).toBe(false);
+  });
+
+  it('rejects networkConfig with missing networkMode', () => {
+    expect(
+      AgentEnvSpecSchema.safeParse({
+        ...validPythonAgent,
+        networkConfig: {
+          subnets: ['subnet-12345678'],
+          securityGroups: ['sg-12345678'],
+        },
+      }).success
+    ).toBe(false);
+  });
+
   it('accepts agent with instrumentation config', () => {
     const result = AgentEnvSpecSchema.safeParse({
       ...validPythonAgent,
@@ -259,3 +298,53 @@ describe('AgentEnvSpecSchema', () => {
     expect(AgentEnvSpecSchema.safeParse({ ...validPythonAgent, name: undefined }).success).toBe(false);
   });
 });
+
+describe('NetworkConfigSchema', () => {
+  it('accepts valid network config', () => {
+    const result = NetworkConfigSchema.safeParse({
+      subnets: ['subnet-12345678'],
+      securityGroups: ['sg-12345678'],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('accepts multiple subnets and security groups', () => {
+    const result = NetworkConfigSchema.safeParse({
+      subnets: ['subnet-12345678', 'subnet-abcdef12'],
+      securityGroups: ['sg-12345678', 'sg-abcdef12'],
+    });
+    expect(result.success).toBe(true);
+  });
+
+  it('rejects empty subnets array', () => {
+    const result = NetworkConfigSchema.safeParse({
+      subnets: [],
+      securityGroups: ['sg-12345678'],
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects empty security groups array', () => {
+    const result = NetworkConfigSchema.safeParse({
+      subnets: ['subnet-12345678'],
+      securityGroups: [],
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects invalid subnet format', () => {
+    const result = NetworkConfigSchema.safeParse({
+      subnets: ['invalid-subnet'],
+      securityGroups: ['sg-12345678'],
+    });
+    expect(result.success).toBe(false);
+  });
+
+  it('rejects invalid security group format', () => {
+    const result = NetworkConfigSchema.safeParse({
+      subnets: ['subnet-12345678'],
+      securityGroups: ['invalid-sg'],
+    });
+    expect(result.success).toBe(false);
+  });
+});

src/schema/schemas/__tests__/mcp.test.ts

@@ -238,8 +238,8 @@ describe('RuntimeConfigSchema', () => {
     }
   });
 
-  it('accepts explicit PRIVATE networkMode', () => {
-    const result = RuntimeConfigSchema.safeParse({ ...validRuntime, networkMode: 'PRIVATE' });
+  it('accepts explicit VPC networkMode', () => {
+    const result = RuntimeConfigSchema.safeParse({ ...validRuntime, networkMode: 'VPC' });
     expect(result.success).toBe(true);
   });
 

src/schema/schemas/agent-env.ts

@@ -103,25 +103,60 @@ export const InstrumentationSchema = z.object({
 });
 export type Instrumentation = z.infer<typeof InstrumentationSchema>;
 
+/**
+ * VPC network configuration for agents running in VPC mode.
+ * Requires at least one subnet and one security group.
+ */
+export const NetworkConfigSchema = z.object({
+  subnets: z
+    .array(z.string().regex(/^subnet-[0-9a-zA-Z]{8,17}$/))
+    .min(1)
+    .max(16),
+  securityGroups: z
+    .array(z.string().regex(/^sg-[0-9a-zA-Z]{8,17}$/))
+    .min(1)
+    .max(16),
+});
+export type NetworkConfig = z.infer<typeof NetworkConfigSchema>;
+
 /**
  * AgentEnvSpec - represents an AgentCore Runtime.
  * This is a top-level resource in the schema.
  */
-export const AgentEnvSpecSchema = z.object({
-  type: AgentTypeSchema,
-  name: AgentNameSchema,
-  build: BuildTypeSchema,
-  entrypoint: EntrypointSchema,
-  codeLocation: DirectoryPathSchema,
-  runtimeVersion: RuntimeVersionSchemaFromConstants,
-  /** Environment variables to set on the runtime */
-  envVars: z.array(EnvVarSchema).optional(),
-  /** Network mode for the runtime. Defaults to PUBLIC. */
-  networkMode: NetworkModeSchema.optional(),
-  /** Instrumentation settings for observability. Defaults to OTel enabled. */
-  instrumentation: InstrumentationSchema.optional(),
-  /** Model provider used by this agent. Optional for backwards compatibility. */
-  modelProvider: ModelProviderSchema.optional(),
-});
+export const AgentEnvSpecSchema = z
+  .object({
+    type: AgentTypeSchema,
+    name: AgentNameSchema,
+    build: BuildTypeSchema,
+    entrypoint: EntrypointSchema,
+    codeLocation: DirectoryPathSchema,
+    runtimeVersion: RuntimeVersionSchemaFromConstants,
+    /** Environment variables to set on the runtime */
+    envVars: z.array(EnvVarSchema).optional(),
+    /** Network mode for the runtime. Defaults to PUBLIC. */
+    networkMode: NetworkModeSchema.optional(),
+    /** VPC network configuration. Required when networkMode is VPC. */
+    networkConfig: NetworkConfigSchema.optional(),
+    /** Instrumentation settings for observability. Defaults to OTel enabled. */
+    instrumentation: InstrumentationSchema.optional(),
+    /** Model provider used by this agent. Optional for backwards compatibility. */
+    modelProvider: ModelProviderSchema.optional(),
+  })
+  .superRefine((data, ctx) => {
+    if (data.networkMode === 'VPC' && !data.networkConfig) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['networkConfig'],
+        message: 'networkConfig is required when networkMode is VPC',
+      });
+    }
+    if (data.networkMode !== 'VPC' && data.networkConfig) {
+      ctx.addIssue({
+        code: 'custom',
+        path: ['networkConfig'],
+        message: 'networkConfig is only allowed when networkMode is VPC',
+      });
+    }
+  });
 
 export type AgentEnvSpec = z.infer<typeof AgentEnvSpecSchema>;