botholomew 0.16.4 → 0.18.0

package/src/tools/file/edit.ts

@@ -1,76 +0,0 @@
-import { z } from "zod";
-import {
-  applyPatches,
-  IsDirectoryError,
-  MtimeConflictError,
-  NotFoundError,
-  readContextFile,
-} from "../../context/store.ts";
-import { LinePatchSchema } from "../../fs/patches.ts";
-import type { ToolDefinition } from "../tool.ts";
-
-const inputSchema = z.object({
-  path: z.string().describe("Project-relative path under context/"),
-  patches: z.array(LinePatchSchema).describe("Patches to apply"),
-});
-
-const outputSchema = z.object({
-  applied: z.number(),
-  content: z.string(),
-  is_error: z.boolean(),
-  error_type: z.string().optional(),
-  message: z.string().optional(),
-  next_action_hint: z.string().optional(),
-});
-
-export const contextEditTool = {
-  name: "context_edit",
-  description:
-    "[[ bash equivalent command: patch ]] Apply line-range patches to a file under context/. Each patch specifies start_line/end_line/content. Edits that traverse a user symlink fail with PathEscapeError — delete the symlink first or copy the content to a real path.",
-  group: "context",
-  inputSchema,
-  outputSchema,
-  execute: async (input, ctx) => {
-    try {
-      const { applied } = await applyPatches(
-        ctx.projectDir,
-        input.path,
-        input.patches,
-        { holderId: ctx.workerId },
-      );
-      const content = await readContextFile(ctx.projectDir, input.path);
-      return { applied, content, is_error: false };
-    } catch (err) {
-      if (err instanceof NotFoundError) {
-        return {
-          applied: 0,
-          content: "",
-          is_error: true,
-          error_type: "not_found",
-          message: `No file at context/${err.path}`,
-        };
-      }
-      if (err instanceof IsDirectoryError) {
-        return {
-          applied: 0,
-          content: "",
-          is_error: true,
-          error_type: "is_directory",
-          message: `context/${err.path} is a directory`,
-        };
-      }
-      if (err instanceof MtimeConflictError) {
-        return {
-          applied: 0,
-          content: "",
-          is_error: true,
-          error_type: "mtime_conflict",
-          message: `context/${input.path} was modified concurrently — another writer (or an external editor) changed it between read and write.`,
-          next_action_hint:
-            "Call context_read to fetch the current content, recompute your patches against the new line numbers, and retry.",
-        };
-      }
-      throw err;
-    }
-  },
-} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/file/exists.ts

@@ -1,33 +0,0 @@
-import { z } from "zod";
-import { fileExists } from "../../context/store.ts";
-import { PathEscapeError } from "../../fs/sandbox.ts";
-import type { ToolDefinition } from "../tool.ts";
-
-const inputSchema = z.object({
-  path: z.string().describe("Path under context/"),
-});
-
-const outputSchema = z.object({
-  exists: z.boolean(),
-  is_error: z.boolean(),
-});
-
-export const contextExistsTool = {
-  name: "context_exists",
-  description:
-    "[[ bash equivalent command: test -e ]] Check whether a path exists under context/.",
-  group: "context",
-  inputSchema,
-  outputSchema,
-  execute: async (input, ctx) => {
-    try {
-      const exists = await fileExists(ctx.projectDir, input.path);
-      return { exists, is_error: false };
-    } catch (err) {
-      if (err instanceof PathEscapeError) {
-        return { exists: false, is_error: false };
-      }
-      throw err;
-    }
-  },
-} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/file/info.ts

