zeitlich 0.2.36 → 0.2.38

package/src/adapters/thread/langchain/activities.ts

@@ -24,8 +24,10 @@ import { createLangChainModelInvoker } from "./model-invoker";
 
 const ADAPTER_PREFIX = "langChain" as const;
 
-export type LangChainThreadOps<TScope extends string = ""> =
-  PrefixedThreadOps<ScopedPrefix<TScope, typeof ADAPTER_PREFIX>, LangChainContent>;
+export type LangChainThreadOps<TScope extends string = ""> = PrefixedThreadOps<
+  ScopedPrefix<TScope, typeof ADAPTER_PREFIX>,
+  LangChainContent
+>;
 
 export interface LangChainAdapterConfig {
   redis: Redis;
@@ -61,9 +63,7 @@ export interface LangChainAdapter {
    * // → { langChainCodingAgentInitializeThread, langChainCodingAgentAppendHumanMessage, … }
    * ```
    */
-  createActivities<S extends string = "">(
-    scope?: S,
-  ): LangChainThreadOps<S>;
+  createActivities<S extends string = "">(scope?: S): LangChainThreadOps<S>;
 
   /**
    * Identity wrapper that types a tool handler for this adapter.
@@ -72,8 +72,8 @@ export interface LangChainAdapter {
   wrapHandler<TArgs, TResult, TContext extends RouterContext = RouterContext>(
     handler: (
       args: TArgs,
-      context: TContext,
-    ) => Promise<ToolHandlerResponse<TResult, LangChainToolResponse>>,
+      context: TContext
+    ) => Promise<ToolHandlerResponse<TResult, LangChainToolResponse>>
   ): ActivityToolHandler<TArgs, TResult, TContext, LangChainToolResponse>;
 }
 
@@ -113,13 +113,20 @@ export interface LangChainAdapter {
  * ```
  */
 export function createLangChainAdapter(
-  config: LangChainAdapterConfig,
+  config: LangChainAdapterConfig
 ): LangChainAdapter {
   const { redis } = config;
 
   const threadOps: ThreadOps<LangChainContent> = {
-    async initializeThread(threadId: string, threadKey?: string): Promise<void> {
-      const thread = createLangChainThreadManager({ redis, threadId, key: threadKey });
+    async initializeThread(
+      threadId: string,
+      threadKey?: string
+    ): Promise<void> {
+      const thread = createLangChainThreadManager({
+        redis,
+        threadId,
+        key: threadKey,
+      });
       await thread.initialize();
     },
 
@@ -127,9 +134,13 @@ export function createLangChainAdapter(
       threadId: string,
       id: string,
       content: LangChainContent,
-      threadKey?: string,
+      threadKey?: string
     ): Promise<void> {
-      const thread = createLangChainThreadManager({ redis, threadId, key: threadKey });
+      const thread = createLangChainThreadManager({
+        redis,
+        threadId,
+        key: threadKey,
+      });
       await thread.appendUserMessage(id, content);
     },
 
@@ -137,15 +148,23 @@ export function createLangChainAdapter(
       threadId: string,
       id: string,
       content: LangChainSystemContent,
-      threadKey?: string,
+      threadKey?: string
     ): Promise<void> {
-      const thread = createLangChainThreadManager({ redis, threadId, key: threadKey });
+      const thread = createLangChainThreadManager({
+        redis,
+        threadId,
+        key: threadKey,
+      });
       await thread.appendSystemMessage(id, content);
     },
 
     async appendToolResult(id: string, cfg: ToolResultConfig): Promise<void> {
       const { threadId, threadKey, toolCallId, content } = cfg;
-      const thread = createLangChainThreadManager({ redis, threadId, key: threadKey });
+      const thread = createLangChainThreadManager({
+        redis,
+        threadId,
+        key: threadKey,
+      });
       await thread.appendToolResult(id, toolCallId, "", content);
     },
 
@@ -153,9 +172,13 @@ export function createLangChainAdapter(
       threadId: string,
       id: string,
       message: StoredMessage,
-      threadKey?: string,
+      threadKey?: string
     ): Promise<void> {
-      const thread = createLangChainThreadManager({ redis, threadId, key: threadKey });
+      const thread = createLangChainThreadManager({
+        redis,
+        threadId,
+        key: threadKey,
+      });
       const patched = { ...message, data: { ...message.data, id } };
       await thread.append([patched]);
     },
@@ -163,7 +186,7 @@ export function createLangChainAdapter(
     async forkThread(
       sourceThreadId: string,
       targetThreadId: string,
-      threadKey?: string,
+      threadKey?: string
     ): Promise<void> {
       const thread = createLangChainThreadManager({
         redis,
@@ -172,24 +195,32 @@ export function createLangChainAdapter(
       });
       await thread.fork(targetThreadId);
     },
+
+    async truncateThread(
+      threadId: string,
+      length: number,
+      threadKey?: string,
+    ): Promise<void> {
+      const thread = createLangChainThreadManager({ redis, threadId, key: threadKey });
+      await thread.truncate(length);
+    },
   };
 
   function createActivities<S extends string = "">(
-    scope?: S,
+    scope?: S
   ): LangChainThreadOps<S> {
     const prefix = scope
       ? `${ADAPTER_PREFIX}${scope.charAt(0).toUpperCase()}${scope.slice(1)}`
       : ADAPTER_PREFIX;
-    const cap = (s: string): string =>
-      s.charAt(0).toUpperCase() + s.slice(1);
+    const cap = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1);
     return Object.fromEntries(
-      Object.entries(threadOps).map(([k, v]) => [`${prefix}${cap(k)}`, v]),
+      Object.entries(threadOps).map(([k, v]) => [`${prefix}${cap(k)}`, v])
     ) as LangChainThreadOps<S>;
   }
 
   const makeInvoker = (
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    model: BaseChatModel<any>,
+    model: BaseChatModel<any>
   ): ModelInvoker<StoredMessage> =>
     createLangChainModelInvoker({ redis, model, hooks: config.hooks });
 
@@ -198,7 +229,7 @@ export function createLangChainAdapter(
     : () => {
         throw new Error(
           "No default model provided to createLangChainAdapter. " +
-            "Either pass `model` in the config or use `createModelInvoker(model)` instead.",
+            "Either pass `model` in the config or use `createModelInvoker(model)` instead."
         );
       };
 

package/src/adapters/thread/langchain/hooks.test.ts

@@ -3,11 +3,14 @@ import { HumanMessage, AIMessage } from "@langchain/core/messages";
 import type { BaseMessage } from "@langchain/core/messages";
 import { appendCachePoint } from "./hooks";
 
-const cacheBlock = { type: "cache_control" as const, cache_control: { type: "ephemeral" as const } };
+const cacheBlock = {
+  type: "cache_control" as const,
+  cache_control: { type: "ephemeral" as const },
+};
 
 function applyHook(
   messages: BaseMessage[],
-  hook: ReturnType<typeof appendCachePoint>,
+  hook: ReturnType<typeof appendCachePoint>
 ): BaseMessage[] {
   return messages.map((m, i, arr) => hook(m, i, arr));
 }
@@ -47,29 +50,25 @@ describe("appendCachePoint", () => {
   it("deduplicates within the last message", () => {
     const messages: BaseMessage[] = [
       new HumanMessage({
-        content: [
-          { type: "text", text: "hello" },
-          cacheBlock,
-        ],
+        content: [{ type: "text", text: "hello" }, cacheBlock],
       }),
     ];
     const hook = appendCachePoint(cacheBlock);
     const result = applyHook(messages, hook);
 
-    const blocks = (messageAt(result, 0).content as Array<{ type: string }>).filter(
-      (b) => b.type === cacheBlock.type,
-    );
+    const blocks = (
+      messageAt(result, 0).content as Array<{ type: string }>
+    ).filter((b) => b.type === cacheBlock.type);
     expect(blocks).toHaveLength(1);
   });
 
   it("strips old cache blocks when total would exceed maxBlocks", () => {
-    const messages: BaseMessage[] = Array.from({ length: 6 }, (_, i) =>
-      new HumanMessage({
-        content: [
-          { type: "text", text: `msg ${i}` },
-          cacheBlock,
-        ],
-      }),
+    const messages: BaseMessage[] = Array.from(
+      { length: 6 },
+      (_, i) =>
+        new HumanMessage({
+          content: [{ type: "text", text: `msg ${i}` }, cacheBlock],
+        })
     );
     const hook = appendCachePoint(cacheBlock, { maxBlocks: 4 });
     const result = applyHook(messages, hook);
@@ -78,13 +77,12 @@ describe("appendCachePoint", () => {
   });
 
   it("keeps the most recent cache blocks", () => {
-    const messages: BaseMessage[] = Array.from({ length: 6 }, (_, i) =>
-      new HumanMessage({
-        content: [
-          { type: "text", text: `msg ${i}` },
-          cacheBlock,
-        ],
-      }),
+    const messages: BaseMessage[] = Array.from(
+      { length: 6 },
+      (_, i) =>
+        new HumanMessage({
+          content: [{ type: "text", text: `msg ${i}` }, cacheBlock],
+        })
     );
     const hook = appendCachePoint(cacheBlock, { maxBlocks: 4 });
     const result = applyHook(messages, hook);
@@ -101,13 +99,12 @@ describe("appendCachePoint", () => {
   });
 
   it("respects a custom maxBlocks value", () => {
-    const messages: BaseMessage[] = Array.from({ length: 5 }, (_, i) =>
-      new HumanMessage({
-        content: [
-          { type: "text", text: `msg ${i}` },
-          cacheBlock,
-        ],
-      }),
+    const messages: BaseMessage[] = Array.from(
+      { length: 5 },
+      (_, i) =>
+        new HumanMessage({
+          content: [{ type: "text", text: `msg ${i}` }, cacheBlock],
+        })
     );
     const hook = appendCachePoint(cacheBlock, { maxBlocks: 2 });
     const result = applyHook(messages, hook);
@@ -141,13 +138,12 @@ describe("appendCachePoint", () => {
   });
 
   it("defaults maxBlocks to 4", () => {
-    const messages: BaseMessage[] = Array.from({ length: 8 }, (_, i) =>
-      new HumanMessage({
-        content: [
-          { type: "text", text: `msg ${i}` },
-          cacheBlock,
-        ],
-      }),
+    const messages: BaseMessage[] = Array.from(
+      { length: 8 },
+      (_, i) =>
+        new HumanMessage({
+          content: [{ type: "text", text: `msg ${i}` }, cacheBlock],
+        })
     );
     const hook = appendCachePoint(cacheBlock);
     const result = applyHook(messages, hook);
@@ -165,22 +161,13 @@ describe("appendCachePoint", () => {
         ],
       }),
       new HumanMessage({
-        content: [
-          { type: "text", text: "msg 1" },
-          cacheBlock,
-        ],
+        content: [{ type: "text", text: "msg 1" }, cacheBlock],
       }),
       new HumanMessage({
-        content: [
-          { type: "text", text: "msg 2" },
-          cacheBlock,
-        ],
+        content: [{ type: "text", text: "msg 2" }, cacheBlock],
       }),
       new HumanMessage({
-        content: [
-          { type: "text", text: "msg 3" },
-          cacheBlock,
-        ],
+        content: [{ type: "text", text: "msg 3" }, cacheBlock],
       }),
       new HumanMessage("last"),
     ];

package/src/adapters/thread/langchain/hooks.ts

@@ -12,8 +12,12 @@ type ContentBlock = MessageContent extends (infer U)[] | string ? U : never;
  */
 export function appendCachePoint(
   block: ContentBlock,
-  { maxBlocks = 4 }: { maxBlocks?: number } = {},
-): (message: BaseMessage, index: number, messages: readonly BaseMessage[]) => BaseMessage {
+  { maxBlocks = 4 }: { maxBlocks?: number } = {}
+): (
+  message: BaseMessage,
+  index: number,
+  messages: readonly BaseMessage[]
+) => BaseMessage {
   return (message, index, messages) => {
     const isLast = index === messages.length - 1;
 
@@ -23,13 +27,19 @@ export function appendCachePoint(
         if (content.some((b) => b.type === block.type)) return message;
         message.content = [...content, block];
       } else if (typeof content === "string") {
-        message.content = [{ type: "text", text: content }, block] satisfies MessageContent;
+        message.content = [
+          { type: "text", text: content },
+          block,
+        ] satisfies MessageContent;
       }
       return message;
     }
 
     const { content } = message;
-    if (!Array.isArray(content) || !content.some((b) => b.type === block.type)) {
+    if (
+      !Array.isArray(content) ||
+      !content.some((b) => b.type === block.type)
+    ) {
       return message;
     }
 
@@ -40,7 +50,10 @@ export function appendCachePoint(
       const msg = messages[i];
       if (!msg) continue;
       const c = msg.content;
-      if (Array.isArray(c) && c.some((b: ContentBlock) => b.type === block.type)) {
+      if (
+        Array.isArray(c) &&
+        c.some((b: ContentBlock) => b.type === block.type)
+      ) {
         cacheBlocksAfter++;
       }
     }

package/src/adapters/thread/langchain/model-invoker.ts

@@ -9,7 +9,7 @@ import {
 } from "./thread-manager";
 import { getActivityContext } from "../../../lib/activity";
 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
+ 
 export interface LangChainModelInvokerConfig<
   TModel extends BaseChatModel<any> = BaseChatModel<any>,
 > {
@@ -40,7 +40,7 @@ export interface LangChainModelInvokerConfig<
  * return { ...createRunAgentActivity(client, invoker, "myAgent") };
  * ```
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
+ 
 export function createLangChainModelInvoker<
   TModel extends BaseChatModel<any> = BaseChatModel<any>,
 >({ redis, model, hooks }: LangChainModelInvokerConfig<TModel>) {
@@ -58,7 +58,7 @@ export function createLangChainModelInvoker<
     });
     const runId = uuidv4();
 
-    const { messages } = await thread.prepareForInvocation();
+    const { messages, storedLength } = await thread.prepareForInvocation();
 
     const heartbeatInterval = heartbeat
       ? setInterval(() => heartbeat(), 30_000)
@@ -97,6 +97,7 @@ export function createLangChainModelInvoker<
             response.usage_metadata?.input_token_details?.cache_read ||
             (providerUsage.cacheReadInputTokens as number | undefined),
         },
+        threadLengthAtCall: storedLength,
       };
     } finally {
       if (heartbeatInterval) clearInterval(heartbeatInterval);
@@ -109,7 +110,7 @@ export function createLangChainModelInvoker<
  * Convenience wrapper around createLangChainModelInvoker for cases where
  * you don't need to reuse the invoker.
  */
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
+ 
 export async function invokeLangChainModel<
   TModel extends BaseChatModel<any> = BaseChatModel<any>,
 >({

package/src/adapters/thread/langchain/proxy.ts

@@ -27,7 +27,11 @@ const ADAPTER_PREFIX = "langChain";
 
 export function proxyLangChainThreadOps(
   scope?: string,
-  options?: Parameters<typeof createThreadOpsProxy>[2],
+  options?: Parameters<typeof createThreadOpsProxy>[2]
 ): ActivityInterfaceFor<ThreadOps<LangChainContent>> {
-  return createThreadOpsProxy(ADAPTER_PREFIX, scope, options) as ActivityInterfaceFor<ThreadOps<LangChainContent>>;
+  return createThreadOpsProxy(
+    ADAPTER_PREFIX,
+    scope,
+    options
+  ) as ActivityInterfaceFor<ThreadOps<LangChainContent>>;
 }

package/src/adapters/thread/langchain/thread-manager.test.ts

@@ -91,7 +91,11 @@ describe("LangChain thread manager hooks", () => {
 
       await tm.prepareForInvocation();
 
-      const args = hook.mock.calls[0] as unknown as [unknown, number, unknown[]];
+      const args = hook.mock.calls[0] as unknown as [
+        unknown,
+        number,
+        unknown[],
+      ];
       expect(args[2]).toHaveLength(2);
     });
   });

package/src/adapters/thread/langchain/thread-manager.ts

@@ -23,7 +23,10 @@ export type LangChainContent = string | MessageContent;
 /** SDK-native content type for LangChain system messages */
 export type LangChainSystemContent = string | MessageContent;
 
-export type LangChainThreadManagerHooks = ThreadManagerHooks<StoredMessage, BaseMessage>;
+export type LangChainThreadManagerHooks = ThreadManagerHooks<
+  StoredMessage,
+  BaseMessage
+>;
 
 export interface LangChainThreadManagerConfig {
   redis: Redis;
@@ -36,11 +39,17 @@ export interface LangChainThreadManagerConfig {
 /** Prepared payload ready to send to a LangChain chat model */
 export interface LangChainInvocationPayload {
   messages: BaseMessage[];
+  /** Number of stored messages loaded from Redis before preparation. */
+  storedLength: number;
 }
 
 /** Thread manager with LangChain StoredMessage convenience helpers */
-export interface LangChainThreadManager
-  extends ProviderThreadManager<StoredMessage, LangChainContent, JsonValue, LangChainSystemContent> {
+export interface LangChainThreadManager extends ProviderThreadManager<
+  StoredMessage,
+  LangChainContent,
+  JsonValue,
+  LangChainSystemContent
+> {
   appendAIMessage(id: string, content: string | MessageContent): Promise<void>;
   prepareForInvocation(): Promise<LangChainInvocationPayload>;
 }
@@ -63,7 +72,7 @@ function storedMessageId(msg: StoredMessage): string {
  * appending typed LangChain messages.
  */
 export function createLangChainThreadManager(
-  config: LangChainThreadManagerConfig,
+  config: LangChainThreadManagerConfig
 ): LangChainThreadManager {
   const baseConfig: ThreadManagerConfig<StoredMessage> = {
     redis: config.redis,
@@ -77,7 +86,7 @@ export function createLangChainThreadManager(
   const helpers: Omit<LangChainThreadManager, keyof typeof base> = {
     async appendUserMessage(
       id: string,
-      content: LangChainContent,
+      content: LangChainContent
     ): Promise<void> {
       await base.append([
         new HumanMessage({ id, content: content as MessageContent }).toDict(),
@@ -86,7 +95,7 @@ export function createLangChainThreadManager(
 
     async appendSystemMessage(
       id: string,
-      content: LangChainSystemContent,
+      content: LangChainSystemContent
     ): Promise<void> {
       await base.initialize();
       await base.append([
@@ -99,7 +108,7 @@ export function createLangChainThreadManager(
 
     async appendAIMessage(
       id: string,
-      content: string | MessageContent,
+      content: string | MessageContent
     ): Promise<void> {
       await base.append([
         new AIMessage({ id, content: content as MessageContent }).toDict(),
@@ -110,10 +119,14 @@ export function createLangChainThreadManager(
       id: string,
       _toolCallId: string,
       _toolName: string,
-      content: JsonValue,
+      content: JsonValue
     ): Promise<void> {
       await base.append([
-        new ToolMessage({ id, content: content as MessageContent, tool_call_id: _toolCallId }).toDict(),
+        new ToolMessage({
+          id,
+          content: content as MessageContent,
+          tool_call_id: _toolCallId,
+        }).toDict(),
       ]);
     },
 
@@ -128,6 +141,7 @@ export function createLangChainThreadManager(
         messages: onPreparedMessage
           ? messages.map((msg, i) => onPreparedMessage(msg, i, messages))
           : messages,
+        storedLength: stored.length,
       };
     },
   };

package/src/index.ts

@@ -58,7 +58,10 @@ export type { AgentStateContext } from "./lib/activity";
 
 // Sandbox (activity-side: manager + Node.js filesystem adapter)
 export { SandboxManager } from "./lib/sandbox/manager";
-export type { SandboxManagerHooks, PreCreateHookResult } from "./lib/sandbox/manager";
+export type {
+  SandboxManagerHooks,
+  PreCreateHookResult,
+} from "./lib/sandbox/manager";
 export { NodeFsSandboxFileSystem } from "./lib/sandbox/node-fs";
 
 // Virtual filesystem (activity-side)

package/src/lib/activity.ts

@@ -59,10 +59,13 @@ export async function queryParentWorkflowState<T>(
  * };
  * ```
  */
-export function createRunAgentActivity<R, S extends BaseAgentState = BaseAgentState>(
+export function createRunAgentActivity<
+  R,
+  S extends BaseAgentState = BaseAgentState,
+>(
   client: WorkflowClient,
   handler: (config: RunAgentConfig & { state: S }) => Promise<R>,
-  scope: string,
+  scope: string
 ): Record<string, (config: RunAgentConfig) => Promise<R>> {
   const name = `run${scope.charAt(0).toUpperCase()}${scope.slice(1)}`;
   return {
@@ -76,7 +79,9 @@ export function createRunAgentActivity<R, S extends BaseAgentState = BaseAgentSt
 /**
  * Context injected into tool handlers created via {@link withParentWorkflowState}.
  */
-export interface AgentStateContext<S extends BaseAgentState = BaseAgentState> extends RouterContext {
+export interface AgentStateContext<
+  S extends BaseAgentState = BaseAgentState,
+> extends RouterContext {
   state: S;
 }
 
@@ -101,12 +106,17 @@ export interface AgentStateContext<S extends BaseAgentState = BaseAgentState> ex
  * );
  * ```
  */
-export function withParentWorkflowState<TArgs, TResult, S extends BaseAgentState = BaseAgentState, TToolResponse = JsonValue>(
+export function withParentWorkflowState<
+  TArgs,
+  TResult,
+  S extends BaseAgentState = BaseAgentState,
+  TToolResponse = JsonValue,
+>(
   client: WorkflowClient,
   handler: (
     args: TArgs,
-    context: AgentStateContext<S>,
-  ) => Promise<ToolHandlerResponse<TResult, TToolResponse>>,
+    context: AgentStateContext<S>
+  ) => Promise<ToolHandlerResponse<TResult, TToolResponse>>
 ): ActivityToolHandler<TArgs, TResult, RouterContext, TToolResponse> {
   return async (args, context) => {
     const state = await queryParentWorkflowState<S>(client);

package/src/lib/hooks/types.ts

@@ -1,8 +1,5 @@
 import type { SessionExitReason } from "../types";
-import type {
-  ToolMap,
-  ToolRouterHooks,
-} from "../tool-router/types";
+import type { ToolMap, ToolRouterHooks } from "../tool-router/types";
 
 // ============================================================================
 // Session Lifecycle Hooks
@@ -85,8 +82,11 @@ export type PostHumanMessageAppendHook<TContent = unknown> = (
  * (consumed by the router) with session/message lifecycle hooks
  * (consumed directly by the session).
  */
-export interface Hooks<T extends ToolMap, TResult = unknown, TContent = unknown>
-  extends ToolRouterHooks<T, TResult> {
+export interface Hooks<
+  T extends ToolMap,
+  TResult = unknown,
+  TContent = unknown,
+> extends ToolRouterHooks<T, TResult> {
   /** Called before each human message is appended to the thread */
   onPreHumanMessageAppend?: PreHumanMessageAppendHook<TContent>;
   /** Called after each human message is appended to the thread */

package/src/lib/lifecycle.ts

@@ -19,6 +19,8 @@ export type ThreadInit =
 // Sandbox lifecycle
 // ============================================================================
 
+import type { SandboxCreateOptions, SandboxSnapshot } from "./sandbox/types";
+
 /**
  * Sandbox initialization strategy.
  *
@@ -29,14 +31,24 @@ export type ThreadInit =
  *   Paused sandboxes are automatically resumed. The shutdown policy applies
  *   on exit.
  * - `"fork"` — fork from an existing (or paused) sandbox; a new sandbox is
- *   created and owned by this session.
+ *   created and owned by this session. `options` is an optional per-call
+ *   override merged on top of the provider's static defaults.
+ * - `"from-snapshot"` — restore a fresh sandbox from a previously captured
+ *   {@link SandboxSnapshot}. The new sandbox is owned by this session.
+ *   `options` is an optional per-call override merged on top of the
+ *   provider's static defaults.
  * - `"inherit"` — use a sandbox owned by someone else (e.g. a parent agent).
  *   The session will **not** manage its lifecycle on exit.
  */
 export type SandboxInit =
   | { mode: "new"; ctx?: unknown }
   | { mode: "continue"; sandboxId: string }
-  | { mode: "fork"; sandboxId: string }
+  | { mode: "fork"; sandboxId: string; options?: SandboxCreateOptions }
+  | {
+      mode: "from-snapshot";
+      snapshot: SandboxSnapshot;
+      options?: SandboxCreateOptions;
+    }
   | {
       mode: "inherit";
       sandboxId: string;
@@ -48,8 +60,11 @@ export type SandboxInit =
  * - `"destroy"` — tear down the sandbox entirely.
  * - `"pause"` — pause the sandbox so it can be resumed later.
  * - `"keep"` — leave the sandbox running (no-op on exit).
+ * - `"snapshot"` — capture a snapshot then destroy the sandbox. The snapshot
+ *   is surfaced on the session result so the caller can reuse it to spawn
+ *   future sandboxes.
  */
-export type SandboxShutdown = "destroy" | "pause" | "keep";
+export type SandboxShutdown = "destroy" | "pause" | "keep" | "snapshot";
 
 /**
  * Extended shutdown options available to subagent workflows.

package/src/lib/model/proxy.ts

@@ -29,7 +29,7 @@ import type { RunAgentConfig } from "../types";
 
 export function proxyRunAgent<M = unknown>(
   scope?: string,
-  options?: Parameters<typeof proxyActivities>[0],
+  options?: Parameters<typeof proxyActivities>[0]
 ): (config: RunAgentConfig) => Promise<AgentResponse<M>> {
   const resolvedScope = scope ?? workflowInfo().workflowType;
   const name = `run${resolvedScope.charAt(0).toUpperCase()}${resolvedScope.slice(1)}`;
@@ -44,7 +44,7 @@ export function proxyRunAgent<M = unknown>(
         maximumInterval: "2m",
         backoffCoefficient: 3,
       },
-    },
+    }
   );
   return acts[name] as (config: RunAgentConfig) => Promise<AgentResponse<M>>;
 }