zeitlich 0.2.38 → 0.2.39

package/dist/{workflow-DuvMZ8Vm.d.cts → workflow-Bx9utBwb.d.cts}

@@ -1,4 +1,4 @@
-import { aq as ToolMap, a0 as SessionConfig, aB as ZeitlichSession, _ as SandboxShutdown, ai as ThreadInit, Z as SandboxInit, t as JsonSerializable, B as BaseAgentState, o as AgentStateManager, aD as ToolRouterOptions, at as ToolRouter, R as RouterContext, J as JsonValue, av as ToolWithHandler, v as ParsedToolCallUnion, ar as ToolNames, a8 as SubagentDefinition, ab as SubagentHooks, ac as SubagentSandboxConfig, a7 as SubagentConfig, ad as SubagentSandboxShutdown, ae as SubagentSessionInput, a9 as SubagentFnResult, a5 as SessionStartHook, a1 as SessionEndHook, D as PostToolUseHook, y as PostToolUseFailureHook, a3 as SessionExitReason, aj as TokenUsage, e as RunAgentConfig, A as AgentResponse, F as FileEntryMetadata, ax as VirtualFileTree, j as TreeMutation, r as FileEntry, ay as VirtualFsOps, g as SkillMetadata, h as Skill, b as ToolHandlerResponse, ao as ToolHandler, aA as WorkflowTask, c as ActivityToolHandler } from './types-C06FwR96.cjs';
+import { as as ToolMap, a1 as SessionConfig, aD as ZeitlichSession, $ as SandboxShutdown, ak as ThreadInit, _ as SandboxInit, u as JsonSerializable, B as BaseAgentState, p as AgentStateManager, aF as ToolRouterOptions, av as ToolRouter, R as RouterContext, J as JsonValue, ax as ToolWithHandler, w as ParsedToolCallUnion, at as ToolNames, aa as SubagentDefinition, ad as SubagentHooks, ae as SubagentSandboxConfig, a9 as SubagentConfig, af as SubagentSandboxShutdown, ag as SubagentSessionInput, ab as SubagentFnResult, a6 as SessionStartHook, a2 as SessionEndHook, E as PostToolUseHook, z as PostToolUseFailureHook, a4 as SessionExitReason, al as TokenUsage, f as RunAgentConfig, A as AgentResponse, F as FileEntryMetadata, az as VirtualFileTree, k as TreeMutation, s as FileEntry, aA as VirtualFsOps, h as SkillMetadata, i as Skill, c as ToolHandlerResponse, aq as ToolHandler, aC as WorkflowTask, d as ActivityToolHandler } from './types-Bcbiq8iv.cjs';
 import { g as SandboxOps } from './types-yx0LzPGn.cjs';
 import z$1, { z } from 'zod';
 import { Sinks, proxyActivities } from '@temporalio/workflow';
