zeitlich 0.2.13 → 0.2.14

package/src/tools/edit/handler.ts

@@ -1,111 +1,97 @@
 import type { ActivityToolHandler } from "../../lib/tool-router";
+import type { SandboxContext } from "../../lib/tool-router/with-sandbox";
 import type { FileEditArgs } from "./tool";
-import type { IFileSystem } from "just-bash";
 
-/**
- * Result of an edit operation
- */
 interface EditResult {
   path: string;
   success: boolean;
   replacements: number;
 }
 
-/**
- * Escape special regex characters in a string
- */
 function escapeRegExp(str: string): string {
   return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
 
 /**
- * Creates an edit handler that edits files within the scoped file tree.
+ * Edit tool handler — performs string replacements in sandbox files.
  *
- * @param fs - File system implementation for I/O operations
- * @returns An ActivityToolHandler for edit tool calls
+ * Wrap with {@link withSandbox} at activity registration time to inject the
+ * sandbox automatically.
  */
-export function createEditHandler(
-  fs: IFileSystem
-): ActivityToolHandler<FileEditArgs, EditResult> {
-  return async (args) => {
-    const { file_path, old_string, new_string, replace_all = false } = args;
+export const editHandler: ActivityToolHandler<
+  FileEditArgs,
+  EditResult,
+  SandboxContext
+> = async (args, { sandbox }) => {
+  const { fs } = sandbox;
+  const { file_path, old_string, new_string, replace_all = false } = args;
+
+  if (old_string === new_string) {
+    return {
+      toolResponse: `Error: old_string and new_string must be different.`,
+      data: { path: file_path, success: false, replacements: 0 },
+    };
+  }
 
-    // Validate old_string !== new_string
-    if (old_string === new_string) {
+  try {
+    const exists = await fs.exists(file_path);
+    if (!exists) {
       return {
-        toolResponse: `Error: old_string and new_string must be different.`,
+        toolResponse: `Error: File "${file_path}" does not exist.`,
         data: { path: file_path, success: false, replacements: 0 },
       };
     }
 
-    try {
-      // Check if file exists
-      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 },
-        };
-      }
-
-      // Read current content
-      const content = await fs.readFile(file_path);
+    const content = await fs.readFile(file_path);
 
-      // Check if old_string exists in the file
-      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 },
-        };
-      }
+    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 },
+      };
+    }
 
-      // Count occurrences
-      const escapedOldString = escapeRegExp(old_string);
-      const globalRegex = new RegExp(escapedOldString, "g");
-      const occurrences = (content.match(globalRegex) || []).length;
+    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 {
-          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 },
-        };
-      }
+    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 },
+      };
+    }
 
-      // Perform replacement
-      let newContent: string;
-      let replacements: number;
+    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;
-      }
+    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;
+    }
 
-      // Write the modified content
-      await fs.writeFile(file_path, newContent);
+    await fs.writeFile(file_path, newContent);
 
-      const summary = replace_all
-        ? `Replaced ${replacements} occurrence(s)`
-        : `Replaced 1 occurrence`;
+    const summary = replace_all
+      ? `Replaced ${replacements} occurrence(s)`
+      : `Replaced 1 occurrence`;
 
-      return {
-        toolResponse: `${summary} in ${file_path}`,
-        data: { path: file_path, success: true, replacements },
-      };
-    } catch (error) {
-      const message = error instanceof Error ? error.message : "Unknown error";
-      return {
-        toolResponse: `Error editing file "${file_path}": ${message}`,
-        data: { path: file_path, success: false, replacements: 0 },
-      };
-    }
-  };
-}
+    return {
+      toolResponse: `${summary} in ${file_path}`,
+      data: { path: file_path, success: true, replacements },
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    return {
+      toolResponse: `Error editing file "${file_path}": ${message}`,
+      data: { path: file_path, success: false, replacements: 0 },
+    };
+  }
+};

package/src/tools/glob/handler.ts

@@ -1,31 +1,74 @@
 import type { ActivityToolHandler } from "../../lib/tool-router";
+import type { SandboxContext } from "../../lib/tool-router/with-sandbox";
 import type { GlobArgs } from "./tool";
-import type { IFileSystem } from "just-bash";
-import { Bash } from "just-bash";
+import type { Sandbox } from "../../lib/sandbox/types";
 