@@ -1,66 +0,0 @@
-import { z } from "zod";
-import { getInfo, readContextFile } from "../../context/store.ts";
-import type { ToolDefinition } from "../tool.ts";
-
-const inputSchema = z.object({
-  path: z.string().describe("Path under context/"),
-});
-
-const fileSchema = z.object({
-  path: z.string(),
-  is_directory: z.boolean(),
-  is_textual: z.boolean(),
-  is_symlink: z.boolean(),
-  mime_type: z.string(),
-  size: z.number(),
-  lines: z.number(),
-  mtime: z.string(),
-  content_hash: z.string().nullable(),
-});
-
-const outputSchema = z.object({
-  file: fileSchema.optional(),
-  is_error: z.boolean(),
-  error_type: z.string().optional(),
-  message: z.string().optional(),
-  next_action_hint: z.string().optional(),
-});
-
-export const contextInfoTool = {
-  name: "context_info",
-  description:
-    "[[ bash equivalent command: stat ]] Show metadata for a path under context/: size, MIME type, line count, mtime, content hash. `is_symlink` is true when the path is a user-placed symlink.",
-  group: "context",
-  inputSchema,
-  outputSchema,
-  execute: async (input, ctx) => {
-    const info = await getInfo(ctx.projectDir, input.path);
-    if (!info) {
-      return {
-        is_error: true,
-        error_type: "not_found",
-        message: `No path at context/${input.path}`,
-        next_action_hint: "Call context_tree to browse.",
-      };
-    }
-    let lines = 0;
-    if (info.is_textual && !info.is_directory) {
-      const content = await readContextFile(ctx.projectDir, input.path);
-      lines = content === "" ? 0 : content.split("\n").length;
-    }
-    return {
-      file: {
-        path: info.path,
-        is_directory: info.is_directory,
-        is_textual: info.is_textual,
-        is_symlink: info.is_symlink,
-        mime_type: info.mime_type,
-        size: info.size,
-        lines,
-        mtime: info.mtime.toISOString(),
-        content_hash: info.content_hash,
-      },
-      is_error: false,
-    };
-  },
-} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/file/move.ts

@@ -1,66 +0,0 @@
-import { z } from "zod";
-import {
-  deleteContextPath,
-  fileExists,
-  moveContextPath,
-  NotFoundError,
-  PathConflictError,
-} from "../../context/store.ts";
-import type { ToolDefinition } from "../tool.ts";
-
-const inputSchema = z.object({
-  src: z.string().describe("Source path under context/"),
-  dst: z.string().describe("Destination path under context/"),
-  overwrite: z.boolean().optional().describe("Overwrite if destination exists"),
-});
-
-const outputSchema = z.object({
-  src: z.string(),
-  dst: z.string(),
-  is_error: z.boolean(),
-  error_type: z.string().optional(),
-  message: z.string().optional(),
-});
-
-export const contextMoveTool = {
-  name: "context_move",
-  description:
-    "[[ bash equivalent command: mv ]] Move or rename a file/directory under context/. Source/destination paths that traverse a user symlink fail with PathEscapeError.",
-  group: "context",
-  inputSchema,
-  outputSchema,
-  execute: async (input, ctx) => {
-    try {
-      if (input.overwrite && (await fileExists(ctx.projectDir, input.dst))) {
-        await deleteContextPath(ctx.projectDir, input.dst, {
-          recursive: true,
-          holderId: ctx.workerId,
-        });
-      }
-      await moveContextPath(ctx.projectDir, input.src, input.dst, {
-        holderId: ctx.workerId,
-      });
-      return { src: input.src, dst: input.dst, is_error: false };
-    } catch (err) {
-      if (err instanceof NotFoundError) {
-        return {
-          src: input.src,
-          dst: input.dst,
-          is_error: true,
-          error_type: "not_found",
-          message: `No file at context/${err.path}`,
-        };
-      }
-      if (err instanceof PathConflictError) {
-        return {
-          src: input.src,
-          dst: input.dst,
-          is_error: true,
-          error_type: "path_conflict",
-          message: `Destination already exists at context/${err.path}; pass overwrite=true to replace.`,
-        };
-      }
-      throw err;
-    }
-  },
-} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/file/read.ts

