zeitlich 0.2.4 → 0.2.6

package/README.md

@@ -1,5 +1,6 @@
 [![npm version](https://img.shields.io/npm/v/zeitlich.svg?style=flat-square)](https://www.npmjs.org/package/zeitlich)
 [![npm downloads](https://img.shields.io/npm/dm/zeitlich.svg?style=flat-square)](https://npm-stat.com/charts.html?package=zeitlich)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/bead-ai/zeitlich)
 
 # Zeitlich
 
@@ -51,7 +52,7 @@ const google = new ChatGoogleGenerativeAI({ model: "gemini-1.5-pro" });
 
 // Pass to invokeModel in your activity
 return {
-  runAgent: (config) => invokeModel(redis, config, anthropic),
+  runAgent: (config) => invokeModel({ config, model: anthropic, redis, client }),
 };
 ```
 
@@ -121,17 +122,25 @@ export const searchTool: ToolDefinition<"Search", typeof searchSchema> = {
 
 ```typescript
 import type Redis from "ioredis";
+import type { WorkflowClient } from "@temporalio/client";
 import { ChatAnthropic } from "@langchain/anthropic";
-import { invokeModel } from "zeitlich";
-
-export const createActivities = (redis: Redis) => {
+import { invokeModel, type InvokeModelConfig } from "zeitlich";
+
+export const createActivities = ({
+  redis,
+  client,
+}: {
+  redis: Redis;
+  client: WorkflowClient;
+}) => {
   const model = new ChatAnthropic({
     model: "claude-sonnet-4-20250514",
     maxTokens: 4096,
   });
 
   return {
-    runAgent: (config) => invokeModel(redis, config, model),
+    runAgent: (config: InvokeModelConfig) =>
+      invokeModel({ config, model, redis, client }),
 
     handleSearchResult: async ({ args }) => {
       const results = await performSearch(args.query);
@@ -147,12 +156,24 @@ export type MyActivities = ReturnType<typeof createActivities>;
 
 ```typescript
 import { proxyActivities, workflowInfo } from "@temporalio/workflow";
-import { createAgentStateManager, createSession } from "zeitlich/workflow";
+import {
+  createAgentStateManager,
+  createSession,
+  defineTool,
+  proxyDefaultThreadOps,
+} from "zeitlich/workflow";
 import { searchTool } from "./tools";
 import type { MyActivities } from "./activities";
 
 const { runAgent, handleSearchResult } = proxyActivities<MyActivities>({
   startToCloseTimeout: "30m",
+  retry: {
+    maximumAttempts: 6,
+    initialInterval: "5s",
+    maximumInterval: "15m",
+    backoffCoefficient: 4,
+  },
+  heartbeatTimeout: "5m",
 });
 
 export async function myAgentWorkflow({ prompt }: { prompt: string }) {
@@ -164,13 +185,15 @@ export async function myAgentWorkflow({ prompt }: { prompt: string }) {
     threadId: runId,
     agentName: "my-agent",
     maxTurns: 20,
+    systemPrompt: "You are a helpful assistant.",
     runAgent,
+    threadOps: proxyDefaultThreadOps(),
     buildContextMessage: () => [{ type: "text", text: prompt }],
     tools: {
-      Search: {
+      Search: defineTool({
         ...searchTool,
         handler: handleSearchResult,
-      },
+      }),
     },
   });
 
@@ -183,6 +206,7 @@ export async function myAgentWorkflow({ prompt }: { prompt: string }) {
 
 ```typescript
 import { Worker, NativeConnection } from "@temporalio/worker";
+import { Client } from "@temporalio/client";
 import { ZeitlichPlugin } from "zeitlich";
 import Redis from "ioredis";
 import { createActivities } from "./activities";
@@ -191,6 +215,7 @@ async function run() {
   const connection = await NativeConnection.connect({
     address: "localhost:7233",
   });
+  const client = new Client({ connection });
   const redis = new Redis({ host: "localhost", port: 6379 });
 
   const worker = await Worker.create({
@@ -198,7 +223,7 @@ async function run() {
     connection,
     taskQueue: "my-agent",
     workflowsPath: require.resolve("./workflows"),
-    activities: createActivities(redis),
+    activities: createActivities({ redis, client: client.workflow }),
   });
 
   await worker.run();
@@ -242,14 +267,14 @@ const searchTool: ToolDefinition<"Search", typeof searchSchema> = {
   schema: z.object({ query: z.string() }),
 };
 
-// In workflow - combine tool definition with handler
+// In workflow - combine tool definition with handler using defineTool()
 const session = await createSession({
   // ... other config
   tools: {
-    Search: {
+    Search: defineTool({
       ...searchTool,
       handler: handleSearchResult, // Activity that implements the tool
-    },
+    }),
   },
 });
 ```
@@ -288,20 +313,17 @@ const session = await createSession({
 Spawn child agents as Temporal child workflows:
 
 ```typescript
+// Define subagent workflows (each is a Temporal workflow that returns string | null)
+export const researcherSubagent = {
+  name: "researcher",
+  description: "Researches topics and returns findings",
+  workflow: researcherWorkflow,
+};
+
+// In the main agent workflow
 const session = await createSession({
   // ... other config
-  subagents: [
-    {
-      name: "researcher",
-      description: "Researches topics and returns findings",
-      workflow: "researcherWorkflow",
-    },
-    {
-      name: "code-reviewer",
-      description: "Reviews code for quality and best practices",
-      workflow: "codeReviewerWorkflow",
-    },
-  ],
+  subagents: [researcherSubagent, codeReviewerSubagent],
 });
 ```
 
@@ -327,18 +349,26 @@ const session = await createSession({
 });
 ```
 
-For more advanced file operations, use the built-in tool handlers:
+For more advanced file operations, use the built-in tool handler factories:
 
 ```typescript
-import { globHandler, editHandler, toTree } from "zeitlich";
+import { createGlobHandler, createEditHandler, toTree } from "zeitlich";
 
 export const createActivities = () => ({
   generateFileTree: () => toTree("/workspace"),
-  handleGlob: (args) => globHandler(args),
-  handleEdit: (args) => editHandler(args, { basePath: "/workspace" }),
+  globHandlerActivity: createGlobHandler("/workspace"),
+  editHandlerActivity: createEditHandler("/workspace"),
 });
 ```
 
+`toTree` also accepts an in-memory filesystem object (e.g. from [`just-bash`](https://github.com/nicholasgasior/just-bash)):
+
+```typescript
+import { toTree } from "zeitlich";
+
+const fileTree = toTree(inMemoryFileSystem);
+```
+
 ### Built-in Tools
 
 Zeitlich provides ready-to-use tool definitions and handlers for common agent operations.
@@ -366,12 +396,12 @@ import {
   askUserQuestionTool,
 } from "zeitlich/workflow";
 
-// Import handlers in activities
+// Import handler factories in activities
 import {
-  editHandler,
-  globHandler,
-  handleBashTool,
-  handleAskUserQuestionToolResult,
+  createEditHandler,
+  createGlobHandler,
+  createBashHandler,
+  createAskUserQuestionHandler,
 } from "zeitlich";
 ```
 
@@ -381,14 +411,14 @@ All tools are passed via `tools`. The Bash tool's description is automatically e
 const session = await createSession({
   // ... other config
   tools: {
-    AskUserQuestion: {
+    AskUserQuestion: defineTool({
       ...askUserQuestionTool,
-      handler: handleAskUserQuestionToolResult,
-    },
-    Bash: {
+      handler: askUserQuestionHandlerActivity,
+    }),
+    Bash: defineTool({
       ...bashTool,
-      handler: handleBashTool(bashOptions),
-    },
+      handler: bashHandlerActivity,
+    }),
   },
 });
 ```
@@ -419,7 +449,7 @@ For use in activities, worker setup, and Node.js code:
 | `createSharedActivities` | Creates thread management activities                                              |
 | `invokeModel`            | Core LLM invocation utility (requires Redis + LangChain)                          |
 | `toTree`                 | Generate file tree string from a directory path                                   |
-| Tool handlers            | `globHandler`, `editHandler`, `handleBashTool`, `handleAskUserQuestionToolResult` |
+| Tool handlers            | `createGlobHandler`, `createEditHandler`, `createBashHandler`, `createAskUserQuestionHandler` |
 
 ### Types
 

package/dist/index.cjs

@@ -16,7 +16,7 @@ var crypto__default = /*#__PURE__*/_interopDefault(crypto);
 // src/lib/session.ts
 var SUBAGENT_TOOL = "Subagent";
 function buildSubagentDescription(subagents) {
-  const subagentList = subagents.map((s) => `- **${s.name}**: ${s.description}`).join("\n");
+  const subagentList = subagents.map((s) => `- **${s.agentName}**: ${s.description}`).join("\n");
   return `Launch a new agent to handle complex tasks autonomously.
 
 The ${SUBAGENT_TOOL} tool launches specialized agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
@@ -42,7 +42,7 @@ function createSubagentTool(subagents) {
   if (subagents.length === 0) {
     throw new Error("createTaskTool requires at least one subagent");
   }
-  const names = subagents.map((s) => s.name);
+  const names = subagents.map((s) => s.agentName);
   return {
     name: SUBAGENT_TOOL,
     description: buildSubagentDescription(subagents),
@@ -54,15 +54,15 @@ function createSubagentTool(subagents) {
   };
 }
 function createSubagentHandler(subagents) {
-  const { workflowId: parentWorkflowId, taskQueue: parentTaskQueue } = workflow.workflowInfo();
+  const { taskQueue: parentTaskQueue } = workflow.workflowInfo();
   return async (args) => {
-    const config = subagents.find((s) => s.name === args.subagent);
+    const config = subagents.find((s) => s.agentName === args.subagent);
     if (!config) {
       throw new Error(
-        `Unknown subagent: ${args.subagent}. Available: ${subagents.map((s) => s.name).join(", ")}`
+        `Unknown subagent: ${args.subagent}. Available: ${subagents.map((s) => s.agentName).join(", ")}`
       );
     }
-    const childWorkflowId = `${parentWorkflowId}-${args.subagent}-${workflow.uuid4()}`;
+    const childWorkflowId = `${args.subagent}-${workflow.uuid4()}`;
     const input = {
       prompt: args.prompt,
       ...config.context && { context: config.context }
@@ -90,31 +90,36 @@ function createToolRouter(options) {
   }
   const isEnabled = (tool) => tool.enabled !== false;
   if (options.subagents) {
-    const subagentHooksMap = /* @__PURE__ */ new Map();
-    for (const s of options.subagents) {
-      if (s.hooks) subagentHooksMap.set(s.name, s.hooks);
-    }
-    const resolveSubagentName = (args) => args.subagent;
-    toolMap.set("Subagent", {
-      ...createSubagentTool(options.subagents),
-      handler: createSubagentHandler(options.subagents),
-      ...subagentHooksMap.size > 0 && {
-        hooks: {
-          onPreToolUse: async (ctx) => {
-            const hooks = subagentHooksMap.get(resolveSubagentName(ctx.args));
-            return hooks?.onPreExecution?.(ctx) ?? {};
-          },
-          onPostToolUse: async (ctx) => {
-            const hooks = subagentHooksMap.get(resolveSubagentName(ctx.args));
-            await hooks?.onPostExecution?.(ctx);
-          },
-          onPostToolUseFailure: async (ctx) => {
-            const hooks = subagentHooksMap.get(resolveSubagentName(ctx.args));
-            return hooks?.onExecutionFailure?.(ctx) ?? {};
+    const enabledSubagents = options.subagents.filter(
+      (s) => s.enabled !== false
+    );
+    if (enabledSubagents.length > 0) {
+      const subagentHooksMap = /* @__PURE__ */ new Map();
+      for (const s of enabledSubagents) {
+        if (s.hooks) subagentHooksMap.set(s.agentName, s.hooks);
+      }
+      const resolveSubagentName = (args) => args.subagent;
+      toolMap.set("Subagent", {
+        ...createSubagentTool(enabledSubagents),
+        handler: createSubagentHandler(enabledSubagents),
+        ...subagentHooksMap.size > 0 && {
+          hooks: {
+            onPreToolUse: async (ctx) => {
+              const hooks = subagentHooksMap.get(resolveSubagentName(ctx.args));
+              return hooks?.onPreExecution?.(ctx) ?? {};
+            },
+            onPostToolUse: async (ctx) => {
+              const hooks = subagentHooksMap.get(resolveSubagentName(ctx.args));
+              await hooks?.onPostExecution?.(ctx);
+            },
+            onPostToolUseFailure: async (ctx) => {
+              const hooks = subagentHooksMap.get(resolveSubagentName(ctx.args));
+              return hooks?.onExecutionFailure?.(ctx) ?? {};
+            }
           }
         }
-      }
-    });
+      });
+    }
   }
   async function processToolCall(toolCall, turn, handlerContext) {
     const startTime = Date.now();
@@ -385,7 +390,11 @@ function withAutoAppend(threadHandler, handler) {
       toolName,
       content: response.toolResponse
     });
-    return { toolResponse: "", data: response.data, resultAppended: true };
+    return {
+      toolResponse: "Response appended via withAutoAppend",
+      data: response.data,
+      resultAppended: true
+    };
   };
 }
 function defineTool(tool) {
@@ -410,11 +419,19 @@ var createSession = async ({
   subagents,
   tools = {},
   processToolsInParallel = true,
-  hooks = {}
+  hooks = {},
+  appendSystemPrompt = true,
+  systemPrompt
 }) => {
+  const {
+    appendToolResult,
+    appendHumanMessage,
+    initializeThread,
+    appendSystemMessage
+  } = threadOps ?? proxyDefaultThreadOps();
   const toolRouter = createToolRouter({
     tools,
-    appendToolResult: threadOps.appendToolResult,
+    appendToolResult,
     threadId,
     hooks,
     subagents,
@@ -441,8 +458,11 @@ var createSession = async ({
         });
       }
       stateManager.setTools(toolRouter.getToolDefinitions());
-      await threadOps.initializeThread(threadId);
-      await threadOps.appendHumanMessage(threadId, await buildContextMessage());
+      await initializeThread(threadId);
+      if (appendSystemPrompt && systemPrompt && systemPrompt.trim() !== "") {
+        await appendSystemMessage(threadId, systemPrompt);
+      }
+      await appendHumanMessage(threadId, await buildContextMessage());
       let exitReason = "completed";
       try {
         while (stateManager.isRunning() && !stateManager.isTerminal() && stateManager.getTurns() < maxTurns) {
@@ -463,7 +483,7 @@ var createSession = async ({
             try {
               parsedToolCalls.push(toolRouter.parseToolCall(tc));
             } catch (error) {
-              await threadOps.appendToolResult({
+              await appendToolResult({
                 threadId,
                 toolCallId: tc.id ?? "",
                 toolName: tc.name,
@@ -510,7 +530,8 @@ function proxyDefaultThreadOps(options) {
   return {
     initializeThread: activities.initializeThread,
     appendHumanMessage: activities.appendHumanMessage,
-    appendToolResult: activities.appendToolResult
+    appendToolResult: activities.appendToolResult,
+    appendSystemMessage: activities.appendSystemMessage
   };
 }
 
@@ -1057,6 +1078,12 @@ function createThreadManager(config) {
         content
       }).toDict();
     },
+    createSystemMessage(content) {
+      return new messages.SystemMessage({
+        id: v4_default(),
+        content
+      }).toDict();
+    },
     createAIMessage(content, kwargs) {
       return new messages.AIMessage({
         id: v4_default(),
@@ -1085,6 +1112,10 @@ function createThreadManager(config) {
     async appendAIMessage(content) {
       const message = helpers.createAIMessage(content);
       await base.append([message]);
+    },
+    async appendSystemMessage(content) {
+      const message = helpers.createSystemMessage(content);
+      await base.append([message]);
     }
   };
   return Object.assign(base, helpers);
@@ -1109,6 +1140,10 @@ function createSharedActivities(redis) {
     async appendHumanMessage(threadId, content) {
       const thread = createThreadManager({ redis, threadId });
       await thread.appendHumanMessage(content);
+    },
+    async appendSystemMessage(threadId, content) {
+      const thread = createThreadManager({ redis, threadId });
+      await thread.appendSystemMessage(content);
     }
   };
 }