botholomew 0.8.4 → 0.8.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botholomew",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "description": "An autonomous AI agent for knowledge work — works your task queue while you sleep.",
   "type": "module",
   "bin": {

package/src/commands/mcpx.ts

@@ -51,155 +51,64 @@ function getDir(program: Command): string {
   return program.opts().dir;
 }
 
+// Slice process.argv from the token after "mcpx" so flags (including --help)
+// and positional args flow through to upstream mcpx verbatim.
+function getRawMcpxArgs(): string[] {
+  const idx = process.argv.indexOf("mcpx");
+  return idx === -1 ? [] : process.argv.slice(idx + 1);
+}
+
+const PASSTHROUGH_SUBCOMMANDS: ReadonlyArray<[name: string, desc: string]> = [
+  ["servers", "List configured MCP server names"],
+  ["info", "Show server overview or schema for a specific tool"],
+  ["search", "Search tools by keyword and/or semantic similarity"],
+  ["exec", "Execute a tool call"],
+  ["add", "Add an MCP server"],
+  ["remove", "Remove an MCP server"],
+  ["ping", "Check connectivity to MCP servers"],
+  ["auth", "Authenticate with an HTTP MCP server"],
+  ["deauth", "Remove stored authentication for a server"],
+  ["resource", "List resources for a server, or read a specific resource"],
+  ["prompt", "List prompts for a server, or get a specific prompt"],
+  ["task", "Manage async tool tasks (list, get, result, cancel)"],
+  ["index", "Build the search index from all configured servers"],
+];
+
 export function registerMcpxCommand(program: Command) {
   const mcpx = program
     .command("mcpx")
     .description("Manage MCP servers via MCPX");
 
-  // --- servers ---
-  mcpx
-    .command("servers")
-    .description("List configured MCP server names")
-    .action(async () => {
-      const out = await runMcpx(getDir(program), ["servers"]);
-      process.stdout.write(out);
-    });
-
-  // --- info ---
-  mcpx
-    .command("info <first> [second]")
-    .description(
-      "Show server overview, or schema for a specific tool (server is optional if tool name is unambiguous)",
-    )
-    .action(async (first: string, second?: string) => {
-      const out = await runMcpx(getDir(program), ["info", first, second]);
-      process.stdout.write(out);
-    });
-
-  // --- search ---
-  mcpx
-    .command("search <terms...>")
-    .description("Search tools by keyword and/or semantic similarity")
-    .action(async (terms: string[]) => {
-      const out = await runMcpx(getDir(program), ["search", ...terms]);
-      process.stdout.write(out);
-    });
+  for (const [name, description] of PASSTHROUGH_SUBCOMMANDS) {
+    mcpx
+      .command(name)
+      .description(description)
+      .allowUnknownOption(true)
+      .helpOption(false)
+      .argument("[args...]", "arguments forwarded to mcpx")
+      .action(async () => {
+        await runMcpx(getDir(program), getRawMcpxArgs(), { inherit: true });
+      });
+  }
 
-  // --- exec ---
+  // Upstream mcpx's "list" is the default action when invoked with no
+  // subcommand — not a registered subcommand — so we strip the "list"
+  // token before forwarding.
   mcpx
-    .command("exec <first> [second] [third]")
+    .command("list")
     .description(
-      "Execute a tool call (server is optional if tool name is unambiguous)",
+      "List all tools, resources, and prompts across all configured servers",
     )
-    .action(async (first: string, second?: string, third?: string) => {
-      const out = await runMcpx(getDir(program), [
-        "exec",
-        first,
-        second,
-        third,
-      ]);
-      process.stdout.write(out);
-    });
-
-  // --- add ---
-  mcpx
-    .command("add <name>")
-    .description("Add an MCP server")
-    .option("--command <cmd>", "Stdio server command")
-    .option("--args <args...>", "Stdio server arguments")
-    .option("--url <url>", "HTTP server URL")
-    .option("--transport <type>", "HTTP transport: sse or streamable-http")
-    .option("--env <pairs...>", "Environment variables as KEY=VALUE pairs")
-    .action(
-      async (
-        name: string,
-        opts: {
-          command?: string;
-          args?: string[];
-          url?: string;
-          transport?: string;
-          env?: string[];
-        },
-      ) => {
-        const cliArgs: string[] = ["add", name];
-        if (opts.command) cliArgs.push("--command", opts.command);
-        if (opts.args) {
-          for (const a of opts.args) cliArgs.push("--args", a);
-        }
-        if (opts.url) cliArgs.push("--url", opts.url);
-        if (opts.transport) cliArgs.push("--transport", opts.transport);
-        if (opts.env) {
-          for (const e of opts.env) cliArgs.push("--env", e);
-        }
-        const out = await runMcpx(getDir(program), cliArgs);
-        process.stdout.write(out);
-      },
-    );
-
-  // --- remove ---
-  mcpx
-    .command("remove <name>")
-    .description("Remove an MCP server")
-    .action(async (name: string) => {
-      const out = await runMcpx(getDir(program), ["remove", name]);
-      process.stdout.write(out);
-    });
-
-  // --- ping ---
-  mcpx
-    .command("ping [servers...]")
-    .description("Check connectivity to MCP servers")
-    .action(async (servers: string[]) => {
-      const out = await runMcpx(getDir(program), ["ping", ...servers]);
-      process.stdout.write(out);
-    });
-
-  // --- auth ---
-  mcpx
-    .command("auth <server>")
-    .description("Authenticate with an HTTP MCP server")
-    .action(async (server: string) => {
-      await runMcpx(getDir(program), ["auth", server], { inherit: true });
-    });
-
-  // --- resource ---
-  mcpx
-    .command("resource [server] [uri]")
-    .description("List resources for a server, or read a specific resource")
-    .action(async (server?: string, uri?: string) => {
-      const out = await runMcpx(getDir(program), ["resource", server, uri]);
-      process.stdout.write(out);
-    });
-
-  // --- prompt ---
-  mcpx
-    .command("prompt [server] [name] [args]")
-    .description("List prompts for a server, or get a specific prompt")
-    .action(async (server?: string, name?: string, argsJson?: string) => {
-      const out = await runMcpx(getDir(program), [
-        "prompt",
-        server,
-        name,
-        argsJson,
-      ]);
-      process.stdout.write(out);
-    });
-
-  // --- task ---
-  mcpx
-    .command("task <action> <server> [taskId]")
-    .description("Manage async tasks (actions: list, get, result, cancel)")
-    .action(async (action: string, server: string, taskId?: string) => {
-      const out = await runMcpx(getDir(program), [
-        "task",
-        action,
-        server,
-        taskId,
-      ]);
-      process.stdout.write(out);
+    .allowUnknownOption(true)
+    .helpOption(false)
+    .argument("[args...]", "arguments forwarded to mcpx")
+    .action(async () => {
+      const raw = getRawMcpxArgs();
+      const args = raw[0] === "list" ? raw.slice(1) : raw;
+      await runMcpx(getDir(program), args, { inherit: true });
     });
 
-  // --- import-global ---
+  // Botholomew-specific: copy system-wide MCPX settings into this project.
   mcpx
     .command("import-global")
     .description("Copy system-wide MCPX settings (~/.mcpx) into this project")
@@ -234,12 +143,4 @@ export function registerMcpxCommand(program: Command) {
         );
       }
     });
-
-  // --- index ---
-  mcpx
-    .command("index")
-    .description("Build the search index from all configured servers")
-    .action(async () => {
-      await runMcpx(getDir(program), ["index"], { inherit: true });
-    });
 }

