zeitlich 0.2.3 → 0.2.5

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

@@ -14,38 +14,38 @@ var z3__default = /*#__PURE__*/_interopDefault(z3);
 var crypto__default = /*#__PURE__*/_interopDefault(crypto);
 
 // src/lib/session.ts
-var TASK_TOOL = "Task";
-function buildTaskDescription(subagents) {
-  const subagentList = subagents.map((s) => `- **${s.name}**: ${s.description}`).join("\n");
-  return `Launch a new agent to handle complex, multi-step tasks autonomously.
+var SUBAGENT_TOOL = "Subagent";
+function buildSubagentDescription(subagents) {
+  const subagentList = subagents.map((s) => `- **${s.agentName}**: ${s.description}`).join("\n");
+  return `Launch a new agent to handle complex tasks autonomously.
 
-The ${TASK_TOOL} tool launches specialized agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
+The ${SUBAGENT_TOOL} tool launches specialized agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
 
 Available agent types:
 
 ${subagentList}
 
-When using the ${TASK_TOOL} tool, you must specify a subagent parameter to select which agent type to use.
+When using the ${SUBAGENT_TOOL} tool, you must specify a subagent parameter to select which agent type to use.
 
 Usage notes:
 
 - Always include a short description (3-5 words) summarizing what the agent will do
 - Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
-- When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
+- When the agent is done, it will return a single message back to you.
 - Each invocation starts fresh - provide a detailed task description with all necessary context.
 - Provide clear, detailed prompts so the agent can work autonomously and return exactly the information you need.
 - The agent's outputs should generally be trusted
 - Clearly tell the agent what type of work you expect since it is not aware of the user's intent
 - If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.`;
 }
-function createTaskTool(subagents) {
+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: TASK_TOOL,
-    description: buildTaskDescription(subagents),
+    name: SUBAGENT_TOOL,
+    description: buildSubagentDescription(subagents),
     schema: z3__default.default.object({
       subagent: z3__default.default.enum(names).describe("The type of subagent to launch"),
       description: z3__default.default.string().describe("A short (3-5 word) description of the task"),
@@ -53,16 +53,16 @@ function createTaskTool(subagents) {
     })
   };
 }
-function createTaskHandler(subagents) {
-  const { workflowId: parentWorkflowId, taskQueue: parentTaskQueue } = workflow.workflowInfo();
+function createSubagentHandler(subagents) {
+  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 }
@@ -72,15 +72,11 @@ function createTaskHandler(subagents) {
       args: [input],
       taskQueue: config.taskQueue ?? parentTaskQueue
     };
-    const childResult = typeof config.workflow === "string" ? await workflow.executeChild(config.workflow, childOpts) : await workflow.executeChild(config.workflow, childOpts);
-    const validated = config.resultSchema ? config.resultSchema.parse(childResult) : childResult;
-    const toolResponse = typeof validated === "string" ? validated : JSON.stringify(validated, null, 2);
+    const { toolResponse, data } = typeof config.workflow === "string" ? await workflow.executeChild(config.workflow, childOpts) : await workflow.executeChild(config.workflow, childOpts);
+    const validated = config.resultSchema ? config.resultSchema.parse(data) : null;
     return {
       toolResponse,
-      data: {
-        result: validated,
-        childWorkflowId
-      }
+      data: validated
     };
   };
 }
@@ -94,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("Task", {
-      ...createTaskTool(options.subagents),
-      handler: createTaskHandler(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();
@@ -389,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) {
@@ -414,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,
@@ -445,35 +458,32 @@ 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) {
           stateManager.incrementTurns();
           const currentTurn = stateManager.getTurns();
-          const { message, stopReason } = await runAgent({
+          const { message, rawToolCalls } = await runAgent({
             threadId,
             agentName,
             metadata
           });
-          if (stopReason === "end_turn") {
-            stateManager.complete();
-            exitReason = "completed";
-            return message;
-          }
-          if (!toolRouter.hasTools()) {
+          if (!toolRouter.hasTools() || rawToolCalls.length === 0) {
             stateManager.complete();
             exitReason = "completed";
             return message;
           }
-          const rawToolCalls = await threadOps.parseToolCalls(message);
           const parsedToolCalls = [];
           for (const tc of rawToolCalls) {
             try {
               parsedToolCalls.push(toolRouter.parseToolCall(tc));
             } catch (error) {
-              await threadOps.appendToolResult({
+              await appendToolResult({
                 threadId,
                 toolCallId: tc.id ?? "",
                 toolName: tc.name,
@@ -521,7 +531,7 @@ function proxyDefaultThreadOps(options) {
     initializeThread: activities.initializeThread,
     appendHumanMessage: activities.appendHumanMessage,
     appendToolResult: activities.appendToolResult,
-    parseToolCalls: activities.parseToolCalls
+    appendSystemMessage: activities.appendSystemMessage
   };
 }
 
@@ -1100,6 +1110,8 @@ function createThreadManager(config) {
   };
   return Object.assign(base, helpers);
 }
+
+// src/activities.ts
 function createSharedActivities(redis) {
   return {
     async appendToolResult(config) {
@@ -1119,14 +1131,9 @@ function createSharedActivities(redis) {
       const thread = createThreadManager({ redis, threadId });
       await thread.appendHumanMessage(content);
     },
-    async parseToolCalls(storedMessage) {
-      const message = messages.mapStoredMessageToChatMessage(storedMessage);
-      const toolCalls = message.tool_calls ?? [];
-      return toolCalls.map((toolCall) => ({
-        id: toolCall.id,
-        name: toolCall.name,
-        args: toolCall.args
-      }));
+    async appendSystemMessage(threadId, content) {
+      const thread = createThreadManager({ redis, threadId });
+      await thread.appendSystemMessage(content);
     }
   };
 }
@@ -1164,9 +1171,14 @@ async function invokeModel({
     }
   );
   await thread.append([response.toDict()]);
+  const toolCalls = response.tool_calls ?? [];
   return {
     message: response.toDict(),
-    stopReason: response.response_metadata?.stop_reason ?? null,
+    rawToolCalls: toolCalls.map((tc) => ({
+      id: tc.id,
+      name: tc.name,
+      args: tc.args
+    })),
     usage: {
       input_tokens: response.usage_metadata?.input_tokens,
       output_tokens: response.usage_metadata?.output_tokens,
@@ -1368,10 +1380,10 @@ exports.createEditHandler = createEditHandler;
 exports.createGlobHandler = createGlobHandler;
 exports.createSession = createSession;
 exports.createSharedActivities = createSharedActivities;
+exports.createSubagentTool = createSubagentTool;
 exports.createTaskCreateHandler = createTaskCreateHandler;
 exports.createTaskGetHandler = createTaskGetHandler;
 exports.createTaskListHandler = createTaskListHandler;
-exports.createTaskTool = createTaskTool;
 exports.createTaskUpdateHandler = createTaskUpdateHandler;
 exports.createThreadManager = createThreadManager;
 exports.createToolRouter = createToolRouter;