zeitlich 0.2.38 → 0.2.39

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

@@ -1810,6 +1810,173 @@ describe("createSubagentHandler", () => {
     expect(deletedTags.sort()).toEqual(["base", "exit-2"]);
   });
 
+  it("publishes persistentBaseSnapshot from childSandboxReadySignal before child completes", async () => {
+    const { setHandler, executeChild } = await import("@temporalio/workflow");
+    const setHandlerMock = setHandler as ReturnType<typeof vi.fn>;
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
+
+    const signalBase = {
+      sandboxId: "sb-signal",
+      providerId: "test",
+      data: { tag: "signal-base" },
+      createdAt: new Date().toISOString(),
+    };
+
+    const config: SubagentConfig = {
+      agentName: "snap-agent",
+      description: "Snapshot-driven",
+      workflow: mockWorkflow(),
+      thread: "continue",
+      sandbox: {
+        source: "own",
+        init: "once",
+        continuation: "snapshot",
+        proxy: noopSandboxProxy,
+      },
+    };
+
+    const { handler } = createSubagentHandler([config]);
+
+    // Fire the signal from inside executeChild so persistentBaseSnapshot is
+    // set before the child's own result is returned. The child result itself
+    // intentionally omits baseSnapshot — only the signal path can populate
+    // the map for this call.
+    execMock.mockImplementationOnce(
+      async (_wf: unknown, opts: { workflowId: string; args: unknown[] }) => {
+        const reg = setHandlerMock.mock.calls
+          .filter(
+            ([sig]) => (sig as { name?: string })?.name === "childSandboxReady"
+          )
+          .at(-1);
+        const signalHandler = reg?.[1] as
+          | ((p: {
+              childWorkflowId: string;
+              sandboxId: string;
+              baseSnapshot?: unknown;
+            }) => void)
+          | undefined;
+        signalHandler?.({
+          childWorkflowId: opts.workflowId,
+          sandboxId: "sb-signal",
+          baseSnapshot: signalBase,
+        });
+        return {
+          toolResponse: "first",
+          data: null,
+          threadId: "child-sig-1",
+        };
+      }
+    );
+
+    await handler(
+      { subagent: "snap-agent", description: "test", prompt: "first" },
+      { threadId: "t", toolCallId: "tc-1", toolName: "Subagent" }
+    );
+
+    // Second call on a new thread must boot from the signal-published base.
+    nextStartChildResult = () => ({
+      toolResponse: "second",
+      data: null,
+      threadId: "child-sig-2",
+    });
+
+    await handler(
+      { subagent: "snap-agent", description: "test", prompt: "second" },
+      { threadId: "t", toolCallId: "tc-2", toolName: "Subagent" }
+    );
+
+    const secondCall = execMock.mock.calls.at(-1);
+    if (!secondCall) throw new Error("expected executeChild call");
+    const secondInput = secondCall[1].args[1] as SubagentWorkflowInput;
+    expect(secondInput.sandbox).toEqual({
+      mode: "from-snapshot",
+      snapshot: expect.objectContaining({ data: { tag: "signal-base" } }),
+    });
+  });
+
+  it("ignores signal baseSnapshot for non-snapshot-base creators", async () => {
+    const { setHandler, executeChild } = await import("@temporalio/workflow");
+    const setHandlerMock = setHandler as ReturnType<typeof vi.fn>;
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
+
+    const config: SubagentConfig = {
+      agentName: "lazy-fork-agent",
+      description: "Lazy fork (not snapshot)",
+      workflow: mockWorkflow(),
+      sandbox: {
+        source: "own",
+        init: "once",
+        continuation: "fork",
+        proxy: noopSandboxProxy,
+      },
+    };
+
+    const { handler } = createSubagentHandler([config]);
+
+    execMock.mockImplementationOnce(
+      async (_wf: unknown, opts: { workflowId: string; args: unknown[] }) => {
+        const reg = setHandlerMock.mock.calls
+          .filter(
+            ([sig]) => (sig as { name?: string })?.name === "childSandboxReady"
+          )
+          .at(-1);
+        const signalHandler = reg?.[1] as
+          | ((p: {
+              childWorkflowId: string;
+              sandboxId: string;
+              baseSnapshot?: unknown;
+            }) => void)
+          | undefined;
+        // Stray baseSnapshot on a non-snapshot path must not land in
+        // persistentBaseSnapshot, or it would corrupt a different agent's
+        // snapshot flow.
+        signalHandler?.({
+          childWorkflowId: opts.workflowId,
+          sandboxId: "sb-lazy",
+          baseSnapshot: {
+            sandboxId: "sb-lazy",
+            providerId: "test",
+            data: { tag: "should-be-ignored" },
+            createdAt: new Date().toISOString(),
+          },
+        });
+        return {
+          toolResponse: "first",
+          data: null,
+          threadId: "child-lazy-1",
+          sandboxId: "sb-lazy",
+        };
+      }
+    );
+
+    await handler(
+      { subagent: "lazy-fork-agent", description: "test", prompt: "first" },
+      { threadId: "t", toolCallId: "tc-1", toolName: "Subagent" }
+    );
+
+    // Second call should fork from the lazy-published sandbox, not restore
+    // from any snapshot.
+    nextStartChildResult = () => ({
+      toolResponse: "second",
+      data: null,
+      threadId: "child-lazy-2",
+      sandboxId: "sb-lazy",
+    });
+
+    await handler(
+      { subagent: "lazy-fork-agent", description: "test", prompt: "second" },
+      { threadId: "t", toolCallId: "tc-2", toolName: "Subagent" }
+    );
+
+    const secondCall = execMock.mock.calls.at(-1);
+    if (!secondCall) throw new Error("expected executeChild call");
+    const secondInput = secondCall[1].args[1] as SubagentWorkflowInput;
+    expect(secondInput.sandbox).toEqual({
+      mode: "fork",
+      sandboxId: "sb-lazy",
+    });
+  });
+
   it("does not call deleteSandboxSnapshot for children that produced no snapshots", async () => {
     const opsMock = makeMockSandboxOps();
     const config: SubagentConfig = {
@@ -1843,6 +2010,195 @@ describe("createSubagentHandler", () => {
 
     expect(opsMock.deleteSandboxSnapshot).not.toHaveBeenCalled();
   });
+
+  // -------------------------------------------------------------------------
+  // Child workflow failure propagation
+  // -------------------------------------------------------------------------
+
+  it("propagates executeChild failure to the caller instead of hanging", async () => {
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
+    execMock.mockImplementationOnce(async () => {
+      throw new Error("Child Workflow execution failed: timeout");
+    });
+
+    const { handler } = createSubagentHandler([
+      {
+        agentName: "researcher",
+        description: "Researches topics",
+        workflow: mockWorkflow("researcherWorkflow"),
+      },
+    ]);
+
+    await expect(
+      handler(
+        { subagent: "researcher", description: "test", prompt: "hi" },
+        { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
+      )
+    ).rejects.toThrow("Child Workflow execution failed: timeout");
+  });
+
+  it("applies a default workflowRunTimeout when workflowOptions is omitted", async () => {
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
+
+    const { DEFAULT_SUBAGENT_WORKFLOW_RUN_TIMEOUT } = await import("./handler");
+
+    const { handler } = createSubagentHandler([
+      {
+        agentName: "researcher",
+        description: "Researches topics",
+        workflow: mockWorkflow("researcherWorkflow"),
+      },
+    ]);
+
+    await handler(
+      { subagent: "researcher", description: "test", prompt: "hi" },
+      { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
+    );
+
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
+    expect(lastCall[1].workflowRunTimeout).toBe(
+      DEFAULT_SUBAGENT_WORKFLOW_RUN_TIMEOUT
+    );
+  });
+
+  it("lets workflowOptions.workflowRunTimeout override the default", async () => {
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
+
+    const { handler } = createSubagentHandler([
+      {
+        agentName: "researcher",
+        description: "Researches topics",
+        workflow: mockWorkflow("researcherWorkflow"),
+        workflowOptions: { workflowRunTimeout: "30s" },
+      },
+    ]);
+
+    await handler(
+      { subagent: "researcher", description: "test", prompt: "hi" },
+      { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
+    );
+
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
+    expect(lastCall[1].workflowRunTimeout).toBe("30s");
+  });
+
+  it("forwards workflowOptions to executeChild", async () => {
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
+
+    const { handler } = createSubagentHandler([
+      {
+        agentName: "researcher",
+        description: "Researches topics",
+        workflow: mockWorkflow("researcherWorkflow"),
+        workflowOptions: {
+          workflowRunTimeout: "5m",
+          workflowTaskTimeout: "30s",
+          retry: { maximumAttempts: 1 },
+        },
+      },
+    ]);
+
+    await handler(
+      { subagent: "researcher", description: "test", prompt: "hi" },
+      { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
+    );
+
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
+    expect(lastCall[1]).toMatchObject({
+      workflowRunTimeout: "5m",
+      workflowTaskTimeout: "30s",
+      retry: { maximumAttempts: 1 },
+    });
+  });
+
+  it("does not let workflowOptions override workflowId, taskQueue, or args", async () => {
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
+
+    const { handler } = createSubagentHandler([
+      {
+        agentName: "researcher",
+        description: "Researches topics",
+        workflow: mockWorkflow("researcherWorkflow"),
+        taskQueue: "my-queue",
+        workflowOptions: {
+          // Intentionally violates the public Omit<> type to prove the
+          // handler still wins at runtime. Cast removes the type error.
+          ...({
+            workflowId: "forbidden-id",
+            taskQueue: "forbidden-queue",
+            args: ["forbidden"],
+          } as Record<string, unknown>),
+        },
+      },
+    ]);
+
+    await handler(
+      { subagent: "researcher", description: "test", prompt: "hello" },
+      { threadId: "t", toolCallId: "tc", toolName: "Subagent" }
+    );
+
+    const lastCall = execMock.mock.calls[execMock.mock.calls.length - 1];
+    if (!lastCall) throw new Error("expected executeChild call");
+    expect(lastCall[1].workflowId).not.toBe("forbidden-id");
+    expect(lastCall[1].workflowId).toMatch(/^researcher-/);
+    expect(lastCall[1].taskQueue).toBe("my-queue");
+    expect(lastCall[1].args[0]).toBe("hello");
+  });
+
+  it("clears lazy-creator bookkeeping on failure so the next call can re-try", async () => {
+    const opsMock = makeMockSandboxOps();
+    const { executeChild } = await import("@temporalio/workflow");
+    const execMock = executeChild as ReturnType<typeof vi.fn>;
+
+    const lazySubagent: SubagentConfig = {
+      agentName: "lazy",
+      description: "Lazy sandbox init",
+      workflow: mockWorkflow(),
+      sandbox: {
+        source: "own",
+        init: "once",
+        continuation: "fork",
+        proxy: () => opsMock,
+      },
+    };
+
+    const { handler } = createSubagentHandler([lazySubagent]);
+
+    execMock.mockImplementationOnce(async () => {
+      throw new Error("init failed");
+    });
+
+    await expect(
+      handler(
+        { subagent: "lazy", description: "test", prompt: "first" },
+        { threadId: "t", toolCallId: "tc-1", toolName: "Subagent" }
+      )
+    ).rejects.toThrow("init failed");
+
+    // A second call must be able to take the creator role again (no stranded
+    // "creating" flag) and succeed.
+    nextStartChildResult = () => ({
+      toolResponse: "ok",
+      data: null,
+      threadId: "child-t-2",
+      sandboxId: "child-sb-2",
+    });
+
+    const result = await handler(
+      { subagent: "lazy", description: "test", prompt: "second" },
+      { threadId: "t", toolCallId: "tc-2", toolName: "Subagent" }
+    );
+
+    expect(result.toolResponse).toBe("ok");
+  });
 });
 
 // ---------------------------------------------------------------------------
@@ -2050,6 +2406,7 @@ describe("defineSubagentWorkflow", () => {
       sandboxShutdown: "destroy",
       thread: { mode: "fork", threadId: "prev-42" },
       onSandboxReady: expect.any(Function),
+      onSessionExit: expect.any(Function),
     });
   });
 
@@ -2069,6 +2426,7 @@ describe("defineSubagentWorkflow", () => {
       sandboxShutdown: "destroy",
       sandbox: { mode: "inherit", sandboxId: "sb-123" },
       onSandboxReady: expect.any(Function),
+      onSessionExit: expect.any(Function),
     });
   });
 
@@ -2088,6 +2446,7 @@ describe("defineSubagentWorkflow", () => {
       sandboxShutdown: "destroy",
       sandbox: { mode: "fork", sandboxId: "prev-sb-1" },
       onSandboxReady: expect.any(Function),
+      onSessionExit: expect.any(Function),
     });
   });
 
