zeitlich 0.2.13 → 0.2.14

package/src/adapters/sandbox/virtual/with-virtual-sandbox.ts

@@ -0,0 +1,91 @@
+import type { WorkflowClient } from "@temporalio/client";
+import { queryParentWorkflowState } from "../../../lib/activity";
+import type { ActivityToolHandler } from "../../../lib/tool-router/types";
+import type {
+  FileEntryMetadata,
+  TreeMutation,
+  VirtualSandboxContext,
+  VirtualSandboxState,
+} from "./types";
+import type { VirtualSandboxProvider } from "./provider";
+import { createVirtualSandbox } from "./index";
+
+/**
+ * Wraps a tool handler that needs a virtual sandbox, automatically querying
+ * the parent workflow for the current file tree and resolver context.
+ *
+ * On each invocation the wrapper:
+ * 1. Queries the workflow's `AgentState` for `fileTree` and `resolverContext`
+ * 2. Creates an ephemeral {@link VirtualSandbox} from tree + provider's resolver
+ * 3. Runs the inner handler
+ * 4. Returns the handler's result together with any {@link TreeMutation}s
+ *
+ * The consumer applies mutations back to workflow state via a post-tool hook.
+ *
+ * @param client    - Temporal `WorkflowClient` for querying the parent workflow
+ * @param agentName - Agent name (used to derive the state query name)
+ * @param provider  - {@link VirtualSandboxProvider} (wraps the resolver)
+ * @param handler   - Inner handler expecting a {@link VirtualSandboxContext}
+ *
+ * @example
+ * ```typescript
+ * import { withVirtualSandbox, type VirtualSandboxContext } from 'zeitlich';
+ *
+ * const readHandler: ActivityToolHandler<FileReadArgs, ReadResult, VirtualSandboxContext> =
+ *   async (args, { sandbox }) => {
+ *     const content = await sandbox.fs.readFile(args.path);
+ *     return { toolResponse: content, data: { path: args.path, content } };
+ *   };
+ *
+ * // At activity registration:
+ * const provider = new VirtualSandboxProvider(resolver);
+ * const handler = withVirtualSandbox(client, "myAgent", provider, readHandler);
+ * ```
+ */
+export function withVirtualSandbox<
+  TArgs,
+  TResult,
+  TCtx,
+  TMeta = FileEntryMetadata,
+>(
+  client: WorkflowClient,
+  provider: VirtualSandboxProvider<TCtx, TMeta>,
+  handler: ActivityToolHandler<
+    TArgs,
+    TResult,
+    VirtualSandboxContext<TCtx, TMeta>
+  >
+): ActivityToolHandler<
+  TArgs,
+  (TResult & { treeMutations: TreeMutation<TMeta>[] }) | null
+> {
+  return async (args, context) => {
+    const state =
+      await queryParentWorkflowState<VirtualSandboxState<TCtx, TMeta>>(client);
+
+    const { sandboxId, fileTree, resolverContext } = state;
+    if (!fileTree || !sandboxId) {
+      return {
+        toolResponse: `Error: No fileTree/sandboxId in agent state. The ${context.toolName} tool requires a virtual sandbox.`,
+        data: null,
+      };
+    }
+
+    const sandbox = createVirtualSandbox(
+      sandboxId,
+      fileTree,
+      provider.resolver,
+      resolverContext
+    );
+    const response = await handler(args, { ...context, sandbox });
+    const mutations = sandbox.fs.getMutations();
+
+    return {
+      toolResponse: response.toolResponse,
+      data: {
+        ...(response.data ?? {}),
+        treeMutations: mutations,
+      } as TResult & { treeMutations: TreeMutation<TMeta>[] },
+    };
+  };
+}

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

