zeitlich 0.2.21 → 0.2.23

package/src/lib/workflow.test.ts

@@ -8,7 +8,7 @@ import {
 const cfg = { name: "test-workflow" };
 
 describe("defineWorkflow", () => {
-  it("maps previousThreadId to threadId + continueThread", async () => {
+  it("maps thread fork into sessionInput", async () => {
     let capturedSession: WorkflowSessionInput | undefined;
 
     const workflow = defineWorkflow(cfg, async (_input, sessionInput) => {
@@ -16,15 +16,16 @@ describe("defineWorkflow", () => {
       return { ok: true };
     });
 
-    await workflow({}, { previousThreadId: "prev-42" });
+    await workflow({}, { thread: { mode: "fork", threadId: "prev-42" } });
 
     expect(capturedSession).toEqual({
-      threadId: "prev-42",
-      continueThread: true,
+      agentName: "test-workflow",
+      sandboxShutdown: "destroy",
+      thread: { mode: "fork", threadId: "prev-42" },
     });
   });
 
-  it("maps sandboxId", async () => {
+  it("maps sandbox inherit", async () => {
     let capturedSession: WorkflowSessionInput | undefined;
 
     const workflow = defineWorkflow(cfg, async (_input, sessionInput) => {
@@ -32,12 +33,16 @@ describe("defineWorkflow", () => {
       return { ok: true };
     });
 
-    await workflow({}, { sandboxId: "sb-123" });
+    await workflow({}, { sandbox: { mode: "inherit", sandboxId: "sb-123" } });
 
-    expect(capturedSession).toEqual({ sandboxId: "sb-123" });
+    expect(capturedSession).toEqual({
+      agentName: "test-workflow",
+      sandboxShutdown: "destroy",
+      sandbox: { mode: "inherit", sandboxId: "sb-123" },
+    });
   });
 
-  it("maps both previousThreadId and sandboxId together", async () => {
+  it("maps thread fork and sandbox together", async () => {
     let capturedSession: WorkflowSessionInput | undefined;
 
     const workflow = defineWorkflow(cfg, async (_input, sessionInput) => {
@@ -45,16 +50,20 @@ describe("defineWorkflow", () => {
       return { ok: true };
     });
 
-    await workflow({}, { previousThreadId: "prev-1", sandboxId: "sb-1" });
+    await workflow({}, {
+      thread: { mode: "fork", threadId: "prev-1" },
+      sandbox: { mode: "continue", sandboxId: "sb-1" },
+    });
 
     expect(capturedSession).toEqual({
-      threadId: "prev-1",
-      continueThread: true,
-      sandboxId: "sb-1",
+      agentName: "test-workflow",
+      sandboxShutdown: "destroy",
+      thread: { mode: "fork", threadId: "prev-1" },
+      sandbox: { mode: "continue", sandboxId: "sb-1" },
     });
   });
 
-  it("returns empty sessionInput when no previousThreadId or sandboxId", async () => {
+  it("defaults sandboxShutdown to destroy when no workflowInput", async () => {
     let capturedSession: WorkflowSessionInput | undefined;
 
     const workflow = defineWorkflow(cfg, async (_input, sessionInput) => {
@@ -64,18 +73,85 @@ describe("defineWorkflow", () => {
 
     await workflow({});
 
-    expect(capturedSession).toEqual({});
+    expect(capturedSession).toEqual({
+      agentName: "test-workflow",
+      sandboxShutdown: "destroy",
+    });
+  });
+
+  it("maps sandbox fork from workflowInput", async () => {
+    let capturedSession: WorkflowSessionInput | undefined;
+
+    const workflow = defineWorkflow(cfg, async (_input, sessionInput) => {
+      capturedSession = sessionInput;
+      return { ok: true };
+    });
+
+    await workflow({}, { sandbox: { mode: "fork", sandboxId: "prev-sb-1" } });
+
+    expect(capturedSession).toEqual({
+      agentName: "test-workflow",
+      sandboxShutdown: "destroy",
+      sandbox: { mode: "fork", sandboxId: "prev-sb-1" },
+    });
+  });
+
+  it("uses sandboxShutdown from config", async () => {
+    let capturedSession: WorkflowSessionInput | undefined;
+
+    const workflow = defineWorkflow(
+      { name: "test-workflow", sandboxShutdown: "pause" },
+      async (_input, sessionInput) => {
+        capturedSession = sessionInput;
+        return { ok: true };
+      }
+    );
+
+    await workflow({});
+
+    expect(capturedSession).toEqual({
+      agentName: "test-workflow",
+      sandboxShutdown: "pause",
+    });
+  });
+
+  it("maps all lifecycle fields together", async () => {
+    let capturedSession: WorkflowSessionInput | undefined;
+
+    const workflow = defineWorkflow(
+      { name: "test-workflow", sandboxShutdown: "pause" },
+      async (_input, sessionInput) => {
+        capturedSession = sessionInput;
+        return { ok: true };
+      }
+    );
+
+    await workflow(
+      {},
+      {
+        thread: { mode: "fork", threadId: "prev-t" },
+        sandbox: { mode: "fork", sandboxId: "prev-sb-1" },
+      }
+    );
+
+    expect(capturedSession).toEqual({
+      agentName: "test-workflow",
+      sandboxShutdown: "pause",
+      thread: { mode: "fork", threadId: "prev-t" },
+      sandbox: { mode: "fork", sandboxId: "prev-sb-1" },
+    });
   });
 
   it("passes full input as first argument", async () => {
     let capturedInput: unknown;
 
-    const workflow = defineWorkflow<{
-      prompt: string;
-      metadata: { key: string };
-      previousThreadId?: string;
-      sandboxId?: string;
-    }, { ok: boolean }>(cfg, async (input, _sessionInput) => {
+    const workflow = defineWorkflow<
+      {
+        prompt: string;
+        metadata: { key: string };
+      },
+      { ok: boolean }
+    >(cfg, async (input, _sessionInput) => {
       capturedInput = input;
       return { ok: true };
     });
@@ -101,20 +177,21 @@ describe("defineWorkflow", () => {
         capturedInput = input;
         capturedSession = sessionInput;
         return { ok: true };
-      },
+      }
     );
 
     const workflowInput: WorkflowInput = {
-      previousThreadId: "prev",
-      sandboxId: "sb",
+      thread: { mode: "fork", threadId: "prev" },
+      sandbox: { mode: "continue", sandboxId: "sb" },
     };
     await workflow({ prompt: "go" }, workflowInput);
 
     expect(capturedInput).toEqual({ prompt: "go" });
     expect(capturedSession).toEqual({
-      threadId: "prev",
-      continueThread: true,
-      sandboxId: "sb",
+      agentName: "test-workflow",
+      sandboxShutdown: "destroy",
+      thread: { mode: "fork", threadId: "prev" },
+      sandbox: { mode: "continue", sandboxId: "sb" },
     });
   });
 
@@ -135,7 +212,7 @@ describe("defineWorkflow", () => {
   it("sets the function name from config", () => {
     const workflow = defineWorkflow(
       { name: "my-main-workflow" },
-      async () => ({}),
+      async () => ({})
     );
 
     expect(workflow.name).toBe("my-main-workflow");

package/src/lib/workflow.ts

@@ -1,27 +1,43 @@
+import type {
+  ThreadInit,
+  SandboxInit,
+  SandboxShutdown,
+} from "./lifecycle";
+
 /**
  * Session config fields derived from a main workflow input, ready to spread
  * into `createSession`.
  */
 export interface WorkflowSessionInput {
-  /** Thread ID to continue (set from `input.previousThreadId`) */
-  threadId?: string;
-  /** Whether to continue an existing thread (true when `previousThreadId` is present) */
-  continueThread?: boolean;
-  /** Optional sandbox ID forwarded to the session */
-  sandboxId?: string;
+  /** Agent name — spread directly into `createSession` */
+  agentName: string;
+  /** Thread initialization strategy */
+  thread?: ThreadInit;
+  /** Sandbox initialization strategy */
+  sandbox?: SandboxInit;
+  /** Sandbox shutdown policy (default: "destroy") */
+  sandboxShutdown?: SandboxShutdown;
 }
 
 /** Raw workflow input fields that map into `WorkflowSessionInput`. */
 export interface WorkflowInput {
-  /** When set, continue this thread instead of starting fresh */
-  previousThreadId?: string;
-  /** Optional sandbox ID to reuse */
-  sandboxId?: string;
+  /** Thread initialization strategy (default: `{ mode: "new" }`) */
+  thread?: ThreadInit;
+  /** Sandbox initialization strategy */
+  sandbox?: SandboxInit;
 }
 
 export interface WorkflowConfig {
   /** Workflow name — used as the Temporal workflow function name */
   name: string;
+  /**
+   * Sandbox shutdown policy applied when the main agent session exits.
+   *
+   * - `"destroy"` (default) — destroy the sandbox on exit.
+   * - `"pause"` — pause the sandbox so it can be resumed later.
+   * - `"keep"` — leave the sandbox running (no-op on exit).
+   */
+  sandboxShutdown?: SandboxShutdown;
 }
 
 /**
@@ -31,20 +47,22 @@ export interface WorkflowConfig {
  * The wrapper:
  * - Accepts a `config` with at least a `name` (used for Temporal workflow naming)
  * - Accepts a handler `fn` receiving `(input, sessionInput)`
- * - Derives `threadId` + `continueThread` from `workflowInput.previousThreadId`
- * - Derives `sandboxId` from `workflowInput.sandboxId`
+ * - Derives thread / sandbox init from `workflowInput`
+ * - Applies the configured `sandboxShutdown` policy
  */
 export function defineWorkflow<TInput, TResult>(
   config: WorkflowConfig,
-  fn: (input: TInput, sessionInput: WorkflowSessionInput) => Promise<TResult>,
+  fn: (input: TInput, sessionInput: WorkflowSessionInput) => Promise<TResult>
 ): (input: TInput, workflowInput?: WorkflowInput) => Promise<TResult> {
-  const workflow = async (input: TInput, workflowInput: WorkflowInput = {}) => {
+  const workflow = async (
+    input: TInput,
+    workflowInput: WorkflowInput = {}
+  ): Promise<TResult> => {
     const sessionInput: WorkflowSessionInput = {
-      ...(workflowInput.previousThreadId && {
-        threadId: workflowInput.previousThreadId,
-        continueThread: true,
-      }),
-      ...(workflowInput.sandboxId && { sandboxId: workflowInput.sandboxId }),
+      agentName: config.name,
+      sandboxShutdown: config.sandboxShutdown ?? "destroy",
+      ...(workflowInput.thread && { thread: workflowInput.thread }),
+      ...(workflowInput.sandbox && { sandbox: workflowInput.sandbox }),
     };
     return fn(input, sessionInput);
   };

package/src/tools/bash/bash.test.ts

@@ -4,11 +4,17 @@ import { withSandbox } from "../../lib/tool-router/with-sandbox";
 import { SandboxManager } from "../../lib/sandbox/manager";
 import { InMemorySandboxProvider } from "../../adapters/sandbox/inmemory/index";
 import type { RouterContext } from "../../lib/tool-router/types";
+import type { Sandbox, SandboxCreateOptions } from "../../lib/sandbox";
 
 describe("bash handler with sandbox", () => {
-  let manager: SandboxManager;
+  let manager: SandboxManager<SandboxCreateOptions, Sandbox, "inMemory">;
   let sandboxId: string;
-  let handler: ReturnType<typeof withSandbox<Parameters<typeof bashHandler>[0], Awaited<ReturnType<typeof bashHandler>>["data"]>>;
+  let handler: ReturnType<
+    typeof withSandbox<
+      Parameters<typeof bashHandler>[0],
+      Awaited<ReturnType<typeof bashHandler>>["data"]
+    >
+  >;
 
   beforeEach(async () => {
     manager = new SandboxManager(new InMemorySandboxProvider());
@@ -83,11 +89,14 @@ describe("bash handler with sandbox", () => {
   });
 
   it("returns error when no sandboxId in context", async () => {
-    const { toolResponse, data } = await handler({ command: "echo hi" }, {
-      threadId: "test-thread",
-      toolCallId: "test-call",
-      toolName: "Bash",
-    });
+    const { toolResponse, data } = await handler(
+      { command: "echo hi" },
+      {
+        threadId: "test-thread",
+        toolCallId: "test-call",
+        toolName: "Bash",
+      }
+    );
     expect(toolResponse).toContain("No sandbox configured");
     expect(data).toBeNull();
   });

package/src/workflow.ts

@@ -7,27 +7,21 @@
  * @example
  * ```typescript
  * // In your workflow file
- * import {
- *   createSession,
- *   createAgentStateManager,
- *   askUserQuestionTool,
- *   bashTool,
- *   defineTool,
- *   type SubagentWorkflow,
- * } from 'zeitlich/workflow';
+ * import { createSession, defineWorkflow, defineTool, bashTool } from 'zeitlich/workflow';
+ * import { proxyLangChainThreadOps } from 'zeitlich/adapters/thread/langchain/workflow';
+ * import { proxyVirtualSandboxOps } from 'zeitlich/adapters/sandbox/virtual/workflow';
  * ```
  */
 
 // Session
-export {
-  createSession,
-  proxyDefaultThreadOps,
-  proxySandboxOps,
-} from "./lib/session";
-export type { ZeitlichSession, ThreadOps, SessionConfig } from "./lib/session";
+export { createSession } from "./lib/session";
+export type { ZeitlichSession, SessionResult, ThreadOps, PrefixedThreadOps, ScopedPrefix, SessionConfig } from "./lib/session";
 export { defineWorkflow } from "./lib/workflow";
 export type { WorkflowConfig, WorkflowInput, WorkflowSessionInput } from "./lib/workflow";
 
+// Lifecycle types
+export type { ThreadInit, SandboxInit, SandboxShutdown, SubagentSandboxShutdown } from "./lib/lifecycle";
+
 // Thread utilities
 export { getShortId } from "./lib/thread/id";
 
@@ -133,8 +127,10 @@ export type {
 export type {
   SubagentConfig,
   SubagentDefinition,
+  SubagentFnResult,
   SubagentHooks,
   SubagentHandlerResponse,
+  SubagentSandboxConfig,
   SubagentWorkflow,
   SubagentWorkflowInput,
   SubagentSessionInput,
@@ -147,6 +143,7 @@ export type {
   SandboxCreateResult,
   SandboxFileSystem,
   SandboxOps,
+  PrefixedSandboxOps,
   SandboxProvider,
   SandboxSnapshot,
   ExecOptions,

package/tsup.config.ts

@@ -5,11 +5,17 @@ export default defineConfig({
     index: "src/index.ts",
     workflow: "src/workflow.ts",
     "adapters/thread/langchain/index": "src/adapters/thread/langchain/index.ts",
+    "adapters/thread/langchain/workflow": "src/adapters/thread/langchain/proxy.ts",
     "adapters/thread/google-genai/index":
       "src/adapters/thread/google-genai/index.ts",
+    "adapters/thread/google-genai/workflow":
+      "src/adapters/thread/google-genai/proxy.ts",
     "adapters/sandbox/inmemory/index": "src/adapters/sandbox/inmemory/index.ts",
+    "adapters/sandbox/inmemory/workflow": "src/adapters/sandbox/inmemory/proxy.ts",
     "adapters/sandbox/daytona/index": "src/adapters/sandbox/daytona/index.ts",
+    "adapters/sandbox/daytona/workflow": "src/adapters/sandbox/daytona/proxy.ts",
     "adapters/sandbox/virtual/index": "src/adapters/sandbox/virtual/index.ts",
+    "adapters/sandbox/virtual/workflow": "src/adapters/sandbox/virtual/proxy.ts",
   },
   format: ["esm", "cjs"],
   dts: true,