@@ -2111,6 +2470,7 @@ describe("defineSubagentWorkflow", () => {
       thread: { mode: "fork", threadId: "prev-t" },
       sandbox: { mode: "fork", sandboxId: "prev-sb" },
       onSandboxReady: expect.any(Function),
+      onSessionExit: expect.any(Function),
     });
   });
 
@@ -2181,6 +2541,7 @@ describe("defineSubagentWorkflow", () => {
       agentName: "test",
       sandboxShutdown: "destroy",
       onSandboxReady: expect.any(Function),
+      onSessionExit: expect.any(Function),
     });
   });
 
@@ -2203,4 +2564,171 @@ describe("defineSubagentWorkflow", () => {
 
     expect(capturedSession?.sandboxShutdown).toBe("keep-until-parent-close");
   });
+
+  // -------------------------------------------------------------------------
+  // Auto-forwarding of session outputs + signal payload
+  // -------------------------------------------------------------------------
+
+  it("auto-forwards baseSnapshot captured via onSandboxReady", async () => {
+    const baseSnapshot = {
+      sandboxId: "sb-1",
+      providerId: "test",
+      data: { tag: "base" },
+      createdAt: new Date().toISOString(),
+    };
+    const workflow = defineSubagentWorkflow(
+      { name: "test", description: "test agent" },
+      async (_prompt, sessionInput) => {
+        sessionInput.onSandboxReady?.({ sandboxId: "sb-1", baseSnapshot });
+        return { toolResponse: "ok", data: null, threadId: "t" };
+      }
+    );
+
+    const result = await workflow("go", {});
+    expect(result.baseSnapshot).toEqual(baseSnapshot);
+  });
+
+  it("auto-forwards sandboxId and snapshot captured via onSessionExit", async () => {
+    const snapshot = {
+      sandboxId: "sb-1",
+      providerId: "test",
+      data: { tag: "exit" },
+      createdAt: new Date().toISOString(),
+    };
+    const workflow = defineSubagentWorkflow(
+      { name: "test", description: "test agent" },
+      async (_prompt, sessionInput) => {
+        sessionInput.onSessionExit?.({
+          sandboxId: "sb-1",
+          snapshot,
+          threadId: "t",
+        });
+        return { toolResponse: "ok", data: null, threadId: "t" };
+      }
+    );
+
+    const result = await workflow("go", {});
+    expect(result.sandboxId).toBe("sb-1");
+    expect(result.snapshot).toEqual(snapshot);
+  });
+
+  it("fn-explicit sandbox outputs win over captured session outputs", async () => {
+    const workflow = defineSubagentWorkflow(
+      { name: "test", description: "test agent" },
+      async (_prompt, sessionInput) => {
+        sessionInput.onSessionExit?.({
+          sandboxId: "session-sb",
+          snapshot: {
+            sandboxId: "session-sb",
+            providerId: "test",
+            data: { tag: "session" },
+            createdAt: new Date().toISOString(),
+          },
+          threadId: "t",
+        });
+        return {
+          toolResponse: "ok",
+          data: null,
+          threadId: "t",
+          sandboxId: "explicit-sb",
+          snapshot: {
+            sandboxId: "explicit-sb",
+            providerId: "test",
+            data: { tag: "explicit" },
+            createdAt: new Date().toISOString(),
+          },
+        };
+      }
+    );
+
+    const result = await workflow("go", {});
+    expect(result.sandboxId).toBe("explicit-sb");
+    expect(
+      (result.snapshot as { data: { tag: string } } | undefined)?.data
+    ).toEqual({ tag: "explicit" });
+  });
+
+  it("signals parent with baseSnapshot via childSandboxReadySignal", async () => {
+    const { getExternalWorkflowHandle } = await import("@temporalio/workflow");
+    const ghMock = getExternalWorkflowHandle as ReturnType<typeof vi.fn>;
+    const baseSnapshot = {
+      sandboxId: "sb-1",
+      providerId: "test",
+      data: { tag: "base" },
+      createdAt: new Date().toISOString(),
+    };
+
+    const workflow = defineSubagentWorkflow(
+      { name: "test", description: "test agent" },
+      async (_prompt, sessionInput) => {
+        sessionInput.onSandboxReady?.({ sandboxId: "sb-1", baseSnapshot });
+        return { toolResponse: "ok", data: null, threadId: "t" };
+      }
+    );
+
+    await workflow("go", {});
+
+    const handle = ghMock.mock.results.at(-1)?.value as {
+      signal: ReturnType<typeof vi.fn>;
+    };
+    expect(handle.signal).toHaveBeenCalledWith(
+      expect.objectContaining({ name: "childSandboxReady" }),
+      expect.objectContaining({
+        childWorkflowId: "child-wf-1",
+        sandboxId: "sb-1",
+        baseSnapshot,
+      })
+    );
+  });
+
+  it("omits baseSnapshot from signal when session did not capture one", async () => {
+    const { getExternalWorkflowHandle } = await import("@temporalio/workflow");
+    const ghMock = getExternalWorkflowHandle as ReturnType<typeof vi.fn>;
+
+    const workflow = defineSubagentWorkflow(
+      { name: "test", description: "test agent" },
+      async (_prompt, sessionInput) => {
+        sessionInput.onSandboxReady?.({ sandboxId: "sb-1" });
+        return { toolResponse: "ok", data: null, threadId: "t" };
+      }
+    );
+
+    await workflow("go", {});
+
+    const handle = ghMock.mock.results.at(-1)?.value as {
+      signal: ReturnType<typeof vi.fn>;
+    };
+    const payload = handle.signal.mock.calls.at(-1)?.[1] as {
+      childWorkflowId: string;
+      sandboxId: string;
+      baseSnapshot?: unknown;
+    };
+    expect(payload).toEqual({
+      childWorkflowId: "child-wf-1",
+      sandboxId: "sb-1",
+    });
+    expect(payload.baseSnapshot).toBeUndefined();
+  });
+
+  it("skips the signal when the sandbox is reused (continue mode)", async () => {
+    const { getExternalWorkflowHandle } = await import("@temporalio/workflow");
+    const ghMock = getExternalWorkflowHandle as ReturnType<typeof vi.fn>;
+
+    const workflow = defineSubagentWorkflow(
+      { name: "test", description: "test agent" },
+      async (_prompt, sessionInput) => {
+        sessionInput.onSandboxReady?.({ sandboxId: "sb-1" });
+        return { toolResponse: "ok", data: null, threadId: "t" };
+      }
+    );
+
+    await workflow("go", {
+      sandbox: { mode: "continue", sandboxId: "sb-1" },
+    });
+
+    const handle = ghMock.mock.results.at(-1)?.value as {
+      signal: ReturnType<typeof vi.fn>;
+    };
+    expect(handle.signal).not.toHaveBeenCalled();
+  });
 });

