zeitlich 0.2.24 → 0.2.26

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

@@ -2,10 +2,13 @@ import type Redis from "ioredis";
 import type { Content, Part } from "@google/genai";
 import {
   createThreadManager,
-  type BaseThreadManager,
+  type ProviderThreadManager,
   type ThreadManagerConfig,
 } from "../../../lib/thread";
-import type { MessageContent, ToolMessageContent } from "../../../lib/types";
+import type { GoogleGenAIToolResponse } from "./activities";
+
+/** SDK-native content type for Google GenAI human messages */
+export type GoogleGenAIContent = string | Part[];
 
 /** A Content with a unique ID for idempotent Redis storage */
 export interface StoredContent {
@@ -20,71 +23,55 @@ export interface GoogleGenAIThreadManagerConfig {
   key?: string;
 }
 
+/** Prepared payload ready to send to the Google GenAI API */
+export interface GoogleGenAIInvocationPayload {
+  contents: Content[];
+  systemInstruction?: string;
+}
+
 /** Thread manager with Google GenAI Content convenience helpers */
-export interface GoogleGenAIThreadManager extends BaseThreadManager<StoredContent> {
-  createUserContent(
-    id: string,
-    content: string | MessageContent
-  ): StoredContent;
-  createSystemContent(id: string, content: string): StoredContent;
-  createModelContent(id: string, parts: Part[]): StoredContent;
-  createToolResponseContent(
-    id: string,
-    toolCallId: string,
-    toolName: string,
-    content: ToolMessageContent
-  ): StoredContent;
-  appendUserMessage(
-    id: string,
-    content: string | MessageContent
-  ): Promise<void>;
-  appendSystemMessage(id: string, content: string): Promise<void>;
+export interface GoogleGenAIThreadManager
+  extends ProviderThreadManager<StoredContent, GoogleGenAIContent, GoogleGenAIToolResponse> {
   appendModelContent(id: string, parts: Part[]): Promise<void>;
-  appendToolResult(
-    id: string,
-    toolCallId: string,
-    toolName: string,
-    content: ToolMessageContent
-  ): Promise<void>;
+  prepareForInvocation(): Promise<GoogleGenAIInvocationPayload>;
 }
 
 function storedContentId(msg: StoredContent): string {
   return msg.id;
 }
 
-/** Convert zeitlich MessageContent to Google GenAI Part[] */
-export function messageContentToParts(
-  content: string | MessageContent
-): Part[] {
+/** Normalise content into Part[] */
+function toParts(content: GoogleGenAIContent): Part[] {
   if (typeof content === "string") {
     return [{ text: content }];
   }
-  if (Array.isArray(content)) {
-    return content.map((part) => {
-      if (part.type === "text") {
-        return { text: part.text as string };
-      }
-      return part as unknown as Part;
-    });
+  return content;
+}
+
+/** Convert a string or object into a Record suitable for functionResponse.response */
+function toFunctionResponse(content: string | Record<string, unknown>): Record<string, unknown> {
+  if (typeof content === "object") {
+    return content;
   }
-  return [{ text: String(content) }];
+  return { result: content };
 }
 
-/** Parse ToolMessageContent into a Record suitable for functionResponse */
-function parseToolResponse(
-  content: ToolMessageContent
-): Record<string, unknown> {
-  if (typeof content === "string") {
-    try {
-      const parsed: unknown = JSON.parse(content);
-      return typeof parsed === "object" && parsed !== null
-        ? (parsed as Record<string, unknown>)
-        : { result: content };
-    } catch {
-      return { result: content };
+/**
+ * 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 { result: content };
+  return merged;
 }
 
 /**
@@ -93,7 +80,7 @@ function parseToolResponse(
  * appending typed Content messages.
  */
 export function createGoogleGenAIThreadManager(
-  config: GoogleGenAIThreadManagerConfig
+  config: GoogleGenAIThreadManagerConfig,
 ): GoogleGenAIThreadManager {
   const baseConfig: ThreadManagerConfig<StoredContent> = {
     redis: config.redis,
@@ -104,79 +91,72 @@ export function createGoogleGenAIThreadManager(
 
   const base = createThreadManager(baseConfig);
 
-  const helpers = {
-    createUserContent(
+  const helpers: Omit<GoogleGenAIThreadManager, keyof typeof base> = {
+    async appendUserMessage(
       id: string,
-      content: string | MessageContent
-    ): StoredContent {
-      return {
+      content: GoogleGenAIContent,
+    ): Promise<void> {
+      await base.append([{
         id,
-        content: { role: "user", parts: messageContentToParts(content) },
-      };
+        content: { role: "user", parts: toParts(content) },
+      }]);
     },
 
-    createSystemContent(id: string, content: string): StoredContent {
-      return {
+    async appendSystemMessage(id: string, content: string): Promise<void> {
+      await base.initialize();
+      await base.append([{
         id,
         content: { role: "system", parts: [{ text: content }] },
-      };
+      }]);
     },
 
-    createModelContent(id: string, parts: Part[]): StoredContent {
-      return {
+    async appendModelContent(id: string, parts: Part[]): Promise<void> {
+      await base.append([{
         id,
         content: { role: "model", parts },
-      };
+      }]);
     },
 
-    createToolResponseContent(
+    async appendToolResult(
       id: string,
       toolCallId: string,
       toolName: string,
-      content: ToolMessageContent
-    ): StoredContent {
-      return {
-        id,
-        content: {
-          role: "user",
-          parts: [
-            {
-              functionResponse: {
-                id: toolCallId,
-                name: toolName,
-                response: parseToolResponse(content),
-              },
+      content: GoogleGenAIToolResponse,
+    ): Promise<void> {
+      const parts: Part[] = Array.isArray(content)
+        ? content as Part[]
+        : [{
+            functionResponse: {
+              id: toolCallId,
+              name: toolName,
+              response: toFunctionResponse(content),
             },
-          ],
-        },
-      };
-    },
+          }];
 
-    async appendUserMessage(
-      id: string,
-      content: string | MessageContent
-    ): Promise<void> {
-      await base.append([helpers.createUserContent(id, content)]);
+      await base.append([{
+        id,
+        content: { role: "user", parts },
+      }]);
     },
 
-    async appendSystemMessage(id: string, content: string): Promise<void> {
-      await base.initialize();
-      await base.append([helpers.createSystemContent(id, content)]);
-    },
+    async prepareForInvocation(): Promise<GoogleGenAIInvocationPayload> {
+      const stored = await base.load();
 
-    async appendModelContent(id: string, parts: Part[]): Promise<void> {
-      await base.append([helpers.createModelContent(id, parts)]);
-    },
+      let systemInstruction: string | undefined;
+      const conversationContents: Content[] = [];
 
-    async appendToolResult(
-      id: string,
-      toolCallId: string,
-      toolName: string,
-      content: ToolMessageContent
-    ): Promise<void> {
-      await base.append([
-        helpers.createToolResponseContent(id, toolCallId, toolName, content),
-      ]);
+      for (const item of stored) {
+        if (item.content.role === "system") {
+          systemInstruction = item.content.parts?.[0]?.text;
+        } else {
+          conversationContents.push(item.content);
+        }
+      }
+
+      return {
+        contents: mergeConsecutiveContents(conversationContents),
+        ...(systemInstruction ? { systemInstruction } : {}),
+      };
     },
   };
 

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

@@ -1,6 +1,11 @@
 import type Redis from "ioredis";
 import type { ToolResultConfig } from "../../../lib/types";
 import type { MessageContent } from "@langchain/core/messages";
+import type {
+  ActivityToolHandler,
+  RouterContext,
+  ToolHandlerResponse,
+} from "../../../lib/tool-router/types";
 import type {
   ThreadOps,
   PrefixedThreadOps,
@@ -9,13 +14,16 @@ import type {
 import type { ModelInvoker } from "../../../lib/model";
 import type { StoredMessage } from "@langchain/core/messages";
 import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
-import { createLangChainThreadManager } from "./thread-manager";
+import {
+  createLangChainThreadManager,
+  type LangChainContent,
+} from "./thread-manager";
 import { createLangChainModelInvoker } from "./model-invoker";
 
 const ADAPTER_PREFIX = "langChain" as const;
 
 export type LangChainThreadOps<TScope extends string = ""> =
-  PrefixedThreadOps<ScopedPrefix<TScope, typeof ADAPTER_PREFIX>>;
+  PrefixedThreadOps<ScopedPrefix<TScope, typeof ADAPTER_PREFIX>, LangChainContent>;
 
 export interface LangChainAdapterConfig {
   redis: Redis;
@@ -24,6 +32,15 @@ export interface LangChainAdapterConfig {
   model?: BaseChatModel<any>;
 }
 
+/**
+ * Tool response type accepted by the LangChain adapter.
+ *
+ * Content is passed directly to `ToolMessage` as `MessageContent`.
+ * Handlers can return a string or an array of content blocks
+ * (e.g. `{ type: "text", text: "..." }`, `{ type: "image_url", image_url: { ... } }`).
+ */
+export type LangChainToolResponse = MessageContent;
+
 export interface LangChainAdapter {
   /** Model invoker using the default model (only available when `model` was provided) */
   invoker: ModelInvoker<StoredMessage>;
@@ -42,8 +59,19 @@ export interface LangChainAdapter {
    * ```
    */
   createActivities<S extends string = "">(
-    scope?: S
+    scope?: S,
   ): LangChainThreadOps<S>;
+
+  /**
+   * Identity wrapper that types a tool handler for this adapter.
+   * Constrains `toolResponse` to {@link LangChainToolResponse}.
+   */
+  wrapHandler<TArgs, TResult, TContext extends RouterContext = RouterContext>(
+    handler: (
+      args: TArgs,
+      context: TContext,
+    ) => Promise<ToolHandlerResponse<TResult, LangChainToolResponse>>,
+  ): ActivityToolHandler<TArgs, TResult, TContext, LangChainToolResponse>;
 }
 
 /**
@@ -82,54 +110,58 @@ export interface LangChainAdapter {
  * ```
  */
 export function createLangChainAdapter(
-  config: LangChainAdapterConfig
+  config: LangChainAdapterConfig,
 ): LangChainAdapter {
   const { redis } = config;
 
-  const threadOps: ThreadOps = {
-    async initializeThread(threadId: string): Promise<void> {
-      const thread = createLangChainThreadManager({ redis, threadId });
+  const threadOps: ThreadOps<LangChainContent> = {
+    async initializeThread(threadId: string, threadKey?: string): Promise<void> {
+      const thread = createLangChainThreadManager({ redis, threadId, key: threadKey });
       await thread.initialize();
     },
 
     async appendHumanMessage(
       threadId: string,
       id: string,
-      content: string | MessageContent
+      content: LangChainContent,
+      threadKey?: string,
     ): Promise<void> {
-      const thread = createLangChainThreadManager({ redis, threadId });
-      await thread.appendHumanMessage(id, content);
+      const thread = createLangChainThreadManager({ 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 = createLangChainThreadManager({ redis, threadId });
+      const thread = createLangChainThreadManager({ redis, threadId, key: threadKey });
       await thread.appendSystemMessage(id, content);
     },
 
     async appendToolResult(id: string, cfg: ToolResultConfig): Promise<void> {
-      const { threadId, toolCallId, content } = cfg;
-      const thread = createLangChainThreadManager({ redis, threadId });
-      await thread.appendToolMessage(id, content, toolCallId);
+      const { threadId, threadKey, toolCallId, content } = cfg;
+      const thread = createLangChainThreadManager({ redis, threadId, key: threadKey });
+      await thread.appendToolResult(id, toolCallId, "", content);
     },
 
     async forkThread(
       sourceThreadId: string,
-      targetThreadId: string
+      targetThreadId: string,
+      threadKey?: string,
     ): Promise<void> {
       const thread = createLangChainThreadManager({
         redis,
         threadId: sourceThreadId,
+        key: threadKey,
       });
       await thread.fork(targetThreadId);
     },
   };
 
   function createActivities<S extends string = "">(
-    scope?: S
+    scope?: S,
   ): LangChainThreadOps<S> {
     const prefix = scope
       ? `${ADAPTER_PREFIX}${scope.charAt(0).toUpperCase()}${scope.slice(1)}`
@@ -137,13 +169,13 @@ export function createLangChainAdapter(
     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])
+      Object.entries(threadOps).map(([k, v]) => [`${prefix}${cap(k)}`, v]),
     ) as LangChainThreadOps<S>;
   }
 
   const makeInvoker = (
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    model: BaseChatModel<any>
+    model: BaseChatModel<any>,
   ): ModelInvoker<StoredMessage> =>
     createLangChainModelInvoker({ redis, model });
 
@@ -152,7 +184,7 @@ export function createLangChainAdapter(
     : () => {
         throw new Error(
           "No default model provided to createLangChainAdapter. " +
-            "Either pass `model` in the config or use `createModelInvoker(model)` instead."
+            "Either pass `model` in the config or use `createModelInvoker(model)` instead.",
         );
       };
 
@@ -160,5 +192,6 @@ export function createLangChainAdapter(
     createActivities,
     invoker,
     createModelInvoker: makeInvoker,
+    wrapHandler: (handler) => handler,
   };
 }

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

@@ -21,6 +21,7 @@ export {
   type LangChainAdapter,
   type LangChainAdapterConfig,
   type LangChainThreadOps,
+  type LangChainToolResponse,
 } from "./activities";
 
 // Thread manager
@@ -28,7 +29,8 @@ export {
   createLangChainThreadManager,
   type LangChainThreadManager,
   type LangChainThreadManagerConfig,
-  type LangChainToolMessageContent,
+  type LangChainContent,
+  type LangChainInvocationPayload,
 } from "./thread-manager";
 
 // Model invoker (for advanced use — prefer adapter.createModelInvoker)

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

@@ -1,7 +1,5 @@
 import type Redis from "ioredis";
-import type { AgentResponse } from "../../../lib/model";
-import type { ModelInvokerConfig } from "../../../lib/model";
-import { mapStoredMessagesToChatMessages } from "@langchain/core/messages";
+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";
@@ -37,22 +35,22 @@ export function createLangChainModelInvoker<TModel extends BaseChatModel<any> =
   { redis, model }: LangChainModelInvokerConfig<TModel>,
 ) {
   return async function invokeLangChainModel(
-    config: ModelInvokerConfig
+    config: ModelInvokerConfig,
   ): Promise<AgentResponse<StoredMessage>> {
-    const { threadId, agentName, state, metadata } = config;
+    const { threadId, threadKey, agentName, state, metadata } = config;
 
-    const thread = createLangChainThreadManager({ redis, threadId });
+    const thread = createLangChainThreadManager({ redis, threadId, key: threadKey });
     const runId = uuidv4();
 
-    const messages = await thread.load();
+    const { messages } = await thread.prepareForInvocation();
     const response = await model.invoke(
-      [...mapStoredMessagesToChatMessages(messages)],
+      messages,
       {
         runName: agentName,
         runId,
         metadata: { thread_id: `${agentName}-${threadId}`, ...metadata },
         tools: state.tools,
-      }
+      },
     );
 
     await thread.append([response.toDict()]);

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

@@ -18,44 +18,16 @@
  * const threadOps = proxyLangChainThreadOps("customScope");
  * ```
  */
-import {
-  proxyActivities,
-  workflowInfo,
-  type ActivityInterfaceFor,
-} from "@temporalio/workflow";
+import { type ActivityInterfaceFor } from "@temporalio/workflow";
 import type { ThreadOps } from "../../../lib/session/types";
+import type { LangChainContent } from "./thread-manager";
+import { createThreadOpsProxy } from "../../../lib/thread/proxy";
 
 const ADAPTER_PREFIX = "langChain";
 
 export function proxyLangChainThreadOps(
   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<LangChainContent>> {
+  return createThreadOpsProxy(ADAPTER_PREFIX, scope, options) as ActivityInterfaceFor<ThreadOps<LangChainContent>>;
 }