zeitlich 0.2.32 → 0.2.34

package/src/lib/sandbox/types.ts

@@ -131,6 +131,8 @@ export interface SandboxProvider<
   get(sandboxId: string): Promise<TSandbox>;
   destroy(sandboxId: string): Promise<void>;
   pause(sandboxId: string, ttlSeconds?: number): Promise<void>;
+  /** Resume a paused sandbox. No-op if already running. */
+  resume(sandboxId: string): Promise<void>;
   snapshot(sandboxId: string): Promise<SandboxSnapshot>;
   restore(snapshot: SandboxSnapshot): Promise<Sandbox>;
   fork(sandboxId: string): Promise<Sandbox>;
@@ -150,6 +152,8 @@ export interface SandboxOps<
   ): Promise<{ sandboxId: string } | null>;
   destroySandbox(sandboxId: string): Promise<void>;
   pauseSandbox(sandboxId: string): Promise<void>;
+  /** Resume a paused sandbox. No-op if already running. */
+  resumeSandbox(sandboxId: string): Promise<void>;
   snapshotSandbox(sandboxId: string): Promise<SandboxSnapshot>;
   forkSandbox(sandboxId: string): Promise<string>;
 }

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

@@ -434,6 +434,7 @@ describe("createSession edge cases", () => {
       }),
       forkSandbox: async () => "forked-sandbox-id",
       pauseSandbox: async () => {},
