zeitlich 0.2.25 → 0.2.27

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

@@ -0,0 +1,202 @@
+import type Redis from "ioredis";
+import type Anthropic from "@anthropic-ai/sdk";
+import type { JsonValue } from "../../../lib/state/types";
+import {
+  createThreadManager,
+  type ProviderThreadManager,
+  type ThreadManagerConfig,
+  type ThreadManagerHooks,
+} from "../../../lib/thread";
+
+/** SDK-native content type for Anthropic human messages */
+export type AnthropicContent =
+  | string
+  | Anthropic.Messages.ContentBlockParam[];
+
+/** A MessageParam with a unique ID for idempotent Redis storage */
+export interface StoredMessage {
+  id: string;
+  message: Anthropic.Messages.MessageParam;
+  /** System messages are stored separately since Anthropic passes them via config */
+  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 */
+export interface AnthropicInvocationPayload {
+  messages: Anthropic.Messages.MessageParam[];
+  system?: string;
+}
+
+/** Thread manager with Anthropic MessageParam convenience helpers */
+export interface AnthropicThreadManager
+  extends ProviderThreadManager<StoredMessage, AnthropicContent> {
+  appendAssistantMessage(
+    id: string,
+    content: Anthropic.Messages.ContentBlock[],
+  ): Promise<void>;
+  prepareForInvocation(): Promise<AnthropicInvocationPayload>;
+}
+
+function storedMessageId(msg: StoredMessage): string {
+  return msg.id;
+}
+
+/** Normalise content into an array of ContentBlockParam */
+function toContentBlocks(
+  content: AnthropicContent,
+): Anthropic.Messages.ContentBlockParam[] {
+  if (typeof content === "string") {
+    return [{ type: "text", text: content }];
+  }
+  return content;
+}
+
+/**
+ * Merge consecutive messages with the same role.
+ * The Anthropic API requires alternating user/assistant turns; without
+ * merging, multiple sequential tool-result messages would violate this.
+ */
+function mergeConsecutiveMessages(
+  messages: Anthropic.Messages.MessageParam[],
+): Anthropic.Messages.MessageParam[] {
+  const merged: Anthropic.Messages.MessageParam[] = [];
+  for (const msg of messages) {
+    const last = merged[merged.length - 1];
+    if (last && last.role === msg.role) {
+      const lastContent = Array.isArray(last.content)
+        ? last.content
+        : [{ type: "text" as const, text: last.content }];
+      const msgContent = Array.isArray(msg.content)
+        ? msg.content
+        : [{ type: "text" as const, text: msg.content }];
+      last.content = [...lastContent, ...msgContent];
+    } else {
+      merged.push({
+        ...msg,
+        content: Array.isArray(msg.content)
+          ? [...msg.content]
+          : msg.content,
+      });
+    }
+  }
+  return merged;
+}
+
+/**
+ * Creates an Anthropic-specific thread manager that stores StoredMessage
+ * instances in Redis and provides convenience helpers for creating and
+ * appending typed messages.
+ */
+export function createAnthropicThreadManager(
+  config: AnthropicThreadManagerConfig,
+): AnthropicThreadManager {
+  const baseConfig: ThreadManagerConfig<StoredMessage> = {
+    redis: config.redis,
+    threadId: config.threadId,
+    key: config.key,
+    idOf: storedMessageId,
+  };
+
+  const base = createThreadManager(baseConfig);
+
+  const helpers: Omit<AnthropicThreadManager, keyof typeof base> = {
+    async appendUserMessage(
+      id: string,
+      content: AnthropicContent,
+    ): Promise<void> {
+      await base.append([{
+        id,
+        message: { role: "user", content: toContentBlocks(content) },
+      }]);
+    },
+
+    async appendSystemMessage(id: string, content: string): Promise<void> {
+      await base.initialize();
+      await base.append([{
+        id,
+        message: { role: "user", content },
+        isSystem: true,
+      }]);
+    },
+
+    async appendAssistantMessage(
+      id: string,
+      content: Anthropic.Messages.ContentBlock[],
+    ): Promise<void> {
+      await base.append([{
+        id,
+        message: {
+          role: "assistant",
+          content: content as unknown as Anthropic.Messages.ContentBlockParam[],
+        },
+      }]);
+    },
+
+    async appendToolResult(
+      id: string,
+      toolCallId: string,
+      _toolName: string,
+      content: JsonValue,
+    ): Promise<void> {
+      const toolContent =
+        typeof content === "string"
+          ? content
+          : Array.isArray(content)
+            ? (content as unknown as Anthropic.Messages.ToolResultBlockParam["content"])
+            : JSON.stringify(content);
+      await base.append([{
+        id,
+        message: {
+          role: "user",
+          content: [{
+            type: "tool_result" as const,
+            tool_use_id: toolCallId,
+            content: toolContent,
+          }],
+        },
+      }]);
+    },
+
+    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 mapped) {
+        if (item.isSystem) {
+          system =
+            typeof item.message.content === "string"
+              ? item.message.content
+              : undefined;
+        } else {
+          conversationMessages.push(item.message);
+        }
+      }
+
+      const messages = mergeConsecutiveMessages(conversationMessages);
+      return {
+        messages: onPreparedMessage
+          ? messages.map((msg, i) => onPreparedMessage(msg, i, messages))
+          : messages,
+        ...(system ? { system } : {}),
+      };
+    },
+  };
+
+  return Object.assign(base, helpers);
+}

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

