zeitlich 0.2.21 → 0.2.23

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

@@ -34,7 +34,11 @@ vi.mock("@temporalio/workflow", () => {
     condition: async (fn: () => boolean) => fn(),
     defineUpdate: (name: string) => ({ __type: "update", name }),
     defineQuery: (name: string) => ({ __type: "query", name }),
+    defineSignal: (name: string) => ({ __type: "signal", name }),
     setHandler: (_def: unknown, _handler: unknown) => {},
+    startChild: async () => ({ result: () => Promise.resolve(null) }),
+    workflowInfo: () => ({ taskQueue: "default-queue" }),
+    getExternalWorkflowHandle: () => ({ signal: async () => {} }),
     uuid4: () =>
       `00000000-0000-0000-0000-${String(++idCounter).padStart(12, "0")}`,
     ApplicationFailure: MockApplicationFailure,
@@ -56,12 +60,11 @@ type TurnScript = {
  * Wraps every method on a ThreadOps object so it also has `.executeWithOptions()`,
  * matching Temporal's `ActivityInterfaceFor<ThreadOps>` shape.
  */
-function toActivityInterface(
-  raw: ThreadOps,
-): ActivityInterfaceFor<ThreadOps> {
+function toActivityInterface(raw: ThreadOps): ActivityInterfaceFor<ThreadOps> {
   const result = {} as Record<string, unknown>;
   for (const [key, fn] of Object.entries(raw)) {
-    const wrapped = (...args: unknown[]) => (fn as (...a: unknown[]) => unknown)(...args);
+    const wrapped = (...args: unknown[]) =>
+      (fn as (...a: unknown[]) => unknown)(...args);
     wrapped.executeWithOptions = (_opts: unknown, args: unknown[]) =>
       (fn as (...a: unknown[]) => unknown)(...args);
     result[key] = wrapped;
@@ -75,14 +78,14 @@ function createMockThreadOps() {
     initializeThread: async (threadId) => {
       log.push({ op: "initializeThread", args: [threadId] });
     },
-    appendHumanMessage: async (threadId, content) => {
-      log.push({ op: "appendHumanMessage", args: [threadId, content] });
+    appendHumanMessage: async (threadId, id, content) => {
+      log.push({ op: "appendHumanMessage", args: [threadId, id, content] });
     },
-    appendToolResult: async (config) => {
-      log.push({ op: "appendToolResult", args: [config] });
+    appendToolResult: async (id, config) => {
+      log.push({ op: "appendToolResult", args: [id, config] });
     },
-    appendSystemMessage: async (threadId, content) => {
-      log.push({ op: "appendSystemMessage", args: [threadId, content] });
+    appendSystemMessage: async (threadId, id, content) => {
+      log.push({ op: "appendSystemMessage", args: [threadId, id, content] });
     },
     forkThread: async (source, target) => {
       log.push({ op: "forkThread", args: [source, target] });
@@ -91,7 +94,9 @@ function createMockThreadOps() {
   return { ops, log };
 }
 
-function createScriptedRunAgent(turns: TurnScript[]): RunAgentActivity<unknown> {
+function createScriptedRunAgent(
+  turns: TurnScript[]
+): RunAgentActivity<unknown> {
   let call = 0;
   return async () => {
     const turn = turns[call++];
@@ -113,7 +118,7 @@ function createEchoTool() {
     schema: z.object({ text: z.string() }),
     handler: async (
       args: { text: string },
-      _ctx: RouterContext,
+      _ctx: RouterContext
     ): Promise<ToolHandlerResponse<{ echoed: string }>> => ({
       toolResponse: `Echo: ${args.text}`,
       data: { echoed: args.text },
@@ -150,7 +155,7 @@ describe("createSession edge cases", () => {
 
     const session = await createSession({
       agentName: "TestAgent",
-      threadId: "thread-1",
+      thread: { mode: "new", threadId: "thread-1" },
       runAgent: createScriptedRunAgent([
         {
           message: "Need user input",
@@ -186,7 +191,7 @@ describe("createSession edge cases", () => {
 
     const session = await createSession({
       agentName: "TestAgent",
-      threadId: "thread-1",
+      thread: { mode: "new", threadId: "thread-1" },
       runAgent: createScriptedRunAgent([
         {
           message: "bad calls",
@@ -216,8 +221,11 @@ describe("createSession edge cases", () => {
 
     const errorResults = log.filter((l) => {
       if (l.op !== "appendToolResult") return false;
-      const config = l.args[0] as ToolResultConfig;
-      return typeof config.content === "string" && config.content.includes("Invalid tool call");
+      const config = l.args[1] as ToolResultConfig;
+      return (
+        typeof config.content === "string" &&
+        config.content.includes("Invalid tool call")
+      );
     });
     expect(errorResults).toHaveLength(2);
   });
@@ -229,7 +237,7 @@ describe("createSession edge cases", () => {
 
     const session = await createSession({
       agentName: "TestAgent",
-      threadId: "thread-1",
+      thread: { mode: "new", threadId: "thread-1" },
       runAgent: createScriptedRunAgent([
         {
           message: "no id",
@@ -260,7 +268,7 @@ describe("createSession edge cases", () => {
 
     const session = await createSession({
       agentName: "TestAgent",
-      threadId: "thread-1",
+      thread: { mode: "new", threadId: "thread-1" },
       runAgent: createScriptedRunAgent([
         {
           message: "I tried calling a tool",
@@ -298,7 +306,7 @@ describe("createSession edge cases", () => {
 
     const session = await createSession({
       agentName: "TestAgent",
-      threadId: "thread-1",
+      thread: { mode: "new", threadId: "thread-1" },
       runAgent: createScriptedRunAgent([
         {
           message: "calling fail",
@@ -328,7 +336,7 @@ describe("createSession edge cases", () => {
 
   // --- Tool handler throws without recovery ---
 
-  it("session fails when tool handler throws with no failure hook", async () => {
+  it("session completes when tool handler throws with no failure hook (error suppressed)", async () => {
     const { ops } = createMockThreadOps();
     let endReason: string | undefined;
 
@@ -343,7 +351,7 @@ describe("createSession edge cases", () => {
 
     const session = await createSession({
       agentName: "TestAgent",
-      threadId: "thread-1",
+      thread: { mode: "new", threadId: "thread-1" },
       runAgent: createScriptedRunAgent([
         {
           message: "calling fail",
@@ -364,10 +372,10 @@ describe("createSession edge cases", () => {
       initialState: { systemPrompt: "test" },
     });
 
-    await expect(session.runSession({ stateManager })).rejects.toThrow(
-      "unrecoverable tool",
-    );
-    expect(endReason).toBe("failed");
+    const result = await session.runSession({ stateManager });
+    expect(result.exitReason).toBe("completed");
+    expect(result.finalMessage).toBe("done");
+    expect(endReason).toBe("completed");
   });
 
   // --- Metadata passed through to hooks ---
@@ -379,11 +387,9 @@ describe("createSession edge cases", () => {
 
     const session = await createSession({
       agentName: "TestAgent",
-      threadId: "thread-1",
+      thread: { mode: "new", threadId: "thread-1" },
       metadata: { env: "test", version: 42 },
-      runAgent: createScriptedRunAgent([
-        { message: "done", toolCalls: [] },
-      ]),
+      runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
       threadOps: ops,
       buildContextMessage: () => "go",
       hooks: {
@@ -422,15 +428,17 @@ describe("createSession edge cases", () => {
         data: null,
         createdAt: new Date().toISOString(),
       }),
+      forkSandbox: async () => "forked-sandbox-id",
+      pauseSandbox: async () => {},
     };
 
     const session = await createSession({
       agentName: "TestAgent",
-      threadId: "thread-1",
+      thread: { mode: "new", threadId: "thread-1" },
       runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
       threadOps: ops,
       buildContextMessage: () => "go",
-      sandbox: sandboxOps,
+      sandboxOps,
     });
 
     const stateManager = createAgentStateManager({
@@ -438,7 +446,7 @@ describe("createSession edge cases", () => {
     });
 
     await expect(session.runSession({ stateManager })).rejects.toThrow(
-      "sandbox creation failed",
+      "sandbox creation failed"
     );
   });
 
@@ -462,17 +470,19 @@ describe("createSession edge cases", () => {
         data: null,
         createdAt: new Date().toISOString(),
       }),
+      forkSandbox: async () => "forked-sandbox-id",
+      pauseSandbox: async () => {},
     };
 
     const session = await createSession({
       agentName: "TestAgent",
-      threadId: "thread-1",
+      thread: { mode: "new", threadId: "thread-1" },
       runAgent: async () => {
         throw new Error("LLM crash");
       },
       threadOps: ops,
       buildContextMessage: () => "go",
-      sandbox: sandboxOps,
+      sandboxOps,
     });
 
     const stateManager = createAgentStateManager({
@@ -480,7 +490,7 @@ describe("createSession edge cases", () => {
     });
 
     await expect(session.runSession({ stateManager })).rejects.toThrow(
-      "LLM crash",
+      "LLM crash"
     );
 
     expect(sandboxLog).toContain("create");
@@ -494,7 +504,7 @@ describe("createSession edge cases", () => {
 
     const session = await createSession({
       agentName: "TestAgent",
-      threadId: "thread-1",
+      thread: { mode: "new", threadId: "thread-1" },
       runAgent: createScriptedRunAgent([]),
       threadOps: ops,
       buildContextMessage: () => "hi",
@@ -505,7 +515,7 @@ describe("createSession edge cases", () => {
     });
 
     await expect(session.runSession({ stateManager })).rejects.toThrow(
-      "No system prompt in state",
+      "No system prompt in state"
     );
   });
 
@@ -527,7 +537,7 @@ describe("createSession edge cases", () => {
 
     const session = await createSession({
       agentName: "TestAgent",
-      threadId: "thread-1",
+      thread: { mode: "new", threadId: "thread-1" },
       runAgent: createScriptedRunAgent([
         {
           message: "t1",
@@ -558,15 +568,14 @@ describe("createSession edge cases", () => {
     expect(result.usage.totalOutputTokens).toBe(50);
   });
 
-  // --- continueThread with no source thread ---
+  // --- Thread fork: new threadId from source ---
 
-  it("continueThread generates new threadId and forks when source is provided", async () => {
+  it("fork thread mode generates new threadId and forks when source is provided", async () => {
     const { ops, log } = createMockThreadOps();
 
     const session = await createSession({
       agentName: "TestAgent",
-      threadId: "original-thread",
-      continueThread: true,
+      thread: { mode: "fork", threadId: "original-thread" },
       runAgent: createScriptedRunAgent([
         { message: "continued", toolCalls: [] },
       ]),
@@ -597,7 +606,7 @@ describe("createSession edge cases", () => {
 
     const session = await createSession({
       agentName: "TestAgent",
-      threadId: "thread-1",
+      thread: { mode: "new", threadId: "thread-1" },
       maxTurns: 1,
       runAgent: createScriptedRunAgent([
         {
@@ -642,7 +651,7 @@ describe("createSession edge cases", () => {
 
     const session = await createSession({
       agentName: "TestAgent",
-      threadId: "thread-1",
+      thread: { mode: "new", threadId: "thread-1" },
       processToolsInParallel: false,
       runAgent: createScriptedRunAgent([
         {
@@ -675,7 +684,7 @@ describe("createSession edge cases", () => {
 
     const session = await createSession({
       agentName: "TestAgent",
-      threadId: "thread-1",
+      thread: { mode: "new", threadId: "thread-1" },
       runAgent: createScriptedRunAgent([
         {
           message: "mixed",
@@ -700,24 +709,27 @@ describe("createSession edge cases", () => {
 
     const toolResults = log.filter((l) => l.op === "appendToolResult");
     const echoResult = toolResults.find((l) => {
-      const config = l.args[0] as ToolResultConfig;
+      const config = l.args[1] as ToolResultConfig;
       return config.toolName === "Echo";
     });
     expect(echoResult).toBeDefined();
     if (echoResult) {
-      expect((echoResult.args[0] as ToolResultConfig).content).toBe("Echo: valid");
+      expect((echoResult.args[1] as ToolResultConfig).content).toBe(
+        "Echo: valid"
+      );
     }
 
     const unknownResult = toolResults.find((l) => {
-      const config = l.args[0] as ToolResultConfig;
+      const config = l.args[1] as ToolResultConfig;
       return config.toolName === "Unknown";
     });
     expect(unknownResult).toBeDefined();
     const unknownContent = unknownResult
-      ? (unknownResult.args[0] as ToolResultConfig).content
+      ? (unknownResult.args[1] as ToolResultConfig).content
       : undefined;
     expect(
-      typeof unknownContent === "string" && unknownContent.includes("Invalid tool call"),
+      typeof unknownContent === "string" &&
+        unknownContent.includes("Invalid tool call")
     ).toBe(true);
   });
 
@@ -728,10 +740,8 @@ describe("createSession edge cases", () => {
 
     const session = await createSession({
       agentName: "TestAgent",
-      threadId: "thread-1",
-      runAgent: createScriptedRunAgent([
-        { message: "done", toolCalls: [] },
-      ]),
+      thread: { mode: "new", threadId: "thread-1" },
+      runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
       threadOps: ops,
       buildContextMessage: () => [
         { type: "text", text: "Hello" },
@@ -749,7 +759,7 @@ describe("createSession edge cases", () => {
     expect(humanOps).toHaveLength(1);
     const humanOp = humanOps[0];
     if (!humanOp) throw new Error("expected human op");
-    const content = humanOp.args[1];
+    const content = humanOp.args[2];
     expect(Array.isArray(content)).toBe(true);
     const firstContent = (content as { type: string }[])[0];
     if (!firstContent) throw new Error("expected content item");
@@ -764,7 +774,7 @@ describe("createSession edge cases", () => {
 
     const session = await createSession({
       agentName: "TestAgent",
-      threadId: "thread-1",
+      thread: { mode: "new", threadId: "thread-1" },
       runAgent: createScriptedRunAgent([
         {
           message: "t1",
@@ -813,7 +823,7 @@ describe("createSession edge cases", () => {
 
     const session = await createSession({
       agentName: "TestAgent",
-      threadId: "thread-1",
+      thread: { mode: "new", threadId: "thread-1" },
       runAgent: createScriptedRunAgent([
         {
           message: "self",
@@ -834,7 +844,7 @@ describe("createSession edge cases", () => {
 
     const toolResults = log.filter((l) => {
       if (l.op !== "appendToolResult") return false;
-      const config = l.args[0] as ToolResultConfig;
+      const config = l.args[1] as ToolResultConfig;
       return config.toolName === "SelfAppend";
     });
     expect(toolResults).toHaveLength(0);
@@ -847,7 +857,7 @@ describe("createSession edge cases", () => {
 
     const session = await createSession({
       agentName: "TestAgent",
-      threadId: "thread-1",
+      thread: { mode: "new", threadId: "thread-1" },
       runAgent: createScriptedRunAgent([
         {
           message: "calling",
@@ -860,7 +870,10 @@ describe("createSession edge cases", () => {
       buildContextMessage: () => "go",
       hooks: {
         onPreToolUse: async ({ toolCall }) => {
-          if (toolCall.args && (toolCall.args as { text: string }).text === "skip-me") {
+          if (
+            toolCall.args &&
+            (toolCall.args as { text: string }).text === "skip-me"
+          ) {
             return { skip: true };
           }
           return {};
@@ -878,8 +891,10 @@ describe("createSession edge cases", () => {
     expect(toolResults).toHaveLength(1);
     const toolResult = toolResults[0];
     if (!toolResult) throw new Error("expected tool result");
-    const content = (toolResult.args[0] as ToolResultConfig).content;
-    expect(typeof content === "string" && content.includes("Skipped")).toBe(true);
+    const content = (toolResult.args[1] as ToolResultConfig).content;
+    expect(typeof content === "string" && content.includes("Skipped")).toBe(
+      true
+    );
   });
 
   // --- Sandbox snapshot is not called on normal flow ---
@@ -897,15 +912,17 @@ describe("createSession edge cases", () => {
       createSandbox: async () => ({ sandboxId: "sb-test" }),
       destroySandbox: async () => {},
       snapshotSandbox: snapshotSpy,
+      forkSandbox: async () => "forked-sandbox-id",
+      pauseSandbox: async () => {},
     };
 
     const session = await createSession({
       agentName: "TestAgent",
-      threadId: "thread-1",
+      thread: { mode: "new", threadId: "thread-1" },
       runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
       threadOps: ops,
       buildContextMessage: () => "go",
-      sandbox: sandboxOps,
+      sandboxOps,
     });
 
     const stateManager = createAgentStateManager({
@@ -924,7 +941,7 @@ describe("createSession edge cases", () => {
 
     const session = await createSession({
       agentName: "TestAgent",
-      threadId: "thread-1",
+      thread: { mode: "new", threadId: "thread-1" },
       runAgent: createScriptedRunAgent([
         {
           message: "t1",
@@ -959,7 +976,7 @@ describe("createSession edge cases", () => {
 
     const session = await createSession({
       agentName: "TestAgent",
-      threadId: "thread-1",
+      thread: { mode: "new", threadId: "thread-1" },
       maxTurns: 0,
       runAgent: createScriptedRunAgent([]),
       threadOps: ops,
@@ -977,4 +994,412 @@ describe("createSession edge cases", () => {
     expect(result.usage.turns).toBe(0);
     expect(result.finalMessage).toBeNull();
   });
+
+  // --- sandboxId returned from runSession ---
+
+  it("returns sandboxId from runSession when sandbox is created", async () => {
+    const { ops } = createMockThreadOps();
+
+    const sandboxOps: SandboxOps = {
+      createSandbox: async () => ({ sandboxId: "sb-created" }),
+      destroySandbox: async () => {},
+      pauseSandbox: 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,
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "test" },
+    });
+
+    const result = await session.runSession({ stateManager });
+    expect((result as { sandboxId?: string }).sandboxId).toBe("sb-created");
+  });
+
+  it("returns inherited sandboxId from runSession", async () => {
+    const { ops } = createMockThreadOps();
+
+    const sandboxOps: SandboxOps = {
+      createSandbox: async () => ({ sandboxId: "sb" }),
+      destroySandbox: async () => {},
+      pauseSandbox: async () => {},
+      snapshotSandbox: async () => ({
+        sandboxId: "sb",
+        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",
+      sandbox: { mode: "inherit", sandboxId: "inherited-sb" },
+      sandboxOps,
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "test" },
+    });
+
+    const result = await session.runSession({ stateManager });
+    expect((result as { sandboxId?: string }).sandboxId).toBe("inherited-sb");
+  });
+
+  // --- Inherited sandbox is not destroyed ---
+
+  it("does not destroy inherited sandbox even when sandboxOps is provided", async () => {
+    const { ops } = createMockThreadOps();
+    const sandboxLog: string[] = [];
+
+    const sandboxOps: SandboxOps = {
+      createSandbox: async () => {
+        sandboxLog.push("create");
+        return { sandboxId: "new-sb" };
+      },
+      destroySandbox: async (id: string) => {
+        sandboxLog.push(`destroy:${id}`);
+      },
+      pauseSandbox: async (id: string) => {
+        sandboxLog.push(`pause:${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: "inherit", sandboxId: "inherited-sb" },
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "test" },
+    });
+
+    await session.runSession({ stateManager });
+
+    expect(sandboxLog).toHaveLength(0);
+  });
+
+  // --- Sandbox fork ---
+
+  it("forks sandbox when sandbox init mode is fork", async () => {
+    const { ops } = createMockThreadOps();
+    const sandboxLog: string[] = [];
+
+    const sandboxOps: SandboxOps = {
+      createSandbox: async () => {
+        sandboxLog.push("create");
+        return { sandboxId: "new-sb" };
+      },
+      destroySandbox: async (id: string) => {
+        sandboxLog.push(`destroy:${id}`);
+      },
+      pauseSandbox: async () => {},
+      snapshotSandbox: async () => ({
+        sandboxId: "sb-1",
+        providerId: "test",
+        data: null,
+        createdAt: new Date().toISOString(),
+      }),
+      forkSandbox: async (id: string) => {
+        sandboxLog.push(`fork:${id}`);
+        return `forked-from-${id}`;
+      },
+    };
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "new", threadId: "thread-1" },
+      runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
+      threadOps: ops,
+      buildContextMessage: () => "go",
+      sandboxOps,
+      sandbox: { mode: "fork", sandboxId: "paused-sb-1" },
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "test" },
+    });
+
+    const result = await session.runSession({ stateManager });
+
+    expect(sandboxLog).toContain("fork:paused-sb-1");
+    expect(sandboxLog).not.toContain("create");
+    expect((result as { sandboxId?: string }).sandboxId).toBe("forked-from-paused-sb-1");
+    expect(sandboxLog).toContain("destroy:forked-from-paused-sb-1");
+  });
+
+  // --- Forked sandbox is destroyed on exit ---
+
+  it("destroys forked sandbox on exit (not inherited)", 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 () => {},
+      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: "fork", sandboxId: "old-sb" },
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "test" },
+    });
+
+    await session.runSession({ stateManager });
+
+    expect(sandboxLog).toContain("destroy:forked-sb");
+  });
+
+  // --- sandboxShutdown: "pause" ---
+
+  it("pauses sandbox on exit when sandboxShutdown is pause", async () => {
+    const { ops } = createMockThreadOps();
+    const sandboxLog: string[] = [];
+
+    const sandboxOps: SandboxOps = {
+      createSandbox: async () => ({ sandboxId: "sb-pause-test" }),
+      destroySandbox: async (id: string) => {
+        sandboxLog.push(`destroy:${id}`);
+      },
+      pauseSandbox: async (id: string) => {
+        sandboxLog.push(`pause:${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,
+      sandboxShutdown: "pause",
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "test" },
+    });
+
+    await session.runSession({ stateManager });
+
+    expect(sandboxLog).toContain("pause:sb-pause-test");
+    expect(sandboxLog).not.toContain("destroy:sb-pause-test");
+  });
+
+  // --- sandboxShutdown: "pause-until-parent-close" ---
+
+  it("pauses sandbox on exit when sandboxShutdown is pause-until-parent-close", async () => {
+    const { ops } = createMockThreadOps();
+    const sandboxLog: string[] = [];
+
+    const sandboxOps: SandboxOps = {
+      createSandbox: async () => ({ sandboxId: "sb-parent-close" }),
+      destroySandbox: async (id: string) => {
+        sandboxLog.push(`destroy:${id}`);
+      },
+      pauseSandbox: async (id: string) => {
+        sandboxLog.push(`pause:${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,
+      sandboxShutdown: "pause-until-parent-close",
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "test" },
+    });
+
+    await session.runSession({ stateManager });
+
+    expect(sandboxLog).toContain("pause:sb-parent-close");
+    expect(sandboxLog).not.toContain("destroy:sb-parent-close");
+  });
+
+  // --- Throws when sandbox fork/continue provided without sandboxOps ---
+
+  it("throws when sandbox fork mode is set without sandboxOps", async () => {
+    const { ops } = createMockThreadOps();
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "new", threadId: "thread-1" },
+      runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
+      threadOps: ops,
+      buildContextMessage: () => "go",
+      sandbox: { mode: "fork", sandboxId: "prev-sb" },
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "test" },
+    });
+
+    await expect(session.runSession({ stateManager })).rejects.toThrow(
+      "No sandboxOps provided — cannot fork sandbox"
+    );
+  });
+
+  // --- No sandboxId returned when no sandbox ---
+
+  it("does not return sandboxId when no sandbox is configured", async () => {
+    const { ops } = createMockThreadOps();
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      thread: { mode: "new", threadId: "thread-1" },
+      runAgent: createScriptedRunAgent([{ message: "done", toolCalls: [] }]),
+      threadOps: ops,
+      buildContextMessage: () => "go",
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "test" },
+    });
+
+    const result = await session.runSession({ stateManager });
+    expect((result as { sandboxId?: string }).sandboxId).toBeUndefined();
+  });
+
+  // --- Thread: defaults to new thread when no thread field provided ---
+
+  it("defaults to new thread without fork when no thread field is provided", async () => {
+    const { ops, log } = createMockThreadOps();
+
+    const session = await createSession({
+      agentName: "TestAgent",
+      runAgent: createScriptedRunAgent([
+        { message: "done", toolCalls: [] },
+      ]),
+      threadOps: ops,
+      buildContextMessage: () => "go",
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "test" },
+    });
+
+    const result = await session.runSession({ stateManager });
+    expect(result.exitReason).toBe("completed");
+
+    const forkOps = log.filter((l) => l.op === "forkThread");
+    expect(forkOps).toHaveLength(0);
+
+    const systemOps = log.filter((l) => l.op === "appendSystemMessage");
+    expect(systemOps).toHaveLength(1);
+  });
+
+  // --- Sandbox pause on error ---
+
+  it("pauses sandbox even when session fails if sandboxShutdown is pause", async () => {
+    const { ops } = createMockThreadOps();
+    const sandboxLog: string[] = [];
+
+    const sandboxOps: SandboxOps = {
+      createSandbox: async () => ({ sandboxId: "sb-err" }),
+      destroySandbox: async (id: string) => {
+        sandboxLog.push(`destroy:${id}`);
+      },
+      pauseSandbox: async (id: string) => {
+        sandboxLog.push(`pause:${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: async () => {
+        throw new Error("crash");
+      },
+      threadOps: ops,
+      buildContextMessage: () => "go",
+      sandboxOps,
+      sandboxShutdown: "pause",
+    });
+
+    const stateManager = createAgentStateManager({
+      initialState: { systemPrompt: "test" },
+    });
+
+    await expect(session.runSession({ stateManager })).rejects.toThrow(
+      "crash"
+    );
+
+    expect(sandboxLog).toContain("pause:sb-err");
+    expect(sandboxLog).not.toContain("destroy:sb-err");
+  });
 });