zeitlich 0.2.33 → 0.2.34

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeitlich",
-  "version": "0.2.33",
+  "version": "0.2.34",
   "description": "[EXPERIMENTAL] An opinionated AI agent implementation for Temporal",
   "main": "./dist/index.js",
   "module": "./dist/index.js",

package/src/adapters/sandbox/bedrock/index.ts

@@ -237,6 +237,10 @@ export class BedrockSandboxProvider
     throw new SandboxNotSupportedError("pause");
   }
 
+  async resume(_sandboxId: string): Promise<void> {
+    // Bedrock sandboxes don't support pause, so resume is a no-op
+  }
+
   async snapshot(_sandboxId: string): Promise<SandboxSnapshot> {
     throw new SandboxNotSupportedError("snapshot");
   }

package/src/adapters/sandbox/bedrock/proxy.ts

@@ -50,6 +50,7 @@ export function proxyBedrockSandboxOps(
     createSandbox: acts[p("createSandbox")],
     destroySandbox: acts[p("destroySandbox")],
     pauseSandbox: acts[p("pauseSandbox")],
+    resumeSandbox: acts[p("resumeSandbox")],
     snapshotSandbox: acts[p("snapshotSandbox")],
     forkSandbox: acts[p("forkSandbox")],
   } as SandboxOps<BedrockSandboxCreateOptions>;

package/src/adapters/sandbox/daytona/index.ts

@@ -145,6 +145,10 @@ export class DaytonaSandboxProvider implements SandboxProvider<
     throw new SandboxNotSupportedError("pause");
   }
 
+  async resume(_sandboxId: string): Promise<void> {
+    // Daytona sandboxes don't support pause, so resume is a no-op
+  }
+
   async fork(_sandboxId: string): Promise<Sandbox> {
     throw new Error("Not implemented");
   }

package/src/adapters/sandbox/daytona/proxy.ts

@@ -50,6 +50,7 @@ export function proxyDaytonaSandboxOps(
     createSandbox: acts[p("createSandbox")],
     destroySandbox: acts[p("destroySandbox")],
     pauseSandbox: acts[p("pauseSandbox")],
+    resumeSandbox: acts[p("resumeSandbox")],
     snapshotSandbox: acts[p("snapshotSandbox")],
     forkSandbox: acts[p("forkSandbox")],
   } as SandboxOps<DaytonaSandboxCreateOptions>;

package/src/adapters/sandbox/e2b/index.ts

@@ -136,6 +136,10 @@ export class E2bSandboxProvider
     await sdkSandbox.pause();
   }
 
+  async resume(sandboxId: string): Promise<void> {
+    await E2bSdkSandbox.connect(sandboxId);
+  }
+
   async snapshot(_sandboxId: string): Promise<SandboxSnapshot> {
     throw new SandboxNotSupportedError("snapshot");
   }

package/src/adapters/sandbox/e2b/proxy.ts

@@ -50,6 +50,7 @@ export function proxyE2bSandboxOps(
     createSandbox: acts[p("createSandbox")],
     destroySandbox: acts[p("destroySandbox")],
     pauseSandbox: acts[p("pauseSandbox")],
+    resumeSandbox: acts[p("resumeSandbox")],
     snapshotSandbox: acts[p("snapshotSandbox")],
     forkSandbox: acts[p("forkSandbox")],
   } as SandboxOps<E2bSandboxCreateOptions>;

package/src/adapters/sandbox/inmemory/index.ts

@@ -163,6 +163,10 @@ export class InMemorySandboxProvider implements SandboxProvider {
     // In-memory: nothing to pause
   }
 
+  async resume(_sandboxId: string): Promise<void> {
+    // In-memory: nothing to resume
+  }
+
   async create(options?: SandboxCreateOptions): Promise<SandboxCreateResult> {
     const id = options?.id ?? getShortId();
     const initialFiles: InitialFiles = {};

package/src/adapters/sandbox/inmemory/proxy.ts

@@ -47,6 +47,7 @@ export function proxyInMemorySandboxOps(
     createSandbox: acts[p("createSandbox")],
     destroySandbox: acts[p("destroySandbox")],
     pauseSandbox: acts[p("pauseSandbox")],
+    resumeSandbox: acts[p("resumeSandbox")],
     snapshotSandbox: acts[p("snapshotSandbox")],
     forkSandbox: acts[p("forkSandbox")],
   } as SandboxOps;

package/src/lib/lifecycle.ts

@@ -25,8 +25,9 @@ export type ThreadInit =
  * - `"new"` — create a fresh sandbox. Optionally pass `ctx` to
  *   have the {@link SandboxManager}'s resolver produce creation options
  *   (e.g. initial files) from workflow arguments.
- * - `"continue"` — resume a previously-paused sandbox (this session takes
- *   ownership and the shutdown policy applies on exit).
+ * - `"continue"` — take ownership of an existing sandbox (paused or running).
+ *   Paused sandboxes are automatically resumed. The shutdown policy applies
+ *   on exit.
  * - `"fork"` — fork from an existing (or paused) sandbox; a new sandbox is
  *   created and owned by this session.
  * - `"inherit"` — use a sandbox owned by someone else (e.g. a parent agent).
@@ -56,7 +57,10 @@ export type SandboxShutdown = "destroy" | "pause" | "keep";
  * Includes all base {@link SandboxShutdown} values plus:
  * - `"pause-until-parent-close"` — pause the sandbox on exit, then wait for
  *   the parent workflow to signal when to destroy it.
+ * - `"keep-until-parent-close"` — leave the sandbox running on exit, then
+ *   wait for the parent workflow to signal when to destroy it.
  */
 export type SubagentSandboxShutdown =
   | SandboxShutdown
-  | "pause-until-parent-close";
+  | "pause-until-parent-close"
+  | "keep-until-parent-close";

package/src/lib/sandbox/manager.ts

@@ -166,6 +166,10 @@ export class SandboxManager<
     await this.provider.pause(id, ttlSeconds);
   }
 
+  async resume(id: string): Promise<void> {
+    await this.provider.resume(id);
+  }
+
   async snapshot(id: string): Promise<SandboxSnapshot> {
     return this.provider.snapshot(id);
   }
@@ -222,6 +226,9 @@ export class SandboxManager<
       ): Promise<void> => {
         await this.pause(sandboxId, ttlSeconds);
       },
+      resumeSandbox: async (sandboxId: string): Promise<void> => {
+        await this.resume(sandboxId);
+      },
       snapshotSandbox: async (sandboxId: string): Promise<SandboxSnapshot> => {
         return this.snapshot(sandboxId);
       },

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),
  *   },