zeitlich 0.2.11 → 0.2.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zeitlich",
-  "version": "0.2.11",
+  "version": "0.2.13",
   "description": "[EXPERIMENTAL] An opinionated AI agent implementation for Temporal",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -26,6 +26,16 @@
         "types": "./dist/workflow.d.ts",
         "default": "./dist/workflow.js"
       }
+    },
+    "./adapters/langchain": {
+      "import": {
+        "types": "./dist/adapters/langchain/index.d.ts",
+        "default": "./dist/adapters/langchain/index.js"
+      },
+      "require": {
+        "types": "./dist/adapters/langchain/index.d.ts",
+        "default": "./dist/adapters/langchain/index.js"
+      }
     }
   },
   "files": [
@@ -82,15 +92,20 @@
     "vitest": "^4.0.18"
   },
   "peerDependencies": {
+    "@langchain/core": ">=1.0.0",
     "ioredis": ">=5.0.0"
   },
+  "peerDependenciesMeta": {
+    "@langchain/core": {
+      "optional": true
+    }
+  },
   "type": "module",
   "bugs": {
     "url": "https://github.com/bead-ai/zeitlich/issues"
   },
   "homepage": "https://github.com/bead-ai/zeitlich#readme",
   "dependencies": {
-    "@langchain/core": "^1.1.29",
     "@temporalio/common": "^1.15.0",
     "@temporalio/plugin": "^1.15.0",
     "@temporalio/workflow": "^1.15.0",

package/src/adapters/langchain/activities.ts

@@ -0,0 +1,120 @@
+import type Redis from "ioredis";
+import type { ThreadOps, ToolResultConfig } from "../../lib/types";
+import type { MessageContent } from "@langchain/core/messages";
+import type { ModelInvoker } from "../../lib/model-invoker";
+import type { StoredMessage } from "@langchain/core/messages";
+import type {
+  BaseChatModel,
+  BaseChatModelCallOptions,
+  BindToolsInput,
+} 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;
+}
+
+export interface LangChainAdapter {
+  /** 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<StoredMessage>;
+  /** Create an invoker for a specific model (for multi-model setups) */
+  createModelInvoker(model: LangChainModel): ModelInvoker<StoredMessage>;
+}
+
+/**
+ * Creates a LangChain adapter that bundles thread operations and model
+ * invocation using a consistent message format (StoredMessage).
+ *
+ * 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 { createLangChainAdapter } from 'zeitlich/adapters/langchain';
+ * import { createRunAgentActivity } from 'zeitlich';
+ *
+ * const adapter = createLangChainAdapter({ redis, model });
+ *
+ * export function createActivities(client: WorkflowClient) {
+ *   return {
+ *     ...adapter.threadOps,
+ *     runAgent: createRunAgentActivity(client, adapter.invoker),
+ *   };
+ * }
+ * ```
+ *
+ * @example Multi-model setup
+ * ```typescript
+ * const adapter = createLangChainAdapter({ redis });
+ *
+ * export function createActivities(client: WorkflowClient) {
+ *   return {
+ *     ...adapter.threadOps,
+ *     runResearchAgent: createRunAgentActivity(client, adapter.createModelInvoker(claude)),
+ *     runWriterAgent: createRunAgentActivity(client, adapter.createModelInvoker(gpt4)),
+ *   };
+ * }
+ * ```
+ */
+export function createLangChainAdapter(
+  config: LangChainAdapterConfig
+): LangChainAdapter {
+  const { redis } = config;
+
+  const threadOps: ThreadOps = {
+    async initializeThread(threadId: string): Promise<void> {
+      const thread = createLangChainThreadManager({ redis, threadId });
+      await thread.initialize();
+    },
+
+    async appendHumanMessage(
+      threadId: string,
+      content: string | MessageContent
+    ): Promise<void> {
+      const thread = createLangChainThreadManager({ redis, threadId });
+      await thread.appendHumanMessage(content);
+    },
+
+    async appendSystemMessage(
+      threadId: string,
+      content: string
+    ): Promise<void> {
+      const thread = createLangChainThreadManager({ redis, threadId });
+      await thread.appendSystemMessage(content);
+    },
+
+    async appendToolResult(cfg: ToolResultConfig): Promise<void> {
+      const { threadId, toolCallId, content } = cfg;
+      const thread = createLangChainThreadManager({ redis, threadId });
+      await thread.appendToolMessage(content, toolCallId);
+    },
+  };
+
+  const makeInvoker = (model: LangChainModel): ModelInvoker<StoredMessage> =>
+    createLangChainModelInvoker({ redis, model });
+
+  const invoker: ModelInvoker<StoredMessage> = config.model
+    ? makeInvoker(config.model)
+    : ((() => {
+        throw new Error(
+          "No default model provided to createLangChainAdapter. " +
+            "Either pass `model` in the config or use `createModelInvoker(model)` instead."
+        );
+      }) as unknown as ModelInvoker<StoredMessage>);
+
+  return {
+    threadOps,
+    invoker,
+    createModelInvoker: makeInvoker,
+  };
+}