@@ -1,67 +0,0 @@
-import { z } from "zod";
-import {
-  IsDirectoryError,
-  NotFoundError,
-  readContextFile,
-} from "../../context/store.ts";
-import type { ToolDefinition } from "../tool.ts";
-
-const inputSchema = z.object({
-  path: z
-    .string()
-    .describe(
-      "Project-relative path under context/ (e.g. 'notes/foo.md'). Forward-slashes; never absolute.",
-    ),
-  offset: z
-    .number()
-    .optional()
-    .describe("Line number to start reading from (1-based)"),
-  limit: z.number().optional().describe("Maximum number of lines to return"),
-});
-
-const outputSchema = z.object({
-  content: z.string().optional(),
-  is_error: z.boolean(),
-  error_type: z.string().optional(),
-  message: z.string().optional(),
-  next_action_hint: z.string().optional(),
-});
-
-export const contextReadTool = {
-  name: "context_read",
-  description: "[[ bash equivalent command: cat ]] Read a file under context/.",
-  group: "context",
-  inputSchema,
-  outputSchema,
-  execute: async (input, ctx) => {
-    try {
-      let content = await readContextFile(ctx.projectDir, input.path);
-      if (input.offset || input.limit) {
-        const lines = content.split("\n");
-        const start = (input.offset ?? 1) - 1;
-        const end = input.limit ? start + input.limit : lines.length;
-        content = lines.slice(start, end).join("\n");
-      }
-      return { content, is_error: false };
-    } catch (err) {
-      if (err instanceof NotFoundError) {
-        return {
-          is_error: true,
-          error_type: "not_found",
-          message: `No file at context/${err.path}`,
-          next_action_hint:
-            "Call context_tree to browse, or context_exists to check first.",
-        };
-      }
-      if (err instanceof IsDirectoryError) {
-        return {
-          is_error: true,
-          error_type: "is_directory",
-          message: `context/${err.path} is a directory`,
-          next_action_hint: "Use context_tree to list its contents.",
-        };
-      }
-      throw err;
-    }
-  },
-} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/file/write.ts

@@ -1,58 +0,0 @@
-import { z } from "zod";
-import { PathConflictError, writeContextFile } from "../../context/store.ts";
-import type { ToolDefinition } from "../tool.ts";
-
-const inputSchema = z.object({
-  path: z
-    .string()
-    .describe(
-      "Project-relative path under context/ (e.g. 'notes/foo.md'). Created if its parent directory does not exist.",
-    ),
-  content: z.string().describe("Text content to write"),
-  on_conflict: z
-    .enum(["error", "overwrite"])
-    .optional()
-    .describe(
-      "What to do if the file already exists. Defaults to 'error'. Pass 'overwrite' to replace.",
-    ),
-});
-
-const outputSchema = z.object({
-  path: z.string(),
-  is_error: z.boolean(),
-  error_type: z.string().optional(),
-  message: z.string().optional(),
-  next_action_hint: z.string().optional(),
-});
-
-export const contextWriteTool = {
-  name: "context_write",
-  description:
-    "[[ bash equivalent command: tee ]] Write text content to a file under context/. Fails if the path already exists unless on_conflict='overwrite'. Writes that traverse a user symlink fail with PathEscapeError — delete the symlink first or write to a real path.",
-  group: "context",
-  inputSchema,
-  outputSchema,
-  execute: async (input, ctx) => {
-    try {
-      const entry = await writeContextFile(
-        ctx.projectDir,
-        input.path,
-        input.content,
-        { onConflict: input.on_conflict ?? "error", holderId: ctx.workerId },
-      );
-      return { path: entry.path, is_error: false };
-    } catch (err) {
-      if (err instanceof PathConflictError) {
-        return {
-          path: err.path,
-          is_error: true,
-          error_type: "path_conflict",
-          message: `A file already exists at context/${err.path}.`,
-          next_action_hint:
-            "Call context_read to inspect, or retry with on_conflict='overwrite'.",
-        };
-      }
-      throw err;
-    }
-  },
-} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/search/fuse.ts

