botholomew 0.7.8 → 0.7.9

package/README.md

@@ -128,6 +128,8 @@ Everything the agent can touch is here. No surprises.
 | `botholomew nuke context\|tasks\|schedules\|threads\|all` | Bulk-erase sections of the database |
 | `botholomew upgrade` | Self-update |
 
+All `list` subcommands support `-l, --limit <n>` and `-o, --offset <n>` for pagination.
+
 ---
 
 ## How it works

package/package.json

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

package/src/chat/agent.ts

@@ -4,6 +4,7 @@ import type {
   ToolResultBlockParam,
   ToolUseBlock,
 } from "@anthropic-ai/sdk/resources/messages";
+import type { McpxClient } from "@evantahler/mcpx";
 import type { BotholomewConfig } from "../config/schemas.ts";
 import { embedSingle } from "../context/embedder.ts";
 import { fitToContextWindow, getMaxInputTokens } from "../daemon/context.ts";
@@ -13,7 +14,7 @@ import {
   extractKeywords,
   loadPersistentContext,
 } from "../daemon/prompt.ts";
-import type { DbConnection } from "../db/connection.ts";
+import { withDb } from "../db/connection.ts";
 import { hybridSearch } from "../db/embeddings.ts";
 import { logInteraction } from "../db/threads.ts";
 import { registerAllTools } from "../tools/registry.ts";
