zeitlich 0.1.1 → 0.2.0

package/src/activities.ts

@@ -0,0 +1,112 @@
+import type Redis from "ioredis";
+import { createThreadManager } from "./lib/thread-manager";
+import type { ToolResultConfig } from "./lib/types";
+import {
+  type AIMessage,
+  mapStoredMessageToChatMessage,
+  type MessageContent,
+  type StoredMessage,
+} from "@langchain/core/messages";
+import type { RawToolCall } from "./lib/tool-router";
+/**
+ * Shared Zeitlich activities - thread management and message handling
+ * Note: runAgent is workflow-specific and should be created per-workflow
+ */
+export interface ZeitlichSharedActivities {
+  appendSystemMessage(threadId: string, content: string): Promise<void>;
+  /**
+   * Append a tool result to the thread.
+   * Handles JSON serialization and optional cache points.
+   */
+  appendToolResult(config: ToolResultConfig): Promise<void>;
+
+  /**
+   * Initialize an empty thread.
+   */
+  initializeThread(threadId: string): Promise<void>;
+
+  /**
+   * Append a system message to a thread.
+   */
+  appendSystemMessage(threadId: string, content: string): Promise<void>;
+
+  /**
+   * Append messages to a thread.
+   */
+  appendThreadMessages(
+    threadId: string,
+    messages: StoredMessage[]
+  ): Promise<void>;
+
+  /**
+   * Append a human message to a thread.
+   */
+  appendHumanMessage(
+    threadId: string,
+    content: string | MessageContent
+  ): Promise<void>;
+
+  /**
+   * Extract raw tool calls from a stored message.
+   * Returns unvalidated tool calls - use toolRegistry.parseToolCall() to validate.
+   */
+  parseToolCalls(storedMessage: StoredMessage): Promise<RawToolCall[]>;
+}
+
+/**
+ * Creates shared Temporal activities for thread management
+ *
+ * @returns An object containing the shared activity functions
+ *
+ * @experimental The Zeitlich integration is an experimental feature; APIs may change without notice.
+ */
+export function createSharedActivities(redis: Redis): ZeitlichSharedActivities {
+  return {
+    async appendSystemMessage(
+      threadId: string,
+      content: string
+    ): Promise<void> {
+      const thread = createThreadManager({ redis, threadId });
+      await thread.appendSystemMessage(content);
+    },
+
+    async appendToolResult(config: ToolResultConfig): Promise<void> {
+      const { threadId, toolCallId, content } = config;
+      const thread = createThreadManager({ redis, threadId });
+
+      await thread.appendToolMessage(content, toolCallId);
+    },
+
+    async initializeThread(threadId: string): Promise<void> {
+      const thread = createThreadManager({ redis, threadId });
+      await thread.initialize();
+    },
+
+    async appendThreadMessages(
+      threadId: string,
+      messages: StoredMessage[]
+    ): Promise<void> {
+      const thread = createThreadManager({ redis, threadId });
+      await thread.append(messages);
+    },
+
+    async appendHumanMessage(
+      threadId: string,
+      content: string | MessageContent
+    ): Promise<void> {
+      const thread = createThreadManager({ redis, threadId });
+      await thread.appendHumanMessage(content);
+    },
+
+    async parseToolCalls(storedMessage: StoredMessage): Promise<RawToolCall[]> {
+      const message = mapStoredMessageToChatMessage(storedMessage) as AIMessage;
+      const toolCalls = message.tool_calls ?? [];
+
+      return toolCalls.map((toolCall) => ({
+        id: toolCall.id,
+        name: toolCall.name,
+        args: toolCall.args,
+      }));
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+/**
+ * Activity-side exports for use in Temporal activity code and worker setup.
+ *
+ * Import from '@bead-ai/zeitlich' in activity files and worker setup.
+ * These exports may have external dependencies (Redis, LangChain).
+ *
+ * For workflow code, use '@bead-ai/zeitlich/workflow' instead.
+ *
+ * @example
+ * ```typescript
+ * // In your activities file
+ * import { invokeModel, globHandler } from '@bead-ai/zeitlich';
+ *
+ * // In your worker file
+ * import { ZeitlichPlugin } from '@bead-ai/zeitlich';
+ * ```
+ */
+
+// Re-export all workflow-safe exports for convenience
+// (Activities can use these too)
+export * from "./workflow";
+
+// Plugin (requires Redis)
+export { ZeitlichPlugin } from "./plugin";
+export type { ZeitlichPluginOptions } from "./plugin";
+
+// Shared activities (requires Redis)
+export { createSharedActivities } from "./activities";
+export type { ZeitlichSharedActivities } from "./activities";
+
+// Model invocation (requires Redis, LangChain)
+export { invokeModel } from "./lib/model-invoker";
+export type { InvokeModelConfig } from "./lib/model-invoker";
+
+// Tool handlers (activity implementations)
+// These are direct functions that accept scopedNodes per-call for dynamic file trees
+export { handleAskUserQuestionToolResult } from "./tools/ask-user-question/handler";
+export { globHandler } from "./tools/glob/handler";
+
+export { editHandler } from "./tools/edit/handler";
+export type {
+  EditResult,
+  EditHandlerResponse,
+  EditHandlerOptions,
+} from "./tools/edit/handler";
+
+export { handleBashTool } from "./tools/bash/handler";
+
+export { toTree } from "./lib/fs";

package/src/lib/fs.ts

@@ -0,0 +1,80 @@
+import type { IFileSystem } from "just-bash";
+
+const basename = (path: string, separator: string): string => {
+  if (path[path.length - 1] === separator) path = path.slice(0, -1);
+  const lastSlashIndex = path.lastIndexOf(separator);
+  return lastSlashIndex === -1 ? path : path.slice(lastSlashIndex + 1);
+};
+
+const printTree = async (
+  tab = "",
+  children: ((tab: string) => Promise<string | null>)[]
+): Promise<string> => {
+  let str = "";
+  let last = children.length - 1;
+  for (; last >= 0; last--) if (children[last]) break;
+  for (let i = 0; i <= last; i++) {
+    const fn = children[i];
+    if (!fn) continue;
+    const isLast = i === last;
+    const child = await fn(tab + (isLast ? " " : "│") + "  ");
+    const branch = child ? (isLast ? "└─" : "├─") : "│";
+    str += "\n" + tab + branch + (child ? " " + child : "");
+  }
+  return str;
+};
+
+export const toTree = async (
+  fs: IFileSystem,
+  opts: {
+    dir?: string;
+    separator?: "/" | "\\";
+    depth?: number;
+    tab?: string;
+    sort?: boolean;
+  } = {}
+): Promise<string> => {
+  const separator = opts.separator || "/";
+  let dir = opts.dir || separator;
+  if (dir[dir.length - 1] !== separator) dir += separator;
+  const tab = opts.tab || "";
+  const depth = opts.depth ?? 10;
+  const sort = opts.sort ?? true;
+  let subtree = " (...)";
+  if (depth > 0) {
+    const list = (await fs.readdirWithFileTypes?.(dir)) || [];
+    if (sort) {
+      list.sort((a, b) => {
+        if (a.isDirectory && b.isDirectory) {
+          return a.name.toString().localeCompare(b.name.toString());
+        } else if (a.isDirectory) {
+          return -1;
+        } else if (b.isDirectory) {
+          return 1;
+        } else {
+          return a.name.toString().localeCompare(b.name.toString());
+        }
+      });
+    }
+    subtree = await printTree(
+      tab,
+      list.map((entry) => async (tab): Promise<string | null> => {
+        if (entry.isDirectory) {
+          return toTree(fs, {
+            dir: dir + entry.name,
+            depth: depth - 1,
+            tab,
+          });
+        } else if (entry.isSymbolicLink) {
+          return (
+            "" + entry.name + " → " + (await fs.readlink(dir + entry.name))
+          );
+        } else {
+          return "" + entry.name;
+        }
+      })
+    );
+  }
+  const base = basename(dir, separator) + separator;
+  return base + subtree;
+};

package/src/lib/model-invoker.ts

@@ -0,0 +1,75 @@
+import type Redis from "ioredis";
+import { createThreadManager } from "./thread-manager";
+import type { AgentResponse } 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 { getStateQuery } from "./state-manager";
+
+/**
+ * Configuration for invoking the model
+ */
+export interface InvokeModelConfig {
+  threadId: string;
+  agentName: string;
+}
+
+/**
+ * Core model invocation logic - shared utility for workflow-specific activities
+ *
+ * @param redis - Redis client for thread management
+ * @param config - Model invocation configuration
+ * @param model - Pre-instantiated LangChain chat model
+ * @param invocationConfig - Per-invocation configuration (system prompt, etc.)
+ * @returns Agent response with message and metadata
+ */
+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(getStateQuery);
+
+  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()]);
+
+  return {
+    message: response.toDict(),
+    stopReason: (response.response_metadata?.stop_reason as string) ?? null,
+    usage: {
+      input_tokens: response.usage_metadata?.input_tokens,
+      output_tokens: response.usage_metadata?.output_tokens,
+      total_tokens: response.usage_metadata?.total_tokens,
+    },
+  };
+}