@@ -0,0 +1,121 @@
+import type Redis from "ioredis";
+import type { GoogleGenAI, Content } from "@google/genai";
+import type { ToolResultConfig } from "../../../lib/types";
+import type { MessageContent } from "../../../lib/types";
+import type { ThreadOps } from "../../../lib/session/types";
+import type { ModelInvoker } from "../../../lib/model";
+import { createGoogleGenAIThreadManager } from "./thread-manager";
+import { createGoogleGenAIModelInvoker } from "./model-invoker";
+
+export interface GoogleGenAIAdapterConfig {
+  redis: Redis;
+  client: GoogleGenAI;
+  /** Default model name (e.g. 'gemini-2.5-flash'). If omitted, use `createModelInvoker()` */
+  model?: string;
+}
+
+export interface GoogleGenAIAdapter {
+  /** Thread operations (register these as Temporal activities on the worker) */
+  threadOps: ThreadOps;
+  /** 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>;
+}
+
+/**
+ * Creates a Google GenAI adapter that bundles thread operations and model
+ * invocation using the `@google/genai` SDK.
+ *
+ * The returned `threadOps` should be registered as Temporal activities on
+ * the worker. The `invoker` (or invokers created via `createModelInvoker`)
+ * should be wrapped with `createRunAgentActivity` for per-agent activities.
+ *
+ * @example
+ * ```typescript
+ * import { createGoogleGenAIAdapter } from 'zeitlich/adapters/thread/google-genai';
+ * import { createRunAgentActivity } from 'zeitlich';
+ * import { GoogleGenAI } from '@google/genai';
+ *
+ * const client = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
+ * const adapter = createGoogleGenAIAdapter({ redis, client, model: 'gemini-2.5-flash' });
+ *
+ * export function createActivities(temporalClient: WorkflowClient) {
+ *   return {
+ *     ...adapter.threadOps,
+ *     runAgent: createRunAgentActivity(temporalClient, adapter.invoker),
+ *   };
+ * }
+ * ```
+ *
+ * @example Multi-model setup
+ * ```typescript
+ * const adapter = createGoogleGenAIAdapter({ redis, client });
+ *
+ * export function createActivities(temporalClient: WorkflowClient) {
+ *   return {
+ *     ...adapter.threadOps,
+ *     runResearchAgent: createRunAgentActivity(
+ *       temporalClient,
+ *       adapter.createModelInvoker('gemini-2.5-pro'),
+ *     ),
+ *     runFastAgent: createRunAgentActivity(
+ *       temporalClient,
+ *       adapter.createModelInvoker('gemini-2.5-flash'),
+ *     ),
+ *   };
+ * }
+ * ```
+ */
+export function createGoogleGenAIAdapter(
+  config: GoogleGenAIAdapterConfig,
+): GoogleGenAIAdapter {
+  const { redis, client } = config;
+
+  const threadOps: ThreadOps = {
+    async initializeThread(threadId: string): Promise<void> {
+      const thread = createGoogleGenAIThreadManager({ redis, threadId });
+      await thread.initialize();
+    },
+
+    async appendHumanMessage(
+      threadId: string,
+      content: string | MessageContent,
+    ): Promise<void> {
+      const thread = createGoogleGenAIThreadManager({ redis, threadId });
+      await thread.appendUserMessage(content);
+    },
+
+    async appendSystemMessage(
+      threadId: string,
+      content: string,
+    ): Promise<void> {
+      const thread = createGoogleGenAIThreadManager({ redis, threadId });
+      await thread.appendSystemMessage(content);
+    },
+
+    async appendToolResult(cfg: ToolResultConfig): Promise<void> {
+      const { threadId, toolCallId, toolName, content } = cfg;
+      const thread = createGoogleGenAIThreadManager({ redis, threadId });
+      await thread.appendToolResult(toolCallId, toolName, content);
+    },
+  };
+
+  const makeInvoker = (model: string): ModelInvoker<Content> =>
+    createGoogleGenAIModelInvoker({ redis, client, model });
+
+  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>);
+
+  return {
+    threadOps,
+    invoker,
+    createModelInvoker: makeInvoker,
+  };
+}

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