@@ -1,96 +0,0 @@
-import type { RegexpHit } from "./regexp.ts";
-import type { SemanticHit } from "./semantic.ts";
-
-export interface FusedMatch {
-  path: string;
-  line: number | null;
-  content: string;
-  context_lines: string[];
-  match_type: "regexp" | "semantic" | "both";
-  semantic_score: number | null;
-  score: number;
-}
-
-const SNIPPET_MAX = 300;
-
-/**
- * Reciprocal rank fusion of regexp line hits and semantic file hits.
- *
- * Each regexp hit becomes its own row. If the same file also has a semantic
- * hit, the regexp row picks up that semantic side's RRF contribution and is
- * tagged `match_type: "both"` — exact-line + semantic agreement is the
- * strongest signal.
- *
- * Semantic hits emit their own rows only for paths with no regexp hit.
- */
-export function fuseRRF(
-  regexpHits: RegexpHit[],
-  semanticHits: SemanticHit[],
-  options: { k?: number; limit: number },
-): FusedMatch[] {
-  const k = options.k ?? 60;
-
-  const bestSemByPath = new Map<
-    string,
-    { rank: number; score: number; hit: SemanticHit }
-  >();
-  for (let i = 0; i < semanticHits.length; i++) {
-    const hit = semanticHits[i];
-    if (!hit) continue;
-    const existing = bestSemByPath.get(hit.path);
-    if (!existing || i < existing.rank) {
-      bestSemByPath.set(hit.path, { rank: i, score: hit.score, hit });
-    }
-  }
-
-  const regexpPaths = new Set<string>();
-  for (const hit of regexpHits) regexpPaths.add(hit.path);
-
-  const fused: FusedMatch[] = [];
-
-  for (let i = 0; i < regexpHits.length; i++) {
-    const rx = regexpHits[i];
-    if (!rx) continue;
-    const sem = bestSemByPath.get(rx.path);
-    let score = 1 / (k + i + 1);
-    let matchType: FusedMatch["match_type"] = "regexp";
-    let semanticScore: number | null = null;
-    if (sem) {
-      score += 1 / (k + sem.rank + 1);
-      matchType = "both";
-      semanticScore = round(sem.score);
-    }
-    fused.push({
-      path: rx.path,
-      line: rx.line,
-      content: rx.content,
-      context_lines: rx.context_lines,
-      match_type: matchType,
-      semantic_score: semanticScore,
-      score: round(score),
-    });
-  }
-
-  for (let i = 0; i < semanticHits.length; i++) {
-    const sem = semanticHits[i];
-    if (!sem) continue;
-    if (regexpPaths.has(sem.path)) continue;
-    const score = 1 / (k + i + 1);
-    fused.push({
-      path: sem.path,
-      line: null,
-      content: sem.chunk_content.slice(0, SNIPPET_MAX),
-      context_lines: [],
-      match_type: "semantic",
-      semantic_score: round(sem.score),
-      score: round(score),
-    });
-  }
-
-  fused.sort((a, b) => b.score - a.score);
-  return fused.slice(0, options.limit);
-}
-
-function round(n: number): number {
-  return Math.round(n * 10000) / 10000;
-}

package/src/tools/search/index.ts

@@ -1,127 +0,0 @@
-import { z } from "zod";
-import type { ToolDefinition } from "../tool.ts";
-import { fuseRRF } from "./fuse.ts";
-import { runRegexp } from "./regexp.ts";
-import { runSemantic } from "./semantic.ts";
-
-const MatchSchema = z.object({
-  path: z.string(),
-  line: z.number().nullable(),
-  content: z.string(),
-  context_lines: z.array(z.string()),
-  match_type: z.enum(["regexp", "semantic", "both"]),
-  semantic_score: z.number().nullable(),
-  score: z.number(),
-});
-
-const inputSchema = z.object({
-  query: z
-    .string()
-    .optional()
-    .describe(
-      "Natural-language query for semantic search. Provide alongside `pattern` for the strongest signal — files matched by both methods float to the top via reciprocal rank fusion.",
-    ),
-  pattern: z
-    .string()
-    .optional()
-    .describe(
-      "Regex pattern for exact text search across file contents under context/.",
-    ),
-  scope: z
-    .string()
-    .optional()
-    .describe(
-      "Restrict search to a sub-directory under context/ (e.g. 'notes' to only search context/notes/...).",
-    ),
-  glob: z
-    .string()
-    .optional()
-    .describe("Filter results to files whose basename matches this glob."),
-  ignore_case: z
-    .boolean()
-    .optional()
-    .describe("Case-insensitive regex (only affects `pattern`)."),
-  context: z
-    .number()
-    .optional()
-    .describe(
-      "Lines of surrounding context to include for each regex hit (only affects `pattern`).",
-    ),
-  max_results: z
-    .number()
-    .optional()
-    .describe("Maximum number of fused results to return (default 20)."),
-});
-
-const outputSchema = z.object({
-  matches: z.array(MatchSchema),
-  is_error: z.boolean(),
-  error_type: z.string().optional(),
-  message: z.string().optional(),
-  next_action_hint: z.string().optional(),
-});
-
-export const searchTool = {
-  name: "search",
-  description:
-    "[[ bash equivalent command: grep -r ]] Hybrid search over files under context/. At least one of `query` (natural language → semantic) or `pattern` (regex over file contents) is required. Pass both for the strongest signal: results matched by both methods float to the top via reciprocal rank fusion. Scoping (`scope`, `glob`) applies to both sides. Note: while a persistent index sidecar is being rebuilt, semantic search re-embeds files on every call — keep result sets small.",
-  group: "search",
-  inputSchema,
-  outputSchema,
-  execute: async (input, ctx) => {
-    if (!input.query && !input.pattern) {
-      return {
-        matches: [],
-        is_error: true,
-        error_type: "invalid_arguments",
-        message:
-          "Provide at least one of `query` (natural language) or `pattern` (regex). Pass both to fuse semantic and exact-match signals.",
-      };
-    }
-
-    // Validate the regex up front so a malformed pattern returns a
-    // structured error instead of bubbling SyntaxError. Match the shape
-    // of search_threads' invalid_regex response so the agent can recover
-    // identically across both tools.
-    if (input.pattern) {
-      try {
-        new RegExp(input.pattern, input.ignore_case ? "i" : "");
-      } catch (err) {
-        return {
-          matches: [],
-          is_error: true,
-          error_type: "invalid_regex",
-          message: `Could not compile pattern: ${err instanceof Error ? err.message : String(err)}`,
-          next_action_hint:
-            "Double-check the regex; remember `.` is a metacharacter — escape it as `\\.` for a literal dot.",
-        };
-      }
-    }
-
-    const limit = input.max_results ?? 20;
-
-    const regexpHits = input.pattern
-      ? await runRegexp(ctx.projectDir, {
-          pattern: input.pattern,
-          scope: input.scope,
-          glob: input.glob,
-          ignore_case: input.ignore_case,
-          context: input.context,
-          max_results: 100,
-        })
-      : [];
-
-    const semanticHits = input.query
-      ? await runSemantic(ctx.projectDir, ctx.config, ctx.dbPath, {
-          query: input.query,
-          scope: input.scope,
-          glob: input.glob,
-          limit: 100,
-        })
-      : [];
-
-    const matches = fuseRRF(regexpHits, semanticHits, { limit });
-
-    return { matches, is_error: false };
-  },
-} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/search/regexp.ts

