zeitlich 0.1.1 → 0.2.0

package/src/tools/edit/handler.ts

@@ -0,0 +1,156 @@
+import type { EditToolSchemaType } from "./tool";
+import type { IFileSystem } from "just-bash";
+
+/**
+ * Result of an edit operation
+ */
+export interface EditResult {
+  path: string;
+  success: boolean;
+  replacements: number;
+}
+
+/**
+ * Edit handler response
+ */
+export interface EditHandlerResponse {
+  content: string;
+  result: EditResult;
+}
+
+/**
+ * Options for edit handler
+ */
+export interface EditHandlerOptions {
+  /**
+   * 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;
+}
+
+/**
+ * Escape special regex characters in a string
+ */
+function escapeRegExp(str: string): string {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Edit handler that edits files within the scoped file tree.
+ *
+ * @param args - Tool arguments (file_path, old_string, new_string, replace_all)
+ * @param options - Additional options (readFiles, skipReadCheck)
+ */
+export async function editHandler(
+  args: EditToolSchemaType,
+  fs: IFileSystem
+): Promise<EditHandlerResponse> {
+  const { file_path, old_string, new_string, replace_all = false } = args;
+
+  // Validate old_string !== new_string
+  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 {
+    // Check if file exists
+    const exists = await fs.exists(file_path);
+    if (!exists) {
+      return {
+        content: `Error: File "${file_path}" does not exist.`,
+        result: {
+          path: file_path,
+          success: false,
+          replacements: 0,
+        },
+      };
+    }
+
+    // Read current content
+    const content = await fs.readFile(file_path);
+
+    // Check if old_string exists in the file
+    if (!content.includes(old_string)) {
+      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,
+        },
+      };
+    }
+
+    // Count occurrences
+    const escapedOldString = escapeRegExp(old_string);
+    const globalRegex = new RegExp(escapedOldString, "g");
+    const occurrences = (content.match(globalRegex) || []).length;
+
+    // Check uniqueness if not replace_all
+    if (!replace_all && occurrences > 1) {
+      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,
+        },
+      };
+    }
+
+    // Perform replacement
+    let newContent: string;
+    let replacements: number;
+
+    if (replace_all) {
+      newContent = content.split(old_string).join(new_string);
+      replacements = occurrences;
+    } else {
+      // Replace only the first occurrence
+      const index = content.indexOf(old_string);
+      newContent =
+        content.slice(0, index) +
+        new_string +
+        content.slice(index + old_string.length);
+      replacements = 1;
+    }
+
+    // Write the modified content
+    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,
+      },
+    };
+  }
+}

package/src/tools/edit/tool.ts

@@ -0,0 +1,39 @@
+import { z } from "zod";
+
+export const editTool = {
+  name: "FileEdit" as const,
+  description: `Edit specific sections of a file by replacing text.
+
+Usage:
+- Provide the exact text to find and replace
+- The old_string must match exactly (whitespace-sensitive)
+- By default, only replaces the first occurrence
+- Use replace_all: true to replace all occurrences
+
+IMPORTANT:
+- You must read the file first (in this session) before editing it
+- old_string must be unique in the file (unless using replace_all)
+- The operation fails if old_string is not found
+- old_string and new_string must be different
+`,
+  schema: z.object({
+    file_path: z
+      .string()
+      .describe("The absolute virtual path to the file to modify"),
+    old_string: z.string().describe("The exact text to replace"),
+    new_string: z
+      .string()
+      .describe(
+        "The text to replace it with (must be different from old_string)"
+      ),
+    replace_all: z
+      .boolean()
+      .optional()
+      .describe(
+        "If true, replace all occurrences of old_string (default: false)"
+      ),
+  }),
+  strict: true,
+};
+
+export type EditToolSchemaType = z.infer<typeof editTool.schema>;

package/src/tools/glob/handler.ts