@@ -0,0 +1,41 @@
+/**
+ * Google GenAI adapter for Zeitlich.
+ *
+ * Provides a unified adapter that bundles thread management and model
+ * invocation using the `@google/genai` SDK (Gemini).
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createGoogleGenAIAdapter,
+ *   createGoogleGenAIThreadManager,
+ * } from 'zeitlich/adapters/thread/google-genai';
+ * import { GoogleGenAI } from '@google/genai';
+ *
+ * const client = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
+ * const adapter = createGoogleGenAIAdapter({ redis, client, model: 'gemini-2.5-flash' });
+ * ```
+ */
+
+// Adapter (primary API)
+export {
+  createGoogleGenAIAdapter,
+  type GoogleGenAIAdapter,
+  type GoogleGenAIAdapterConfig,
+} from "./activities";
+
+// Thread manager
+export {
+  createGoogleGenAIThreadManager,
+  messageContentToParts,
+  type GoogleGenAIThreadManager,
+  type GoogleGenAIThreadManagerConfig,
+  type StoredContent,
+} from "./thread-manager";
+
+// Model invoker (for advanced use — prefer adapter.createModelInvoker)
+export {
+  createGoogleGenAIModelInvoker,
+  invokeGoogleGenAIModel,
+  type GoogleGenAIModelInvokerConfig,
+} from "./model-invoker";

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

@@ -0,0 +1,154 @@
+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";
+
+export interface GoogleGenAIModelInvokerConfig {
+  redis: Redis;
+  client: GoogleGenAI;
+  model: string;
+}
+
+function toFunctionDeclarations(
+  tools: SerializableToolDefinition[],
+): FunctionDeclaration[] {
+  return tools.map((t) => ({
+    name: t.name,
+    description: t.description,
+    parametersJsonSchema: t.schema,
+  }));
+}
+
+/**
+ * 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.
+ *
+ * Loads the conversation thread from Redis, invokes the Gemini model via
+ * `client.models.generateContent`, appends the AI response, and returns
+ * a normalised AgentResponse.
+ *
+ * @example
+ * ```typescript
+ * import { createGoogleGenAIModelInvoker } from 'zeitlich/adapters/thread/google-genai';
+ * import { createRunAgentActivity } from 'zeitlich';
+ * import { GoogleGenAI } from '@google/genai';
+ *
+ * const client = new GoogleGenAI({ apiKey: process.env.GEMINI_API_KEY });
+ * const invoker = createGoogleGenAIModelInvoker({
+ *   redis,
+ *   client,
+ *   model: 'gemini-2.5-flash',
+ * });
+ *
+ * return { runAgent: createRunAgentActivity(client, invoker) };
+ * ```
+ */
+export function createGoogleGenAIModelInvoker({
+  redis,
+  client,
+  model,
+}: GoogleGenAIModelInvokerConfig) {
+  return async function invokeGoogleGenAIModel(
+    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 contents = mergeConsecutiveContents(conversationContents);
+
+    const functionDeclarations = toFunctionDeclarations(state.tools);
+    const tools =
+      functionDeclarations.length > 0
+        ? [{ functionDeclarations }]
+        : undefined;
+
+    const response = await client.models.generateContent({
+      model,
+      contents,
+      config: {
+        ...(systemInstruction ? { systemInstruction } : {}),
+        ...(tools ? { tools } : {}),
+      },
+    });
+
+    const responseParts = response.candidates?.[0]?.content?.parts ?? [];
+    const modelContent: Content = { role: "model", parts: responseParts };
+
+    await thread.appendModelContent(responseParts);
+
+    const functionCalls = response.functionCalls ?? [];
+
+    return {
+      message: modelContent,
+      rawToolCalls: functionCalls.map((fc) => ({
+        id: fc.id,
+        name: fc.name ?? "",
+        args: fc.args ?? {},
+      })),
+      usage: {
+        inputTokens: response.usageMetadata?.promptTokenCount,
+        outputTokens: response.usageMetadata?.candidatesTokenCount,
+        cachedReadTokens: response.usageMetadata?.cachedContentTokenCount,
+      },
+    };
+  };
+}
+
+/**
+ * Standalone function for one-shot Google GenAI model invocation.
+ * Convenience wrapper around createGoogleGenAIModelInvoker for cases
+ * where you don't need to reuse the invoker.
+ */
+export async function invokeGoogleGenAIModel({
+  redis,
+  client,
+  model,
+  config,
+}: {
+  redis: Redis;
+  client: GoogleGenAI;
+  model: string;
+  config: ModelInvokerConfig;
+}): Promise<AgentResponse<Content>> {
+  const invoker = createGoogleGenAIModelInvoker({ redis, client, model });
+  return invoker(config);
+}

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

