zeitlich 0.1.1 → 0.2.1

package/README.md

@@ -1,3 +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)
+
 # Zeitlich
 
 > **⚠️ Experimental Beta**: This library is under active development. APIs and interfaces may change between versions. Use in production at your own risk.
@@ -48,8 +51,7 @@ const google = new ChatGoogleGenerativeAI({ model: "gemini-1.5-pro" });
 
 // Pass to invokeModel in your activity
 return {
-  runAgent: (config, invocationConfig) =>
-    invokeModel(redis, { ...config, tools }, anthropic, invocationConfig),
+  runAgent: (config) => invokeModel(redis, config, anthropic),
 };
 ```
 
@@ -82,10 +84,10 @@ Zeitlich provides two entry points to work with Temporal's workflow sandboxing:
 
 ```typescript
 // In workflow files - no external dependencies (Redis, LangChain, etc.)
-import { createSession, createToolRegistry, ... } from 'zeitlich/workflow';
+import { createSession, createAgentStateManager, askUserQuestionTool } from 'zeitlich/workflow';
 
 // In activity files and worker setup - full functionality
-import { ZeitlichPlugin, invokeModel, createGlobHandler, ... } from 'zeitlich';
+import { ZeitlichPlugin, invokeModel, toTree } from 'zeitlich';
 ```
 
 **Why?** Temporal workflows run in an isolated V8 sandbox that cannot import modules with Node.js APIs or external dependencies. The `/workflow` entry point contains only pure TypeScript code safe for workflow use.
@@ -109,8 +111,6 @@ export const searchTool: ToolDefinition<"Search", typeof searchSchema> = {
     query: z.string().describe("The search query"),
   }),
 };
-
-export const tools = { Search: searchTool };
 ```
 
 ### 2. Create Activities
@@ -119,7 +119,6 @@ export const tools = { Search: searchTool };
 import type Redis from "ioredis";
 import { ChatAnthropic } from "@langchain/anthropic";
 import { invokeModel } from "zeitlich";