package/src/lib/session.ts

@@ -0,0 +1,216 @@
+import { proxyActivities } from "@temporalio/workflow";
+import type { ZeitlichSharedActivities } from "../activities";
+import type {
+  ZeitlichAgentConfig,
+  SessionStartHook,
+  SessionEndHook,
+  SessionExitReason,
+  SubagentConfig,
+} from "./types";
+import { type AgentStateManager, type JsonSerializable } from "./state-manager";
+import {
+  createToolRouter,
+  type ParsedToolCall,
+  type ParsedToolCallUnion,
+  type RawToolCall,
+  type ToolMap,
+} from "./tool-router";
+import type { StoredMessage } from "@langchain/core/messages";
+import { createTaskTool, type TaskToolSchemaType } from "../tools/task/tool";
+
+export interface ZeitlichSession {
+  runSession<T extends JsonSerializable<T>>(args: {
+    stateManager: AgentStateManager<T>;
+  }): Promise<StoredMessage | null>;
+}
+
+async function resolvePrompt(
+  prompt: string | (() => string | Promise<string>)
+): Promise<string> {
+  if (typeof prompt === "function") {
+    return prompt();
+  }
+  return prompt;
+}
+
+/**
+ * Session-level hooks for lifecycle events
+ */
+export interface SessionLifecycleHooks {
+  /** Called when session starts */
+  onSessionStart?: SessionStartHook;
+  /** Called when session ends */
+  onSessionEnd?: SessionEndHook;
+}
+
+export const createSession = async <T extends ToolMap>({
+  threadId,
+  agentName,
+  maxTurns = 50,
+  metadata = {},
+  runAgent,
+  baseSystemPrompt,
+  instructionsPrompt,
+  buildContextMessage,
+  buildFileTree = async (): Promise<string> => "",
+  subagents,
+  tools = {} as T,
+  processToolsInParallel = true,
+  buildInTools = {},
+  hooks = {},
+}: ZeitlichAgentConfig<T>): Promise<ZeitlichSession> => {
+  const {
+    initializeThread,
+    appendHumanMessage,
+    parseToolCalls,
+    appendToolResult,
+    appendSystemMessage,
+  } = proxyActivities<ZeitlichSharedActivities>({
+    startToCloseTimeout: "30m",
+    retry: {
+      maximumAttempts: 6,
+      initialInterval: "5s",
+      maximumInterval: "15m",
+      backoffCoefficient: 4,
+    },
+    heartbeatTimeout: "5m",
+  });
+
+  const fileTree = await buildFileTree();
+
+  const toolRouter = createToolRouter({
+    tools,
+    appendToolResult,
+    threadId,
+    hooks,
+    buildInTools,
+    fileTree,
+    subagents,
+    parallel: processToolsInParallel,
+  });
+
+  // Helper to call session end hook
+  const callSessionEnd = async (
+    exitReason: SessionExitReason,
+    turns: number
+  ): Promise<void> => {
+    if (hooks.onSessionEnd) {
+      await hooks.onSessionEnd({
+        threadId,
+        agentName,
+        exitReason,
+        turns,
+        metadata,
+      });
+    }
+  };
+
+  return {
+    runSession: async ({ stateManager }): Promise<StoredMessage | null> => {
+      if (hooks.onSessionStart) {
+        await hooks.onSessionStart({
+          threadId,
+          agentName,
+          metadata,
+        });
+      }
+
+      stateManager.setTools(toolRouter.getToolDefinitions());
+
+      await initializeThread(threadId);
+      await appendSystemMessage(
+        threadId,
+        [
+          await resolvePrompt(baseSystemPrompt),
+          await resolvePrompt(instructionsPrompt),
+        ].join("\n")
+      );
+      await appendHumanMessage(threadId, await buildContextMessage());
+
+      let exitReason: SessionExitReason = "completed";
+
+      try {
+        while (
+          stateManager.isRunning() &&
+          !stateManager.isTerminal() &&
+          stateManager.getTurns() < maxTurns
+        ) {
+          stateManager.incrementTurns();
+          const currentTurn = stateManager.getTurns();
+
+          const { message, stopReason } = await runAgent({
+            threadId,
+            agentName,
+            metadata,
+          });
+
+          if (stopReason === "end_turn") {
+            stateManager.complete();
+            exitReason = "completed";
+            return message;
+          }
+
+          // No tools configured - treat any non-end_turn as completed
+          if (!toolRouter.hasTools()) {
+            stateManager.complete();
+            exitReason = "completed";
+            return message;
+          }
+
+          const rawToolCalls: RawToolCall[] = await parseToolCalls(message);
+          const parsedToolCalls = rawToolCalls
+            .filter((tc: RawToolCall) => tc.name !== "Task")
+            .map((tc: RawToolCall) => toolRouter.parseToolCall(tc));
+          const taskToolCalls =
+            subagents && subagents.length > 0
+              ? rawToolCalls
+                  .filter((tc: RawToolCall) => tc.name === "Task")
+                  .map((tc: RawToolCall) => {
+                    // Parse and validate args using the tool's schema
+                    const parsedArgs = createTaskTool(subagents).schema.parse(
+                      tc.args
+                    );
+
+                    return {
+                      id: tc.id ?? "",
+                      name: tc.name,
+                      args: parsedArgs,
+                    } as ParsedToolCall<
+                      "Task",
+                      TaskToolSchemaType<SubagentConfig[]>
+                    >;
+                  })
+              : [];
+
+          // Hooks can call stateManager.waitForInput() to pause the session
+          await toolRouter.processToolCalls(
+            [...parsedToolCalls, ...taskToolCalls] as ParsedToolCallUnion<
+              T & { Task: TaskToolSchemaType<SubagentConfig[]> }
+            >[],
+            {
+              turn: currentTurn,
+            }
+          );
+
+          if (stateManager.getStatus() === "WAITING_FOR_INPUT") {
+            exitReason = "waiting_for_input";
+            break;
+          }
+        }
+
+        // Check if we hit max turns
+        if (stateManager.getTurns() >= maxTurns && stateManager.isRunning()) {
+          exitReason = "max_turns";
+        }
+      } catch (error) {
+        exitReason = "failed";
+        throw error;
+      } finally {
+        // SessionEnd hook - always called
+        await callSessionEnd(exitReason, stateManager.getTurns());
+      }
+
+      return null;
+    },
+  };
+};