package/src/tools/context/refresh.ts

@@ -6,6 +6,7 @@ import {
   listContextItemsByPrefix,
   resolveContextItem,
 } from "../../db/context.ts";
+import { buildContextTree } from "../dir/tree.ts";
 import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({
@@ -43,6 +44,12 @@ const outputSchema = z.object({
   ),
   message: z.string(),
   is_error: z.boolean(),
+  tree: z
+    .string()
+    .optional()
+    .describe(
+      "Snapshot of the context filesystem after the refresh so you can see what's currently stored.",
+    ),
 });
 
 const empty = {
@@ -54,6 +61,7 @@ const empty = {
   chunks: 0,
   embeddings_skipped: false,
   items: [],
+  tree: undefined as string | undefined,
 };
 
 export const contextRefreshTool = {
@@ -127,10 +135,13 @@ export const contextRefreshTool = {
       parts.push("embeddings skipped (no OpenAI API key configured)");
     }
 
+    const { tree } = await buildContextTree(ctx.conn);
+
     return {
       ...result,
       message: parts.join(", "),
       is_error: false,
+      tree,
     };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/dir/tree.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import type { DbConnection } from "../../db/connection.ts";
 import {
   countContextItemsByPrefix,
   listContextItemsByPrefix,
@@ -9,6 +10,185 @@ const DEFAULT_MAX_DEPTH = 3;
 const DEFAULT_ITEMS_PER_DIR = 15;
 const HARD_FETCH_CAP = 1000;
 
+export interface BuildContextTreeOptions {
+  path?: string;
+  maxDepth?: number;
+  itemsPerDir?: number;
+}
+
+export interface BuildContextTreeResult {
+  tree: string;
+  total_items: number;
+  truncated_dirs: Array<{ path: string; shown: number; total: number }>;
+  hint: string;
+}
+
+interface DirNode {
+  name: string;
+  fullPath: string;
+  isDir: true;
+  children: TreeEntry[];
+}
+
+interface FileNode {
+  name: string;
+  fullPath: string;
+  isDir: false;
+}
+
+type TreeEntry = DirNode | FileNode;
+
+export async function buildContextTree(
+  conn: DbConnection,
+  options: BuildContextTreeOptions = {},
+): Promise<BuildContextTreeResult> {
+  const path = options.path ?? "/";
+  const maxDepth = options.maxDepth ?? DEFAULT_MAX_DEPTH;
+  const itemsPerDir = options.itemsPerDir ?? DEFAULT_ITEMS_PER_DIR;
+  const normalizedPath = path.endsWith("/") ? path : `${path}/`;
+
+  const totalItems = await countContextItemsByPrefix(conn, path, {
+    recursive: true,
+  });
+
+  if (totalItems === 0) {
+    return {
+      tree: `${path}\n  (empty)`,
+      total_items: 0,
+      truncated_dirs: [],
+      hint: "Directory is empty.",
+    };
+  }
+
+  const items = await listContextItemsByPrefix(conn, path, {
+    recursive: true,
+    limit: HARD_FETCH_CAP,
+  });
+
+  // Build tree structure: dirs map child name -> child node
+  const root: DirNode = {
+    name: path,
+    fullPath: path,
+    isDir: true,
+    children: [],
+  };
+  const dirIndex = new Map<string, DirNode>();
+  dirIndex.set(stripTrailingSlash(path), root);
+
+  for (const item of items) {
+    const relative = item.context_path.slice(normalizedPath.length);
+    if (relative.length === 0) continue; // root itself, skip
+    const parts = relative.split("/").filter((p) => p.length > 0);
+    const isExplicitDir = item.mime_type === "inode/directory";
+
+    // Walk segments, creating intermediate directories as needed
+    let parentDir = root;
+    let currentRel = "";
+    for (let i = 0; i < parts.length; i++) {
+      const segment = parts[i];
+      if (!segment) continue;
+      currentRel = currentRel ? `${currentRel}/${segment}` : segment;
+      const fullPath = `${normalizedPath}${currentRel}`;
+      const isLeaf = i === parts.length - 1;
+      const isDirHere = !isLeaf || isExplicitDir;
+
+      if (isDirHere) {
+        const key = stripTrailingSlash(fullPath);
+        let dir = dirIndex.get(key);
+        if (!dir) {
+          dir = {
+            name: segment,
+            fullPath,
+            isDir: true,
+            children: [],
+          };
+          dirIndex.set(key, dir);
+          parentDir.children.push(dir);
+        }
+        parentDir = dir;
+      } else {
+        parentDir.children.push({
+          name: segment,
+          fullPath,
+          isDir: false,
+        });
+      }
+    }
+  }
+
+  // Sort each directory's children: dirs first, then alphabetical
+  for (const dir of dirIndex.values()) {
+    dir.children.sort((a, b) => {
+      if (a.isDir !== b.isDir) return a.isDir ? -1 : 1;
+      return a.name.localeCompare(b.name);
+    });
+  }
+
+  const truncatedDirs: Array<{
+    path: string;
+    shown: number;
+    total: number;
+  }> = [];
+  const depthLimitedDirs: string[] = [];
+
+  const lines: string[] = [path];
+
+  const render = (dir: DirNode, indent: string, currentDepth: number): void => {
+    const children = dir.children;
+    const total = children.length;
+    const shown = Math.min(total, itemsPerDir);
+    const visible = children.slice(0, shown);
+    const overflow = total - shown;
+
+    if (overflow > 0) {
+      truncatedDirs.push({
+        path: stripTrailingSlash(dir.fullPath),
+        shown,
+        total,
+      });
+    }
+
+    for (let i = 0; i < visible.length; i++) {
+      const child = visible[i];
+      if (!child) continue;
+      const isLastVisible = i === visible.length - 1 && overflow === 0;
+      const connector = isLastVisible ? "└── " : "├── ";
+      const childIndent = isLastVisible ? "    " : "│   ";
+
+      if (child.isDir) {
+        const atDepthLimit = currentDepth + 1 >= maxDepth;
+        if (atDepthLimit && child.children.length > 0) {
+          depthLimitedDirs.push(stripTrailingSlash(child.fullPath));
+          const subCount = countDescendants(child);
+          lines.push(
+            `${indent}${connector}${child.name}/ (${subCount} ${
+              subCount === 1 ? "item" : "items"
+            }, drill in)`,
+          );
+        } else {
+          lines.push(`${indent}${connector}${child.name}/`);
+          render(child, indent + childIndent, currentDepth + 1);
+        }
+      } else {
+        lines.push(`${indent}${connector}${child.name}`);
+      }
+    }
+
+    if (overflow > 0) {
+      lines.push(`${indent}└── ... (+${overflow} more)`);
+    }
+  };
+
+  render(root, "", 0);
+
+  return {
+    tree: lines.join("\n"),
+    total_items: totalItems,
+    truncated_dirs: truncatedDirs,
+    hint: buildHint({ truncatedDirs, depthLimitedDirs, totalItems }),
+  };
+}
+
 const inputSchema = z.object({
   path: z
     .string()
@@ -48,21 +228,6 @@ const outputSchema = z.object({
   hint: z.string(),
 });
 
-interface DirNode {
-  name: string;
-  fullPath: string;
-  isDir: true;
-  children: TreeEntry[];
-}
-
-interface FileNode {
-  name: string;
-  fullPath: string;
-  isDir: false;
-}
-
-type TreeEntry = DirNode | FileNode;
-
 export const contextTreeTool = {
   name: "context_tree",
   description:
@@ -71,163 +236,12 @@ export const contextTreeTool = {
   inputSchema,
   outputSchema,
   execute: async (input, ctx) => {
-    const path = input.path ?? "/";
-    const maxDepth = input.max_depth ?? DEFAULT_MAX_DEPTH;
-    const itemsPerDir = input.items_per_dir ?? DEFAULT_ITEMS_PER_DIR;
-    const normalizedPath = path.endsWith("/") ? path : `${path}/`;
-
-    const totalItems = await countContextItemsByPrefix(ctx.conn, path, {
-      recursive: true,
-    });
-
-    if (totalItems === 0) {
-      return {
-        tree: `${path}\n  (empty)`,
-        is_error: false,
-        total_items: 0,
-        truncated_dirs: [],
-        hint: "Directory is empty.",
-      };
-    }
-
-    const items = await listContextItemsByPrefix(ctx.conn, path, {
-      recursive: true,
-      limit: HARD_FETCH_CAP,
-    });
-
-    // Build tree structure: dirs map child name -> child node
-    const root: DirNode = {
-      name: path,
-      fullPath: path,
-      isDir: true,
-      children: [],
-    };
-    const dirIndex = new Map<string, DirNode>();
-    dirIndex.set(stripTrailingSlash(path), root);
-
-    for (const item of items) {
-      const relative = item.context_path.slice(normalizedPath.length);
-      if (relative.length === 0) continue; // root itself, skip
-      const parts = relative.split("/").filter((p) => p.length > 0);
-      const isExplicitDir = item.mime_type === "inode/directory";
-
-      // Walk segments, creating intermediate directories as needed
-      let parentDir = root;
-      let currentRel = "";
-      for (let i = 0; i < parts.length; i++) {
-        const segment = parts[i];
-        if (!segment) continue;
-        currentRel = currentRel ? `${currentRel}/${segment}` : segment;
-        const fullPath = `${normalizedPath}${currentRel}`;
-        const isLeaf = i === parts.length - 1;
-        const isDirHere = !isLeaf || isExplicitDir;
-
-        if (isDirHere) {
-          const key = stripTrailingSlash(fullPath);
-          let dir = dirIndex.get(key);
-          if (!dir) {
-            dir = {
-              name: segment,
-              fullPath,
-              isDir: true,
-              children: [],
-            };
-            dirIndex.set(key, dir);
-            parentDir.children.push(dir);
-          }
-          parentDir = dir;
-        } else {
-          parentDir.children.push({
-            name: segment,
-            fullPath,
-            isDir: false,
-          });
-        }
-      }
-    }
-
-    // Sort each directory's children: dirs first, then alphabetical
-    for (const dir of dirIndex.values()) {
-      dir.children.sort((a, b) => {
-        if (a.isDir !== b.isDir) return a.isDir ? -1 : 1;
-        return a.name.localeCompare(b.name);
-      });
-    }
-
-    const truncatedDirs: Array<{
-      path: string;
-      shown: number;
-      total: number;
-    }> = [];
-    const depthLimitedDirs: string[] = [];
-
-    const lines: string[] = [path];
-
-    const render = (
-      dir: DirNode,
-      indent: string,
-      currentDepth: number,
-    ): void => {
-      const children = dir.children;
-      const total = children.length;
-      const shown = Math.min(total, itemsPerDir);
-      const visible = children.slice(0, shown);
-      const overflow = total - shown;
-
-      if (overflow > 0) {
-        truncatedDirs.push({
-          path: stripTrailingSlash(dir.fullPath),
-          shown,
-          total,
-        });
-      }
-
-      for (let i = 0; i < visible.length; i++) {
-        const child = visible[i];
-        if (!child) continue;
-        const isLastVisible = i === visible.length - 1 && overflow === 0;
-        const connector = isLastVisible ? "└── " : "├── ";
-        const childIndent = isLastVisible ? "    " : "│   ";
-
-        if (child.isDir) {
-          const atDepthLimit = currentDepth + 1 >= maxDepth;
-          if (atDepthLimit && child.children.length > 0) {
-            depthLimitedDirs.push(stripTrailingSlash(child.fullPath));
-            const subCount = countDescendants(child);
-            lines.push(
-              `${indent}${connector}${child.name}/ (${subCount} ${
-                subCount === 1 ? "item" : "items"
-              }, drill in)`,
-            );
-          } else {
-            lines.push(`${indent}${connector}${child.name}/`);
-            render(child, indent + childIndent, currentDepth + 1);
-          }
-        } else {
-          lines.push(`${indent}${connector}${child.name}`);
-        }
-      }
-
-      if (overflow > 0) {
-        lines.push(`${indent}└── ... (+${overflow} more)`);
-      }
-    };
-
-    render(root, "", 0);
-
-    const hint = buildHint({
-      truncatedDirs,
-      depthLimitedDirs,
-      totalItems,
+    const result = await buildContextTree(ctx.conn, {
+      path: input.path,
+      maxDepth: input.max_depth,
+      itemsPerDir: input.items_per_dir,
     });
-
-    return {
-      tree: lines.join("\n"),
-      is_error: false,
-      total_items: totalItems,
-      truncated_dirs: truncatedDirs,
-      hint,
-    };
+    return { ...result, is_error: false };
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;
 

package/src/tools/file/write.ts

@@ -6,6 +6,7 @@ import {
   PathConflictError,
   upsertContextItem,
 } from "../../db/context.ts";
+import { buildContextTree } from "../dir/tree.ts";
 import type { ToolDefinition } from "../tool.ts";
 
 function mimeFromPath(path: string): string {
@@ -49,6 +50,12 @@ const outputSchema = z.object({
   error_type: z.string().optional(),
   message: z.string().optional(),
   next_action_hint: z.string().optional(),
+  tree: z
+    .string()
+    .optional()
+    .describe(
+      "Snapshot of the context filesystem after the write so you can see the surrounding files.",
+    ),
 });
 
 export const contextWriteTool = {
@@ -86,7 +93,13 @@ export const contextWriteTool = {
             });
 
       await ingestByPath(ctx.conn, input.path, ctx.config);
-      return { id: item.id, path: item.context_path, is_error: false };
+      const { tree } = await buildContextTree(ctx.conn);
+      return {
+        id: item.id,
+        path: item.context_path,
+        is_error: false,
+        tree,
+      };
     } catch (err) {
       if (err instanceof PathConflictError) {
         return {