package/src/lib/subagent/types.ts

@@ -1,4 +1,5 @@
 import type { z } from "zod";
+import type { ChildWorkflowOptions } from "@temporalio/workflow";
 import type { JsonValue } from "../state/types";
 import type {
   ToolHandlerResponse,
@@ -12,22 +13,27 @@ import type {
 } from "../lifecycle";
 import type { SandboxOps, SandboxSnapshot } from "../sandbox/types";
 
+/**
+ * Subset of {@link ChildWorkflowOptions} that callers may override when a
+ * subagent is invoked. `workflowId`, `taskQueue`, and `args` are managed by
+ * the subagent handler itself and therefore cannot be set here.
+ *
+ * Configuring `workflowRunTimeout` (or `workflowExecutionTimeout`) is strongly
+ * recommended: it is the only reliable way to guarantee that a child workflow
+ * which fails during initialization or repeatedly fails workflow tasks will
+ * eventually be terminated, allowing the parent's `Subagent` tool call to fail
+ * deterministically instead of hanging forever waiting for a result.
+ */
+export type SubagentChildWorkflowOptions = Omit<
+  ChildWorkflowOptions,
+  "workflowId" | "taskQueue" | "args"
+>;
+
 /** ToolHandlerResponse with threadId required (subagents must always surface their thread) */
 export type SubagentHandlerResponse<
   TResult = null,
   TToolResponse = JsonValue,
-> = ToolHandlerResponse<TResult, TToolResponse> & {
-  threadId: string;
-  sandboxId?: string;
-  /** Snapshot captured on session exit when `sandboxShutdown === "snapshot"`. */
-  snapshot?: SandboxSnapshot;
-  /**
-   * Snapshot captured immediately after the sandbox was seeded (before the
-   * first agent turn) when `continuation === "snapshot"`. Only set on the
-   * first call that actually created the sandbox.
-   */
-  baseSnapshot?: SandboxSnapshot;
-};
+> = ToolHandlerResponse<TResult, TToolResponse>;
 
 /**
  * Raw workflow input fields passed from parent to child workflow.
@@ -124,6 +130,24 @@ export interface SubagentConfig<TResult extends z.ZodType = z.ZodType> {
   workflow: SubagentWorkflow<TResult>;
   /** Optional task queue - defaults to parent's queue if not specified */
   taskQueue?: string;
+  /**
+   * Optional child workflow options forwarded to `executeChild` when the
+   * subagent is spawned. Use this to configure timeouts, retry policies, or
+   * parent-close behavior for the child workflow.
+   *
+   * **Recommended:** configure a `workflowRunTimeout` (or
+   * `workflowExecutionTimeout`) so that a child workflow that fails to
+   * initialize — or repeatedly fails workflow tasks without ever reaching a
+   * terminal state — is eventually terminated by the Temporal server. Without
+   * such a timeout, the parent's `Subagent` tool call can hang indefinitely
+   * waiting for the child to finish. When Temporal terminates the child, the
+   * tool call fails with a structured `ChildWorkflowFailure` that the router's
+   * failure hooks can handle just like any other tool error.
+   *
+   * `workflowId`, `taskQueue`, and `args` are managed by the subagent handler
+   * and cannot be overridden here.
+   */
+  workflowOptions?: SubagentChildWorkflowOptions;
   /** Optional Zod schema to validate the child workflow's result. If omitted, result is passed through as-is. */
   resultSchema?: TResult;
   /** Optional context passed to the subagent — a static object or a function evaluated at invocation time */
@@ -214,6 +238,13 @@ export type SubagentFnResult<
 export interface ChildSandboxReadySignalPayload {
   childWorkflowId: string;
   sandboxId: string;
+  /**
+   * Present only when the session captured a seed snapshot on this run
+   * (`continuation === "snapshot"` + fresh creation). Allows the parent to
+   * publish the reusable base snapshot to concurrent waiters without
+   * blocking on the child workflow's completion.
+   */
+  baseSnapshot?: SandboxSnapshot;
 }
 
 /**
@@ -228,6 +259,24 @@ export interface SubagentSessionInput {
   sandbox?: SandboxInit;
   /** Sandbox shutdown policy (default: "destroy") */
   sandboxShutdown?: SubagentSandboxShutdown;
-  /** Called by the session as soon as the sandbox is created, before the agent loop starts. */
-  onSandboxReady?: (sandboxId: string) => void;
+  /**
+   * Called by the session as soon as the sandbox is created, before the
+   * agent loop starts. `baseSnapshot` is populated only when the session
+   * captured a seed snapshot (fresh creation + `sandboxShutdown === "snapshot"`).
+   */
+  onSandboxReady?: (args: {
+    sandboxId: string;
+    baseSnapshot?: SandboxSnapshot;
+  }) => void;
+  /**
+   * Called by the session right before `runSession` returns. Installed by
+   * `defineSubagentWorkflow` to capture sandbox outputs and auto-forward
+   * them to the subagent's final result so user code never has to thread
+   * `sandboxId` / `snapshot` manually.
+   */
+  onSessionExit?: (result: {
+    sandboxId?: string;
+    snapshot?: SandboxSnapshot;
+    threadId: string;
+  }) => void;
 }