zeitlich 0.2.21 → 0.2.23

package/src/lib/session/session.ts

@@ -1,13 +1,11 @@
 import {
-  proxyActivities,
   condition,
   defineUpdate,
   setHandler,
   ApplicationFailure,
-  type ActivityInterfaceFor,
 } from "@temporalio/workflow";
 import type { SessionExitReason, MessageContent } from "../types";
-import type { ThreadOps, SessionConfig, ZeitlichSession } from "./types";
+import type { SessionConfig, ZeitlichSession } from "./types";
 import type { SandboxOps } from "../sandbox/types";
 import { type AgentStateManager, type JsonSerializable } from "../state/types";
 import { createToolRouter } from "../tool-router/router";
@@ -21,22 +19,22 @@ import { uuid4 } from "@temporalio/workflow";
  * Creates an agent session that manages the agent loop: LLM invocation,
  * tool routing, subagent coordination, and lifecycle hooks.
  *
+ * When `sandboxOps` is provided the returned session result is guaranteed to
+ * include `sandboxId: string`. Without it, `sandboxId` is `undefined`.
+ *
  * @param config - Session and agent configuration (merged `SessionConfig` and `AgentConfig`)
  * @returns A session object with `runSession()` to start the agent loop
  *
  * @example
  * ```typescript
  * import { createSession, createAgentStateManager, defineTool, bashTool } from 'zeitlich/workflow';
- *
- * const stateManager = createAgentStateManager({
- *   initialState: { systemPrompt: "You are a helpful assistant." },
- *   agentName: "my-agent",
- * });
+ * import { proxyGoogleGenAIThreadOps } from 'zeitlich/adapters/thread/google-genai/workflow';
  *
  * const session = await createSession({
  *   agentName: "my-agent",
  *   maxTurns: 20,
- *   threadId: runId,
+ *   thread: { mode: "new" },
+ *   threadOps: proxyGoogleGenAIThreadOps(),
  *   runAgent: runAgentActivity,
  *   buildContextMessage: () => [{ type: "text", text: prompt }],
  *   subagents: [researcherSubagent],
@@ -48,8 +46,13 @@ import { uuid4 } from "@temporalio/workflow";
  * const { finalMessage, exitReason } = await session.runSession({ stateManager });
  * ```
  */
