feat(runtime): add persistent session storage

Author: krokoko

agent/entrypoint.py

@@ -37,6 +37,8 @@
 # Configuration
 # ---------------------------------------------------------------------------
 
+AGENT_WORKSPACE = os.environ.get("AGENT_WORKSPACE", "/workspace")
+
 
 def resolve_github_token() -> str:
     """Resolve GitHub token from Secrets Manager or environment variable.
@@ -298,7 +300,7 @@ def setup_repo(config: dict) -> dict:
     Returns a dict with keys: repo_dir, branch, notes, build_before,
     lint_before, and default_branch.
     """
-    repo_dir = f"/workspace/{config['task_id']}"
+    repo_dir = f"{AGENT_WORKSPACE}/{config['task_id']}"
     setup: dict[str, str | list[str] | bool] = {"repo_dir": repo_dir, "notes": []}
 
     # Derive branch slug from issue title or task description
@@ -311,6 +313,14 @@ def setup_repo(config: dict) -> dict:
     branch = f"bgagent/{config['task_id']}/{slug}"
     setup["branch"] = branch
 
+    # Mark the repo directory as safe for git.  On persistent session storage
+    # the mount may be owned by a different UID than the container user,
+    # triggering git's "dubious ownership" check on clone/resume.
+    run_cmd(
+        ["git", "config", "--global", "--add", "safe.directory", repo_dir],
+        label="safe-directory",
+    )
+
     # Clone
     log("SETUP", f"Cloning {config['repo_url']}...")
     run_cmd(
@@ -794,7 +804,7 @@ def _extract_agent_notes(repo_dir: str, branch: str, config: dict) -> str | None
 # ---------------------------------------------------------------------------
 
 
-def get_disk_usage(path: str = "/workspace") -> float:
+def get_disk_usage(path: str = AGENT_WORKSPACE) -> float:
     """Return disk usage in bytes for the given path."""
     try:
         result = subprocess.run(
@@ -1225,7 +1235,9 @@ def _setup_agent_env(config: dict) -> tuple[str | None, str | None]:
     return otlp_endpoint, otlp_protocol
 
 
-async def run_agent(prompt: str, system_prompt: str, config: dict, cwd: str = "/workspace") -> dict:
+async def run_agent(
+    prompt: str, system_prompt: str, config: dict, cwd: str = AGENT_WORKSPACE
+) -> dict:
     """Invoke the Claude Agent SDK and stream output."""
     from claude_agent_sdk import (
         AssistantMessage,
@@ -1472,6 +1484,7 @@ def _build_system_prompt(
     """Assemble the system prompt with task-specific values and memory context."""
     system_prompt = SYSTEM_PROMPT.replace("{repo_url}", config["repo_url"])
     system_prompt = system_prompt.replace("{task_id}", config["task_id"])
+    system_prompt = system_prompt.replace("{workspace}", AGENT_WORKSPACE)
     system_prompt = system_prompt.replace("{branch_name}", setup["branch"])
     default_branch = setup.get("default_branch", "main")
     system_prompt = system_prompt.replace("{default_branch}", default_branch)
@@ -1719,7 +1732,7 @@ def run_task(
                 log("TASK", "No repo-level project configuration found")
 
             # Run agent
-            disk_before = get_disk_usage("/workspace")
+            disk_before = get_disk_usage(AGENT_WORKSPACE)
             start_time = time.time()
 
             log("TASK", "Starting agent...")
@@ -1781,7 +1794,7 @@ def run_task(
 
             # Metrics
             duration = time.time() - start_time
-            disk_after = get_disk_usage("/workspace")
+            disk_after = get_disk_usage(AGENT_WORKSPACE)
 
             # Determine overall status:
             #   - "success" if the agent reported success/end_turn and the build passes
@@ -1916,6 +1929,7 @@ def main():
         prompt = assemble_prompt(config)
         system_prompt = SYSTEM_PROMPT.replace("{repo_url}", config["repo_url"])
         system_prompt = system_prompt.replace("{task_id}", config["task_id"])
+        system_prompt = system_prompt.replace("{workspace}", AGENT_WORKSPACE)
         system_prompt = system_prompt.replace("{branch_name}", "bgagent/{task_id}/dry-run")
         system_prompt = system_prompt.replace("{default_branch}", "main")
         system_prompt = system_prompt.replace("{max_turns}", str(config.get("max_turns", 100)))

agent/system_prompt.py

@@ -6,6 +6,7 @@
 Placeholders replaced at runtime by entrypoint.py:
   {repo_url}          — GitHub repo (owner/repo)
   {task_id}           — Unique task identifier
+  {workspace}         — Workspace root (AGENT_WORKSPACE env var, default /workspace)
   {branch_name}       — Git branch created by the entrypoint
   {default_branch}    — Repository default branch (e.g. main, master)
   {max_turns}         — Maximum agent turns for this task
@@ -20,7 +21,7 @@
 ## Environment
 
 - You are running inside an isolated container with shell access.
-- The repository `{repo_url}` is already cloned at `/workspace/{task_id}`.
+- The repository `{repo_url}` is already cloned at `{workspace}/{task_id}`.
 - You are on branch `{branch_name}`.
 - The repository default branch is `{default_branch}`.
 - Git is configured and authenticated — `git push` works without extra setup.

agent/tests/test_entrypoint.py

@@ -16,6 +16,32 @@
     truncate,
 )
 
+# ---------------------------------------------------------------------------
+# AGENT_WORKSPACE
+# ---------------------------------------------------------------------------
+
+
+class TestAgentWorkspace:
+    def test_defaults_to_workspace(self, monkeypatch):
+        monkeypatch.delenv("AGENT_WORKSPACE", raising=False)
+        # Re-import to pick up the env change
+        import importlib
+
+        import entrypoint
+
+        importlib.reload(entrypoint)
+        assert entrypoint.AGENT_WORKSPACE == "/workspace"
+
+    def test_reads_env_var(self, monkeypatch):
+        monkeypatch.setenv("AGENT_WORKSPACE", "/mnt/workspace")
+        import importlib
+
+        import entrypoint
+
+        importlib.reload(entrypoint)
+        assert entrypoint.AGENT_WORKSPACE == "/mnt/workspace"
+
+
 # ---------------------------------------------------------------------------
 # slugify
 # ---------------------------------------------------------------------------

cdk/src/stacks/agent.ts

@@ -21,7 +21,7 @@ import * as path from 'path';
 import * as agentcore from '@aws-cdk/aws-bedrock-agentcore-alpha';
 import * as bedrock from '@aws-cdk/aws-bedrock-alpha';
 import * as agentcoremixins from '@aws-cdk/mixins-preview/aws-bedrockagentcore';
-import { Stack, StackProps, RemovalPolicy, CfnOutput } from 'aws-cdk-lib';
+import { Stack, StackProps, RemovalPolicy, CfnOutput, CfnResource } from 'aws-cdk-lib';
 import * as ec2 from 'aws-cdk-lib/aws-ec2';
 import * as iam from 'aws-cdk-lib/aws-iam';
 import * as logs from 'aws-cdk-lib/aws-logs';
@@ -143,10 +143,35 @@ export class AgentStack extends Stack {
         LOG_GROUP_NAME: applicationLogGroup.logGroupName,
         MEMORY_ID: agentMemory.memory.memoryId,
         MAX_TURNS: '100',
+        // Session storage: the S3-backed FUSE mount at /mnt/workspace does NOT
+        // support flock(). Only caches whose tools never call flock() go there.
+        // Everything else stays on local ephemeral disk.
+        //
+        // Local disk (tools use flock):
+        //   AGENT_WORKSPACE — omitted, defaults to /workspace
+        //   MISE_DATA_DIR — mise's pipx backend sets UV_TOOL_DIR inside installs/,
+        //     and uv flocks that directory → must be local.
+        MISE_DATA_DIR: '/tmp/mise-data',
+        UV_CACHE_DIR: '/tmp/uv-cache',
+        // Persistent mount (no flock):
+        CLAUDE_CONFIG_DIR: '/mnt/workspace/.claude-config',
+        npm_config_cache: '/mnt/workspace/.npm-cache',
         // ENABLE_CLI_TELEMETRY: '1',
       },
     });
 
+    // --- Session storage (preview) ---
+    // The L2 construct does not yet expose filesystemConfigurations.
+    // Use a CFN escape hatch until the L2 adds native support.
+    const cfnRuntime = runtime.node.defaultChild as CfnResource;
+    cfnRuntime.addPropertyOverride('FilesystemConfigurations', [
+      {
+        SessionStorage: {
+          MountPath: '/mnt/workspace',
+        },
+      },
+    ]);
+
     taskTable.table.grantReadWriteData(runtime);
     taskEventsTable.table.grantReadWriteData(runtime);
     userConcurrencyTable.table.grantReadWriteData(runtime);

cdk/test/stacks/agent.test.ts

@@ -172,6 +172,31 @@ describe('AgentStack', () => {
     expect(loggingConfigs.length).toBe(1);
   });
 
+  test('enables session storage with persistent filesystem', () => {
+    template.hasResourceProperties('AWS::BedrockAgentCore::Runtime', {
+      FilesystemConfigurations: [
+        {
+          SessionStorage: {
+            MountPath: '/mnt/workspace',
+          },
+        },
+      ],
+    });
+  });
+
+  test('sets cache env vars on runtime (persistent mount + local for flock)', () => {
+    template.hasResourceProperties('AWS::BedrockAgentCore::Runtime', {
+      EnvironmentVariables: Match.objectLike({
+        // Local disk — tools use flock()
+        MISE_DATA_DIR: '/tmp/mise-data',
+        UV_CACHE_DIR: '/tmp/uv-cache',
+        // Persistent mount — no flock()
+        CLAUDE_CONFIG_DIR: '/mnt/workspace/.claude-config',
+        npm_config_cache: '/mnt/workspace/.npm-cache',
+      }),
+    });
+  });
+
   test('creates AgentCore Memory resource', () => {
     template.resourceCountIs('AWS::BedrockAgentCore::Memory', 1);
   });

docs/design/AGENT_HARNESS.md

@@ -39,7 +39,7 @@ The following are desired properties for the harness; MVP satisfies some and def
 - **Deterministic hooks** — Support for deterministic steps or hooks (e.g. pre/post tool execution, validation) so the platform can mix coded logic with the agent loop. The **blueprint execution framework** (see [REPO_ONBOARDING.md](./REPO_ONBOARDING.md#blueprint-execution-framework)) realizes this requirement: the orchestrator runs custom Lambda-backed steps at configurable pipeline phases (`pre-agent`, `post-agent`) with framework-enforced invariants (state transitions, events, cancellation). The agent harness itself does not need to implement hooks — they run at the orchestrator level, outside the agent session.
 - **Plugins / skills / MCP** — Support for plugins, skills, or MCP servers for extensibility. Out of scope for MVP.
 - **Access to external memory** — The agent should be able to read and write short- and long-term memory (e.g. AgentCore Memory). MVP: AgentCore Memory is available to the agent via the runtime; the SDK or platform wires it in.
-- **Session persistence** — Persisting conversation and agent state across session boundaries for crash recovery or resume. MVP: Claude Code SDK has no built-in session manager; durability is via frequent commits.
+- **Session persistence** — Persisting conversation and agent state across session boundaries for crash recovery or resume. MVP: Claude Code SDK has no built-in session manager; durability is via frequent commits. **Update:** AgentCore Runtime persistent session storage (preview) now mounts a per-session filesystem at `/mnt/workspace` that survives stop/resume cycles. Tool caches (mise, npm, Claude Code config) persist across invocations within a session (14-day TTL). Repo clones remain on local ephemeral disk because the S3-backed FUSE mount does not support `flock()`, which breaks build tools like `uv`. See [COMPUTE.md](./COMPUTE.md#session-storage-persistent-filesystem).
 
 ## Diagnostic tools