-import { tools } from "./tools";
 
 export const createActivities = (redis: Redis) => {
   const model = new ChatAnthropic({
@@ -128,70 +127,52 @@ export const createActivities = (redis: Redis) => {
   });
 
   return {
-    runAgent: (config, invocationConfig) =>
-      invokeModel(
-        redis,
-        { ...config, tools: Object.values(tools) },
-        model,
-        invocationConfig
-      ),
+    runAgent: (config) => invokeModel(redis, config, model),
 
     handleSearchResult: async ({ args }) => {
-      // Your tool implementation
       const results = await performSearch(args.query);
       return { result: { results } };
     },
   };
 };
+
+export type MyActivities = ReturnType<typeof createActivities>;
 ```
 
 ### 3. Create the Workflow
 
 ```typescript
 import { proxyActivities, workflowInfo } from "@temporalio/workflow";
-import {
-  createAgentStateManager,
-  createSession,
-  createPromptManager,
-  createToolRegistry,
-  createToolRouter,
-} from "zeitlich/workflow";
-import type { ZeitlichSharedActivities } from "zeitlich/workflow";
-import { tools } from "./tools";
+import { createAgentStateManager, createSession } from "zeitlich/workflow";
+import { searchTool } from "./tools";
+import type { MyActivities } from "./activities";
 
 const { runAgent, handleSearchResult } = proxyActivities<MyActivities>({
   startToCloseTimeout: "30m",
 });
 
-const { appendToolResult } = proxyActivities<ZeitlichSharedActivities>({
-  startToCloseTimeout: "30m",
-});
-
 export async function myAgentWorkflow({ prompt }: { prompt: string }) {
   const { runId } = workflowInfo();
 
-  const stateManager = createAgentStateManager({
-    initialState: { prompt },
-  });
-
-  const toolRegistry = createToolRegistry(tools);
+  const stateManager = createAgentStateManager({});
 
-  const toolRouter = createToolRouter(
-    { registry: toolRegistry, threadId: runId, appendToolResult },
-    { Search: handleSearchResult }
-  );
-
-  const promptManager = createPromptManager({
+  const session = await createSession({
+    threadId: runId,
+    agentName: "my-agent",
+    maxTurns: 20,
+    runAgent,
     baseSystemPrompt: "You are a helpful assistant.",
+    instructionsPrompt: "Help the user with their request.",
     buildContextMessage: () => [{ type: "text", text: prompt }],
+    tools: {
+      Search: {
+        ...searchTool,
+        handler: handleSearchResult,
+      },
+    },
   });
 
-  const session = await createSession(
-    { threadId: runId, agentName: "my-agent", maxTurns: 20 },
-    { runAgent, promptManager, toolRouter, toolRegistry }
-  );
-
-  await session.runSession(prompt, stateManager);
+  await session.runSession({ stateManager });
   return stateManager.getCurrentState();
 }
 ```
@@ -232,65 +213,72 @@ Manages workflow state with automatic versioning and status tracking:
 import { createAgentStateManager } from "zeitlich/workflow";
 
 const stateManager = createAgentStateManager({
-  initialState: { customField: "value" },
+  customField: "value",
 });
 
 // State operations
 stateManager.set("customField", "new value");
+stateManager.get("customField"); // Get current value
 stateManager.complete(); // Mark as COMPLETED
 stateManager.waitForInput(); // Mark as WAITING_FOR_INPUT
 stateManager.isRunning(); // Check if RUNNING
 stateManager.isTerminal(); // Check if COMPLETED/FAILED/CANCELLED
 ```
 
-### Tool Registry
+### Tools with Handlers
 
-Type-safe tool management with Zod validation:
+Define tools with their handlers inline in `createSession`:
 
 ```typescript
-import { createToolRegistry } from "zeitlich/workflow";
+import { z } from "zod";
+import type { ToolDefinition } from "zeitlich/workflow";
 
-const registry = createToolRegistry({
-  Search: searchTool,
-  Calculate: calculateTool,
-});
+// Define tool schema
+const searchTool: ToolDefinition<"Search", typeof searchSchema> = {
+  name: "Search",
+  description: "Search for information",
+  schema: z.object({ query: z.string() }),
+};
 
-// Parse and validate tool calls from LLM
-const parsed = registry.parseToolCall(rawToolCall);
-// parsed.name is "Search" | "Calculate"
-// parsed.args is fully typed based on the tool's schema
+// In workflow - combine tool definition with handler
+const session = await createSession({
+  // ... other config
+  tools: {
+    Search: {
+      ...searchTool,
+      handler: handleSearchResult, // Activity that implements the tool
+    },
+  },
+});
 ```
 
-### Tool Router
+### Lifecycle Hooks
 
-Routes tool calls to handlers with lifecycle hooks:
+Add hooks for tool execution and session lifecycle:
 
 ```typescript
-import { createToolRouter } from "zeitlich/workflow";
-
-const router = createToolRouter(
-  {
-    registry: toolRegistry,
-    threadId,
-    appendToolResult,
-    hooks: {
-      onPreToolUse: ({ toolCall }) => {
-        console.log(`Executing ${toolCall.name}`);
-        return {}; // Can return { skip: true } or { modifiedArgs: {...} }
-      },
-      onPostToolUse: ({ toolCall, result, durationMs }) => {
-        console.log(`${toolCall.name} completed in ${durationMs}ms`);
-      },
-      onPostToolUseFailure: ({ toolCall, error }) => {
-        return { fallbackContent: "Tool failed, please try again" };
-      },
+const session = await createSession({
+  // ... other config
+  hooks: {
+    onPreToolUse: ({ toolCall }) => {
+      console.log(`Executing ${toolCall.name}`);
+      return {}; // Can return { skip: true } or { modifiedArgs: {...} }
+    },
+    onPostToolUse: ({ toolCall, result, durationMs }) => {
+      console.log(`${toolCall.name} completed in ${durationMs}ms`);
+      // Access stateManager here to update state based on results
+    },
+    onPostToolUseFailure: ({ toolCall, error }) => {
+      return { fallbackContent: "Tool failed, please try again" };
+    },
+    onSessionStart: ({ threadId, agentName }) => {
+      console.log(`Session started: ${agentName}`);
+    },
+    onSessionEnd: ({ exitReason, turns }) => {
+      console.log(`Session ended: ${exitReason} after ${turns} turns`);
     },
   },
-  {
-    Search: handleSearchResult,
-    Calculate: handleCalculateResult,
-  }
-);
+});
 ```
 
 ### Subagents
@@ -298,83 +286,71 @@ const router = createToolRouter(
 Spawn child agents as Temporal child workflows:
 
 ```typescript
-import { withSubagentSupport } from "zeitlich/workflow";
-import { z } from "zod";
-
-const { tools, taskHandler } = withSubagentSupport(baseTools, {
+const session = await createSession({
+  // ... other config
   subagents: [
     {
       name: "researcher",
       description: "Researches topics and returns findings",
       workflowType: "researcherWorkflow",
-      resultSchema: z.object({
-        findings: z.string(),
-        sources: z.array(z.string()),
-      }),
+    },
+    {
+      name: "code-reviewer",
+      description: "Reviews code for quality and best practices",
+      workflowType: "codeReviewerWorkflow",
     },
   ],
 });
-
-// Include taskHandler in your tool router
-const router = createToolRouter(
-  { registry, threadId, appendToolResult },
-  { ...handlers, Task: taskHandler }
-);
 ```
 
+The `Task` tool is automatically added when subagents are configured, allowing the agent to spawn child workflows.
+
 ### Filesystem Utilities
 
-Built-in support for file operations with pluggable providers:
+Built-in support for file operations. Use `buildFileTree` to generate a file tree string that's included in the agent's context:
 
 ```typescript
-// In workflow - use the pure utilities and tool definitions
-import {
-  buildFileTreePrompt,
-  globTool,
-  grepTool,
-  readTool,
-} from "zeitlich/workflow";
+// In activities
+export const createActivities = () => ({
+  generateFileTree: async (): Promise<string> => {
+    // Return a formatted file tree string
+    return toTree("/path/to/workspace");
+  },
+});
 
-// In activities - use the providers and handlers
-import {
-  InMemoryFileSystemProvider,
-  createGlobHandler,
-  createGrepHandler,
-  createReadHandler,
-} from "zeitlich";
+// In workflow
+const session = await createSession({
+  // ... other config
+  buildFileTree: generateFileTree, // Called at session start
+});
+```
 
-// Create an in-memory filesystem
-const provider = InMemoryFileSystemProvider.fromTextFiles(
-  fileTree,
-  fileContents
-);
-
-// Create tool handlers
-const handlers = {
-  Glob: createGlobHandler({ provider, scopedNodes: fileTree }),
-  Grep: createGrepHandler({ provider, scopedNodes: fileTree }),
-  FileRead: createReadHandler({ provider, scopedNodes: fileTree }),
-};
+For more advanced file operations, use the built-in tool handlers:
 
-// Generate context for the agent
-const fileTreeContext = buildFileTreePrompt(fileTree, {
-  headerText: "Available Files",
+```typescript
+import { globHandler, editHandler, toTree } from "zeitlich";
+
+export const createActivities = () => ({
+  generateFileTree: () => toTree("/workspace"),
+  handleGlob: (args) => globHandler(args),
+  handleEdit: (args) => editHandler(args, { basePath: "/workspace" }),
 });
 ```
 
 ### Built-in Tools
 
-Zeitlich provides ready-to-use tool definitions and handlers for common agent operations. More tools will be added in future releases.
+Zeitlich provides ready-to-use tool definitions and handlers for common agent operations.
 
-| Tool              | Description                                                               |
-| ----------------- | ------------------------------------------------------------------------- |
-| `FileRead`        | Read file contents with optional pagination (supports text, images, PDFs) |
-| `FileWrite`       | Create or overwrite files with new content                                |
-| `FileEdit`        | Edit specific sections of a file by find/replace                          |
-| `Glob`            | Search for files matching a glob pattern                                  |
-| `Grep`            | Search file contents with regex patterns                                  |
-| `AskUserQuestion` | Ask the user questions during execution with structured options           |
-| `Task`            | Launch subagents as child workflows (see [Subagents](#subagents))         |
+| Tool              | Description                                                     |
+| ----------------- | --------------------------------------------------------------- |
+| `Read`            | Read file contents with optional pagination                     |
+| `Write`           | Create or overwrite files with new content                      |
+| `Edit`            | Edit specific sections of a file by find/replace                |
+| `Glob`            | Search for files matching a glob pattern                        |
+| `Grep`            | Search file contents with regex patterns                        |
+| `Bash`            | Execute shell commands                                          |
+| `AskUserQuestion` | Ask the user questions during execution with structured options |
+| `Task`            | Launch subagents as child workflows (see [Subagents](#subagents)) |
 
 ```typescript
 // Import tool definitions in workflows
@@ -384,59 +360,74 @@ import {
   editTool,
   globTool,
   grepTool,
+  bashTool,
   askUserQuestionTool,
 } from "zeitlich/workflow";
 
 // Import handlers in activities
 import {
-  createReadHandler,
-  createWriteHandler,
-  createEditHandler,
-  createGlobHandler,
-  createGrepHandler,
+  editHandler,
+  globHandler,
+  handleBashTool,
+  handleAskUserQuestionToolResult,
 } from "zeitlich";
 ```
 
+Built-in tools can be added via `buildInTools` (for tools with special handling like Bash) or as regular tools:
+
+```typescript
+const session = await createSession({
+  // ... other config
+  tools: {
+    AskUserQuestion: {
+      ...askUserQuestionTool,
+      handler: handleAskUserQuestionToolResult,
+    },
+  },
+  buildInTools: {
+    Bash: handleBashToolResult,
+  },
+});
+```
+
 ## API Reference
 
 ### Workflow Entry Point (`zeitlich/workflow`)
 
 Safe for use in Temporal workflow files:
 
-| Export                    | Description                                                                        |
-| ------------------------- | ---------------------------------------------------------------------------------- |
-| `createSession`           | Creates an agent session for running the agentic loop                              |
-| `createAgentStateManager` | Creates a state manager for workflow state                                         |
-| `createPromptManager`     | Creates a prompt manager for system/context prompts                                |
-| `createToolRegistry`      | Creates a type-safe tool registry                                                  |
-| `createToolRouter`        | Creates a tool router with handlers and hooks                                      |
-| `withSubagentSupport`     | Adds Task tool for spawning subagents                                              |
-| `buildFileTreePrompt`     | Generates file tree context for prompts                                            |
-| Tool definitions          | `askUserQuestionTool`, `globTool`, `grepTool`, `readTool`, `writeTool`, `editTool` |
-| Types                     | All TypeScript types and interfaces                                                |
+| Export                    | Description                                                                                  |
+| ------------------------- | -------------------------------------------------------------------------------------------- |
+| `createSession`           | Creates an agent session with tools, prompts, subagents, and hooks                           |
+| `createAgentStateManager` | Creates a state manager for workflow state                                                   |
+| `createToolRouter`        | Creates a tool router (used internally by session, or for advanced use)                      |
+| `createTaskTool`          | Creates the Task tool for subagent support                                                   |
+| Tool definitions          | `askUserQuestionTool`, `globTool`, `grepTool`, `readTool`, `writeTool`, `editTool`, `bashTool` |
+| Task tools                | `taskCreateTool`, `taskGetTool`, `taskListTool`, `taskUpdateTool` for workflow task management |
+| Types                     | All TypeScript types and interfaces                                                          |
 
 ### Activity Entry Point (`zeitlich`)
 
 For use in activities, worker setup, and Node.js code:
 
-| Export                        | Description                                                                                              |
-| ----------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `ZeitlichPlugin`              | Temporal worker plugin that registers shared activities                                                  |
-| `createSharedActivities`      | Creates thread management activities                                                                     |
-| `invokeModel`                 | Core LLM invocation utility (requires Redis + LangChain)                                                 |
-| `InMemoryFileSystemProvider`  | In-memory filesystem implementation                                                                      |
-| `CompositeFileSystemProvider` | Combines multiple filesystem providers                                                                   |
-| `BaseFileSystemProvider`      | Base class for custom providers                                                                          |
-| Tool handlers                 | `createGlobHandler`, `createGrepHandler`, `createReadHandler`, `createWriteHandler`, `createEditHandler` |
+| Export                           | Description                                            |
+| -------------------------------- | ------------------------------------------------------ |
+| `ZeitlichPlugin`                 | Temporal worker plugin that registers shared activities |
+| `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` |
 
 ### Types
 
-| Export           | Description                                                                  |
-| ---------------- | ---------------------------------------------------------------------------- |
-| `AgentStatus`    | `"RUNNING" \| "WAITING_FOR_INPUT" \| "COMPLETED" \| "FAILED" \| "CANCELLED"` |
-| `ToolDefinition` | Tool definition with name, description, and Zod schema                       |
-| `SubagentConfig` | Configuration for subagent workflows                                         |
-| `SessionHooks`   | Lifecycle hooks interface                                                    |
+| Export                  | Description                                                                  |
+| ----------------------- | ---------------------------------------------------------------------------- |
+| `AgentStatus`           | `"RUNNING" \| "WAITING_FOR_INPUT" \| "COMPLETED" \| "FAILED" \| "CANCELLED"` |
+| `ToolDefinition`        | Tool definition with name, description, and Zod schema                       |
+| `ToolWithHandler`       | Tool definition combined with its handler                                    |
+| `SubagentConfig`        | Configuration for subagent workflows                                         |
+| `SessionLifecycleHooks` | Lifecycle hooks interface                                                    |
+| `AgentState`            | Generic agent state type                                                     |
 
 ## Architecture
 
@@ -450,24 +441,19 @@ For use in activities, worker setup, and Node.js code:
 │                              │                                  │
 │  ┌──────────────────────────────────────────────────────────┐  │
 │  │                      Workflow                             │  │
-│  │  ┌────────────────┐  ┌─────────────┐  ┌──────────────┐   │  │
-│  │  │ State Manager  │  │   Session   │  │ Tool Router  │   │  │
-│  │  │ • Status       │  │ • Run loop  │  │ • Dispatch   │   │  │
-│  │  │ • Turns        │  │ • Max turns │  │ • Hooks      │   │  │
-│  │  │ • Custom state │  │ • Lifecycle │  │ • Handlers   │   │  │
-│  │  └────────────────┘  └─────────────┘  └──────────────┘   │  │
-│  │                              │                            │  │
-│  │  ┌────────────────┐  ┌─────────────┐  ┌──────────────┐   │  │
-│  │  │ Prompt Manager │  │Tool Registry│  │  Subagents   │   │  │
-│  │  │ • System prompt│  │ • Parsing   │  │ • Child WFs  │   │  │
-│  │  │ • Context      │  │ • Validation│  │ • Results    │   │  │
-│  │  └────────────────┘  └─────────────┘  └──────────────┘   │  │
+│  │  ┌────────────────┐  ┌───────────────────────────────┐   │  │
+│  │  │ State Manager  │  │           Session             │   │  │
+│  │  │ • Status       │  │  • Agent loop                 │   │  │
+│  │  │ • Turns        │  │  • Tool routing & hooks       │   │  │
+│  │  │ • Custom state │  │  • Prompts (system, context)  │   │  │
+│  │  └────────────────┘  │  • Subagent coordination      │   │  │
+│  │                      └───────────────────────────────────┘   │  │
 │  └──────────────────────────────────────────────────────────┘  │
 │                              │                                  │
 │  ┌──────────────────────────────────────────────────────────┐  │
 │  │                      Activities                           │  │
 │  │  • runAgent (LLM invocation)                              │  │
-│  │  • Tool handlers                                          │  │
+│  │  • Tool handlers (search, file ops, bash, etc.)           │  │
 │  └──────────────────────────────────────────────────────────┘  │
 └─────────────────────────────────────────────────────────────────┘
                               │
@@ -489,6 +475,8 @@ For use in activities, worker setup, and Node.js code:
 
 Contributions are welcome! Please open an issue or submit a PR.
 
+For maintainers: see [RELEASING.md](./RELEASING.md) for the release process.
+
 ## License
 
 MIT © [Bead Technologies Inc.](https://usebead.ai)