@@ -60,7 +61,7 @@ export async function buildChatSystemPrompt(
   projectDir: string,
   options?: {
     keywordSource?: string;
-    conn?: DbConnection;
+    dbPath?: string;
     config?: Required<BotholomewConfig>;
   },
 ): Promise<string> {
@@ -74,12 +75,14 @@ export async function buildChatSystemPrompt(
   parts.push(...(await loadPersistentContext(projectDir, taskKeywords)));
 
   // Relevant context from embeddings search
-  const conn = options?.conn;
+  const dbPath = options?.dbPath;
   const config = options?.config;
-  if (conn && config?.openai_api_key && keywordSource) {
+  if (dbPath && config?.openai_api_key && keywordSource) {
     try {
       const queryVec = await embedSingle(keywordSource, config);
-      const results = await hybridSearch(conn, keywordSource, queryVec, 5);
+      const results = await withDb(dbPath, (conn) =>
+        hybridSearch(conn, keywordSource, queryVec, 5),
+      );
 
       if (results.length > 0) {
         parts.push("## Relevant Context");
@@ -160,13 +163,20 @@ export async function runChatTurn(input: {
   messages: MessageParam[];
   projectDir: string;
   config: Required<BotholomewConfig>;
-  conn: DbConnection;
+  dbPath: string;
   threadId: string;
-  toolCtx: ToolContext;
+  mcpxClient: McpxClient | null;
   callbacks: ChatTurnCallbacks;
 }): Promise<void> {
-  const { messages, projectDir, config, conn, threadId, toolCtx, callbacks } =
-    input;
+  const {
+    messages,
+    projectDir,
+    config,
+    dbPath,
+    threadId,
+    mcpxClient,
+    callbacks,
+  } = input;
 
   const client = new Anthropic({
     apiKey: config.anthropic_api_key || undefined,
@@ -190,7 +200,7 @@ export async function runChatTurn(input: {
     const keywordSource = findLastUserText(messages);
     const systemPrompt = await buildChatSystemPrompt(projectDir, {
       keywordSource,
-      conn,
+      dbPath,
       config,
     });
 
@@ -230,13 +240,15 @@ export async function runChatTurn(input: {
 
     // Log assistant text
     if (assistantText) {
-      await logInteraction(conn, threadId, {
-        role: "assistant",
-        kind: "message",
-        content: assistantText,
-        durationMs,
-        tokenCount,
-      });
+      await withDb(dbPath, (conn) =>
+        logInteraction(conn, threadId, {
+          role: "assistant",
+          kind: "message",
+          content: assistantText,
+          durationMs,
+          tokenCount,
+        }),
+      );
     }
 
     // Check for tool calls
@@ -260,20 +272,29 @@ export async function runChatTurn(input: {
         callbacks.onToolStart(toolUse.id, toolUse.name, toolInput);
       }
 
-      await logInteraction(conn, threadId, {
-        role: "assistant",
-        kind: "tool_use",
-        content: `Calling ${toolUse.name}`,
-        toolName: toolUse.name,
-        toolInput,
-      });
+      await withDb(dbPath, (conn) =>
+        logInteraction(conn, threadId, {
+          role: "assistant",
+          kind: "tool_use",
+          content: `Calling ${toolUse.name}`,
+          toolName: toolUse.name,
+          toolInput,
+        }),
+      );
     }
 
-    // Execute all tools in parallel
+    // Execute all tools in parallel. Each tool call opens its own short-lived
+    // connection; parallel calls share the process-local DuckDB instance and
+    // release the file lock as soon as the last one finishes.
     const execResults = await Promise.all(
       toolUseBlocks.map(async (toolUse) => {
         const start = Date.now();
-        const result = await executeChatToolCall(toolUse, toolCtx);
+        const result = await executeChatToolCall(toolUse, {
+          dbPath,
+          projectDir,
+          config,
+          mcpxClient,
+        });
         const durationMs = Date.now() - start;
         const stored = maybeStoreResult(toolUse.name, result.output);
         const meta: ToolEndMeta | undefined = stored.stored
@@ -293,13 +314,15 @@ export async function runChatTurn(input: {
     // Log results and collect tool_result messages
     const toolResults: ToolResultBlockParam[] = [];
     for (const { toolUse, result, durationMs, stored } of execResults) {
-      await logInteraction(conn, threadId, {
-        role: "tool",
-        kind: "tool_result",
-        content: result.output,
-        toolName: toolUse.name,
-        durationMs,
-      });
+      await withDb(dbPath, (conn) =>
+        logInteraction(conn, threadId, {
+          role: "tool",
+          kind: "tool_result",
+          content: result.output,
+          toolName: toolUse.name,
+          durationMs,
+        }),
+      );
 
       toolResults.push({
         type: "tool_result",
@@ -314,9 +337,16 @@ export async function runChatTurn(input: {
   }
 }
 
+interface ChatToolCallCtx {
+  dbPath: string;
+  projectDir: string;
+  config: Required<BotholomewConfig>;
+  mcpxClient: McpxClient | null;
+}
+
 async function executeChatToolCall(
   toolUse: ToolUseBlock,
-  ctx: ToolContext,
+  baseCtx: ChatToolCallCtx,
 ): Promise<{ output: string; isError: boolean }> {
   const tool = getTool(toolUse.name);
   if (!tool) return { output: `Unknown tool: ${toolUse.name}`, isError: true };
@@ -335,7 +365,10 @@ async function executeChatToolCall(
   }
 
   try {
-    const result = await tool.execute(parsed.data, ctx);
+    const result = await withDb(baseCtx.dbPath, (conn) => {
+      const ctx: ToolContext = { ...baseCtx, conn };
+      return tool.execute(parsed.data, ctx);
+    });
     const isError =
       typeof result === "object" && result !== null && "is_error" in result
         ? (result as { is_error: boolean }).is_error

package/src/chat/session.ts

@@ -2,8 +2,7 @@ import type { MessageParam } from "@anthropic-ai/sdk/resources/messages";
 import { loadConfig } from "../config/loader.ts";
 import type { BotholomewConfig } from "../config/schemas.ts";
 import { getDbPath } from "../constants.ts";
-import type { DbConnection } from "../db/connection.ts";
-import { getConnection } from "../db/connection.ts";
+import { withDb } from "../db/connection.ts";
 import { migrate } from "../db/schema.ts";
 import {
   createThread,
@@ -15,18 +14,18 @@ import {
 import { createMcpxClient } from "../mcpx/client.ts";
 import { loadSkills } from "../skills/loader.ts";
 import type { SkillDefinition } from "../skills/parser.ts";
-import type { ToolContext } from "../tools/tool.ts";
 import { generateThreadTitle } from "../utils/title.ts";
 import { type ChatTurnCallbacks, runChatTurn } from "./agent.ts";
 
 export interface ChatSession {
-  conn: DbConnection;
+  dbPath: string;
   threadId: string;
   projectDir: string;
   config: Required<BotholomewConfig>;
   messages: MessageParam[];
-  toolCtx: ToolContext;
   skills: Map<string, SkillDefinition>;
+  // biome-ignore lint/suspicious/noExplicitAny: mcpx client
+  mcpxClient: any;
   cleanup: () => Promise<void>;
 }
 
@@ -42,21 +41,22 @@ export async function startChatSession(
     );
   }
 
-  const conn = await getConnection(getDbPath(projectDir));
-  await migrate(conn);
+  const dbPath = getDbPath(projectDir);
+  await withDb(dbPath, (conn) => migrate(conn));
 
   let threadId: string;
   const messages: MessageParam[] = [];
 
   if (existingThreadId) {
     // Resume existing thread
-    const result = await getThread(conn, existingThreadId);
+    const result = await withDb(dbPath, (conn) =>
+      getThread(conn, existingThreadId),
+    );
     if (!result) {
-      conn.close();
       throw new Error(`Thread not found: ${existingThreadId}`);
     }
     threadId = existingThreadId;
-    await reopenThread(conn, threadId);
+    await withDb(dbPath, (conn) => reopenThread(conn, threadId));
 
     // Rebuild message history from interactions
     let firstUserMessage: string | undefined;
@@ -72,34 +72,29 @@ export async function startChatSession(
 
     // Backfill title for threads that still have the default
     if (result.thread.title === "New chat" && firstUserMessage) {
-      void generateThreadTitle(config, conn, threadId, firstUserMessage);
+      void generateThreadTitle(config, dbPath, threadId, firstUserMessage);
     }
   } else {
-    threadId = await createThread(conn, "chat_session", undefined, "New chat");
+    threadId = await withDb(dbPath, (conn) =>
+      createThread(conn, "chat_session", undefined, "New chat"),
+    );
   }
 
   const mcpxClient = await createMcpxClient(projectDir);
   const skills = await loadSkills(projectDir);
 
-  const toolCtx: ToolContext = {
-    conn,
-    projectDir,
-    config,
-    mcpxClient,
-  };
-
   const cleanup = async () => {
     await mcpxClient?.close();
   };
 
   return {
-    conn,
+    dbPath,
     threadId,
     projectDir,
     config,
     messages,
-    toolCtx,
     skills,
+    mcpxClient,
     cleanup,
   };
 }
@@ -110,11 +105,13 @@ export async function sendMessage(
   callbacks: ChatTurnCallbacks,
 ): Promise<void> {
   // Log and append user message
-  await logInteraction(session.conn, session.threadId, {
-    role: "user",
-    kind: "message",
-    content: userMessage,
-  });
+  await withDb(session.dbPath, (conn) =>
+    logInteraction(conn, session.threadId, {
+      role: "user",
+      kind: "message",
+      content: userMessage,
+    }),
+  );
 
   session.messages.push({ role: "user", content: userMessage });
 
@@ -122,7 +119,7 @@ export async function sendMessage(
   if (session.messages.length === 1) {
     void generateThreadTitle(
       session.config,
-      session.conn,
+      session.dbPath,
       session.threadId,
       userMessage,
     );
@@ -132,15 +129,14 @@ export async function sendMessage(
     messages: session.messages,
     projectDir: session.projectDir,
     config: session.config,
-    conn: session.conn,
+    dbPath: session.dbPath,
     threadId: session.threadId,
-    toolCtx: session.toolCtx,
+    mcpxClient: session.mcpxClient,
     callbacks,
   });
 }
 
 export async function endChatSession(session: ChatSession): Promise<void> {
-  await endThread(session.conn, session.threadId);
+  await withDb(session.dbPath, (conn) => endThread(conn, session.threadId));
   await session.cleanup();
-  session.conn.close();
 }

package/src/commands/daemon.ts

@@ -109,7 +109,9 @@ export function registerDaemonCommand(program: Command) {
   daemon
     .command("list")
     .description("List all registered Botholomew projects on this machine")
-    .action(async () => {
+    .option("-l, --limit <n>", "max number of projects", Number.parseInt)
+    .option("-o, --offset <n>", "skip first N projects", Number.parseInt)
+    .action(async (opts: { limit?: number; offset?: number }) => {
       const { listAllWatchdogProjects } = await import("../daemon/watchdog.ts");
       try {
         const projects = await listAllWatchdogProjects();
@@ -117,10 +119,21 @@ export function registerDaemonCommand(program: Command) {
           logger.dim("No registered projects found.");
           return;
         }
-        for (const p of projects) {
+        const total = projects.length;
+        const start = opts.offset ?? 0;
+        const end = opts.limit ? start + opts.limit : undefined;
+        const page = projects.slice(start, end);
+        if (page.length === 0) {
+          logger.dim(`No projects on this page (total: ${total}).`);
+          return;
+        }
+        for (const p of page) {
           logger.info(p.projectDir);
           logger.dim(`  Config: ${p.configPath}`);
         }
+        if (page.length !== total) {
+          logger.dim(`\nshowing ${page.length} of ${total} project(s)`);
+        }
       } catch (err) {
         logger.error(
           `Failed to list projects: ${err instanceof Error ? err.message : err}`,

package/src/commands/schedule.ts

@@ -19,9 +19,18 @@ export function registerScheduleCommand(program: Command) {
     .description("List all schedules")
     .option("--enabled", "show only enabled schedules")
     .option("--disabled", "show only disabled schedules")
+    .option("-l, --limit <n>", "max number of schedules", Number.parseInt)
+    .option("-o, --offset <n>", "skip first N schedules", Number.parseInt)
     .action((opts) =>
       withDb(program, async (conn) => {
-        const filters: { enabled?: boolean } = {};
+        const filters: {
+          enabled?: boolean;
+          limit?: number;
+          offset?: number;
+        } = {
+          limit: opts.limit,
+          offset: opts.offset,
+        };
         if (opts.enabled) filters.enabled = true;
         if (opts.disabled) filters.enabled = false;
 

package/src/commands/skill.ts

@@ -27,7 +27,9 @@ export function registerSkillCommand(program: Command) {
   skill
     .command("list")
     .description("List all skills loaded from .botholomew/skills/")
-    .action(async () => {
+    .option("-l, --limit <n>", "max number of skills", Number.parseInt)
+    .option("-o, --offset <n>", "skip first N skills", Number.parseInt)
+    .action(async (opts: { limit?: number; offset?: number }) => {
       const dir = program.opts().dir;
       const skills = await loadSkills(dir);
 
@@ -39,12 +41,21 @@ export function registerSkillCommand(program: Command) {
       const sorted = [...skills.values()].sort((a, b) =>
         a.name.localeCompare(b.name),
       );
+      const total = sorted.length;
+      const start = opts.offset ?? 0;
+      const end = opts.limit ? start + opts.limit : undefined;
+      const page = sorted.slice(start, end);
+
+      if (page.length === 0) {
+        logger.dim(`No skills on this page (total: ${total}).`);
+        return;
+      }
 
       const header = `${ansis.bold("Name".padEnd(20))} ${ansis.bold("Description".padEnd(40))} ${ansis.bold("Args".padEnd(20))} ${ansis.bold("Path")}`;
       console.log(header);
       console.log("-".repeat(header.length));
 
-      for (const s of sorted) {
+      for (const s of page) {
         const name = s.name.padEnd(20);
         const desc = s.description
           ? s.description.slice(0, 39).padEnd(40)
@@ -61,7 +72,11 @@ export function registerSkillCommand(program: Command) {
         console.log(`${name} ${desc} ${args} ${path}`);
       }
 
-      console.log(`\n${ansis.dim(`${sorted.length} skill(s)`)}`);
+      const footer =
+        page.length === total
+          ? `${total} skill(s)`
+          : `showing ${page.length} of ${total} skill(s)`;
+      console.log(`\n${ansis.dim(footer)}`);
     });
 
   skill

package/src/commands/task.ts

@@ -17,16 +17,18 @@ export function registerTaskCommand(program: Command) {
 
   task
     .command("list")
-    .description("List all tasks")
+    .description("List all tasks (newest first)")
     .option("-s, --status <status>", "filter by status")
     .option("-p, --priority <priority>", "filter by priority")
-    .option("-l, --limit <n>", "max number of tasks", parseInt)
+    .option("-l, --limit <n>", "max number of tasks", Number.parseInt)
+    .option("-o, --offset <n>", "skip first N tasks", Number.parseInt)
     .action((opts) =>
       withDb(program, async (conn) => {
         const tasks = await listTasks(conn, {
           status: opts.status,
           priority: opts.priority,
           limit: opts.limit,
+          offset: opts.offset,
         });
 
         if (tasks.length === 0) {
@@ -34,9 +36,15 @@ export function registerTaskCommand(program: Command) {
           return;
         }
 
+        const header = `${ansis.bold("ID".padEnd(36))}  ${ansis.bold("Status".padEnd(11))}  ${ansis.bold("Priority".padEnd(6))}  ${ansis.bold("Created".padEnd(19))}  ${ansis.bold("Updated".padEnd(19))}  ${ansis.bold("Name")}`;
+        console.log(header);
+        console.log("-".repeat(120));
+
         for (const t of tasks) {
           printTask(t);
         }
+
+        console.log(`\n${ansis.dim(`${tasks.length} task(s)`)}`);
       }),
     );
 
@@ -154,10 +162,26 @@ function priorityColor(priority: Task["priority"]): string {
   }
 }
 
+function formatTime(date: Date): string {
+  return date
+    .toISOString()
+    .replace("T", " ")
+    .replace(/\.\d{3}Z$/, "");
+}
+
+function padColored(colored: string, raw: string, width: number): string {
+  const padding = Math.max(0, width - raw.length);
+  return colored + " ".repeat(padding);
+}
+
 function printTask(t: Task) {
-  const id = ansis.dim(t.id);
+  const id = ansis.dim(t.id.padEnd(36));
+  const status = padColored(statusColor(t.status), t.status, 11);
+  const priority = padColored(priorityColor(t.priority), t.priority, 6);
+  const created = ansis.dim(formatTime(t.created_at).padEnd(19));
+  const updated = ansis.dim(formatTime(t.updated_at).padEnd(19));
   console.log(
-    `  ${id}  ${statusColor(t.status)}  ${priorityColor(t.priority)}  ${t.name}`,
+    `${id}  ${status}  ${priority}  ${created}  ${updated}  ${t.name}`,
   );
 }
 

package/src/commands/thread.ts

@@ -19,12 +19,14 @@ export function registerThreadCommand(program: Command) {
     .command("list")
     .description("List threads")
     .option("-t, --type <type>", "filter by type (daemon_tick, chat_session)")
-    .option("-l, --limit <n>", "max number of threads", parseInt)
+    .option("-l, --limit <n>", "max number of threads", Number.parseInt)
+    .option("-o, --offset <n>", "skip first N threads", Number.parseInt)
     .action((opts) =>
       withDb(program, async (conn) => {
         const threads = await listThreads(conn, {
           type: opts.type,
           limit: opts.limit,
+          offset: opts.offset,
         });
 
         if (threads.length === 0) {

package/src/commands/tools.ts

@@ -2,6 +2,7 @@ import ansis from "ansis";
 import type { Command } from "commander";
 import { z } from "zod";
 import { loadConfig } from "../config/loader.ts";
+import { getDbPath } from "../constants.ts";
 import { registerAllTools } from "../tools/registry.ts";
 import {
   type AnyToolDefinition,
@@ -112,6 +113,7 @@ function registerToolAsCLI(parent: Command, tool: AnyToolDefinition) {
 
         const ctx: ToolContext = {
           conn,
+          dbPath: getDbPath(dir),
           projectDir: dir,
           config: await loadConfig(dir),
           mcpxClient: null,

package/src/commands/with-db.ts

@@ -1,23 +1,22 @@
 import type { Command } from "commander";
 import { getDbPath } from "../constants.ts";
 import type { DbConnection } from "../db/connection.ts";
-import { getConnection } from "../db/connection.ts";
+import { withDb as coreWithDb } from "../db/connection.ts";
 import { migrate } from "../db/schema.ts";
 
 /**
  * Open a migrated DB connection from the CLI --dir flag, run the callback,
- * and guarantee the connection is closed afterward.
+ * and guarantee the connection is closed afterward. Retries on lock
+ * conflicts so CLI invocations cooperate with a running daemon/chat.
  */
 export async function withDb<T>(
   program: Command,
   fn: (conn: DbConnection, dir: string) => Promise<T>,
 ): Promise<T> {
   const dir = program.opts().dir;
-  const conn = await getConnection(getDbPath(dir));
-  await migrate(conn);
-  try {
-    return await fn(conn, dir);
-  } finally {
-    conn.close();
-  }
+  const dbPath = getDbPath(dir);
+  return coreWithDb(dbPath, async (conn) => {
+    await migrate(conn);
+    return fn(conn, dir);
+  });
 }

package/src/context/fetcher.ts

@@ -161,6 +161,7 @@ async function runFetcherLoop(
 
   const toolCtx: ToolContext = {
     conn: null as unknown as DbConnection,
+    dbPath: "",
     projectDir: "",
     config,
     mcpxClient,

package/src/context/ingest.ts

@@ -79,7 +79,9 @@ export interface IngestionResult {
 
 /**
  * Store a prepared ingestion into the database.
- * This is the fast DB-write phase and must be called sequentially.
+ * All statements in BEGIN/COMMIT/ROLLBACK must share one connection, so the
+ * caller must pass a connection that lives long enough for the transaction
+ * (the tool executor wraps each tool call in `withDb`, which satisfies this).
  */
 export async function storeIngestion(
   conn: DbConnection,

package/src/daemon/index.ts

@@ -1,7 +1,7 @@
 import ansis from "ansis";
 import { loadConfig } from "../config/loader.ts";
 import { getDbPath } from "../constants.ts";
-import { getConnection } from "../db/connection.ts";
+import { withDb } from "../db/connection.ts";
 import { migrate } from "../db/schema.ts";
 import { createMcpxClient } from "../mcpx/client.ts";
 import { logger } from "../utils/logger.ts";
@@ -49,8 +49,10 @@ export async function startDaemon(
 ): Promise<void> {
   const config = await loadConfig(projectDir);
   const dbPath = getDbPath(projectDir);
-  const conn = await getConnection(dbPath);
-  await migrate(conn);
+
+  // One short-lived connection to apply migrations. After this returns,
+  // the file lock is released so CLI invocations can run freely.
+  await withDb(dbPath, (conn) => migrate(conn));
 
   // Initialize MCPX client for external tool access
   const mcpxClient = await createMcpxClient(projectDir);
@@ -64,7 +66,6 @@ export async function startDaemon(
     logger.info("Daemon shutting down...");
     await mcpxClient?.close();
     await removePidFile(projectDir);
-    conn.close();
     process.exit(0);
   };
 
@@ -87,7 +88,7 @@ export async function startDaemon(
     try {
       didWork = await tick(
         projectDir,
-        conn,
+        dbPath,
         config,
         mcpxClient,
         callbacks,