@@ -0,0 +1,169 @@
+import type Redis from "ioredis";
+import type { Content, Part } from "@google/genai";
+import {
+  createThreadManager,
+  type BaseThreadManager,
+  type ThreadManagerConfig,
+} from "../../../lib/thread";
+import type { MessageContent, ToolMessageContent } from "../../../lib/types";
+
+/** A Content with a unique ID for idempotent Redis storage */
+export interface StoredContent {
+  id: string;
+  content: Content;
+}
+
+export interface GoogleGenAIThreadManagerConfig {
+  redis: Redis;
+  threadId: string;
+  /** Thread key, defaults to 'messages' */
+  key?: string;
+}
+
+/** Thread manager with Google GenAI Content convenience helpers */
+export interface GoogleGenAIThreadManager
+  extends BaseThreadManager<StoredContent> {
+  createUserContent(content: string | MessageContent): StoredContent;
+  createSystemContent(content: string): StoredContent;
+  createModelContent(parts: Part[]): StoredContent;
+  createToolResponseContent(
+    toolCallId: string,
+    toolName: string,
+    content: ToolMessageContent,
+  ): StoredContent;
+  appendUserMessage(content: string | MessageContent): Promise<void>;
+  appendSystemMessage(content: string): Promise<void>;
+  appendModelContent(parts: Part[]): Promise<void>;
+  appendToolResult(
+    toolCallId: string,
+    toolName: string,
+    content: ToolMessageContent,
+  ): Promise<void>;
+}
+
+function storedContentId(msg: StoredContent): string {
+  return msg.id;
+}
+
+/** Convert zeitlich MessageContent to Google GenAI Part[] */
+export function messageContentToParts(
+  content: string | MessageContent,
+): 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 [{ text: String(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 };
+    }
+  }
+  return { result: content };
+}
+
+/**
+ * Creates a Google GenAI-specific thread manager that stores StoredContent
+ * instances in Redis and provides convenience helpers for creating and
+ * appending typed Content messages.
+ */
+export function createGoogleGenAIThreadManager(
+  config: GoogleGenAIThreadManagerConfig,
+): GoogleGenAIThreadManager {
+  const baseConfig: ThreadManagerConfig<StoredContent> = {
+    redis: config.redis,
+    threadId: config.threadId,
+    key: config.key,
+    idOf: storedContentId,
+  };
+
+  const base = createThreadManager(baseConfig);
+
+  const helpers = {
+    createUserContent(content: string | MessageContent): StoredContent {
+      return {
+        id: crypto.randomUUID(),
+        content: { role: "user", parts: messageContentToParts(content) },
+      };
+    },
+
+    createSystemContent(content: string): StoredContent {
+      return {
+        id: crypto.randomUUID(),
+        content: { role: "system", parts: [{ text: content }] },
+      };
+    },
+
+    createModelContent(parts: Part[]): StoredContent {
+      return {
+        id: crypto.randomUUID(),
+        content: { role: "model", parts },
+      };
+    },
+
+    createToolResponseContent(
+      toolCallId: string,
+      toolName: string,
+      content: ToolMessageContent,
+    ): StoredContent {
+      return {
+        id: crypto.randomUUID(),
+        content: {
+          role: "user",
+          parts: [
+            {
+              functionResponse: {
+                id: toolCallId,
+                name: toolName,
+                response: parseToolResponse(content),
+              },
+            },
+          ],
+        },
+      };
+    },
+
+    async appendUserMessage(content: string | MessageContent): Promise<void> {
+      await base.append([helpers.createUserContent(content)]);
+    },
+
+    async appendSystemMessage(content: string): Promise<void> {
+      await base.initialize();
+      await base.append([helpers.createSystemContent(content)]);
+    },
+
+    async appendModelContent(parts: Part[]): Promise<void> {
+      await base.append([helpers.createModelContent(parts)]);
+    },
+
+    async appendToolResult(
+      toolCallId: string,
+      toolName: string,
+      content: ToolMessageContent,
+    ): Promise<void> {
+      await base.append([
+        helpers.createToolResponseContent(toolCallId, toolName, content),
+      ]);
+    },
+  };
+
+  return Object.assign(base, helpers);
+}

