fix(sandbox): add workflow serialization support for Snapshot class (#140)

## Summary

- Adds `WORKFLOW_SERIALIZE` / `WORKFLOW_DESERIALIZE` static methods to
the `Snapshot` class, fixing serialization errors when a `Snapshot`
instance is returned from a workflow step.
- Uses the same lazy-client pattern as `Sandbox` and `Command`: only
plain `SnapshotMetadata` is serialized (credentials are excluded), and
an API client is lazily created via `ensureClient()` when needed after
deserialization.
- Includes 10 tests covering serialize/deserialize roundtrips,
credential exclusion, and full `dehydrate`/`hydrate` through the
workflow runtime pipeline.

Author: TooTallNate

.changeset/snapshot-workflow-serialization.md

@@ -0,0 +1,5 @@
+---
+"@vercel/sandbox": patch
+---
+
+Add workflow serialization support for the `Snapshot` class via `WORKFLOW_SERIALIZE` / `WORKFLOW_DESERIALIZE`, fixing serialization errors when a `Snapshot` instance is returned from a workflow step.

packages/vercel-sandbox/src/index.ts

@@ -6,6 +6,7 @@ export {
 } from "./sandbox.js";
 export type { SerializedSandbox } from "./sandbox.js";
 export { Snapshot } from "./snapshot.js";
+export type { SerializedSnapshot } from "./snapshot.js";
 export { Command, CommandFinished } from "./command.js";
 export type {
   SerializedCommand,

packages/vercel-sandbox/src/snapshot.serialize.test.ts

@@ -0,0 +1,198 @@
+import { registerSerializationClass } from "@workflow/core/class-serialization";
+import {
+  dehydrateStepReturnValue,
+  hydrateStepReturnValue,
+} from "@workflow/core/serialization";
+import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from "@workflow/serde";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { SnapshotMetadata } from "./api-client";
+import { APIClient } from "./api-client";
+import { Snapshot, type SerializedSnapshot } from "./snapshot";
+
+describe("Snapshot serialization", () => {
+  const mockSnapshotMetadata: SnapshotMetadata = {
+    id: "snap_test123",
+    sourceSandboxId: "sbx_source456",
+    region: "iad1",
+    status: "created",
+    sizeBytes: 253826392,
+    expiresAt: 1775737021391,
+    createdAt: 1775650621392,
+    updatedAt: 1775650621392,
+  };
+
+  const createMockSnapshot = (
+    metadata: SnapshotMetadata = mockSnapshotMetadata,
+  ): Snapshot => {
+    const client = new APIClient({
+      teamId: "team_test",
+      token: "test_token",
+    });
+
+    return new Snapshot({
+      client,
+      snapshot: metadata,
+    });
+  };
+
+  const serializeSnapshot = (snapshot: Snapshot): SerializedSnapshot => {
+    return Snapshot[WORKFLOW_SERIALIZE](snapshot);
+  };
+
+  const deserializeSnapshot = (data: SerializedSnapshot): Snapshot => {
+    return Snapshot[WORKFLOW_DESERIALIZE](data);
+  };
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe("WORKFLOW_SERIALIZE", () => {
+    it("serializes snapshot metadata", () => {
+      const snapshot = createMockSnapshot();
+      const serialized = serializeSnapshot(snapshot);
+
+      expect(serialized.snapshot.id).toBe("snap_test123");
+      expect(serialized.snapshot.sourceSandboxId).toBe("sbx_source456");
+      expect(serialized.snapshot.region).toBe("iad1");
+      expect(serialized.snapshot.status).toBe("created");
+      expect(serialized.snapshot.sizeBytes).toBe(253826392);
+    });
+
+    it("returns plain JSON-serializable data", () => {
+      const snapshot = createMockSnapshot();
+      const serialized = serializeSnapshot(snapshot);
+
+      const jsonString = JSON.stringify(serialized);
+      const parsed = JSON.parse(jsonString);
+
+      expect(parsed.snapshot.id).toBe("snap_test123");
+      expect(parsed.snapshot.sourceSandboxId).toBe("sbx_source456");
+    });
+
+    it("does not include the API client or credentials", () => {
+      const snapshot = createMockSnapshot();
+      const serialized = serializeSnapshot(snapshot);
+
+      expect(serialized).not.toHaveProperty("client");
+      expect(serialized).not.toHaveProperty("_client");
+      expect(JSON.stringify(serialized)).not.toContain("token");
+    });
+  });
+
+  describe("WORKFLOW_DESERIALIZE", () => {
+    it("returns synchronously", () => {
+      const snapshot = createMockSnapshot();
+      const serialized = serializeSnapshot(snapshot);
+
+      const result = deserializeSnapshot(serialized);
+
+      expect(result).toBeInstanceOf(Snapshot);
+      expect(result).not.toBeInstanceOf(Promise);
+    });
+
+    it("reconstructs a fully usable metadata-backed instance", () => {
+      const snapshot = createMockSnapshot();
+      const serialized = serializeSnapshot(snapshot);
+
+      const result = deserializeSnapshot(serialized);
+
+      expect(result.snapshotId).toBe("snap_test123");
+      expect(result.sourceSandboxId).toBe("sbx_source456");
+      expect(result.status).toBe("created");
+      expect(result.sizeBytes).toBe(253826392);
+      expect(result.createdAt).toEqual(new Date(1775650621392));
+      expect(result.expiresAt).toEqual(new Date(1775737021391));
+    });
+
+    it("does not require global credentials just to deserialize and read metadata", async () => {
+      vi.resetModules();
+      const { Snapshot: FreshSnapshot } = await import("./snapshot");
+
+      const serializedData: SerializedSnapshot = {
+        snapshot: mockSnapshotMetadata,
+      };
+
+      const deserialized = FreshSnapshot[WORKFLOW_DESERIALIZE](
+        serializedData,
+      ) as Snapshot;
+
+      expect(deserialized.snapshotId).toBe("snap_test123");
+      expect(deserialized.sourceSandboxId).toBe("sbx_source456");
+      expect(deserialized.status).toBe("created");
+    });
+
+    it("deserialized instance has no client until ensureClient() is called", async () => {
+      vi.resetModules();
+      const { Snapshot: FreshSnapshot } = await import("./snapshot");
+
+      const serializedData: SerializedSnapshot = {
+        snapshot: mockSnapshotMetadata,
+      };
+
+      const deserialized = FreshSnapshot[WORKFLOW_DESERIALIZE](
+        serializedData,
+      ) as Snapshot;
+
+      expect((deserialized as any)._client).toBeNull();
+    });
+
+    it("handles snapshot without expiresAt", () => {
+      const metadataWithoutExpiry: SnapshotMetadata = {
+        ...mockSnapshotMetadata,
+        expiresAt: undefined,
+      };
+
+      const snapshot = createMockSnapshot(metadataWithoutExpiry);
+      const serialized = serializeSnapshot(snapshot);
+      const result = deserializeSnapshot(serialized);
+
+      expect(result.expiresAt).toBeUndefined();
+      expect(result.snapshotId).toBe("snap_test123");
+    });
+  });
+
+  describe("workflow runtime integration", () => {
+    it("survives a step boundary roundtrip", async () => {
+      registerSerializationClass("Snapshot", Snapshot);
+
+      const snapshot = createMockSnapshot();
+
+      const dehydrated = await dehydrateStepReturnValue(
+        snapshot,
+        "run_123",
+        undefined,
+      );
+      const rehydrated = await hydrateStepReturnValue(
+        dehydrated,
+        "run_123",
+        undefined,
+      );
+
+      expect(rehydrated).toBeInstanceOf(Snapshot);
+      expect(rehydrated.snapshotId).toBe("snap_test123");
+      expect(rehydrated.sourceSandboxId).toBe("sbx_source456");
+    });
+
+    it("preserves all metadata through runtime pipeline", async () => {
+      registerSerializationClass("Snapshot", Snapshot);
+
+      const snapshot = createMockSnapshot();
+
+      const dehydrated = await dehydrateStepReturnValue(
+        snapshot,
+        "run_456",
+        undefined,
+      );
+      const rehydrated = await hydrateStepReturnValue(
+        dehydrated,
+        "run_456",
+        undefined,
+      );
+
+      expect(rehydrated.status).toBe("created");
+      expect(rehydrated.sizeBytes).toBe(253826392);
+      expect(rehydrated.createdAt).toEqual(new Date(1775650621392));
+    });
+  });
+});

packages/vercel-sandbox/src/snapshot.ts

@@ -1,8 +1,13 @@
+import { WORKFLOW_DESERIALIZE, WORKFLOW_SERIALIZE } from "@workflow/serde";
 import type { WithFetchOptions } from "./api-client/api-client.js";
 import type { SnapshotMetadata } from "./api-client/index.js";
 import { APIClient } from "./api-client/index.js";
 import { type Credentials, getCredentials } from "./utils/get-credentials.js";
 
+export interface SerializedSnapshot {
+  snapshot: SnapshotMetadata;
+}
+
 /** @inline */
 interface GetSnapshotParams {
   /**
@@ -22,7 +27,24 @@ interface GetSnapshotParams {
  * @hideconstructor
  */
 export class Snapshot {
-  private readonly client: APIClient;
+  private _client: APIClient | null = null;
+
+  /**
+   * Lazily resolve credentials and construct an API client.
+   * This is used in step contexts where the Snapshot was deserialized
+   * without a client (e.g. when crossing workflow/step boundaries).
+   * @internal
+   */
+  private async ensureClient(): Promise<APIClient> {
+    "use step";
+    if (this._client) return this._client;
+    const credentials = await getCredentials();
+    this._client = new APIClient({
+      teamId: credentials.teamId,
+      token: credentials.token,
+    });
+    return this._client;
+  }
 
   /**
    * Unique ID of this snapshot.
@@ -76,19 +98,40 @@ export class Snapshot {
   private snapshot: SnapshotMetadata;
 
   /**
-   * Create a new Snapshot instance.
+   * Serialize a Snapshot instance to plain data for @workflow/serde.
    *
-   * @param client - API client used to communicate with the backend
-   * @param snapshot - Snapshot metadata
+   * @param instance - The Snapshot instance to serialize
+   * @returns A plain object containing snapshot metadata
    */
+  static [WORKFLOW_SERIALIZE](instance: Snapshot): SerializedSnapshot {
+    return {
+      snapshot: instance.snapshot,
+    };
+  }
+
+  /**
+   * Deserialize a Snapshot from serialized data.
+   *
+   * The deserialized instance uses the serialized metadata synchronously and
+   * lazily creates an API client only when methods perform API requests.
+   *
+   * @param data - The serialized snapshot data
+   * @returns The reconstructed Snapshot instance
+   */
+  static [WORKFLOW_DESERIALIZE](data: SerializedSnapshot): Snapshot {
+    return new Snapshot({
+      snapshot: data.snapshot,
+    });
+  }
+
   constructor({
     client,
     snapshot,
   }: {
-    client: APIClient;
+    client?: APIClient;
     snapshot: SnapshotMetadata;
   }) {
-    this.client = client;
+    this._client = client ?? null;
     this.snapshot = snapshot;
   }
 
@@ -151,7 +194,8 @@ export class Snapshot {
    */
   async delete(opts?: { signal?: AbortSignal }): Promise<void> {
     "use step";
-    const response = await this.client!.deleteSnapshot({
+    const client = await this.ensureClient();
+    const response = await client.deleteSnapshot({
       snapshotId: this.snapshot.id,
       signal: opts?.signal,
     });