@@ -0,0 +1,62 @@
+import type { IFileSystem } from "just-bash";
+import { Bash } from "just-bash";
+import type { GlobToolSchemaType } from "./tool";
+
+/**
+ * Result of a glob operation
+ */
+export interface GlobResult {
+  files: string[];
+}
+
+/**
+ * Glob handler response
+ */
+export interface GlobHandlerResponse {
+  content: string;
+  result: GlobResult;
+}
+
+/**
+ * Glob handler that searches within the scoped file tree.
+ *
+ * @param args - Tool arguments (pattern, root)
+ * @param provider - FileSystemProvider for I/O operations
+ */
+export async function globHandler(
+  _args: GlobToolSchemaType,
+  fs: IFileSystem
+): Promise<GlobHandlerResponse> {
+  // const { pattern, root } = args;
+  const _bash = new Bash({ fs });
+
+  return Promise.resolve({
+    content: "Hello, world!",
+    result: { files: [] },
+  });
+
+  // try {
+  //   const matches = await bash.exec(`glob ${root} -name "${pattern}"`);
+
+  //   if (matches.length === 0) {
+  //     return {
+  //       content: `No files found matching pattern: ${pattern}`,
+  //       result: { files: [] },
+  //     };
+  //   }
+
+  //   const paths = matches.map((node) => node.path);
+  //   const fileList = paths.map((p) => `  ${p}`).join("\n");
+
+  //   return {
+  //     content: `Found ${matches.length} file(s) matching "${pattern}":\n${fileList}`,
+  //     result: { files: matches },
+  //   };
+  // } catch (error) {
+  //   const message = error instanceof Error ? error.message : "Unknown error";
+  //   return {
+  //     content: `Error searching for files: ${message}`,
+  //     result: { files: [] },
+  //   };
+  // }
+}

package/src/tools/glob/tool.ts

@@ -0,0 +1,27 @@
+import { z } from "zod";
+
+export const globTool = {
+  name: "Glob" as const,
+  description: `Search for files matching a glob pattern within the available file system.
+
+Usage:
+- Use glob patterns like "**/*.ts" to find all TypeScript files
+- Use "docs/**" to find all files in the docs directory
+- Patterns are matched against virtual paths in the file system
+
+Examples:
+- "*.md" - Find all markdown files in the root
+- "**/*.test.ts" - Find all test files recursively
+- "src/**/*.ts" - Find all TypeScript files in src directory
+`,
+  schema: z.object({
+    pattern: z.string().describe("Glob pattern to match files against"),
+    root: z
+      .string()
+      .optional()
+      .describe("Optional root directory to search from"),
+  }),
+  strict: true,
+};
+
+export type GlobToolSchemaType = z.infer<typeof globTool.schema>;

package/src/tools/grep/tool.ts

@@ -0,0 +1,45 @@
+import { z } from "zod";
+
+export const grepTool = {
+  name: "Grep" as const,
+  description: `Search file contents for a pattern within the available file system.
+
+Usage:
+- Searches for a regex pattern across file contents
+- Returns matching lines with file paths and line numbers
+- Can filter by file patterns and limit results
+
+Examples:
+- Search for "TODO" in all files
+- Search for function definitions with "function.*handleClick"
+- Search case-insensitively with ignoreCase: true
+`,
+  schema: z.object({
+    pattern: z
+      .string()
+      .describe("Regex pattern to search for in file contents"),
+    ignoreCase: z
+      .boolean()
+      .optional()
+      .describe("Case-insensitive search (default: false)"),
+    maxMatches: z
+      .number()
+      .optional()
+      .describe("Maximum number of matches to return (default: 50)"),
+    includePatterns: z
+      .array(z.string())
+      .optional()
+      .describe("Glob patterns to include (e.g., ['*.ts', '*.js'])"),
+    excludePatterns: z
+      .array(z.string())
+      .optional()
+      .describe("Glob patterns to exclude (e.g., ['*.test.ts'])"),
+    contextLines: z
+      .number()
+      .optional()
+      .describe("Number of context lines to show around matches"),
+  }),
+  strict: true,
+};
+
+export type GrepToolSchemaType = z.infer<typeof grepTool.schema>;

package/src/tools/read/tool.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+
+export const readTool = {
+  name: "FileRead" as const,
+  description: `Read file contents with optional pagination.
+
+Usage:
+- Provide the virtual path to the file you want to read
+- Supports text files, images, and PDFs
+- For large files, use offset and limit to read specific portions
+
+The tool returns the file content in an appropriate format:
+- Text files: Plain text content
+- Images: Base64-encoded image data
+- PDFs: Extracted text content
+`,
+  schema: z.object({
+    path: z.string().describe("Virtual path to the file to read"),
+    offset: z
+      .number()
+      .optional()
+      .describe(
+        "Line number to start reading from (1-indexed, for text files)"
+      ),
+    limit: z
+      .number()
+      .optional()
+      .describe("Maximum number of lines to read (for text files)"),
+  }),
+  strict: true,
+};
+
+export type ReadToolSchemaType = z.infer<typeof readTool.schema>;

package/src/tools/task/handler.ts