@@ -1,33 +1,69 @@
 import type Redis from "ioredis";
-import type { GoogleGenAI, Content } from "@google/genai";
+import type { GoogleGenAI, Content, Part } from "@google/genai";
 import type { ToolResultConfig } from "../../../lib/types";
-import type { MessageContent } from "../../../lib/types";
+import type {
+  ActivityToolHandler,
+  RouterContext,
+  ToolHandlerResponse,
+} from "../../../lib/tool-router/types";
 import type {
   ThreadOps,
   PrefixedThreadOps,
   ScopedPrefix,
 } from "../../../lib/session/types";
 import type { ModelInvoker } from "../../../lib/model";
-import { createGoogleGenAIThreadManager } from "./thread-manager";
+import {
+  createGoogleGenAIThreadManager,
+  type GoogleGenAIContent,
+  type GoogleGenAIThreadManagerHooks,
+} from "./thread-manager";
 import { createGoogleGenAIModelInvoker } from "./model-invoker";
 
 const ADAPTER_PREFIX = "googleGenAI" as const;
 
 export type GoogleGenAIThreadOps<TScope extends string = ""> =
-  PrefixedThreadOps<ScopedPrefix<TScope, typeof ADAPTER_PREFIX>>;
+  PrefixedThreadOps<
+    ScopedPrefix<TScope, typeof ADAPTER_PREFIX>,
+    GoogleGenAIContent
+  >;
 
 export interface GoogleGenAIAdapterConfig {
   redis: Redis;
-  client: GoogleGenAI;
+  client?: GoogleGenAI;
   /** Default model name (e.g. 'gemini-2.5-flash'). If omitted, use `createModelInvoker()` */
   model?: string;
+  hooks?: GoogleGenAIThreadManagerHooks;
 }
 
