zeitlich 0.2.44 → 0.2.46

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeitlich",
-  "version": "0.2.44",
+  "version": "0.2.46",
   "description": "[EXPERIMENTAL] An opinionated AI agent implementation for Temporal",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -201,6 +201,7 @@
   },
   "devDependencies": {
     "@anthropic-ai/sdk": "^0.93.0",
+    "@aws-sdk/client-s3": "^3.1000.0",
     "@daytonaio/sdk": "^0.171.0",
     "@e2b/code-interpreter": "^2.3.3",
     "@eslint/js": "^10.0.1",
@@ -223,6 +224,7 @@
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": ">=0.50.0",
+    "@aws-sdk/client-s3": ">=3.700.0",
     "@daytonaio/sdk": ">=0.153.0",
     "@e2b/code-interpreter": "^2.3.3",
     "@google/genai": "^1.43.0",
@@ -241,6 +243,9 @@
     "@anthropic-ai/sdk": {
       "optional": true
     },
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
     "@google/genai": {
       "optional": true
     },

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

@@ -13,11 +13,15 @@ import type {
   ScopedPrefix,
 } from "../../../lib/session/types";
 import type { ModelInvoker } from "../../../lib/model";
+import { createTieredThreadManager } from "../../../lib/thread/tiered";
+import type { ColdThreadStore } from "../../../lib/thread/cold-store";
 import {
   createAnthropicThreadManager,
+  storedMessageId,
   type AnthropicContent,
   type AnthropicSystemContent,
   type AnthropicThreadManagerHooks,
+  type StoredMessage,
 } from "./thread-manager";
 import {
   createAnthropicModelInvoker,
@@ -38,6 +42,20 @@ export interface AnthropicAdapterConfig {
   /** Maximum tokens to generate. Defaults to 16384. */
   maxTokens?: number;
   hooks?: AnthropicThreadManagerHooks;
+  /**
+   * Optional durable cold tier (e.g. S3, R2, GCS). When provided,
+   * the session will hydrate the thread from cold storage on entry
+   * (`continue`/`fork` modes) and flush it back on every exit path.
+   * When omitted, the adapter is Redis-only and `hydrateThread`/
+   * `flushThread` activities are no-ops.
+   */
+  coldStore?: ColdThreadStore;
+  /**
+   * Override the default Redis TTL (90 days) for thread keys. When
+   * pairing the adapter with a `coldStore`, a shorter TTL (hours)
+   * is typically more appropriate.
+   */
+  ttlSeconds?: number;
 }
 
 /**
@@ -135,16 +153,41 @@ export function createAnthropicAdapter(
 ): AnthropicAdapter {
   const { redis, client } = config;
 
+  /**
+   * Common per-call config plumbed into both the provider thread
+   * manager (for message I/O) and the tiered base manager (for
+   * hot↔cold lifecycle ops). Keeping them in lockstep means a single
+   * `coldStore` / `ttlSeconds` configuration controls every Redis
+   * write the adapter does.
+   */
+  const baseExtras = {
+    ...(config.ttlSeconds !== undefined && { ttlSeconds: config.ttlSeconds }),
+  };
+
+  const makeProviderThread = (threadId: string, threadKey?: string) =>
+    createAnthropicThreadManager({
+      redis,
+      threadId,
+      key: threadKey,
+      ...baseExtras,
+    });
+
+  const makeTieredBase = (threadId: string, threadKey?: string) =>
+    createTieredThreadManager<StoredMessage>({
+      redis,
+      threadId,
+      key: threadKey,
+      idOf: storedMessageId,
+      ...baseExtras,
+      ...(config.coldStore && { coldStore: config.coldStore }),
+    });
+
   const threadOps: ThreadOps<AnthropicContent> = {
     async initializeThread(
       threadId: string,
       threadKey?: string
     ): Promise<void> {
-      const thread = createAnthropicThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.initialize();
     },
 
@@ -154,11 +197,7 @@ export function createAnthropicAdapter(
       content: AnthropicContent,
       threadKey?: string
     ): Promise<void> {
-      const thread = createAnthropicThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.appendUserMessage(id, content);
     },
 
@@ -168,21 +207,13 @@ export function createAnthropicAdapter(
       content: AnthropicSystemContent,
       threadKey?: string
     ): Promise<void> {
-      const thread = createAnthropicThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.appendSystemMessage(id, content);
     },
 
     async appendToolResult(id: string, cfg: ToolResultConfig): Promise<void> {
       const { threadId, threadKey, toolCallId, toolName, content } = cfg;
-      const thread = createAnthropicThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.appendToolResult(id, toolCallId, toolName, content);
     },
 
@@ -192,11 +223,7 @@ export function createAnthropicAdapter(
       message: Anthropic.Messages.Message,
       threadKey?: string
     ): Promise<void> {
-      const thread = createAnthropicThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.appendAssistantMessage(id, message.content);
     },
 
@@ -210,6 +237,7 @@ export function createAnthropicAdapter(
         threadId: sourceThreadId,
         key: threadKey,
         hooks: config.hooks,
+        ...baseExtras,
       });
       await thread.fork(targetThreadId);
     },
@@ -219,7 +247,7 @@ export function createAnthropicAdapter(
       messageId: string,
       threadKey?: string,
     ): Promise<void> {
-      const thread = createAnthropicThreadManager({ redis, threadId, key: threadKey });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.truncateFromId(messageId);
     },
 
@@ -227,11 +255,7 @@ export function createAnthropicAdapter(
       threadId: string,
       threadKey?: string
     ): Promise<PersistedThreadState | null> {
-      const thread = createAnthropicThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       return thread.loadState();
     },
 
@@ -240,13 +264,25 @@ export function createAnthropicAdapter(
       state: PersistedThreadState,
       threadKey?: string
     ): Promise<void> {
-      const thread = createAnthropicThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.saveState(state);
     },
+
+    async hydrateThread(
+      threadId: string,
+      threadKey?: string
+    ): Promise<void> {
+      if (!config.coldStore) return;
+      await makeTieredBase(threadId, threadKey).hydrate();
+    },
+
+    async flushThread(
+      threadId: string,
+      threadKey?: string
+    ): Promise<void> {
+      if (!config.coldStore) return;
+      await makeTieredBase(threadId, threadKey).flush();
+    },
   };
 
   function createActivities<S extends string = "">(

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

@@ -35,6 +35,12 @@ export interface AnthropicThreadManagerConfig {
   /** Thread key, defaults to 'messages' */
   key?: string;
   hooks?: AnthropicThreadManagerHooks;
+  /**
+   * Override the default thread TTL (90 days). When pairing the
+   * adapter with a durable cold tier, a shorter TTL (hours) is
+   * typically more appropriate.
+   */
+  ttlSeconds?: number;
 }
 
 /** Prepared payload ready to send to the Anthropic API */
@@ -57,7 +63,8 @@ export interface AnthropicThreadManager extends ProviderThreadManager<
   prepareForInvocation(): Promise<AnthropicInvocationPayload>;
 }
 
