feat: add EFS and S3 filesystem mount support (#1436)

* feat: add EFS and S3 filesystem mount support (BYO agents and harness)

Adds session storage, EFS access point, and S3 Files access point
filesystem mounts across the full stack: CLI flags, TUI wizard steps,
schema validation, CDK IAM permissions, and generated agent templates.

CLI (agentcore create / add agent / add harness):
- --session-storage-mount-path, --efs-access-point-arn/--efs-mount-path,
  --s3-access-point-arn/--s3-mount-path flags on create and add agent
- Harness create path wires filesystem flags through to harness.json
- Sync validation: ARN format, paired flags, max mounts, VPC requirement
  in both validateCreateOptions and validateCreateHarnessOptions
- Async validation: L1 access point exists, L2 VPC/AZ topology, L3 SG
  in agent create, add agent, and harness create paths
- Level 3 SG check uses EFS/S3 ARN region (not agent region) for mount
  target SG queries; validation reads deployment region from aws-targets.json

TUI wizard:
- EFS/S3 two-step ARN→path entry with add/edit/remove review screens
- Shared useFilesystemMountState hook (generate wizard + BYO + harness)
- Shared buildMountListItems helper
- Session-storage advanced setting in harness wizard includes EFS/S3 steps
- VPC warning and validation on harness EFS/S3 ARN steps
- Harness TUI add flow forwards efsAccessPoints/s3AccessPoints to primitive

Schema:
- FilesystemConfigurationSchema union (sessionStorage | efsAccessPoint |
  s3FilesAccessPoint) with z.strictObject, duplicate path detection,
  max-count enforcement, VPC requirement
- EFS_ACCESS_POINT_ARN_PATTERN / S3_FILES_ACCESS_POINT_ARN_PATTERN
  constants shared between CLI validators and Zod schema
- HarnessSpec gains efsAccessPoints/s3AccessPoints with VPC enforcement
  and duplicate mount path validation

CDK / deploy:
- AgentCoreRuntime: typed filesystemConfigurations props (aws-cdk-lib 2.257)
- AgentCoreHarnessRole: EFS ClientMount/ClientWrite and S3 Files
  ClientMount/ClientWrite IAM policies when mounts are configured
- harness-mapper writes all three filesystem types; hasFilesystem uses
  correct boolean coercion; mount paths normalized (trailing slash stripped)
- Vended cdk-stack.ts and bin/cdk.ts include new HarnessConfig fields

Templates:
- HTTP, A2A, AGUI, MCP Python templates render file_read/file_write/
  list_files filesystem tools via {{#if needsOs}} blocks
- needsOs uses || not ?? so S3-only agents correctly generate tools
- EFS ARN regex constants shared (single source of truth)
- regionFromEfsArn/regionFromS3FilesArn merged into single regionFromArn

Tests:
- filesystem-utils.test.ts: ARN format, path validation, pairing, mounts
- filesystem-roundtrip.test.ts, filesystem-error-quality.test.ts: schema
- harness-mapper.test.ts: EFS, S3, combined filesystem mapping
- validate.test.ts: 16 new EFS/S3 validation cases for create path
- harness-validate.test.ts: 12 new cases for harness create path
- buildMountListItems.test.ts: 6 cases for mount list item builder
- schema-mapper.test.ts: 12 filesystem configuration mapping cases
- useFilesystemMountState.test.tsx: 15 hook handler tests
- computeByoSteps.test.ts: filesystem step inclusion
- useGenerateWizard.test.tsx: EFS/S3 flow, edit/remove, deselect

* fix: address PR review comments on filesystem mount support

- Extract duplicated EFS/S3 mount resolution and validation logic from
  handleCreateCLI and handleCreateHarnessCLI into a shared
  resolveAndValidateFilesystemMounts() helper in filesystem-utils.ts
- Fix path traversal vulnerability in _safe_resolve: append os.sep
  before startswith check to prevent prefix collision (e.g. /mnt/a
  incorrectly matching /mnt/abc/secret)
- Add JSDoc describing L1/L2/L3 validation levels on
  validateFilesystemMountsConfiguration
- Add tests for buildFilesystemConfigurations and
  resolveAndValidateFilesystemMounts

Author: padmak30

npm-shrinkwrap.json

@@ -84,12 +84,14 @@
     "@aws-sdk/client-bedrock-runtime": "^3.893.0",
     "@aws-sdk/client-cloudformation": "^3.893.0",
     "@aws-sdk/client-cloudwatch-logs": "^3.893.0",
+    "@aws-sdk/client-efs": "^3.1049.0",
     "@aws-sdk/client-resource-groups-tagging-api": "^3.893.0",
     "@aws-sdk/client-s3": "^3.1012.0",
+    "@aws-sdk/client-s3files": "^3.1049.0",
     "@aws-sdk/client-sts": "^3.893.0",
-    "@aws-sdk/region-config-resolver": "^3.972.13",
     "@aws-sdk/client-xray": "^3.1003.0",
     "@aws-sdk/credential-providers": "^3.893.0",
+    "@aws-sdk/region-config-resolver": "^3.972.13",
     "@aws/agent-inspector": "0.4.2",
     "@commander-js/extra-typings": "^14.0.0",
     "@opentelemetry/api": "^1.9.1",

package.json

@@ -66,6 +66,8 @@ async function main() {
     codeLocation?: string;
     tools?: { type: string; name: string }[];
     apiKeyArn?: string;
+    efsAccessPoints?: { accessPointArn: string; mountPath: string }[];
+    s3AccessPoints?: { accessPointArn: string; mountPath: string }[];
   }[] = [];
   for (const entry of specAny.harnesses ?? []) {
     const harnessDir = path.resolve(projectRoot, entry.path);
@@ -82,6 +84,8 @@ async function main() {
         codeLocation: harnessSpec.dockerfile ? harnessDir : undefined,
         tools: harnessSpec.tools,
         apiKeyArn: harnessSpec.model?.apiKeyArn,
+        efsAccessPoints: harnessSpec.efsAccessPoints,
+        s3AccessPoints: harnessSpec.s3AccessPoints,
       });
     } catch (err) {
       throw new Error(

src/assets/__tests__/__snapshots__/assets.snapshot.test.ts.snap

@@ -17,6 +17,8 @@ export interface HarnessConfig {
   codeLocation?: string;
   tools?: { type: string; name: string }[];
   apiKeyArn?: string;
+  efsAccessPoints?: { accessPointArn: string; mountPath: string }[];
+  s3AccessPoints?: { accessPointArn: string; mountPath: string }[];
 }
 
 export interface AgentCoreStackProps extends StackProps {

src/assets/cdk/bin/cdk.ts

@@ -1,4 +1,6 @@
+{{#if needsOs}}
 import os
+{{/if}}
 from google.adk.agents import Agent
 from google.adk.a2a.executor.a2a_agent_executor import A2aAgentExecutor
 from google.adk.runners import Runner
@@ -17,18 +19,21 @@ def add_numbers(a: int, b: int) -> int:
 
 tools = [add_numbers]
 
-{{#if sessionStorageMountPath}}
-SESSION_STORAGE_PATH = "{{sessionStorageMountPath}}"
+{{#if needsOs}}
+_MOUNT_PATHS = [
+    {{#if sessionStorageMountPath}}"{{sessionStorageMountPath}}",{{/if}}
+    {{#each efsMounts}}"{{mountPath}}",{{/each}}
+    {{#each s3Mounts}}"{{mountPath}}",{{/each}}
+]
 
 def _safe_resolve(path: str) -> str:
-    """Resolve path safely within the storage boundary."""
-    resolved = os.path.realpath(os.path.join(SESSION_STORAGE_PATH, path.lstrip("/")))
-    if not resolved.startswith(os.path.realpath(SESSION_STORAGE_PATH)):
-        raise ValueError(f"Path '{path}' is outside the storage boundary")
+    resolved = os.path.realpath(path)
+    if not any(resolved == os.path.realpath(m) or resolved.startswith(os.path.realpath(m) + os.sep) for m in _MOUNT_PATHS):
+        raise ValueError(f"Path '{path}' is not within any configured mount ({', '.join(_MOUNT_PATHS)})")
     return resolved
 
 def file_read(path: str) -> str:
-    """Read a file from persistent storage. The path is relative to the storage root."""
+    """Read a file from a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."""
     try:
         full_path = _safe_resolve(path)
         with open(full_path) as f:
@@ -39,7 +44,7 @@ def file_read(path: str) -> str:
         return f"Error reading '{path}': {e.strerror}"
 
 def file_write(path: str, content: str) -> str:
-    """Write content to a file in persistent storage. The path is relative to the storage root."""
+    """Write a file to a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."""
     try:
         full_path = _safe_resolve(path)
         parent = os.path.dirname(full_path)
@@ -53,25 +58,28 @@ def file_write(path: str, content: str) -> str:
     except OSError as e:
         return f"Error writing '{path}': {e.strerror}"
 
-def list_files(directory: str = "") -> str:
-    """List files in persistent storage. The directory is relative to the storage root."""
+def list_files(path: str) -> str:
+    """List files in a mounted filesystem directory. Use the absolute path (e.g. /mnt/tools)."""
     try:
-        target = _safe_resolve(directory)
-        entries = os.listdir(target)
+        full_path = _safe_resolve(path)
+        entries = os.listdir(full_path)
         return "\n".join(entries) if entries else "(empty directory)"
     except ValueError as e:
         return str(e)
     except OSError as e:
-        return f"Error listing '{directory}': {e.strerror}"
+        return f"Error listing '{path}': {e.strerror}"
 
 tools.extend([file_read, file_write, list_files])
 {{/if}}
 
 AGENT_INSTRUCTION = """
 You are a helpful assistant. Use tools when appropriate.
-{{#if sessionStorageMountPath}}
-You have persistent storage at {{sessionStorageMountPath}}. Use file tools to read and write files. Data persists across sessions.
-{{/if}}
+{{#if needsOs}}
+You have access to the following mounted filesystems. Use file_read, file_write, and list_files with full absolute paths:
+{{#if sessionStorageMountPath}}- {{sessionStorageMountPath}}: ephemeral session storage (lost when session ends)
+{{/if}}{{#each efsMounts}}- {{mountPath}}: EFS persistent storage (persists across sessions and agent restarts)
+{{/each}}{{#each s3Mounts}}- {{mountPath}}: S3 Files persistent storage (durable, backed by S3)
+{{/each}}{{/if}}
 """
 
 agent = Agent(

src/assets/cdk/lib/cdk-stack.ts

@@ -1,4 +1,6 @@
+{{#if needsOs}}
 import os
+{{/if}}
 from langchain_core.tools import tool
 from langgraph.prebuilt import create_react_agent
 from opentelemetry.instrumentation.langchain import LangchainInstrumentor
@@ -21,19 +23,22 @@ def add_numbers(a: int, b: int) -> int:
 
 tools = [add_numbers]
 
-{{#if sessionStorageMountPath}}
-SESSION_STORAGE_PATH = "{{sessionStorageMountPath}}"
+{{#if needsOs}}
+_MOUNT_PATHS = [
+    {{#if sessionStorageMountPath}}"{{sessionStorageMountPath}}",{{/if}}
+    {{#each efsMounts}}"{{mountPath}}",{{/each}}
+    {{#each s3Mounts}}"{{mountPath}}",{{/each}}
+]
 
 def _safe_resolve(path: str) -> str:
-    """Resolve path safely within the storage boundary."""
-    resolved = os.path.realpath(os.path.join(SESSION_STORAGE_PATH, path.lstrip("/")))
-    if not resolved.startswith(os.path.realpath(SESSION_STORAGE_PATH)):
-        raise ValueError(f"Path '{path}' is outside the storage boundary")
+    resolved = os.path.realpath(path)
+    if not any(resolved == os.path.realpath(m) or resolved.startswith(os.path.realpath(m) + os.sep) for m in _MOUNT_PATHS):
+        raise ValueError(f"Path '{path}' is not within any configured mount ({', '.join(_MOUNT_PATHS)})")
     return resolved
 
 @tool
 def file_read(path: str) -> str:
-    """Read a file from persistent storage. The path is relative to the storage root."""
+    """Read a file from a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."""
     try:
         full_path = _safe_resolve(path)
         with open(full_path) as f:
@@ -45,7 +50,7 @@ def file_read(path: str) -> str:
 
 @tool
 def file_write(path: str, content: str) -> str:
-    """Write content to a file in persistent storage. The path is relative to the storage root."""
+    """Write a file to a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."""
     try:
         full_path = _safe_resolve(path)
         parent = os.path.dirname(full_path)
@@ -60,25 +65,28 @@ def file_write(path: str, content: str) -> str:
         return f"Error writing '{path}': {e.strerror}"
 
 @tool
-def list_files(directory: str = "") -> str:
-    """List files in persistent storage. The directory is relative to the storage root."""
+def list_files(path: str) -> str:
+    """List files in a mounted filesystem directory. Use the absolute path (e.g. /mnt/tools)."""
     try:
-        target = _safe_resolve(directory)
-        entries = os.listdir(target)
+        full_path = _safe_resolve(path)
+        entries = os.listdir(full_path)
         return "\n".join(entries) if entries else "(empty directory)"
     except ValueError as e:
         return str(e)
     except OSError as e:
-        return f"Error listing '{directory}': {e.strerror}"
+        return f"Error listing '{path}': {e.strerror}"
 
 tools.extend([file_read, file_write, list_files])
 {{/if}}
 
 SYSTEM_PROMPT = """
 You are a helpful assistant. Use tools when appropriate.
-{{#if sessionStorageMountPath}}
-You have persistent storage at {{sessionStorageMountPath}}. Use file tools to read and write files. Data persists across sessions.
-{{/if}}
+{{#if needsOs}}
+You have access to the following mounted filesystems. Use file_read, file_write, and list_files with full absolute paths:
+{{#if sessionStorageMountPath}}- {{sessionStorageMountPath}}: ephemeral session storage (lost when session ends)
+{{/if}}{{#each efsMounts}}- {{mountPath}}: EFS persistent storage (persists across sessions and agent restarts)
+{{/each}}{{#each s3Mounts}}- {{mountPath}}: S3 Files persistent storage (durable, backed by S3)
+{{/each}}{{/if}}
 """
 
 model = load_model()

src/assets/python/a2a/googleadk/base/main.py

@@ -5,7 +5,7 @@
 {{#if hasMemory}}
 from memory.session import get_memory_session_manager
 {{/if}}
-{{#if sessionStorageMountPath}}
+{{#if needsOs}}
 import os
 {{/if}}
 
@@ -18,19 +18,22 @@ def add_numbers(a: int, b: int) -> int:
 
 tools = [add_numbers]
 
-{{#if sessionStorageMountPath}}
-SESSION_STORAGE_PATH = "{{sessionStorageMountPath}}"
+{{#if needsOs}}
+_MOUNT_PATHS = [
+    {{#if sessionStorageMountPath}}"{{sessionStorageMountPath}}",{{/if}}
+    {{#each efsMounts}}"{{mountPath}}",{{/each}}
+    {{#each s3Mounts}}"{{mountPath}}",{{/each}}
+]
 
 def _safe_resolve(path: str) -> str:
-    """Resolve path safely within the storage boundary."""
-    resolved = os.path.realpath(os.path.join(SESSION_STORAGE_PATH, path.lstrip("/")))
-    if not resolved.startswith(os.path.realpath(SESSION_STORAGE_PATH)):
-        raise ValueError(f"Path '{path}' is outside the storage boundary")
+    resolved = os.path.realpath(path)
+    if not any(resolved == os.path.realpath(m) or resolved.startswith(os.path.realpath(m) + os.sep) for m in _MOUNT_PATHS):
+        raise ValueError(f"Path '{path}' is not within any configured mount ({', '.join(_MOUNT_PATHS)})")
     return resolved
 
 @tool
 def file_read(path: str) -> str:
-    """Read a file from persistent storage. The path is relative to the storage root."""
+    """Read a file from a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."""
     try:
         full_path = _safe_resolve(path)
         with open(full_path) as f:
@@ -42,7 +45,7 @@ def file_read(path: str) -> str:
 
 @tool
 def file_write(path: str, content: str) -> str:
-    """Write content to a file in persistent storage. The path is relative to the storage root."""
+    """Write a file to a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."""
     try:
         full_path = _safe_resolve(path)
         parent = os.path.dirname(full_path)
@@ -57,25 +60,28 @@ def file_write(path: str, content: str) -> str:
         return f"Error writing '{path}': {e.strerror}"
 
 @tool
-def list_files(directory: str = "") -> str:
-    """List files in persistent storage. The directory is relative to the storage root."""
+def list_files(path: str) -> str:
+    """List files in a mounted filesystem directory. Use the absolute path (e.g. /mnt/tools)."""
     try:
-        target = _safe_resolve(directory)
-        entries = os.listdir(target)
+        full_path = _safe_resolve(path)
+        entries = os.listdir(full_path)
         return "\n".join(entries) if entries else "(empty directory)"
     except ValueError as e:
         return str(e)
     except OSError as e:
-        return f"Error listing '{directory}': {e.strerror}"
+        return f"Error listing '{path}': {e.strerror}"
 
 tools.extend([file_read, file_write, list_files])
 {{/if}}
 
 SYSTEM_PROMPT = """
 You are a helpful assistant. Use tools when appropriate.
-{{#if sessionStorageMountPath}}
-You have persistent storage at {{sessionStorageMountPath}}. Use file tools to read and write files. Data persists across sessions.
-{{/if}}
+{{#if needsOs}}
+You have access to the following mounted filesystems. Use file_read, file_write, and list_files with full absolute paths:
+{{#if sessionStorageMountPath}}- {{sessionStorageMountPath}}: ephemeral session storage (lost when session ends)
+{{/if}}{{#each efsMounts}}- {{mountPath}}: EFS persistent storage (persists across sessions and agent restarts)
+{{/each}}{{#each s3Mounts}}- {{mountPath}}: S3 Files persistent storage (durable, backed by S3)
+{{/each}}{{/if}}
 """
 
 {{#if hasMemory}}

src/assets/python/a2a/langchain_langgraph/base/main.py

@@ -1,16 +1,76 @@
 import os
 import uvicorn
 from google.adk.agents import LlmAgent
+from google.adk.tools import FunctionTool
 from ag_ui_adk import ADKAgent, AGUIToolset, create_adk_app
 from model.load import load_model
 
 load_model()
 
+{{#if needsOs}}
+_MOUNT_PATHS = [
+    {{#if sessionStorageMountPath}}"{{sessionStorageMountPath}}",{{/if}}
+    {{#each efsMounts}}"{{mountPath}}",{{/each}}
+    {{#each s3Mounts}}"{{mountPath}}",{{/each}}
+]
+
+def _safe_resolve(path: str) -> str:
+    resolved = os.path.realpath(path)
+    if not any(resolved == os.path.realpath(m) or resolved.startswith(os.path.realpath(m) + os.sep) for m in _MOUNT_PATHS):
+        raise ValueError(f"Path '{path}' is not within any configured mount ({', '.join(_MOUNT_PATHS)})")
+    return resolved
+
+def file_read(path: str) -> str:
+    """Read a file from a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."""
+    try:
+        full_path = _safe_resolve(path)
+        with open(full_path) as f:
+            return f.read()
+    except ValueError as e:
+        return str(e)
+    except OSError as e:
+        return f"Error reading '{path}': {e.strerror}"
+
+def file_write(path: str, content: str) -> str:
+    """Write a file to a mounted filesystem. Use the absolute path (e.g. /mnt/tools/data.txt)."""
+    try:
+        full_path = _safe_resolve(path)
+        parent = os.path.dirname(full_path)
+        if parent:
+            os.makedirs(parent, exist_ok=True)
+        with open(full_path, "w") as f:
+            f.write(content)
+        return f"Written to {path}"
+    except ValueError as e:
+        return str(e)
+    except OSError as e:
+        return f"Error writing '{path}': {e.strerror}"
+
+def list_files(path: str) -> str:
+    """List files in a mounted filesystem directory. Use the absolute path (e.g. /mnt/tools)."""
+    try:
+        full_path = _safe_resolve(path)
+        entries = os.listdir(full_path)
+        return "\n".join(entries) if entries else "(empty directory)"
+    except ValueError as e:
+        return str(e)
+    except OSError as e:
+        return f"Error listing '{path}': {e.strerror}"
+
+_fs_tools = [FunctionTool(file_read), FunctionTool(file_write), FunctionTool(list_files)]
+{{/if}}
+
 agent = LlmAgent(
     name="{{ name }}",
     model="gemini-2.5-flash",
-    instruction="You are a helpful assistant.",
-    tools=[AGUIToolset()],
+    instruction="""You are a helpful assistant.
+{{#if needsOs}}
+You have access to the following mounted filesystems. Use file_read, file_write, and list_files with full absolute paths:
+{{#if sessionStorageMountPath}}- {{sessionStorageMountPath}}: ephemeral session storage (lost when session ends)
+{{/if}}{{#each efsMounts}}- {{mountPath}}: EFS persistent storage (persists across sessions and agent restarts)
+{{/each}}{{#each s3Mounts}}- {{mountPath}}: S3 Files persistent storage (durable, backed by S3)
+{{/each}}{{/if}}""",
+    tools=[AGUIToolset(), {{#if needsOs}}*_fs_tools{{/if}}],
 )
 
 adk_agent = ADKAgent(