+/**
+ * Tool response type accepted by the Google GenAI adapter.
+ *
+ * Handlers can return:
+ * - **`string`** — plain text, wrapped in a `functionResponse` part.
+ * - **`Record<string, unknown>`** — structured object used as `functionResponse.response`.
+ * - **`Part[]`** — pre-built parts used directly as `Content.parts`.
+ *   The handler is responsible for building correct Part objects (e.g. `functionResponse`,
+ *   `inlineData`, `text`). Use `context.toolCallId` and `context.toolName` to construct
+ *   `functionResponse` parts.
+ *
+ * @example
+ * ```typescript
+ * adapter.wrapHandler(async (args, ctx) => ({
+ *   toolResponse: [
+ *     { functionResponse: { id: ctx.toolCallId, name: ctx.toolName, response: { result: "done" } } },
+ *     { inlineData: { data: base64, mimeType: "image/png" } },
+ *   ],
+ *   data: null,
+ * }));
+ * ```
+ */
+export type GoogleGenAIToolResponse = string | Record<string, unknown> | Part[];
+
 export interface GoogleGenAIAdapter {
   /** Model invoker using the default model (only available when `model` was provided) */
   invoker: ModelInvoker<Content>;
   /** Create an invoker for a specific model name (for multi-model setups) */
-  createModelInvoker(model: string): ModelInvoker<Content>;
+  createModelInvoker(model: string, client: GoogleGenAI): ModelInvoker<Content>;
   /**
    * Create prefixed thread activities for registration on the worker.
    *
@@ -43,9 +79,18 @@ export interface GoogleGenAIAdapter {
    * // → { googleGenAIResearchAgentInitializeThread, … }
    * ```
    */
-  createActivities<S extends string = "">(
-    scope?: S
-  ): GoogleGenAIThreadOps<S>;
+  createActivities<S extends string = "">(scope?: S): GoogleGenAIThreadOps<S>;
+
+  /**
+   * Identity wrapper that types a tool handler for this adapter.
+   * Constrains `toolResponse` to {@link GoogleGenAIToolResponse}.
+   */
+  wrapHandler<TArgs, TResult, TContext extends RouterContext = RouterContext>(
+    handler: (
+      args: TArgs,
+      context: TContext
+    ) => Promise<ToolHandlerResponse<TResult, GoogleGenAIToolResponse>>
+  ): ActivityToolHandler<TArgs, TResult, TContext, GoogleGenAIToolResponse>;
 }
 
 /**
@@ -91,45 +136,73 @@ export interface GoogleGenAIAdapter {
 export function createGoogleGenAIAdapter(
   config: GoogleGenAIAdapterConfig
 ): GoogleGenAIAdapter {
-  const { redis, client } = config;
+  const { redis } = config;
 
-  const threadOps: ThreadOps = {
-    async initializeThread(threadId: string): Promise<void> {
-      const thread = createGoogleGenAIThreadManager({ redis, threadId });
+  const threadOps: ThreadOps<GoogleGenAIContent> = {
+    async initializeThread(
+      threadId: string,
+      threadKey?: string
+    ): Promise<void> {
+      const thread = createGoogleGenAIThreadManager({
+        redis,
+        threadId,
+        key: threadKey,
+      });
       await thread.initialize();
     },
 
     async appendHumanMessage(
       threadId: string,
       id: string,
-      content: string | MessageContent
+      content: GoogleGenAIContent,
+      threadKey?: string
     ): Promise<void> {
-      const thread = createGoogleGenAIThreadManager({ redis, threadId });
+      const thread = createGoogleGenAIThreadManager({
+        redis,
+        threadId,
+        key: threadKey,
+      });
       await thread.appendUserMessage(id, content);
     },
 
     async appendSystemMessage(
       threadId: string,
       id: string,
-      content: string
+      content: string,
+      threadKey?: string
     ): Promise<void> {
-      const thread = createGoogleGenAIThreadManager({ redis, threadId });
+      const thread = createGoogleGenAIThreadManager({
+        redis,
+        threadId,
+        key: threadKey,
+      });
       await thread.appendSystemMessage(id, content);
     },
 
     async appendToolResult(id: string, cfg: ToolResultConfig): Promise<void> {
-      const { threadId, toolCallId, toolName, content } = cfg;
-      const thread = createGoogleGenAIThreadManager({ redis, threadId });
-      await thread.appendToolResult(id, toolCallId, toolName, content);
+      const { threadId, threadKey, toolCallId, toolName, content } = cfg;
+      const thread = createGoogleGenAIThreadManager({
+        redis,
+        threadId,
+        key: threadKey,
+      });
+      await thread.appendToolResult(
+        id,
+        toolCallId,
+        toolName,
+        content as GoogleGenAIToolResponse
+      );
     },
 
     async forkThread(
       sourceThreadId: string,
-      targetThreadId: string
+      targetThreadId: string,
+      threadKey?: string
     ): Promise<void> {
       const thread = createGoogleGenAIThreadManager({
         redis,
         threadId: sourceThreadId,
+        key: threadKey,
       });
       await thread.fork(targetThreadId);
     },
@@ -141,28 +214,32 @@ export function createGoogleGenAIAdapter(
     const prefix = scope
       ? `${ADAPTER_PREFIX}${scope.charAt(0).toUpperCase()}${scope.slice(1)}`
       : ADAPTER_PREFIX;
-    const cap = (s: string): string =>
-      s.charAt(0).toUpperCase() + s.slice(1);
+    const cap = (s: string): string => s.charAt(0).toUpperCase() + s.slice(1);
     return Object.fromEntries(
       Object.entries(threadOps).map(([k, v]) => [`${prefix}${cap(k)}`, v])
     ) as GoogleGenAIThreadOps<S>;
   }
 
-  const makeInvoker = (model: string): ModelInvoker<Content> =>
-    createGoogleGenAIModelInvoker({ redis, client, model });
+  const makeInvoker = (
+    model: string,
+    client: GoogleGenAI
+  ): ModelInvoker<Content> =>
+    createGoogleGenAIModelInvoker({ redis, client, model, hooks: config.hooks });
 
-  const invoker: ModelInvoker<Content> = config.model
-    ? makeInvoker(config.model)
-    : ((() => {
-        throw new Error(
-          "No default model provided to createGoogleGenAIAdapter. " +
-            "Either pass `model` in the config or use `createModelInvoker(model)` instead."
-        );
-      }) as unknown as ModelInvoker<Content>);
+  const invoker: ModelInvoker<Content> =
+    config.model && config.client
+      ? makeInvoker(config.model, config.client)
+      : ((() => {
+          throw new Error(
+            "No default model provided to createGoogleGenAIAdapter. " +
+              "Either pass `model` in the config or use `createModelInvoker(model)` instead."
+          );
+        }) as unknown as ModelInvoker<Content>);
 
   return {
     createActivities,
     invoker,
     createModelInvoker: makeInvoker,
+    wrapHandler: (handler) => handler,
   };
 }

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

@@ -23,14 +23,16 @@ export {
   type GoogleGenAIAdapter,
   type GoogleGenAIAdapterConfig,
   type GoogleGenAIThreadOps,
+  type GoogleGenAIToolResponse,
 } from "./activities";
 
 // Thread manager
 export {
   createGoogleGenAIThreadManager,
-  messageContentToParts,
   type GoogleGenAIThreadManager,
   type GoogleGenAIThreadManagerConfig,
+  type GoogleGenAIContent,
+  type GoogleGenAIInvocationPayload,
   type StoredContent,
 } from "./thread-manager";
 

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

@@ -1,19 +1,19 @@
 import type Redis from "ioredis";
 import type { GoogleGenAI, Content, FunctionDeclaration } from "@google/genai";
 import type { SerializableToolDefinition } from "../../../lib/types";
-import type { AgentResponse } from "../../../lib/model";
-import type { ModelInvokerConfig } from "../../../lib/model";
-import { createGoogleGenAIThreadManager } from "./thread-manager";
+import type { AgentResponse, ModelInvokerConfig } from "../../../lib/model";
+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(
-  tools: SerializableToolDefinition[]
+  tools: SerializableToolDefinition[],
 ): FunctionDeclaration[] {
   return tools.map((t) => ({
     name: t.name,
@@ -22,24 +22,6 @@ function toFunctionDeclarations(
   }));
 }
 
-/**
- * Merge consecutive Content objects sharing the same role.
- * The Gemini API requires alternating user/model turns; without
- * merging, multiple sequential tool-result messages would violate this.
- */
-function mergeConsecutiveContents(contents: Content[]): Content[] {
-  const merged: Content[] = [];
-  for (const content of contents) {
-    const last = merged[merged.length - 1];
-    if (last && last.role === content.role) {
-      last.parts = [...(last.parts ?? []), ...(content.parts ?? [])];
-    } else {
-      merged.push({ ...content, parts: [...(content.parts ?? [])] });
-    }
-  }
-  return merged;
-}
-
 /**
  * Creates a Google GenAI model invoker that satisfies the generic
  * `ModelInvoker<Content>` contract.
@@ -68,29 +50,16 @@ export function createGoogleGenAIModelInvoker({
   redis,
   client,
   model,
+  hooks,
 }: GoogleGenAIModelInvokerConfig) {
   return async function invokeGoogleGenAIModel(
-    config: ModelInvokerConfig
+    config: ModelInvokerConfig,
   ): Promise<AgentResponse<Content>> {
-    const { threadId, state } = config;
-
-    const thread = createGoogleGenAIThreadManager({ redis, threadId });
-    const stored = await thread.load();
-
-    // Separate system instructions from conversation content.
-    // Google GenAI takes system instructions via config, not in the contents array.
-    let systemInstruction: string | undefined;
-    const conversationContents: Content[] = [];
-
-    for (const item of stored) {
-      if (item.content.role === "system") {
-        systemInstruction = item.content.parts?.[0]?.text;
-      } else {
-        conversationContents.push(item.content);
-      }
-    }
+    const { threadId, threadKey, state } = config;
 
-    const contents = mergeConsecutiveContents(conversationContents);
+    const thread = createGoogleGenAIThreadManager({ redis, threadId, key: threadKey, hooks });
+    const { contents, systemInstruction } =
+      await thread.prepareForInvocation();
 
     const functionDeclarations = toFunctionDeclarations(state.tools);
     const tools =
@@ -137,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/proxy.ts

@@ -18,44 +18,16 @@
  * const threadOps = proxyGoogleGenAIThreadOps("customScope");
  * ```
  */
