zeitlich 0.2.50 → 0.2.51

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

@@ -1,5 +1,10 @@
 import type { RedisClientType as Redis } from "redis";
-import type { GoogleGenAI, Content, Part } from "@google/genai";
+import type {
+  GoogleGenAI,
+  Content,
+  Part,
+  GenerateContentConfig,
+} from "@google/genai";
 import type { ToolResultConfig } from "../../../lib/types";
 import type { PersistedThreadState } from "../../../lib/state/types";
 import type {
@@ -23,7 +28,10 @@ import {
   type GoogleGenAIThreadManagerHooks,
   type StoredContent,
 } from "./thread-manager";
-import { createGoogleGenAIModelInvoker } from "./model-invoker";
+import {
+  createGoogleGenAIModelInvoker,
+  type GoogleGenAIModelInvokerConfig,
+} from "./model-invoker";
 import { ADAPTER_ID } from "./adapter-id";
 
 export type GoogleGenAIThreadOps<TScope extends string = ""> =
@@ -46,11 +54,22 @@ export interface GoogleGenAIAdapterConfig {
    */
   coldStore?: ColdThreadStore;
   /**
-   * Override the default Redis TTL (90 days). When pairing the
-   * adapter with a `coldStore`, a shorter TTL (hours) is typically
-   * more appropriate.
+   * Redis TTL for the thread's keys; defaults to 90 days. Use a shorter
+   * value (hours) with a cold tier.
    */
   ttlSeconds?: number;
+  /**
+   * Default generation config forwarded to every invoker the adapter
+   * builds (`invoker` and `createModelInvoker`). `systemInstruction`,
+   * `tools`, and `abortSignal` are managed by the invoker and override
+   * any values set here.
+   */
+  generationConfig?: GenerateContentConfig;
+  /**
+   * Default server-side context caching config forwarded to every
+   * invoker the adapter builds. See {@link createGoogleGenAIModelInvoker}.
+   */
+  cache?: GoogleGenAIModelInvokerConfig["cache"];
 }
 
 /**
@@ -145,7 +164,7 @@ export interface GoogleGenAIAdapter {
  *     ...createRunAgentActivity(temporalClient, adapter.invoker, "codingAgent"),
  *     ...createRunAgentActivity(
  *       temporalClient,
- *       adapter.createModelInvoker('gemini-2.5-pro'),
+ *       adapter.createModelInvoker('gemini-2.5-pro', client),
  *       "researchAgent",
  *     ),
  *   };
@@ -157,25 +176,26 @@ export function createGoogleGenAIAdapter(
 ): GoogleGenAIAdapter {
   const { redis } = config;
 
-  const baseExtras = {
+  // Single source for the adapter's `redis` handle and configured TTL, spread
+  // into every internal thread manager so all of them share one configuration.
+  const base = {
+    redis,
     ...(config.ttlSeconds !== undefined && { ttlSeconds: config.ttlSeconds }),
   };
 
   const makeProviderThread = (threadId: string, threadKey?: string) =>
     createGoogleGenAIThreadManager({
-      redis,
+      ...base,
       threadId,
       key: threadKey,
-      ...baseExtras,
     });
 
   const makeTieredBase = (threadId: string, threadKey?: string) =>
     createTieredThreadManager<StoredContent>({
-      redis,
+      ...base,
       threadId,
       key: threadKey,
       idOf: storedContentId,
-      ...baseExtras,
       ...(config.coldStore && { coldStore: config.coldStore }),
     });
 
@@ -235,11 +255,10 @@ export function createGoogleGenAIAdapter(
       threadKey?: string
     ): Promise<void> {
       const thread = createGoogleGenAIThreadManager({
-        redis,
+        ...base,
         threadId: sourceThreadId,
         key: threadKey,
         hooks: config.hooks,
-        ...baseExtras,
       });
       await thread.fork(targetThreadId);
     },
@@ -304,10 +323,14 @@ export function createGoogleGenAIAdapter(
     client: GoogleGenAI
   ): ModelInvoker<Content> =>
     createGoogleGenAIModelInvoker({
-      redis,
+      ...base,
       client,
       model,
       hooks: config.hooks,
+      ...(config.generationConfig !== undefined && {
+        config: config.generationConfig,
+      }),
+      ...(config.cache !== undefined && { cache: config.cache }),
     });
 
   const invoker: ModelInvoker<Content> =

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

@@ -8,6 +8,7 @@ import {
 import { createGoogleGenAIModelInvoker } from "./model-invoker";
 import type { StoredContent } from "./thread-manager";
 import type { AgentResponse } from "../../../lib/model";
+import { THREAD_TTL_SECONDS } from "../../../lib/thread/keys";
 
 const textReply: Part[] = [{ text: "ok" }];
 
@@ -17,7 +18,8 @@ function createMockRedis(
 ) {
   return {
     exists: vi.fn().mockResolvedValue(1),
-    lrange: vi.fn().mockResolvedValue(stored.map((m) => JSON.stringify(m))),
+    lRange: vi.fn().mockResolvedValue(stored.map((m) => JSON.stringify(m))),
+    lTrim: vi.fn().mockResolvedValue("OK"),
     get: vi
       .fn()
       .mockImplementation((key: string) =>
@@ -25,7 +27,7 @@ function createMockRedis(
       ),
     del: vi.fn().mockResolvedValue(1),
     set: vi.fn().mockResolvedValue("OK"),
-    rpush: vi.fn().mockResolvedValue(1),
+    rPush: vi.fn().mockResolvedValue(1),
     expire: vi.fn().mockResolvedValue(1),
     eval: vi.fn().mockResolvedValue(1),
   };
@@ -311,8 +313,7 @@ describe("Google GenAI model invoker — context caching", () => {
     );
     expect(setCall).toBeDefined();
     expect(setCall?.[1]).toBe("cached-content-ref");
-    expect(setCall?.[2]).toBe("EX");
-    expect(setCall?.[3]).toBe(595);
+    expect(setCall?.[2]).toEqual({ EX: 595 });
   });
 
   it("reports cachedWriteTokens from cache creation", async () => {
@@ -335,3 +336,51 @@ describe("Google GenAI model invoker — context caching", () => {
     expect(result.usage?.cachedWriteTokens).toBe(4200);
   });
 });
+
+describe("Google GenAI model invoker — thread TTL", () => {
+  // A thread whose tail is a prior attempt's assistant message stored
+  // under `assistant-1`, so the invoker's `truncateFromId(assistant-1)`
+  // trims it and re-stamps the surviving list key's TTL.
+  const retriedThread: StoredContent[] = [
+    { id: "msg-1", content: { role: "user", parts: [{ text: "hi" }] } },
+    {
+      id: "assistant-1",
+      content: { role: "model", parts: [{ text: "prior attempt" }] },
+    },
+  ];
+  const listKey = "messages:thread:thread-1";
+
+  it("re-stamps trimmed hot keys at the configured ttlSeconds", async () => {
+    const redis = createMockRedis(retriedThread);
+    const client = createMockClient();
+
+    const invoker = createGoogleGenAIModelInvoker({
+      redis: redis as never,
+      client: client as never,
+      model: "gemini-2.5-flash",
+      ttlSeconds: 3600,
+    });
+
+    await invoker(invokerConfig);
+
+    expect(redis.lTrim).toHaveBeenCalledWith(listKey, 0, 0);
+    expect(redis.expire).toHaveBeenCalledWith(listKey, 3600);
+    expect(redis.expire).not.toHaveBeenCalledWith(listKey, THREAD_TTL_SECONDS);
+  });
+
+  it("defaults to THREAD_TTL_SECONDS when ttlSeconds is omitted", async () => {
+    const redis = createMockRedis(retriedThread);
+    const client = createMockClient();
+
+    const invoker = createGoogleGenAIModelInvoker({
+      redis: redis as never,
+      client: client as never,
+      model: "gemini-2.5-flash",
+    });
+
+    await invoker(invokerConfig);
+
+    expect(redis.lTrim).toHaveBeenCalledWith(listKey, 0, 0);
+    expect(redis.expire).toHaveBeenCalledWith(listKey, THREAD_TTL_SECONDS);
+  });
+});

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

@@ -21,6 +21,12 @@ export interface GoogleGenAIModelInvokerConfig {
   client: GoogleGenAI;
   model: string;
   hooks?: GoogleGenAIThreadManagerHooks;
+  /**
+   * Redis TTL for the thread's keys; defaults to 90 days. Use a shorter
+   * value (hours) with a cold tier. Distinct from `cache.ttlSeconds`
+   * (server-side context caching).
+   */
+  ttlSeconds?: number;
   /** Passed through to `generateContentStream().config`.
    *  `systemInstruction`, `tools`, and `abortSignal` are managed by the
    *  invoker and will override any values set here. */
@@ -69,6 +75,7 @@ export function createGoogleGenAIModelInvoker({
   client,
   model,
   hooks,
+  ttlSeconds,
   config: generationConfig,
   cache: cacheConfig,
 }: GoogleGenAIModelInvokerConfig) {
@@ -83,6 +90,7 @@ export function createGoogleGenAIModelInvoker({
       threadId,
       key: threadKey,
       hooks,
+      ...(ttlSeconds !== undefined && { ttlSeconds }),
     });
     // Truncate the thread starting at the id the assistant message
     // will be stored under. No-op on the first attempt; on rewind
@@ -214,6 +222,7 @@ export async function invokeGoogleGenAIModel({
   client,
   model,
   hooks,
+  ttlSeconds,
   config,
   generationConfig,
   cache,
@@ -222,6 +231,7 @@ export async function invokeGoogleGenAIModel({
   client: GoogleGenAI;
   model: string;
   hooks?: GoogleGenAIThreadManagerHooks;
+  ttlSeconds?: number;
   config: ModelInvokerConfig;
   generationConfig?: GenerateContentConfig;
   cache?: GoogleGenAIModelInvokerConfig["cache"];
@@ -231,6 +241,7 @@ export async function invokeGoogleGenAIModel({
     client,
     model,
     hooks,
+    ...(ttlSeconds !== undefined && { ttlSeconds }),
     config: generationConfig,
     cache,
   });

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

@@ -32,9 +32,8 @@ export interface GoogleGenAIThreadManagerConfig {
   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.
+   * Redis TTL for the thread's keys; defaults to 90 days. Use a shorter
+   * value (hours) with a cold tier.
    */
   ttlSeconds?: number;
 }

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

@@ -0,0 +1,88 @@
+import { describe, expect, it, vi } from "vitest";
+import { AIMessage, HumanMessage } from "@langchain/core/messages";
+import { createLangChainAdapter } from "./activities";
+import { THREAD_TTL_SECONDS } from "../../../lib/thread/keys";
+
+function createMockRedis(stored: unknown[]) {
+  return {
+    exists: vi.fn().mockResolvedValue(1),
+    lRange: vi.fn().mockResolvedValue(stored.map((m) => JSON.stringify(m))),
+    lTrim: vi.fn().mockResolvedValue("OK"),
+    del: vi.fn().mockResolvedValue(1),
+    set: vi.fn().mockResolvedValue("OK"),
+    rPush: vi.fn().mockResolvedValue(1),
+    expire: vi.fn().mockResolvedValue(1),
+    eval: vi.fn().mockResolvedValue(1),
+  };
+}
+
+function createMockModel() {
+  const response = {
+    tool_calls: [],
+    response_metadata: {},
+    usage_metadata: { input_tokens: 1, output_tokens: 1 },
+    toDict: () => ({ type: "ai", data: { content: "ok" } }),
+  };
+  return { invoke: vi.fn().mockResolvedValue(response) };
+}
+
+// Tail stored under the `assistantMessageId`, so the invoker's
+// `truncateFromId` trims it and re-stamps the surviving list key's TTL.
+const retriedThread = [
+  new HumanMessage({ id: "msg-1", content: "hi" }).toDict(),
+  new AIMessage({ id: "assistant-1", content: "prior" }).toDict(),
+];
+const listKey = "messages:thread:thread-1";
+const metaKey = "messages:meta:thread:thread-1";
+const invokerCall = {
+  threadId: "thread-1",
+  assistantMessageId: "assistant-1",
+  state: { tools: [] } as never,
+  agentName: "TestAgent",
+};
+
+describe("createLangChainAdapter — TTL propagation", () => {
+  it("forwards adapter ttlSeconds to a created invoker's writes", async () => {
+    const redis = createMockRedis(retriedThread);
+    const model = createMockModel();
+    const adapter = createLangChainAdapter({
+      redis: redis as never,
+      ttlSeconds: 3600,
+    });
+
+    await adapter.createModelInvoker(model as never)(invokerCall);
+
+    expect(redis.expire).toHaveBeenCalledWith(listKey, 3600);
+    expect(redis.expire).not.toHaveBeenCalledWith(listKey, THREAD_TTL_SECONDS);
+  });
+
+  it("forwards adapter ttlSeconds to thread-op writes", async () => {
+    const redis = createMockRedis([]);
+    const adapter = createLangChainAdapter({
+      redis: redis as never,
+      ttlSeconds: 3600,
+    });
+    const acts = adapter.createActivities() as unknown as Record<
+      string,
+      (threadId: string, threadKey?: string) => Promise<void>
+    >;
+    const initialize = Object.entries(acts).find(([k]) =>
+      k.endsWith("InitializeThread")
+    )?.[1];
+    if (!initialize) throw new Error("initializeThread activity not found");
+
+    await initialize("thread-1");
+
+    expect(redis.set).toHaveBeenCalledWith(metaKey, "1", { EX: 3600 });
+  });
+
+  it("defaults to THREAD_TTL_SECONDS when adapter ttlSeconds is omitted", async () => {
+    const redis = createMockRedis(retriedThread);
+    const model = createMockModel();
+    const adapter = createLangChainAdapter({ redis: redis as never });
+
+    await adapter.createModelInvoker(model as never)(invokerCall);
+
+    expect(redis.expire).toHaveBeenCalledWith(listKey, THREAD_TTL_SECONDS);
+  });
+});

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

@@ -46,9 +46,8 @@ export interface LangChainAdapterConfig {
    */
   coldStore?: ColdThreadStore;
   /**
-   * Override the default Redis TTL (90 days). When pairing the
-   * adapter with a `coldStore`, a shorter TTL (hours) is typically
-   * more appropriate.
+   * Redis TTL for the thread's keys; defaults to 90 days. Use a shorter
+   * value (hours) with a cold tier.
    */
   ttlSeconds?: number;
 }
@@ -133,25 +132,26 @@ export function createLangChainAdapter(
 ): LangChainAdapter {
   const { redis } = config;
 
-  const baseExtras = {
+  // Single source for the adapter's `redis` handle and configured TTL, spread
+  // into every internal thread manager so all of them share one configuration.
+  const base = {
+    redis,
     ...(config.ttlSeconds !== undefined && { ttlSeconds: config.ttlSeconds }),
   };
 
   const makeProviderThread = (threadId: string, threadKey?: string) =>
     createLangChainThreadManager({
-      redis,
+      ...base,
       threadId,
       key: threadKey,
-      ...baseExtras,
     });
 
   const makeTieredBase = (threadId: string, threadKey?: string) =>
     createTieredThreadManager<StoredMessage>({
-      redis,
+      ...base,
       threadId,
       key: threadKey,
       idOf: storedMessageId,
-      ...baseExtras,
       ...(config.coldStore && { coldStore: config.coldStore }),
     });
 
@@ -207,11 +207,10 @@ export function createLangChainAdapter(
       threadKey?: string
     ): Promise<void> {
       const thread = createLangChainThreadManager({
-        redis,
+        ...base,
         threadId: sourceThreadId,
         key: threadKey,
         hooks: config.hooks,
-        ...baseExtras,
       });
       await thread.fork(targetThreadId);
     },
@@ -275,7 +274,11 @@ export function createLangChainAdapter(
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     model: BaseChatModel<any>
   ): ModelInvoker<StoredMessage> =>
-    createLangChainModelInvoker({ redis, model, hooks: config.hooks });
+    createLangChainModelInvoker({
+      ...base,
+      model,
+      hooks: config.hooks,
+    });
 
   const invoker: ModelInvoker<StoredMessage> = config.model
     ? makeInvoker(config.model)

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

@@ -0,0 +1,74 @@
+import { describe, expect, it, vi } from "vitest";
+import { AIMessage, HumanMessage } from "@langchain/core/messages";
+import { createLangChainModelInvoker } from "./model-invoker";
+import { THREAD_TTL_SECONDS } from "../../../lib/thread/keys";
+
+function createMockRedis(stored: unknown[]) {
+  return {
+    exists: vi.fn().mockResolvedValue(1),
+    lRange: vi.fn().mockResolvedValue(stored.map((m) => JSON.stringify(m))),
+    lTrim: vi.fn().mockResolvedValue("OK"),
+    del: vi.fn().mockResolvedValue(1),
+    set: vi.fn().mockResolvedValue("OK"),
+    rPush: vi.fn().mockResolvedValue(1),
+    expire: vi.fn().mockResolvedValue(1),
+    eval: vi.fn().mockResolvedValue(1),
+  };
+}
+
+function createMockModel() {
+  const response = {
+    tool_calls: [],
+    response_metadata: {},
+    usage_metadata: { input_tokens: 1, output_tokens: 1 },
+    toDict: () => ({ type: "ai", data: { content: "ok" } }),
+  };
+  return { invoke: vi.fn().mockResolvedValue(response) };
+}
+
+describe("createLangChainModelInvoker thread TTL", () => {
+  // The tail message is stored under `assistant-1`, so the invoker's
+  // `truncateFromId(assistant-1)` trims it and re-stamps the surviving
+  // list key's TTL.
+  const retriedThread = [
+    new HumanMessage({ id: "msg-1", content: "hi" }).toDict(),
+    new AIMessage({ id: "assistant-1", content: "prior" }).toDict(),
+  ];
+  const listKey = "messages:thread:thread-1";
+  const invokerConfig = {
+    threadId: "thread-1",
+    assistantMessageId: "assistant-1",
+    state: { tools: [] } as never,
+    agentName: "Agent",
+  };
+
+  it("re-stamps trimmed hot keys at the configured ttlSeconds", async () => {
+    const redis = createMockRedis(retriedThread);
+    const model = createMockModel();
+    const invoker = createLangChainModelInvoker({
+      redis: redis as never,
+      model: model as never,
+      ttlSeconds: 3600,
+    });
+
+    await invoker(invokerConfig);
+
+    expect(redis.lTrim).toHaveBeenCalledWith(listKey, 0, 0);
+    expect(redis.expire).toHaveBeenCalledWith(listKey, 3600);
+    expect(redis.expire).not.toHaveBeenCalledWith(listKey, THREAD_TTL_SECONDS);
+  });
+
+  it("defaults to THREAD_TTL_SECONDS when ttlSeconds is omitted", async () => {
+    const redis = createMockRedis(retriedThread);
+    const model = createMockModel();
+    const invoker = createLangChainModelInvoker({
+      redis: redis as never,
+      model: model as never,
+    });
+
+    await invoker(invokerConfig);
+
+    expect(redis.lTrim).toHaveBeenCalledWith(listKey, 0, 0);
+    expect(redis.expire).toHaveBeenCalledWith(listKey, THREAD_TTL_SECONDS);
+  });
+});

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

@@ -16,6 +16,11 @@ export interface LangChainModelInvokerConfig<
   redis: Redis;
   model: TModel;
   hooks?: LangChainThreadManagerHooks;
+  /**
+   * Redis TTL for the thread's keys; defaults to 90 days. Use a shorter
+   * value (hours) with a cold tier.
+   */
+  ttlSeconds?: number;
 }
 
 /**
@@ -43,7 +48,7 @@ export interface LangChainModelInvokerConfig<
  
 export function createLangChainModelInvoker<
   TModel extends BaseChatModel<any> = BaseChatModel<any>,
->({ redis, model, hooks }: LangChainModelInvokerConfig<TModel>) {
+>({ redis, model, hooks, ttlSeconds }: LangChainModelInvokerConfig<TModel>) {
   return async function invokeLangChainModel(
     config: ModelInvokerConfig
   ): Promise<AgentResponse<StoredMessage>> {
@@ -56,6 +61,7 @@ export function createLangChainModelInvoker<
       threadId,
       key: threadKey,
       hooks,
+      ...(ttlSeconds !== undefined && { ttlSeconds }),
     });
     const runId = uuidv4();
 
@@ -122,13 +128,20 @@ export async function invokeLangChainModel<
   redis,
   model,
   hooks,
+  ttlSeconds,
   config,
 }: {
   redis: Redis;
   config: ModelInvokerConfig;
   model: TModel;
   hooks?: LangChainThreadManagerHooks;
+  ttlSeconds?: number;
 }): Promise<AgentResponse<StoredMessage>> {
-  const invoker = createLangChainModelInvoker({ redis, model, hooks });
+  const invoker = createLangChainModelInvoker({
+    redis,
+    model,
+    hooks,
+    ...(ttlSeconds !== undefined && { ttlSeconds }),
+  });
   return invoker(config);
 }

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

@@ -35,9 +35,8 @@ export interface LangChainThreadManagerConfig {
   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.
+   * Redis TTL for the thread's keys; defaults to 90 days. Use a shorter
+   * value (hours) with a cold tier.
    */
   ttlSeconds?: number;
 }