refactor: extract createSandboxWithFallback to own lib file, add error logging

- Extract createSandboxWithFallback to lib/sandbox/createSandboxWithFallback.ts (SRP)
- processCreateSandbox and createSandboxFromSnapshot use it / follow same pattern
- Log snapshot creation errors before falling back to fresh sandbox
- Add 4 unit tests for createSandboxWithFallback

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: sweetmantech

lib/sandbox/__tests__/createSandboxWithFallback.test.ts

@@ -0,0 +1,70 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+
+import { createSandboxWithFallback } from "../createSandboxWithFallback";
+
+const mockCreateSandbox = vi.fn();
+
+vi.mock("@/lib/sandbox/createSandbox", () => ({
+  createSandbox: (...args: unknown[]) => mockCreateSandbox(...args),
+}));
+
+const mockResponse = {
+  sandboxId: "sbx_123",
+  sandboxStatus: "running",
+  timeout: 1800000,
+  createdAt: "2024-01-01T00:00:00.000Z",
+};
+
+describe("createSandboxWithFallback", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockCreateSandbox.mockResolvedValue({
+      sandbox: {},
+      response: mockResponse,
+    });
+  });
+
+  it("creates from snapshot when snapshotId is provided", async () => {
+    const result = await createSandboxWithFallback("snap_abc");
+
+    expect(mockCreateSandbox).toHaveBeenCalledWith({
+      source: { type: "snapshot", snapshotId: "snap_abc" },
+    });
+    expect(result).toEqual(mockResponse);
+  });
+
+  it("creates fresh sandbox when snapshotId is undefined", async () => {
+    const result = await createSandboxWithFallback(undefined);
+
+    expect(mockCreateSandbox).toHaveBeenCalledWith({});
+    expect(result).toEqual(mockResponse);
+  });
+
+  it("falls back to fresh sandbox when snapshot creation fails", async () => {
+    const freshResponse = { ...mockResponse, sandboxId: "sbx_fresh" };
+    mockCreateSandbox
+      .mockRejectedValueOnce(new Error("Status code 400 is not ok"))
+      .mockResolvedValueOnce({ sandbox: {}, response: freshResponse });
+
+    const result = await createSandboxWithFallback("snap_bad");
+
+    expect(mockCreateSandbox).toHaveBeenCalledTimes(2);
+    expect(result).toEqual(freshResponse);
+  });
+
+  it("logs error when snapshot creation fails", async () => {
+    const consoleSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const snapshotError = new Error("Status code 400 is not ok");
+    mockCreateSandbox
+      .mockRejectedValueOnce(snapshotError)
+      .mockResolvedValueOnce({ sandbox: {}, response: mockResponse });
+
+    await createSandboxWithFallback("snap_bad");
+
+    expect(consoleSpy).toHaveBeenCalledWith(
+      "Snapshot sandbox creation failed, falling back to fresh sandbox:",
+      snapshotError,
+    );
+    consoleSpy.mockRestore();
+  });
+});

lib/sandbox/createSandboxFromSnapshot.ts

@@ -27,8 +27,11 @@ export async function createSandboxFromSnapshot(
     try {
       sandbox = (await createSandbox({ source: { type: "snapshot", snapshotId } })).sandbox;
       fromSnapshot = true;
-    } catch {
-      // Snapshot invalid or expired on Vercel's side — fall through to fresh
+    } catch (error) {
+      console.error(
+        "Snapshot sandbox creation failed, falling back to fresh sandbox:",
+        error,
+      );
     }
   }
 
@@ -38,8 +41,8 @@ export async function createSandboxFromSnapshot(
 
   await insertAccountSandbox({
     account_id: accountId,
-    sandbox_id: sandbox.sandboxId,
+    sandbox_id: sandbox!.sandboxId,
   });
 
-  return { sandbox, fromSnapshot };
+  return { sandbox: sandbox!, fromSnapshot };
 }

lib/sandbox/createSandboxWithFallback.ts

@@ -0,0 +1,24 @@
+import { createSandbox, type SandboxCreatedResponse } from "@/lib/sandbox/createSandbox";
+
+/**
+ * Attempts to create a sandbox from the given snapshot, falling back to a fresh sandbox on failure.
+ * If no snapshotId is provided, creates a fresh sandbox directly.
+ *
+ * @param snapshotId - Optional snapshot ID to restore from
+ * @returns The sandbox creation response
+ */
+export async function createSandboxWithFallback(
+  snapshotId: string | undefined,
+): Promise<SandboxCreatedResponse> {
+  if (snapshotId) {
+    try {
+      return (await createSandbox({ source: { type: "snapshot", snapshotId } })).response;
+    } catch (error) {
+      console.error(
+        "Snapshot sandbox creation failed, falling back to fresh sandbox:",
+        error,
+      );
+    }
+  }
+  return (await createSandbox({})).response;
+}

lib/sandbox/processCreateSandbox.ts

@@ -1,32 +1,15 @@
-import { createSandbox, type SandboxCreatedResponse } from "@/lib/sandbox/createSandbox";
+import { createSandboxWithFallback } from "@/lib/sandbox/createSandboxWithFallback";
 import { getValidSnapshotId } from "@/lib/sandbox/getValidSnapshotId";
 import { insertAccountSandbox } from "@/lib/supabase/account_sandboxes/insertAccountSandbox";
 import { triggerPromptSandbox } from "@/lib/trigger/triggerPromptSandbox";
+import type { SandboxCreatedResponse } from "@/lib/sandbox/createSandbox";
 
 type ProcessCreateSandboxInput = {
   accountId: string;
   prompt?: string;
 };
 type ProcessCreateSandboxResult = SandboxCreatedResponse & { runId?: string };
 
-/**
- * Attempts to create a sandbox from the given snapshot, falling back to a fresh sandbox on failure.
- * If no snapshotId is provided, creates a fresh sandbox directly.
- *
- * @param snapshotId - Optional snapshot ID to restore from
- * @returns The sandbox creation response
- */
-async function createSandboxWithFallback(snapshotId: string | undefined) {
-  if (snapshotId) {
-    try {
-      return (await createSandbox({ source: { type: "snapshot", snapshotId } })).response;
-    } catch {
-      // Snapshot invalid or expired on Vercel's side — fall through to fresh
-    }
-  }
-  return (await createSandbox({})).response;
-}
-
 /**
  * Shared domain logic for creating a sandbox and optionally running a prompt.
  * Used by both POST /api/sandboxes handler and the prompt_sandbox MCP tool.