zeitlich 0.2.37 → 0.2.38

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeitlich",
-  "version": "0.2.37",
+  "version": "0.2.38",
   "description": "[EXPERIMENTAL] An opinionated AI agent implementation for Temporal",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -210,7 +210,7 @@
     "node": ">=18"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "^0.80.0",
+    "@anthropic-ai/sdk": "^0.81.0",
     "@aws-sdk/client-bedrock-agentcore": "^3.900.0",
     "@daytonaio/sdk": "^0.158.1",
     "@e2b/code-interpreter": "^2.3.3",

package/src/adapters/sandbox/bedrock/index.ts

@@ -239,15 +239,24 @@ export class BedrockSandboxProvider implements SandboxProvider<
     // Bedrock sandboxes don't support pause, so resume is a no-op
   }
 
-  async snapshot(_sandboxId: string): Promise<SandboxSnapshot> {
+  async snapshot(
+    _sandboxId: string,
+    _options?: BedrockSandboxCreateOptions
+  ): Promise<SandboxSnapshot> {
     throw new SandboxNotSupportedError("snapshot");
   }
 
-  async restore(_snapshot: SandboxSnapshot): Promise<never> {
+  async restore(
+    _snapshot: SandboxSnapshot,
+    _options?: BedrockSandboxCreateOptions
+  ): Promise<never> {
     throw new SandboxNotSupportedError("restore");
   }
 
-  async fork(_sandboxId: string): Promise<Sandbox> {
+  async fork(
+    _sandboxId: string,
+    _options?: BedrockSandboxCreateOptions
+  ): Promise<Sandbox> {
     throw new SandboxNotSupportedError("fork");
   }
 

package/src/adapters/sandbox/daytona/index.ts

@@ -149,17 +149,26 @@ export class DaytonaSandboxProvider implements SandboxProvider<
     // Daytona sandboxes don't support pause, so resume is a no-op
   }
 
-  async fork(_sandboxId: string): Promise<Sandbox> {
+  async fork(
+    _sandboxId: string,
+    _options?: DaytonaSandboxCreateOptions
+  ): Promise<Sandbox> {
     throw new Error("Not implemented");
   }
 
-  async snapshot(_sandboxId: string): Promise<SandboxSnapshot> {
+  async snapshot(
+    _sandboxId: string,
+    _options?: DaytonaSandboxCreateOptions
+  ): Promise<SandboxSnapshot> {
     throw new SandboxNotSupportedError(
       "snapshot (use Daytona's native snapshot API directly)"
     );
   }
 
-  async restore(_snapshot: SandboxSnapshot): Promise<never> {
+  async restore(
+    _snapshot: SandboxSnapshot,
+    _options?: DaytonaSandboxCreateOptions
+  ): Promise<never> {
     throw new SandboxNotSupportedError(
       "restore (use Daytona's native snapshot API directly)"
     );

package/src/adapters/sandbox/e2b/index.ts

@@ -76,11 +76,19 @@ export class E2bSandboxProvider implements SandboxProvider<
   private readonly defaultTemplate?: string;
   private readonly defaultWorkspaceBase: string;
   private readonly defaultTimeoutMs?: number;
+  private readonly defaultAllowInternetAccess?: boolean;
+  private readonly defaultNetwork?: E2bSandboxConfig["network"];
+  private readonly defaultMetadata?: E2bSandboxConfig["metadata"];
+  private readonly defaultLifecycle?: E2bSandboxConfig["lifecycle"];
 
   constructor(config?: E2bSandboxConfig) {
     this.defaultTemplate = config?.template;
     this.defaultWorkspaceBase = config?.workspaceBase ?? "/home/user";
     this.defaultTimeoutMs = config?.timeoutMs;
+    this.defaultAllowInternetAccess = config?.allowInternetAccess;
+    this.defaultNetwork = config?.network;
+    this.defaultMetadata = config?.metadata;
+    this.defaultLifecycle = config?.lifecycle;
   }
 
   async create(
@@ -142,7 +150,10 @@ export class E2bSandboxProvider implements SandboxProvider<
     await E2bSdkSandbox.connect(sandboxId);
   }
 
-  async snapshot(sandboxId: string): Promise<SandboxSnapshot> {
+  async snapshot(
+    sandboxId: string,
+    _options?: E2bSandboxCreateOptions
+  ): Promise<SandboxSnapshot> {
     const { snapshotId } = await E2bSdkSandbox.createSnapshot(sandboxId);
     return {
       sandboxId,
@@ -152,14 +163,18 @@ export class E2bSandboxProvider implements SandboxProvider<
     };
   }
 
-  async restore(snapshot: SandboxSnapshot): Promise<Sandbox> {
+  async restore(
+    snapshot: SandboxSnapshot,
+    options?: E2bSandboxCreateOptions
+  ): Promise<Sandbox> {
     const data = snapshot.data as { snapshotId?: string } | null;
     if (!data?.snapshotId) {
       throw new SandboxNotSupportedError(
         "restore: snapshot is missing snapshotId"
       );
     }
-    const sdkSandbox = await E2bSdkSandbox.create(data.snapshotId);
+    const sdkOpts = this.buildSdkCreateOpts(options);
+    const sdkSandbox = await E2bSdkSandbox.create(data.snapshotId, sdkOpts);
     return new E2bSandboxImpl(
       sdkSandbox.sandboxId,
       sdkSandbox,
@@ -177,9 +192,13 @@ export class E2bSandboxProvider implements SandboxProvider<
     }
   }
 
-  async fork(sandboxId: string): Promise<Sandbox> {
+  async fork(
+    sandboxId: string,
+    options?: E2bSandboxCreateOptions
+  ): Promise<Sandbox> {
     const { snapshotId } = await E2bSdkSandbox.createSnapshot(sandboxId);
-    const sdkSandbox = await E2bSdkSandbox.create(snapshotId);
+    const sdkOpts = this.buildSdkCreateOpts(options);
+    const sdkSandbox = await E2bSdkSandbox.create(snapshotId, sdkOpts);
     return new E2bSandboxImpl(
       sdkSandbox.sandboxId,
       sdkSandbox,
@@ -188,22 +207,25 @@ export class E2bSandboxProvider implements SandboxProvider<
   }
 
   private buildSdkCreateOpts(options?: E2bSandboxCreateOptions) {
+    const network = options?.network ?? this.defaultNetwork;
+    const lifecycle = options?.lifecycle ?? this.defaultLifecycle;
     return {
       envs: options?.env,
       timeoutMs: options?.timeoutMs ?? this.defaultTimeoutMs,
-      metadata: options?.metadata,
-      allowInternetAccess: options?.allowInternetAccess,
-      network: options?.network
+      metadata: options?.metadata ?? this.defaultMetadata,
+      allowInternetAccess:
+        options?.allowInternetAccess ?? this.defaultAllowInternetAccess,
+      network: network
         ? {
-            allowOut: options.network.allowOut,
-            denyOut: options.network.denyOut,
-            allowPublicTraffic: options.network.allowPublicTraffic,
+            allowOut: network.allowOut,
+            denyOut: network.denyOut,
+            allowPublicTraffic: network.allowPublicTraffic,
           }
         : undefined,
-      lifecycle: options?.lifecycle
+      lifecycle: lifecycle
         ? {
-            onTimeout: options.lifecycle.onTimeout,
-            autoResume: options.lifecycle.autoResume,
+            onTimeout: lifecycle.onTimeout,
+            autoResume: lifecycle.autoResume,
           }
         : undefined,
     };

package/src/adapters/sandbox/e2b/types.ts

@@ -6,6 +6,14 @@ import type { E2bSandboxFileSystem } from "./filesystem";
  */
 export type E2bSandbox = Sandbox & { fs: E2bSandboxFileSystem };
 
+/**
+ * Provider-level defaults for E2B sandboxes. Every lifecycle op
+ * (`create` / `restore` / `fork`) merges per-call options on top of these —
+ * per-call options win per-field. This is how E2B preserves sandbox-level
+ * config (network policy, metadata, lifecycle, timeout) across
+ * snapshot/restore and fork, since the E2B API treats those as pure
+ * create-time inputs that aren't carried in the snapshot blob.
+ */
 export interface E2bSandboxConfig {
   /** Sandbox template name or ID */
   template?: string;
@@ -13,6 +21,14 @@ export interface E2bSandboxConfig {
   workspaceBase?: string;
   /** Sandbox idle timeout in milliseconds */
   timeoutMs?: number;
+  /** Default outbound internet access policy */
+  allowInternetAccess?: boolean;
+  /** Default outbound network allow/deny rules */
+  network?: SandboxCreateOptions["network"];
+  /** Default metadata surfaced via provider list/query APIs */
+  metadata?: SandboxCreateOptions["metadata"];
+  /** Default sandbox timeout behaviour */
+  lifecycle?: SandboxCreateOptions["lifecycle"];
 }
 
 export interface E2bSandboxCreateOptions extends SandboxCreateOptions {

package/src/adapters/sandbox/inmemory/index.ts

@@ -183,7 +183,10 @@ export class InMemorySandboxProvider implements SandboxProvider {
     return { sandbox };
   }
 
-  async snapshot(sandboxId: string): Promise<SandboxSnapshot> {
+  async snapshot(
+    sandboxId: string,
+    _options?: SandboxCreateOptions
+  ): Promise<SandboxSnapshot> {
     const sandbox = this.sandboxes.get(sandboxId);
     if (!sandbox) throw new SandboxNotFoundError(sandboxId);
 
@@ -210,7 +213,10 @@ export class InMemorySandboxProvider implements SandboxProvider {
     };
   }
 
-  async fork(sandboxId: string): Promise<Sandbox> {
+  async fork(
+    sandboxId: string,
+    _options?: SandboxCreateOptions
+  ): Promise<Sandbox> {
     const sandbox = await this.get(sandboxId);
 
     const entries = await sandbox.fs.readdirWithFileTypes("/");
@@ -228,7 +234,10 @@ export class InMemorySandboxProvider implements SandboxProvider {
     return newSandbox.sandbox;
   }
 
-  async restore(snapshot: SandboxSnapshot): Promise<Sandbox> {
+  async restore(
+    snapshot: SandboxSnapshot,
+    _options?: SandboxCreateOptions
+  ): Promise<Sandbox> {
     const { files } = snapshot.data as { files: Record<string, string> };
     const initialFiles: InitialFiles = {};
     for (const [path, content] of Object.entries(files)) {

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

@@ -212,6 +212,15 @@ export function createAnthropicAdapter(
       });
       await thread.fork(targetThreadId);
     },
+
+    async truncateThread(
+      threadId: string,
+      length: number,
+      threadKey?: string,
+    ): Promise<void> {
+      const thread = createAnthropicThreadManager({ redis, threadId, key: threadKey });
+      await thread.truncate(length);
+    },
   };
 
   function createActivities<S extends string = "">(

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

@@ -70,7 +70,8 @@ export function createAnthropicModelInvoker({
       key: threadKey,
       hooks,
     });
-    const { messages, system } = await thread.prepareForInvocation();
+    const { messages, system, storedLength } =
+      await thread.prepareForInvocation();
 
     const anthropicTools = toAnthropicTools(state.tools);
     const tools = anthropicTools.length > 0 ? anthropicTools : undefined;
@@ -110,6 +111,7 @@ export function createAnthropicModelInvoker({
           response.usage.cache_creation_input_tokens ?? undefined,
         cachedReadTokens: response.usage.cache_read_input_tokens ?? undefined,
       },
+      threadLengthAtCall: storedLength,
     };
   };
 }

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

@@ -41,6 +41,8 @@ export interface AnthropicThreadManagerConfig {
 export interface AnthropicInvocationPayload {
   messages: Anthropic.Messages.MessageParam[];
   system?: string | Anthropic.Messages.TextBlockParam[];
+  /** Number of stored messages loaded from Redis before preparation. */
+  storedLength: number;
 }
 
 /** Thread manager with Anthropic MessageParam convenience helpers */
@@ -220,6 +222,7 @@ export function createAnthropicThreadManager(
           ? messages.map((msg, i) => onPreparedMessage(msg, i, messages))
           : messages,
         ...(system ? { system } : {}),
+        storedLength: stored.length,
       };
     },
   };

package/src/adapters/thread/google-genai/activities.ts

@@ -222,6 +222,19 @@ export function createGoogleGenAIAdapter(
       });
       await thread.fork(targetThreadId);
     },
+
+    async truncateThread(
+      threadId: string,
+      length: number,
+      threadKey?: string,
+    ): Promise<void> {
+      const thread = createGoogleGenAIThreadManager({
+        redis,
+        threadId,
+        key: threadKey,
+      });
+      await thread.truncate(length);
+    },
   };
 
   function createActivities<S extends string = "">(

package/src/adapters/thread/google-genai/model-invoker.ts

@@ -73,7 +73,8 @@ export function createGoogleGenAIModelInvoker({
       key: threadKey,
       hooks,
     });
-    const { contents, systemInstruction } = await thread.prepareForInvocation();
+    const { contents, systemInstruction, storedLength } =
+      await thread.prepareForInvocation();
 
     const functionDeclarations = toFunctionDeclarations(state.tools);
     const tools =
@@ -116,6 +117,7 @@ export function createGoogleGenAIModelInvoker({
         outputTokens: lastChunk.usageMetadata?.candidatesTokenCount,
         cachedReadTokens: lastChunk.usageMetadata?.cachedContentTokenCount,
       },
+      threadLengthAtCall: storedLength,
     };
   };
 }

package/src/adapters/thread/google-genai/thread-manager.ts

@@ -37,6 +37,8 @@ export interface GoogleGenAIThreadManagerConfig {
 export interface GoogleGenAIInvocationPayload {
   contents: Content[];
   systemInstruction?: Part[];
+  /** Number of stored messages loaded from Redis before preparation. */
+  storedLength: number;
 }
 
 /** Thread manager with Google GenAI Content convenience helpers */
@@ -196,6 +198,7 @@ export function createGoogleGenAIThreadManager(
         ...(systemInstruction && systemInstruction.length > 0
           ? { systemInstruction }
           : {}),
+        storedLength: stored.length,
       };
     },
   };

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

@@ -195,6 +195,15 @@ 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 = "">(

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

@@ -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);

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

@@ -39,6 +39,8 @@ 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 */
@@ -139,6 +141,7 @@ export function createLangChainThreadManager(
         messages: onPreparedMessage
           ? messages.map((msg, i) => onPreparedMessage(msg, i, messages))
           : messages,
+        storedLength: stored.length,
       };
     },
   };

package/src/lib/lifecycle.ts

@@ -19,7 +19,7 @@ export type ThreadInit =
 // Sandbox lifecycle
 // ============================================================================
 
-import type { SandboxSnapshot } from "./sandbox/types";
+import type { SandboxCreateOptions, SandboxSnapshot } from "./sandbox/types";
 
 /**
  * Sandbox initialization strategy.
@@ -31,17 +31,24 @@ import type { SandboxSnapshot } from "./sandbox/types";
  *   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: "from-snapshot"; snapshot: SandboxSnapshot }
+  | { mode: "fork"; sandboxId: string; options?: SandboxCreateOptions }
+  | {
+      mode: "from-snapshot";
+      snapshot: SandboxSnapshot;
+      options?: SandboxCreateOptions;
+    }
   | {
       mode: "inherit";
       sandboxId: string;

package/src/lib/model/types.ts

@@ -8,6 +8,16 @@ export interface AgentResponse<M = unknown> {
   message: M;
   rawToolCalls: RawToolCall[];
   usage?: TokenUsage;
+  /**
+   * Number of stored messages in the thread at the moment the LLM was
+   * invoked — i.e. *before* the assistant message is appended. The
+   * session uses this as a rewind snapshot so it can roll the thread
+   * back to this exact state if a tool requests a rewind.
+   *
+   * Adapters compute this for free from the array of stored messages
+   * they load when preparing the payload.
+   */
+  threadLengthAtCall?: number;
 }
 
 /**

package/src/lib/sandbox/manager.ts

@@ -120,9 +120,7 @@ export class SandboxManager<
   async create(
     options?: TOptions,
     ctx?: TCtx
-  ): Promise<{
-    sandboxId: string;
-  } | null> {
+  ): Promise<{ sandboxId: string } | null> {
     let providerOptions = options;
 
     if (this.hooks.onPreCreate) {
@@ -175,12 +173,15 @@ export class SandboxManager<
     await this.provider.resume(id);
   }
 
-  async snapshot(id: string): Promise<SandboxSnapshot> {
-    return this.provider.snapshot(id);
+  async snapshot(id: string, options?: TOptions): Promise<SandboxSnapshot> {
+    return this.provider.snapshot(id, options);
   }
 
-  async restore(snapshot: SandboxSnapshot): Promise<string> {
-    const sandbox = await this.provider.restore(snapshot);
+  async restore(
+    snapshot: SandboxSnapshot,
+    options?: TOptions
+  ): Promise<string> {
+    const sandbox = await this.provider.restore(snapshot, options);
     return sandbox.id;
   }
 
@@ -188,8 +189,8 @@ export class SandboxManager<
     await this.provider.deleteSnapshot(snapshot);
   }
 
-  async fork(sandboxId: string): Promise<string> {
-    const sandbox = await this.provider.fork(sandboxId);
+  async fork(sandboxId: string, options?: TOptions): Promise<string> {
+    const sandbox = await this.provider.fork(sandboxId, options);
     return sandbox.id;
   }
 
@@ -221,9 +222,7 @@ export class SandboxManager<
       createSandbox: async (
         options?: TOptions,
         ctx?: TCtx
-      ): Promise<{
-        sandboxId: string;
-      } | null> => {
+      ): Promise<{ sandboxId: string } | null> => {
         return this.create(options, ctx);
       },
       destroySandbox: async (sandboxId: string): Promise<void> => {
@@ -238,19 +237,28 @@ export class SandboxManager<
       resumeSandbox: async (sandboxId: string): Promise<void> => {
         await this.resume(sandboxId);
       },
-      snapshotSandbox: async (sandboxId: string): Promise<SandboxSnapshot> => {
-        return this.snapshot(sandboxId);
+      snapshotSandbox: async (
+        sandboxId: string,
+        options?: TOptions
+      ): Promise<SandboxSnapshot> => {
+        return this.snapshot(sandboxId, options);
       },
-      restoreSandbox: async (snapshot: SandboxSnapshot): Promise<string> => {
-        return this.restore(snapshot);
+      restoreSandbox: async (
+        snapshot: SandboxSnapshot,
+        options?: TOptions
+      ): Promise<string> => {
+        return this.restore(snapshot, options);
       },
       deleteSandboxSnapshot: async (
         snapshot: SandboxSnapshot
       ): Promise<void> => {
         await this.deleteSnapshot(snapshot);
       },
-      forkSandbox: async (sandboxId: string): Promise<string> => {
-        return this.fork(sandboxId);
+      forkSandbox: async (
+        sandboxId: string,
+        options?: TOptions
+      ): Promise<string> => {
+        return this.fork(sandboxId, options);
       },
     };
     const cap = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1);

package/src/lib/sandbox/types.ts

@@ -158,11 +158,23 @@ export interface SandboxProvider<
   pause(sandboxId: string, ttlSeconds?: number): Promise<void>;
   /** Resume a paused sandbox. No-op if already running. */
   resume(sandboxId: string): Promise<void>;
-  snapshot(sandboxId: string): Promise<SandboxSnapshot>;
-  restore(snapshot: SandboxSnapshot): Promise<Sandbox>;
+  /**
+   * Capture a snapshot of a running sandbox. `options` is a per-call override
+   * merged on top of the provider's static defaults.
+   */
+  snapshot(sandboxId: string, options?: TOptions): Promise<SandboxSnapshot>;
+  /**
+   * Restore a sandbox from a snapshot. `options` is a per-call override
+   * merged on top of the provider's static defaults.
+   */
+  restore(snapshot: SandboxSnapshot, options?: TOptions): Promise<Sandbox>;
   /** Delete a previously captured snapshot. No-op if already deleted. */
   deleteSnapshot(snapshot: SandboxSnapshot): Promise<void>;
-  fork(sandboxId: string): Promise<Sandbox>;
+  /**
+   * Fork a running sandbox into a new one. `options` is a per-call override
+   * merged on top of the provider's static defaults.
+   */
+  fork(sandboxId: string, options?: TOptions): Promise<Sandbox>;
 }
 
 // ============================================================================
@@ -181,12 +193,20 @@ export interface SandboxOps<
   pauseSandbox(sandboxId: string): Promise<void>;
   /** Resume a paused sandbox. No-op if already running. */
   resumeSandbox(sandboxId: string): Promise<void>;
-  snapshotSandbox(sandboxId: string): Promise<SandboxSnapshot>;
-  /** Create a fresh sandbox from a previously captured snapshot. */
-  restoreSandbox(snapshot: SandboxSnapshot): Promise<string>;
+  /** Capture a snapshot. `options` is a per-call override merged on top of provider defaults. */
+  snapshotSandbox(
+    sandboxId: string,
+    options?: TOptions
+  ): Promise<SandboxSnapshot>;
+  /** Create a fresh sandbox from a snapshot. `options` is a per-call override merged on top of provider defaults. */
+  restoreSandbox(
+    snapshot: SandboxSnapshot,
+    options?: TOptions
+  ): Promise<string>;
   /** Delete a previously captured snapshot. No-op if already deleted. */
   deleteSandboxSnapshot(snapshot: SandboxSnapshot): Promise<void>;
-  forkSandbox(sandboxId: string): Promise<string>;
+  /** Fork a running sandbox. `options` is a per-call override merged on top of provider defaults. */
+  forkSandbox(sandboxId: string, options?: TOptions): Promise<string>;
 }
 
 /**