package/src/adapters/langchain/index.ts

@@ -0,0 +1,38 @@
+/**
+ * LangChain adapter for Zeitlich.
+ *
+ * Provides a unified adapter that bundles thread management and model
+ * invocation using LangChain's StoredMessage format.
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   createLangChainAdapter,
+ *   createLangChainThreadManager,
+ * } from 'zeitlich/adapters/langchain';
+ *
+ * const adapter = createLangChainAdapter({ redis, model });
+ * ```
+ */
+
+// Adapter (primary API)
+export {
+  createLangChainAdapter,
+  type LangChainAdapter,
+  type LangChainAdapterConfig,
+} from "./activities";
+
+// Thread manager
+export {
+  createLangChainThreadManager,
+  type LangChainThreadManager,
+  type LangChainThreadManagerConfig,
+  type LangChainToolMessageContent,
+} from "./thread-manager";
+
+// Model invoker (for advanced use — prefer adapter.createModelInvoker)
+export {
+  createLangChainModelInvoker,
+  invokeLangChainModel,
+  type LangChainModelInvokerConfig,
+} from "./model-invoker";

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

@@ -0,0 +1,102 @@
+import type Redis from "ioredis";
+import type { AgentResponse } from "../../lib/types";
+import type { ModelInvokerConfig } from "../../lib/model-invoker";
+import { mapStoredMessagesToChatMessages } from "@langchain/core/messages";
+import type { StoredMessage } from "@langchain/core/messages";
+import { v4 as uuidv4 } from "uuid";
+import type {
+  BaseChatModel,
+  BaseChatModelCallOptions,
+  BindToolsInput,
+} from "@langchain/core/language_models/chat_models";
+import { createLangChainThreadManager } from "./thread-manager";
+
+export interface LangChainModelInvokerConfig {
+  redis: Redis;
+  model: BaseChatModel<BaseChatModelCallOptions & { tools?: BindToolsInput }>;
+}
+
+/**
+ * Creates a LangChain-based model invoker that satisfies the generic
+ * `ModelInvoker<StoredMessage>` contract.
+ *
+ * Loads the conversation thread from Redis, invokes a LangChain chat model,
+ * appends the AI response, and returns a normalised AgentResponse.
+ *
+ * @example
+ * ```typescript
+ * import { createLangChainModelInvoker } from 'zeitlich/adapters/langchain';
+ * import { createRunAgentActivity } from 'zeitlich';
+ * import { ChatAnthropic } from '@langchain/anthropic';
+ *
+ * const model = new ChatAnthropic({ model: "claude-sonnet-4-6" });
+ * const invoker = createLangChainModelInvoker({ redis, model });
+ *
+ * // Wrap with createRunAgentActivity to use as runAgent activity:
+ * return { runAgent: createRunAgentActivity(client, invoker) };
+ * ```
+ */
+export function createLangChainModelInvoker({
+  redis,
+  model,
+}: LangChainModelInvokerConfig) {
+  return async function invokeLangChainModel(
+    config: ModelInvokerConfig
+  ): Promise<AgentResponse<StoredMessage>> {
+    const { threadId, agentName, state, metadata } = config;
+
+    const thread = createLangChainThreadManager({ redis, threadId });
+    const runId = uuidv4();
+
+    const messages = await thread.load();
+    const response = await model.invoke(
+      [...mapStoredMessagesToChatMessages(messages)],
+      {
+        runName: agentName,
+        runId,
+        metadata: { thread_id: threadId, ...metadata },
+        tools: state.tools,
+      }
+    );
+
+    await thread.append([response.toDict()]);
+
+    const toolCalls = response.tool_calls ?? [];
+
+    return {
+      message: response.toDict(),
+      rawToolCalls: toolCalls.map((tc) => ({
+        id: tc.id,
+        name: tc.name,
+        args: tc.args,
+      })),
+      usage: {
+        inputTokens: response.usage_metadata?.input_tokens,
+        outputTokens: response.usage_metadata?.output_tokens,
+        reasonTokens: response.usage_metadata?.output_token_details?.reasoning,
+        cachedWriteTokens:
+          response.usage_metadata?.input_token_details?.cache_creation,
+        cachedReadTokens:
+          response.usage_metadata?.input_token_details?.cache_read,
+      },
+    };
+  };
+}
+
+/**
+ * Standalone function for one-shot LangChain model invocation.
+ * Convenience wrapper around createLangChainModelInvoker for cases where
+ * you don't need to reuse the invoker.
+ */
+export async function invokeLangChainModel({
+  redis,
+  model,
+  config,
+}: {
+  redis: Redis;
+  config: ModelInvokerConfig;
+  model: BaseChatModel<BaseChatModelCallOptions & { tools?: BindToolsInput }>;
+}): Promise<AgentResponse<StoredMessage>> {
+  const invoker = createLangChainModelInvoker({ redis, model });
+  return invoker(config);
+}

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

