zeitlich 0.2.1 → 0.2.3

package/dist/index.cjs

@@ -1,7 +1,7 @@
 'use strict';
 
 var workflow = require('@temporalio/workflow');
-var z4 = require('zod');
+var z3 = require('zod');
 var plugin = require('@temporalio/plugin');
 var messages = require('@langchain/core/messages');
 var crypto = require('crypto');
@@ -10,7 +10,7 @@ var justBash = require('just-bash');
 
 function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
 
-var z4__default = /*#__PURE__*/_interopDefault(z4);
+var z3__default = /*#__PURE__*/_interopDefault(z3);
 var crypto__default = /*#__PURE__*/_interopDefault(crypto);
 
 // src/lib/session.ts
@@ -46,10 +46,10 @@ function createTaskTool(subagents) {
   return {
     name: TASK_TOOL,
     description: buildTaskDescription(subagents),
-    schema: z4__default.default.object({
-      subagent: z4__default.default.enum(names).describe("The type of subagent to launch"),
-      description: z4__default.default.string().describe("A short (3-5 word) description of the task"),
-      prompt: z4__default.default.string().describe("The task for the agent to perform")
+    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"),
+      prompt: z3__default.default.string().describe("The task for the agent to perform")
     })
   };
 }
@@ -63,149 +63,67 @@ function createTaskHandler(subagents) {
       );
     }
     const childWorkflowId = `${parentWorkflowId}-${args.subagent}-${workflow.uuid4()}`;
-    const childResult = await workflow.executeChild(config.workflowType, {
+    const input = {
+      prompt: args.prompt,
+      ...config.context && { context: config.context }
+    };
+    const childOpts = {
       workflowId: childWorkflowId,
-      args: [{ prompt: args.prompt }],
+      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 content = typeof validated === "string" ? validated : JSON.stringify(validated, null, 2);
+    const toolResponse = typeof validated === "string" ? validated : JSON.stringify(validated, null, 2);
     return {
-      content,
-      result: {
+      toolResponse,
+      data: {
         result: validated,
         childWorkflowId
       }
     };
   };
 }
-var createBashToolDescription = ({
-  fileTree
-}) => `Execute shell commands in a bash environment.
-
-Use this tool to:
-- Run shell commands (ls, cat, grep, find, etc.)
-- Execute scripts and chain commands with pipes (|) or logical operators (&&, ||)
-- Inspect files and directories
-
-Current file tree:
-${fileTree}`;
-var bashTool = {
-  name: "Bash",
-  description: `Execute shell commands in a sandboxed bash environment.
-
-Use this tool to:
-- Run shell commands (ls, cat, grep, find, etc.)
-- Execute scripts and chain commands with pipes (|) or logical operators (&&, ||)
-- Inspect files and directories
-`,
-  schema: z4__default.default.object({
-    command: z4__default.default.string().describe(
-      "The bash command to execute. Can include pipes (|), redirects (>, >>), logical operators (&&, ||), and shell features like command substitution $(...)."
-    )
-  }),
-  strict: true
-};
-var taskCreateTool = {
-  name: "TaskCreate",
-  description: `Use this tool to create a structured task list for the control test. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
-  It also helps the user understand the progress of the task and overall progress of their requests.
-  
-  ## When to Use This Tool
-  
-  Use this tool proactively in these scenarios:
-  
-  - Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
-  - Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
-  - User explicitly requests todo list - When the user directly asks you to use the todo list
-  - User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
-  - After receiving new instructions - Immediately capture user requirements as tasks
-  - When you start working on a task - Mark it as in_progress BEFORE beginning work
-  - After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation
-  
-  ## When NOT to Use This Tool
-  
-  Skip using this tool when:
-  - There is only a single, straightforward task
-  - The task is trivial and tracking it provides no organizational benefit
-  - The task can be completed in less than 3 trivial steps
-  - The task is purely conversational or informational
-  
-  NOTE that you should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.
-  
-  ## Task Fields
-  
-  - **subject**: A brief, actionable title in imperative form (e.g., "Fix authentication bug in login flow")
-  - **description**: Detailed description of what needs to be done, including context and acceptance criteria
-  - **activeForm**: Present continuous form shown in spinner when task is in_progress (e.g., "Fixing authentication bug"). This is displayed to the user while you work on the task.
-  
-  **IMPORTANT**: Always provide activeForm when creating tasks. The subject should be imperative ("Run tests") while activeForm should be present continuous ("Running tests"). All tasks are created with status \`pending\`.
-  
-  ## Tips
-  
-  - Create tasks with clear, specific subjects that describe the outcome
-  - Include enough detail in the description for another agent to understand and complete the task
-  - After creating tasks, use TaskUpdate to set up dependencies (blocks/blockedBy) if needed
-  - Check TaskList first to avoid creating duplicate tasks`,
-  schema: z4__default.default.object({
-    subject: z4__default.default.string().describe(
-      'A brief, actionable title in imperative form (e.g., "Fix authentication bug in login flow")'
-    ),
-    description: z4__default.default.string().describe(
-      "Detailed description of what needs to be done, including context and acceptance criteria"
-    ),
-    activeForm: z4__default.default.string().describe(
-      'Present continuous form shown in spinner when task is in_progress (e.g., "Fixing authentication bug"). This is displayed to the user while you work on the task.'
-    ),
-    metadata: z4__default.default.record(z4__default.default.string(), z4__default.default.string()).describe("Arbitrary key-value pairs for tracking")
-  })
-};
 
 // src/lib/tool-router.ts
-var buildIntoolDefinitions = {
-  [bashTool.name]: bashTool,
-  [taskCreateTool.name]: taskCreateTool
-};
 function createToolRouter(options) {
-  const { appendToolResult } = workflow.proxyActivities({
-    startToCloseTimeout: "2m",
-    retry: {
-      maximumAttempts: 3,
-      initialInterval: "5s",
-      maximumInterval: "15m",
-      backoffCoefficient: 4
-    }
-  });
+  const { appendToolResult } = options;
   const toolMap = /* @__PURE__ */ new Map();
   for (const [_key, tool] of Object.entries(options.tools)) {
     toolMap.set(tool.name, tool);
   }
+  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)
-    });
-  }
-  if (options.buildInTools) {
-    for (const [key, value] of Object.entries(options.buildInTools)) {
-      if (key === bashTool.name) {
-        toolMap.set(key, {
-          ...buildIntoolDefinitions[key],
-          description: createBashToolDescription({
-            fileTree: options.fileTree
-          }),
-          handler: value
-        });
-      } else {
-        toolMap.set(key, {
-          ...buildIntoolDefinitions[key],
-          handler: value
-        });
+      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) ?? {};
+          }
+        }
       }
