zeitlich 0.2.36 → 0.2.37

package/src/lib/sandbox/tree.integration.test.ts

@@ -3,7 +3,10 @@ import { toTree } from "./tree";
 import type { SandboxFileSystem, DirentEntry } from "./types";
 
 function createMockFs(
-  structure: Record<string, { isDir: boolean; isLink?: boolean; linkTarget?: string }>,
+  structure: Record<
+    string,
+    { isDir: boolean; isLink?: boolean; linkTarget?: string }
+  >
 ): SandboxFileSystem {
   return {
     workspaceBase: "/",
@@ -21,13 +24,17 @@ function createMockFs(
     readdir: async (dir: string) => {
       const prefix = dir.endsWith("/") ? dir : dir + "/";
       return Object.keys(structure)
-        .filter((p) => p.startsWith(prefix) && !p.slice(prefix.length).includes("/"))
+        .filter(
+          (p) => p.startsWith(prefix) && !p.slice(prefix.length).includes("/")
+        )
         .map((p) => p.slice(prefix.length));
     },
     readdirWithFileTypes: async (dir: string): Promise<DirentEntry[]> => {
       const prefix = dir.endsWith("/") ? dir : dir + "/";
       return Object.entries(structure)
-        .filter(([p]) => p.startsWith(prefix) && !p.slice(prefix.length).includes("/"))
+        .filter(
+          ([p]) => p.startsWith(prefix) && !p.slice(prefix.length).includes("/")
+        )
         .map(([p, meta]) => ({
           name: p.slice(prefix.length),
           isFile: !meta.isDir && !meta.isLink,

package/src/lib/sandbox/types.ts

@@ -17,6 +17,21 @@ export interface FileStat {
   mtime: Date;
 }
 
+// ============================================================================
+// Network & lifecycle
+// ============================================================================
+
+export interface SandboxNetworkConfig {
+  allowOut?: string[];
+  denyOut?: string[];
+  allowPublicTraffic?: boolean;
+}
+
+export interface SandboxLifecycleConfig {
+  onTimeout: "kill" | "pause";
+  autoResume?: boolean;
+}
+
 /**
  * Provider-agnostic filesystem interface.
  *
@@ -114,6 +129,16 @@ export interface SandboxCreateOptions {
   initialFiles?: Record<string, string | Uint8Array>;
   /** Environment variables available inside the sandbox */
   env?: Record<string, string>;
+  /** Key-value metadata surfaced via provider list/query APIs */
+  metadata?: Record<string, string>;
+  /** Sandbox idle timeout in milliseconds */
+  timeoutMs?: number;
+  /** Enable or disable outbound internet access */
+  allowInternetAccess?: boolean;
+  /** Outbound network allow/deny rules */
+  network?: SandboxNetworkConfig;
+  /** Sandbox timeout behaviour */
+  lifecycle?: SandboxLifecycleConfig;
 }
 
 export interface SandboxCreateResult {
@@ -135,6 +160,8 @@ export interface SandboxProvider<
   resume(sandboxId: string): Promise<void>;
   snapshot(sandboxId: string): Promise<SandboxSnapshot>;
   restore(snapshot: SandboxSnapshot): Promise<Sandbox>;
+  /** Delete a previously captured snapshot. No-op if already deleted. */
+  deleteSnapshot(snapshot: SandboxSnapshot): Promise<void>;
   fork(sandboxId: string): Promise<Sandbox>;
 }
 
@@ -155,6 +182,10 @@ export interface SandboxOps<
   /** Resume a paused sandbox. No-op if already running. */
   resumeSandbox(sandboxId: string): Promise<void>;
   snapshotSandbox(sandboxId: string): Promise<SandboxSnapshot>;
+  /** Create a fresh sandbox from a previously captured snapshot. */
+  restoreSandbox(snapshot: SandboxSnapshot): Promise<string>;
+  /** Delete a previously captured snapshot. No-op if already deleted. */
+  deleteSandboxSnapshot(snapshot: SandboxSnapshot): Promise<void>;
   forkSandbox(sandboxId: string): Promise<string>;
 }
 
@@ -172,7 +203,10 @@ export type PrefixedSandboxOps<
   TOptions extends SandboxCreateOptions = SandboxCreateOptions,
   TCtx = unknown,
 > = {
-  [K in keyof SandboxOps<TOptions, TCtx> as `${TPrefix}${Capitalize<K & string>}`]: SandboxOps<TOptions, TCtx>[K];
+  [K in keyof SandboxOps<
+    TOptions,
+    TCtx
+  > as `${TPrefix}${Capitalize<K & string>}`]: SandboxOps<TOptions, TCtx>[K];
 };
 
 // ============================================================================

package/src/lib/session/session-edge-cases.integration.test.ts

@@ -42,7 +42,13 @@ vi.mock("@temporalio/workflow", () => {
     uuid4: () =>
       `00000000-0000-0000-0000-${String(++idCounter).padStart(12, "0")}`,
     ApplicationFailure: MockApplicationFailure,
-    log: { trace: () => {}, debug: () => {}, info: () => {}, warn: () => {}, error: () => {} },
+    log: {
+      trace: () => {},
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+    },
   };
 });
 
@@ -61,7 +67,9 @@ type TurnScript = {
  * Wraps every method on a ThreadOps object so it also has `.executeWithOptions()`,
  * matching Temporal's `ActivityInterfaceFor<ThreadOps>` shape.
  */
-function toActivityInterface<TContent = string>(raw: ThreadOps<TContent>): ActivityInterfaceFor<ThreadOps<TContent>> {
+function toActivityInterface<TContent = string>(
+  raw: ThreadOps<TContent>
+): ActivityInterfaceFor<ThreadOps<TContent>> {
   const result = {} as Record<string, unknown>;
   for (const [key, fn] of Object.entries(raw)) {
     const wrapped = (...args: unknown[]) =>
@@ -433,6 +441,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sandbox-id",
+      restoreSandbox: async () => "restored-sandbox-id",
+      deleteSandboxSnapshot: async () => {},
       pauseSandbox: async () => {},
       resumeSandbox: async () => {},
     };
@@ -476,6 +486,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sandbox-id",
+      restoreSandbox: async () => "restored-sandbox-id",
+      deleteSandboxSnapshot: async () => {},
       pauseSandbox: async () => {},
       resumeSandbox: async () => {},
     };
@@ -765,7 +777,11 @@ describe("createSession edge cases", () => {
       },
     });
 
-    const session = await createSession<Record<string, never>, unknown, TestContent>({
+    const session = await createSession<
+      Record<string, never>,
+      unknown,
+      TestContent
+    >({
       agentName: "TestAgent",
       thread: { mode: "new", threadId: "thread-1" },
       runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
@@ -940,6 +956,8 @@ describe("createSession edge cases", () => {
       destroySandbox: async () => {},
       snapshotSandbox: snapshotSpy,
       forkSandbox: async () => "forked-sandbox-id",
+      restoreSandbox: async () => "restored-sandbox-id",
+      deleteSandboxSnapshot: async () => {},
       pauseSandbox: async () => {},
       resumeSandbox: async () => {},
     };
@@ -1040,6 +1058,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -1074,6 +1094,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -1119,6 +1141,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -1166,6 +1190,8 @@ describe("createSession edge cases", () => {
         sandboxLog.push(`fork:${id}`);
         return `forked-from-${id}`;
       },
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -1186,7 +1212,9 @@ describe("createSession edge cases", () => {
 
     expect(sandboxLog).toContain("fork:paused-sb-1");
     expect(sandboxLog).not.toContain("create");
-    expect((result as { sandboxId?: string }).sandboxId).toBe("forked-from-paused-sb-1");
+    expect((result as { sandboxId?: string }).sandboxId).toBe(
+      "forked-from-paused-sb-1"
+    );
     expect(sandboxLog).toContain("destroy:forked-from-paused-sb-1");
   });
 
@@ -1210,6 +1238,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -1253,6 +1283,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -1297,6 +1329,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -1370,9 +1404,7 @@ describe("createSession edge cases", () => {
 
     const session = await createSession({
       agentName: "TestAgent",
-      runAgent: createScriptedRunAgent([
-        { message: "done", toolCalls: [] },
-      ]),
+      runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
       threadOps: ops,
       buildContextMessage: () => "go",
     });
@@ -1413,6 +1445,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -1431,9 +1465,7 @@ describe("createSession edge cases", () => {
       initialState: { systemPrompt: "test" },
     });
 
-    await expect(session.runSession({ stateManager })).rejects.toThrow(
-      "crash"
-    );
+    await expect(session.runSession({ stateManager })).rejects.toThrow("crash");
 
     expect(sandboxLog).toContain("pause:sb-err");
     expect(sandboxLog).not.toContain("destroy:sb-err");
@@ -1461,6 +1493,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -1503,6 +1537,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -1521,9 +1557,7 @@ describe("createSession edge cases", () => {
       initialState: { systemPrompt: "test" },
     });
 
-    await expect(session.runSession({ stateManager })).rejects.toThrow(
-      "crash"
-    );
+    await expect(session.runSession({ stateManager })).rejects.toThrow("crash");
 
     expect(sandboxLog).not.toContain("pause:sb-keep-err");
     expect(sandboxLog).not.toContain("destroy:sb-keep-err");
@@ -1553,6 +1587,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -1598,6 +1634,8 @@ describe("createSession edge cases", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({

package/src/lib/session/session.integration.test.ts

@@ -517,6 +517,8 @@ describe("createSession integration", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sandbox-id",
+      restoreSandbox: async () => "restored-sandbox-id",
+      deleteSandboxSnapshot: async () => {},
       pauseSandbox: async () => {},
       resumeSandbox: async () => {},
     };
@@ -559,6 +561,8 @@ describe("createSession integration", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sandbox-id",
+      restoreSandbox: async () => "restored-sandbox-id",
+      deleteSandboxSnapshot: async () => {},
       pauseSandbox: async () => {},
       resumeSandbox: async () => {},
     };
@@ -610,6 +614,8 @@ describe("createSession integration", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sb",
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
     };
 
     const session = await createSession({
@@ -822,6 +828,8 @@ describe("createSession integration", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sandbox-id",
+      restoreSandbox: async () => "restored-sandbox-id",
+      deleteSandboxSnapshot: async () => {},
       pauseSandbox: async () => {},
       resumeSandbox: async () => {},
     };
@@ -873,6 +881,8 @@ describe("createSession integration", () => {
         createdAt: new Date().toISOString(),
       }),
       forkSandbox: async () => "forked-sandbox-id",
+      restoreSandbox: async () => "restored-sandbox-id",
+      deleteSandboxSnapshot: async () => {},
       pauseSandbox: async () => {},
       resumeSandbox: async () => {},
     };
@@ -949,4 +959,133 @@ describe("createSession integration", () => {
     expect(result.usage.totalInputTokens).toBe(180);
     expect(result.usage.totalOutputTokens).toBe(90);
   });
+
+  // --- Snapshot-driven shutdown ---
+
+  it("captures base + exit snapshot and destroys sandbox on sandboxShutdown=snapshot", async () => {
+    const { ops } = createMockThreadOps();
+    const sandboxLog: string[] = [];
+    let snapCounter = 0;
+
+    const sandboxOps: SandboxOps = {
+      createSandbox: async () => {
+        sandboxLog.push("create");
+        return { sandboxId: "sb-snap" };
+      },
+      destroySandbox: async (id: string) => {
+        sandboxLog.push(`destroy:${id}`);
+      },
+      pauseSandbox: async () => {
+        sandboxLog.push("pause");
+      },
+      resumeSandbox: async () => {},
+      snapshotSandbox: async (id: string) => {
+        snapCounter += 1;
+        sandboxLog.push(`snapshot:${id}`);
+        return {
+          sandboxId: id,
+          providerId: "test",
+          data: { tag: `snap-${snapCounter}` },
+          createdAt: new Date().toISOString(),
+        };
+      },
+      restoreSandbox: async () => "restored-sb",
+      deleteSandboxSnapshot: async () => {},
+      forkSandbox: async () => "forked-sb",
+    };
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "new", threadId: "thread-snap" },
+      runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
+      threadOps: ops,
+      buildContextMessage: () => "go",
+      sandboxOps,
+      sandboxShutdown: "snapshot",
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "test" },
+    });
+
+    const result = await session.runSession({ stateManager });
+
+    expect(result.exitReason).toBe("completed");
+    expect(result.sandboxId).toBe("sb-snap");
+    expect(result.baseSnapshot?.data).toEqual({ tag: "snap-1" });
+    expect(result.snapshot?.data).toEqual({ tag: "snap-2" });
+    expect(sandboxLog).toEqual([
+      "create",
+      "snapshot:sb-snap",
+      "snapshot:sb-snap",
+      "destroy:sb-snap",
+    ]);
+    expect(sandboxLog).not.toContain("pause");
+  });
+
+  it("restores a sandbox when sandbox.mode=from-snapshot and skips base snapshot", async () => {
+    const { ops } = createMockThreadOps();
+    const sandboxLog: string[] = [];
+    const priorSnapshot = {
+      sandboxId: "sb-prior",
+      providerId: "test",
+      data: { tag: "prior" },
+      createdAt: new Date().toISOString(),
+    };
+
+    const sandboxOps: SandboxOps = {
+      createSandbox: async () => {
+        sandboxLog.push("create");
+        return { sandboxId: "sb-should-not-be-created" };
+      },
+      destroySandbox: async (id: string) => {
+        sandboxLog.push(`destroy:${id}`);
+      },
+      pauseSandbox: async () => {},
+      resumeSandbox: async () => {},
+      snapshotSandbox: async (id: string) => {
+        sandboxLog.push(`snapshot:${id}`);
+        return {
+          sandboxId: id,
+          providerId: "test",
+          data: { tag: "exit" },
+          createdAt: new Date().toISOString(),
+        };
+      },
+      restoreSandbox: async (snap) => {
+        sandboxLog.push(`restore:${(snap.data as { tag: string }).tag}`);
+        return "sb-restored";
+      },
+      deleteSandboxSnapshot: async () => {},
+      forkSandbox: async () => "forked-sb",
+    };
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "new", threadId: "thread-restore" },
+      runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
+      threadOps: ops,
+      buildContextMessage: () => "go",
+      sandboxOps,
+      sandbox: { mode: "from-snapshot", snapshot: priorSnapshot },
+      sandboxShutdown: "snapshot",
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "test" },
+    });
+
+    const result = await session.runSession({ stateManager });
+
+    expect(result.sandboxId).toBe("sb-restored");
+    // No base snapshot because the sandbox was restored, not freshly created.
+    expect(result.baseSnapshot).toBeUndefined();
+    expect(result.snapshot?.data).toEqual({ tag: "exit" });
+    expect(sandboxLog).toEqual([
+      "restore:prior",
+      "snapshot:sb-restored",
+      "destroy:sb-restored",
+    ]);
+    expect(sandboxLog).not.toContain("create");
+  });
 });

package/src/lib/session/session.ts

@@ -7,7 +7,7 @@ import {
 } from "@temporalio/workflow";
 import type { SessionExitReason } from "../types";
 import type { SessionConfig, ZeitlichSession } from "./types";
-import type { SandboxOps } from "../sandbox/types";
+import type { SandboxOps, SandboxSnapshot } from "../sandbox/types";
 import type {
   AgentState,
   AgentStateManager,
@@ -146,12 +146,14 @@ export async function createSession<
 
   const plugins: ToolMap[string][] = [];
   let destroySubagentSandboxes: (() => Promise<void>) | undefined;
+  let cleanupSubagentSnapshots: (() => Promise<void>) | undefined;
 
   if (subagents) {
     const result = buildSubagentRegistration(subagents);
     if (result) {
       plugins.push(result.registration);
       destroySubagentSandboxes = result.destroySubagentSandboxes;
+      cleanupSubagentSnapshots = result.cleanupSubagentSnapshots;
     }
   }
   if (skills) {
@@ -210,10 +212,13 @@ export async function createSession<
         }
       );
 
-      // --- Sandbox lifecycle: create, continue, fork, or inherit ----------
+      // --- Sandbox lifecycle: create, continue, fork, from-snapshot, or inherit ---
       const sandboxMode = sandboxInit?.mode;
       let sandboxId: string | undefined;
       let sandboxOwned = false;
+      let baseSnapshot: SandboxSnapshot | undefined;
+      let exitSnapshot: SandboxSnapshot | undefined;
+      let freshlyCreated = false;
 
       if (sandboxMode === "inherit") {
         const inheritInit = sandboxInit as {
@@ -252,6 +257,18 @@ export async function createSession<
           (sandboxInit as { mode: "fork"; sandboxId: string }).sandboxId
         );
         sandboxOwned = true;
+      } else if (sandboxMode === "from-snapshot") {
+        if (!sandboxOps) {
+          throw ApplicationFailure.create({
+            message: "No sandboxOps provided — cannot restore sandbox",
+            nonRetryable: true,
+          });
+        }
+        const snap = (
+          sandboxInit as { mode: "from-snapshot"; snapshot: SandboxSnapshot }
+        ).snapshot;
+        sandboxId = await sandboxOps.restoreSandbox(snap);
+        sandboxOwned = true;
       } else if (sandboxOps) {
         const skillFiles = skills ? collectSkillFiles(skills) : undefined;
         const ctx = (sandboxInit as { mode: "new"; ctx?: unknown } | undefined)
@@ -263,10 +280,24 @@ export async function createSession<
         if (result) {
           sandboxId = result.sandboxId;
           sandboxOwned = true;
+          freshlyCreated = true;
         }
       }
 
-      if (sandboxId && onSandboxReady) {
+      // Capture a base snapshot immediately after seeding so it can be reused
+      // as a template for future runs that want to skip the (potentially
+      // expensive) seed step.
+      if (
+        sandboxId &&
+        sandboxOwned &&
+        freshlyCreated &&
+        sandboxShutdown === "snapshot" &&
+        sandboxOps
+      ) {
+        baseSnapshot = await sandboxOps.snapshotSandbox(sandboxId);
+      }
+
+      if (sandboxId && sandboxOwned && onSandboxReady) {
         onSandboxReady(sandboxId);
       }
 
@@ -347,6 +378,7 @@ export async function createSession<
       );
 
       let exitReason: SessionExitReason = "completed";
+      let finalMessage: M | null = null;
 
       try {
         while (
@@ -385,21 +417,8 @@ export async function createSession<
           if (!toolRouter.hasTools() || rawToolCalls.length === 0) {
             stateManager.complete();
             exitReason = "completed";
-            log.info("session ended", {
-              agentName,
-              threadId,
-              exitReason,
-              turns: currentTurn,
-              durationMs: Date.now() - sessionStartMs,
-              usage: stateManager.getTotalUsage(),
-            });
-            return {
-              threadId,
-              finalMessage: message,
-              exitReason,
-              usage: stateManager.getTotalUsage(),
-              sandboxId,
-            } as Awaited<ReturnType<ZeitlichSession<M, boolean>["runSession"]>>;
+            finalMessage = message;
+            break;
           }
 
           const parsedToolCalls: ParsedToolCallUnion<T>[] = [];
@@ -480,12 +499,20 @@ export async function createSession<
             case "keep":
             case "keep-until-parent-close":
               break;
+            case "snapshot":
+              exitSnapshot = await sandboxOps.snapshotSandbox(sandboxId);
+              await sandboxOps.destroySandbox(sandboxId);
+              break;
           }
         }
 
         if (destroySubagentSandboxes) {
           await destroySubagentSandboxes();
         }
+
+        if (cleanupSubagentSnapshots) {
+          await cleanupSubagentSnapshots();
+        }
       }
 
       log.info("session ended", {
@@ -495,14 +522,18 @@ export async function createSession<
         turns: stateManager.getTurns(),
         durationMs: Date.now() - sessionStartMs,
         usage: stateManager.getTotalUsage(),
+        ...(baseSnapshot && { hasBaseSnapshot: true }),
+        ...(exitSnapshot && { hasExitSnapshot: true }),
       });
 
       return {
         threadId,
-        finalMessage: null,
+        finalMessage,
         exitReason,
         usage: stateManager.getTotalUsage(),
         sandboxId,
+        ...(baseSnapshot && { baseSnapshot }),
+        ...(exitSnapshot && { snapshot: exitSnapshot }),
       } as Awaited<ReturnType<ZeitlichSession<M, boolean>["runSession"]>>;
     },
   };

package/src/lib/session/types.ts

@@ -1,8 +1,5 @@
 import type { Duration } from "@temporalio/common";
-import type {
-  SessionExitReason,
-  ToolResultConfig,
-} from "../types";
+import type { SessionExitReason, ToolResultConfig } from "../types";
 import type {
   ToolMap,
   ToolCallResultUnion,
@@ -11,7 +8,7 @@ import type {
 import type { Hooks } from "../hooks/types";
 import type { SubagentConfig } from "../subagent/types";
 import type { Skill } from "../skills/types";
-import type { SandboxOps } from "../sandbox/types";
+import type { SandboxOps, SandboxSnapshot } from "../sandbox/types";
 import type { VirtualFsOps } from "../virtual-fs/types";
 import type { RunAgentActivity } from "../model/types";
 import type { AgentStateManager, JsonSerializable } from "../state/types";
@@ -219,6 +216,17 @@ export type SessionResult<
   finalMessage: M | null;
   exitReason: SessionExitReason;
   usage: ReturnType<AgentStateManager<TState>["getTotalUsage"]>;
+  /**
+   * Snapshot captured on exit when `sandboxShutdown === "snapshot"`.
+   */
+  snapshot?: SandboxSnapshot;
+  /**
+   * Snapshot captured immediately after sandbox seeding (before the agent
+   * loop starts) when `sandbox.mode === "new"` and
+   * `sandboxShutdown === "snapshot"`. Intended as a reusable "base" for new
+   * threads that want to skip re-seeding.
+   */
+  baseSnapshot?: SandboxSnapshot;
 } & (HasSandbox extends true
   ? { sandboxId: string }
   : { sandboxId?: undefined });