zeitlich 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bead AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,494 @@
+# Zeitlich
+
+> **⚠️ Experimental Beta**: This library is under active development. APIs and interfaces may change between versions. Use in production at your own risk.
+
+**Durable AI Agents for Temporal**
+
+Zeitlich is an opinionated framework for building reliable, stateful AI agents using [Temporal](https://temporal.io). It provides the building blocks for creating agents that can survive crashes, handle long-running tasks, and coordinate with other agents—all with full type safety.
+
+## Why Zeitlich?
+
+Building production AI agents is hard. Agents need to:
+
+- **Survive failures** — What happens when your agent crashes mid-task?
+- **Handle long-running work** — Some tasks take hours or days
+- **Coordinate** — Multiple agents often need to work together
+- **Maintain state** — Conversation history, tool results, workflow state
+
+Temporal solves these problems for workflows. Zeitlich brings these guarantees to AI agents.
+
+## Features
+
+- **Durable execution** — Agent state survives process restarts and failures
+- **Thread management** — Redis-backed conversation storage with automatic persistence
+- **Type-safe tools** — Define tools with Zod schemas, get full TypeScript inference
+- **Lifecycle hooks** — Pre/post tool execution, session start/end
+- **Subagent support** — Spawn child agents as Temporal child workflows
+- **Filesystem utilities** — In-memory or custom providers for file operations
+- **Model flexibility** — Use any LLM provider via LangChain
+
+## LLM Integration
+
+Zeitlich uses [LangChain](https://js.langchain.com/) as the abstraction layer for LLM execution. This gives you:
+
+- **Provider flexibility** — Use Anthropic, OpenAI, Google, Azure, AWS Bedrock, or any LangChain-supported provider
+- **Consistent interface** — Same tool calling and message format regardless of provider
+- **Easy model swapping** — Change models without rewriting agent logic
+- **Soon** — Support native provider SDKs directly
+
+```typescript
+import { ChatAnthropic } from "@langchain/anthropic";
+import { ChatOpenAI } from "@langchain/openai";
+import { ChatGoogleGenerativeAI } from "@langchain/google-genai";
+
+// Use any LangChain chat model
+const anthropic = new ChatAnthropic({ model: "claude-sonnet-4-20250514" });
+const openai = new ChatOpenAI({ model: "gpt-4o" });
+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),
+};
+```
+
+Install the LangChain package for your chosen provider:
+
+```bash
+npm install @langchain/anthropic  # Anthropic
+npm install @langchain/openai     # OpenAI
+npm install @langchain/google-genai # Google
+```
+
+## Installation
+
+```bash
+npm install zeitlich ioredis
+```
+
+**Peer dependencies:**
+
+- `ioredis` >= 5.0.0
+
+**Required infrastructure:**
+
+- Temporal server (local dev: `temporal server start-dev`)
+- Redis instance
+
+## Import Paths
+
+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';
+
+// In activity files and worker setup - full functionality
+import { ZeitlichPlugin, invokeModel, createGlobHandler, ... } 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.
+
+## Examples
+
+Runnable examples (worker, client, workflows) are in a separate repo: [zeitlich-examples](https://github.com/bead-ai/zeitlich-examples).
+
+## Quick Start
+
+### 1. Define Your Tools
+
+```typescript
+import { z } from "zod";
+import type { ToolDefinition } from "zeitlich/workflow";
+
+export const searchTool: ToolDefinition<"Search", typeof searchSchema> = {
+  name: "Search",
+  description: "Search for information",
+  schema: z.object({
+    query: z.string().describe("The search query"),
+  }),
+};
+
+export const tools = { Search: searchTool };
+```
+
+### 2. Create Activities
+
+```typescript
+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({
+    model: "claude-sonnet-4-20250514",
+    maxTokens: 4096,
+  });
+
+  return {
+    runAgent: (config, invocationConfig) =>
+      invokeModel(
+        redis,
+        { ...config, tools: Object.values(tools) },
+        model,
+        invocationConfig
+      ),
+
+    handleSearchResult: async ({ args }) => {
+      // Your tool implementation
+      const results = await performSearch(args.query);
+      return { result: { results } };
+    },
+  };
+};
+```
+
+### 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";
+
+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 toolRouter = createToolRouter(
+    { registry: toolRegistry, threadId: runId, appendToolResult },
+    { Search: handleSearchResult }
+  );
+
+  const promptManager = createPromptManager({
+    baseSystemPrompt: "You are a helpful assistant.",
+    buildContextMessage: () => [{ type: "text", text: prompt }],
+  });
+
+  const session = await createSession(
+    { threadId: runId, agentName: "my-agent", maxTurns: 20 },
+    { runAgent, promptManager, toolRouter, toolRegistry }
+  );
+
+  await session.runSession(prompt, stateManager);
+  return stateManager.getCurrentState();
+}
+```
+
+### 4. Set Up the Worker
+
+```typescript
+import { Worker, NativeConnection } from "@temporalio/worker";
+import { ZeitlichPlugin } from "zeitlich";
+import Redis from "ioredis";
+import { createActivities } from "./activities";
+
+async function run() {
+  const connection = await NativeConnection.connect({
+    address: "localhost:7233",
+  });
+  const redis = new Redis({ host: "localhost", port: 6379 });
+
+  const worker = await Worker.create({
+    plugins: [new ZeitlichPlugin({ redis })],
+    connection,
+    taskQueue: "my-agent",
+    workflowsPath: require.resolve("./workflows"),
+    activities: createActivities(redis),
+  });
+
+  await worker.run();
+}
+```
+
+## Core Concepts
+
+### Agent State Manager
+
+Manages workflow state with automatic versioning and status tracking:
+
+```typescript
+import { createAgentStateManager } from "zeitlich/workflow";
+
+const stateManager = createAgentStateManager({
+  initialState: { customField: "value" },
+});
+
+// State operations
+stateManager.set("customField", "new 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
+
+Type-safe tool management with Zod validation:
+
+```typescript
+import { createToolRegistry } from "zeitlich/workflow";
+
+const registry = createToolRegistry({
+  Search: searchTool,
+  Calculate: calculateTool,
+});
+
+// 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
+```
+
+### Tool Router
+
+Routes tool calls to handlers with lifecycle hooks:
+
+```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" };
+      },
+    },
+  },
+  {
+    Search: handleSearchResult,
+    Calculate: handleCalculateResult,
+  }
+);
+```
+
+### Subagents
+
+Spawn child agents as Temporal child workflows:
+
+```typescript
+import { withSubagentSupport } from "zeitlich/workflow";
+import { z } from "zod";
+
+const { tools, taskHandler } = withSubagentSupport(baseTools, {
+  subagents: [
+    {
+      name: "researcher",
+      description: "Researches topics and returns findings",
+      workflowType: "researcherWorkflow",
+      resultSchema: z.object({
+        findings: z.string(),
+        sources: z.array(z.string()),
+      }),
+    },
+  ],
+});
+
+// Include taskHandler in your tool router
+const router = createToolRouter(
+  { registry, threadId, appendToolResult },
+  { ...handlers, Task: taskHandler }
+);
+```
+
+### Filesystem Utilities
+
+Built-in support for file operations with pluggable providers:
+
+```typescript
+// In workflow - use the pure utilities and tool definitions
+import {
+  buildFileTreePrompt,
+  globTool,
+  grepTool,
+  readTool,
+} from "zeitlich/workflow";
+
+// In activities - use the providers and handlers
+import {
+  InMemoryFileSystemProvider,
+  createGlobHandler,
+  createGrepHandler,
+  createReadHandler,
+} from "zeitlich";
+
+// 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 }),
+};
+
+// Generate context for the agent
+const fileTreeContext = buildFileTreePrompt(fileTree, {
+  headerText: "Available Files",
+});
+```
+
+### Built-in Tools
+
+Zeitlich provides ready-to-use tool definitions and handlers for common agent operations. More tools will be added in future releases.
+
+| 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))         |
+
+```typescript
+// Import tool definitions in workflows
+import {
+  readTool,
+  writeTool,
+  editTool,
+  globTool,
+  grepTool,
+  askUserQuestionTool,
+} from "zeitlich/workflow";
+
+// Import handlers in activities
+import {
+  createReadHandler,
+  createWriteHandler,
+  createEditHandler,
+  createGlobHandler,
+  createGrepHandler,
+} from "zeitlich";
+```
+
+## 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                                                |
+
+### 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` |
+
+### 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                                                    |
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        Temporal Worker                          │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │                    ZeitlichPlugin                         │  │
+│  │  • Registers shared activities (thread management)        │  │
+│  └──────────────────────────────────────────────────────────┘  │
+│                              │                                  │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │                      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    │   │  │
+│  │  └────────────────┘  └─────────────┘  └──────────────┘   │  │
+│  └──────────────────────────────────────────────────────────┘  │
+│                              │                                  │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │                      Activities                           │  │
+│  │  • runAgent (LLM invocation)                              │  │
+│  │  • Tool handlers                                          │  │
+│  └──────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+                    ┌─────────────────┐
+                    │      Redis      │
+                    │ • Thread state  │
+                    │ • Messages      │
+                    └─────────────────┘
+```
+
+## Requirements
+
+- Node.js >= 18
+- Temporal server
+- Redis
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a PR.
+
+## License
+
+MIT © [Bead Technologies Inc.](https://usebead.ai)

package/dist/index.d.mts

@@ -0,0 +1,152 @@
+import { T as ToolDefinition, I as InvocationConfig, A as AgentResponse, a as ActivityToolHandler, b as AskUserQuestionToolSchemaType, F as FileSystemProvider, c as FileNode, G as GlobToolSchemaType, d as GrepToolSchemaType, e as GrepMatch, R as ReadToolSchemaType, f as FileContent, W as WriteToolSchemaType, E as EditToolSchemaType } from './workflow-DeVGEXSc.mjs';
+export { g as AGENT_HANDLER_NAMES, h as AgentFile, i as AgentState, j as AgentStateManager, k as AgentStateManagerConfig, l as AgentStatus, m as AppendToolResultFn, B as BackendConfig, n as BaseAgentState, o as BaseFileSystemProvider, C as CompositeFileSystemProvider, p as FileResolver, q as FileSystemToolsConfig, r as FileTreeRenderOptions, s as GenericTaskToolSchemaType, t as GrepOptions, u as InMemoryFileSystemProvider, J as JsonPrimitive, v as JsonSerializable, w as JsonValue, P as ParsedToolCall, x as ParsedToolCallUnion, y as PostToolUseFailureHook, z as PostToolUseFailureHookContext, D as PostToolUseFailureHookResult, H as PostToolUseHook, K as PostToolUseHookContext, L as PreToolUseHook, M as PreToolUseHookContext, N as PreToolUseHookResult, O as ProcessToolCallsContext, Q as PromptManager, S as PromptManagerConfig, U as RawToolCall, V as RunAgentActivity, X as RunAgentConfig, Y as SessionEndHook, Z as SessionEndHookContext, _ as SessionExitReason, $ as SessionHooks, a0 as SessionLifecycleHooks, a1 as SessionStartHook, a2 as SessionStartHookContext, a3 as SubagentConfig, a4 as SubagentInput, a5 as SubagentSupportConfig, a6 as SubagentSupportResult, a7 as TaskHandlerResult, a8 as TaskToolSchemaType, a9 as ToolCallResult, aa as ToolCallResultUnion, ab as ToolHandler, ac as ToolHandlerMap, ad as ToolHandlerResponse, ae as ToolMap, af as ToolMessageContent, ag as ToolNames, ah as ToolRegistry, ai as ToolResultConfig, aj as ToolRouter, ak as ToolRouterHooks, al as ToolRouterOptions, am as ZeitlichAgentConfig, an as ZeitlichSession, ao as ZeitlichSharedActivities, ap as askUserQuestionTool, aq as buildFileTreePrompt, ar as createAgentStateManager, as as createPromptManager, at as createSession, au as createSharedActivities, av as createTaskHandler, aw as createTaskTool, ax as createToolRegistry, ay as createToolRouter, az as editTool, aA as fileContentToMessageContent, aB as findNodeByPath, aC as flattenFileTree, aD as globTool, aE as grepTool, aF as hasNoOtherToolCalls, aG as hasTaskTool, aH as isPathInScope, aI as isTerminalStatus, aJ as readTool, aK as withSubagentSupport, aL as writeTool } from './workflow-DeVGEXSc.mjs';
+import { SimplePlugin } from '@temporalio/plugin';
+import Redis from 'ioredis';
+import { BaseChatModel, BaseChatModelCallOptions, BindToolsInput } from '@langchain/core/language_models/chat_models';
+import { StoredMessage, ContentBlock } from '@langchain/core/messages';
+import 'zod';
+
+/**
+ * Options for the Zeitlich plugin
+ *
+ * @experimental The Zeitlich plugin is an experimental feature; APIs may change without notice.
+ */
+interface ZeitlichPluginOptions {
+    redis: Redis;
+}
+/**
+ * A Temporal plugin that integrates Zeitlich for use in workflows.
+ * This plugin creates shared activities for thread management.
+ * Workflow-specific activities (like runAgent) should be created separately.
+ *
+ * @experimental The Zeitlich plugin is an experimental feature; APIs may change without notice.
+ */
+declare class ZeitlichPlugin extends SimplePlugin {
+    constructor(options: ZeitlichPluginOptions);
+}
+
+/**
+ * Configuration for invoking the model
+ */
+interface InvokeModelConfig {
+    threadId: string;
+    agentName: string;
+    tools: ToolDefinition[];
+}
+/**
+ * Core model invocation logic - shared utility for workflow-specific activities
+ *
+ * @param redis - Redis client for thread management
+ * @param config - Model invocation configuration
+ * @param model - Pre-instantiated LangChain chat model
+ * @param invocationConfig - Per-invocation configuration (system prompt, etc.)
+ * @returns Agent response with message and metadata
+ */
+declare function invokeModel(redis: Redis, { threadId, agentName, tools }: InvokeModelConfig, model: BaseChatModel<BaseChatModelCallOptions & {
+    tools?: BindToolsInput;
+}>, { systemPrompt }: InvocationConfig): Promise<AgentResponse>;
+
+/**
+ * Handle user interaction tool result - creates AI messages for display.
+ */
+declare const handleAskUserQuestionToolResult: ActivityToolHandler<AskUserQuestionToolSchemaType, {
+    chatMessages: StoredMessage[];
+}>;
+
+interface GlobHandlerConfig {
+    provider: FileSystemProvider;
+    scopedNodes: FileNode[];
+}
+/**
+ * Create a glob handler that searches within the scoped file tree.
+ */
+declare function createGlobHandler(config: GlobHandlerConfig): (args: GlobToolSchemaType) => Promise<{
+    content: string;
+    result: {
+        files: FileNode[];
+    };
+}>;
+
+interface GrepHandlerConfig {
+    provider: FileSystemProvider;
+    scopedNodes: FileNode[];
+}
+/**
+ * Create a grep handler that searches within the scoped file tree.
+ */
+declare function createGrepHandler(config: GrepHandlerConfig): (args: GrepToolSchemaType) => Promise<{
+    content: string;
+    result: {
+        matches: GrepMatch[];
+    };
+}>;
+
+interface ReadHandlerConfig {
+    provider: FileSystemProvider;
+    scopedNodes: FileNode[];
+}
+/**
+ * Create a read handler that reads files within the scoped file tree.
+ */
+declare function createReadHandler(config: ReadHandlerConfig): (args: ReadToolSchemaType) => Promise<{
+    content: ContentBlock[];
+    result: {
+        path: string;
+        content: FileContent;
+    };
+}>;
+
+interface WriteHandlerConfig {
+    provider: FileSystemProvider;
+    scopedNodes: FileNode[];
+    /**
+     * Set of file paths that have been read in this session.
+     * Required for enforcing read-before-write policy.
+     */
+    readFiles: Set<string>;
+    /**
+     * If true, skip the read-before-write check (not recommended)
+     */
+    skipReadCheck?: boolean;
+}
+interface WriteResult {
+    path: string;
+    success: boolean;
+    created: boolean;
+    bytesWritten: number;
+}
+/**
+ * Create a write handler that writes files within the scoped file tree.
+ */
+declare function createWriteHandler(config: WriteHandlerConfig): (args: WriteToolSchemaType) => Promise<{
+    content: string;
+    result: WriteResult;
+}>;
+
+interface EditHandlerConfig {
+    provider: FileSystemProvider;
+    scopedNodes: FileNode[];
+    /**
+     * Set of file paths that have been read in this session.
+     * Required for enforcing read-before-write policy.
+     */
+    readFiles: Set<string>;
+    /**
+     * If true, skip the read-before-write check (not recommended)
+     */
+    skipReadCheck?: boolean;
+}
+interface EditResult {
+    path: string;
+    success: boolean;
+    replacements: number;
+}
+/**
+ * Create an edit handler that edits files within the scoped file tree.
+ */
+declare function createEditHandler(config: EditHandlerConfig): (args: EditToolSchemaType) => Promise<{
+    content: string;
+    result: EditResult;
+}>;
+
+export { ActivityToolHandler, AgentResponse, AskUserQuestionToolSchemaType, type EditHandlerConfig, type EditResult, EditToolSchemaType, FileContent, FileNode, FileSystemProvider, type GlobHandlerConfig, GlobToolSchemaType, type GrepHandlerConfig, GrepMatch, GrepToolSchemaType, InvocationConfig, type InvokeModelConfig, type ReadHandlerConfig, ReadToolSchemaType, ToolDefinition, type WriteHandlerConfig, type WriteResult, WriteToolSchemaType, ZeitlichPlugin, type ZeitlichPluginOptions, createEditHandler, createGlobHandler, createGrepHandler, createReadHandler, createWriteHandler, handleAskUserQuestionToolResult, invokeModel };