@@ -0,0 +1,75 @@
+import { executeChild, workflowInfo, uuid4 } from "@temporalio/workflow";
+import type { ToolHandlerResponse } from "../../lib/tool-router";
+import type { SubagentConfig, SubagentInput } from "../../lib/types";
+import type { GenericTaskToolSchemaType } from "./tool";
+
+/**
+ * Result from a task handler execution
+ */
+export interface TaskHandlerResult<TResult = unknown> {
+  /** The validated result from the child workflow */
+  result: TResult;
+  /** The child workflow ID (for reference/debugging) */
+  childWorkflowId: string;
+}
+
+/**
+ * Creates a Task tool handler that spawns child workflows for configured subagents.
+ *
+ * @param subagents - Array of subagent configurations
+ * @returns A tool handler function that can be used with the tool router
+ *
+ * @example
+ * const taskHandler = taskHandler([
+ *   {
+ *     name: "researcher",
+ *     description: "Researches topics",
+ *     workflowType: "researcherWorkflow",
+ *     resultSchema: z.object({ findings: z.string() }),
+ *   },
+ * ]);
+ */
+export function createTaskHandler(subagents: SubagentConfig[]) {
+  const { workflowId: parentWorkflowId, taskQueue: parentTaskQueue } =
+    workflowInfo();
+
+  return async (
+    args: GenericTaskToolSchemaType
+  ): Promise<ToolHandlerResponse<TaskHandlerResult>> => {
+    const config = subagents.find((s) => s.name === args.subagent);
+
+    if (!config) {
+      throw new Error(
+        `Unknown subagent: ${args.subagent}. Available: ${subagents.map((s) => s.name).join(", ")}`
+      );
+    }
+
+    const childWorkflowId = `${parentWorkflowId}-${args.subagent}-${uuid4()}`;
+
+    // Execute the child workflow
+    const childResult = await executeChild(config.workflowType, {
+      workflowId: childWorkflowId,
+      args: [{ prompt: args.prompt } satisfies SubagentInput],
+      taskQueue: config.taskQueue ?? parentTaskQueue,
+    });
+
+    // Validate result if schema provided, otherwise pass through as-is
+    const validated = config.resultSchema
+      ? config.resultSchema.parse(childResult)
+      : childResult;
+
+    // Format content - stringify objects, pass strings through
+    const content =
+      typeof validated === "string"
+        ? validated
+        : JSON.stringify(validated, null, 2);
+
+    return {
+      content,
+      result: {
+        result: validated,
+        childWorkflowId,
+      },
+    };
+  };
+}

package/src/tools/task/tool.ts

@@ -0,0 +1,96 @@
+import z from "zod";
+import type { SubagentConfig } from "../../lib/types";
+
+const TASK_TOOL = "Task" as const;
+
+/**
+ * Builds the tool description with available subagent information
+ */
+function buildTaskDescription(subagents: SubagentConfig[]): string {
+  const subagentList = subagents
+    .map((s) => `- **${s.name}**: ${s.description}`)
+    .join("\n");
+
+  return `Launch a new agent to handle complex, multi-step tasks autonomously.
+
+The ${TASK_TOOL} tool launches specialized agents (subprocesses) that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
+
+Available agent types:
+
+${subagentList}
+
+When using the ${TASK_TOOL} tool, you must specify a subagent parameter to select which agent type to use.
+
+Usage notes:
+
+- Always include a short description (3-5 words) summarizing what the agent will do
+- Launch multiple agents concurrently whenever possible, to maximize performance; to do that, use a single message with multiple tool uses
+- When the agent is done, it will return a single message back to you. The result returned by the agent is not visible to the user. To show the user the result, you should send a text message back to the user with a concise summary of the result.
+- Each invocation starts fresh - provide a detailed task description with all necessary context.
+- Provide clear, detailed prompts so the agent can work autonomously and return exactly the information you need.
+- The agent's outputs should generally be trusted
+- Clearly tell the agent what type of work you expect since it is not aware of the user's intent
+- If the agent description mentions that it should be used proactively, then you should try your best to use it without the user having to ask for it first. Use your judgement.`;
+}
+
+/**
+ * Creates a Task tool configured with the available subagents.
+ *
+ * @param subagents - Array of subagent configurations (must have at least one)
+ * @returns A tool definition with dynamic schema based on available subagents
+ *
+ * @example
+ * const taskTool = createTaskTool([
+ *   {
+ *     name: "researcher",
+ *     description: "Researches topics and gathers information",
+ *     workflowType: "researcherWorkflow",
+ *     resultSchema: z.object({ findings: z.string() }),
+ *   },
+ * ]);
+ */
+export function createTaskTool<T extends SubagentConfig[]>(
+  subagents: T
+): {
+  name: string;
+  description: string;
+  schema: z.ZodObject<{
+    subagent: z.ZodEnum<Record<string, string>>;
+    description: z.ZodString;
+    prompt: z.ZodString;
+  }>;
+} {
+  if (subagents.length === 0) {
+    throw new Error("createTaskTool requires at least one subagent");
+  }
+
+  const names = subagents.map((s) => s.name);
+
+  return {
+    name: TASK_TOOL,
+    description: buildTaskDescription(subagents),
+    schema: z.object({
+      subagent: z.enum(names).describe("The type of subagent to launch"),
+      description: z
+        .string()
+        .describe("A short (3-5 word) description of the task"),
+      prompt: z.string().describe("The task for the agent to perform"),
+    }),
+  } as const;
+}
+
+/**
+ * Infer the schema type for a task tool created with specific subagents
+ */
+export type TaskToolSchemaType<T extends SubagentConfig[]> = z.infer<
+  ReturnType<typeof createTaskTool<T>>["schema"]
+>;
+
+/**
+ * Generic task tool schema type (when subagent names are not known at compile time)
+ */
+export type GenericTaskToolSchemaType = {
+  subagent: string;
+  description: string;
+  prompt: string;
+};

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