@@ -0,0 +1,142 @@
+import type Redis from "ioredis";
+import {
+  type $InferMessageContent,
+  AIMessage,
+  HumanMessage,
+  type MessageContent,
+  type MessageStructure,
+  type StoredMessage,
+  SystemMessage,
+  ToolMessage,
+} from "@langchain/core/messages";
+import { v4 as uuidv4 } from "uuid";
+import {
+  createThreadManager,
+  type BaseThreadManager,
+  type ThreadManagerConfig,
+} from "../../lib/thread-manager";
+
+export type LangChainToolMessageContent = $InferMessageContent<
+  MessageStructure,
+  "tool"
+>;
+
+export interface LangChainThreadManagerConfig {
+  redis: Redis;
+  threadId: string;
+  /** Thread key, defaults to 'messages' */
+  key?: string;
+}
+
+/** Thread manager with LangChain StoredMessage convenience helpers */
+export interface LangChainThreadManager extends BaseThreadManager<StoredMessage> {
+  createHumanMessage(content: string | MessageContent): StoredMessage;
+  createSystemMessage(content: string): StoredMessage;
+  createAIMessage(
+    content: string | MessageContent,
+    kwargs?: { header?: string; options?: string[]; multiSelect?: boolean },
+  ): StoredMessage;
+  createToolMessage(
+    content: LangChainToolMessageContent,
+    toolCallId: string,
+  ): StoredMessage;
+  appendHumanMessage(content: string | MessageContent): Promise<void>;
+  appendSystemMessage(content: string): Promise<void>;
+  appendToolMessage(
+    content: LangChainToolMessageContent,
+    toolCallId: string,
+  ): Promise<void>;
+  appendAIMessage(content: string | MessageContent): Promise<void>;
+}
+
+function storedMessageId(msg: StoredMessage): string {
+  return msg.data.id ?? "";
+}
+
+/**
+ * Creates a LangChain-specific thread manager that stores StoredMessage
+ * instances in Redis and provides convenience helpers for creating and
+ * appending typed LangChain messages.
+ */
+export function createLangChainThreadManager(
+  config: LangChainThreadManagerConfig,
+): LangChainThreadManager {
+  const baseConfig: ThreadManagerConfig<StoredMessage> = {
+    redis: config.redis,
+    threadId: config.threadId,
+    key: config.key,
+    idOf: storedMessageId,
+  };
+
+  const base = createThreadManager(baseConfig);
+
+  const helpers = {
+    createHumanMessage(content: string | MessageContent): StoredMessage {
+      return new HumanMessage({
+        id: uuidv4(),
+        content: content as string,
+      }).toDict();
+    },
+
+    createSystemMessage(content: string): StoredMessage {
+      return new SystemMessage({
+        id: uuidv4(),
+        content: content as string,
+      }).toDict();
+    },
+
+    createAIMessage(
+      content: string,
+      kwargs?: { header?: string; options?: string[]; multiSelect?: boolean },
+    ): StoredMessage {
+      return new AIMessage({
+        id: uuidv4(),
+        content,
+        additional_kwargs: kwargs
+          ? {
+              header: kwargs.header,
+              options: kwargs.options,
+              multiSelect: kwargs.multiSelect,
+            }
+          : undefined,
+      }).toDict();
+    },
+
+    createToolMessage(
+      content: LangChainToolMessageContent,
+      toolCallId: string,
+    ): StoredMessage {
+      return new ToolMessage({
+        id: uuidv4(),
+        content: content as MessageContent,
+        tool_call_id: toolCallId,
+      }).toDict();
+    },
+
+    async appendHumanMessage(content: string | MessageContent): Promise<void> {
+      const message = helpers.createHumanMessage(content);
+      await base.append([message]);
+    },
+
+    async appendToolMessage(
+      content: LangChainToolMessageContent,
+      toolCallId: string,
+    ): Promise<void> {
+      const message = helpers.createToolMessage(content, toolCallId);
+      await base.append([message]);
+    },
+
+    async appendAIMessage(content: string | MessageContent): Promise<void> {
+      const message = helpers.createAIMessage(content as string);
+      await base.append([message]);
+    },
+
+    async appendSystemMessage(content: string): Promise<void> {
+      const message = helpers.createSystemMessage(content);
+      await base.initialize();
+      await base.append([message]);
+    },
+  };
+
+  return Object.assign(base, helpers);
+}