-function storedMessageId(msg: StoredMessage): string {
+/** Extract the unique id from a {@link StoredMessage}. */
+export function storedMessageId(msg: StoredMessage): string {
   return msg.id;
 }
 
@@ -113,6 +120,7 @@ export function createAnthropicThreadManager(
     threadId: config.threadId,
     key: config.key,
     idOf: storedMessageId,
+    ...(config.ttlSeconds !== undefined && { ttlSeconds: config.ttlSeconds }),
   };
 
   const base = createThreadManager(baseConfig);

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

@@ -13,11 +13,15 @@ import type {
   ScopedPrefix,
 } from "../../../lib/session/types";
 import type { ModelInvoker } from "../../../lib/model";
+import { createTieredThreadManager } from "../../../lib/thread/tiered";
+import type { ColdThreadStore } from "../../../lib/thread/cold-store";
 import {
   createGoogleGenAIThreadManager,
+  storedContentId,
   type GoogleGenAIContent,
   type GoogleGenAISystemContent,
   type GoogleGenAIThreadManagerHooks,
+  type StoredContent,
 } from "./thread-manager";
 import { createGoogleGenAIModelInvoker } from "./model-invoker";
 import { ADAPTER_ID } from "./adapter-id";
@@ -34,6 +38,19 @@ export interface GoogleGenAIAdapterConfig {
   /** Default model name (e.g. 'gemini-2.5-flash'). If omitted, use `createModelInvoker()` */
   model?: string;
   hooks?: GoogleGenAIThreadManagerHooks;
+  /**
+   * Optional durable cold tier (e.g. S3, R2, GCS). When provided,
+   * the session hydrates the thread on entry (`continue`/`fork`) and
+   * flushes it on every exit path. When omitted, the adapter is
+   * Redis-only and `hydrateThread`/`flushThread` activities are no-ops.
+   */
+  coldStore?: ColdThreadStore;
+  /**
+   * Override the default Redis TTL (90 days). When pairing the
+   * adapter with a `coldStore`, a shorter TTL (hours) is typically
+   * more appropriate.
+   */
+  ttlSeconds?: number;
 }
 
 /**
@@ -140,16 +157,34 @@ export function createGoogleGenAIAdapter(
 ): GoogleGenAIAdapter {
   const { redis } = config;
 
+  const baseExtras = {
+    ...(config.ttlSeconds !== undefined && { ttlSeconds: config.ttlSeconds }),
+  };
+
+  const makeProviderThread = (threadId: string, threadKey?: string) =>
+    createGoogleGenAIThreadManager({
+      redis,
+      threadId,
+      key: threadKey,
+      ...baseExtras,
+    });
+
+  const makeTieredBase = (threadId: string, threadKey?: string) =>
+    createTieredThreadManager<StoredContent>({
+      redis,
+      threadId,
+      key: threadKey,
+      idOf: storedContentId,
+      ...baseExtras,
+      ...(config.coldStore && { coldStore: config.coldStore }),
+    });
+
   const threadOps: ThreadOps<GoogleGenAIContent> = {
     async initializeThread(
       threadId: string,
       threadKey?: string
     ): Promise<void> {
-      const thread = createGoogleGenAIThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.initialize();
     },
 
@@ -159,11 +194,7 @@ export function createGoogleGenAIAdapter(
       content: GoogleGenAIContent,
       threadKey?: string
     ): Promise<void> {
-      const thread = createGoogleGenAIThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.appendUserMessage(id, content);
     },
 
@@ -173,21 +204,13 @@ export function createGoogleGenAIAdapter(
       content: GoogleGenAISystemContent,
       threadKey?: string
     ): Promise<void> {
-      const thread = createGoogleGenAIThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.appendSystemMessage(id, content);
     },
 
     async appendToolResult(id: string, cfg: ToolResultConfig): Promise<void> {
       const { threadId, threadKey, toolCallId, toolName, content } = cfg;
-      const thread = createGoogleGenAIThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.appendToolResult(
         id,
         toolCallId,
@@ -202,11 +225,7 @@ export function createGoogleGenAIAdapter(
       message: Content,
       threadKey?: string
     ): Promise<void> {
-      const thread = createGoogleGenAIThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.appendModelContent(id, message.parts ?? []);
     },
 
@@ -220,6 +239,7 @@ export function createGoogleGenAIAdapter(
         threadId: sourceThreadId,
         key: threadKey,
         hooks: config.hooks,
+        ...baseExtras,
       });
       await thread.fork(targetThreadId);
     },
@@ -229,11 +249,7 @@ export function createGoogleGenAIAdapter(
       messageId: string,
       threadKey?: string,
     ): Promise<void> {
-      const thread = createGoogleGenAIThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.truncateFromId(messageId);
     },
 
@@ -241,11 +257,7 @@ export function createGoogleGenAIAdapter(
       threadId: string,
       threadKey?: string
     ): Promise<PersistedThreadState | null> {
-      const thread = createGoogleGenAIThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       return thread.loadState();
     },
 
@@ -254,13 +266,25 @@ export function createGoogleGenAIAdapter(
       state: PersistedThreadState,
       threadKey?: string
     ): Promise<void> {
-      const thread = createGoogleGenAIThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.saveState(state);
     },
+
+    async hydrateThread(
+      threadId: string,
+      threadKey?: string
+    ): Promise<void> {
+      if (!config.coldStore) return;
+      await makeTieredBase(threadId, threadKey).hydrate();
+    },
+
+    async flushThread(
+      threadId: string,
+      threadKey?: string
+    ): Promise<void> {
+      if (!config.coldStore) return;
+      await makeTieredBase(threadId, threadKey).flush();
+    },
   };
 
   function createActivities<S extends string = "">(

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

@@ -31,6 +31,12 @@ export interface GoogleGenAIThreadManagerConfig {
   /** Thread key, defaults to 'messages' */
   key?: string;
   hooks?: GoogleGenAIThreadManagerHooks;
+  /**
+   * Override the default thread TTL (90 days). When pairing the
+   * adapter with a durable cold tier, a shorter TTL (hours) is
+   * typically more appropriate.
+   */
+  ttlSeconds?: number;
 }
 
 /** Prepared payload ready to send to the Google GenAI API */