@@ -0,0 +1,49 @@
+import type {
+  AgentStateManager,
+  JsonSerializable,
+} from "../../lib/state-manager";
+import type { ToolHandlerResponse } from "../../lib/tool-router";
+import type { WorkflowTask } from "../../lib/types";
+import type { TaskCreateToolSchemaType } from "./tool";
+
+/**
+ * Creates a TaskCreate handler that adds tasks to the workflow state.
+ *
+ * @param stateManager - State manager containing tasks state
+ * @param idGenerator - Function to generate unique task IDs (e.g., uuid4 from Temporal)
+ * @returns A tool handler function
+ *
+ * @example
+ * const handler = createTaskCreateHandler(stateManager, uuid4);
+ */
+export function createTaskCreateHandler<
+  TCustom extends JsonSerializable<TCustom>,
+>({
+  stateManager,
+  idGenerator,
+}: {
+  stateManager: AgentStateManager<TCustom>;
+  idGenerator: () => string;
+}): (args: TaskCreateToolSchemaType) => ToolHandlerResponse<WorkflowTask> {
+  return (
+    args: TaskCreateToolSchemaType
+  ): ToolHandlerResponse<WorkflowTask> => {
+    const task: WorkflowTask = {
+      id: idGenerator(),
+      subject: args.subject,
+      description: args.description,
+      activeForm: args.activeForm,
+      status: "pending",
+      metadata: args.metadata ?? {},
+      blockedBy: [],
+      blocks: [],
+    };
+
+    stateManager.setTask(task);
+
+    return {
+      content: JSON.stringify(task, null, 2),
+      result: task,
+    };
+  };
+}

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

@@ -0,0 +1,66 @@
+import z from "zod";
+
+export const taskCreateTool = {
+  name: "TaskCreate" as const,
+  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: z.object({
+    subject: z
+      .string()
+      .describe(
+        'A brief, actionable title in imperative form (e.g., "Fix authentication bug in login flow")'
+      ),
+    description: z
+      .string()
+      .describe(
+        "Detailed description of what needs to be done, including context and acceptance criteria"
+      ),
+    activeForm: z
+      .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: z
+      .record(z.string(), z.string())
+      .describe("Arbitrary key-value pairs for tracking"),
+  }),
+};
+
+export type TaskCreateToolSchemaType = z.infer<typeof taskCreateTool.schema>;

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

@@ -0,0 +1,38 @@
+import type {
+  AgentStateManager,
+  JsonSerializable,
+} from "../../lib/state-manager";
+import type { ToolHandlerResponse } from "../../lib/tool-router";
+import type { WorkflowTask } from "../../lib/types";
+import type { TaskGetToolSchemaType } from "./tool";
+
+/**
+ * Creates a TaskGet handler that retrieves a task by ID.
+ *
+ * @param stateManager - State manager containing tasks state
+ * @returns A tool handler function
+ *
+ * @example
+ * const handler = createTaskGetHandler(stateManager);
+ */
+export function createTaskGetHandler<TCustom extends JsonSerializable<TCustom>>(
+  stateManager: AgentStateManager<TCustom>
+): (args: TaskGetToolSchemaType) => ToolHandlerResponse<WorkflowTask | null> {
+  return (
+    args: TaskGetToolSchemaType
+  ): ToolHandlerResponse<WorkflowTask | null> => {
+    const task = stateManager.getTask(args.taskId) ?? null;
+
+    if (!task) {
+      return {
+        content: JSON.stringify({ error: `Task not found: ${args.taskId}` }),
+        result: null,
+      };
+    }
+
+    return {
+      content: JSON.stringify(task, null, 2),
+      result: task,
+    };
+  };
+}