-export const createSession = async <T extends ToolMap, M = unknown>({
-  threadId: providedThreadId,
+export async function createSession<T extends ToolMap, M = unknown>(
+  config: SessionConfig<T, M> & { sandboxOps: SandboxOps }
+): Promise<ZeitlichSession<M, true>>;
+export async function createSession<T extends ToolMap, M = unknown>(
+  config: SessionConfig<T, M>
+): Promise<ZeitlichSession<M, false>>;
+export async function createSession<T extends ToolMap, M = unknown>({
   agentName,
   maxTurns = 50,
   metadata = {},
@@ -62,16 +65,33 @@ export const createSession = async <T extends ToolMap, M = unknown>({
   processToolsInParallel = true,
   hooks = {},
   appendSystemPrompt = true,
-  continueThread = false,
   waitForInputTimeout = "48h",
-  sandbox: sandboxOps,
-  sandboxId: inheritedSandboxId,
-}: SessionConfig<T, M>): Promise<ZeitlichSession<M>> => {
-  const sourceThreadId = continueThread ? providedThreadId : undefined;
-  const threadId =
-    continueThread && providedThreadId
-      ? getShortId()
-      : (providedThreadId ?? getShortId());
+  sandboxOps,
+  thread: threadInit,
+  sandbox: sandboxInit,
+  sandboxShutdown = "destroy",
+}: SessionConfig<T, M>): Promise<ZeitlichSession<M, boolean>> {
+  // ---------------------------------------------------------------------------
+  // Thread resolution
+  // ---------------------------------------------------------------------------
+  const threadMode = threadInit?.mode ?? "new";
+  let threadId: string;
+  let sourceThreadId: string | undefined;
+
+  switch (threadMode) {
+    case "new":
+      threadId = threadInit?.mode === "new" && threadInit.threadId
+        ? threadInit.threadId
+        : getShortId();
+      break;
+    case "continue":
+      threadId = (threadInit as { mode: "continue"; threadId: string }).threadId;
+      break;
+    case "fork":
+      sourceThreadId = (threadInit as { mode: "fork"; threadId: string }).threadId;
+      threadId = getShortId();
+      break;
+  }
 
   const {
     appendToolResult,
@@ -79,12 +99,16 @@ export const createSession = async <T extends ToolMap, M = unknown>({
     initializeThread,
     appendSystemMessage,
     forkThread,
-  } = threadOps ?? proxyDefaultThreadOps();
+  } = threadOps;
 
   const plugins: ToolMap[string][] = [];
+  let destroySubagentSandboxes: (() => Promise<void>) | undefined;
   if (subagents) {
-    const reg = buildSubagentRegistration(subagents);
-    if (reg) plugins.push(reg);
+    const result = buildSubagentRegistration(subagents);
+    if (result) {
+      plugins.push(result.registration);
+      destroySubagentSandboxes = result.destroySubagentSandboxes;
+    }
   }
   if (skills) {
     const reg = buildSkillRegistration(skills);
@@ -120,12 +144,7 @@ export const createSession = async <T extends ToolMap, M = unknown>({
       stateManager,
     }: {
       stateManager: AgentStateManager<TState>;
-    }): Promise<{
-      threadId: string;
-      finalMessage: M | null;
-      exitReason: SessionExitReason;
-      usage: ReturnType<AgentStateManager<TState>["getTotalUsage"]>;
-    }> => {
+    }) => {
       setHandler(
         defineUpdate<unknown, [MessageContent]>(`add${agentName}Message`),
         async (message: MessageContent) => {
@@ -146,12 +165,43 @@ export const createSession = async <T extends ToolMap, M = unknown>({
         }
       );
 
-      // --- Sandbox lifecycle: create or inherit ---
-      let sandboxId: string | undefined = inheritedSandboxId;
-      const ownsSandbox = !sandboxId && !!sandboxOps;
-      if (ownsSandbox) {
-        const result = await sandboxOps.createSandbox({ id: threadId });
+      // --- Sandbox lifecycle: create, continue, fork, or inherit ----------
+      const sandboxMode = sandboxInit?.mode;
+      let sandboxId: string | undefined;
+      let sandboxOwned = false;
+
+      if (sandboxMode === "inherit") {
+        sandboxId = (sandboxInit as { mode: "inherit"; sandboxId: string }).sandboxId;
+        if (!sandboxOps) {
+          throw ApplicationFailure.create({
+            message: "sandboxId provided but no sandboxOps — cannot manage sandbox lifecycle",
+            nonRetryable: true,
+          });
+        }
+      } else if (sandboxMode === "continue") {
+        if (!sandboxOps) {
+          throw ApplicationFailure.create({
+            message: "No sandboxOps provided — cannot continue sandbox",
+            nonRetryable: true,
+          });
+        }
+        sandboxId = (sandboxInit as { mode: "continue"; sandboxId: string }).sandboxId;
+        sandboxOwned = true;
+      } else if (sandboxMode === "fork") {
+        if (!sandboxOps) {
+          throw ApplicationFailure.create({
+            message: "No sandboxOps provided — cannot fork sandbox",
+            nonRetryable: true,
+          });
+        }
+        sandboxId = await sandboxOps.forkSandbox(
+          (sandboxInit as { mode: "fork"; sandboxId: string }).sandboxId
+        );
+        sandboxOwned = true;
+      } else if (sandboxOps) {
+        const result = await sandboxOps.createSandbox();
         sandboxId = result.sandboxId;
+        sandboxOwned = true;
         if (result.stateUpdate) {
           stateManager.mergeUpdate(result.stateUpdate as Partial<TState>);
         }
@@ -167,8 +217,11 @@ export const createSession = async <T extends ToolMap, M = unknown>({
 
       const systemPrompt = stateManager.getSystemPrompt();
 
-      if (continueThread && sourceThreadId) {
+      // --- Thread lifecycle: new, continue, or fork ----------------------
+      if (threadMode === "fork" && sourceThreadId) {
         await forkThread(sourceThreadId, threadId);
+      } else if (threadMode === "continue") {
+        // "continue" — thread already exists, just append the new message
       } else {
         if (appendSystemPrompt) {
           if (!systemPrompt || systemPrompt.trim() === "") {
@@ -215,7 +268,8 @@ export const createSession = async <T extends ToolMap, M = unknown>({
               finalMessage: message,
               exitReason,
               usage: stateManager.getTotalUsage(),
-            };
+              sandboxId,
+            } as Awaited<ReturnType<ZeitlichSession<M, boolean>["runSession"]>>;
           }
 
           const parsedToolCalls: ParsedToolCallUnion<T>[] = [];
@@ -271,8 +325,22 @@ export const createSession = async <T extends ToolMap, M = unknown>({
       } finally {
         await callSessionEnd(exitReason, stateManager.getTurns());
 
-        if (ownsSandbox && sandboxId && sandboxOps) {
-          await sandboxOps.destroySandbox(sandboxId);
+        if (sandboxOwned && sandboxId && sandboxOps) {
+          switch (sandboxShutdown) {
+            case "destroy":
+              await sandboxOps.destroySandbox(sandboxId);
+              break;
+            case "pause":
+            case "pause-until-parent-close":
+              await sandboxOps.pauseSandbox(sandboxId);
+              break;
+            case "keep":
+              break;
+          }
+        }
+
+        if (destroySubagentSandboxes) {
+          await destroySubagentSandboxes();
         }
       }
 
@@ -281,64 +349,8 @@ export const createSession = async <T extends ToolMap, M = unknown>({
         finalMessage: null,
         exitReason,
         usage: stateManager.getTotalUsage(),
-      };
+        sandboxId,
+      } as Awaited<ReturnType<ZeitlichSession<M, boolean>["runSession"]>>;
     },
   };
-};
-
-/**
- * Proxy the adapter's thread operations as Temporal activities.
- * Call this in workflow code to delegate thread operations to the
- * adapter-provided activities registered on the worker.
- *
- * @example
- * ```typescript
- * const session = await createSession({
- *   threadOps: proxyDefaultThreadOps(),
- *   // ...
- * });
- * ```
- */
-export function proxyDefaultThreadOps(
-  options?: Parameters<typeof proxyActivities>[0]
-): ActivityInterfaceFor<ThreadOps> {
-  return proxyActivities<ThreadOps>(
-    options ?? {
-      startToCloseTimeout: "10s",
-      retry: {
-        maximumAttempts: 6,
-        initialInterval: "5s",
-        maximumInterval: "15m",
-        backoffCoefficient: 4,
-      },
-    }
-  );
-}
-
-/**
- * Proxy sandbox lifecycle operations as Temporal activities.
- * Call this in workflow code when the agent needs a sandbox.
- *
- * @example
- * ```typescript
- * const session = await createSession({
- *   sandbox: proxySandboxOps(),
- *   // ...
- * });
- * ```
- */
-export function proxySandboxOps(
-  options?: Parameters<typeof proxyActivities>[0]
-): SandboxOps {
-  return proxyActivities<SandboxOps>(
-    options ?? {
-      startToCloseTimeout: "30s",
-      retry: {
-        maximumAttempts: 3,
-        initialInterval: "2s",
-        maximumInterval: "30s",
-        backoffCoefficient: 2,
-      },
-    }
-  );
 }

package/src/lib/session/types.ts

@@ -16,6 +16,7 @@ import type { SandboxOps } from "../sandbox/types";
 import type { RunAgentActivity } from "../model/types";
 import type { AgentStateManager, JsonSerializable } from "../state/types";
 import type { ActivityInterfaceFor } from "@temporalio/workflow";
+import type { ThreadInit, SandboxInit, SubagentSandboxShutdown } from "../lifecycle";
 
 /**
  * Thread operations required by a session.
@@ -42,14 +43,43 @@ export interface ThreadOps {
   forkThread(sourceThreadId: string, targetThreadId: string): Promise<void>;
 }
 
+/**
+ * Composes an adapter prefix + workflow scope for activity naming.
+ *
+ * The adapter prefix stays first (camelCase); the workflow scope is
+ * capitalised and appended. When `TScope` is empty the adapter prefix
+ * is used as-is.
+ *
+ * @example
+ * ```typescript
+ * ScopedPrefix<"codingAgent", "googleGenAI"> // "googleGenAICodingAgent"
+ * ScopedPrefix<"", "googleGenAI">            // "googleGenAI"
+ * ```
+ */
+export type ScopedPrefix<
+  TScope extends string,
+  TAdapter extends string,
+> = TScope extends "" ? TAdapter : `${TAdapter}${Capitalize<TScope>}`;
+
+/**
+ * Maps generic {@link ThreadOps} method names to adapter-prefixed names.
+ *
+ * @example
+ * ```typescript
+ * type GoogleOps = PrefixedThreadOps<"googleGenAI">;
+ * // → { googleGenAIInitializeThread, googleGenAIAppendHumanMessage, … }
+ * ```
+ */
+export type PrefixedThreadOps<TPrefix extends string> = {
+  [K in keyof ThreadOps as `${TPrefix}${Capitalize<K & string>}`]: ThreadOps[K];
+};
+
 /**
  * Configuration for a Zeitlich agent session
  */
 export interface SessionConfig<T extends ToolMap, M = unknown> {
   /** The name of the agent, should be unique within the workflows */
   agentName: string;
-  /** The thread ID to use for the session (defaults to a short generated ID) */
-  threadId?: string;
   /** Metadata for the session */
   metadata?: Record<string, unknown>;
   /** Whether to append the system prompt as message to the thread */
@@ -59,7 +89,7 @@ export interface SessionConfig<T extends ToolMap, M = unknown> {
   /** Workflow-specific runAgent activity (with tools pre-bound) */
   runAgent: RunAgentActivity<M>;
   /** Thread operations (initialize, append messages, parse tool calls) */
-  threadOps?: ActivityInterfaceFor<ThreadOps>;
+  threadOps: ActivityInterfaceFor<ThreadOps>;
   /** Tool router for processing tool calls (optional if agent has no tools) */
   tools?: T;
   /** Subagent configurations */
@@ -75,27 +105,67 @@ export interface SessionConfig<T extends ToolMap, M = unknown> {
    * Returns MessageContent array for the initial HumanMessage.
    */
   buildContextMessage: () => MessageContent | Promise<MessageContent>;
-  /** When true, skip thread initialization and system prompt — append only the new human message to the existing thread. */
-  continueThread?: boolean;
   /** How long to wait for input before cancelling the workflow */
   waitForInputTimeout?: Duration;
+
+  // ---------------------------------------------------------------------------
+  // Thread lifecycle
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Thread initialization strategy (default: `{ mode: "new" }`).
+   *
+   * - `{ mode: "new" }` — start a fresh thread.
+   * - `{ mode: "new", threadId: "..." }` — start a fresh thread with a specific ID.
+   * - `{ mode: "continue", threadId: "..." }` — append to an existing thread in-place.
+   * - `{ mode: "fork", threadId: "..." }` — fork an existing thread and continue in the copy.
+   */
+  thread?: ThreadInit;
+
+  // ---------------------------------------------------------------------------
+  // Sandbox lifecycle
+  // ---------------------------------------------------------------------------
+
   /** Sandbox lifecycle operations (optional — omit for agents that don't need a sandbox) */
-  sandbox?: SandboxOps;
+  sandboxOps?: SandboxOps;
   /**
-   * Pre-existing sandbox ID to reuse (e.g. inherited from a parent agent).
-   * When set, the session skips `createSandbox` and will not destroy the
-   * sandbox on exit (the owner is responsible for cleanup).
+   * Sandbox initialization strategy.
+   *
+   * - `{ mode: "new" }` — create a fresh sandbox.
+   * - `{ mode: "continue", sandboxId: "..." }` — resume a paused sandbox (session owns it).
+   * - `{ mode: "fork", sandboxId: "..." }` — fork from an existing sandbox.
+   * - `{ mode: "inherit", sandboxId: "..." }` — use a parent's sandbox without ownership.
+   *
+   * When omitted and `sandboxOps` is provided, defaults to `{ mode: "new" }`.
    */
-  sandboxId?: string;
+  sandbox?: SandboxInit;
+  /**
+   * What to do with the sandbox when this session exits.
+   *
+   * Defaults to `"destroy"` when omitted.
+   * Has no effect when the sandbox is inherited (`sandbox.mode === "inherit"`).
+   */
+  sandboxShutdown?: SubagentSandboxShutdown;
 }
 
-export interface ZeitlichSession<M = unknown> {
+export type SessionResult<
+  M,
+  TState extends JsonSerializable<TState>,
+  HasSandbox extends boolean = boolean,
+> = {
+  threadId: string;
+  finalMessage: M | null;
+  exitReason: SessionExitReason;
+  usage: ReturnType<AgentStateManager<TState>["getTotalUsage"]>;
+} & (HasSandbox extends true
+  ? { sandboxId: string }
+  : { sandboxId?: undefined });
+
+export interface ZeitlichSession<
+  M = unknown,
+  HasSandbox extends boolean = boolean,
+> {
   runSession<T extends JsonSerializable<T>>(args: {
     stateManager: AgentStateManager<T>;
-  }): Promise<{
-    threadId: string;
-    finalMessage: M | null;
-    exitReason: SessionExitReason;
-    usage: ReturnType<AgentStateManager<T>["getTotalUsage"]>;
-  }>;
+  }): Promise<SessionResult<M, T, HasSandbox>>;
 }

package/src/lib/subagent/define.ts

@@ -3,6 +3,7 @@ import type {
   SubagentConfig,
   SubagentDefinition,
   SubagentHooks,
+  SubagentSandboxConfig,
   SubagentWorkflow,
 } from "./types";
 import type { SubagentArgs } from "./tool";
@@ -19,8 +20,8 @@ import type { SubagentArgs } from "./tool";
  *
  * // With parent-specific overrides
  * export const researcher = defineSubagent(researcherWorkflow, {
- *   allowThreadContinuation: true,
- *   sandbox: "own",
+ *   thread: "fork",
+ *   sandbox: { source: "own", shutdown: "pause" },
  *   hooks: {
  *     onPostExecution: ({ result }) => console.log(result),
  *   },
@@ -38,12 +39,12 @@ export function defineSubagent<
 >(
   definition: SubagentDefinition<TResult, TContext>,
   overrides?: {
-    context?: TContext;
+    context?: TContext | (() => TContext);
     hooks?: SubagentHooks<SubagentArgs, z.infer<TResult>>;
     enabled?: boolean | (() => boolean);
     taskQueue?: string;
-    allowThreadContinuation?: boolean;
-    sandbox?: "inherit" | "own";
+    thread?: "new" | "fork" | "continue";
+    sandbox?: SubagentSandboxConfig;
   },
 ): SubagentConfig<TResult> {
   return {