botholomew 0.9.5 → 0.9.8

package/src/tools/registry.ts

@@ -32,9 +32,16 @@ import { listSchedulesTool } from "./schedule/list.ts";
 // Search tools
 import { searchGrepTool } from "./search/grep.ts";
 import { searchSemanticTool } from "./search/semantic.ts";
+// Skill tools
+import { skillEditTool } from "./skill/edit.ts";
+import { skillListTool } from "./skill/list.ts";
+import { skillReadTool } from "./skill/read.ts";
+import { skillSearchTool } from "./skill/search.ts";
+import { skillWriteTool } from "./skill/write.ts";
 // Task tools
 import { completeTaskTool } from "./task/complete.ts";
 import { createTaskTool } from "./task/create.ts";
+import { deleteTaskTool } from "./task/delete.ts";
 import { failTaskTool } from "./task/fail.ts";
 import { listTasksTool } from "./task/list.ts";
 import { updateTaskTool } from "./task/update.ts";
@@ -54,6 +61,7 @@ export function registerAllTools(): void {
   registerTool(waitTaskTool);
   registerTool(createTaskTool);
   registerTool(updateTaskTool);
+  registerTool(deleteTaskTool);
   registerTool(listTasksTool);
   registerTool(viewTaskTool);
 
@@ -88,6 +96,13 @@ export function registerAllTools(): void {
   registerTool(searchGrepTool);
   registerTool(searchSemanticTool);
 
+  // Skill
+  registerTool(skillListTool);
+  registerTool(skillReadTool);
+  registerTool(skillWriteTool);
+  registerTool(skillEditTool);
+  registerTool(skillSearchTool);
+
   // Thread
   registerTool(listThreadsTool);
   registerTool(viewThreadTool);

package/src/tools/skill/edit.ts

@@ -0,0 +1,114 @@
+import { join } from "node:path";
+import { z } from "zod";
+import { getSkillsDir } from "../../constants.ts";
+import { parseSkillFile } from "../../skills/parser.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const PatchSchema = z.object({
+  start_line: z.number().describe("1-based inclusive start line"),
+  end_line: z
+    .number()
+    .describe("1-based inclusive end line (0 to insert without replacing)"),
+  content: z
+    .string()
+    .describe("Replacement text (empty string to delete lines)"),
+});
+
+const inputSchema = z.object({
+  name: z.string().describe("Skill name (case-insensitive)"),
+  patches: z.array(PatchSchema).describe("Patches to apply"),
+});
+
+const outputSchema = z.object({
+  name: z.string(),
+  path: z.string().nullable(),
+  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(),
+});
+
+function applyPatches(
+  raw: string,
+  patches: Array<{ start_line: number; end_line: number; content: string }>,
+): string {
+  const lines = raw.split("\n");
+  const sorted = [...patches].sort((a, b) => b.start_line - a.start_line);
+
+  for (const patch of sorted) {
+    if (patch.end_line === 0) {
+      const insertLines = patch.content === "" ? [] : patch.content.split("\n");
+      lines.splice(patch.start_line - 1, 0, ...insertLines);
+    } else {
+      const deleteCount = patch.end_line - patch.start_line + 1;
+      const insertLines = patch.content === "" ? [] : patch.content.split("\n");
+      lines.splice(patch.start_line - 1, deleteCount, ...insertLines);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+export const skillEditTool = {
+  name: "skill_edit",
+  description:
+    "[[ bash equivalent command: patch ]] Apply git-style line-range patches to a skill file (user-defined slash command). Operates on the whole file (frontmatter + body). Patches whose result would not parse as a valid skill are rejected without writing. Use skill_read first to inspect current line numbers.",
+  group: "skill",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    const normalized = input.name.toLowerCase();
+    const filePath = join(getSkillsDir(ctx.projectDir), `${normalized}.md`);
+
+    const file = Bun.file(filePath);
+    if (!(await file.exists())) {
+      return {
+        name: normalized,
+        path: null,
+        applied: 0,
+        content: "",
+        is_error: true,
+        error_type: "not_found",
+        message: `Skill not found: ${input.name}`,
+        next_action_hint:
+          "Use skill_list to see available skills, or skill_write to create one.",
+      };
+    }
+
+    const original = await file.text();
+    const updated = applyPatches(original, input.patches);
+
+    try {
+      const parsed = parseSkillFile(updated, filePath);
+      if (parsed.name !== normalized) {
+        throw new Error(
+          `frontmatter name '${parsed.name}' no longer matches filename '${normalized}'`,
+        );
+      }
+    } catch (err) {
+      return {
+        name: normalized,
+        path: filePath,
+        applied: 0,
+        content: original,
+        is_error: true,
+        error_type: "invalid_skill",
+        message: `Patched content failed validation: ${err instanceof Error ? err.message : String(err)}`,
+        next_action_hint:
+          "Check that frontmatter YAML stays valid and the file still has a name/description.",
+      };
+    }
+
+    await Bun.write(filePath, updated);
+
+    return {
+      name: normalized,
+      path: filePath,
+      applied: input.patches.length,
+      content: updated,
+      is_error: false,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/skill/list.ts

@@ -0,0 +1,63 @@
+import { basename } from "node:path";
+import { z } from "zod";
+import { loadSkills } from "../../skills/loader.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  limit: z
+    .number()
+    .optional()
+    .default(100)
+    .describe("Max number of skills to return (default 100)"),
+  offset: z
+    .number()
+    .optional()
+    .default(0)
+    .describe("Skip the first N skills (default 0)"),
+});
+
+const outputSchema = z.object({
+  skills: z.array(
+    z.object({
+      name: z.string(),
+      description: z.string(),
+      arguments: z.array(z.string()),
+      filename: z.string(),
+      path: z.string(),
+    }),
+  ),
+  total: z.number(),
+  is_error: z.boolean(),
+});
+
+export const skillListTool = {
+  name: "skill_list",
+  description:
+    "[[ bash equivalent command: ls ]] List skills (user-defined slash commands) loaded from .botholomew/skills/. Returns name, description, argument names, and file path for each.",
+  group: "skill",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    const skills = await loadSkills(ctx.projectDir);
+    const sorted = [...skills.values()].sort((a, b) =>
+      a.name.localeCompare(b.name),
+    );
+
+    const total = sorted.length;
+    const offset = input.offset ?? 0;
+    const limit = input.limit ?? 100;
+    const page = sorted.slice(offset, offset + limit);
+
+    return {
+      skills: page.map((s) => ({
+        name: s.name,
+        description: s.description,
+        arguments: s.arguments.map((a) => a.name),
+        filename: basename(s.filePath),
+        path: s.filePath,
+      })),
+      total,
+      is_error: false,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/skill/read.ts

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { loadSkills } from "../../skills/loader.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  name: z.string().describe("Skill name (case-insensitive)"),
+});
+
+const ArgSchema = z.object({
+  name: z.string(),
+  description: z.string(),
+  required: z.boolean(),
+  default: z.string().optional(),
+});
+
+const outputSchema = z.object({
+  name: z.string(),
+  path: z.string().nullable(),
+  raw: z.string().nullable(),
+  description: z.string(),
+  arguments: z.array(ArgSchema),
+  body: z.string(),
+  is_error: z.boolean(),
+  error_type: z.string().optional(),
+  message: z.string().optional(),
+  next_action_hint: z.string().optional(),
+});
+
+export const skillReadTool = {
+  name: "skill_read",
+  description:
+    "[[ bash equivalent command: cat ]] Read a skill file (user-defined slash command) by name. Returns the raw file contents plus parsed fields. Returns a not_found error with the list of available names when the skill doesn't exist.",
+  group: "skill",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    const skills = await loadSkills(ctx.projectDir);
+    const skill = skills.get(input.name.toLowerCase());
+
+    if (!skill) {
+      const available = [...skills.keys()].sort();
+      const hint =
+        available.length > 0
+          ? `Available: ${available.join(", ")}. Use skill_list to browse.`
+          : "No skills exist yet. Use skill_write to create one.";
+      return {
+        name: input.name,
+        path: null,
+        raw: null,
+        description: "",
+        arguments: [],
+        body: "",
+        is_error: true,
+        error_type: "not_found",
+        message: `Skill not found: ${input.name}`,
+        next_action_hint: hint,
+      };
+    }
+
+    const raw = await Bun.file(skill.filePath).text();
+
+    return {
+      name: skill.name,
+      path: skill.filePath,
+      raw,
+      description: skill.description,
+      arguments: skill.arguments,
+      body: skill.body,
+      is_error: false,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/skill/search.ts

@@ -0,0 +1,165 @@
+import { z } from "zod";
+import { loadSkills } from "../../skills/loader.ts";
+import type { SkillDefinition } from "../../skills/parser.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  query: z
+    .string()
+    .describe(
+      "Search query (matched against name, description, body, and arg metadata)",
+    ),
+  top_k: z
+    .number()
+    .optional()
+    .default(10)
+    .describe("Maximum number of results to return (default 10)"),
+});
+
+const outputSchema = z.object({
+  results: z.array(
+    z.object({
+      name: z.string(),
+      description: z.string(),
+      score: z.number(),
+      match_fields: z.array(z.string()),
+      snippet: z.string(),
+    }),
+  ),
+  is_error: z.boolean(),
+  hint: z.string().optional(),
+});
+
+const SNIPPET_RADIUS = 60;
+
+function countOccurrences(haystack: string, needle: string): number {
+  if (needle === "") return 0;
+  let count = 0;
+  let from = 0;
+  while (true) {
+    const idx = haystack.indexOf(needle, from);
+    if (idx === -1) break;
+    count++;
+    from = idx + needle.length;
+  }
+  return count;
+}
+
+function buildSnippet(body: string, term: string): string {
+  const lower = body.toLowerCase();
+  const idx = lower.indexOf(term);
+  if (idx === -1) return body.slice(0, SNIPPET_RADIUS * 2);
+
+  const start = Math.max(0, idx - SNIPPET_RADIUS);
+  const end = Math.min(body.length, idx + term.length + SNIPPET_RADIUS);
+  const prefix = start > 0 ? "…" : "";
+  const suffix = end < body.length ? "…" : "";
+  return prefix + body.slice(start, end) + suffix;
+}
+
+interface ScoreEntry {
+  skill: SkillDefinition;
+  score: number;
+  matchFields: Set<string>;
+  firstBodyTerm: string | null;
+}
+
+function scoreSkill(skill: SkillDefinition, terms: string[]): ScoreEntry {
+  const name = skill.name.toLowerCase();
+  const desc = skill.description.toLowerCase();
+  const body = skill.body.toLowerCase();
+  const matchFields = new Set<string>();
+  let score = 0;
+  let firstBodyTerm: string | null = null;
+
+  for (const term of terms) {
+    if (term === "") continue;
+    if (name.includes(term)) {
+      score += 10;
+      matchFields.add("name");
+    }
+    if (desc.includes(term)) {
+      score += 5;
+      matchFields.add("description");
+    }
+    for (const arg of skill.arguments) {
+      if (arg.name.toLowerCase().includes(term)) {
+        score += 3;
+        matchFields.add("argument_name");
+      }
+      if (arg.description.toLowerCase().includes(term)) {
+        score += 2;
+        matchFields.add("argument_description");
+      }
+    }
+    const bodyHits = Math.min(countOccurrences(body, term), 5);
+    if (bodyHits > 0) {
+      score += bodyHits;
+      matchFields.add("body");
+      if (firstBodyTerm === null) firstBodyTerm = term;
+    }
+  }
+
+  return { skill, score, matchFields, firstBodyTerm };
+}
+
+export const skillSearchTool = {
+  name: "skill_search",
+  description:
+    "Keyword search over skills (user-defined slash commands). Matches against name, description, body, and argument metadata. Returns top-K ranked matches. Use skill_read after finding a match.",
+  group: "skill",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    const skills = await loadSkills(ctx.projectDir);
+    const terms = input.query
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((t) => t.length > 0);
+
+    if (skills.size === 0) {
+      return {
+        results: [],
+        is_error: false,
+        hint: "No skills exist yet. Use skill_write to create one.",
+      };
+    }
+
+    if (terms.length === 0) {
+      return {
+        results: [],
+        is_error: false,
+        hint: "Empty query. Provide one or more keywords, or use skill_list to browse.",
+      };
+    }
+
+    const scored = [...skills.values()].map((s) => scoreSkill(s, terms));
+    const matched = scored
+      .filter((e) => e.score > 0)
+      .sort((a, b) => b.score - a.score)
+      .slice(0, input.top_k ?? 10);
+
+    if (matched.length === 0) {
+      return {
+        results: [],
+        is_error: false,
+        hint: "No matches. Try broader terms, or use skill_list to browse.",
+      };
+    }
+
+    const fallbackTerm = terms[0] ?? "";
+    return {
+      results: matched.map((e) => {
+        const snippetTerm = e.firstBodyTerm ?? fallbackTerm;
+        return {
+          name: e.skill.name,
+          description: e.skill.description,
+          score: e.score,
+          match_fields: [...e.matchFields].sort(),
+          snippet: buildSnippet(e.skill.body, snippetTerm),
+        };
+      }),
+      is_error: false,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/skill/write.ts

@@ -0,0 +1,180 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { getSkillsDir } from "../../constants.ts";
+import { parseSkillFile } from "../../skills/parser.ts";
+import {
+  buildSkillFileContent,
+  validateSkillName,
+} from "../../skills/writer.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const ArgInputSchema = z.object({
+  name: z
+    .string()
+    .min(1)
+    .describe("Argument name (referenced as $1, $2, … in the body)"),
+  description: z.string().optional().describe("Argument description"),
+  required: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe("Whether the argument is required"),
+  default: z
+    .string()
+    .optional()
+    .describe("Default value when the argument is omitted"),
+});
+
+const inputSchema = z.object({
+  name: z
+    .string()
+    .describe(
+      "Skill name (slash-command identifier). Will be normalized to lowercase + [a-z0-9-]. Reserved: help, skills, clear, exit.",
+    ),
+  description: z
+    .string()
+    .describe("Short description shown in /skills and /help"),
+  body: z
+    .string()
+    .describe(
+      "Prompt-template body (markdown). Use $ARGUMENTS or $1..$9 for argument substitution.",
+    ),
+  arguments: z
+    .array(ArgInputSchema)
+    .optional()
+    .describe("Argument definitions (positional)"),
+  on_conflict: z
+    .enum(["error", "overwrite"])
+    .optional()
+    .default("error")
+    .describe(
+      "What to do if a skill with this name already exists. Defaults to 'error'.",
+    ),
+});
+
+const outputSchema = z.object({
+  name: z.string().nullable(),
+  path: z.string().nullable(),
+  ref: z.string().nullable(),
+  created: z.boolean(),
+  is_error: z.boolean(),
+  error_type: z.string().optional(),
+  message: z.string().optional(),
+  next_action_hint: z.string().optional(),
+});
+
+export const skillWriteTool = {
+  name: "skill_write",
+  description:
+    "[[ bash equivalent command: tee ]] Create or overwrite a skill file (user-defined slash command) at .botholomew/skills/<name>.md. Fails with path_conflict when the file exists unless on_conflict='overwrite'. Reserved names (help, skills, clear, exit) are rejected. The generated file is parsed to validate before being written.",
+  group: "skill",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    const nameCheck = validateSkillName(input.name);
+    if (!nameCheck.ok) {
+      const errorType =
+        nameCheck.reason === "reserved" ? "reserved_name" : "invalid_name";
+      const message =
+        nameCheck.reason === "reserved"
+          ? `'${input.name}' is reserved by a built-in slash command (help, skills, clear, exit).`
+          : nameCheck.reason === "too_long"
+            ? `Skill name too long (max 64 chars after normalization).`
+            : `'${input.name}' is not a valid skill name. After normalization (lowercase, [a-z0-9-], trimmed hyphens) it is empty.`;
+      return {
+        name: null,
+        path: null,
+        ref: null,
+        created: false,
+        is_error: true,
+        error_type: errorType,
+        message,
+        next_action_hint:
+          "Pick a different name made of lowercase letters, digits, and hyphens.",
+      };
+    }
+
+    const normalized = nameCheck.normalized;
+    const body = input.body.trim();
+    if (body === "") {
+      return {
+        name: normalized,
+        path: null,
+        ref: null,
+        created: false,
+        is_error: true,
+        error_type: "empty_body",
+        message: "Skill body is empty.",
+        next_action_hint:
+          "Provide a non-empty prompt template using $ARGUMENTS or $1..$9.",
+      };
+    }
+
+    const args = (input.arguments ?? []).map((a) => ({
+      name: a.name,
+      description: a.description ?? "",
+      required: a.required ?? false,
+      default: a.default,
+    }));
+
+    const skillsDir = getSkillsDir(ctx.projectDir);
+    const filePath = join(skillsDir, `${normalized}.md`);
+
+    const raw = buildSkillFileContent({
+      name: normalized,
+      description: input.description,
+      arguments: args,
+      body,
+    });
+
+    try {
+      const parsed = parseSkillFile(raw, filePath);
+      if (parsed.name !== normalized) {
+        throw new Error(
+          `frontmatter name '${parsed.name}' does not match expected '${normalized}'`,
+        );
+      }
+    } catch (err) {
+      return {
+        name: normalized,
+        path: null,
+        ref: null,
+        created: false,
+        is_error: true,
+        error_type: "invalid_skill",
+        message: `Generated skill content failed validation: ${err instanceof Error ? err.message : String(err)}`,
+        next_action_hint:
+          "Check description and body for unusual characters that break YAML.",
+      };
+    }
+
+    const onConflict = input.on_conflict ?? "error";
+    const existed = await Bun.file(filePath).exists();
+
+    if (existed && onConflict === "error") {
+      return {
+        name: normalized,
+        path: filePath,
+        ref: `skill:${normalized}`,
+        created: false,
+        is_error: true,
+        error_type: "path_conflict",
+        message: `Skill '${normalized}' already exists at ${filePath}.`,
+        next_action_hint:
+          "Retry with on_conflict='overwrite' to replace, or use skill_edit for a partial change.",
+      };
+    }
+
+    await mkdir(skillsDir, { recursive: true });
+    await Bun.write(filePath, raw);
+
+    return {
+      name: normalized,
+      path: filePath,
+      ref: `skill:${normalized}`,
+      created: !existed,
+      is_error: false,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/task/delete.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { deleteTask, getTask } from "../../db/tasks.ts";
+import { logger } from "../../utils/logger.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  id: z.string().describe("ID of the task to delete"),
+});
+
+const outputSchema = z.object({
+  deleted_id: z.string().nullable(),
+  message: z.string(),
+  is_error: z.boolean(),
+});
+
+export const deleteTaskTool = {
+  name: "delete_task",
+  description:
+    "[[ bash equivalent command: rm ]] Delete a task permanently. Refuses in_progress tasks; wait for the worker to finish or run `botholomew task reset <id>` first.",
+  group: "task",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    const existing = await getTask(ctx.conn, input.id);
+    if (!existing) {
+      return {
+        deleted_id: null,
+        message: `Task ${input.id} not found`,
+        is_error: true,
+      };
+    }
+    if (existing.status === "in_progress") {
+      return {
+        deleted_id: null,
+        message: `Cannot delete task ${input.id}: it is currently in_progress (claimed by ${existing.claimed_by ?? "unknown"}). Wait for the worker to finish, or reset it first via \`botholomew task reset ${input.id}\`.`,
+        is_error: true,
+      };
+    }
+    const ok = await deleteTask(ctx.conn, input.id);
+    if (!ok) {
+      return {
+        deleted_id: null,
+        message: `Failed to delete task ${input.id}`,
+        is_error: true,
+      };
+    }
+    logger.info(`Deleted task: ${existing.name} (${existing.id})`);
+    return {
+      deleted_id: existing.id,
+      message: `Deleted task "${existing.name}" (${existing.id})`,
+      is_error: false,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;