package/src/adapters/{langchain → thread/langchain}/activities.ts

@@ -1,24 +1,18 @@
 import type Redis from "ioredis";
-import type { ThreadOps, ToolResultConfig } from "../../lib/types";
+import type { ToolResultConfig } from "../../../lib/types";
 import type { MessageContent } from "@langchain/core/messages";
-import type { ModelInvoker } from "../../lib/model-invoker";
+import type { ThreadOps } from "../../../lib/session/types";
+import type { ModelInvoker } from "../../../lib/model";
 import type { StoredMessage } from "@langchain/core/messages";
-import type {
-  BaseChatModel,
-  BaseChatModelCallOptions,
-  BindToolsInput,
-} from "@langchain/core/language_models/chat_models";
+import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
 import { createLangChainThreadManager } from "./thread-manager";
 import { createLangChainModelInvoker } from "./model-invoker";
 
-type LangChainModel = BaseChatModel<
-  BaseChatModelCallOptions & { tools?: BindToolsInput }
->;
-
 export interface LangChainAdapterConfig {
   redis: Redis;
   /** Optional default model — if omitted, use `createModelInvoker()` to create invokers later */
-  model?: LangChainModel;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  model?: BaseChatModel<any>;
 }
 
 export interface LangChainAdapter {
@@ -27,7 +21,8 @@ export interface LangChainAdapter {
   /** Model invoker using the default model (only available when `model` was provided) */
   invoker: ModelInvoker<StoredMessage>;
   /** Create an invoker for a specific model (for multi-model setups) */
-  createModelInvoker(model: LangChainModel): ModelInvoker<StoredMessage>;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  createModelInvoker(model: BaseChatModel<any>): ModelInvoker<StoredMessage>;
 }
 
 /**
@@ -40,7 +35,7 @@ export interface LangChainAdapter {
  *
  * @example
  * ```typescript
- * import { createLangChainAdapter } from 'zeitlich/adapters/langchain';
+ * import { createLangChainAdapter } from 'zeitlich/adapters/thread/langchain';
  * import { createRunAgentActivity } from 'zeitlich';
  *
  * const adapter = createLangChainAdapter({ redis, model });
@@ -100,7 +95,8 @@ export function createLangChainAdapter(
     },
   };
 
-  const makeInvoker = (model: LangChainModel): ModelInvoker<StoredMessage> =>
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const makeInvoker = (model: BaseChatModel<any>): ModelInvoker<StoredMessage> =>
     createLangChainModelInvoker({ redis, model });
 
   const invoker: ModelInvoker<StoredMessage> = config.model

package/src/adapters/{langchain → thread/langchain}/index.ts

@@ -9,7 +9,7 @@
  * import {
  *   createLangChainAdapter,
  *   createLangChainThreadManager,
- * } from 'zeitlich/adapters/langchain';
+ * } from 'zeitlich/adapters/thread/langchain';
  *
  * const adapter = createLangChainAdapter({ redis, model });
  * ```