botholomew 0.12.5 → 0.14.0

package/src/tools/skill/write.ts

@@ -67,7 +67,7 @@ const outputSchema = z.object({
 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.",
+    "[[ bash equivalent command: tee ]] Create or overwrite a skill file (user-defined slash command) at 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,

package/src/tools/task/create.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
-import { createTask, TASK_PRIORITIES } from "../../db/tasks.ts";
+import { TASK_PRIORITIES } from "../../tasks/schema.ts";
+import { CircularDependencyError, createTask } from "../../tasks/store.ts";
 import { logger } from "../../utils/logger.ts";
 import type { ToolDefinition } from "../tool.ts";
 
@@ -21,13 +22,21 @@ const inputSchema = z.object({
     .array(z.string())
     .optional()
     .describe("IDs of tasks that must complete first"),
+  context_paths: z
+    .array(z.string())
+    .optional()
+    .describe(
+      "Project-relative paths under context/ that the task should reference",
+    ),
 });
 
 const outputSchema = z.object({
-  id: z.string(),
-  name: z.string(),
+  id: z.string().nullable(),
+  name: z.string().nullable(),
   message: z.string(),
   is_error: z.boolean(),
+  error_type: z.string().optional(),
+  next_action_hint: z.string().optional(),
 });
 
 export const createTaskTool = {
@@ -38,18 +47,34 @@ export const createTaskTool = {
   inputSchema,
   outputSchema,
   execute: async (input, ctx) => {
-    const newTask = await createTask(ctx.conn, {
-      name: input.name,
-      description: input.description,
-      priority: input.priority,
-      blocked_by: input.blocked_by,
-    });
-    logger.info(`Created subtask: ${newTask.name} (${newTask.id})`);
-    return {
-      id: newTask.id,
-      name: newTask.name,
-      message: `Created task "${newTask.name}" with ID ${newTask.id}`,
-      is_error: false,
-    };
+    try {
+      const newTask = await createTask(ctx.projectDir, {
+        name: input.name,
+        description: input.description,
+        priority: input.priority,
+        blocked_by: input.blocked_by,
+        context_paths: input.context_paths,
+      });
+      logger.info(`Created subtask: ${newTask.name} (${newTask.id})`);
+      return {
+        id: newTask.id,
+        name: newTask.name,
+        message: `Created task "${newTask.name}" with ID ${newTask.id}`,
+        is_error: false,
+      };
+    } catch (err) {
+      if (err instanceof CircularDependencyError) {
+        return {
+          id: null,
+          name: null,
+          message: err.message,
+          is_error: true,
+          error_type: "circular_dependency",
+          next_action_hint:
+            "Pick blockers that don't transitively depend on this task. `list_tasks` + `view_task` show the existing dependency graph.",
+        };
+      }
+      throw err;
+    }
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/task/delete.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { deleteTask, getTask } from "../../db/tasks.ts";
+import { deleteTask, getTask } from "../../tasks/store.ts";
 import { logger } from "../../utils/logger.ts";
 import type { ToolDefinition } from "../tool.ts";
 
@@ -21,7 +21,7 @@ export const deleteTaskTool = {
   inputSchema,
   outputSchema,
   execute: async (input, ctx) => {
-    const existing = await getTask(ctx.conn, input.id);
+    const existing = await getTask(ctx.projectDir, input.id);
     if (!existing) {
       return {
         deleted_id: null,
@@ -36,7 +36,7 @@ export const deleteTaskTool = {
         is_error: true,
       };
     }
-    const ok = await deleteTask(ctx.conn, input.id);
+    const ok = await deleteTask(ctx.projectDir, input.id);
     if (!ok) {
       return {
         deleted_id: null,

package/src/tools/task/list.ts

@@ -1,11 +1,13 @@
 import { z } from "zod";
-import { listTasks, TASK_PRIORITIES, TASK_STATUSES } from "../../db/tasks.ts";
+import { TASK_PRIORITIES, TASK_STATUSES } from "../../tasks/schema.ts";
+import { listTasks } from "../../tasks/store.ts";
 import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({
   status: z.enum(TASK_STATUSES).optional().describe("Filter by status"),
   priority: z.enum(TASK_PRIORITIES).optional().describe("Filter by priority"),
   limit: z.number().optional().describe("Max number of tasks to return"),
+  offset: z.number().optional().describe("Skip first N tasks"),
 });
 
 const outputSchema = z.object({
@@ -31,10 +33,11 @@ export const listTasksTool = {
   inputSchema,
   outputSchema,
   execute: async (input, ctx) => {
-    const tasks = await listTasks(ctx.conn, {
+    const tasks = await listTasks(ctx.projectDir, {
       status: input.status,
       priority: input.priority,
       limit: input.limit,
+      offset: input.offset,
     });
     return {
       tasks: tasks.map((t) => ({
@@ -44,7 +47,7 @@ export const listTasksTool = {
         priority: t.priority,
         description: t.description,
         output: t.output,
-        created_at: t.created_at.toISOString(),
+        created_at: t.created_at,
       })),
       count: tasks.length,
       is_error: false,

package/src/tools/task/update.ts

@@ -1,5 +1,10 @@
 import { z } from "zod";
-import { getTask, TASK_PRIORITIES, updateTask } from "../../db/tasks.ts";
+import { TASK_PRIORITIES } from "../../tasks/schema.ts";
+import {
+  CircularDependencyError,
+  getTask,
+  updateTask,
+} from "../../tasks/store.ts";
 import { logger } from "../../utils/logger.ts";
 import type { ToolDefinition } from "../tool.ts";
 
@@ -28,6 +33,8 @@ const outputSchema = z.object({
     .nullable(),
   message: z.string(),
   is_error: z.boolean(),
+  error_type: z.string().optional(),
+  next_action_hint: z.string().optional(),
 });
 
 export const updateTaskTool = {
@@ -38,7 +45,7 @@ export const updateTaskTool = {
   inputSchema,
   outputSchema,
   execute: async (input, ctx) => {
-    const existing = await getTask(ctx.conn, input.id);
+    const existing = await getTask(ctx.projectDir, input.id);
     if (!existing) {
       return {
         task: null,
@@ -54,12 +61,27 @@ export const updateTaskTool = {
       };
     }
 
-    const updated = await updateTask(ctx.conn, input.id, {
-      name: input.name,
-      description: input.description,
-      priority: input.priority,
-      blocked_by: input.blocked_by,
-    });
+    let updated: Awaited<ReturnType<typeof updateTask>>;
+    try {
+      updated = await updateTask(ctx.projectDir, input.id, {
+        name: input.name,
+        description: input.description,
+        priority: input.priority,
+        blocked_by: input.blocked_by,
+      });
+    } catch (err) {
+      if (err instanceof CircularDependencyError) {
+        return {
+          task: null,
+          message: err.message,
+          is_error: true,
+          error_type: "circular_dependency",
+          next_action_hint:
+            "Pick blockers that don't transitively depend on this task.",
+        };
+      }
+      throw err;
+    }
 
     if (!updated) {
       return {
@@ -78,7 +100,7 @@ export const updateTaskTool = {
         status: updated.status,
         priority: updated.priority,
         blocked_by: updated.blocked_by,
-        updated_at: updated.updated_at.toISOString(),
+        updated_at: updated.updated_at,
       },
       message: `Updated task "${updated.name}"`,
       is_error: false,

package/src/tools/task/view.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { getTask } from "../../db/tasks.ts";
+import { getTask } from "../../tasks/store.ts";
 import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({
@@ -18,7 +18,7 @@ const outputSchema = z.object({
       output: z.string().nullable(),
       claimed_by: z.string().nullable(),
       blocked_by: z.array(z.string()),
-      context_ids: z.array(z.string()),
+      context_paths: z.array(z.string()),
       created_at: z.string(),
       updated_at: z.string(),
     })
@@ -33,7 +33,7 @@ export const viewTaskTool = {
   inputSchema,
   outputSchema,
   execute: async (input, ctx) => {
-    const task = await getTask(ctx.conn, input.id);
+    const task = await getTask(ctx.projectDir, input.id);
     if (!task) return { task: null, is_error: true };
     return {
       task: {
@@ -46,9 +46,9 @@ export const viewTaskTool = {
         output: task.output,
         claimed_by: task.claimed_by,
         blocked_by: task.blocked_by,
-        context_ids: task.context_ids,
-        created_at: task.created_at.toISOString(),
-        updated_at: task.updated_at.toISOString(),
+        context_paths: task.context_paths,
+        created_at: task.created_at,
+        updated_at: task.updated_at,
       },
       is_error: false,
     };

package/src/tools/thread/list.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { listThreads } from "../../db/threads.ts";
+import { listThreads } from "../../threads/store.ts";
 import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({
@@ -32,7 +32,7 @@ export const listThreadsTool = {
   inputSchema,
   outputSchema,
   execute: async (input, ctx) => {
-    const threads = await listThreads(ctx.conn, {
+    const threads = await listThreads(ctx.projectDir, {
       type: input.type,
       limit: input.limit,
     });

package/src/tools/thread/search.ts

@@ -0,0 +1,208 @@
+import { z } from "zod";
+import {
+  getThread,
+  type Interaction,
+  type InteractionKind,
+  type InteractionRole,
+  listThreads,
+  type Thread,
+} from "../../threads/store.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const ROLES = ["user", "assistant", "system", "tool"] as const;
+const KINDS = [
+  "message",
+  "thinking",
+  "tool_use",
+  "tool_result",
+  "context_update",
+  "status_change",
+] as const;
+
+const SNIPPET_MAX = 240;
+
+const inputSchema = z.object({
+  pattern: z
+    .string()
+    .describe(
+      "Regex pattern matched against each interaction's `content`. Use a plain substring (it's a regex, but plain text Just Works).",
+    ),
+  ignore_case: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe("Case-insensitive regex (default true)."),
+  role: z
+    .enum(ROLES)
+    .optional()
+    .describe(
+      "Restrict matches to a single role (user/assistant/system/tool).",
+    ),
+  kind: z
+    .enum(KINDS)
+    .optional()
+    .describe(
+      "Restrict matches to a single interaction kind (message/tool_use/tool_result/etc).",
+    ),
+  thread_type: z
+    .enum(["worker_tick", "chat_session"])
+    .optional()
+    .describe("Restrict to chat sessions or worker-tick threads."),
+  since: z
+    .string()
+    .optional()
+    .describe("ISO date — only consider threads started on or after this."),
+  until: z
+    .string()
+    .optional()
+    .describe("ISO date — only consider threads started on or before this."),
+  max_results: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .default(20)
+    .describe("Maximum number of hits to return across all threads."),
+});
+
+const HitSchema = z.object({
+  thread_id: z.string(),
+  thread_title: z.string(),
+  thread_type: z.string(),
+  sequence: z
+    .number()
+    .describe(
+      "1-based sequence of the matching interaction in the thread. Plug this into `view_thread({ id, offset: sequence-1, limit: 5 })` to read context around the hit.",
+    ),
+  role: z.string(),
+  kind: z.string(),
+  content_snippet: z.string(),
+  created_at: z.string(),
+});
+
+const outputSchema = z.object({
+  matches: z.array(HitSchema),
+  threads_scanned: z.number(),
+  is_error: z.boolean(),
+  error_type: z.string().optional(),
+  message: z.string().optional(),
+  next_action_hint: z.string().optional(),
+});
+
+export const searchThreadsTool = {
+  name: "search_threads",
+  description:
+    "[[ bash equivalent command: grep -r ]] Search past conversations (chat sessions and worker ticks) for a regex match. Returns hits with `(thread_id, sequence)` pairs — pass them to `view_thread` to read context around the match.",
+  group: "thread",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    let regex: RegExp;
+    try {
+      regex = new RegExp(input.pattern, input.ignore_case ? "i" : "");
+    } catch (err) {
+      return {
+        matches: [],
+        threads_scanned: 0,
+        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 sinceMs = input.since
+      ? Date.parse(input.since)
+      : Number.NEGATIVE_INFINITY;
+    const untilMs = input.until
+      ? Date.parse(input.until)
+      : Number.POSITIVE_INFINITY;
+
+    let threads: Thread[];
+    try {
+      threads = await listThreads(ctx.projectDir, {
+        type: input.thread_type,
+      });
+    } catch (err) {
+      return {
+        matches: [],
+        threads_scanned: 0,
+        is_error: true,
+        error_type: "list_failed",
+        message: `Failed to enumerate threads: ${err instanceof Error ? err.message : String(err)}`,
+      };
+    }
+
+    type Hit = z.infer<typeof HitSchema>;
+    const matches: Hit[] = [];
+    let scanned = 0;
+
+    for (const t of threads) {
+      const startedMs = t.started_at.getTime();
+      if (startedMs < sinceMs || startedMs > untilMs) continue;
+      const data = await getThread(ctx.projectDir, t.id);
+      if (!data) continue;
+      scanned++;
+      for (const ix of data.interactions) {
+        if (input.role && ix.role !== input.role) continue;
+        if (input.kind && ix.kind !== input.kind) continue;
+        if (!matchInteraction(ix, regex)) continue;
+        matches.push({
+          thread_id: t.id,
+          thread_title: t.title || "(untitled)",
+          thread_type: t.type,
+          sequence: ix.sequence,
+          role: ix.role,
+          kind: ix.kind,
+          content_snippet: snippetForMatch(ix.content, regex),
+          created_at: ix.created_at.toISOString(),
+        });
+        if (matches.length >= input.max_results) break;
+      }
+      if (matches.length >= input.max_results) break;
+    }
+
+    return {
+      matches,
+      threads_scanned: scanned,
+      is_error: false,
+      next_action_hint:
+        matches.length === 0
+          ? `No hits in ${scanned} thread(s). Try a broader pattern or remove role/kind filters.`
+          : `Pass any (thread_id, sequence) into view_thread({ id: thread_id, offset: sequence - 1, limit: 5 }) to read surrounding context.`,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;
+
+function matchInteraction(ix: Interaction, regex: RegExp): boolean {
+  // We treat the user-visible content as the primary haystack, but a
+  // tool_use interaction's content is just "Calling <name>" — fall through
+  // to the tool name + JSON args so a search for an exact tool argument
+  // still finds the call.
+  if (regex.test(ix.content)) return true;
+  if (ix.tool_name && regex.test(ix.tool_name)) return true;
+  if (ix.tool_input && regex.test(ix.tool_input)) return true;
+  return false;
+}
+
+/**
+ * Pick a short window around the first regex match so the agent gets enough
+ * context to know whether the hit is relevant without paging the whole
+ * interaction. Falls back to the head when the match index isn't available.
+ */
+function snippetForMatch(content: string, regex: RegExp): string {
+  const m = regex.exec(content);
+  if (!m) return content.slice(0, SNIPPET_MAX);
+  const idx = m.index;
+  const start = Math.max(0, idx - 60);
+  const end = Math.min(content.length, idx + SNIPPET_MAX - 60);
+  let snippet = content.slice(start, end);
+  if (start > 0) snippet = `…${snippet}`;
+  if (end < content.length) snippet = `${snippet}…`;
+  return snippet;
+}
+
+// Keep the role/kind unions exported for tests that want to type-pin filters.
+export type SearchThreadsRole = InteractionRole;
+export type SearchThreadsKind = InteractionKind;

package/src/tools/thread/view.ts

@@ -1,9 +1,27 @@
 import { z } from "zod";
-import { getThread } from "../../db/threads.ts";
+import { getThread } from "../../threads/store.ts";
 import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({
   id: z.string().describe("Thread ID to view"),
+  offset: z
+    .number()
+    .int()
+    .nonnegative()
+    .optional()
+    .default(0)
+    .describe(
+      "1-based sequence to start from (skip earlier interactions). Use with `limit` to paginate long threads.",
+    ),
+  limit: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .default(50)
+    .describe(
+      "Max interactions to return in this page. Default 50 keeps long threads from blowing the LLM context window.",
+    ),
 });
 
 const outputSchema = z.object({
@@ -28,19 +46,39 @@ const outputSchema = z.object({
       created_at: z.string(),
     }),
   ),
+  total_interactions: z.number(),
+  offset: z.number(),
+  limit: z.number(),
+  has_more: z.boolean(),
   is_error: z.boolean(),
+  next_action_hint: z.string().optional(),
 });
 
 export const viewThreadTool = {
   name: "view_thread",
   description:
-    "View a thread and its full interaction log (messages, tool calls, results).",
+    "View a thread's metadata and a paginated slice of its interactions. Pass `offset` (sequence to start from) and `limit` to walk a long thread without flooding the context window. `search_threads` returns `(thread_id, sequence)` pairs you can plug into `offset` to jump straight to a hit.",
   group: "thread",
   inputSchema,
   outputSchema,
   execute: async (input, ctx) => {
-    const result = await getThread(ctx.conn, input.id);
-    if (!result) return { thread: null, interactions: [], is_error: false };
+    const result = await getThread(ctx.projectDir, input.id);
+    if (!result) {
+      return {
+        thread: null,
+        interactions: [],
+        total_interactions: 0,
+        offset: input.offset,
+        limit: input.limit,
+        has_more: false,
+        is_error: false,
+      };
+    }
+    const total = result.interactions.length;
+    const start = Math.min(input.offset, total);
+    const end = Math.min(start + input.limit, total);
+    const page = result.interactions.slice(start, end);
+    const hasMore = end < total;
     return {
       thread: {
         id: result.thread.id,
@@ -50,7 +88,7 @@ export const viewThreadTool = {
         started_at: result.thread.started_at.toISOString(),
         ended_at: result.thread.ended_at?.toISOString() ?? null,
       },
-      interactions: result.interactions.map((i) => ({
+      interactions: page.map((i) => ({
         id: i.id,
         sequence: i.sequence,
         role: i.role,
@@ -59,6 +97,13 @@ export const viewThreadTool = {
         tool_name: i.tool_name,
         created_at: i.created_at.toISOString(),
       })),
+      total_interactions: total,
+      offset: start,
+      limit: input.limit,
+      has_more: hasMore,
+      next_action_hint: hasMore
+        ? `Call view_thread again with offset=${end} to see the next page.`
+        : undefined,
       is_error: false,
     };
   },

package/src/tools/tool.ts

@@ -17,6 +17,11 @@ export interface ToolContext {
   projectDir: string;
   config: Required<BotholomewConfig>;
   mcpxClient: McpxClient | null;
+  /**
+   * Chat-mode only. Lets long-running tools (e.g. `sleep`) poll for
+   * Esc-to-abort by reading `session.aborted`. Workers leave this `undefined`.
+   */
+  shouldAbort?: () => boolean;
 }
 
 type ToolOutputBase = { is_error: z.ZodBoolean };

package/src/tools/util/sleep.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import type { ToolDefinition } from "../tool.ts";
+
+const MIN_SECONDS = 1;
+const MAX_SECONDS = 3600;
+const POLL_INTERVAL_MS = 250;
+
+const inputSchema = z.object({
+  seconds: z
+    .number()
+    .int()
+    .min(MIN_SECONDS)
+    .max(MAX_SECONDS)
+    .describe(
+      `How long to sleep, in seconds (${MIN_SECONDS}–${MAX_SECONDS}). For longer pauses, create a schedule instead.`,
+    ),
+  reason: z
+    .string()
+    .min(1)
+    .describe(
+      "Why you're sleeping — shown to the user under the progress bar. Be specific (e.g. 'waiting for worker to finish task abc').",
+    ),
+});
+
+const outputSchema = z.object({
+  message: z.string(),
+  slept_seconds: z.number(),
+  aborted: z.boolean(),
+  is_error: z.boolean(),
+});
+
+export const sleepTool = {
+  name: "sleep",
+  description:
+    "[[ bash equivalent command: sleep ]] Pause the chat agent for a fixed number of seconds. Useful after enqueuing tasks for workers, before checking results. The user sees a progress bar while you wait; pressing Esc cancels the wait. Returns when the time elapses or the user steers.",
+  group: "util",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx): Promise<z.infer<typeof outputSchema>> => {
+    const startedAt = Date.now();
+    const totalMs = input.seconds * 1000;
+    const shouldAbort = ctx.shouldAbort;
+
+    let aborted: boolean = false;
+    await new Promise<void>((resolve) => {
+      let timeout: ReturnType<typeof setTimeout> | null = null;
+      let interval: ReturnType<typeof setInterval> | null = null;
+
+      const finish = () => {
+        if (timeout) clearTimeout(timeout);
+        if (interval) clearInterval(interval);
+        resolve();
+      };
+
+      timeout = setTimeout(finish, totalMs);
+
+      if (shouldAbort) {
+        interval = setInterval(() => {
+          if (shouldAbort()) {
+            aborted = true;
+            finish();
+          }
+        }, POLL_INTERVAL_MS);
+      }
+    });
+
+    const sleptSeconds = (Date.now() - startedAt) / 1000;
+    return {
+      message: aborted
+        ? `Sleep interrupted after ${sleptSeconds.toFixed(1)}s of ${input.seconds}s — user steered.`
+        : `Slept ${sleptSeconds.toFixed(1)}s. ${input.reason}`,
+      slept_seconds: sleptSeconds,
+      aborted,
+      is_error: false,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;