-import {
-  proxyActivities,
-  workflowInfo,
-  type ActivityInterfaceFor,
-} from "@temporalio/workflow";
+import { type ActivityInterfaceFor } from "@temporalio/workflow";
 import type { ThreadOps } from "../../../lib/session/types";
+import type { GoogleGenAIContent } from "./thread-manager";
+import { createThreadOpsProxy } from "../../../lib/thread/proxy";
 
 const ADAPTER_PREFIX = "googleGenAI";
 
 export function proxyGoogleGenAIThreadOps(
   scope?: string,
-  options?: Parameters<typeof proxyActivities>[0]
-): ActivityInterfaceFor<ThreadOps> {
-  const resolvedScope = scope ?? workflowInfo().workflowType;
-
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const acts = proxyActivities<Record<string, (...args: any[]) => any>>(
-    options ?? {
-      startToCloseTimeout: "10s",
-      retry: {
-        maximumAttempts: 6,
-        initialInterval: "5s",
-        maximumInterval: "15m",
-        backoffCoefficient: 4,
-      },
-    }
-  );
-
-  const prefix =
-    `${ADAPTER_PREFIX}${resolvedScope.charAt(0).toUpperCase()}${resolvedScope.slice(1)}`;
-  const p = (key: string): string =>
-    `${prefix}${key.charAt(0).toUpperCase()}${key.slice(1)}`;
-
-  return {
-    initializeThread: acts[p("initializeThread")],
-    appendHumanMessage: acts[p("appendHumanMessage")],
-    appendToolResult: acts[p("appendToolResult")],
-    appendSystemMessage: acts[p("appendSystemMessage")],
-    forkThread: acts[p("forkThread")],
-  } as ActivityInterfaceFor<ThreadOps>;
+  options?: Parameters<typeof createThreadOpsProxy>[2],
+): ActivityInterfaceFor<ThreadOps<GoogleGenAIContent>> {
+  return createThreadOpsProxy(ADAPTER_PREFIX, scope, options) as ActivityInterfaceFor<ThreadOps<GoogleGenAIContent>>;
 }