zeitlich 0.2.33 → 0.2.35

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) {
@@ -317,7 +325,10 @@ export async function createSession<
         // "continue" — thread already exists, just append the new message
       } else {
         if (appendSystemPrompt) {
-          if (!systemPrompt || systemPrompt.trim() === "") {
+          if (
+            systemPrompt == null ||
+            (typeof systemPrompt === "string" && systemPrompt.trim() === "")
+          ) {
             throw ApplicationFailure.create({
               message: "No system prompt in state",
               nonRetryable: true,
@@ -467,6 +478,7 @@ export async function createSession<
               await sandboxOps.pauseSandbox(sandboxId);
               break;
             case "keep":
+            case "keep-until-parent-close":
               break;
           }
         }

package/src/lib/session/types.ts

@@ -1,5 +1,8 @@
 import type { Duration } from "@temporalio/common";
-import type { ToolResultConfig, SessionExitReason } from "../types";
+import type {
+  SessionExitReason,
+  ToolResultConfig,
+} from "../types";
 import type {
   ToolMap,
   ToolCallResultUnion,
@@ -50,7 +53,7 @@ export interface ThreadOps<TContent = string> {
   appendSystemMessage(
     threadId: string,
     id: string,
-    content: string,
+    content: unknown,
     threadKey?: string
   ): Promise<void>;
   /** Copy all messages from sourceThreadId into a new thread at targetThreadId */
@@ -180,6 +183,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/state/manager.ts

@@ -108,7 +108,7 @@ export function createAgentStateManager<
       return status === "RUNNING";
     },
 
-    getSystemPrompt(): string | undefined {
+    getSystemPrompt(): unknown {
       return systemPrompt;
     },
 
@@ -202,7 +202,7 @@ export function createAgentStateManager<
       }));
     },
 
-    setSystemPrompt(newSystemPrompt: string): void {
+    setSystemPrompt(newSystemPrompt: unknown): void {
       systemPrompt = newSystemPrompt;
     },
 

package/src/lib/state/types.ts

@@ -90,10 +90,10 @@ export interface AgentStateManager<TCustom extends JsonSerializable<TCustom>> {
   getTurns(): number;
 
   /** Get the system prompt */
-  getSystemPrompt(): string | undefined;
+  getSystemPrompt(): unknown;
 
   /** Set the system prompt */
-  setSystemPrompt(newSystemPrompt: string): void;
+  setSystemPrompt(newSystemPrompt: unknown): void;
 
   /** Get a custom state value by key */
   get<K extends keyof TCustom>(key: K): TCustom[K];

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