zeitlich 0.2.36 → 0.2.37

package/dist/index.js

@@ -1,4 +1,4 @@
-import { defineSignal, uuid4, setHandler, defineUpdate, ApplicationFailure, log, condition, defineQuery, proxySinks, workflowInfo, proxyActivities, getExternalWorkflowHandle, startChild } from '@temporalio/workflow';
+import { defineSignal, uuid4, setHandler, defineUpdate, ApplicationFailure, log, condition, defineQuery, proxySinks, workflowInfo, proxyActivities, getExternalWorkflowHandle, executeChild } from '@temporalio/workflow';
 import z14, { z } from 'zod';
 import { randomUUID, randomFillSync } from 'crypto';
 import { ApplicationFailure as ApplicationFailure$1 } from '@temporalio/common';
@@ -389,9 +389,7 @@ function createSubagentTool(subagents) {
     schema
   };
 }
-var childResultSignal = defineSignal("childResult");
 var childSandboxReadySignal = defineSignal("childSandboxReady");
-var destroySandboxSignal = defineSignal("destroySandbox");
 
 // src/lib/subagent/handler.ts
 function resolveSandboxConfig(config) {
@@ -415,25 +413,27 @@ function resolveSandboxConfig(config) {
 }
 function createSubagentHandler(subagents) {
   const { taskQueue: parentTaskQueue } = workflowInfo();
-  const childResults = /* @__PURE__ */ new Map();
+  const agentSandboxOps = /* @__PURE__ */ new Map();
+  for (const cfg of subagents) {
+    if (cfg.sandbox && cfg.sandbox !== "none") {
+      agentSandboxOps.set(cfg.agentName, cfg.sandbox.proxy(cfg.agentName));
+    }
+  }
   const pendingDestroys = /* @__PURE__ */ new Map();
   const threadSandboxes = /* @__PURE__ */ new Map();
   const persistentSandboxes = /* @__PURE__ */ new Map();
   const persistentSandboxCreating = /* @__PURE__ */ new Set();
   const lazyCreatorAgent = /* @__PURE__ */ new Map();
-  setHandler(childResultSignal, ({ childWorkflowId, result }) => {
-    childResults.set(childWorkflowId, result);
-  });
-  setHandler(
-    childSandboxReadySignal,
-    ({ childWorkflowId, sandboxId }) => {
-      const agentName = lazyCreatorAgent.get(childWorkflowId);
-      if (agentName && !persistentSandboxes.has(agentName)) {
-        persistentSandboxes.set(agentName, sandboxId);
-        lazyCreatorAgent.delete(childWorkflowId);
-      }
+  const threadSnapshots = /* @__PURE__ */ new Map();
+  const persistentBaseSnapshot = /* @__PURE__ */ new Map();
+  const persistentBaseSnapshotCreating = /* @__PURE__ */ new Set();
+  setHandler(childSandboxReadySignal, ({ childWorkflowId, sandboxId }) => {
+    const agentName = lazyCreatorAgent.get(childWorkflowId);
+    if (agentName && !persistentSandboxes.has(agentName)) {
+      persistentSandboxes.set(agentName, sandboxId);
+      lazyCreatorAgent.delete(childWorkflowId);
     }
-  );
+  });
   const handler = async (args, context) => {
     const config = subagents.find((s) => s.agentName === args.subagent);
     if (!config) {
@@ -444,6 +444,12 @@ function createSubagentHandler(subagents) {
     const childWorkflowId = `${args.subagent}-${getShortId()}`;
     const { sandboxId: parentSandboxId } = context;
     const sandboxCfg = resolveSandboxConfig(config.sandbox);
+    if (sandboxCfg.source !== "none" && !agentSandboxOps.has(config.agentName)) {
+      throw ApplicationFailure.create({
+        message: `Subagent "${config.agentName}" uses a sandbox but no \`sandbox.proxy\` is configured on its SubagentConfig`,
+        nonRetryable: true
+      });
+    }
     if (sandboxCfg.source === "inherit" && !parentSandboxId) {
       throw new Error(
         `Subagent "${config.agentName}" is configured with sandbox: "inherit" but the parent has no sandbox`
@@ -462,12 +468,39 @@ function createSubagentHandler(subagents) {
     let sandbox;
     let sandboxShutdownOverride;
     let isLazyCreator = false;
+    let isSnapshotBaseCreator = false;
     if (sandboxCfg.source === "inherit" && parentSandboxId) {
       if (sandboxCfg.continuation === "fork") {
         sandbox = { mode: "fork", sandboxId: parentSandboxId };
+      } else if (sandboxCfg.continuation === "snapshot") {
+        throw new Error(
+          `Subagent "${config.agentName}" has sandbox source "inherit" with continuation "snapshot" \u2014 snapshot continuation is only supported for source "own"`
+        );
       } else {
         sandbox = { mode: "inherit", sandboxId: parentSandboxId };
       }
+    } else if (sandboxCfg.source === "own" && sandboxCfg.continuation === "snapshot") {
+      const isLazy = sandboxCfg.init === "once";
+      let baseSnap;
+      if (continuationThreadId) {
+        baseSnap = threadSnapshots.get(continuationThreadId)?.snapshot;
+      }
+      if (!baseSnap && isLazy) {
+        baseSnap = persistentBaseSnapshot.get(config.agentName);
+        if (!baseSnap) {
+          if (persistentBaseSnapshotCreating.has(config.agentName)) {
+            await condition(() => persistentBaseSnapshot.has(config.agentName));
+            baseSnap = persistentBaseSnapshot.get(config.agentName);
+          } else {
+            persistentBaseSnapshotCreating.add(config.agentName);
+            isSnapshotBaseCreator = true;
+          }
+        }
+      }
+      if (baseSnap) {
+        sandbox = { mode: "from-snapshot", snapshot: baseSnap };
+      }
+      sandboxShutdownOverride = "snapshot";
     } else if (sandboxCfg.source === "own") {
       const isLazy = sandboxCfg.init === "once";
       let baseSandboxId;
@@ -518,31 +551,8 @@ function createSubagentHandler(subagents) {
       threadMode,
       sandboxSource: sandboxCfg.source
     });
-    const childHandle = await startChild(config.workflow, childOpts);
+    const childResult = await executeChild(config.workflow, childOpts);
     const effectiveShutdown = sandboxShutdownOverride ?? sandboxCfg.shutdown ?? "destroy";
-    if (effectiveShutdown === "pause-until-parent-close" || effectiveShutdown === "keep-until-parent-close") {
-      const key = isLazyCreator ? `persistent:${config.agentName}` : childWorkflowId;
-      pendingDestroys.set(key, childHandle);
-    }
-    await Promise.race([
-      condition(() => childResults.has(childWorkflowId)),
-      childHandle.result()
-    ]);
-    if (!childResults.has(childWorkflowId)) {
-      await condition(() => childResults.has(childWorkflowId));
-    }
-    const childResult = childResults.get(childWorkflowId);
-    childResults.delete(childWorkflowId);
-    if (!childResult) {
-      log.warn("subagent returned no result", {
-        subagent: config.agentName,
-        childWorkflowId
-      });
-      return {
-        toolResponse: "Subagent workflow did not signal a result",
-        data: null
-      };
-    }
     log.info("subagent completed", {
       subagent: config.agentName,
       childWorkflowId,
@@ -554,19 +564,42 @@ function createSubagentHandler(subagents) {
       usage,
       threadId: childThreadId,
       sandboxId: childSandboxId,
+      snapshot: childSnapshot,
+      baseSnapshot: childBaseSnapshot,
       metadata
     } = childResult;
     if (childSandboxId) {
-      if (sandboxCfg.source === "own" && sandboxCfg.init === "once" && !persistentSandboxes.has(config.agentName)) {
+      if (sandboxCfg.source === "own" && sandboxCfg.init === "once" && sandboxCfg.continuation !== "snapshot" && !persistentSandboxes.has(config.agentName)) {
         persistentSandboxes.set(config.agentName, childSandboxId);
-      } else if (allowsContinuation && childThreadId) {
+      } else if (allowsContinuation && childThreadId && sandboxCfg.source === "own" && sandboxCfg.continuation !== "snapshot") {
         threadSandboxes.set(childThreadId, childSandboxId);
       }
     }
+    if (childSandboxId && (effectiveShutdown === "pause-until-parent-close" || effectiveShutdown === "keep-until-parent-close")) {
+      const key = isLazyCreator ? `persistent:${config.agentName}` : childWorkflowId;
+      pendingDestroys.set(key, {
+        agentName: config.agentName,
+        sandboxId: childSandboxId
+      });
+    }
+    if (sandboxCfg.source === "own" && sandboxCfg.continuation === "snapshot") {
+      if (childSnapshot && childThreadId) {
+        threadSnapshots.set(childThreadId, {
+          agentName: config.agentName,
+          snapshot: childSnapshot
+        });
+      }
+      if (isSnapshotBaseCreator && childBaseSnapshot && !persistentBaseSnapshot.has(config.agentName)) {
+        persistentBaseSnapshot.set(config.agentName, childBaseSnapshot);
+      }
+    }
     if (isLazyCreator) {
       persistentSandboxCreating.delete(config.agentName);
       lazyCreatorAgent.delete(childWorkflowId);
     }
+    if (isSnapshotBaseCreator) {
+      persistentBaseSnapshotCreating.delete(config.agentName);
+    }
     if (!toolResponse) {
       return {
         toolResponse: "Subagent workflow returned no response",
@@ -602,22 +635,60 @@ function createSubagentHandler(subagents) {
     };
   };
   const destroySubagentSandboxes = async () => {
-    const handles = [...pendingDestroys.values()];
+    const entries = [...pendingDestroys.values()];
     pendingDestroys.clear();
     await Promise.all(
-      handles.map(async (handle) => {
+      entries.map(async ({ agentName, sandboxId }) => {
+        const ops = agentSandboxOps.get(agentName);
+        if (!ops) {
+          log.warn(
+            "Skipping sandbox destroy \u2014 no sandbox.proxy registered for agent",
+            { agentName, sandboxId }
+          );
+          return;
+        }
+        try {
+          await ops.destroySandbox(sandboxId);
+        } catch (err) {
+          log.warn("Failed to destroy subagent sandbox", {
+            agentName,
+            sandboxId,
+            error: err
+          });
+        }
+      })
+    );
+  };
+  const cleanupSubagentSnapshots = async () => {
+    const tagged = [];
+    for (const entry of threadSnapshots.values()) tagged.push(entry);
+    for (const [agentName, snapshot] of persistentBaseSnapshot.entries()) {
+      tagged.push({ agentName, snapshot });
+    }
+    threadSnapshots.clear();
+    persistentBaseSnapshot.clear();
+    await Promise.all(
+      tagged.map(async ({ agentName, snapshot }) => {
+        const ops = agentSandboxOps.get(agentName);
+        if (!ops) {
+          log.warn(
+            "Skipping snapshot delete \u2014 no sandbox.proxy registered for agent",
+            { agentName }
+          );
+          return;
+        }
         try {
-          await handle.signal(destroySandboxSignal);
-          await handle.result();
+          await ops.deleteSandboxSnapshot(snapshot);
         } catch (err) {
-          log.warn("Failed to signal destroySandbox to child workflow", {
+          log.warn("Failed to delete subagent snapshot", {
+            agentName,
             error: err
           });
         }
       })
     );
   };
-  return { handler, destroySubagentSandboxes };
+  return { handler, destroySubagentSandboxes, cleanupSubagentSnapshots };
 }
 
 // src/lib/subagent/register.ts
@@ -631,7 +702,7 @@ function buildSubagentRegistration(subagents) {
     if (s.hooks) subagentHooksMap.set(s.agentName, s.hooks);
   }
   const resolveSubagentName = (args) => args.subagent;
-  const { handler, destroySubagentSandboxes } = createSubagentHandler(subagents);
+  const { handler, destroySubagentSandboxes, cleanupSubagentSnapshots } = createSubagentHandler(subagents);
   const registration = {
     name: SUBAGENT_TOOL_NAME,
     enabled: () => getEnabled().length > 0,
@@ -655,7 +726,7 @@ function buildSubagentRegistration(subagents) {
       }
     }
   };
-  return { registration, destroySubagentSandboxes };
+  return { registration, destroySubagentSandboxes, cleanupSubagentSnapshots };
 }
 var READ_SKILL_TOOL_NAME = "ReadSkill";
 function buildReadSkillDescription(skills) {
@@ -728,9 +799,7 @@ function validateSkillNames(skills) {
   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(", ")}`);
   }
 }
 function buildSkillRegistration(skills) {
@@ -800,11 +869,13 @@ async function createSession({
   } = threadOps;
   const plugins = [];
   let destroySubagentSandboxes;
+  let cleanupSubagentSnapshots;
   if (subagents) {
     const result = buildSubagentRegistration(subagents);
     if (result) {
       plugins.push(result.registration);
       destroySubagentSandboxes = result.destroySubagentSandboxes;
+      cleanupSubagentSnapshots = result.cleanupSubagentSnapshots;
     }
   }
   if (skills) {
@@ -857,6 +928,9 @@ async function createSession({
       const sandboxMode = sandboxInit?.mode;
       let sandboxId;
       let sandboxOwned = false;
+      let baseSnapshot;
+      let exitSnapshot;
+      let freshlyCreated = false;
       if (sandboxMode === "inherit") {
         const inheritInit = sandboxInit;
         sandboxId = inheritInit.sandboxId;
@@ -889,6 +963,16 @@ async function createSession({
           sandboxInit.sandboxId
         );
         sandboxOwned = true;
+      } else if (sandboxMode === "from-snapshot") {
+        if (!sandboxOps) {
+          throw ApplicationFailure.create({
+            message: "No sandboxOps provided \u2014 cannot restore sandbox",
+            nonRetryable: true
+          });
+        }
+        const snap = sandboxInit.snapshot;
+        sandboxId = await sandboxOps.restoreSandbox(snap);
+        sandboxOwned = true;
       } else if (sandboxOps) {
         const skillFiles = skills ? collectSkillFiles(skills) : void 0;
         const ctx = sandboxInit?.ctx;
@@ -897,9 +981,13 @@ async function createSession({
         if (result) {
           sandboxId = result.sandboxId;
           sandboxOwned = true;
+          freshlyCreated = true;
         }
       }
-      if (sandboxId && onSandboxReady) {
+      if (sandboxId && sandboxOwned && freshlyCreated && sandboxShutdown === "snapshot" && sandboxOps) {
+        baseSnapshot = await sandboxOps.snapshotSandbox(sandboxId);
+      }
+      if (sandboxId && sandboxOwned && onSandboxReady) {
         onSandboxReady(sandboxId);
       }
       if (virtualFsConfig) {
@@ -965,6 +1053,7 @@ async function createSession({
         threadKey
       );
       let exitReason = "completed";
+      let finalMessage = null;
       try {
         while (stateManager.isRunning() && !stateManager.isTerminal() && stateManager.getTurns() < maxTurns) {
           stateManager.incrementTurns();
@@ -991,21 +1080,8 @@ 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
-            };
+            finalMessage = message;
+            break;
           }
           const parsedToolCalls = [];
           for (const tc of rawToolCalls) {
@@ -1077,11 +1153,21 @@ async function createSession({
             case "pause-until-parent-close":
               await sandboxOps.pauseSandbox(sandboxId);
               break;
+            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", {
         agentName,
@@ -1089,14 +1175,18 @@ async function createSession({
         exitReason,
         turns: stateManager.getTurns(),
         durationMs: Date.now() - sessionStartMs,
-        usage: stateManager.getTotalUsage()
+        usage: stateManager.getTotalUsage(),
+        ...baseSnapshot && { hasBaseSnapshot: true },
+        ...exitSnapshot && { hasExitSnapshot: true }
       });
       return {
         threadId,
-        finalMessage: null,
+        finalMessage,
         exitReason,
         usage: stateManager.getTotalUsage(),
-        sandboxId
+        sandboxId,
+        ...baseSnapshot && { baseSnapshot },
+        ...exitSnapshot && { snapshot: exitSnapshot }
       };
     }
   };
@@ -1385,44 +1475,16 @@ function defineSubagentWorkflow(config, fn) {
       ...workflowInput.thread && { thread: workflowInput.thread },
       ...workflowInput.sandbox && { sandbox: workflowInput.sandbox },
       onSandboxReady: (sandboxId) => {
-        void parentHandle.signal(childSandboxReadySignal, {
-          childWorkflowId: workflowInfo().workflowId,
-          sandboxId
-        });
+        const isReuse = workflowInput.sandbox?.mode === "continue";
+        if (!isReuse) {
+          void parentHandle.signal(childSandboxReadySignal, {
+            childWorkflowId: workflowInfo().workflowId,
+            sandboxId
+          });
+        }
       }
     };
-    const { destroySandbox, ...result } = await fn(
-      prompt,
-      sessionInput,
-      context ?? {}
-    );
-    if (effectiveShutdown === "pause-until-parent-close" || effectiveShutdown === "keep-until-parent-close") {
-      if (!destroySandbox) {
-        throw ApplicationFailure.create({
-          message: `Subagent "${config.name}" has sandboxShutdown="${effectiveShutdown}" but fn did not return a destroySandbox callback`,
-          nonRetryable: true
-        });
-      }
-      if (!result.sandboxId) {
-        throw ApplicationFailure.create({
-          message: `Subagent "${config.name}" has sandboxShutdown="${effectiveShutdown}" but fn did not return a sandboxId`,
-          nonRetryable: true
-        });
-      }
-    }
-    await parentHandle.signal(childResultSignal, {
-      childWorkflowId: workflowInfo().workflowId,
-      result
-    });
-    if (destroySandbox) {
-      let destroyRequested = false;
-      setHandler(destroySandboxSignal, () => {
-        destroyRequested = true;
-      });
-      await condition(() => destroyRequested);
-      await destroySandbox();
-    }
-    return result;
+    return fn(prompt, sessionInput, context ?? {});
   };
   Object.defineProperty(workflow, "name", { value: config.name });
   return Object.assign(workflow, {
@@ -1532,9 +1594,7 @@ function applyVirtualTreeMutations(stateManager, mutations) {
         tree = tree.filter((e) => e.path !== m.path);
         break;
       case "update":
-        tree = tree.map(
-          (e) => e.path === m.path ? { ...e, ...m.entry } : e
-        );
+        tree = tree.map((e) => e.path === m.path ? { ...e, ...m.entry } : e);
         break;
     }
   }
@@ -1593,7 +1653,9 @@ function formatVirtualFileTree(entries, opts = {}) {
 // src/lib/virtual-fs/queries.ts
 function hasFileWithMimeType(stateManager, pattern) {
   const tree = stateManager.get("fileTree");
-  const matchers = (Array.isArray(pattern) ? pattern : [pattern]).map(buildMatcher);
+  const matchers = (Array.isArray(pattern) ? pattern : [pattern]).map(
+    buildMatcher
+  );
   return tree.some((entry) => {
     const meta = entry.metadata;
     const mime = meta?.mimeType;
@@ -1654,7 +1716,9 @@ function proxyVirtualFsOps(scope, options) {
 // src/lib/skills/parse.ts
 function parseSkillFile(raw) {
   const trimmed = raw.replace(/^\uFEFF/, "");
-  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(
       "SKILL.md must start with YAML frontmatter delimited by ---"
@@ -1926,7 +1990,9 @@ function createTaskGetHandler(stateManager) {
     const task = stateManager.getTask(args.taskId) ?? null;
     if (!task) {
       return {
-        toolResponse: JSON.stringify({ error: `Task not found: ${args.taskId}` }),
+        toolResponse: JSON.stringify({
+          error: `Task not found: ${args.taskId}`
+        }),
         data: null
       };
     }
@@ -1969,7 +2035,9 @@ function createTaskUpdateHandler(stateManager) {
     const task = stateManager.getTask(args.taskId);
     if (!task) {
       return {
-        toolResponse: JSON.stringify({ error: `Task not found: ${args.taskId}` }),
+        toolResponse: JSON.stringify({
+          error: `Task not found: ${args.taskId}`
+        }),
         data: null
       };
     }
@@ -2079,6 +2147,8 @@ var FileSystemSkillProvider = class {
     this.fs = fs;
     this.baseDir = baseDir;
   }
+  fs;
+  baseDir;
   async listSkills() {
     const dirs = await this.discoverSkillDirs();
     const skills = [];
@@ -2094,9 +2164,7 @@ var FileSystemSkillProvider = class {
     return skills;
   }
   async getSkill(name) {
-    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(
@@ -2105,7 +2173,10 @@ var FileSystemSkillProvider = class {
     }
     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,
@@ -2125,7 +2196,10 @@ var FileSystemSkillProvider = class {
       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,
@@ -2299,6 +2373,7 @@ var SandboxManager = class {
     this.provider = provider;
     this.hooks = options?.hooks ?? {};
   }
+  provider;
   hooks;
   async create(options, ctx) {
     let providerOptions = options;
@@ -2327,7 +2402,7 @@ var SandboxManager = class {
     }
     const { sandbox } = await this.provider.create(providerOptions);
     if (this.hooks.onPostCreate) {
-      await this.hooks.onPostCreate(sandbox.id);
+      await this.hooks.onPostCreate(sandbox, ctx ?? {});
     }
     return { sandboxId: sandbox.id };
   }
@@ -2350,6 +2425,9 @@ var SandboxManager = class {
     const sandbox = await this.provider.restore(snapshot);
     return sandbox.id;
   }
+  async deleteSnapshot(snapshot) {
+    await this.provider.deleteSnapshot(snapshot);
+  }
   async fork(sandboxId) {
     const sandbox = await this.provider.fork(sandboxId);
     return sandbox.id;
@@ -2392,6 +2470,12 @@ var SandboxManager = class {
       snapshotSandbox: async (sandboxId) => {
         return this.snapshot(sandboxId);
       },
+      restoreSandbox: async (snapshot) => {
+        return this.restore(snapshot);
+      },
+      deleteSandboxSnapshot: async (snapshot) => {
+        await this.deleteSnapshot(snapshot);
+      },
       forkSandbox: async (sandboxId) => {
         return this.fork(sandboxId);
       }
@@ -2507,6 +2591,8 @@ var VirtualFileSystem = class {
       ]) : []
     );
   }
+  resolver;
+  ctx;
   workspaceBase;
   entries;
   directories;