@@ -50,7 +56,8 @@ export interface GoogleGenAIThreadManager extends ProviderThreadManager<
   prepareForInvocation(): Promise<GoogleGenAIInvocationPayload>;
 }
 
-function storedContentId(msg: StoredContent): string {
+/** Extract the unique id from a {@link StoredContent}. */
+export function storedContentId(msg: StoredContent): string {
   return msg.id;
 }
 
@@ -103,6 +110,7 @@ export function createGoogleGenAIThreadManager(
     threadId: config.threadId,
     key: config.key,
     idOf: storedContentId,
+    ...(config.ttlSeconds !== undefined && { ttlSeconds: config.ttlSeconds }),
   };
 
   const base = createThreadManager(baseConfig);

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

@@ -13,10 +13,13 @@ import type {
   ScopedPrefix,
 } from "../../../lib/session/types";
 import type { ModelInvoker } from "../../../lib/model";
+import { createTieredThreadManager } from "../../../lib/thread/tiered";
+import type { ColdThreadStore } from "../../../lib/thread/cold-store";
 import type { StoredMessage } from "@langchain/core/messages";
 import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
 import {
   createLangChainThreadManager,
+  storedMessageId,
   type LangChainContent,
   type LangChainSystemContent,
   type LangChainThreadManagerHooks,
@@ -35,6 +38,19 @@ export interface LangChainAdapterConfig {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   model?: BaseChatModel<any>;
   hooks?: LangChainThreadManagerHooks;
+  /**
+   * Optional durable cold tier (e.g. S3, R2, GCS). When provided,
+   * the session hydrates the thread on entry (`continue`/`fork`) and
+   * flushes it on every exit path. When omitted, the adapter is
+   * Redis-only and `hydrateThread`/`flushThread` activities are no-ops.
+   */
+  coldStore?: ColdThreadStore;
+  /**
+   * Override the default Redis TTL (90 days). When pairing the
+   * adapter with a `coldStore`, a shorter TTL (hours) is typically
+   * more appropriate.
+   */
+  ttlSeconds?: number;
 }
 
 /**
@@ -117,16 +133,34 @@ export function createLangChainAdapter(
 ): LangChainAdapter {
   const { redis } = config;
 
+  const baseExtras = {
+    ...(config.ttlSeconds !== undefined && { ttlSeconds: config.ttlSeconds }),
+  };
+
+  const makeProviderThread = (threadId: string, threadKey?: string) =>
+    createLangChainThreadManager({
+      redis,
+      threadId,
+      key: threadKey,
+      ...baseExtras,
+    });
+
+  const makeTieredBase = (threadId: string, threadKey?: string) =>
+    createTieredThreadManager<StoredMessage>({
+      redis,
+      threadId,
+      key: threadKey,
+      idOf: storedMessageId,
+      ...baseExtras,
+      ...(config.coldStore && { coldStore: config.coldStore }),
+    });
+
   const threadOps: ThreadOps<LangChainContent> = {
     async initializeThread(
       threadId: string,
       threadKey?: string
     ): Promise<void> {
-      const thread = createLangChainThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.initialize();
     },
 
@@ -136,11 +170,7 @@ export function createLangChainAdapter(
       content: LangChainContent,
       threadKey?: string
     ): Promise<void> {
-      const thread = createLangChainThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.appendUserMessage(id, content);
     },
 
@@ -150,21 +180,13 @@ export function createLangChainAdapter(
       content: LangChainSystemContent,
       threadKey?: string
     ): Promise<void> {
-      const thread = createLangChainThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, 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 = makeProviderThread(threadId, threadKey);
       await thread.appendToolResult(id, toolCallId, "", content);
     },
 
@@ -174,11 +196,7 @@ export function createLangChainAdapter(
       message: StoredMessage,
       threadKey?: string
     ): Promise<void> {
-      const thread = createLangChainThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       const patched = { ...message, data: { ...message.data, id } };
       await thread.append([patched]);
     },
@@ -193,6 +211,7 @@ export function createLangChainAdapter(
         threadId: sourceThreadId,
         key: threadKey,
         hooks: config.hooks,
+        ...baseExtras,
       });
       await thread.fork(targetThreadId);
     },
@@ -202,7 +221,7 @@ export function createLangChainAdapter(
       messageId: string,
       threadKey?: string,
     ): Promise<void> {
-      const thread = createLangChainThreadManager({ redis, threadId, key: threadKey });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.truncateFromId(messageId);
     },
 
@@ -210,11 +229,7 @@ export function createLangChainAdapter(
       threadId: string,
       threadKey?: string
     ): Promise<PersistedThreadState | null> {
-      const thread = createLangChainThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       return thread.loadState();
     },
 
@@ -223,13 +238,25 @@ export function createLangChainAdapter(
       state: PersistedThreadState,
       threadKey?: string
     ): Promise<void> {
-      const thread = createLangChainThreadManager({
-        redis,
-        threadId,
-        key: threadKey,
-      });
+      const thread = makeProviderThread(threadId, threadKey);
       await thread.saveState(state);
     },
+
+    async hydrateThread(
+      threadId: string,
+      threadKey?: string
+    ): Promise<void> {
+      if (!config.coldStore) return;
+      await makeTieredBase(threadId, threadKey).hydrate();
+    },
+
+    async flushThread(
+      threadId: string,
+      threadKey?: string
+    ): Promise<void> {
+      if (!config.coldStore) return;
+      await makeTieredBase(threadId, threadKey).flush();
+    },
   };
 
   function createActivities<S extends string = "">(

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

@@ -34,6 +34,12 @@ export interface LangChainThreadManagerConfig {
   /** Thread key, defaults to 'messages' */
   key?: string;
   hooks?: LangChainThreadManagerHooks;
+  /**
+   * Override the default thread TTL (90 days). When pairing the
+   * adapter with a durable cold tier, a shorter TTL (hours) is
+   * typically more appropriate.
+   */
+  ttlSeconds?: number;
 }
 
 /** Prepared payload ready to send to a LangChain chat model */
@@ -52,7 +58,8 @@ export interface LangChainThreadManager extends ProviderThreadManager<
   prepareForInvocation(): Promise<LangChainInvocationPayload>;
 }
 
-function storedMessageId(msg: StoredMessage): string {
+/** Extract the unique id from a LangChain {@link StoredMessage}. */
+export function storedMessageId(msg: StoredMessage): string {
   if (msg.type === "tool" && msg.data.tool_call_id) {
     return msg.data.tool_call_id;
   }
@@ -77,6 +84,7 @@ export function createLangChainThreadManager(
     threadId: config.threadId,
     key: config.key,
     idOf: storedMessageId,
+    ...(config.ttlSeconds !== undefined && { ttlSeconds: config.ttlSeconds }),
   };
 
   const base = createThreadManager(baseConfig);