package/src/index.ts

@@ -1,18 +1,22 @@
 /**
  * Activity-side exports for use in Temporal activity code and worker setup.
  *
- * Import from 'zeitlich' in activity files and worker setup.
- * These exports may have external dependencies (Redis, LangChain).
- *
- * For workflow code, use 'zeitlich/workflow' instead.
+ * Import from `zeitlich` in activity files and worker setup.
+ * For LangChain-specific adapters (model invoker, thread manager, adapter),
+ * import from `zeitlich/adapters/langchain`.
+ * For workflow code, use `zeitlich/workflow` instead.
  *
  * @example
  * ```typescript
  * // In your activities file
- * import { invokeModel, createGlobHandler } from 'zeitlich';
+ * import {
+ *   createBashHandler,
+ *   createAskUserQuestionHandler,
+ *   toTree,
+ * } from 'zeitlich';
  *
- * // In your worker file
- * import { ZeitlichPlugin } from 'zeitlich';
+ * // LangChain adapter
+ * import { createLangChainAdapter } from 'zeitlich/adapters/langchain';
  * ```
  */
 
@@ -20,20 +24,24 @@
 // (Activities can use these too)
 export * from "./workflow";
 
-// Plugin (requires Redis)
-export { ZeitlichPlugin } from "./plugin";
-export type { ZeitlichPluginOptions } from "./plugin";
+// Thread manager (generic, framework-agnostic)
+export { createThreadManager } from "./lib/thread-manager";
+export type {
+  BaseThreadManager,
+  ThreadManagerConfig,
+} from "./lib/thread-manager";
 
-// Shared activities (requires Redis)
-export { createSharedActivities } from "./activities";
-export type { ZeitlichSharedActivities } from "./activities";
+// Model invoker contract (framework-agnostic)
+export type { ModelInvoker, ModelInvokerConfig } from "./lib/model-invoker";
 
 // Auto-append wrapper for large tool results (activity-side only)
 export { withAutoAppend } from "./lib/tool-router";
 
-// Model invocation (requires Redis, LangChain)
-export { invokeModel } from "./lib/model-invoker";
-export type { InvokeModelConfig } from "./lib/model-invoker";
+// Workflow state helpers (requires Temporal client)
+export {
+  queryParentWorkflowState,
+  createRunAgentActivity,
+} from "./lib/workflow-helpers";
 
 // Tool handlers (activity implementations)
 // All handlers follow the factory pattern: createXHandler(deps) => handler(args)
@@ -47,10 +55,3 @@ export { toTree } from "./lib/fs";
 
 // Skills (activity-side: filesystem provider)
 export { FileSystemSkillProvider } from "./lib/skills/fs-provider";
-
-export { createThreadManager } from "./lib/thread-manager";
-export type {
-  BaseThreadManager,
-  ThreadManager,
-  ThreadManagerConfig,
-} from "./lib/thread-manager";

package/src/lib/fs.ts

@@ -24,6 +24,31 @@ const printTree = async (
   return str;
 };
 
