zeitlich 0.1.1 → 0.2.0

package/src/tools/task-get/tool.ts

@@ -0,0 +1,11 @@
+import z from "zod";
+
+export const taskGetTool = {
+  name: "TaskGet" as const,
+  description: `Retrieve full task details including dependencies.`,
+  schema: z.object({
+    taskId: z.string().describe("The ID of the task to get"),
+  }),
+};
+
+export type TaskGetToolSchemaType = z.infer<typeof taskGetTool.schema>;

package/src/tools/task-list/handler.ts

@@ -0,0 +1,33 @@
+import type {
+  AgentStateManager,
+  JsonSerializable,
+} from "../../lib/state-manager";
+import type { ToolHandlerResponse } from "../../lib/tool-router";
+import type { WorkflowTask } from "../../lib/types";
+import type { TaskListToolSchemaType } from "./tool";
+
+/**
+ * Creates a TaskList handler that returns all tasks.
+ *
+ * @param stateManager - State manager containing tasks state
+ * @returns A tool handler function
+ *
+ * @example
+ * const handler = createTaskListHandler(stateManager);
+ */
+export function createTaskListHandler<
+  TCustom extends JsonSerializable<TCustom>,
+>(
+  stateManager: AgentStateManager<TCustom>
+): (args: TaskListToolSchemaType) => ToolHandlerResponse<WorkflowTask[]> {
+  return (
+    _args: TaskListToolSchemaType
+  ): ToolHandlerResponse<WorkflowTask[]> => {
+    const taskList = stateManager.getTasks();
+
+    return {
+      content: JSON.stringify(taskList, null, 2),
+      result: taskList,
+    };
+  };
+}

package/src/tools/task-list/tool.ts

@@ -0,0 +1,9 @@
+import z from "zod";
+
+export const taskListTool = {
+  name: "TaskList" as const,
+  description: `List all tasks with current state.`,
+  schema: z.object({}),
+};
+
+export type TaskListToolSchemaType = z.infer<typeof taskListTool.schema>;

package/src/tools/task-update/handler.ts

@@ -0,0 +1,79 @@
+import type {
+  AgentStateManager,
+  JsonSerializable,
+} from "../../lib/state-manager";
+import type { ToolHandlerResponse } from "../../lib/tool-router";
+import type { WorkflowTask } from "../../lib/types";
+import type { TaskUpdateToolSchemaType } from "./tool";
+
+/**
+ * Creates a TaskUpdate handler that modifies task status and dependencies.
+ *
+ * @param stateManager - State manager containing tasks state
+ * @returns A tool handler function
+ *
+ * @example
+ * const handler = createTaskUpdateHandler(stateManager);
+ */
+export function createTaskUpdateHandler<
+  TCustom extends JsonSerializable<TCustom>,
+>(
+  stateManager: AgentStateManager<TCustom>
+): (
+  args: TaskUpdateToolSchemaType
+) => ToolHandlerResponse<WorkflowTask | null> {
+  return (
+    args: TaskUpdateToolSchemaType
+  ): ToolHandlerResponse<WorkflowTask | null> => {
+    const task = stateManager.getTask(args.taskId);
+
+    if (!task) {
+      return {
+        content: JSON.stringify({ error: `Task not found: ${args.taskId}` }),
+        result: null,
+      };
+    }
+
+    // Update status if provided
+    if (args.status) {
+      task.status = args.status;
+    }
+
+    // Add blockedBy relationships (bidirectional)
+    if (args.addBlockedBy) {
+      for (const blockerId of args.addBlockedBy) {
+        if (!task.blockedBy.includes(blockerId)) {
+          task.blockedBy.push(blockerId);
+        }
+        // Update the blocker task's blocks array
+        const blockerTask = stateManager.getTask(blockerId);
+        if (blockerTask && !blockerTask.blocks.includes(task.id)) {
+          blockerTask.blocks.push(task.id);
+          stateManager.setTask(blockerTask);
+        }
+      }
+    }
+
+    // Add blocks relationships (bidirectional)
+    if (args.addBlocks) {
+      for (const blockedId of args.addBlocks) {
+        if (!task.blocks.includes(blockedId)) {
+          task.blocks.push(blockedId);
+        }
+        // Update the blocked task's blockedBy array
+        const blockedTask = stateManager.getTask(blockedId);
+        if (blockedTask && !blockedTask.blockedBy.includes(task.id)) {
+          blockedTask.blockedBy.push(task.id);
+          stateManager.setTask(blockedTask);
+        }
+      }
+    }
+
+    stateManager.setTask(task);
+
+    return {
+      content: JSON.stringify(task, null, 2),
+      result: task,
+    };
+  };
+}

