zeitlich 0.2.45 → 0.2.47

package/src/adapters/thread/anthropic/prompt-cache.ts

@@ -0,0 +1,163 @@
+import type Anthropic from "@anthropic-ai/sdk";
+
+export interface AnthropicPromptCacheOptions {
+  /** TTL for the cache checkpoint. Defaults to 5m. */
+  ttl?: Anthropic.Messages.CacheControlEphemeral["ttl"];
+  /** Claude models support at most 4 cache breakpoints per request. */
+  maxBreakpoints?: number;
+}
+
+export type AnthropicPromptCacheConfig = boolean | AnthropicPromptCacheOptions;
+
+interface PromptCachePayload {
+  messages: Anthropic.Messages.MessageParam[];
+  system?: string | Anthropic.Messages.TextBlockParam[];
+  tools?: Anthropic.Messages.Tool[];
+}
+
+type CacheControl = Anthropic.Messages.CacheControlEphemeral;
+type CacheableRecord = Record<string, unknown> & {
+  cache_control?: CacheControl | null;
+};
+
+const DEFAULT_MAX_CACHE_BREAKPOINTS = 4;
+const UNCACHEABLE_BLOCK_TYPES = new Set(["thinking", "redacted_thinking"]);
+
+/**
+ * Resolve model-invoker prompt-cache config. Undefined means the default:
+ * enabled with an explicit 5 minute TTL.
+ */
+export function resolvePromptCacheOptions(
+  promptCache?: AnthropicPromptCacheConfig
+): AnthropicPromptCacheOptions | undefined {
+  if (promptCache === false) return undefined;
+  if (promptCache === true || promptCache === undefined) return {};
+  return promptCache;
+}
+
+/**
+ * Add an explicit `cache_control` marker to the final cacheable message block.
+ *
+ * This intentionally uses block-level cache control rather than Anthropic's
+ * top-level automatic `cache_control` field because Amazon Bedrock does not
+ * support the top-level form. The block-level shape is accepted by both the
+ * Anthropic Messages API and Bedrock InvokeModel for Anthropic Claude models.
+ */
+export function addPromptCacheControl<TPayload extends PromptCachePayload>(
+  payload: TPayload,
+  options: AnthropicPromptCacheOptions = {}
+): TPayload {
+  const maxBreakpoints =
+    options.maxBreakpoints ?? DEFAULT_MAX_CACHE_BREAKPOINTS;
+  if (maxBreakpoints <= 0) return payload;
+
+  if (countCacheControls(payload) >= maxBreakpoints) return payload;
+
+  const cacheControl: CacheControl = {
+    type: "ephemeral",
+    ttl: options.ttl ?? "5m",
+  };
+  const messages = addCacheControlToLastMessageBlock(
+    payload.messages,
+    cacheControl
+  );
+
+  if (messages === payload.messages) return payload;
+  return { ...payload, messages };
+}
+
+function addCacheControlToLastMessageBlock(
+  messages: Anthropic.Messages.MessageParam[],
+  cacheControl: CacheControl
+): Anthropic.Messages.MessageParam[] {
+  for (
+    let messageIndex = messages.length - 1;
+    messageIndex >= 0;
+    messageIndex--
+  ) {
+    const message = messages[messageIndex];
+    if (!message) continue;
+
+    if (typeof message.content === "string") {
+      if (message.content.length === 0) continue;
+      return replaceMessage(messages, messageIndex, {
+        ...message,
+        content: [
+          { type: "text", text: message.content, cache_control: cacheControl },
+        ],
+      });
+    }
+
+    if (!Array.isArray(message.content)) continue;
+
+    for (
+      let blockIndex = message.content.length - 1;
+      blockIndex >= 0;
+      blockIndex--
+    ) {
+      const block = message.content[blockIndex];
+      if (!isCacheableContentBlock(block)) continue;
+      if (hasCacheControl(block)) return messages;
+
+      const content = [...message.content];
+      content[blockIndex] = {
+        ...(block as Record<string, unknown>),
+        cache_control: cacheControl,
+      } as Anthropic.Messages.ContentBlockParam;
+      return replaceMessage(messages, messageIndex, { ...message, content });
+    }
+  }
+
+  return messages;
+}
+
+function replaceMessage(
+  messages: Anthropic.Messages.MessageParam[],
+  index: number,
+  message: Anthropic.Messages.MessageParam
+): Anthropic.Messages.MessageParam[] {
+  const next = [...messages];
+  next[index] = message;
+  return next;
+}
+
+function isCacheableContentBlock(
+  block: Anthropic.Messages.ContentBlockParam | undefined
+): block is Anthropic.Messages.ContentBlockParam & CacheableRecord {
+  if (!isRecord(block)) return false;
+  const type = typeof block.type === "string" ? block.type : undefined;
+  if (type && UNCACHEABLE_BLOCK_TYPES.has(type)) return false;
+  if (type === "text" && block.text === "") return false;
+  return true;
+}
+
+function countCacheControls(payload: PromptCachePayload): number {
+  let count = 0;
+
+  for (const tool of payload.tools ?? []) {
+    if (hasCacheControl(tool)) count++;
+  }
+
+  if (Array.isArray(payload.system)) {
+    for (const block of payload.system) {
+      if (hasCacheControl(block)) count++;
+    }
+  }
+
+  for (const message of payload.messages) {
+    if (!Array.isArray(message.content)) continue;
+    for (const block of message.content) {
+      if (hasCacheControl(block)) count++;
+    }
+  }
+
+  return count;
+}
+
+function hasCacheControl(value: unknown): value is CacheableRecord {
+  return isRecord(value) && value.cache_control != null;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

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

@@ -25,6 +25,7 @@ import { createThreadOpsProxy } from "../../../lib/thread/proxy";
 import { ADAPTER_ID } from "./adapter-id";
 
 export { ADAPTER_ID, type AdapterId } from "./adapter-id";
+export type { ThreadOpsProxyOptions } from "../../../lib/thread/proxy";
 
 export function proxyAnthropicThreadOps(
   scope?: 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/proxy.ts

@@ -25,6 +25,7 @@ import { createThreadOpsProxy } from "../../../lib/thread/proxy";
 import { ADAPTER_ID } from "./adapter-id";
 
 export { ADAPTER_ID, type AdapterId } from "./adapter-id";
+export type { ThreadOpsProxyOptions } from "../../../lib/thread/proxy";
 
 export function proxyGoogleGenAIThreadOps(
   scope?: 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/proxy.ts

@@ -25,6 +25,7 @@ import { createThreadOpsProxy } from "../../../lib/thread/proxy";
 import { ADAPTER_ID } from "./adapter-id";
 
 export { ADAPTER_ID, type AdapterId } from "./adapter-id";
+export type { ThreadOpsProxyOptions } from "../../../lib/thread/proxy";
 
 export function proxyLangChainThreadOps(
   scope?: 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);

package/src/index.ts

@@ -33,11 +33,30 @@ export * from "./workflow";
 export { FileSystemSkillProvider } from "./lib/skills/fs-provider";
 
 // Thread manager (generic, framework-agnostic)
-export { createThreadManager } from "./lib/thread";
+export {
+  createThreadManager,
+  createTieredThreadManager,
+  createS3ColdStore,
+  encodeSnapshot,
+  applySnapshot,
+  clearHotTier,
+  getThreadStateKey,
+  getThreadDedupKey,
+} from "./lib/thread";
 export type {
   BaseThreadManager,
   ProviderThreadManager,
   ThreadManagerConfig,
+  TieredThreadManager,
+  TieredThreadManagerConfig,
+  FlushOptions,
+  ColdThreadStore,
+  ThreadSnapshot,
+  S3LikeClient,
+  S3ColdStoreConfig,
+  EncodeSnapshotConfig,
+  ApplySnapshotConfig,
+  ClearHotTierConfig,
 } from "./lib/thread";
 
 // Model invoker contract (framework-agnostic)
@@ -74,7 +93,7 @@ export type { VirtualFsContext } from "./lib/virtual-fs/types";
 // Tool handlers (activity implementations)
 // Wrap sandbox handlers with withSandbox(manager, handler) at registration time
 export { bashHandler } from "./tools/bash/handler";
-export { editHandler } from "./tools/edit/handler";
+export { editHandler, multiEditHandler } from "./tools/edit/handler";
 export { globHandler } from "./tools/glob/handler";
 export { readFileHandler } from "./tools/read-file/handler";
 export { writeFileHandler } from "./tools/write-file/handler";