-    }
+    });
   }
   async function processToolCall(toolCall, turn, handlerContext) {
     const startTime = Date.now();
+    const tool = toolMap.get(toolCall.name);
+    const toolHooks = tool?.hooks;
     let effectiveArgs = toolCall.args;
     if (options.hooks?.onPreToolUse) {
       const preResult = await options.hooks.onPreToolUse({
@@ -217,6 +135,7 @@ function createToolRouter(options) {
         await appendToolResult({
           threadId: options.threadId,
           toolCallId: toolCall.id,
+          toolName: toolCall.name,
           content: JSON.stringify({
             skipped: true,
             reason: "Skipped by PreToolUse hook"
@@ -228,54 +147,115 @@ function createToolRouter(options) {
         effectiveArgs = preResult.modifiedArgs;
       }
     }
-    const tool = toolMap.get(toolCall.name);
+    if (toolHooks?.onPreToolUse) {
+      const preResult = await toolHooks.onPreToolUse({
+        args: effectiveArgs,
+        threadId: options.threadId,
+        turn
+      });
+      if (preResult?.skip) {
+        await appendToolResult({
+          threadId: options.threadId,
+          toolCallId: toolCall.id,
+          toolName: toolCall.name,
+          content: JSON.stringify({
+            skipped: true,
+            reason: "Skipped by tool PreToolUse hook"
+          })
+        });
+        return null;
+      }
+      if (preResult?.modifiedArgs !== void 0) {
+        effectiveArgs = preResult.modifiedArgs;
+      }
+    }
     let result;
     let content;
+    let resultAppended = false;
     try {
       if (tool) {
+        const enrichedContext = {
+          ...handlerContext ?? {},
+          threadId: options.threadId,
+          toolCallId: toolCall.id,
+          toolName: toolCall.name
+        };
         const response = await tool.handler(
           effectiveArgs,
-          handlerContext ?? {}
+          enrichedContext
         );
-        result = response.result;
-        content = response.content;
+        result = response.data;
+        content = response.toolResponse;
+        resultAppended = response.resultAppended === true;
       } else {
         result = { error: `Unknown tool: ${toolCall.name}` };
         content = JSON.stringify(result, null, 2);
       }
     } catch (error) {
-      if (options.hooks?.onPostToolUseFailure) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      let recovered = false;
+      if (toolHooks?.onPostToolUseFailure) {
+        const failureResult = await toolHooks.onPostToolUseFailure({
+          args: effectiveArgs,
+          error: err,
+          threadId: options.threadId,
+          turn
+        });
+        if (failureResult?.fallbackContent !== void 0) {
+          content = failureResult.fallbackContent;
+          result = { error: String(error), recovered: true };
+          recovered = true;
+        } else if (failureResult?.suppress) {
+          content = JSON.stringify({ error: String(error), suppressed: true });
+          result = { error: String(error), suppressed: true };
+          recovered = true;
+        }
+      }
+      if (!recovered && options.hooks?.onPostToolUseFailure) {
         const failureResult = await options.hooks.onPostToolUseFailure({
           toolCall,
-          error: error instanceof Error ? error : new Error(String(error)),
+          error: err,
           threadId: options.threadId,
           turn
         });
         if (failureResult?.fallbackContent !== void 0) {
           content = failureResult.fallbackContent;
           result = { error: String(error), recovered: true };
+          recovered = true;
         } else if (failureResult?.suppress) {
           content = JSON.stringify({ error: String(error), suppressed: true });
           result = { error: String(error), suppressed: true };
-        } else {
-          throw error;
+          recovered = true;
         }
-      } else {
+      }
+      if (!recovered) {
         throw error;
       }
     }
-    await appendToolResult({
-      threadId: options.threadId,
-      toolCallId: toolCall.id,
-      content
-    });
+    if (!resultAppended) {
+      await appendToolResult({
+        threadId: options.threadId,
+        toolCallId: toolCall.id,
+        toolName: toolCall.name,
+        content
+      });
+    }
     const toolResult = {
       toolCallId: toolCall.id,
       name: toolCall.name,
-      result
+      data: result
     };
+    const durationMs = Date.now() - startTime;
+    if (toolHooks?.onPostToolUse) {
+      await toolHooks.onPostToolUse({
+        args: effectiveArgs,
+        result,
+        threadId: options.threadId,
+        turn,
+        durationMs
+      });
+    }
     if (options.hooks?.onPostToolUse) {
-      const durationMs = Date.now() - startTime;
       await options.hooks.onPostToolUse({
         toolCall,
         result: toolResult,
@@ -289,11 +269,11 @@ function createToolRouter(options) {
   return {
     // --- Methods from registry ---
     hasTools() {
-      return toolMap.size > 0;
+      return Array.from(toolMap.values()).some(isEnabled);
     },
     parseToolCall(toolCall) {
       const tool = toolMap.get(toolCall.name);
-      if (!tool) {
+      if (!tool || !isEnabled(tool)) {
         throw new Error(`Tool ${toolCall.name} not found`);
       }
       const parsedArgs = tool.schema.parse(toolCall.args);
@@ -304,13 +284,14 @@ function createToolRouter(options) {
       };
     },
     hasTool(name) {
-      return toolMap.has(name);
+      const tool = toolMap.get(name);
+      return tool !== void 0 && isEnabled(tool);
     },
     getToolNames() {
-      return Array.from(toolMap.keys());
+      return Array.from(toolMap.entries()).filter(([, tool]) => isEnabled(tool)).map(([name]) => name);
     },
     getToolDefinitions() {
-      return Array.from(toolMap).map(([name, tool]) => ({
+      return Array.from(toolMap).filter(([, tool]) => isEnabled(tool)).map(([name, tool]) => ({
         name,
         description: tool.description,
         schema: tool.schema,
@@ -349,19 +330,28 @@ function createToolRouter(options) {
       }
       const handlerContext = context?.handlerContext ?? {};
       const processOne = async (toolCall) => {
+        const enrichedContext = {
+          ...handlerContext ?? {},
+          threadId: options.threadId,
+          toolCallId: toolCall.id,
+          toolName: toolCall.name
+        };
         const response = await handler(
           toolCall.args,
-          handlerContext
+          enrichedContext
         );
-        await appendToolResult({
-          threadId: options.threadId,
-          toolCallId: toolCall.id,
-          content: response.content
-        });
+        if (!response.resultAppended) {
+          await appendToolResult({
+            threadId: options.threadId,
+            toolCallId: toolCall.id,
+            toolName: toolCall.name,
+            content: response.toolResponse
+          });
+        }
         return {
           toolCallId: toolCall.id,
           name: toolCall.name,
-          result: response.result
+          data: response.data
         };
       };
       if (options.parallel) {
@@ -387,56 +377,50 @@ function createToolRouter(options) {
     }
   };
 }
+function withAutoAppend(threadHandler, handler) {
+  return async (args, context) => {
+    const response = await handler(args, context);
+    const threadId = context.threadId;
+    const toolCallId = context.toolCallId;
+    const toolName = context.toolName;
+    await threadHandler({
+      threadId,
+      toolCallId,
+      toolName,
+      content: response.toolResponse
+    });
+    return { toolResponse: "", data: response.data, resultAppended: true };
+  };
+}
+function defineTool(tool) {
+  return tool;
+}
+function defineSubagent(config) {
+  return config;
+}
 function hasNoOtherToolCalls(toolCalls, excludeName) {
   return toolCalls.filter((tc) => tc.name !== excludeName).length === 0;
 }
 
 // src/lib/session.ts
-async function resolvePrompt(prompt) {
-  if (typeof prompt === "function") {
-    return prompt();
-  }
-  return prompt;
-}
 var createSession = async ({
   threadId,
   agentName,
   maxTurns = 50,
   metadata = {},
   runAgent,
-  baseSystemPrompt,
-  instructionsPrompt,
+  threadOps,
   buildContextMessage,
-  buildFileTree = async () => "",
   subagents,
   tools = {},
   processToolsInParallel = true,
-  buildInTools = {},
   hooks = {}
 }) => {
-  const {
-    initializeThread,
-    appendHumanMessage,
-    parseToolCalls,
-    appendToolResult,
-    appendSystemMessage
-  } = workflow.proxyActivities({
-    startToCloseTimeout: "30m",
-    retry: {
-      maximumAttempts: 6,
-      initialInterval: "5s",
-      maximumInterval: "15m",
-      backoffCoefficient: 4
-    },
-    heartbeatTimeout: "5m"
-  });
-  const fileTree = await buildFileTree();
   const toolRouter = createToolRouter({
     tools,
+    appendToolResult: threadOps.appendToolResult,
     threadId,
     hooks,
-    buildInTools,
-    fileTree,
     subagents,
     parallel: processToolsInParallel
   });
@@ -461,15 +445,8 @@ var createSession = async ({
         });
       }
       stateManager.setTools(toolRouter.getToolDefinitions());
-      await initializeThread(threadId);
-      await appendSystemMessage(
-        threadId,
-        [
-          await resolvePrompt(baseSystemPrompt),
-          await resolvePrompt(instructionsPrompt)
-        ].join("\n")
-      );
-      await appendHumanMessage(threadId, await buildContextMessage());
+      await threadOps.initializeThread(threadId);
+      await threadOps.appendHumanMessage(threadId, await buildContextMessage());
       let exitReason = "completed";
       try {
         while (stateManager.isRunning() && !stateManager.isTerminal() && stateManager.getTurns() < maxTurns) {
@@ -490,24 +467,25 @@ var createSession = async ({
             exitReason = "completed";
             return message;
           }
-          const rawToolCalls = await parseToolCalls(message);
-          const parsedToolCalls = rawToolCalls.filter((tc) => tc.name !== "Task").map((tc) => toolRouter.parseToolCall(tc));
-          const taskToolCalls = subagents && subagents.length > 0 ? rawToolCalls.filter((tc) => tc.name === "Task").map((tc) => {
-            const parsedArgs = createTaskTool(subagents).schema.parse(
-              tc.args
-            );
-            return {
-              id: tc.id ?? "",
-              name: tc.name,
-              args: parsedArgs
-            };
-          }) : [];
-          await toolRouter.processToolCalls(
-            [...parsedToolCalls, ...taskToolCalls],
-            {
-              turn: currentTurn
+          const rawToolCalls = await threadOps.parseToolCalls(message);
+          const parsedToolCalls = [];
+          for (const tc of rawToolCalls) {
+            try {
+              parsedToolCalls.push(toolRouter.parseToolCall(tc));
+            } catch (error) {
+              await threadOps.appendToolResult({
+                threadId,
+                toolCallId: tc.id ?? "",
+                toolName: tc.name,
+                content: JSON.stringify({
+                  error: `Invalid tool call for "${tc.name}": ${error instanceof Error ? error.message : String(error)}`
+                })
+              });
             }
-          );
+          }
+          await toolRouter.processToolCalls(parsedToolCalls, {
+            turn: currentTurn
+          });
           if (stateManager.getStatus() === "WAITING_FOR_INPUT") {
             exitReason = "waiting_for_input";
             break;
@@ -526,13 +504,31 @@ var createSession = async ({
     }
   };
 };
+function proxyDefaultThreadOps(options) {
+  const activities = workflow.proxyActivities(
+    options ?? {
+      startToCloseTimeout: "30m",
+      retry: {
+        maximumAttempts: 6,
+        initialInterval: "5s",
+        maximumInterval: "15m",
+        backoffCoefficient: 4
+      },
+      heartbeatTimeout: "5m"
+    }
+  );
+  return {
+    initializeThread: activities.initializeThread,
+    appendHumanMessage: activities.appendHumanMessage,
+    appendToolResult: activities.appendToolResult,
+    parseToolCalls: activities.parseToolCalls
+  };
+}
 
 // src/lib/types.ts
 function isTerminalStatus(status) {
   return status === "COMPLETED" || status === "FAILED" || status === "CANCELLED";
 }
-
-// src/lib/state-manager.ts
 var getStateQuery = workflow.defineQuery("getState");
 function createAgentStateManager(initialState) {
   let status = initialState?.status ?? "RUNNING";
@@ -627,7 +623,13 @@ function createAgentStateManager(initialState) {
       version++;
     },
     setTools(newTools) {
-      tools = newTools;
+      tools = newTools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        schema: z3.z.toJSONSchema(tool.schema),
+        strict: tool.strict,
+        max_uses: tool.max_uses
+      }));
     },
     deleteTask(id) {
       const deleted = tasks.delete(id);
@@ -658,18 +660,18 @@ Usage notes:
 * Use multiSelect: true to allow multiple answers to be selected for a question
 * If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label
 `,
-  schema: z4__default.default.object({
-    questions: z4__default.default.array(
-      z4__default.default.object({
-        question: z4__default.default.string().describe("The full question text to display"),
-        header: z4__default.default.string().describe("Short label for the question (max 12 characters)"),
-        options: z4__default.default.array(
-          z4__default.default.object({
-            label: z4__default.default.string(),
-            description: z4__default.default.string()
+  schema: z3__default.default.object({
+    questions: z3__default.default.array(
+      z3__default.default.object({
+        question: z3__default.default.string().describe("The full question text to display"),
+        header: z3__default.default.string().describe("Short label for the question (max 12 characters)"),
+        options: z3__default.default.array(
+          z3__default.default.object({
+            label: z3__default.default.string(),
+            description: z3__default.default.string()
           })
         ).min(0).max(4).describe("Array of 0-4 choices, each with label and description"),
-        multiSelect: z4__default.default.boolean().describe("If true, users can select multiple options")
+        multiSelect: z3__default.default.boolean().describe("If true, users can select multiple options")
       })
     )
   }),
@@ -689,9 +691,9 @@ Examples:
 - "**/*.test.ts" - Find all test files recursively
 - "src/**/*.ts" - Find all TypeScript files in src directory
 `,
-  schema: z4.z.object({
-    pattern: z4.z.string().describe("Glob pattern to match files against"),
-    root: z4.z.string().optional().describe("Optional root directory to search from")
+  schema: z3.z.object({
+    pattern: z3.z.string().describe("Glob pattern to match files against"),
+    root: z3.z.string().optional().describe("Optional root directory to search from")
   }),
   strict: true
 };
@@ -709,13 +711,13 @@ Examples:
 - Search for function definitions with "function.*handleClick"
 - Search case-insensitively with ignoreCase: true
 `,
-  schema: z4.z.object({
-    pattern: z4.z.string().describe("Regex pattern to search for in file contents"),
-    ignoreCase: z4.z.boolean().optional().describe("Case-insensitive search (default: false)"),
-    maxMatches: z4.z.number().optional().describe("Maximum number of matches to return (default: 50)"),
-    includePatterns: z4.z.array(z4.z.string()).optional().describe("Glob patterns to include (e.g., ['*.ts', '*.js'])"),
-    excludePatterns: z4.z.array(z4.z.string()).optional().describe("Glob patterns to exclude (e.g., ['*.test.ts'])"),
-    contextLines: z4.z.number().optional().describe("Number of context lines to show around matches")
+  schema: z3.z.object({
+    pattern: z3.z.string().describe("Regex pattern to search for in file contents"),
+    ignoreCase: z3.z.boolean().optional().describe("Case-insensitive search (default: false)"),
+    maxMatches: z3.z.number().optional().describe("Maximum number of matches to return (default: 50)"),
+    includePatterns: z3.z.array(z3.z.string()).optional().describe("Glob patterns to include (e.g., ['*.ts', '*.js'])"),
+    excludePatterns: z3.z.array(z3.z.string()).optional().describe("Glob patterns to exclude (e.g., ['*.test.ts'])"),
+    contextLines: z3.z.number().optional().describe("Number of context lines to show around matches")
   }),
   strict: true
 };
@@ -733,12 +735,12 @@ The tool returns the file content in an appropriate format:
 - Images: Base64-encoded image data
 - PDFs: Extracted text content
 `,
-  schema: z4.z.object({
-    path: z4.z.string().describe("Virtual path to the file to read"),
-    offset: z4.z.number().optional().describe(
+  schema: z3.z.object({
+    path: z3.z.string().describe("Virtual path to the file to read"),
+    offset: z3.z.number().optional().describe(
       "Line number to start reading from (1-indexed, for text files)"
     ),
-    limit: z4.z.number().optional().describe("Maximum number of lines to read (for text files)")
+    limit: z3.z.number().optional().describe("Maximum number of lines to read (for text files)")
   }),
   strict: true
 };
@@ -747,7 +749,7 @@ var writeTool = {
   description: `Create or overwrite a file with new content.
 
 Usage:
-- Provide the absolute virtual path to the file
+- Provide the absolute path to the file
 - The file will be created if it doesn't exist
 - If the file exists, it will be completely overwritten
 
@@ -756,9 +758,9 @@ IMPORTANT:
 - This is an atomic write operation - the entire file is replaced
 - Path must be absolute (e.g., "/docs/readme.md", not "docs/readme.md")
 `,
-  schema: z4.z.object({
-    file_path: z4.z.string().describe("The absolute virtual path to the file to write"),
-    content: z4.z.string().describe("The content to write to the file")
+  schema: z3.z.object({
+    file_path: z3.z.string().describe("The absolute path to the file to write"),
+    content: z3.z.string().describe("The content to write to the file")
   }),
   strict: true
 };
@@ -778,27 +780,76 @@ IMPORTANT:
 - The operation fails if old_string is not found
 - old_string and new_string must be different
 `,
-  schema: z4.z.object({
-    file_path: z4.z.string().describe("The absolute virtual path to the file to modify"),
-    old_string: z4.z.string().describe("The exact text to replace"),
-    new_string: z4.z.string().describe(
+  schema: z3.z.object({
+    file_path: z3.z.string().describe("The absolute virtual path to the file to modify"),
+    old_string: z3.z.string().describe("The exact text to replace"),
+    new_string: z3.z.string().describe(
       "The text to replace it with (must be different from old_string)"
     ),
-    replace_all: z4.z.boolean().optional().describe(
+    replace_all: z3.z.boolean().optional().describe(
       "If true, replace all occurrences of old_string (default: false)"
     )
   }),
   strict: true
 };
-
-// src/tools/task-create/handler.ts
-function createTaskCreateHandler({
-  stateManager,
-  idGenerator
-}) {
+var taskCreateTool = {
+  name: "TaskCreate",
+  description: `Use this tool to create a structured task list for the control test. This helps you track progress, organize complex tasks, and demonstrate thoroughness to the user.
+  It also helps the user understand the progress of the task and overall progress of their requests.
+  
+  ## When to Use This Tool
+  
+  Use this tool proactively in these scenarios:
+  
+  - Complex multi-step tasks - When a task requires 3 or more distinct steps or actions
+  - Non-trivial and complex tasks - Tasks that require careful planning or multiple operations
+  - User explicitly requests todo list - When the user directly asks you to use the todo list
+  - User provides multiple tasks - When users provide a list of things to be done (numbered or comma-separated)
+  - After receiving new instructions - Immediately capture user requirements as tasks
+  - When you start working on a task - Mark it as in_progress BEFORE beginning work
+  - After completing a task - Mark it as completed and add any new follow-up tasks discovered during implementation
+  
+  ## When NOT to Use This Tool
+  
+  Skip using this tool when:
+  - There is only a single, straightforward task
+  - The task is trivial and tracking it provides no organizational benefit
+  - The task can be completed in less than 3 trivial steps
+  - The task is purely conversational or informational
+  
+  NOTE that you should not use this tool if there is only one trivial task to do. In this case you are better off just doing the task directly.
+  
+  ## Task Fields
+  
+  - **subject**: A brief, actionable title in imperative form (e.g., "Fix authentication bug in login flow")
+  - **description**: Detailed description of what needs to be done, including context and acceptance criteria
+  - **activeForm**: Present continuous form shown in spinner when task is in_progress (e.g., "Fixing authentication bug"). This is displayed to the user while you work on the task.
+  
+  **IMPORTANT**: Always provide activeForm when creating tasks. The subject should be imperative ("Run tests") while activeForm should be present continuous ("Running tests"). All tasks are created with status \`pending\`.
+  
+  ## Tips
+  
+  - Create tasks with clear, specific subjects that describe the outcome
+  - Include enough detail in the description for another agent to understand and complete the task
+  - After creating tasks, use TaskUpdate to set up dependencies (blocks/blockedBy) if needed
+  - Check TaskList first to avoid creating duplicate tasks`,
+  schema: z3__default.default.object({
+    subject: z3__default.default.string().describe(
+      'A brief, actionable title in imperative form (e.g., "Fix authentication bug in login flow")'
+    ),
+    description: z3__default.default.string().describe(
+      "Detailed description of what needs to be done, including context and acceptance criteria"
+    ),
+    activeForm: z3__default.default.string().describe(
+      'Present continuous form shown in spinner when task is in_progress (e.g., "Fixing authentication bug"). This is displayed to the user while you work on the task.'
+    ),
+    metadata: z3__default.default.record(z3__default.default.string(), z3__default.default.string()).describe("Arbitrary key-value pairs for tracking")
+  })
+};
+function createTaskCreateHandler(stateManager) {
   return (args) => {
     const task = {
-      id: idGenerator(),
+      id: workflow.uuid4(),
       subject: args.subject,
       description: args.description,
       activeForm: args.activeForm,
@@ -809,16 +860,16 @@ function createTaskCreateHandler({
     };
     stateManager.setTask(task);
     return {
-      content: JSON.stringify(task, null, 2),
-      result: task
+      toolResponse: JSON.stringify(task, null, 2),
+      data: task
     };
   };
 }
 var taskGetTool = {
   name: "TaskGet",
   description: `Retrieve full task details including dependencies.`,
-  schema: z4__default.default.object({
-    taskId: z4__default.default.string().describe("The ID of the task to get")
+  schema: z3__default.default.object({
+    taskId: z3__default.default.string().describe("The ID of the task to get")
   })
 };
 
@@ -828,40 +879,40 @@ function createTaskGetHandler(stateManager) {
     const task = stateManager.getTask(args.taskId) ?? null;
     if (!task) {
       return {
-        content: JSON.stringify({ error: `Task not found: ${args.taskId}` }),
-        result: null
+        toolResponse: JSON.stringify({ error: `Task not found: ${args.taskId}` }),
+        data: null
       };
     }
     return {
-      content: JSON.stringify(task, null, 2),
-      result: task
+      toolResponse: JSON.stringify(task, null, 2),
+      data: task
     };
   };
 }
 var taskListTool = {
   name: "TaskList",
   description: `List all tasks with current state.`,
-  schema: z4__default.default.object({})
+  schema: z3__default.default.object({})
 };
 
 // src/tools/task-list/handler.ts
 function createTaskListHandler(stateManager) {
-  return (_args) => {
+  return () => {
     const taskList = stateManager.getTasks();
     return {
-      content: JSON.stringify(taskList, null, 2),
-      result: taskList
+      toolResponse: JSON.stringify(taskList, null, 2),
+      data: taskList
     };
   };
 }
 var taskUpdateTool = {
   name: "TaskUpdate",
   description: `Update status, add blockers, modify details.`,
-  schema: z4__default.default.object({
-    taskId: z4__default.default.string().describe("The ID of the task to get"),
-    status: z4__default.default.enum(["pending", "in_progress", "completed"]).describe("The status of the task"),
-    addBlockedBy: z4__default.default.array(z4__default.default.string()).describe("The IDs of the tasks that are blocking this task"),
-    addBlocks: z4__default.default.array(z4__default.default.string()).describe("The IDs of the tasks that this task is blocking")
+  schema: z3__default.default.object({
+    taskId: z3__default.default.string().describe("The ID of the task to get"),
+    status: z3__default.default.enum(["pending", "in_progress", "completed"]).describe("The status of the task"),
+    addBlockedBy: z3__default.default.array(z3__default.default.string()).describe("The IDs of the tasks that are blocking this task"),
+    addBlocks: z3__default.default.array(z3__default.default.string()).describe("The IDs of the tasks that this task is blocking")
   })
 };
 
@@ -871,8 +922,8 @@ function createTaskUpdateHandler(stateManager) {
     const task = stateManager.getTask(args.taskId);
     if (!task) {
       return {
-        content: JSON.stringify({ error: `Task not found: ${args.taskId}` }),
-        result: null
+        toolResponse: JSON.stringify({ error: `Task not found: ${args.taskId}` }),
+        data: null
       };
     }
     if (args.status) {
@@ -904,11 +955,38 @@ function createTaskUpdateHandler(stateManager) {
     }
     stateManager.setTask(task);
     return {
-      content: JSON.stringify(task, null, 2),
-      result: task
+      toolResponse: JSON.stringify(task, null, 2),
+      data: task
     };
   };
 }
+var createBashToolDescription = ({
+  fileTree
+}) => `Execute shell commands in a bash environment.
+
+Use this tool to:
+- Run shell commands (ls, cat, grep, find, etc.)
+- Execute scripts and chain commands with pipes (|) or logical operators (&&, ||)
+- Inspect files and directories
+
+Current file tree:
+${fileTree}`;
+var bashTool = {
+  name: "Bash",
+  description: `Execute shell commands in a sandboxed bash environment.
+
+Use this tool to:
+- Run shell commands (ls, cat, grep, find, etc.)
+- Execute scripts and chain commands with pipes (|) or logical operators (&&, ||)
+- Inspect files and directories
+`,
+  schema: z3__default.default.object({
+    command: z3__default.default.string().describe(
+      "The bash command to execute. Can include pipes (|), redirects (>, >>), logical operators (&&, ||), and shell features like command substitution $(...)."
+    )
+  }),
+  strict: true
+};
 
 // node_modules/uuid/dist/esm-node/stringify.js
 var byteToHex = [];
@@ -957,25 +1035,33 @@ function getThreadKey(threadId, key) {
   return `thread:${threadId}:${key}`;
 }
 function createThreadManager(config) {
-  const { redis, threadId, key = "messages" } = config;
+  const {
+    redis,
+    threadId,
+    key = "messages",
+    serialize = (m) => JSON.stringify(m),
+    deserialize = (raw) => JSON.parse(raw)
+  } = config;
   const redisKey = getThreadKey(threadId, key);
-  return {
+  const base = {
     async initialize() {
       await redis.del(redisKey);
     },
     async load() {
       const data = await redis.lrange(redisKey, 0, -1);
-      return data.map((item) => JSON.parse(item));
+      return data.map(deserialize);
     },
     async append(messages) {
       if (messages.length > 0) {
-        await redis.rpush(redisKey, ...messages.map((m) => JSON.stringify(m)));
+        await redis.rpush(redisKey, ...messages.map(serialize));
         await redis.expire(redisKey, THREAD_TTL_SECONDS);
       }
     },
     async delete() {
       await redis.del(redisKey);
-    },
+    }
+  };
+  const helpers = {
     createHumanMessage(content) {
       return new messages.HumanMessage({
         id: v4_default(),
@@ -995,40 +1081,27 @@ function createThreadManager(config) {
     },
     createToolMessage(content, toolCallId) {
       return new messages.ToolMessage({
-        // Cast needed due to langchain type compatibility
         content,
         tool_call_id: toolCallId
       }).toDict();
     },
-    createSystemMessage(content) {
-      return new messages.SystemMessage({
-        content
-      }).toDict();
-    },
-    async appendSystemMessage(content) {
-      const message = this.createSystemMessage(content);
-      await this.append([message]);
-    },
     async appendHumanMessage(content) {
-      const message = this.createHumanMessage(content);
-      await this.append([message]);
+      const message = helpers.createHumanMessage(content);
+      await base.append([message]);
     },
     async appendToolMessage(content, toolCallId) {
-      const message = this.createToolMessage(content, toolCallId);
-      await this.append([message]);
+      const message = helpers.createToolMessage(content, toolCallId);
+      await base.append([message]);
     },
     async appendAIMessage(content) {
-      const message = this.createAIMessage(content);
-      await this.append([message]);
+      const message = helpers.createAIMessage(content);
+      await base.append([message]);
     }
   };
+  return Object.assign(base, helpers);
 }
 function createSharedActivities(redis) {
   return {
-    async appendSystemMessage(threadId, content) {
-      const thread = createThreadManager({ redis, threadId });
-      await thread.appendSystemMessage(content);
-    },
     async appendToolResult(config) {
       const { threadId, toolCallId, content } = config;
       const thread = createThreadManager({ redis, threadId });
@@ -1101,7 +1174,7 @@ async function invokeModel({
     }
   };
 }
-var handleAskUserQuestionToolResult = async (args) => {
+var createAskUserQuestionHandler = () => async (args) => {
   const messages$1 = args.questions.map(
     ({ question, header, options, multiSelect }) => new messages.AIMessage({
       content: question,
@@ -1112,101 +1185,81 @@ var handleAskUserQuestionToolResult = async (args) => {
       }
     }).toDict()
   );
-  return { content: "Question submitted", result: { chatMessages: messages$1 } };
+  return { toolResponse: "Question submitted", data: { chatMessages: messages$1 } };
 };
-async function globHandler(_args, fs) {
-  new justBash.Bash({ fs });
-  return Promise.resolve({
-    content: "Hello, world!",
-    result: { files: [] }
-  });
+function createGlobHandler(fs) {
+  return async (_args) => {
+    new justBash.Bash({ fs });
+    return {
+      toolResponse: "Hello, world!",
+      data: { files: [] }
+    };
+  };
 }
 
 // src/tools/edit/handler.ts
 function escapeRegExp(str) {
   return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
-async function editHandler(args, fs) {
-  const { file_path, old_string, new_string, replace_all = false } = args;
-  if (old_string === new_string) {
-    return {
-      content: `Error: old_string and new_string must be different.`,
-      result: {
-        path: file_path,
-        success: false,
-        replacements: 0
-      }
-    };
-  }
-  try {
-    const exists = await fs.exists(file_path);
-    if (!exists) {
+function createEditHandler(fs) {
+  return async (args) => {
+    const { file_path, old_string, new_string, replace_all = false } = args;
+    if (old_string === new_string) {
       return {
-        content: `Error: File "${file_path}" does not exist.`,
-        result: {
-          path: file_path,
-          success: false,
-          replacements: 0
-        }
+        toolResponse: `Error: old_string and new_string must be different.`,
+        data: { path: file_path, success: false, replacements: 0 }
       };
     }
-    const content = await fs.readFile(file_path);
-    if (!content.includes(old_string)) {
+    try {
+      const exists = await fs.exists(file_path);
+      if (!exists) {
+        return {
+          toolResponse: `Error: File "${file_path}" does not exist.`,
+          data: { path: file_path, success: false, replacements: 0 }
+        };
+      }
+      const content = await fs.readFile(file_path);
+      if (!content.includes(old_string)) {
+        return {
+          toolResponse: `Error: Could not find the specified text in "${file_path}". Make sure old_string matches exactly (whitespace-sensitive).`,
+          data: { path: file_path, success: false, replacements: 0 }
+        };
+      }
+      const escapedOldString = escapeRegExp(old_string);
+      const globalRegex = new RegExp(escapedOldString, "g");
+      const occurrences = (content.match(globalRegex) || []).length;
+      if (!replace_all && occurrences > 1) {
+        return {
+          toolResponse: `Error: old_string appears ${occurrences} times in "${file_path}". Either provide more context to make it unique, or use replace_all: true.`,
+          data: { path: file_path, success: false, replacements: 0 }
+        };
+      }
+      let newContent;
+      let replacements;
+      if (replace_all) {
+        newContent = content.split(old_string).join(new_string);
+        replacements = occurrences;
+      } else {
+        const index = content.indexOf(old_string);
+        newContent = content.slice(0, index) + new_string + content.slice(index + old_string.length);
+        replacements = 1;
+      }
+      await fs.writeFile(file_path, newContent);
+      const summary = replace_all ? `Replaced ${replacements} occurrence(s)` : `Replaced 1 occurrence`;
       return {
-        content: `Error: Could not find the specified text in "${file_path}". Make sure old_string matches exactly (whitespace-sensitive).`,
-        result: {
-          path: file_path,
-          success: false,
-          replacements: 0
-        }
+        toolResponse: `${summary} in ${file_path}`,
+        data: { path: file_path, success: true, replacements }
       };
-    }
-    const escapedOldString = escapeRegExp(old_string);
-    const globalRegex = new RegExp(escapedOldString, "g");
-    const occurrences = (content.match(globalRegex) || []).length;
-    if (!replace_all && occurrences > 1) {
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Unknown error";
       return {
-        content: `Error: old_string appears ${occurrences} times in "${file_path}". Either provide more context to make it unique, or use replace_all: true.`,
-        result: {
-          path: file_path,
-          success: false,
-          replacements: 0
-        }
+        toolResponse: `Error editing file "${file_path}": ${message}`,
+        data: { path: file_path, success: false, replacements: 0 }
       };
     }
-    let newContent;
-    let replacements;
-    if (replace_all) {
-      newContent = content.split(old_string).join(new_string);
-      replacements = occurrences;
-    } else {
-      const index = content.indexOf(old_string);
-      newContent = content.slice(0, index) + new_string + content.slice(index + old_string.length);
-      replacements = 1;
-    }
-    await fs.writeFile(file_path, newContent);
-    const summary = replace_all ? `Replaced ${replacements} occurrence(s)` : `Replaced 1 occurrence`;
-    return {
-      content: `${summary} in ${file_path}`,
-      result: {
-        path: file_path,
-        success: true,
-        replacements
-      }
-    };
-  } catch (error) {
-    const message = error instanceof Error ? error.message : "Unknown error";
-    return {
-      content: `Error editing file "${file_path}": ${message}`,
-      result: {
-        path: file_path,
-        success: false,
-        replacements: 0
-      }
-    };
-  }
+  };
 }
-var handleBashTool = (bashOptions) => async (args, _context) => {
+var createBashHandler = (bashOptions) => async (args, _context) => {
   const { command } = args;
   const mergedOptions = {
     ...bashOptions,
@@ -1221,20 +1274,20 @@ var handleBashTool = (bashOptions) => async (args, _context) => {
     const { exitCode, stderr, stdout } = await bash.exec(command);
     const bashExecOut = { exitCode, stderr, stdout };
     return {
-      content: `Exit code: ${exitCode}
+      toolResponse: `Exit code: ${exitCode}
 
 stdout:
 ${stdout}
 
 stderr:
 ${stderr}`,
-      result: bashExecOut
+      data: bashExecOut
     };
   } catch (error) {
     const err = error instanceof Error ? error : new Error("Unknown error");
     return {
-      content: `Error executing bash command: ${err.message}`,
-      result: null
+      toolResponse: `Error executing bash command: ${err.message}`,
+      data: null
     };
   }
 };
@@ -1308,6 +1361,11 @@ exports.ZeitlichPlugin = ZeitlichPlugin;
 exports.askUserQuestionTool = askUserQuestionTool;
 exports.bashTool = bashTool;
 exports.createAgentStateManager = createAgentStateManager;
+exports.createAskUserQuestionHandler = createAskUserQuestionHandler;
+exports.createBashHandler = createBashHandler;
+exports.createBashToolDescription = createBashToolDescription;
+exports.createEditHandler = createEditHandler;
+exports.createGlobHandler = createGlobHandler;
 exports.createSession = createSession;
 exports.createSharedActivities = createSharedActivities;
 exports.createTaskCreateHandler = createTaskCreateHandler;
@@ -1315,23 +1373,25 @@ exports.createTaskGetHandler = createTaskGetHandler;
 exports.createTaskListHandler = createTaskListHandler;
 exports.createTaskTool = createTaskTool;
 exports.createTaskUpdateHandler = createTaskUpdateHandler;
+exports.createThreadManager = createThreadManager;
 exports.createToolRouter = createToolRouter;
-exports.editHandler = editHandler;
+exports.defineSubagent = defineSubagent;
+exports.defineTool = defineTool;
 exports.editTool = editTool;
-exports.globHandler = globHandler;
+exports.getStateQuery = getStateQuery;
 exports.globTool = globTool;
 exports.grepTool = grepTool;
-exports.handleAskUserQuestionToolResult = handleAskUserQuestionToolResult;
-exports.handleBashTool = handleBashTool;
 exports.hasNoOtherToolCalls = hasNoOtherToolCalls;
 exports.invokeModel = invokeModel;
 exports.isTerminalStatus = isTerminalStatus;
+exports.proxyDefaultThreadOps = proxyDefaultThreadOps;
 exports.readTool = readTool;
 exports.taskCreateTool = taskCreateTool;
 exports.taskGetTool = taskGetTool;
 exports.taskListTool = taskListTool;
 exports.taskUpdateTool = taskUpdateTool;
 exports.toTree = toTree;
+exports.withAutoAppend = withAutoAppend;
 exports.writeTool = writeTool;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map