zeitlich 0.2.41 → 0.2.42

package/dist/index.js

@@ -7,6 +7,16 @@ import { Context } from '@temporalio/activity';
 import { promises } from 'fs';
 
 // src/lib/session/session.ts
+
+// src/lib/session/types.ts
+function resolveSessionLifecycle(init, shutdown) {
+  const resolvedInit = init ?? { mode: "new" };
+  const resolvedShutdown = shutdown ?? "destroy";
+  return {
+    mode: resolvedInit.mode,
+    shutdown: resolvedShutdown
+  };
+}
 function createToolRouter(options) {
   const { appendToolResult } = options;
   const toolMap = /* @__PURE__ */ new Map();
@@ -435,6 +445,37 @@ function createSubagentTool(subagents) {
     schema
   };
 }
+
+// src/lib/subagent/types.ts
+function isSurvivalShutdown(s) {
+  return s === "pause" || s === "pause-until-parent-close" || s === "keep" || s === "keep-until-parent-close";
+}
+function resolveSubagentLifecycle(cfg, isLazyCreator) {
+  if (cfg.source !== "own") {
+    return {
+      shutdownOverride: cfg.shutdown,
+      mustSurvive: false
+    };
+  }
+  if (cfg.continuation === "snapshot") {
+    return {
+      shutdownOverride: "snapshot",
+      mustSurvive: false
+    };
+  }
+  const isLazy = cfg.init === "once";
+  const mustSurvive = isLazyCreator || cfg.continuation === "continue" || isLazy && cfg.continuation === "fork";
+  if (!mustSurvive) {
+    return { shutdownOverride: cfg.shutdown, mustSurvive: false };
+  }
+  if (isSurvivalShutdown(cfg.shutdown)) {
+    return { shutdownOverride: cfg.shutdown, mustSurvive };
+  }
+  return {
+    shutdownOverride: isLazyCreator ? "pause-until-parent-close" : "pause",
+    mustSurvive
+  };
+}
 var childSandboxReadySignal = defineSignal("childSandboxReady");
 
 // src/lib/subagent/handler.ts
