botholomew 0.3.1 → 0.3.2

package/src/tools/context/update-goals.ts

@@ -19,6 +19,7 @@ const inputSchema = z.object({
 const outputSchema = z.object({
   message: z.string(),
   path: z.string(),
+  is_error: z.boolean(),
 });
 
 export const updateGoalsTool = {
@@ -49,6 +50,7 @@ export const updateGoalsTool = {
     return {
       message: "Updated goals.md",
       path: filePath,
+      is_error: false,
     };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/dir/create.ts

@@ -13,6 +13,7 @@ const inputSchema = z.object({
 const outputSchema = z.object({
   created: z.boolean(),
   path: z.string(),
+  is_error: z.boolean(),
 });
 
 export const dirCreateTool = {
@@ -24,7 +25,7 @@ export const dirCreateTool = {
   execute: async (input, ctx) => {
     const exists = await contextPathExists(ctx.conn, input.path);
     if (exists) {
-      return { created: false, path: input.path };
+      return { created: false, path: input.path, is_error: false };
     }
 
     await createContextItem(ctx.conn, {
@@ -34,6 +35,6 @@ export const dirCreateTool = {
       isTextual: false,
     });
 
-    return { created: true, path: input.path };
+    return { created: true, path: input.path, is_error: false };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/dir/list.ts

@@ -33,6 +33,7 @@ const inputSchema = z.object({
 const outputSchema = z.object({
   entries: z.array(DirEntrySchema),
   total: z.number(),
+  is_error: z.boolean(),
 });
 
 export const dirListTool = {
@@ -82,6 +83,6 @@ export const dirListTool = {
     const total = entries.length;
     const paginated = entries.slice(offset, offset + limit);
 
-    return { entries: paginated, total };
+    return { entries: paginated, total, is_error: false };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/dir/size.ts

@@ -21,6 +21,7 @@ const inputSchema = z.object({
 const outputSchema = z.object({
   bytes: z.number(),
   formatted: z.string(),
+  is_error: z.boolean(),
 });
 
 export const dirSizeTool = {
@@ -40,6 +41,6 @@ export const dirSizeTool = {
       if (item.content != null) bytes += item.content.length;
     }
 
-    return { bytes, formatted: formatBytes(bytes) };
+    return { bytes, formatted: formatBytes(bytes), is_error: false };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/dir/tree.ts

@@ -20,6 +20,7 @@ const inputSchema = z.object({
 
 const outputSchema = z.object({
   tree: z.string(),
+  is_error: z.boolean(),
 });
 
 export const dirTreeTool = {
@@ -38,7 +39,7 @@ export const dirTreeTool = {
     });
 
     if (items.length === 0) {
-      return { tree: `${path}\n  (empty)` };
+      return { tree: `${path}\n  (empty)`, is_error: false };
     }
 
     const normalizedPath = path.endsWith("/") ? path : `${path}/`;
@@ -86,6 +87,6 @@ export const dirTreeTool = {
       lines.push(`... (truncated at ${maxItems} items)`);
     }
 
-    return { tree: lines.join("\n") };
+    return { tree: lines.join("\n"), is_error: false };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/file/copy.ts

@@ -15,6 +15,7 @@ const inputSchema = z.object({
 const outputSchema = z.object({
   id: z.string(),
   path: z.string(),
+  is_error: z.boolean(),
 });
 
 export const fileCopyTool = {
@@ -33,6 +34,6 @@ export const fileCopyTool = {
     }
 
     const item = await copyContextItem(ctx.conn, input.src, input.dst);
-    return { id: item.id, path: item.context_path };
+    return { id: item.id, path: item.context_path, is_error: false };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/file/count-lines.ts

@@ -8,6 +8,7 @@ const inputSchema = z.object({
 
 const outputSchema = z.object({
   lines: z.number(),
+  is_error: z.boolean(),
 });
 
 export const fileCountLinesTool = {
@@ -21,6 +22,6 @@ export const fileCountLinesTool = {
     if (!item) throw new Error(`Not found: ${input.path}`);
     if (item.content == null) throw new Error(`No text content: ${input.path}`);
 
-    return { lines: item.content.split("\n").length };
+    return { lines: item.content.split("\n").length, is_error: false };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/file/delete.ts

@@ -19,6 +19,7 @@ const inputSchema = z.object({
 
 const outputSchema = z.object({
   deleted: z.number(),
+  is_error: z.boolean(),
 });
 
 export const fileDeleteTool = {
@@ -31,13 +32,13 @@ export const fileDeleteTool = {
     if (input.recursive) {
       const count = await deleteContextItemsByPrefix(ctx.conn, input.path);
       const exact = await deleteContextItemByPath(ctx.conn, input.path);
-      return { deleted: count + (exact ? 1 : 0) };
+      return { deleted: count + (exact ? 1 : 0), is_error: false };
     }
 
     const deleted = await deleteContextItemByPath(ctx.conn, input.path);
     if (!deleted && !input.force) {
       throw new Error(`Not found: ${input.path}`);
     }
-    return { deleted: deleted ? 1 : 0 };
+    return { deleted: deleted ? 1 : 0, is_error: false };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/file/edit.ts

@@ -21,6 +21,7 @@ const inputSchema = z.object({
 const outputSchema = z.object({
   applied: z.number(),
   content: z.string(),
+  is_error: z.boolean(),
 });
 
 export const fileEditTool = {
@@ -38,6 +39,6 @@ export const fileEditTool = {
     );
 
     await ingestByPath(ctx.conn, input.path, ctx.config, ctx.embedFn);
-    return { applied, content: item.content ?? "" };
+    return { applied, content: item.content ?? "", is_error: false };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/file/exists.ts

@@ -8,6 +8,7 @@ const inputSchema = z.object({
 
 const outputSchema = z.object({
   exists: z.boolean(),
+  is_error: z.boolean(),
 });
 
 export const fileExistsTool = {
@@ -18,6 +19,6 @@ export const fileExistsTool = {
   outputSchema,
   execute: async (input, ctx) => {
     const exists = await contextPathExists(ctx.conn, input.path);
-    return { exists };
+    return { exists, is_error: false };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/file/info.ts

@@ -19,6 +19,7 @@ const outputSchema = z.object({
   indexed_at: z.string().nullable(),
   created_at: z.string(),
   updated_at: z.string(),
+  is_error: z.boolean(),
 });
 
 export const fileInfoTool = {
@@ -45,6 +46,7 @@ export const fileInfoTool = {
       indexed_at: item.indexed_at?.toISOString() ?? null,
       created_at: item.created_at.toISOString(),
       updated_at: item.updated_at.toISOString(),
+      is_error: false,
     };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/file/move.ts

@@ -14,6 +14,7 @@ const inputSchema = z.object({
 
 const outputSchema = z.object({
   path: z.string(),
+  is_error: z.boolean(),
 });
 
 export const fileMoveTool = {
@@ -38,6 +39,6 @@ export const fileMoveTool = {
       .query("UPDATE embeddings SET source_path = ?1 WHERE source_path = ?2")
       .run(input.dst, input.src);
 
-    return { path: input.dst };
+    return { path: input.dst, is_error: false };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/file/read.ts

@@ -13,6 +13,7 @@ const inputSchema = z.object({
 
 const outputSchema = z.object({
   content: z.string(),
+  is_error: z.boolean(),
 });
 
 export const fileReadTool = {
@@ -35,6 +36,6 @@ export const fileReadTool = {
       content = lines.slice(start, end).join("\n");
     }
 
-    return { content };
+    return { content, is_error: false };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/file/write.ts

@@ -40,6 +40,7 @@ const inputSchema = z.object({
 const outputSchema = z.object({
   id: z.string(),
   path: z.string(),
+  is_error: z.boolean(),
 });
 
 export const fileWriteTool = {
@@ -72,7 +73,7 @@ export const fileWriteTool = {
         });
       }
       await ingestByPath(ctx.conn, input.path, ctx.config, ctx.embedFn);
-      return { id: existing.id, path: input.path };
+      return { id: existing.id, path: input.path, is_error: false };
     }
 
     const title =
@@ -88,6 +89,6 @@ export const fileWriteTool = {
     });
 
     await ingestByPath(ctx.conn, input.path, ctx.config, ctx.embedFn);
-    return { id: item.id, path: item.context_path };
+    return { id: item.id, path: item.context_path, is_error: false };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/mcp/exec.ts

@@ -11,15 +11,72 @@ const inputSchema = z.object({
     .describe("Tool arguments as a JSON object"),
 });
 
+const errorKindSchema = z
+  .enum(["retryable", "permanent", "input_error", "auth_error"])
+  .optional();
+
 const outputSchema = z.object({
   result: z.string(),
   is_error: z.boolean(),
+  error_kind: errorKindSchema,
+  hint: z.string().optional(),
 });
 
+type ErrorKind = z.infer<typeof errorKindSchema>;
+
+function classifyError(err: unknown): { error_kind: ErrorKind; hint: string } {
+  const msg = String(err).toLowerCase();
+
+  if (
+    msg.includes("econnrefused") ||
+    msg.includes("etimedout") ||
+    msg.includes("enotfound") ||
+    msg.includes("rate limit") ||
+    msg.includes("429") ||
+    msg.includes("503")
+  ) {
+    return {
+      error_kind: "retryable",
+      hint: "Transient network error. Retry after a pause.",
+    };
+  }
+
+  if (
+    msg.includes("401") ||
+    msg.includes("403") ||
+    msg.includes("unauthorized") ||
+    msg.includes("forbidden") ||
+    msg.includes("authentication") ||
+    msg.includes("auth")
+  ) {
+    return {
+      error_kind: "auth_error",
+      hint: "Authentication failed. Check MCP server credentials. Not retryable.",
+    };
+  }
+
+  if (
+    msg.includes("invalid") ||
+    msg.includes("validation") ||
+    msg.includes("required") ||
+    msg.includes("schema")
+  ) {
+    return {
+      error_kind: "input_error",
+      hint: `Tool rejected input. Use mcp_info to check the expected schema for ${msg}, then retry with corrected arguments.`,
+    };
+  }
+
+  return {
+    error_kind: "permanent",
+    hint: "Unexpected error. Use mcp_search to find an alternative tool.",
+  };
+}
+
 export const mcpExecTool = {
   name: "mcp_exec",
   description:
-    "Execute a tool on an MCP server. Use mcp_list_tools or mcp_search to discover available tools first.",
+    "Execute a tool on an MCP server. Use mcp_list_tools or mcp_search to discover available tools first, and mcp_info to check the expected input schema.",
   group: "mcp",
   inputSchema,
   outputSchema,
@@ -27,8 +84,10 @@ export const mcpExecTool = {
     if (!ctx.mcpxClient) {
       return {
         result:
-          "No MCP servers configured. Add servers with `botholomew mcpx add`.",
+          "No MCP servers configured. This task requires external tool access. Add servers with `botholomew mcpx add`.",
         is_error: true,
+        error_kind: "permanent" as const,
+        hint: "Consider calling fail_task noting that MCP servers need to be configured.",
       };
     }
 
@@ -38,14 +97,22 @@ export const mcpExecTool = {
         input.tool,
         input.args,
       );
+      const isError = callResult.isError ?? false;
       return {
         result: formatCallToolResult(callResult),
-        is_error: callResult.isError ?? false,
+        is_error: isError,
+        error_kind: undefined,
+        hint: isError
+          ? "The tool returned an error. Check the error message and use mcp_info to verify you're passing the correct arguments."
+          : undefined,
       };
     } catch (err) {
+      const { error_kind, hint } = classifyError(err);
       return {
         result: `MCP tool error: ${err}`,
         is_error: true,
+        error_kind,
+        hint,
       };
     }
   },

package/src/tools/mcp/info.ts

@@ -11,6 +11,8 @@ const outputSchema = z.object({
   name: z.string(),
   description: z.string(),
   input_schema: z.string(),
+  is_error: z.boolean(),
+  hint: z.string().optional(),
 });
 
 export const mcpInfoTool = {
@@ -27,6 +29,8 @@ export const mcpInfoTool = {
         name: input.tool,
         description: "No MCP servers configured.",
         input_schema: "{}",
+        is_error: true,
+        hint: "Add MCP servers with `botholomew mcpx add` before using external tools.",
       };
     }
 
@@ -37,6 +41,8 @@ export const mcpInfoTool = {
         name: input.tool,
         description: `Tool "${input.tool}" not found on server "${input.server}".`,
         input_schema: "{}",
+        is_error: true,
+        hint: "Tool not found. Use mcp_search or mcp_list_tools to find the correct server and tool name.",
       };
     }
 
@@ -45,6 +51,8 @@ export const mcpInfoTool = {
       name: tool.name,
       description: tool.description ?? "",
       input_schema: JSON.stringify(tool.inputSchema ?? {}, null, 2),
+      is_error: false,
+      hint: `Call mcp_exec with server='${input.server}', tool='${tool.name}', and the required args.`,
     };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/mcp/list-tools.ts

@@ -16,6 +16,8 @@ const ToolEntrySchema = z.object({
 
 const outputSchema = z.object({
   tools: z.array(ToolEntrySchema),
+  is_error: z.boolean(),
+  hint: z.string().optional(),
 });
 
 export const mcpListToolsTool = {
@@ -27,16 +29,26 @@ export const mcpListToolsTool = {
   outputSchema,
   execute: async (input, ctx) => {
     if (!ctx.mcpxClient) {
-      return { tools: [] };
+      return {
+        tools: [],
+        is_error: false,
+        hint: "No MCP servers configured. Add servers with `botholomew mcpx add`.",
+      };
     }
 
     const toolsWithServer = await ctx.mcpxClient.listTools(input.server);
+    const mapped = toolsWithServer.map((t) => ({
+      server: t.server,
+      name: t.tool.name,
+      description: t.tool.description ?? "",
+    }));
     return {
-      tools: toolsWithServer.map((t) => ({
-        server: t.server,
-        name: t.tool.name,
-        description: t.tool.description ?? "",
-      })),
+      tools: mapped,
+      is_error: false,
+      hint:
+        mapped.length > 0
+          ? "Use mcp_search to find tools by capability, or mcp_info to get the full schema for a specific tool."
+          : "No tools available. MCP servers may not be configured or may be offline.",
     };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/mcp/search.ts

@@ -23,6 +23,9 @@ const SearchResultSchema = z.object({
 
 const outputSchema = z.object({
   results: z.array(SearchResultSchema),
+  is_error: z.boolean(),
+  error_message: z.string().optional(),
+  hint: z.string().optional(),
 });
 
 export const mcpSearchTool = {
@@ -34,7 +37,11 @@ export const mcpSearchTool = {
   outputSchema,
   execute: async (input, ctx) => {
     if (!ctx.mcpxClient) {
-      return { results: [] };
+      return {
+        results: [],
+        is_error: false,
+        hint: "No MCP servers configured. Add servers with `botholomew mcpx add`.",
+      };
     }
 
     try {
@@ -42,17 +49,38 @@ export const mcpSearchTool = {
         keywordOnly: input.keyword_only,
         semanticOnly: input.semantic_only,
       });
+      const mapped = results.map((r) => ({
+        server: r.server,
+        tool: r.tool,
+        description: r.description ?? "",
+        score: r.score,
+        match_type: r.matchType ?? "keyword",
+      }));
+      return {
+        results: mapped,
+        is_error: false,
+        hint:
+          mapped.length > 0
+            ? "Use mcp_info with server and tool name to see the full input schema before calling mcp_exec."
+            : "No matches. Try broader search terms, or use mcp_list_tools to browse all available tools.",
+      };
+    } catch (err) {
+      const msg = String(err).toLowerCase();
+      const isIndexMissing =
+        msg.includes("index") ||
+        msg.includes("not found") ||
+        msg.includes("no such file");
+
       return {
-        results: results.map((r) => ({
-          server: r.server,
-          tool: r.tool,
-          description: r.description ?? "",
-          score: r.score,
-          match_type: r.matchType ?? "keyword",
-        })),
+        results: [],
+        is_error: true,
+        error_message: isIndexMissing
+          ? "Search index not built. Run 'botholomew mcpx index' to build it."
+          : `Search failed: ${err}`,
+        hint: isIndexMissing
+          ? "Use mcp_list_tools to browse available tools instead."
+          : "Search temporarily unavailable. Use mcp_list_tools as a fallback.",
       };
-    } catch {
-      return { results: [] };
     }
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/registry.ts

@@ -34,6 +34,7 @@ import { completeTaskTool } from "./task/complete.ts";
 import { createTaskTool } from "./task/create.ts";
 import { failTaskTool } from "./task/fail.ts";
 import { listTasksTool } from "./task/list.ts";
+import { updateTaskTool } from "./task/update.ts";
 import { viewTaskTool } from "./task/view.ts";
 import { waitTaskTool } from "./task/wait.ts";
 // Thread tools
@@ -47,6 +48,7 @@ export function registerAllTools(): void {
   registerTool(failTaskTool);
   registerTool(waitTaskTool);
   registerTool(createTaskTool);
+  registerTool(updateTaskTool);
   registerTool(listTasksTool);
   registerTool(viewTaskTool);
 

package/src/tools/schedule/create.ts

@@ -17,6 +17,7 @@ const outputSchema = z.object({
   id: z.string(),
   name: z.string(),
   message: z.string(),
+  is_error: z.boolean(),
 });
 
 export const createScheduleTool = {
@@ -37,6 +38,7 @@ export const createScheduleTool = {
       id: schedule.id,
       name: schedule.name,
       message: `Created schedule "${schedule.name}" with frequency "${schedule.frequency}"`,
+      is_error: false,
     };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/schedule/list.ts

@@ -17,6 +17,7 @@ const outputSchema = z.object({
     }),
   ),
   count: z.number(),
+  is_error: z.boolean(),
 });
 
 export const listSchedulesTool = {
@@ -38,6 +39,7 @@ export const listSchedulesTool = {
         last_run_at: s.last_run_at?.toISOString() ?? null,
       })),
       count: schedules.length,
+      is_error: false,
     };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/search/grep.ts

@@ -32,6 +32,7 @@ const inputSchema = z.object({
 
 const outputSchema = z.object({
   matches: z.array(GrepMatchSchema),
+  is_error: z.boolean(),
 });
 
 export const searchGrepTool = {
@@ -76,12 +77,12 @@ export const searchGrepTool = {
             content: line,
             context_lines: lines.slice(start, end),
           });
-          if (matches.length >= maxResults) return { matches };
+          if (matches.length >= maxResults) return { matches, is_error: false };
         }
       }
     }
 
-    return { matches };
+    return { matches, is_error: false };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;
 

package/src/tools/search/semantic.ts

@@ -25,6 +25,7 @@ const outputSchema = z.object({
       snippet: z.string(),
     }),
   ),
+  is_error: z.boolean(),
 });
 
 export const searchSemanticTool = {
@@ -55,6 +56,7 @@ export const searchSemanticTool = {
           snippet: (r.chunk_content || "").slice(0, 300),
         }))
         .sort((a, b) => b.score - a.score),
+      is_error: false,
     };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/task/complete.ts

@@ -7,6 +7,7 @@ const inputSchema = z.object({
 
 const outputSchema = z.object({
   message: z.string(),
+  is_error: z.boolean(),
 });
 
 export const completeTaskTool = {
@@ -19,5 +20,6 @@ export const completeTaskTool = {
   outputSchema,
   execute: async (input) => ({
     message: `Task completed: ${input.summary}`,
+    is_error: false,
   }),
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/task/create.ts

@@ -4,9 +4,19 @@ import { logger } from "../../utils/logger.ts";
 import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({
-  name: z.string().describe("Task name"),
-  description: z.string().optional().describe("Task description"),
-  priority: z.enum(TASK_PRIORITIES).optional().describe("Task priority"),
+  name: z
+    .string()
+    .describe("Concise but descriptive task name summarizing the goal"),
+  description: z
+    .string()
+    .optional()
+    .describe(
+      "Detailed description including relevant file paths, what needs to change, why, and any constraints. Rich descriptions reduce redundant tool calls when the task is picked up later.",
+    ),
+  priority: z
+    .enum(TASK_PRIORITIES)
+    .optional()
+    .describe("Task priority (default: medium)"),
   blocked_by: z
     .array(z.string())
     .optional()
@@ -17,11 +27,13 @@ const outputSchema = z.object({
   id: z.string(),
   name: z.string(),
   message: z.string(),
+  is_error: z.boolean(),
 });
 
 export const createTaskTool = {
   name: "create_task",
-  description: "Create a new task to be worked on later.",
+  description:
+    "Create a new task. Include as much context as possible in the description so the agent picking it up can start immediately without redundant lookups.",
   group: "task",
   inputSchema,
   outputSchema,
@@ -37,6 +49,7 @@ export const createTaskTool = {
       id: newTask.id,
       name: newTask.name,
       message: `Created task "${newTask.name}" with ID ${newTask.id}`,
+      is_error: false,
     };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;