-/**
- * Result of a glob operation
- */
 interface GlobResult {
   files: string[];
 }
 
 /**
- * Creates a glob handler that searches within the scoped file tree.
+ * Simple glob-style matcher (supports `*` and `**`).
+ */
+function matchGlob(pattern: string, path: string): boolean {
+  const regex = pattern
+    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
+    .replace(/\*\*/g, "{{GLOBSTAR}}")
+    .replace(/\*/g, "[^/]*")
+    .replace(/\{\{GLOBSTAR\}\}/g, ".*");
+  return new RegExp(`^${regex}$`).test(path);
+}
+
+async function walk(
+  fs: Sandbox["fs"],
+  dir: string,
+): Promise<string[]> {
+  const results: string[] = [];
+  const entries = await fs.readdirWithFileTypes(dir);
+  for (const entry of entries) {
+    const full = dir === "/" ? `/${entry.name}` : `${dir}/${entry.name}`;
+    if (entry.isDirectory) {
+      results.push(...(await walk(fs, full)));
+    } else {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+/**
+ * Glob tool handler — searches files within a {@link Sandbox} filesystem.
  *
- * @param fs - File system implementation for I/O operations
- * @returns An ActivityToolHandler for glob tool calls
+ * Wrap with {@link withSandbox} at activity registration time to inject the
+ * sandbox automatically.
  */
-export function createGlobHandler(
-  fs: IFileSystem
-): ActivityToolHandler<GlobArgs, GlobResult> {
-  return async (_args) => {
-    // const { pattern, root } = args;
-    const _bash = new Bash({ fs });
+export const globHandler: ActivityToolHandler<
+  GlobArgs,
+  GlobResult,
+  SandboxContext
+> = async (args, { sandbox }) => {
+  const { fs } = sandbox;
+  const { pattern, root = "/" } = args;
+
+  try {
+    const allFiles = await walk(fs, root);
+    const relativeTo = root.endsWith("/") ? root : `${root}/`;
+    const matched = allFiles
+      .map((f) => (f.startsWith(relativeTo) ? f.slice(relativeTo.length) : f))
+      .filter((f) => matchGlob(pattern, f));
 
     return {
-      toolResponse: "Hello, world!",
+      toolResponse:
+        matched.length > 0
+          ? `Found ${matched.length} file(s):\n${matched.join("\n")}`
+          : `No files matched pattern "${pattern}"`,
+      data: { files: matched },
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    return {
+      toolResponse: `Error running glob: ${message}`,
       data: { files: [] },
     };
-  };
-}
+  }
+};

package/src/tools/read-file/handler.ts

@@ -0,0 +1,67 @@
+import type { ActivityToolHandler } from "../../lib/tool-router";
+import type { SandboxContext } from "../../lib/tool-router/with-sandbox";
+import type { FileReadArgs } from "./tool";
+
+interface ReadFileResult {
+  path: string;
+  content: string;
+  totalLines?: number;
+}
+
+/**
+ * Read-file tool handler — reads files from a {@link Sandbox} filesystem.
+ *
+ * Wrap with {@link withSandbox} at activity registration time to inject the
+ * sandbox automatically.
+ */
+export const readFileHandler: ActivityToolHandler<
+  FileReadArgs,
+  ReadFileResult | null,
+  SandboxContext
+> = async (args, { sandbox }) => {
+  const { fs } = sandbox;
+  const { path, offset, limit } = args;
+
+  try {
+    const exists = await fs.exists(path);
+    if (!exists) {
+      return {
+        toolResponse: `Error: File "${path}" does not exist.`,
+        data: null,
+      };
+    }
+
+    const raw = await fs.readFile(path);
+    const lines = raw.split("\n");
+    const totalLines = lines.length;
+
+    if (offset !== undefined || limit !== undefined) {
+      const start = Math.max(0, (offset ?? 1) - 1);
+      const end = limit !== undefined ? start + limit : lines.length;
+      const slice = lines.slice(start, end);
+      const numbered = slice
+        .map((line, i) => `${String(start + i + 1).padStart(6)}|${line}`)
+        .join("\n");
+
+      return {
+        toolResponse: numbered,
+        data: { path, content: numbered, totalLines },
+      };
+    }
+
+    const numbered = lines
+      .map((line, i) => `${String(i + 1).padStart(6)}|${line}`)
+      .join("\n");
+
+    return {
+      toolResponse: numbered,
+      data: { path, content: numbered, totalLines },
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown error";
+    return {
+      toolResponse: `Error reading file "${path}": ${message}`,
+      data: null,
+    };
+  }
+};

package/src/tools/read-skill/handler.ts

@@ -1,31 +1 @@
-import type { Skill } from "../../lib/skills/types";
-import type { ToolHandlerResponse } from "../../lib/tool-router";
-import type { ReadSkillArgs } from "./tool";
-
-/**
- * Creates a ReadSkill handler that looks up skills from an in-memory array.
- * Runs directly in the workflow (like task tools) — no activity needed.
- */
-export function createReadSkillHandler(
-  skills: Skill[]
-): (args: ReadSkillArgs) => ToolHandlerResponse<null> {
-  const skillMap = new Map(skills.map((s) => [s.name, s]));
-
-  return (args: ReadSkillArgs): ToolHandlerResponse<null> => {
-    const skill = skillMap.get(args.skill_name);
-
-    if (!skill) {
-      return {
-        toolResponse: JSON.stringify({
-          error: `Skill "${args.skill_name}" not found`,
-        }),
-        data: null,
-      };
-    }
-
-    return {
-      toolResponse: skill.instructions,
-      data: null,
-    };
-  };
-}
+export { createReadSkillHandler } from "../../lib/skills/handler";

package/src/tools/read-skill/tool.ts

@@ -1,47 +1,5 @@
-import z from "zod";
-import type { Skill } from "../../lib/skills/types";
-
-export const READ_SKILL_TOOL_NAME = "ReadSkill" as const;
-
-function buildReadSkillDescription(skills: Skill[]): string {
-  const skillList = skills
-    .map((s) => `- **${s.name}**: ${s.description}`)
-    .join("\n");
-
-  return `Load the full instructions for a skill. Read the skill before following its instructions.
-
-# Available skills:
-${skillList}
-`;
-}
-
-/**
- * Creates a ReadSkill tool configured with the available skills.
- * The tool description embeds skill metadata so the agent discovers
- * skills purely through the tool definition.
- */
-export function createReadSkillTool(skills: Skill[]): {
-  name: string;
-  description: string;
-  schema: z.ZodObject<{
-    skill_name: z.ZodEnum<Record<string, string>>;
-  }>;
-} {
-  if (skills.length === 0) {
-    throw new Error("createReadSkillTool requires at least one skill");
-  }
-
-  const names = skills.map((s) => s.name);
-
-  return {
-    name: READ_SKILL_TOOL_NAME,
-    description: buildReadSkillDescription(skills),
-    schema: z.object({
-      skill_name: z.enum(names).describe("The name of the skill to load"),
-    }),
-  } as const;
-}
-
-export type ReadSkillArgs = {
-  skill_name: string;
-};
+export {
+  createReadSkillTool,
+  READ_SKILL_TOOL_NAME,
+  type ReadSkillArgs,
+} from "../../lib/skills/tool";

package/src/tools/subagent/handler.ts

@@ -1,100 +1 @@
-import { executeChild, workflowInfo } from "@temporalio/workflow";
-import { getShortId } from "../../lib/thread-id";
-import type { ToolHandlerResponse } from "../../lib/tool-router";
-import type { ToolMessageContent } from "../../lib/types";
-import type {
-  InferSubagentResult,
-  SubagentConfig,
-  SubagentInput,
-} from "../../lib/types";
-import type { SubagentArgs } from "./tool";
-import type { z } from "zod";
-
-/**
- * Creates a Subagent 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 subagentHandler = subagentHandler([
- *   {
- *     name: "researcher",
- *     description: "Researches topics",
- *     workflow: "researcherWorkflow",
- *     resultSchema: z.object({ findings: z.string() }),
- *   },
- * ]);
- */
-export function createSubagentHandler<
-  const T extends readonly SubagentConfig[],
->(subagents: [...T]) {
-  const { taskQueue: parentTaskQueue } = workflowInfo();
-
-  return async (
-    args: SubagentArgs
-  ): Promise<ToolHandlerResponse<InferSubagentResult<T[number]> | null>> => {
-    const config = subagents.find((s) => s.agentName === args.subagent);
-
-    if (!config) {
-      throw new Error(
-        `Unknown subagent: ${args.subagent}. Available: ${subagents.map((s) => s.agentName).join(", ")}`
-      );
-    }
-
-    const childWorkflowId = `${args.subagent}-${getShortId()}`;
-
-    const input: SubagentInput = {
-      prompt: args.prompt,
-      ...(config.context && { context: config.context }),
-      ...(args.threadId &&
-        config.allowThreadContinuation && { threadId: args.threadId }),
-    };
-
-    const childOpts = {
-      workflowId: childWorkflowId,
-      args: [input] as const,
-      taskQueue: config.taskQueue ?? parentTaskQueue,
-    };
-
-    const { toolResponse, data, usage, threadId: childThreadId } =
-      typeof config.workflow === "string"
-        ? await executeChild(config.workflow, childOpts)
-        : await executeChild(config.workflow, childOpts);
-
-    if (!toolResponse) {
-      return {
-        toolResponse: "Subagent workflow returned no response",
-        data: null,
-        ...(usage && { usage }),
-      };
-    }
-
-    // Validate result if schema provided, otherwise pass through as-is
-    const validated = (
-      config.resultSchema ? config.resultSchema.safeParse(data) : null
-    ) as z.ZodSafeParseResult<InferSubagentResult<T[number]>> | null;
-
-    if (validated && !validated.success) {
-      return {
-        toolResponse: `Subagent workflow returned invalid data: ${validated.error.message}`,
-        data: null,
-        ...(usage && { usage }),
-      };
-    }
-
-    let finalToolResponse: ToolMessageContent = toolResponse;
-    if (config.allowThreadContinuation && childThreadId) {
-      finalToolResponse =
-        typeof toolResponse === "string"
-          ? `${toolResponse}\n\n[Thread ID: ${childThreadId}]`
-          : toolResponse;
-    }
-
-    return {
-      toolResponse: finalToolResponse,
-      data: validated ? validated.data : data,
-      ...(usage && { usage }),
-    };
-  };
-}
+export { createSubagentHandler } from "../../lib/subagent/handler";

package/src/tools/subagent/tool.ts

@@ -1,93 +1,5 @@
-import z from "zod";
-import type { SubagentConfig } from "../../lib/types";
-
-export const SUBAGENT_TOOL_NAME = "Subagent" as const;
-
-/**
- * Builds the tool description with available subagent information
- */
-function buildSubagentDescription(subagents: SubagentConfig[]): string {
-  const subagentList = subagents
-    .map((s) => {
-      const continuation = s.allowThreadContinuation
-        ? "\n*(Supports thread continuation — pass a threadId to resume a previous conversation)*"
-        : "";
-      return `## ${s.agentName}\n${s.description}${continuation}`;
-    })
-    .join("\n\n");
-
-  return `The ${SUBAGENT_TOOL_NAME} tool launches specialized agents (subagents) that autonomously handle complex work. Each agent type has specific capabilities and tools available to it.
-
-# Available subagents:
-${subagentList}
-`;
-}
-
-/**
- * Creates a Subagent 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 subagentTool = createSubagentTool([
- *   {
- *     agentName: "researcher",
- *     description: "Researches topics and gathers information",
- *     workflow: "researcherWorkflow",
- *     resultSchema: z.object({ findings: z.string() }),
- *   },
- * ]);
- */
-export function createSubagentTool<T extends SubagentConfig[]>(
-  subagents: T
-): {
-  readonly name: typeof SUBAGENT_TOOL_NAME;
-  readonly description: string;
-  readonly schema: z.ZodObject<z.ZodRawShape>;
-} {
-  if (subagents.length === 0) {
-    throw new Error("createTaskTool requires at least one subagent");
-  }
-
-  const names = subagents.map((s) => s.agentName);
-  const hasThreadContinuation = subagents.some(
-    (s) => s.allowThreadContinuation
-  );
-
-  const baseFields = {
-    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"),
-  };
-
-  const schema = hasThreadContinuation
-    ? z.object({
-        ...baseFields,
-        threadId: z
-          .string()
-          .nullable()
-          .describe(
-            "Thread ID to continue an existing conversation, or null to start a new one"
-          ),
-      })
-    : z.object(baseFields);
-
-  return {
-    name: SUBAGENT_TOOL_NAME,
-    description: buildSubagentDescription(subagents),
-    schema,
-  } as const;
-}
-
-/**
- * Subagent tool args type (when subagent names are not known at compile time)
- */
-export type SubagentArgs = {
-  subagent: string;
-  description: string;
-  prompt: string;
-  threadId?: string;
-};
+export {
+  createSubagentTool,
+  SUBAGENT_TOOL_NAME,
+  type SubagentArgs,
+} from "../../lib/subagent/tool";

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

@@ -1,7 +1,7 @@
 import type {
   AgentStateManager,
   JsonSerializable,
-} from "../../lib/state-manager";
+} from "../../lib/state";
 import type { ToolHandler } from "../../lib/tool-router";
 import type { WorkflowTask } from "../../lib/types";
 import type { TaskCreateArgs } from "./tool";

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

@@ -1,7 +1,7 @@
 import type {
   AgentStateManager,
   JsonSerializable,
-} from "../../lib/state-manager";
+} from "../../lib/state";
 import type { ToolHandler } from "../../lib/tool-router";
 import type { WorkflowTask } from "../../lib/types";
 import type { TaskGetArgs } from "./tool";

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

@@ -1,7 +1,7 @@
 import type {
   AgentStateManager,
   JsonSerializable,
-} from "../../lib/state-manager";
+} from "../../lib/state";
 import type { ToolHandler } from "../../lib/tool-router";
 import type { WorkflowTask } from "../../lib/types";
 import type { TaskListArgs } from "./tool";

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

@@ -1,7 +1,7 @@
 import type {
   AgentStateManager,
   JsonSerializable,
-} from "../../lib/state-manager";
+} from "../../lib/state";
 import type { ToolHandler } from "../../lib/tool-router";
 import type { WorkflowTask } from "../../lib/types";
 import type { TaskUpdateArgs } from "./tool";