package/src/tools/task-update/tool.ts

@@ -0,0 +1,20 @@
+import z from "zod";
+
+export const taskUpdateTool = {
+  name: "TaskUpdate" as const,
+  description: `Update status, add blockers, modify details.`,
+  schema: z.object({
+    taskId: z.string().describe("The ID of the task to get"),
+    status: z
+      .enum(["pending", "in_progress", "completed"])
+      .describe("The status of the task"),
+    addBlockedBy: z
+      .array(z.string())
+      .describe("The IDs of the tasks that are blocking this task"),
+    addBlocks: z
+      .array(z.string())
+      .describe("The IDs of the tasks that this task is blocking"),
+  }),
+};
+
+export type TaskUpdateToolSchemaType = z.infer<typeof taskUpdateTool.schema>;

package/src/tools/write/tool.ts

@@ -0,0 +1,26 @@
+import { z } from "zod";
+
+export const writeTool = {
+  name: "FileWrite" as const,
+  description: `Create or overwrite a file with new content.
+
+Usage:
+- Provide the absolute virtual path to the file
+- The file will be created if it doesn't exist
+- If the file exists, it will be completely overwritten
+
+IMPORTANT:
+- You must read the file first (in this session) before writing to it
+- 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: z.object({
+    file_path: z
+      .string()
+      .describe("The absolute virtual path to the file to write"),
+    content: z.string().describe("The content to write to the file"),
+  }),
+  strict: true,
+};
+
+export type WriteToolSchemaType = z.infer<typeof writeTool.schema>;

package/src/workflow.ts

@@ -0,0 +1,138 @@
+/**
+ * Workflow-safe exports for use in Temporal workflow code.
+ *
+ * Import from '@bead-ai/zeitlich/workflow' in workflow files.
+ * These exports have no external dependencies (no Redis, no LangChain).
+ *
+ * @example
+ * ```typescript
+ * // In your workflow file
+ * import {
+ *   createSession,
+ *   createAgentStateManager,
+ *   createToolRouter,
+ * } from '@bead-ai/zeitlich/workflow';
+ * ```
+ */
+
+// Session
+export { createSession } from "./lib/session";
+export type { ZeitlichSession, SessionLifecycleHooks } from "./lib/session";
+
+// State management
+export {
+  createAgentStateManager,
+  AGENT_HANDLER_NAMES,
+} from "./lib/state-manager";
+export type {
+  AgentState,
+  AgentStateManager,
+  JsonSerializable,
+  JsonValue,
+  JsonPrimitive,
+} from "./lib/state-manager";
+
+// Tool router (includes registry functionality)
+export { createToolRouter, hasNoOtherToolCalls } from "./lib/tool-router";
+export type {
+  // Tool definition types
+  ToolDefinition,
+  ToolWithHandler,
+  ToolMap,
+  ToolNames,
+  RawToolCall,
+  ParsedToolCall,
+  ParsedToolCallUnion,
+  // Router types
+  ToolRouter,
+  // Handler types
+  ToolHandler,
+  ActivityToolHandler,
+  ToolHandlerContext,
+  ToolHandlerResponse,
+  // Result types
+  ToolArgs,
+  ToolResult,
+  ToolCallResult,
+  ToolCallResultUnion,
+  InferToolResults,
+  // Other
+  ToolMessageContent,
+  AppendToolResultFn,
+  ProcessToolCallsContext,
+} from "./lib/tool-router";
+
+// Types
+export type {
+  AgentStatus,
+  BaseAgentState,
+  AgentFile,
+  AgentResponse,
+  ZeitlichAgentConfig,
+  RunAgentConfig,
+  RunAgentActivity,
+  ToolResultConfig,
+  SessionExitReason,
+  PreToolUseHook,
+  PreToolUseHookContext,
+  PreToolUseHookResult,
+  PostToolUseHook,
+  PostToolUseHookContext,
+  PostToolUseFailureHook,
+  PostToolUseFailureHookContext,
+  PostToolUseFailureHookResult,
+  SessionStartHook,
+  SessionStartHookContext,
+  SessionEndHook,
+  SessionEndHookContext,
+  SubagentConfig,
+  SubagentInput,
+  TaskStatus,
+  WorkflowTask,
+} from "./lib/types";
+export { isTerminalStatus } from "./lib/types";
+
+// Subagent support
+export { createTaskTool } from "./tools/task/tool";
+export type {
+  TaskToolSchemaType,
+  GenericTaskToolSchemaType,
+} from "./tools/task/tool";
+export type { TaskHandlerResult } from "./tools/task/handler";
+
+// Activity type interfaces (types only, no runtime code)
+// These are safe to import in workflows for typing proxyActivities
+export type { ZeitlichSharedActivities } from "./activities";
+
+// Tool definitions (schemas only - no handlers)
+export { askUserQuestionTool } from "./tools/ask-user-question/tool";
+export type { AskUserQuestionToolSchemaType } from "./tools/ask-user-question/tool";
+export { globTool } from "./tools/glob/tool";
+export type { GlobToolSchemaType } from "./tools/glob/tool";
+export { grepTool } from "./tools/grep/tool";
+export type { GrepToolSchemaType } from "./tools/grep/tool";
+export { readTool } from "./tools/read/tool";
+export type { ReadToolSchemaType } from "./tools/read/tool";
+export { writeTool } from "./tools/write/tool";
+export type { WriteToolSchemaType } from "./tools/write/tool";
+export { editTool } from "./tools/edit/tool";
+export type { EditToolSchemaType } from "./tools/edit/tool";
+
+// Workflow task tools (state-only, no activities needed)
+export { taskCreateTool } from "./tools/task-create/tool";
+export type { TaskCreateToolSchemaType } from "./tools/task-create/tool";
+export { createTaskCreateHandler } from "./tools/task-create/handler";
+
+export { taskGetTool } from "./tools/task-get/tool";
+export type { TaskGetToolSchemaType } from "./tools/task-get/tool";
+export { createTaskGetHandler } from "./tools/task-get/handler";
+
+export { taskListTool } from "./tools/task-list/tool";
+export { createTaskListHandler } from "./tools/task-list/handler";
+
+export { taskUpdateTool } from "./tools/task-update/tool";
+export type { TaskUpdateToolSchemaType } from "./tools/task-update/tool";
+export { createTaskUpdateHandler } from "./tools/task-update/handler";
+
+export { bashTool } from "./tools/bash/tool";
+export type { bashToolSchemaType } from "./tools/bash/tool";

package/tsup.config.ts

@@ -0,0 +1,20 @@
+import { defineConfig } from "tsup";
+
+export default defineConfig({
+  entry: {
+    index: "src/index.ts",
+    workflow: "src/workflow.ts",
+  },
+  format: ["cjs", "esm"],
+  dts: true,
+  clean: true,
+  sourcemap: true,
+  splitting: false,
+  treeshake: true,
+  outDir: "dist",
+  external: [
+    /^@temporalio\//,
+    /^@langchain\//,
+    "ioredis",
+  ],
+});

package/dist/index.d.mts

@@ -1,152 +0,0 @@
-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-7_MT-5-w.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-7_MT-5-w.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 };