+      resumeSandbox: async () => {},
     };
 
     const session = await createSession({
@@ -476,6 +477,7 @@ describe("createSession edge cases", () => {
       }),
       forkSandbox: async () => "forked-sandbox-id",
       pauseSandbox: async () => {},
+      resumeSandbox: async () => {},
     };
 
     const session = await createSession({
@@ -939,6 +941,7 @@ describe("createSession edge cases", () => {
       snapshotSandbox: snapshotSpy,
       forkSandbox: async () => "forked-sandbox-id",
       pauseSandbox: async () => {},
+      resumeSandbox: async () => {},
     };
 
     const session = await createSession({
@@ -1029,6 +1032,7 @@ describe("createSession edge cases", () => {
       createSandbox: async () => ({ sandboxId: "sb-created" }),
       destroySandbox: async () => {},
       pauseSandbox: async () => {},
+      resumeSandbox: async () => {},
       snapshotSandbox: async () => ({
         sandboxId: "sb-1",
         providerId: "test",
@@ -1062,6 +1066,7 @@ describe("createSession edge cases", () => {
       createSandbox: async () => ({ sandboxId: "sb" }),
       destroySandbox: async () => {},
       pauseSandbox: async () => {},
+      resumeSandbox: async () => {},
       snapshotSandbox: async () => ({
         sandboxId: "sb",
         providerId: "test",
@@ -1106,6 +1111,7 @@ describe("createSession edge cases", () => {
       pauseSandbox: async (id: string) => {
         sandboxLog.push(`pause:${id}`);
       },
+      resumeSandbox: async () => {},
       snapshotSandbox: async () => ({
         sandboxId: "sb-1",
         providerId: "test",
@@ -1149,6 +1155,7 @@ describe("createSession edge cases", () => {
         sandboxLog.push(`destroy:${id}`);
       },
       pauseSandbox: async () => {},
+      resumeSandbox: async () => {},
       snapshotSandbox: async () => ({
         sandboxId: "sb-1",
         providerId: "test",
@@ -1195,6 +1202,7 @@ describe("createSession edge cases", () => {
         sandboxLog.push(`destroy:${id}`);
       },
       pauseSandbox: async () => {},
+      resumeSandbox: async () => {},
       snapshotSandbox: async () => ({
         sandboxId: "sb-1",
         providerId: "test",
@@ -1237,6 +1245,7 @@ describe("createSession edge cases", () => {
       pauseSandbox: async (id: string) => {
         sandboxLog.push(`pause:${id}`);
       },
+      resumeSandbox: async () => {},
       snapshotSandbox: async () => ({
         sandboxId: "sb-1",
         providerId: "test",
@@ -1280,6 +1289,7 @@ describe("createSession edge cases", () => {
       pauseSandbox: async (id: string) => {
         sandboxLog.push(`pause:${id}`);
       },
+      resumeSandbox: async () => {},
       snapshotSandbox: async () => ({
         sandboxId: "sb-1",
         providerId: "test",
@@ -1395,6 +1405,7 @@ describe("createSession edge cases", () => {
       pauseSandbox: async (id: string) => {
         sandboxLog.push(`pause:${id}`);
       },
+      resumeSandbox: async () => {},
       snapshotSandbox: async () => ({
         sandboxId: "sb-1",
         providerId: "test",
@@ -1427,4 +1438,187 @@ describe("createSession edge cases", () => {
     expect(sandboxLog).toContain("pause:sb-err");
     expect(sandboxLog).not.toContain("destroy:sb-err");
   });
+
+  // --- sandboxShutdown: "keep-until-parent-close" ---
+
+  it("keeps sandbox running on exit when sandboxShutdown is keep-until-parent-close", async () => {
+    const { ops } = createMockThreadOps();
+    const sandboxLog: string[] = [];
+
+    const sandboxOps: SandboxOps = {
+      createSandbox: async () => ({ sandboxId: "sb-keep-parent" }),
+      destroySandbox: async (id: string) => {
+        sandboxLog.push(`destroy:${id}`);
+      },
+      pauseSandbox: async (id: string) => {
+        sandboxLog.push(`pause:${id}`);
+      },
+      resumeSandbox: async () => {},
+      snapshotSandbox: async () => ({
+        sandboxId: "sb-1",
+        providerId: "test",
+        data: null,
+        createdAt: new Date().toISOString(),
+      }),
+      forkSandbox: async () => "forked-sb",
+    };
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "new", threadId: "thread-1" },
+      runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
+      threadOps: ops,
+      buildContextMessage: () => "go",
+      sandboxOps,
+      sandboxShutdown: "keep-until-parent-close",
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "test" },
+    });
+
+    await session.runSession({ stateManager });
+
+    expect(sandboxLog).not.toContain("pause:sb-keep-parent");
+    expect(sandboxLog).not.toContain("destroy:sb-keep-parent");
+  });
+
+  it("keeps sandbox running on error when sandboxShutdown is keep-until-parent-close", async () => {
+    const { ops } = createMockThreadOps();
+    const sandboxLog: string[] = [];
+
+    const sandboxOps: SandboxOps = {
+      createSandbox: async () => ({ sandboxId: "sb-keep-err" }),
+      destroySandbox: async (id: string) => {
+        sandboxLog.push(`destroy:${id}`);
+      },
+      pauseSandbox: async (id: string) => {
+        sandboxLog.push(`pause:${id}`);
+      },
+      resumeSandbox: async () => {},
+      snapshotSandbox: async () => ({
+        sandboxId: "sb-1",
+        providerId: "test",
+        data: null,
+        createdAt: new Date().toISOString(),
+      }),
+      forkSandbox: async () => "forked-sb",
+    };
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "new", threadId: "thread-1" },
+      runAgent: async () => {
+        throw new Error("crash");
+      },
+      threadOps: ops,
+      buildContextMessage: () => "go",
+      sandboxOps,
+      sandboxShutdown: "keep-until-parent-close",
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "test" },
+    });
+
+    await expect(session.runSession({ stateManager })).rejects.toThrow(
+      "crash"
+    );
+
+    expect(sandboxLog).not.toContain("pause:sb-keep-err");
+    expect(sandboxLog).not.toContain("destroy:sb-keep-err");
+  });
+
+  // --- sandbox continue calls resumeSandbox only for pause-until-parent-close ---
+
+  it("calls resumeSandbox when sandbox mode is continue with pause-until-parent-close", async () => {
+    const { ops } = createMockThreadOps();
+    const sandboxLog: string[] = [];
+
+    const sandboxOps: SandboxOps = {
+      createSandbox: async () => ({ sandboxId: "new-sb" }),
+      destroySandbox: async (id: string) => {
+        sandboxLog.push(`destroy:${id}`);
+      },
+      pauseSandbox: async (id: string) => {
+        sandboxLog.push(`pause:${id}`);
+      },
+      resumeSandbox: async (id: string) => {
+        sandboxLog.push(`resume:${id}`);
+      },
+      snapshotSandbox: async () => ({
+        sandboxId: "sb-1",
+        providerId: "test",
+        data: null,
+        createdAt: new Date().toISOString(),
+      }),
+      forkSandbox: async () => "forked-sb",
+    };
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "new", threadId: "thread-1" },
+      runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
+      threadOps: ops,
+      buildContextMessage: () => "go",
+      sandboxOps,
+      sandbox: { mode: "continue", sandboxId: "paused-sb" },
+      sandboxShutdown: "pause-until-parent-close",
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "test" },
+    });
+
+    await session.runSession({ stateManager });
+
+    expect(sandboxLog).toContain("resume:paused-sb");
+    expect(sandboxLog).toContain("pause:paused-sb");
+  });
+
+  it("skips resumeSandbox when sandbox mode is continue with keep-until-parent-close", async () => {
+    const { ops } = createMockThreadOps();
+    const sandboxLog: string[] = [];
+
+    const sandboxOps: SandboxOps = {
+      createSandbox: async () => ({ sandboxId: "new-sb" }),
+      destroySandbox: async (id: string) => {
+        sandboxLog.push(`destroy:${id}`);
+      },
+      pauseSandbox: async (id: string) => {
+        sandboxLog.push(`pause:${id}`);
+      },
+      resumeSandbox: async (id: string) => {
+        sandboxLog.push(`resume:${id}`);
+      },
+      snapshotSandbox: async () => ({
+        sandboxId: "sb-1",
+        providerId: "test",
+        data: null,
+        createdAt: new Date().toISOString(),
+      }),
+      forkSandbox: async () => "forked-sb",
+    };
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "new", threadId: "thread-1" },
+      runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
+      threadOps: ops,
+      buildContextMessage: () => "go",
+      sandboxOps,
+      sandbox: { mode: "continue", sandboxId: "kept-sb" },
+      sandboxShutdown: "keep-until-parent-close",
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "test" },
+    });
+
+    await session.runSession({ stateManager });
+
+    expect(sandboxLog).not.toContain("resume:kept-sb");
+    expect(sandboxLog).not.toContain("pause:kept-sb");
+    expect(sandboxLog).not.toContain("destroy:kept-sb");
+  });
 });

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

@@ -518,6 +518,7 @@ describe("createSession integration", () => {
       }),
       forkSandbox: async () => "forked-sandbox-id",
       pauseSandbox: async () => {},
+      resumeSandbox: async () => {},
     };
 
     const session = await createSession({
@@ -559,6 +560,7 @@ describe("createSession integration", () => {
       }),
       forkSandbox: async () => "forked-sandbox-id",
       pauseSandbox: async () => {},
+      resumeSandbox: async () => {},
     };
 
     const session = await createSession({
@@ -600,6 +602,7 @@ describe("createSession integration", () => {
       createSandbox: async () => ({ sandboxId: "sb" }),
       destroySandbox: async () => {},
       pauseSandbox: async () => {},
+      resumeSandbox: async () => {},
       snapshotSandbox: async () => ({
         sandboxId: "sb",
         providerId: "test",
@@ -820,6 +823,7 @@ describe("createSession integration", () => {
       }),
       forkSandbox: async () => "forked-sandbox-id",
       pauseSandbox: async () => {},
+      resumeSandbox: async () => {},
     };
 
     const session = await createSession({
@@ -870,6 +874,7 @@ describe("createSession integration", () => {
       }),
       forkSandbox: async () => "forked-sandbox-id",
       pauseSandbox: async () => {},
+      resumeSandbox: async () => {},
     };
 
     const session = await createSession({

package/src/lib/session/session.ts

@@ -106,6 +106,7 @@ export async function createSession<
   thread: threadInit,
   sandbox: sandboxInit,
   sandboxShutdown = "destroy",
+  onSandboxReady,
   virtualFs: virtualFsConfig,
   virtualFsOps,
 }: SessionConfig<T, M, TContent>): Promise<ZeitlichSession<M, boolean>> {
@@ -236,6 +237,9 @@ export async function createSession<
         }
         sandboxId = (sandboxInit as { mode: "continue"; sandboxId: string })
           .sandboxId;
+        if (sandboxShutdown === "pause-until-parent-close") {
+          await sandboxOps.resumeSandbox(sandboxId);
+        }
         sandboxOwned = true;
       } else if (sandboxMode === "fork") {
         if (!sandboxOps) {
@@ -262,6 +266,10 @@ export async function createSession<
         }
       }
 
+      if (sandboxId && onSandboxReady) {
+        onSandboxReady(sandboxId);
+      }
+
       // --- Virtual filesystem init (independent of sandbox) ----------------
       if (virtualFsConfig) {
         if (!virtualFsOps) {
@@ -467,6 +475,7 @@ export async function createSession<
               await sandboxOps.pauseSandbox(sandboxId);
               break;
             case "keep":
+            case "keep-until-parent-close":
               break;
           }
         }

package/src/lib/session/types.ts

@@ -180,6 +180,11 @@ export interface SessionConfig<
    * Has no effect when the sandbox is inherited (`sandbox.mode === "inherit"`).
    */
   sandboxShutdown?: SubagentSandboxShutdown;
+  /**
+   * Called as soon as the sandbox is created (or resumed/forked), before the
+   * agent loop starts. Useful for signalling sandbox readiness to a parent.
+   */
+  onSandboxReady?: (sandboxId: string) => void;
 
   // ---------------------------------------------------------------------------
   // Virtual filesystem

package/src/lib/subagent/define.ts

@@ -21,7 +21,7 @@ import type { SubagentArgs } from "./tool";
  * // With parent-specific overrides
  * export const researcher = defineSubagent(researcherWorkflow, {
  *   thread: "fork",
- *   sandbox: { source: "own", shutdown: "pause" },
+ *   sandbox: { source: "own", continuation: "fork", shutdown: "pause" },
  *   hooks: {
  *     onPostExecution: ({ result }) => console.log(result),
  *   },

package/src/lib/subagent/handler.ts

@@ -22,19 +22,40 @@ import type {
   SandboxInit,
   SubagentSandboxShutdown,
 } from "../lifecycle";
-import { childResultSignal, destroySandboxSignal } from "./signals";
+import {
+  childResultSignal,
+  childSandboxReadySignal,
+  destroySandboxSignal,
+} from "./signals";
 
-/**
- * Resolve the shorthand/object `SubagentSandboxConfig` into a normalized form.
- */
-function resolveSandboxConfig(config?: SubagentSandboxConfig): {
+/** Normalized sandbox config after resolving the union. */
+interface ResolvedSandboxConfig {
   source: "none" | "inherit" | "own";
+  init: "per-call" | "once";
+  continuation: "continue" | "fork";
   shutdown?: SubagentSandboxShutdown;
-} {
-  if (!config || config === "none") return { source: "none" };
-  if (config === "inherit") return { source: "inherit" };
-  if (config === "own") return { source: "own" };
-  return { source: "own", shutdown: config.shutdown };
+}
+
+function resolveSandboxConfig(
+  config?: SubagentSandboxConfig
+): ResolvedSandboxConfig {
+  if (!config || config === "none") {
+    return { source: "none", init: "per-call", continuation: "fork" };
+  }
+  if (config.source === "inherit") {
+    return {
+      source: "inherit",
+      init: "per-call",
+      continuation: config.continuation,
+      shutdown: config.shutdown,
+    };
+  }
+  return {
+    source: "own",
+    init: config.init ?? "per-call",
+    continuation: config.continuation,
+    shutdown: config.shutdown,
+  };
 }
 
 /**
@@ -65,13 +86,30 @@ export function createSubagentHandler<
     string,
     Awaited<ReturnType<typeof startChild>>
   >();
-  /** Maps childThreadId → sandboxId for sandbox continuation across invocations */
+  /** Maps childThreadId → sandboxId for sandbox continuation across invocations (init: per-call) */
   const threadSandboxes = new Map<string, string>();
+  /** Maps agentName → sandboxId for persistent sandboxes (init: once) */
+  const persistentSandboxes = new Map<string, string>();
+  /** Tracks agents whose first lazy sandbox creation is in-flight (guards concurrent init) */
+  const persistentSandboxCreating = new Set<string>();
+  /** Reverse lookup: childWorkflowId → agentName for in-flight lazy creators */
+  const lazyCreatorAgent = new Map<string, string>();
 
   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 handler = async (
     args: SubagentArgs,
     context: RouterContext
@@ -111,25 +149,74 @@ export function createSubagentHandler<
 
     // --- Build sandbox init ---
     let sandbox: SandboxInit | undefined;
+    let sandboxShutdownOverride: SubagentSandboxShutdown | undefined;
+    let isLazyCreator = false;
+
     if (sandboxCfg.source === "inherit" && parentSandboxId) {
-      sandbox = {
-        mode: "inherit",
-        sandboxId: parentSandboxId,
-      };
+      if (sandboxCfg.continuation === "fork") {
+        sandbox = { mode: "fork", sandboxId: parentSandboxId };
+      } else {
+        sandbox = { mode: "inherit", sandboxId: parentSandboxId };
+      }
     } else if (sandboxCfg.source === "own") {
-      const prevSbId = continuationThreadId
-        ? threadSandboxes.get(continuationThreadId)
-        : undefined;
-      if (prevSbId) {
-        sandbox = { mode: "fork", sandboxId: prevSbId };
+      const isLazy = sandboxCfg.init === "once";
+
+      let baseSandboxId: string | undefined;
+      if (isLazy) {
+        baseSandboxId = persistentSandboxes.get(config.agentName);
+        if (!baseSandboxId) {
+          if (persistentSandboxCreating.has(config.agentName)) {
+            // Another call is already creating — wait for it to finish
+            await condition(() => persistentSandboxes.has(config.agentName));
+            baseSandboxId = persistentSandboxes.get(config.agentName);
+          } else {
+            // We're the first concurrent caller — claim the creator role
+            persistentSandboxCreating.add(config.agentName);
+            isLazyCreator = true;
+          }
+        }
+      } else if (continuationThreadId) {
+        baseSandboxId = threadSandboxes.get(continuationThreadId);
+      }
+
+      if (baseSandboxId) {
+        sandbox = {
+          mode: sandboxCfg.continuation === "continue" ? "continue" : "fork",
+          sandboxId: baseSandboxId,
+        };
+      }
+
+      // Ensure the sandbox survives for future continuation/fork:
+      // - first lazy call (creator): pause-until-parent-close so parent can clean up
+      // - continuation=continue: sandbox must survive for next call
+      // - lazy+fork (non-creator): template must survive for future forks
+      //
+      // Skip the override when the user already configured a *-until-parent-close
+      // shutdown — that already guarantees survival.
+      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";
       }
-      // When no previous sandbox, omit — the child will create its own via sandboxOps
     }
 
     const workflowInput: SubagentWorkflowInput = {
       ...(thread && { thread }),
       ...(sandbox && { sandbox }),
-      ...(sandboxCfg.shutdown && { sandboxShutdown: sandboxCfg.shutdown }),
+      sandboxShutdown:
+        sandboxShutdownOverride ?? sandboxCfg.shutdown ?? undefined,
     };
 
     const resolvedContext =
@@ -148,6 +235,10 @@ export function createSubagentHandler<
       taskQueue: config.taskQueue ?? parentTaskQueue,
     };
 
+    if (isLazyCreator) {
+      lazyCreatorAgent.set(childWorkflowId, config.agentName);
+    }
+
     log.info("subagent spawned", {
       subagent: config.agentName,
       childWorkflowId,
@@ -157,14 +248,18 @@ export function createSubagentHandler<
 
     const childHandle = await startChild(config.workflow, childOpts);
 
-    const effectiveShutdown = sandboxCfg.shutdown ?? "destroy";
-    const shouldDeferDestroy =
-      effectiveShutdown === "pause-until-parent-close" &&
-      (sandboxCfg.source === "own" ||
-        (allowsContinuation && sandboxCfg.source !== "inherit"));
-
-    if (shouldDeferDestroy) {
-      pendingDestroys.set(childWorkflowId, childHandle);
+    // Track child handles that need signaling at parent shutdown.
+    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);
     }
 
     // Wait for signal from child; race with child completion to propagate failures
@@ -205,8 +300,23 @@ export function createSubagentHandler<
       metadata,
     } = childResult;
 
-    if (allowsContinuation && childSandboxId && childThreadId) {
-      threadSandboxes.set(childThreadId, childSandboxId);
+    // Store sandbox ID for future continuation/fork
+    if (childSandboxId) {
+      if (
+        sandboxCfg.source === "own" &&
+        sandboxCfg.init === "once" &&
+        !persistentSandboxes.has(config.agentName)
+      ) {
+        // Fallback: signal may have already set this via childSandboxReadySignal
+        persistentSandboxes.set(config.agentName, childSandboxId);
+      } else if (allowsContinuation && childThreadId) {
+        threadSandboxes.set(childThreadId, childSandboxId);
+      }
+    }
+
+    if (isLazyCreator) {
+      persistentSandboxCreating.delete(config.agentName);
+      lazyCreatorAgent.delete(childWorkflowId);
     }
 
     if (!toolResponse) {

package/src/lib/subagent/index.ts

@@ -17,4 +17,8 @@ export { createSubagentHandler } from "./handler";
 export { defineSubagent } from "./define";
 export { defineSubagentWorkflow } from "./workflow";
 export { buildSubagentRegistration } from "./register";
-export { childResultSignal, destroySandboxSignal } from "./signals";
+export {
+  childResultSignal,
+  childSandboxReadySignal,
+  destroySandboxSignal,
+} from "./signals";

package/src/lib/subagent/signals.ts

@@ -1,8 +1,15 @@
 import { defineSignal } from "@temporalio/workflow";
-import type { ChildResultSignalPayload } from "./types";
+import type {
+  ChildResultSignalPayload,
+  ChildSandboxReadySignalPayload,
+} from "./types";
 
 export const childResultSignal =
   defineSignal<[ChildResultSignalPayload]>("childResult");
 
+/** Sent by a child workflow as soon as its sandbox is created, before the agent loop starts. */
+export const childSandboxReadySignal =
+  defineSignal<[ChildSandboxReadySignalPayload]>("childSandboxReady");
+
 /** Sent by the parent to tell a subagent it may destroy its sandbox. */
 export const destroySandboxSignal = defineSignal("destroySandbox");