zeitlich 0.2.26 → 0.2.27

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

@@ -0,0 +1,137 @@
+import { describe, expect, it, vi } from "vitest";
+import type { StoredMessage } from "./thread-manager";
+import { createAnthropicThreadManager } from "./thread-manager";
+
+function createMockRedis(stored: StoredMessage[]) {
+  return {
+    exists: vi.fn().mockResolvedValue(1),
+    lrange: vi.fn().mockResolvedValue(stored.map((m) => JSON.stringify(m))),
+    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),
+  };
+}
+
+const systemMsg: StoredMessage = {
+  id: "sys-1",
+  message: { role: "user", content: "You are helpful." },
+  isSystem: true,
+};
+
+const userMsg: StoredMessage = {
+  id: "msg-1",
+  message: { role: "user", content: [{ type: "text", text: "Hello" }] },
+};
+
+const assistantMsg: StoredMessage = {
+  id: "msg-2",
+  message: { role: "assistant", content: [{ type: "text", text: "Hi there!" }] },
+};
+
+describe("Anthropic thread manager hooks", () => {
+  describe("onPrepareMessage", () => {
+    it("transforms stored messages before system extraction and merge", async () => {
+      const hook = vi.fn((msg: StoredMessage) => {
+        if (msg.isSystem) return msg;
+        const firstBlock = (msg.message.content as Array<{ text: string }>)[0];
+        return {
+          ...msg,
+          message: {
+            ...msg.message,
+            content: [{ type: "text" as const, text: `[modified] ${firstBlock?.text}` }],
+          },
+        };
+      });
+
+      const redis = createMockRedis([systemMsg, userMsg, assistantMsg]);
+      const tm = createAnthropicThreadManager({
+        redis: redis as never,
+        threadId: "t1",
+        hooks: { onPrepareMessage: hook },
+      });
+
+      const { messages, system } = await tm.prepareForInvocation();
+
+      expect(hook).toHaveBeenCalledTimes(3);
+      expect(hook).toHaveBeenCalledWith(systemMsg, 0, [systemMsg, userMsg, assistantMsg]);
+      expect(system).toBe("You are helpful.");
+      expect(messages[0]?.content).toEqual([{ type: "text", text: "[modified] Hello" }]);
+      expect(messages[1]?.content).toEqual([{ type: "text", text: "[modified] Hi there!" }]);
+    });
+
+    it("is not called when not configured", async () => {
+      const redis = createMockRedis([userMsg]);
+      const tm = createAnthropicThreadManager({
+        redis: redis as never,
+        threadId: "t1",
+      });
+
+      const { messages } = await tm.prepareForInvocation();
+      expect(messages).toHaveLength(1);
+    });
+  });
+
+  describe("onPreparedMessage", () => {
+    it("transforms SDK-native messages after merge", async () => {
+      const hook = vi.fn((msg) => ({
+        ...msg,
+        content: [{ type: "text" as const, text: "[post] done" }],
+      }));
+
+      const redis = createMockRedis([userMsg, assistantMsg]);
+      const tm = createAnthropicThreadManager({
+        redis: redis as never,
+        threadId: "t1",
+        hooks: { onPreparedMessage: hook },
+      });
+
+      const { messages } = await tm.prepareForInvocation();
+
+      expect(hook).toHaveBeenCalledTimes(2);
+      expect(messages[0]?.content).toEqual([{ type: "text", text: "[post] done" }]);
+    });
+
+    it("receives the full prepared messages array", async () => {
+      const hook = vi.fn((msg) => msg);
+
+      const redis = createMockRedis([userMsg, assistantMsg]);
+      const tm = createAnthropicThreadManager({
+        redis: redis as never,
+        threadId: "t1",
+        hooks: { onPreparedMessage: hook },
+      });
+
+      await tm.prepareForInvocation();
+
+      const args = hook.mock.calls[0] as unknown as [unknown, number, unknown[]];
+      expect(args[2]).toHaveLength(2);
+    });
+  });
+
+  describe("both hooks combined", () => {
+    it("runs onPrepareMessage before onPreparedMessage", async () => {
+      const order: string[] = [];
+
+      const redis = createMockRedis([userMsg]);
+      const tm = createAnthropicThreadManager({
+        redis: redis as never,
+        threadId: "t1",
+        hooks: {
+          onPrepareMessage: (msg) => {
+            order.push("pre");
+            return msg;
+          },
+          onPreparedMessage: (msg) => {
+            order.push("post");
+            return msg;
+          },
+        },
+      });
+
+      await tm.prepareForInvocation();
+      expect(order).toEqual(["pre", "post"]);
+    });
+  });
+});

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

