zeitlich 0.2.35 → 0.2.37

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 });

package/src/lib/skills/fs-provider.ts

@@ -24,7 +24,7 @@ import { parseSkillFile } from "./parse";
 export class FileSystemSkillProvider implements SkillProvider {
   constructor(
     private readonly fs: SandboxFileSystem,
-    private readonly baseDir: string,
+    private readonly baseDir: string
   ) {}
 
   async listSkills(): Promise<SkillMetadata[]> {
@@ -45,20 +45,21 @@ export class FileSystemSkillProvider implements SkillProvider {
   }
 
   async getSkill(name: string): Promise<Skill> {
-    const raw = await this.fs.readFile(
-      join(this.baseDir, name, "SKILL.md"),
-    );
+    const raw = await this.fs.readFile(join(this.baseDir, name, "SKILL.md"));
     const { frontmatter, body } = parseSkillFile(raw);
 
     if (frontmatter.name !== name) {
       throw new Error(
-        `Skill directory "${name}" contains SKILL.md with mismatched name "${frontmatter.name}"`,
+        `Skill directory "${name}" contains SKILL.md with mismatched name "${frontmatter.name}"`
       );
     }
 
     const location = join(this.baseDir, name);
     const resourcePaths = await this.discoverResources(name);
-    const resourceContents = await this.readResourceContents(location, resourcePaths);
+    const resourceContents = await this.readResourceContents(
+      location,
+      resourcePaths
+    );
     return {
       ...frontmatter,
       instructions: body,
@@ -80,7 +81,10 @@ export class FileSystemSkillProvider implements SkillProvider {
       const { frontmatter, body } = parseSkillFile(raw);
       const location = join(this.baseDir, dir);
       const resourcePaths = await this.discoverResources(dir);
-      const resourceContents = await this.readResourceContents(location, resourcePaths);
+      const resourceContents = await this.readResourceContents(
+        location,
+        resourcePaths
+      );
       skills.push({
         ...frontmatter,
         instructions: body,
@@ -119,7 +123,7 @@ export class FileSystemSkillProvider implements SkillProvider {
 
   private async readResourceContents(
     location: string,
-    resources: string[],
+    resources: string[]
   ): Promise<Record<string, string> | undefined> {
     if (resources.length === 0) return undefined;
     const contents: Record<string, string> = {};

package/src/lib/skills/handler.ts

@@ -18,7 +18,7 @@ function formatSkillResponse(skill: Skill): string {
   if (skill.location) {
     parts.push(`\nSkill directory: ${skill.location}`);
     parts.push(
-      "Relative paths in this skill resolve against the skill directory above.",
+      "Relative paths in this skill resolve against the skill directory above."
     );
   }
 

package/src/lib/skills/parse.ts

@@ -12,7 +12,9 @@ export function parseSkillFile(raw: string): {
   body: string;
 } {
   const trimmed = raw.replace(/^\uFEFF/, ""); // strip BOM
-  const match = trimmed.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?([\s\S]*)$/);
+  const match = trimmed.match(
+    /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n?([\s\S]*)$/
+  );
 
   if (!match) {
     throw new Error(

package/src/lib/skills/register.ts

@@ -11,9 +11,7 @@ function validateSkillNames(skills: SkillMetadata[]): void {
   const names = skills.map((s) => s.name);
   const dupes = names.filter((n, i) => names.indexOf(n) !== i);
   if (dupes.length > 0) {
-    throw new Error(
-      `Duplicate skill names: ${[...new Set(dupes)].join(", ")}`
-    );
+    throw new Error(`Duplicate skill names: ${[...new Set(dupes)].join(", ")}`);
   }
 }
 

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

@@ -47,7 +47,10 @@ Body content here.`;
     expect(frontmatter.license).toBe("MIT");
     expect(frontmatter.compatibility).toBe("linux-only");
     expect(frontmatter.allowedTools).toEqual(["bash", "grep", "read-file"]);
-    expect(frontmatter.metadata).toEqual({ author: "test-author", version: "1.0" });
+    expect(frontmatter.metadata).toEqual({
+      author: "test-author",
+      version: "1.0",
+    });
     expect(body).toBe("Body content here.");
   });
 
@@ -76,7 +79,7 @@ Body`;
 
   it("throws when frontmatter is missing", () => {
     expect(() => parseSkillFile("No frontmatter here")).toThrow(
-      "SKILL.md must start with YAML frontmatter",
+      "SKILL.md must start with YAML frontmatter"
     );
   });
 
@@ -87,7 +90,7 @@ description: Missing name
 Body`;
 
     expect(() => parseSkillFile(raw)).toThrow(
-      "SKILL.md frontmatter must include a 'name' field",
+      "SKILL.md frontmatter must include a 'name' field"
     );
   });
 
@@ -98,7 +101,7 @@ name: no-desc
 Body`;
 
     expect(() => parseSkillFile(raw)).toThrow(
-      "SKILL.md frontmatter must include a 'description' field",
+      "SKILL.md frontmatter must include a 'description' field"
     );
   });
 
@@ -114,7 +117,8 @@ description: No body content
   });
 
   it("handles CRLF line endings", () => {
-    const raw = "---\r\nname: crlf-skill\r\ndescription: CRLF test\r\n---\r\nBody with CRLF";
+    const raw =
+      "---\r\nname: crlf-skill\r\ndescription: CRLF test\r\n---\r\nBody with CRLF";
 
     const { frontmatter, body } = parseSkillFile(raw);
     expect(frontmatter.name).toBe("crlf-skill");
@@ -204,7 +208,7 @@ describe("createReadSkillTool", () => {
 
   it("throws when no skills are provided", () => {
     expect(() => createReadSkillTool([])).toThrow(
-      "createReadSkillTool requires at least one skill",
+      "createReadSkillTool requires at least one skill"
     );
   });
 });
@@ -242,7 +246,9 @@ describe("createReadSkillHandler", () => {
 
     const text = result.toolResponse as string;
     expect(text).toContain("Skill directory: /skills/skill-a");
-    expect(text).toContain("Relative paths in this skill resolve against the skill directory above.");
+    expect(text).toContain(
+      "Relative paths in this skill resolve against the skill directory above."
+    );
   });
 
   it("lists resources derived from resourceContents keys", () => {
@@ -298,17 +304,21 @@ describe("createReadSkillHandler", () => {
     const result = handler({ skill_name: "nonexistent" });
 
     expect(typeof result.toolResponse).toBe("string");
-    expect((result.toolResponse as string)).toContain("not found");
+    expect(result.toolResponse as string).toContain("not found");
     expect(result.data).toBeNull();
   });
 
   it("handles single skill", () => {
     const skills: Skill[] = [
-      { name: "skill-a", description: "First", instructions: "Instructions for A" },
+      {
+        name: "skill-a",
+        description: "First",
+        instructions: "Instructions for A",
+      },
     ];
     const handler = createReadSkillHandler(skills);
     const result = handler({ skill_name: "skill-a" });
-    expect((result.toolResponse as string)).toContain("Instructions for A");
+    expect(result.toolResponse as string).toContain("Instructions for A");
   });
 });
 
@@ -350,7 +360,9 @@ describe("buildSkillRegistration", () => {
       { name: "dupe", description: "First", instructions: "A" },
       { name: "dupe", description: "Second", instructions: "B" },
     ];
-    expect(() => buildSkillRegistration(skills)).toThrow("Duplicate skill names: dupe");
+    expect(() => buildSkillRegistration(skills)).toThrow(
+      "Duplicate skill names: dupe"
+    );
   });
 
   it("returns a complete tool entry with handler", () => {
@@ -389,7 +401,7 @@ describe("buildSkillRegistration", () => {
     if (!registration) return;
     const result = registration.handler(
       { skill_name: "test-skill" },
-      { threadId: "t-1", toolCallId: "tc-1", toolName: "ReadSkill" },
+      { threadId: "t-1", toolCallId: "tc-1", toolName: "ReadSkill" }
     );
 
     if (result instanceof Promise) {
@@ -414,9 +426,7 @@ describe("buildSkillRegistration", () => {
 // FileSystemSkillProvider — resource discovery
 // ---------------------------------------------------------------------------
 
-function createMockFs(
-  tree: Record<string, string | "DIR">,
-): SandboxFileSystem {
+function createMockFs(tree: Record<string, string | "DIR">): SandboxFileSystem {
   const dir = (entries: DirentEntry[]): DirentEntry[] => entries;
 
   return {

package/src/lib/state/manager.integration.test.ts

@@ -11,7 +11,13 @@ vi.mock("@temporalio/workflow", () => {
     setHandler: (_def: unknown, _handler: unknown) => {},
     uuid4: () =>
       `00000000-0000-0000-0000-${String(++idCounter).padStart(12, "0")}`,
-    log: { trace: () => {}, debug: () => {}, info: () => {}, warn: () => {}, error: () => {} },
+    log: {
+      trace: () => {},
+      debug: () => {},
+      info: () => {},
+      warn: () => {},
+      error: () => {},
+    },
   };
 });
 
@@ -148,7 +154,11 @@ describe("createAgentStateManager integration", () => {
     const sm = createAgentStateManager({});
 
     sm.updateUsage({ inputTokens: 100, outputTokens: 50 });
-    sm.updateUsage({ inputTokens: 200, outputTokens: 100, cachedWriteTokens: 30 });
+    sm.updateUsage({
+      inputTokens: 200,
+      outputTokens: 100,
+      cachedWriteTokens: 30,
+    });
     sm.updateUsage({ cachedReadTokens: 20, reasonTokens: 10 });
 
     expect(sm.getTotalUsage()).toEqual({

package/src/lib/subagent/define.ts

@@ -45,7 +45,7 @@ export function defineSubagent<
     taskQueue?: string;
     thread?: "new" | "fork" | "continue";
     sandbox?: SubagentSandboxConfig;
-  },
+  }
 ): SubagentConfig<TResult> {
   return {
     agentName: definition.agentName,