@@ -97,6 +97,68 @@ declare function defineWorkflow<TInput, TResult>(config: WorkflowConfig, fn: (in
  */
 declare function getShortId(length?: number): string;
 
+/**
+ * Public helpers for zeitlich's Redis thread storage layout.
+ *
+ * These are the exact string-building primitives zeitlich's internal thread
+ * manager uses for every adapter. Downstream consumers that need to read a
+ * persisted thread (for evaluation, observability, admin tooling, etc.)
+ * should use these helpers rather than reconstructing the key layout by
+ * hand — the layout is versioned with this module, so upgrading zeitlich
+ * keeps the consumer in sync.
+ *
+ * The layout is adapter-agnostic: every thread adapter stores messages the
+ * same way.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   getThreadListKey,
+ *   getThreadMetaKey,
+ *   THREAD_TTL_SECONDS,
+ * } from 'zeitlich';
+ *
+ * const listKey = getThreadListKey('messages', threadId);
+ * const metaKey = getThreadMetaKey('messages', threadId);
+ * const ttl = await redis.ttl(listKey); // <= THREAD_TTL_SECONDS
+ * ```
+ */
+/**
+ * TTL (in seconds) applied to every thread list and thread meta key that
+ * zeitlich's {@link createThreadManager} writes. Exposed so downstream
+ * consumers can size their Redis retention / query windows to match.
+ *
+ * Current value: 90 days.
+ */
+declare const THREAD_TTL_SECONDS: number;
+/**
+ * Build the Redis list key that holds a thread's serialized messages.
+ *
+ * Mirrors the exact key used internally by zeitlich's thread manager,
+ * so a consumer calling `redis.lrange(getThreadListKey(key, id), 0, -1)`
+ * sees the same data the writer wrote.
+ *
+ * @param threadKey - Thread key (defaults to `"messages"` inside the
+ *                    thread manager, but downstream adapters may pass
+ *                    their own value).
+ * @param threadId  - Thread id as provided to the thread manager.
+ */
+declare function getThreadListKey(threadKey: string, threadId: string): string;
+/**
+ * Build the Redis key that stores a thread's existence marker / metadata.
+ *
+ * Zeitlich treats the presence of this key as "thread has been
+ * initialized"; append/load/fork/truncate operations fail when it is
+ * missing. Consumers can use it as a cheap existence probe without
+ * scanning the message list.
+ *
+ * @param threadKey - Thread key (defaults to `"messages"` inside the
+ *                    thread manager, but downstream adapters may pass
+ *                    their own value).
+ * @param threadId  - Thread id as provided to the thread manager.
+ */
+declare function getThreadMetaKey(threadKey: string, threadId: string): string;
+
 /**
  * Creates an agent state manager for tracking workflow state.
  * Automatically registers Temporal query and update handlers for the agent.
@@ -194,6 +256,22 @@ type SubagentArgs = {
     threadId?: string | null;
 };
 
+/**
+ * Default `workflowRunTimeout` applied to every subagent child workflow
+ * unless overridden via `SubagentConfig.workflowOptions.workflowRunTimeout`.
+ *
+ * Chosen as a safety bound: Temporal retries failing workflow tasks forever
+ * by default, so a child that fails to initialize (e.g. missing workflow
+ * export) or is otherwise broken will never reach a terminal state on its
+ * own and the parent's `Subagent` tool call would hang indefinitely. A
+ * bounded run timeout guarantees the child is eventually terminated and the
+ * parent receives a structured `ChildWorkflowFailure` it can surface to the
+ * agent. One hour is generous enough for realistic agent sessions while
+ * still catching hangs; agents that legitimately need longer should set an
+ * explicit `workflowOptions.workflowRunTimeout`.
+ */
+declare const DEFAULT_SUBAGENT_WORKFLOW_RUN_TIMEOUT = "1h";
+
 /**
  * Creates a `SubagentConfig` from a `SubagentDefinition` (returned by `defineSubagentWorkflow`).
  * Metadata (name, description, resultSchema) is read from the definition — only configure
@@ -264,6 +342,8 @@ declare function defineSubagent<TResult extends z.ZodType = z.ZodType, TContext
  *     });
  *
  *     const { finalMessage, threadId } = await session.runSession({ stateManager });
+ *     // `sandboxId`, `snapshot`, and `baseSnapshot` are auto-forwarded
+ *     // from the session — no need to thread them through manually.
  *     return { toolResponse: finalMessage ?? "No response", data: null, threadId };
  *   },
  * );
@@ -775,4 +855,4 @@ declare const createAskUserQuestionHandler: () => ActivityToolHandler<AskUserQue
     }[];
 }>;
 
-export { proxyRunAgent as $, type AskUserQuestionArgs as A, type BashArgs as B, createTaskListHandler as C, createTaskUpdateHandler as D, createToolRouter as E, type FileEditArgs as F, type GlobArgs as G, defineSubagent as H, defineSubagentWorkflow as I, defineTool as J, defineWorkflow as K, editTool as L, filesWithMimeType as M, formatVirtualFileTree as N, type ObservabilityHooks as O, getShortId as P, globTool as Q, type ReadSkillArgs as R, type SessionEndedEvent as S, type TaskCreateArgs as T, grepTool as U, hasDirectory as V, type WorkflowConfig as W, hasFileWithMimeType as X, hasNoOtherToolCalls as Y, type ZeitlichObservabilitySinks as Z, parseSkillFile as _, type FileReadArgs as a, proxyVirtualFsOps as a0, readFileTool as a1, taskCreateTool as a2, taskGetTool as a3, taskListTool as a4, taskUpdateTool as a5, writeFileTool as a6, type FileWriteArgs as b, type FileTreeAccessor as c, type GrepArgs as d, type SessionStartedEvent as e, type SubagentArgs as f, type TaskGetArgs as g, type TaskListArgs as h, type TaskUpdateArgs as i, type ToolExecutedEvent as j, type TurnCompletedEvent as k, type WorkflowInput as l, type WorkflowSessionInput as m, applyVirtualTreeMutations as n, askUserQuestionTool as o, bashTool as p, composeHooks as q, createAgentStateManager as r, createAskUserQuestionHandler as s, createBashToolDescription as t, createObservabilityHooks as u, createReadSkillHandler as v, createReadSkillTool as w, createSession as x, createTaskCreateHandler as y, createTaskGetHandler as z };
+export { hasDirectory as $, type AskUserQuestionArgs as A, type BashArgs as B, createTaskGetHandler as C, DEFAULT_SUBAGENT_WORKFLOW_RUN_TIMEOUT as D, createTaskListHandler as E, type FileEditArgs as F, type GlobArgs as G, createTaskUpdateHandler as H, createToolRouter as I, defineSubagent as J, defineSubagentWorkflow as K, defineTool as L, defineWorkflow as M, editTool as N, type ObservabilityHooks as O, filesWithMimeType as P, formatVirtualFileTree as Q, type ReadSkillArgs as R, type SessionEndedEvent as S, THREAD_TTL_SECONDS as T, getShortId as U, getThreadListKey as V, type WorkflowConfig as W, getThreadMetaKey as X, globTool as Y, type ZeitlichObservabilitySinks as Z, grepTool as _, type FileReadArgs as a, hasFileWithMimeType as a0, hasNoOtherToolCalls as a1, parseSkillFile as a2, proxyRunAgent as a3, proxyVirtualFsOps as a4, readFileTool as a5, taskCreateTool as a6, taskGetTool as a7, taskListTool as a8, taskUpdateTool as a9, writeFileTool as aa, type FileWriteArgs as b, type FileTreeAccessor as c, type GrepArgs as d, type SessionStartedEvent as e, type SubagentArgs as f, type TaskCreateArgs as g, type TaskGetArgs as h, type TaskListArgs as i, type TaskUpdateArgs as j, type ToolExecutedEvent as k, type TurnCompletedEvent as l, type WorkflowInput as m, type WorkflowSessionInput as n, applyVirtualTreeMutations as o, askUserQuestionTool as p, bashTool as q, composeHooks as r, createAgentStateManager as s, createAskUserQuestionHandler as t, createBashToolDescription as u, createObservabilityHooks as v, createReadSkillHandler as w, createReadSkillTool as x, createSession as y, createTaskCreateHandler as z };

package/dist/workflow.cjs

@@ -440,6 +440,7 @@ function createSubagentTool(subagents) {
 var childSandboxReadySignal = workflow.defineSignal("childSandboxReady");
 
 // src/lib/subagent/handler.ts
+var DEFAULT_SUBAGENT_WORKFLOW_RUN_TIMEOUT = "1h";
 function resolveSandboxConfig(config) {
   if (!config || config === "none") {
     return { source: "none", init: "per-call", continuation: "fork" };
@@ -471,17 +472,28 @@ function createSubagentHandler(subagents) {
   const threadSandboxes = /* @__PURE__ */ new Map();
   const persistentSandboxes = /* @__PURE__ */ new Map();
   const persistentSandboxCreating = /* @__PURE__ */ new Set();
+  const persistentSandboxCreationError = /* @__PURE__ */ new Map();
   const lazyCreatorAgent = /* @__PURE__ */ new Map();
+  const snapshotBaseCreatorAgent = /* @__PURE__ */ new Map();
   const threadSnapshots = /* @__PURE__ */ new Map();
   const persistentBaseSnapshot = /* @__PURE__ */ new Map();
   const persistentBaseSnapshotCreating = /* @__PURE__ */ new Set();
-  workflow.setHandler(childSandboxReadySignal, ({ childWorkflowId, sandboxId }) => {
-    const agentName = lazyCreatorAgent.get(childWorkflowId);
-    if (agentName && !persistentSandboxes.has(agentName)) {
-      persistentSandboxes.set(agentName, sandboxId);
-      lazyCreatorAgent.delete(childWorkflowId);
+  const persistentBaseSnapshotCreationError = /* @__PURE__ */ new Map();
+  workflow.setHandler(
+    childSandboxReadySignal,
+    ({ childWorkflowId, sandboxId, baseSnapshot }) => {
+      const lazyAgent = lazyCreatorAgent.get(childWorkflowId);
+      if (lazyAgent && !persistentSandboxes.has(lazyAgent)) {
+        persistentSandboxes.set(lazyAgent, sandboxId);
+        lazyCreatorAgent.delete(childWorkflowId);
+      }
+      const snapAgent = snapshotBaseCreatorAgent.get(childWorkflowId);
+      if (snapAgent && baseSnapshot && !persistentBaseSnapshot.has(snapAgent)) {
+        persistentBaseSnapshot.set(snapAgent, baseSnapshot);
+        snapshotBaseCreatorAgent.delete(childWorkflowId);
+      }
     }
-  });
+  );
   const handler = async (args, context) => {
     const config = subagents.find((s) => s.agentName === args.subagent);
     if (!config) {
@@ -537,8 +549,20 @@ function createSubagentHandler(subagents) {
         baseSnap = persistentBaseSnapshot.get(config.agentName);
         if (!baseSnap) {
           if (persistentBaseSnapshotCreating.has(config.agentName)) {
-            await workflow.condition(() => persistentBaseSnapshot.has(config.agentName));
+            await workflow.condition(
+              () => persistentBaseSnapshot.has(config.agentName) || persistentBaseSnapshotCreationError.has(config.agentName) || !persistentBaseSnapshotCreating.has(config.agentName)
+            );
+            const creatorErr = persistentBaseSnapshotCreationError.get(
+              config.agentName
+            );
+            if (creatorErr !== void 0) {
+              throw creatorErr;
+            }
             baseSnap = persistentBaseSnapshot.get(config.agentName);
+            if (!baseSnap) {
+              persistentBaseSnapshotCreating.add(config.agentName);
+              isSnapshotBaseCreator = true;
+            }
           } else {
             persistentBaseSnapshotCreating.add(config.agentName);
             isSnapshotBaseCreator = true;
@@ -556,8 +580,20 @@ function createSubagentHandler(subagents) {
         baseSandboxId = persistentSandboxes.get(config.agentName);
         if (!baseSandboxId) {
           if (persistentSandboxCreating.has(config.agentName)) {
-            await workflow.condition(() => persistentSandboxes.has(config.agentName));
+            await workflow.condition(
+              () => persistentSandboxes.has(config.agentName) || persistentSandboxCreationError.has(config.agentName) || !persistentSandboxCreating.has(config.agentName)
+            );
+            const creatorErr = persistentSandboxCreationError.get(
+              config.agentName
+            );
+            if (creatorErr !== void 0) {
+              throw creatorErr;
+            }
             baseSandboxId = persistentSandboxes.get(config.agentName);
+            if (!baseSandboxId) {
+              persistentSandboxCreating.add(config.agentName);
+              isLazyCreator = true;
+            }
           } else {
             persistentSandboxCreating.add(config.agentName);
             isLazyCreator = true;
@@ -586,6 +622,12 @@ function createSubagentHandler(subagents) {
     };
     const resolvedContext = config.context === void 0 ? void 0 : typeof config.context === "function" ? config.context() : config.context;
     const childOpts = {
+      // Apply a bounded run timeout by default so a child workflow that
+      // fails to initialize or otherwise never reaches a terminal state
+      // cannot hang the parent's `Subagent` tool call forever. Callers can
+      // raise, lower, or disable it via `workflowOptions.workflowRunTimeout`.
+      workflowRunTimeout: DEFAULT_SUBAGENT_WORKFLOW_RUN_TIMEOUT,
+      ...config.workflowOptions ?? {},
       workflowId: childWorkflowId,
       args: resolvedContext === void 0 ? [args.prompt, workflowInput] : [args.prompt, workflowInput, resolvedContext],
       taskQueue: config.taskQueue ?? parentTaskQueue
@@ -593,13 +635,39 @@ function createSubagentHandler(subagents) {
     if (isLazyCreator) {
       lazyCreatorAgent.set(childWorkflowId, config.agentName);
     }
+    if (isSnapshotBaseCreator) {
+      snapshotBaseCreatorAgent.set(childWorkflowId, config.agentName);
+    }
     workflow.log.info("subagent spawned", {
       subagent: config.agentName,
       childWorkflowId,
       threadMode,
       sandboxSource: sandboxCfg.source
     });
-    const childResult = await workflow.executeChild(config.workflow, childOpts);
+    let childResult;
+    try {
+      childResult = await workflow.executeChild(
+        config.workflow,
+        childOpts
+      );
+    } catch (err) {
+      workflow.log.warn("subagent failed", {
+        subagent: config.agentName,
+        childWorkflowId,
+        error: err instanceof Error ? err.message : String(err)
+      });
+      if (isLazyCreator) {
+        persistentSandboxCreating.delete(config.agentName);
+        persistentSandboxCreationError.set(config.agentName, err);
+        lazyCreatorAgent.delete(childWorkflowId);
+      }
+      if (isSnapshotBaseCreator) {
+        persistentBaseSnapshotCreating.delete(config.agentName);
+        persistentBaseSnapshotCreationError.set(config.agentName, err);
+        snapshotBaseCreatorAgent.delete(childWorkflowId);
+      }
+      throw err;
+    }
     const effectiveShutdown = sandboxShutdownOverride ?? sandboxCfg.shutdown ?? "destroy";
     workflow.log.info("subagent completed", {
       subagent: config.agentName,
@@ -643,10 +711,13 @@ function createSubagentHandler(subagents) {
     }
     if (isLazyCreator) {
       persistentSandboxCreating.delete(config.agentName);
+      persistentSandboxCreationError.delete(config.agentName);
       lazyCreatorAgent.delete(childWorkflowId);
     }
     if (isSnapshotBaseCreator) {
       persistentBaseSnapshotCreating.delete(config.agentName);
+      persistentBaseSnapshotCreationError.delete(config.agentName);
+      snapshotBaseCreatorAgent.delete(childWorkflowId);
     }
     if (!toolResponse) {
       return {
@@ -889,6 +960,7 @@ async function createSession({
   sandbox: sandboxInit,
   sandboxShutdown = "destroy",
   onSandboxReady,
+  onSessionExit,
   virtualFs: virtualFsConfig,
   virtualFsOps
 }) {
@@ -914,7 +986,8 @@ async function createSession({
     appendSystemMessage,
     appendAgentMessage,
     forkThread,
-    truncateThread
+    loadThreadState,
+    saveThreadState
   } = threadOps;
   const plugins = [];
   let destroySubagentSandboxes;
@@ -1042,7 +1115,10 @@ async function createSession({
         baseSnapshot = await sandboxOps.snapshotSandbox(sandboxId);
       }
       if (sandboxId && sandboxOwned && onSandboxReady) {
-        onSandboxReady(sandboxId);
+        onSandboxReady({
+          sandboxId,
+          ...baseSnapshot && { baseSnapshot }
+        });
       }
       if (virtualFsConfig) {
         if (!virtualFsOps) {
@@ -1085,9 +1161,20 @@ async function createSession({
       });
       const sessionStartMs = Date.now();
       const systemPrompt = stateManager.getSystemPrompt();
+      const rehydrateFromSlice = (slice) => {
+        stateManager.mergeUpdate({
+          tasks: new Map(slice.tasks),
+          ...slice.custom
+        });
+      };
       if (threadMode === "fork" && sourceThreadId) {
         await forkThread(sourceThreadId, threadId, threadKey);
-      } else if (threadMode === "continue") ; else {
+        const forkedSlice = await loadThreadState(threadId, threadKey);
+        if (forkedSlice) rehydrateFromSlice(forkedSlice);
+      } else if (threadMode === "continue") {
+        const continuedSlice = await loadThreadState(threadId, threadKey);
+        if (continuedSlice) rehydrateFromSlice(continuedSlice);
+      } else {
         if (appendSystemPrompt) {
           if (systemPrompt == null || typeof systemPrompt === "string" && systemPrompt.trim() === "") {
             throw workflow.ApplicationFailure.create({
@@ -1109,24 +1196,21 @@ async function createSession({
       let exitReason = "completed";
       let finalMessage = null;
       try {
+        let assistantId;
         while (stateManager.isRunning() && !stateManager.isTerminal() && stateManager.getTurns() < maxTurns) {
           stateManager.incrementTurns();
           const currentTurn = stateManager.getTurns();
           workflow.log.debug("turn started", { agentName, threadId, turn: currentTurn });
           stateManager.setTools(toolRouter.getToolDefinitions());
-          const {
-            message,
-            rawToolCalls,
-            usage,
-            threadLengthAtCall
-          } = await runAgent({
+          assistantId ??= workflow.uuid4();
+          const { message, rawToolCalls, usage } = await runAgent({
             threadId,
             threadKey,
             agentName,
-            metadata
+            metadata,
+            assistantMessageId: assistantId
           });
-          const preAssistantLength = threadLengthAtCall;
-          await appendAgentMessage(threadId, workflow.uuid4(), message, threadKey);
+          await appendAgentMessage(threadId, assistantId, message, threadKey);
           if (usage) {
             stateManager.updateUsage(usage);
           }
@@ -1180,15 +1264,9 @@ async function createSession({
               toolCallId: rewind.toolCallId,
               toolName: rewind.toolName
             });
-            if (preAssistantLength === void 0) {
-              throw workflow.ApplicationFailure.create({
-                message: "Rewind requested but runAgent did not report `threadLengthAtCall`; the adapter must populate it to support rewinds.",
-                nonRetryable: true
-              });
-            }
-            await truncateThread(threadId, preAssistantLength, threadKey);
             continue;
           }
+          assistantId = void 0;
           if (stateManager.getStatus() === "WAITING_FOR_INPUT") {
             const conditionMet = await workflow.condition(
               () => stateManager.getStatus() === "RUNNING",
@@ -1221,6 +1299,19 @@ async function createSession({
         });
         throw workflow.ApplicationFailure.fromError(error);
       } finally {
+        try {
+          await saveThreadState(
+            threadId,
+            stateManager.getPersistedSlice(),
+            threadKey
+          );
+        } catch (persistError) {
+          workflow.log.warn("failed to persist thread state", {
+            agentName,
+            threadId,
+            error: persistError instanceof Error ? persistError.message : String(persistError)
+          });
+        }
         await callSessionEnd(exitReason, stateManager.getTurns());
         if (sandboxOwned && sandboxId && sandboxOps) {
           switch (sandboxShutdown) {
@@ -1257,6 +1348,12 @@ async function createSession({
         ...baseSnapshot && { hasBaseSnapshot: true },
         ...exitSnapshot && { hasExitSnapshot: true }
       });
+      if (onSessionExit) {
+        onSessionExit({
+          ...sandboxId && { sandboxId },
+          ...exitSnapshot && { snapshot: exitSnapshot }
+        });
+      }
       return {
         threadId,
         finalMessage,
@@ -1285,6 +1382,15 @@ function defineWorkflow(config, fn) {
   return workflow;
 }
 
+// src/lib/thread/keys.ts
+var THREAD_TTL_SECONDS = 60 * 60 * 24 * 90;
+function getThreadListKey(threadKey, threadId) {
+  return `${threadKey}:thread:${threadId}`;
+}
+function getThreadMetaKey(threadKey, threadId) {
+  return `${threadKey}:meta:thread:${threadId}`;
+}
+
 // src/lib/types.ts
 function isTerminalStatus(status) {
   return status === "COMPLETED" || status === "FAILED" || status === "CANCELLED";
@@ -1304,11 +1410,19 @@ function createAgentStateManager({
   let systemPrompt = initialState?.systemPrompt;
   const tasks = new Map(initialState?.tasks);
   const {
-    status: _,
-    version: __,
-    turns: ___,
-    tasks: ____,
-    tools: _____,
+    status: _status,
+    version: _version,
+    turns: _turns,
+    tasks: _tasks,
+    tools: _tools,
+    systemPrompt: _systemPrompt,
+    fileTree: _fileTree,
+    inlineFiles: _inlineFiles,
+    virtualFsCtx: _virtualFsCtx,
+    totalInputTokens: _totalInputTokens,
+    totalOutputTokens: _totalOutputTokens,
+    cachedWriteTokens: _cachedWriteTokens,
+    cachedReadTokens: _cachedReadTokens,
     ...custom
   } = initialState ?? {};
   const customState = custom;
@@ -1388,7 +1502,14 @@ function createAgentStateManager({
       version++;
     },
     mergeUpdate(update) {
-      Object.assign(customState, update);
+      const { tasks: nextTasks, ...rest } = update;
+      if (nextTasks) {
+        tasks.clear();
+        for (const [id, task] of nextTasks) {
+          tasks.set(id, task);
+        }
+      }
+      Object.assign(customState, rest);
       version++;
     },
     getCurrentState() {
@@ -1426,6 +1547,12 @@ function createAgentStateManager({
       }
       return deleted;
     },
+    getPersistedSlice() {
+      return {
+        tasks: Array.from(tasks.entries()),
+        custom: { ...customState }
+      };
+    },
     updateUsage(usage) {
       totalInputTokens += usage.inputTokens ?? 0;
       totalOutputTokens += usage.outputTokens ?? 0;
@@ -1469,22 +1596,42 @@ function defineSubagentWorkflow(config, fn) {
       });
     }
     const parentHandle = workflow.getExternalWorkflowHandle(parent.workflowId);
+    let capturedSandboxId;
+    let capturedSnapshot;
+    let capturedBaseSnapshot;
+    let capturedThreadId;
     const sessionInput = {
       agentName: config.name,
       sandboxShutdown: effectiveShutdown,
       ...workflowInput.thread && { thread: workflowInput.thread },
       ...workflowInput.sandbox && { sandbox: workflowInput.sandbox },
-      onSandboxReady: (sandboxId) => {
+      onSandboxReady: ({ sandboxId, baseSnapshot }) => {
+        capturedBaseSnapshot = baseSnapshot;
         const isReuse = workflowInput.sandbox?.mode === "continue";
         if (!isReuse) {
           void parentHandle.signal(childSandboxReadySignal, {
             childWorkflowId: workflow.workflowInfo().workflowId,
-            sandboxId
+            sandboxId,
+            ...baseSnapshot && { baseSnapshot }
           });
         }
+      },
+      onSessionExit: ({ sandboxId, snapshot, threadId }) => {
+        capturedSandboxId = sandboxId;
+        capturedSnapshot = snapshot;
+        capturedThreadId = threadId;
+      }
+    };
+    const result = await fn(prompt, sessionInput, context ?? {});
+    return {
+      ...result,
+      ...capturedThreadId !== void 0 && { threadId: capturedThreadId },
+      ...capturedSandboxId !== void 0 && { sandboxId: capturedSandboxId },
+      ...capturedSnapshot !== void 0 && { snapshot: capturedSnapshot },
+      ...capturedBaseSnapshot !== void 0 && {
+        baseSnapshot: capturedBaseSnapshot
       }
     };
-    return fn(prompt, sessionInput, context ?? {});
   };
   Object.defineProperty(workflow$1, "name", { value: config.name });
   return Object.assign(workflow$1, {
@@ -2143,8 +2290,10 @@ var createAskUserQuestionHandler = () => async (args) => {
   };
 };
 
+exports.DEFAULT_SUBAGENT_WORKFLOW_RUN_TIMEOUT = DEFAULT_SUBAGENT_WORKFLOW_RUN_TIMEOUT;
 exports.SandboxNotFoundError = SandboxNotFoundError;
 exports.SandboxNotSupportedError = SandboxNotSupportedError;
+exports.THREAD_TTL_SECONDS = THREAD_TTL_SECONDS;
 exports.applyVirtualTreeMutations = applyVirtualTreeMutations;
 exports.askUserQuestionTool = askUserQuestionTool;
 exports.bashTool = bashTool;
@@ -2169,6 +2318,8 @@ exports.editTool = editTool;
 exports.filesWithMimeType = filesWithMimeType;
 exports.formatVirtualFileTree = formatVirtualFileTree;
 exports.getShortId = getShortId;
+exports.getThreadListKey = getThreadListKey;
+exports.getThreadMetaKey = getThreadMetaKey;
 exports.globTool = globTool;
 exports.grepTool = grepTool;
 exports.hasDirectory = hasDirectory;