@@ -1,82 +0,0 @@
-import { listContextDir, readContextFile } from "../../context/store.ts";
-
-export interface RegexpHit {
-  path: string;
-  line: number;
-  content: string;
-  context_lines: string[];
-}
-
-export interface RegexpOptions {
-  pattern: string;
-  /** Optional path under context/ to scope the walk (default: whole tree). */
-  scope?: string;
-  glob?: string;
-  ignore_case?: boolean;
-  context?: number;
-  max_results?: number;
-}
-
-/**
- * Walk every textual file under `context/` (or `context/<scope>/`) and run
- * `pattern` against each line. Cheap because tools opt into reading content
- * only for files whose names match an optional glob.
- */
-export async function runRegexp(
-  projectDir: string,
-  options: RegexpOptions,
-): Promise<RegexpHit[]> {
-  const flags = options.ignore_case ? "gi" : "g";
-  const regex = new RegExp(options.pattern, flags);
-  const globRegex = options.glob ? globToRegex(options.glob) : null;
-  const contextLines = options.context ?? 0;
-  const maxResults = options.max_results ?? 100;
-
-  const entries = await listContextDir(projectDir, options.scope ?? "", {
-    recursive: true,
-  });
-
-  const hits: RegexpHit[] = [];
-  for (const entry of entries) {
-    if (entry.is_directory) continue;
-    if (!entry.is_textual) continue;
-    if (globRegex) {
-      const filename = entry.path.split("/").pop() ?? "";
-      if (!globRegex.test(filename)) continue;
-    }
-
-    let content: string;
-    try {
-      content = await readContextFile(projectDir, entry.path);
-    } catch {
-      continue;
-    }
-    const lines = content.split("\n");
-    for (let i = 0; i < lines.length; i++) {
-      regex.lastIndex = 0;
-      const line = lines[i];
-      if (line === undefined) continue;
-      if (regex.test(line)) {
-        const start = Math.max(0, i - contextLines);
-        const end = Math.min(lines.length, i + contextLines + 1);
-        hits.push({
-          path: entry.path,
-          line: i + 1,
-          content: line,
-          context_lines: lines.slice(start, end),
-        });
-        if (hits.length >= maxResults) return hits;
-      }
-    }
-  }
-
-  return hits;
-}
-
-export function globToRegex(glob: string): RegExp {
-  const escaped = glob
-    .replace(/[.+^${}()|[\]\\]/g, "\\$&")
-    .replace(/\*/g, ".*")
-    .replace(/\?/g, ".");
-  return new RegExp(`^${escaped}$`, "i");
-}