zeitlich 0.2.22 → 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,16 +16,16 @@ describe("defineWorkflow", () => {
       return { ok: true };
     });
 
-    await workflow({}, { previousThreadId: "prev-42" });
+    await workflow({}, { thread: { mode: "fork", threadId: "prev-42" } });
 
     expect(capturedSession).toEqual({
       agentName: "test-workflow",
-      threadId: "prev-42",
-      continueThread: true,
+      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) => {
@@ -33,15 +33,16 @@ describe("defineWorkflow", () => {
       return { ok: true };
     });
 
-    await workflow({}, { sandboxId: "sb-123" });
+    await workflow({}, { sandbox: { mode: "inherit", sandboxId: "sb-123" } });
 
     expect(capturedSession).toEqual({
       agentName: "test-workflow",
-      sandboxId: "sb-123",
+      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) => {
@@ -49,17 +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({
       agentName: "test-workflow",
-      threadId: "prev-1",
-      continueThread: true,
-      sandboxId: "sb-1",
+      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) => {
@@ -69,7 +73,73 @@ describe("defineWorkflow", () => {
 
     await workflow({});
 
-    expect(capturedSession).toEqual({ agentName: "test-workflow" });
+    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 () => {
@@ -79,8 +149,6 @@ describe("defineWorkflow", () => {
       {
         prompt: string;
         metadata: { key: string };
-        previousThreadId?: string;
-        sandboxId?: string;
       },
       { ok: boolean }
     >(cfg, async (input, _sessionInput) => {
@@ -113,17 +181,17 @@ describe("defineWorkflow", () => {
     );
 
     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({
       agentName: "test-workflow",
-      threadId: "prev",
-      continueThread: true,
-      sandboxId: "sb",
+      sandboxShutdown: "destroy",
+      thread: { mode: "fork", threadId: "prev" },
+      sandbox: { mode: "continue", sandboxId: "sb" },
     });
   });
 

package/src/lib/workflow.ts

@@ -1,3 +1,9 @@
+import type {
+  ThreadInit,
+  SandboxInit,
+  SandboxShutdown,
+} from "./lifecycle";
+
 /**
  * Session config fields derived from a main workflow input, ready to spread
  * into `createSession`.
@@ -5,25 +11,33 @@
 export interface WorkflowSessionInput {
   /** Agent name — spread directly into `createSession` */
   agentName: string;
-  /** 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;
+  /** 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;
 }
 
 /**
@@ -33,21 +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>
 ): (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 = {
       agentName: config.name,
-      ...(workflowInput.previousThreadId && {
-        threadId: workflowInput.previousThreadId,
-        continueThread: true,
-      }),
-      ...(workflowInput.sandboxId && { sandboxId: workflowInput.sandboxId }),
+      sandboxShutdown: config.sandboxShutdown ?? "destroy",
+      ...(workflowInput.thread && { thread: workflowInput.thread }),
+      ...(workflowInput.sandbox && { sandbox: workflowInput.sandbox }),
     };
     return fn(input, sessionInput);
   };

package/src/workflow.ts

@@ -15,10 +15,13 @@
 
 // Session
 export { createSession } from "./lib/session";
-export type { ZeitlichSession, ThreadOps, PrefixedThreadOps, ScopedPrefix, SessionConfig } 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";
 
@@ -124,8 +127,10 @@ export type {
 export type {
   SubagentConfig,
   SubagentDefinition,
+  SubagentFnResult,
   SubagentHooks,
   SubagentHandlerResponse,
+  SubagentSandboxConfig,
   SubagentWorkflow,
   SubagentWorkflowInput,
   SubagentSessionInput,