+/**
+ * Generates a formatted file tree string from an `IFileSystem` instance.
+ * Useful for including filesystem context in agent prompts.
+ *
+ * @param fs - File system implementation (e.g. from `just-bash`)
+ * @param opts - Optional configuration for tree generation
+ * @param opts.dir - Root directory to start from (defaults to `/`)
+ * @param opts.separator - Path separator (`/` or `\\`, defaults to `/`)
+ * @param opts.depth - Maximum directory depth (defaults to 10)
+ * @param opts.sort - Sort entries alphabetically with directories first (defaults to true)
+ * @returns Formatted file tree string
+ *
+ * @example
+ * ```typescript
+ * import { toTree } from 'zeitlich';
+ *
+ * const fileTree = await toTree(inMemoryFileSystem);
+ * // Returns:
+ * // /
+ * // ├─ src/
+ * // │  ├─ index.ts
+ * // │  └─ utils.ts
+ * // └─ package.json
+ * ```
+ */
 export const toTree = async (
   fs: IFileSystem,
   opts: {

package/src/lib/model-invoker.ts

@@ -1,85 +1,25 @@
-import type Redis from "ioredis";
-import { createThreadManager } from "./thread-manager";
-import { agentQueryName, type AgentResponse, type BaseAgentState } from "./types";
-import { Context } from "@temporalio/activity";
-import type { WorkflowClient } from "@temporalio/client";
-import { mapStoredMessagesToChatMessages } from "@langchain/core/messages";
-import { v4 as uuidv4 } from "uuid";
-import type {
-  BaseChatModel,
-  BaseChatModelCallOptions,
-  BindToolsInput,
-} from "@langchain/core/language_models/chat_models";
+import type { AgentResponse, BaseAgentState } from "./types";
 
 /**
- * Configuration for invoking the model
+ * Configuration passed to a ModelInvoker.
+ * Includes the full agent state so adapters can read tools, system prompt,
+ * token usage, or any custom state fields for model configuration.
  */
-export interface InvokeModelConfig {
+export interface ModelInvokerConfig {
   threadId: string;
   agentName: string;
+  state: BaseAgentState;
+  metadata?: Record<string, unknown>;
 }
 
 /**
- * Core model invocation logic - shared utility for workflow-specific activities
+ * Generic model invocation contract.
+ * Implementations load the thread, call the LLM, append the response,
+ * and return a normalised AgentResponse.
  *
- * @param options - Named options object
- * @param options.redis - Redis client for thread management
- * @param options.config - Model invocation configuration (threadId, agentName)
- * @param options.model - Pre-instantiated LangChain chat model
- * @param options.client - Temporal WorkflowClient for querying workflow state
- * @returns Agent response with message and metadata
+ * Framework adapters (e.g. `zeitlich/langchain`) provide concrete
+ * implementations of this type.
  */
-export async function invokeModel({
-  redis,
-  model,
-  client,
-  config: { threadId, agentName },
-}: {
-  redis: Redis;
-  client: WorkflowClient;
-  config: InvokeModelConfig;
-  model: BaseChatModel<BaseChatModelCallOptions & { tools?: BindToolsInput }>;
-}): Promise<AgentResponse> {
-  const thread = createThreadManager({ redis, threadId });
-  const runId = uuidv4();
-
-  const info = Context.current().info; // Activity info
-  const parentWorkflowId = info.workflowExecution.workflowId;
-  const parentRunId = info.workflowExecution.runId;
-
-  const handle = client.getHandle(parentWorkflowId, parentRunId);
-  const { tools } = await handle.query<BaseAgentState>(agentQueryName(agentName));
-
-  const messages = await thread.load();
-  const response = await model.invoke(
-    [...mapStoredMessagesToChatMessages(messages)],
-    {
-      runName: agentName,
-      runId,
-      metadata: { thread_id: threadId },
-      tools,
-    }
-  );
-
-  await thread.append([response.toDict()]);
-
-  const toolCalls = response.tool_calls ?? [];
-
-  return {
-    message: response.toDict(),
-    rawToolCalls: toolCalls.map((tc) => ({
-      id: tc.id,
-      name: tc.name,
-      args: tc.args,
-    })),
-    usage: {
-      inputTokens: response.usage_metadata?.input_tokens,
-      outputTokens: response.usage_metadata?.output_tokens,
-      reasonTokens: response.usage_metadata?.output_token_details?.reasoning,
-      cachedWriteTokens:
-        response.usage_metadata?.input_token_details?.cache_creation,
-      cachedReadTokens:
-        response.usage_metadata?.input_token_details?.cache_read,
-    },
-  };
-}
+export type ModelInvoker<M = unknown> = (
+  config: ModelInvokerConfig
+) => Promise<AgentResponse<M>>;