@@ -5,6 +5,7 @@ import {
   createThreadManager,
   type ProviderThreadManager,
   type ThreadManagerConfig,
+  type ThreadManagerHooks,
 } from "../../../lib/thread";
 
 /** SDK-native content type for Anthropic human messages */
@@ -20,11 +21,14 @@ export interface StoredMessage {
   isSystem?: boolean;
 }
 
+export type AnthropicThreadManagerHooks = ThreadManagerHooks<StoredMessage, Anthropic.Messages.MessageParam>;
+
 export interface AnthropicThreadManagerConfig {
   redis: Redis;
   threadId: string;
   /** Thread key, defaults to 'messages' */
   key?: string;
+  hooks?: AnthropicThreadManagerHooks;
 }
 
 /** Prepared payload ready to send to the Anthropic API */
@@ -165,11 +169,15 @@ export function createAnthropicThreadManager(
 
     async prepareForInvocation(): Promise<AnthropicInvocationPayload> {
       const stored = await base.load();
+      const { onPrepareMessage, onPreparedMessage } = config.hooks ?? {};
+      const mapped = onPrepareMessage
+        ? stored.map((msg, i) => onPrepareMessage(msg, i, stored))
+        : stored;
 
       let system: string | undefined;
       const conversationMessages: Anthropic.Messages.MessageParam[] = [];
 
-      for (const item of stored) {
+      for (const item of mapped) {
         if (item.isSystem) {
           system =
             typeof item.message.content === "string"
@@ -180,8 +188,11 @@ export function createAnthropicThreadManager(
         }
       }
 
+      const messages = mergeConsecutiveMessages(conversationMessages);
       return {
-        messages: mergeConsecutiveMessages(conversationMessages),
+        messages: onPreparedMessage
+          ? messages.map((msg, i) => onPreparedMessage(msg, i, messages))
+          : messages,
         ...(system ? { system } : {}),
       };
     },

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

@@ -15,6 +15,7 @@ import type { ModelInvoker } from "../../../lib/model";
 import {
   createGoogleGenAIThreadManager,
   type GoogleGenAIContent,
+  type GoogleGenAIThreadManagerHooks,
 } from "./thread-manager";
 import { createGoogleGenAIModelInvoker } from "./model-invoker";
 
@@ -31,6 +32,7 @@ export interface GoogleGenAIAdapterConfig {
   client?: GoogleGenAI;
   /** Default model name (e.g. 'gemini-2.5-flash'). If omitted, use `createModelInvoker()` */
   model?: string;
+  hooks?: GoogleGenAIThreadManagerHooks;
 }
 
 /**
@@ -222,7 +224,7 @@ export function createGoogleGenAIAdapter(
     model: string,
     client: GoogleGenAI
   ): ModelInvoker<Content> =>
-    createGoogleGenAIModelInvoker({ redis, client, model });
+    createGoogleGenAIModelInvoker({ redis, client, model, hooks: config.hooks });
 
   const invoker: ModelInvoker<Content> =
     config.model && config.client

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

@@ -2,13 +2,14 @@ import type Redis from "ioredis";
 import type { GoogleGenAI, Content, FunctionDeclaration } from "@google/genai";
 import type { SerializableToolDefinition } from "../../../lib/types";
 import type { AgentResponse, ModelInvokerConfig } from "../../../lib/model";
-import { createGoogleGenAIThreadManager } from "./thread-manager";
+import { createGoogleGenAIThreadManager, type GoogleGenAIThreadManagerHooks } from "./thread-manager";
 import { v4 as uuidv4 } from "uuid";
 
 export interface GoogleGenAIModelInvokerConfig {
   redis: Redis;
   client: GoogleGenAI;
   model: string;
+  hooks?: GoogleGenAIThreadManagerHooks;
 }
 
 function toFunctionDeclarations(
@@ -49,13 +50,14 @@ export function createGoogleGenAIModelInvoker({
   redis,
   client,
   model,
+  hooks,
 }: GoogleGenAIModelInvokerConfig) {
   return async function invokeGoogleGenAIModel(
     config: ModelInvokerConfig,
   ): Promise<AgentResponse<Content>> {
     const { threadId, threadKey, state } = config;
 
-    const thread = createGoogleGenAIThreadManager({ redis, threadId, key: threadKey });
+    const thread = createGoogleGenAIThreadManager({ redis, threadId, key: threadKey, hooks });
     const { contents, systemInstruction } =
       await thread.prepareForInvocation();
 
@@ -104,13 +106,15 @@ export async function invokeGoogleGenAIModel({
   redis,
   client,
   model,
+  hooks,
   config,
 }: {
   redis: Redis;
   client: GoogleGenAI;
   model: string;
+  hooks?: GoogleGenAIThreadManagerHooks;
   config: ModelInvokerConfig;
 }): Promise<AgentResponse<Content>> {
-  const invoker = createGoogleGenAIModelInvoker({ redis, client, model });
+  const invoker = createGoogleGenAIModelInvoker({ redis, client, model, hooks });
   return invoker(config);
 }

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

@@ -0,0 +1,159 @@
+import { describe, expect, it, vi } from "vitest";
+import type { Content } from "@google/genai";
+import type { StoredContent } from "./thread-manager";
+import { createGoogleGenAIThreadManager } from "./thread-manager";
+
+function createMockRedis(stored: StoredContent[]) {
+  return {
+    exists: vi.fn().mockResolvedValue(1),
+    lrange: vi.fn().mockResolvedValue(stored.map((m) => JSON.stringify(m))),
+    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),
+  };
+}
+
+const systemContent: StoredContent = {
+  id: "sys-1",
+  content: { role: "system", parts: [{ text: "You are helpful." }] },
+};
+
+const userContent: StoredContent = {
+  id: "msg-1",
+  content: { role: "user", parts: [{ text: "Hello" }] },
+};
+
+const modelContent: StoredContent = {
+  id: "msg-2",
+  content: { role: "model", parts: [{ text: "Hi there!" }] },
+};
+
+describe("Google GenAI thread manager hooks", () => {
+  describe("onPrepareMessage", () => {
+    it("transforms stored messages before system extraction and merge", async () => {
+      const hook = vi.fn((msg: StoredContent) => {
+        if (msg.content.role === "system") return msg;
+        return {
+          ...msg,
+          content: {
+            ...msg.content,
+            parts: [{ text: `[modified] ${msg.content.parts?.[0]?.text ?? ""}` }],
+          },
+        };
+      });
+
+      const redis = createMockRedis([systemContent, userContent, modelContent]);
+      const tm = createGoogleGenAIThreadManager({
+        redis: redis as never,
+        threadId: "t1",
+        hooks: { onPrepareMessage: hook },
+      });
+
+      const { contents, systemInstruction } = await tm.prepareForInvocation();
+
+      expect(hook).toHaveBeenCalledTimes(3);
+      expect(hook).toHaveBeenCalledWith(systemContent, 0, [systemContent, userContent, modelContent]);
+      expect(systemInstruction).toBe("You are helpful.");
+      expect(contents[0]?.parts?.[0]?.text).toBe("[modified] Hello");
+      expect(contents[1]?.parts?.[0]?.text).toBe("[modified] Hi there!");
+    });
+
+    it("is not called when not configured", async () => {
+      const redis = createMockRedis([userContent]);
+      const tm = createGoogleGenAIThreadManager({
+        redis: redis as never,
+        threadId: "t1",
+      });
+
+      const { contents } = await tm.prepareForInvocation();
+      expect(contents).toHaveLength(1);
+      expect(contents[0]?.parts?.[0]?.text).toBe("Hello");
+    });
+  });
+
+  describe("onPreparedMessage", () => {
+    it("transforms SDK-native Content after merge", async () => {
+      const hook = vi.fn((msg: Content) => ({
+        ...msg,
+        parts: [{ text: `[post] ${msg.parts?.[0]?.text ?? ""}` }],
+      }));
+
+      const redis = createMockRedis([userContent, modelContent]);
+      const tm = createGoogleGenAIThreadManager({
+        redis: redis as never,
+        threadId: "t1",
+        hooks: { onPreparedMessage: hook },
+      });
+
+      const { contents } = await tm.prepareForInvocation();
+
+      expect(hook).toHaveBeenCalledTimes(2);
+      expect(contents[0]?.parts?.[0]?.text).toBe("[post] Hello");
+      expect(contents[1]?.parts?.[0]?.text).toBe("[post] Hi there!");
+    });
+
+    it("receives the full prepared contents array", async () => {
+      const hook = vi.fn((msg: Content) => msg);
+
+      const redis = createMockRedis([userContent, modelContent]);
+      const tm = createGoogleGenAIThreadManager({
+        redis: redis as never,
+        threadId: "t1",
+        hooks: { onPreparedMessage: hook },
+      });
+
+      await tm.prepareForInvocation();
+
+      const args = hook.mock.calls[0] as unknown as [Content, number, Content[]];
+      expect(args[2]).toHaveLength(2);
+    });
+  });
+
+  describe("both hooks combined", () => {
+    it("runs onPrepareMessage before onPreparedMessage", async () => {
+      const order: string[] = [];
+
+      const redis = createMockRedis([userContent]);
+      const tm = createGoogleGenAIThreadManager({
+        redis: redis as never,
+        threadId: "t1",
+        hooks: {
+          onPrepareMessage: (msg) => {
+            order.push("pre");
+            return msg;
+          },
+          onPreparedMessage: (msg) => {
+            order.push("post");
+            return msg;
+          },
+        },
+      });
+
+      await tm.prepareForInvocation();
+      expect(order).toEqual(["pre", "post"]);
+    });
+
+    it("onPreparedMessage sees results of onPrepareMessage", async () => {
+      const redis = createMockRedis([userContent]);
+      const tm = createGoogleGenAIThreadManager({
+        redis: redis as never,
+        threadId: "t1",
+        hooks: {
+          onPrepareMessage: (msg) => ({
+            ...msg,
+            content: { ...msg.content, parts: [{ text: "replaced" }] },
+          }),
+          onPreparedMessage: (msg) => {
+            expect(msg.parts?.[0]?.text).toBe("replaced");
+            return msg;
+          },
+        },
+      });
+
+      const { contents } = await tm.prepareForInvocation();
+      expect(contents[0]?.parts?.[0]?.text).toBe("replaced");
+    });
+  });
+});

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

@@ -4,6 +4,7 @@ import {
   createThreadManager,
   type ProviderThreadManager,
   type ThreadManagerConfig,
+  type ThreadManagerHooks,
 } from "../../../lib/thread";
 import type { GoogleGenAIToolResponse } from "./activities";
 
@@ -16,11 +17,14 @@ export interface StoredContent {
   content: Content;
 }
 
+export type GoogleGenAIThreadManagerHooks = ThreadManagerHooks<StoredContent, Content>;
+
 export interface GoogleGenAIThreadManagerConfig {
   redis: Redis;
   threadId: string;
   /** Thread key, defaults to 'messages' */
   key?: string;
+  hooks?: GoogleGenAIThreadManagerHooks;
 }
 
 /** Prepared payload ready to send to the Google GenAI API */
@@ -141,11 +145,15 @@ export function createGoogleGenAIThreadManager(
 
     async prepareForInvocation(): Promise<GoogleGenAIInvocationPayload> {
       const stored = await base.load();
+      const { onPrepareMessage, onPreparedMessage } = config.hooks ?? {};
+      const mapped = onPrepareMessage
+        ? stored.map((msg, i) => onPrepareMessage(msg, i, stored))
+        : stored;
 
       let systemInstruction: string | undefined;
       const conversationContents: Content[] = [];
 
-      for (const item of stored) {
+      for (const item of mapped) {
         if (item.content.role === "system") {
           systemInstruction = item.content.parts?.[0]?.text;
         } else {
@@ -153,8 +161,11 @@ export function createGoogleGenAIThreadManager(
         }
       }
 
+      const contents = mergeConsecutiveContents(conversationContents);
       return {
-        contents: mergeConsecutiveContents(conversationContents),
+        contents: onPreparedMessage
+          ? contents.map((msg, i) => onPreparedMessage(msg, i, contents))
+          : contents,
         ...(systemInstruction ? { systemInstruction } : {}),
       };
     },

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

@@ -17,6 +17,7 @@ import type { BaseChatModel } from "@langchain/core/language_models/chat_models"
 import {
   createLangChainThreadManager,
   type LangChainContent,
+  type LangChainThreadManagerHooks,
 } from "./thread-manager";
 import { createLangChainModelInvoker } from "./model-invoker";
 
@@ -30,6 +31,7 @@ export interface LangChainAdapterConfig {
   /** Optional default model — if omitted, use `createModelInvoker()` to create invokers later */
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   model?: BaseChatModel<any>;
+  hooks?: LangChainThreadManagerHooks;
 }
 
 /**
@@ -177,7 +179,7 @@ export function createLangChainAdapter(
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     model: BaseChatModel<any>,
   ): ModelInvoker<StoredMessage> =>
-    createLangChainModelInvoker({ redis, model });
+    createLangChainModelInvoker({ redis, model, hooks: config.hooks });
 
   const invoker: ModelInvoker<StoredMessage> = config.model
     ? makeInvoker(config.model)

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

@@ -0,0 +1,37 @@
+import type { BaseMessage, MessageContent } from "@langchain/core/messages";
+
+type ContentBlock = MessageContent extends (infer U)[] | string ? U : never;
+
+/**
+ * Creates an `onPreparedMessage` hook that appends a cache-point content
+ * block to the last message in the thread.
+ *
+ * Skips appending if the last message already contains a block with the
+ * same `type`.
+ */
+export function appendCachePoint(
+  block: ContentBlock,
+): (message: BaseMessage, index: number, messages: readonly BaseMessage[]) => BaseMessage {
+  return (message, index, messages) => {
+    if (index !== messages.length - 1) {
+      return message;
+    }
+
+    const { content } = message;
+
+    if (Array.isArray(content)) {
+      if (content.some((b) => b.type === block.type)) {
+        return message;
+      }
+      message.content = [...content, block];
+      return message;
+    }
+
+    if (typeof content === "string") {
+      message.content = [{ type: "text", text: content }, block] satisfies MessageContent;
+      return message;
+    }
+
+    return message;
+  };
+}

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

@@ -39,3 +39,6 @@ export {
   invokeLangChainModel,
   type LangChainModelInvokerConfig,
 } from "./model-invoker";
+
+// Hooks / utilities
+export { appendCachePoint } from "./hooks";

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

@@ -3,12 +3,13 @@ import type { AgentResponse, ModelInvokerConfig } from "../../../lib/model";
 import type { StoredMessage } from "@langchain/core/messages";
 import { v4 as uuidv4 } from "uuid";
 import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
-import { createLangChainThreadManager } from "./thread-manager";
+import { createLangChainThreadManager, type LangChainThreadManagerHooks } from "./thread-manager";
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export interface LangChainModelInvokerConfig<TModel extends BaseChatModel<any> = BaseChatModel<any>> {
   redis: Redis;
   model: TModel;
+  hooks?: LangChainThreadManagerHooks;
 }
 
 /**
@@ -32,14 +33,14 @@ export interface LangChainModelInvokerConfig<TModel extends BaseChatModel<any> =
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export function createLangChainModelInvoker<TModel extends BaseChatModel<any> = BaseChatModel<any>>(
-  { redis, model }: LangChainModelInvokerConfig<TModel>,
+  { redis, model, hooks }: LangChainModelInvokerConfig<TModel>,
 ) {
   return async function invokeLangChainModel(
     config: ModelInvokerConfig,
   ): Promise<AgentResponse<StoredMessage>> {
     const { threadId, threadKey, agentName, state, metadata } = config;
 
-    const thread = createLangChainThreadManager({ redis, threadId, key: threadKey });
+    const thread = createLangChainThreadManager({ redis, threadId, key: threadKey, hooks });
     const runId = uuidv4();
 
     const { messages } = await thread.prepareForInvocation();
@@ -86,12 +87,14 @@ export function createLangChainModelInvoker<TModel extends BaseChatModel<any> =
 export async function invokeLangChainModel<TModel extends BaseChatModel<any> = BaseChatModel<any>>({
   redis,
   model,
+  hooks,
   config,
 }: {
   redis: Redis;
   config: ModelInvokerConfig;
   model: TModel;
+  hooks?: LangChainThreadManagerHooks;
 }): Promise<AgentResponse<StoredMessage>> {
-  const invoker = createLangChainModelInvoker({ redis, model });
+  const invoker = createLangChainModelInvoker({ redis, model, hooks });
   return invoker(config);
 }