@@ -460,10 +501,18 @@ function resolveSandboxConfig(config) {
 }
 function createSubagentHandler(subagents) {
   const { taskQueue: parentTaskQueue } = workflowInfo();
-  const agentSandboxOps = /* @__PURE__ */ new Map();
+  const agentDestroyOps = /* @__PURE__ */ new Map();
+  const agentDeleteSnapshotOps = /* @__PURE__ */ new Map();
   for (const cfg of subagents) {
-    if (cfg.sandbox && cfg.sandbox !== "none") {
-      agentSandboxOps.set(cfg.agentName, cfg.sandbox.proxy(cfg.agentName));
+    const cfgSandbox = cfg.sandbox;
+    if (!cfgSandbox || cfgSandbox === "none") continue;
+    if (cfgSandbox.continuation === "snapshot") {
+      const proxy = cfgSandbox.proxy(cfg.agentName);
+      agentDestroyOps.set(cfg.agentName, proxy);
+      agentDeleteSnapshotOps.set(cfg.agentName, proxy);
+    } else {
+      const proxy = cfgSandbox.proxy(cfg.agentName);
+      agentDestroyOps.set(cfg.agentName, proxy);
     }
   }
   const pendingDestroys = /* @__PURE__ */ new Map();
@@ -502,7 +551,7 @@ 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)) {
+    if (sandboxCfg.source !== "none" && !agentDestroyOps.has(config.agentName)) {
       throw ApplicationFailure.create({
         message: `Subagent "${config.agentName}" uses a sandbox but no \`sandbox.proxy\` is configured on its SubagentConfig`,
         nonRetryable: true
@@ -570,7 +619,6 @@ function createSubagentHandler(subagents) {
       if (baseSnap) {
         sandbox = { mode: "from-snapshot", snapshot: baseSnap };
       }
-      sandboxShutdownOverride = "snapshot";
     } else if (sandboxCfg.source === "own") {
       const isLazy = sandboxCfg.init === "once";
       let baseSandboxId;
@@ -606,12 +654,10 @@ function createSubagentHandler(subagents) {
           sandboxId: baseSandboxId
         };
       }
-      const userShutdown = sandboxCfg.shutdown;
-      const alreadySurvives = userShutdown === "pause-until-parent-close" || userShutdown === "keep-until-parent-close" || userShutdown === "pause" || userShutdown === "keep";
-      const mustSurvive = isLazyCreator || sandboxCfg.continuation === "continue" || isLazy && sandboxCfg.continuation === "fork";
-      if (mustSurvive && !alreadySurvives) {
-        sandboxShutdownOverride = isLazyCreator ? "pause-until-parent-close" : "pause";
-      }
+    }
+    {
+      const lifecycle = resolveSubagentLifecycle(sandboxCfg, isLazyCreator);
+      sandboxShutdownOverride = lifecycle.shutdownOverride;
     }
     const workflowInput = {
       ...thread && { thread },
@@ -756,7 +802,7 @@ function createSubagentHandler(subagents) {
     pendingDestroys.clear();
     await Promise.all(
       entries.map(async ({ agentName, sandboxId }) => {
-        const ops = agentSandboxOps.get(agentName);
+        const ops = agentDestroyOps.get(agentName);
         if (!ops) {
           log.warn(
             "Skipping sandbox destroy \u2014 no sandbox.proxy registered for agent",
@@ -786,7 +832,7 @@ function createSubagentHandler(subagents) {
     persistentBaseSnapshot.clear();
     await Promise.all(
       tagged.map(async ({ agentName, snapshot }) => {
-        const ops = agentSandboxOps.get(agentName);
+        const ops = agentDeleteSnapshotOps.get(agentName);
         if (!ops) {
           log.warn(
             "Skipping snapshot delete \u2014 no sandbox.proxy registered for agent",
@@ -938,29 +984,31 @@ function collectSkillFiles(skills) {
   }
   return files;
 }
-async function createSession({
-  agentName,
-  maxTurns = 50,
-  metadata = {},
-  runAgent,
-  threadOps,
-  buildContextMessage,
-  subagents,
-  skills,
-  tools = {},
-  processToolsInParallel = true,
-  hooks = {},
-  appendSystemPrompt = true,
-  threadKey,
-  sandboxOps,
-  thread: threadInit,
-  sandbox: sandboxInit,
-  sandboxShutdown = "destroy",
-  onSandboxReady,
-  onSessionExit,
-  virtualFs: virtualFsConfig,
-  virtualFsOps
-}) {
+async function createSession(config) {
+  const {
+    agentName,
+    maxTurns = 50,
+    metadata = {},
+    runAgent,
+    threadOps,
+    buildContextMessage,
+    subagents,
+    skills,
+    tools = {},
+    processToolsInParallel = true,
+    hooks = {},
+    appendSystemPrompt = true,
+    threadKey,
+    sandboxOps,
+    thread: threadInit,
+    sandbox: sandboxInit,
+    sandboxShutdown,
+    onSandboxReady,
+    onSessionExit,
+    virtualFs: virtualFsConfig,
+    virtualFsOps
+  } = config;
+  const wideOps = () => sandboxOps;
   const threadMode = threadInit?.mode ?? "new";
   let threadId;
   let sourceThreadId;
@@ -1044,7 +1092,12 @@ async function createSession({
           stateManager.run();
         }
       );
-      const sandboxMode = sandboxInit?.mode;
+      const lifecycle = resolveSessionLifecycle(
+        sandboxInit,
+        sandboxShutdown
+      );
+      const sandboxMode = lifecycle.mode;
+      const resolvedShutdown = lifecycle.shutdown;
       let sandboxId;
       let sandboxOwned = false;
       let baseSnapshot;
@@ -1067,8 +1120,8 @@ async function createSession({
           });
         }
         sandboxId = sandboxInit.sandboxId;
-        if (sandboxShutdown === "pause-until-parent-close") {
-          await sandboxOps.resumeSandbox(sandboxId);
+        if (resolvedShutdown === "pause-until-parent-close") {
+          await wideOps().resumeSandbox(sandboxId);
         }
         sandboxOwned = true;
       } else if (sandboxMode === "fork") {
@@ -1079,7 +1132,7 @@ async function createSession({
           });
         }
         const forkInit = sandboxInit;
-        sandboxId = await sandboxOps.forkSandbox(
+        sandboxId = await wideOps().forkSandbox(
           forkInit.sandboxId,
           forkInit.options
         );
@@ -1092,7 +1145,7 @@ async function createSession({
           });
         }
         const restoreInit = sandboxInit;
-        sandboxId = await sandboxOps.restoreSandbox(
+        sandboxId = await wideOps().restoreSandbox(
           restoreInit.snapshot,
           restoreInit.options
         );
@@ -1108,8 +1161,8 @@ async function createSession({
           freshlyCreated = true;
         }
       }
-      if (sandboxId && sandboxOwned && freshlyCreated && sandboxShutdown === "snapshot" && sandboxOps) {
-        baseSnapshot = await sandboxOps.snapshotSandbox(sandboxId);
+      if (sandboxId && sandboxOwned && freshlyCreated && resolvedShutdown === "snapshot" && sandboxOps) {
+        baseSnapshot = await wideOps().snapshotSandbox(sandboxId);
       }
       if (sandboxId && sandboxOwned && onSandboxReady) {
         onSandboxReady({
@@ -1310,19 +1363,19 @@ async function createSession({
         }
         await callSessionEnd(exitReason, stateManager.getTurns());
         if (sandboxOwned && sandboxId && sandboxOps) {
-          switch (sandboxShutdown) {
+          switch (resolvedShutdown) {
             case "destroy":
               await sandboxOps.destroySandbox(sandboxId);
               break;
             case "pause":
             case "pause-until-parent-close":
-              await sandboxOps.pauseSandbox(sandboxId);
+              await wideOps().pauseSandbox(sandboxId);
               break;
             case "keep":
             case "keep-until-parent-close":
               break;
             case "snapshot":
-              exitSnapshot = await sandboxOps.snapshotSandbox(sandboxId);
+              exitSnapshot = await wideOps().snapshotSandbox(sandboxId);
               await sandboxOps.destroySandbox(sandboxId);
               break;
           }
@@ -2670,6 +2723,9 @@ function getActivityContext() {
 }
 async function queryParentWorkflowState(client) {
   const { workflowExecution } = Context.current().info;
+  if (!workflowExecution) {
+    throw new Error("No workflow execution found");
+  }
   const handle = client.getHandle(
     workflowExecution.workflowId,
     workflowExecution.runId
@@ -2693,13 +2749,56 @@ function withParentWorkflowState(client, handler) {
 }
 
 // src/lib/sandbox/manager.ts
+var CAP_METHOD_TO_CAPABILITY = [
+  { method: "pause", capability: "pause" },
+  { method: "resume", capability: "resume" },
+  { method: "snapshot", capability: "snapshot" },
+  { method: "deleteSnapshot", capability: "snapshot" },
+  { method: "restore", capability: "restore" },
+  { method: "fork", capability: "fork" }
+];
 var SandboxManager = class {
   constructor(provider, options) {
     this.provider = provider;
     this.hooks = options?.hooks ?? {};
+    this.assertCapabilityRuntimeConsistency();
   }
   provider;
   hooks;
+  /**
+   * Verifies that the provider's runtime `supportedCapabilities` set is
+   * consistent with the gated methods physically present on the provider.
+   *
+   * Belt-and-suspenders complement to the type-level
+   * `ReadonlySet<TCaps & SandboxCapability>` constraint: TypeScript can
+   * prevent the runtime set from containing capabilities not declared in
+   * `TCaps`, but it cannot detect a provider that **declares** a cap in
+   * `TCaps` and forgets to include it in the runtime set (or that ships
+   * a method without listing its cap). Both shapes silently break
+   * activity registration, so we trip a loud failure at construction
+   * time instead.
+   *
+   * Adapters that derive both surfaces from a single `as const`
+   * capability array (the recommended pattern) pass this check by
+   * construction.
+   */
+  assertCapabilityRuntimeConsistency() {
+    const supported = this.provider.supportedCapabilities;
+    for (const { method, capability } of CAP_METHOD_TO_CAPABILITY) {
+      const hasMethod = typeof this.provider[method] === "function";
+      const declaresCap = supported.has(capability);
+      if (hasMethod && !declaresCap) {
+        throw new Error(
+          `Sandbox provider "${this.provider.id}" implements ${method}() but does not list "${capability}" in supportedCapabilities. Add the capability to the provider's runtime set so activities for it can be registered.`
+        );
+      }
+      if (declaresCap && !hasMethod) {
+        throw new Error(
+          `Sandbox provider "${this.provider.id}" lists "${capability}" in supportedCapabilities but does not implement ${method}(). Either add the method to the provider or remove the capability from supportedCapabilities.`
+        );
+      }
+    }
+  }
   async create(options, ctx) {
     let providerOptions = options;
     if (this.hooks.onPreCreate) {
@@ -2737,26 +2836,61 @@ var SandboxManager = class {
   async destroy(id) {
     await this.provider.destroy(id);
   }
+  /**
+   * Capability-gated lifecycle methods on the underlying provider.
+   *
+   * These manager methods always exist at runtime; calling one whose
+   * capability is absent from the provider's `supportedCapabilities`
+   * throws an error. The activities returned from
+   * {@link SandboxManager.createActivities} are gated at the type level
+   * via `TCaps`, which is where compile-time safety is enforced.
+   */
   async pause(id, ttlSeconds) {
-    await this.provider.pause(id, ttlSeconds);
+    const fn = this.providerMethod("pause");
+    if (!fn) throw this.unsupported("pause");
+    await fn.call(this.provider, id, ttlSeconds);
   }
   async resume(id) {
-    await this.provider.resume(id);
+    const fn = this.providerMethod("resume");
+    if (!fn) throw this.unsupported("resume");
+    await fn.call(this.provider, id);
   }
   async snapshot(id, options) {
-    return this.provider.snapshot(id, options);
+    const fn = this.providerMethod("snapshot");
+    if (!fn) throw this.unsupported("snapshot");
+    return fn.call(this.provider, id, options);
   }
   async restore(snapshot, options) {
-    const sandbox = await this.provider.restore(snapshot, options);
+    const fn = this.providerMethod("restore");
+    if (!fn) throw this.unsupported("restore");
+    const sandbox = await fn.call(this.provider, snapshot, options);
     return sandbox.id;
   }
   async deleteSnapshot(snapshot) {
-    await this.provider.deleteSnapshot(snapshot);
+    const fn = this.providerMethod("deleteSnapshot");
+    if (!fn) throw this.unsupported("deleteSnapshot");
+    await fn.call(this.provider, snapshot);
   }
   async fork(sandboxId, options) {
-    const sandbox = await this.provider.fork(sandboxId, options);
+    const fn = this.providerMethod("fork");
+    if (!fn) throw this.unsupported("fork");
+    const sandbox = await fn.call(this.provider, sandboxId, options);
     return sandbox.id;
   }
+  providerMethod(name) {
+    const value = this.provider[name];
+    return typeof value === "function" ? value : void 0;
+  }
+  /**
+   * Constructs the structured error thrown when an unsupported lifecycle
+   * method is invoked through the manager. Uses the public
+   * {@link SandboxNotSupportedError} symbol so consumers that catch on
+   * `instanceof SandboxNotSupportedError` (the documented compatibility
+   * path) keep matching after the refactor.
+   */
+  unsupported(name) {
+    return new SandboxNotSupportedError(name);
+  }
   /**
    * Returns Temporal activity functions with prefixed names.
    *
@@ -2764,6 +2898,11 @@ var SandboxManager = class {
    * to pass the workflow/scope name. Use the matching `proxy*SandboxOps()`
    * helper from the adapter's `/workflow` entrypoint on the workflow side.
    *
+   * Activities are only registered for capabilities the provider declares
+   * via {@link SandboxProvider.supportedCapabilities}: methods omitted
+   * from the cap set are not wrapped, and the returned object's type
+   * omits the corresponding keys.
+   *
    * @param scope - Workflow name (appended to the provider id)
    *
    * @example
@@ -2774,40 +2913,55 @@ var SandboxManager = class {
    *
    * const dmgr = new SandboxManager(new DaytonaSandboxProvider(config));
    * dmgr.createActivities("CodingAgent");
-   * // registers: daytonaCodingAgentCreateSandbox, …
+   * // registers: daytonaCodingAgentCreateSandbox, daytonaCodingAgentDestroySandbox
+   * // (snapshot/restore/fork/pause/resume omitted — Daytona doesn't declare them)
    * ```
    */
   createActivities(scope) {
     const prefix = `${this.provider.id}${scope.charAt(0).toUpperCase()}${scope.slice(1)}`;
+    const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+    const supported = this.provider.supportedCapabilities;
     const ops = {
       createSandbox: async (options, ctx) => {
         return this.create(options, ctx);
       },
       destroySandbox: async (sandboxId) => {
         await this.destroy(sandboxId);
-      },
-      pauseSandbox: async (sandboxId, ttlSeconds) => {
+      }
+    };
+    if (supported.has("pause")) {
+      ops.pauseSandbox = async (sandboxId, ttlSeconds) => {
         await this.pause(sandboxId, ttlSeconds);
-      },
-      resumeSandbox: async (sandboxId) => {
+      };
+    }
+    if (supported.has("resume")) {
+      ops.resumeSandbox = async (sandboxId) => {
         await this.resume(sandboxId);
-      },
-      snapshotSandbox: async (sandboxId, options) => {
+      };
+    }
+    if (supported.has("snapshot")) {
+      ops.snapshotSandbox = async (sandboxId, options) => {
         return this.snapshot(sandboxId, options);
-      },
-      restoreSandbox: async (snapshot, options) => {
-        return this.restore(snapshot, options);
-      },
-      deleteSandboxSnapshot: async (snapshot) => {
+      };
+      ops.deleteSandboxSnapshot = async (snapshot) => {
         await this.deleteSnapshot(snapshot);
-      },
-      forkSandbox: async (sandboxId, options) => {
+      };
+    }
+    if (supported.has("restore")) {
+      ops.restoreSandbox = async (snapshot, options) => {
+        return this.restore(snapshot, options);
+      };
+    }
+    if (supported.has("fork")) {
+      ops.forkSandbox = async (sandboxId, options) => {
         return this.fork(sandboxId, options);
-      }
-    };
-    const cap = (s) => s.charAt(0).toUpperCase() + s.slice(1);
+      };
+    }
+    const entries = Object.entries(ops).filter(
+      ([, v]) => typeof v === "function"
+    );
     return Object.fromEntries(
-      Object.entries(ops).map(([k, v]) => [`${prefix}${cap(k)}`, v])
+      entries.map(([k, v]) => [`${prefix}${cap(k)}`, v])
     );
   }
 };