botholomew 0.7.12 → 0.8.0

package/src/worker/index.ts

@@ -0,0 +1,200 @@
+import { hostname } from "node:os";
+import ansis from "ansis";
+import { loadConfig } from "../config/loader.ts";
+import { getDbPath } from "../constants.ts";
+import { withDb } from "../db/connection.ts";
+import { migrate } from "../db/schema.ts";
+import { uuidv7 } from "../db/uuid.ts";
+import { markWorkerStopped, registerWorker } from "../db/workers.ts";
+import { createMcpxClient } from "../mcpx/client.ts";
+import { logger } from "../utils/logger.ts";
+import { startHeartbeat, startReaper } from "./heartbeat.ts";
+import type { WorkerStreamCallbacks } from "./llm.ts";
+import { runSpecificTask, tick } from "./tick.ts";
+
+export type WorkerMode = "persist" | "once";
+
+export interface StartWorkerOptions {
+  /** When true, stream LLM tokens + tool calls to stdout for the CLI `run` command. */
+  foreground?: boolean;
+  /** 'once' (default): claim one task and exit. 'persist': run the tick loop forever. */
+  mode?: WorkerMode;
+  /**
+   * When mode='once', optionally pin this worker to a specific task id.
+   * When omitted, the worker claims the next eligible task from the queue.
+   */
+  taskId?: string;
+  /**
+   * Whether to evaluate schedules as part of this run.
+   * Defaults to `true` for one-shot workers without a taskId and for persist
+   * workers; `false` when a taskId is supplied (targeted work shouldn't fan
+   * out into unrelated schedule processing).
+   */
+  evalSchedules?: boolean;
+}
+
+function buildForegroundCallbacks(): WorkerStreamCallbacks {
+  return {
+    onTaskStart(task) {
+      process.stdout.write(
+        `\n${ansis.bold.blue(`Task: ${task.name}`)} ${ansis.dim(`(${task.id})`)}\n`,
+      );
+      if (task.description) {
+        process.stdout.write(`${ansis.dim(task.description)}\n`);
+      }
+      process.stdout.write("\n");
+    },
+    onToken(text) {
+      process.stdout.write(text);
+    },
+    onToolStart(name, input) {
+      process.stdout.write(
+        `  ${ansis.yellow("▶")} ${ansis.bold(name)} ${ansis.dim(input)}\n`,
+      );
+    },
+    onToolEnd(name, _output, isError, durationMs) {
+      const seconds = (durationMs / 1000).toFixed(1);
+      if (isError) {
+        process.stdout.write(
+          `  ${ansis.red("✗")} ${ansis.bold(name)} ${ansis.red("error")} ${ansis.dim(`(${seconds}s)`)}\n`,
+        );
+      } else {
+        process.stdout.write(
+          `  ${ansis.green("✓")} ${ansis.bold(name)} ${ansis.dim(`(${seconds}s)`)}\n`,
+        );
+      }
+    },
+  };
+}
+
+export async function startWorker(
+  projectDir: string,
+  options: StartWorkerOptions = {},
+): Promise<void> {
+  const mode: WorkerMode = options.mode ?? "once";
+  const { taskId } = options;
+  const evalSchedules = options.evalSchedules ?? !taskId;
+
+  const config = await loadConfig(projectDir);
+  const dbPath = getDbPath(projectDir);
+
+  // One short-lived connection to apply migrations, then release the lock.
+  await withDb(dbPath, (conn) => migrate(conn));
+
+  const mcpxClient = await createMcpxClient(projectDir);
+  if (mcpxClient) {
+    logger.info("MCPX client initialized with external tools");
+  }
+
+  const workerId = uuidv7();
+  await withDb(dbPath, (conn) =>
+    registerWorker(conn, {
+      id: workerId,
+      pid: process.pid,
+      hostname: hostname(),
+      mode,
+      taskId: taskId ?? null,
+    }),
+  );
+
+  const stopHeartbeat = startHeartbeat(
+    dbPath,
+    workerId,
+    config.worker_heartbeat_interval_seconds,
+  );
+  const stopReaper =
+    mode === "persist"
+      ? startReaper(
+          dbPath,
+          config.worker_reap_interval_seconds,
+          config.worker_dead_after_seconds,
+          config.worker_stopped_retention_seconds,
+        )
+      : () => {};
+
+  const shutdown = async () => {
+    logger.info("Worker shutting down...");
+    stopHeartbeat();
+    stopReaper();
+    await mcpxClient?.close();
+    try {
+      await withDb(dbPath, (conn) => markWorkerStopped(conn, workerId));
+    } catch (err) {
+      logger.warn(`failed to mark worker stopped: ${err}`);
+    }
+    process.exit(0);
+  };
+
+  process.on("SIGTERM", shutdown);
+  process.on("SIGINT", shutdown);
+
+  const callbacks = options.foreground ? buildForegroundCallbacks() : undefined;
+
+  logger.info(
+    `Worker ${workerId} started ${new Date().toISOString()} for ${projectDir} (PID ${process.pid}, mode=${mode})`,
+  );
+
+  try {
+    if (mode === "once") {
+      if (taskId) {
+        await runSpecificTask({
+          projectDir,
+          dbPath,
+          config,
+          workerId,
+          taskId,
+          mcpxClient,
+          callbacks,
+        });
+      } else {
+        await tick({
+          projectDir,
+          dbPath,
+          config,
+          workerId,
+          mcpxClient,
+          callbacks,
+          tickNum: 1,
+          evalSchedules,
+        });
+      }
+      return;
+    }
+
+    // persist mode: loop forever until SIGTERM/SIGINT flips us into shutdown()
+    logger.info(`Tick interval: ${config.tick_interval_seconds}s`);
+    let tickNum = 0;
+    while (true) {
+      tickNum++;
+      let didWork = false;
+      try {
+        didWork = await tick({
+          projectDir,
+          dbPath,
+          config,
+          workerId,
+          mcpxClient,
+          callbacks,
+          tickNum,
+          evalSchedules: true,
+        });
+      } catch (err) {
+        logger.error(`Tick failed: ${err}`);
+      }
+
+      if (!didWork) {
+        logger.phase("sleeping", `${config.tick_interval_seconds}s`);
+        await Bun.sleep(config.tick_interval_seconds * 1000);
+      }
+    }
+  } finally {
+    stopHeartbeat();
+    stopReaper();
+    try {
+      await withDb(dbPath, (conn) => markWorkerStopped(conn, workerId));
+    } catch (err) {
+      logger.warn(`failed to mark worker stopped: ${err}`);
+    }
+    await mcpxClient?.close();
+  }
+}

package/src/{daemon → worker}/llm.ts

@@ -17,7 +17,7 @@ import { createLlmClient } from "./llm-client.ts";
 
 registerAllTools();
 
-export interface DaemonStreamCallbacks {
+export interface WorkerStreamCallbacks {
   onToken: (text: string) => void;
   onToolStart: (name: string, input: string) => void;
   onToolEnd: (
@@ -48,7 +48,7 @@ export async function runAgentLoop(input: {
   threadId: string;
   projectDir: string;
   mcpxClient?: McpxClient | null;
-  callbacks?: DaemonStreamCallbacks;
+  callbacks?: WorkerStreamCallbacks;
 }): Promise<AgentLoopResult> {
   const {
     systemPrompt,
@@ -93,7 +93,7 @@ export async function runAgentLoop(input: {
   );
 
   clearLargeResults();
-  const daemonTools = toAnthropicTools();
+  const workerTools = toAnthropicTools();
   const maxInputTokens = await getMaxInputTokens(
     config.anthropic_api_key,
     config.model,
@@ -113,7 +113,7 @@ export async function runAgentLoop(input: {
         max_tokens: 4096,
         system: systemPrompt,
         messages,
-        tools: daemonTools,
+        tools: workerTools,
       });
 
       stream.on("text", (text) => {
@@ -133,7 +133,7 @@ export async function runAgentLoop(input: {
         max_tokens: 4096,
         system: systemPrompt,
         messages,
-        tools: daemonTools,
+        tools: workerTools,
       });
     }
 

package/src/{daemon → worker}/prompt.ts

@@ -16,7 +16,7 @@ const pkg = await Bun.file(
 /**
  * Extract keyword set from free-form text: lowercase, split on whitespace,
  * keep words longer than 3 chars. Used to match `loading: contextual` files
- * against the agent's current intent (task text for the daemon, latest user
+ * against the agent's current intent (task text for the worker, latest user
  * message for the chat).
  */
 export function extractKeywords(text: string): Set<string> {
@@ -134,7 +134,7 @@ export async function buildSystemPrompt(
   // Instructions
   parts.push("## Instructions");
   parts.push(
-    "You are Botholomew, a wise-owl daemon that works through tasks. Use available tools to complete your assigned task, then call complete_task, fail_task, or wait_task. Use create_task for subtasks and update_task to refine pending tasks. Batch independent tool calls in a single response for parallel execution.\n\nWhen calling complete_task, write a summary that captures your key findings, decisions, and outputs. This summary becomes the task's output and is provided to any downstream tasks that depend on this one. Include specific results (data, names, paths, conclusions) rather than vague descriptions of what you did — downstream tasks will rely on this information to do their work.",
+    "You are Botholomew, a wise-owl worker that works through tasks. Use available tools to complete your assigned task, then call complete_task, fail_task, or wait_task. Use create_task for subtasks and update_task to refine pending tasks. Batch independent tool calls in a single response for parallel execution.\n\nWhen calling complete_task, write a summary that captures your key findings, decisions, and outputs. This summary becomes the task's output and is provided to any downstream tasks that depend on this one. Include specific results (data, names, paths, conclusions) rather than vague descriptions of what you did — downstream tasks will rely on this information to do their work.",
   );
   if (options?.hasMcpTools) {
     parts.push("");

package/src/worker/run.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env bun
+
+// Standalone entry point for a worker when spawned as a detached process.
+// Usage: bun run src/worker/run.ts <projectDir> [--persist] [--task-id=<uuid>] [--no-eval-schedules]
+
+import { startWorker } from "./index.ts";
+
+const projectDir = process.argv[2];
+if (!projectDir) {
+  console.error(
+    "Usage: bun run src/worker/run.ts <projectDir> [--persist] [--task-id=<uuid>] [--no-eval-schedules]",
+  );
+  process.exit(1);
+}
+
+const args = process.argv.slice(3);
+const persist = args.includes("--persist");
+const noEvalSchedules = args.includes("--no-eval-schedules");
+const taskIdArg = args.find((a) => a.startsWith("--task-id="));
+const taskId = taskIdArg ? taskIdArg.slice("--task-id=".length) : undefined;
+
+await startWorker(projectDir, {
+  mode: persist ? "persist" : "once",
+  taskId,
+  evalSchedules: noEvalSchedules ? false : undefined,
+});

package/src/{daemon → worker}/schedules.ts

@@ -2,8 +2,10 @@ import Anthropic from "@anthropic-ai/sdk";
 import type { BotholomewConfig } from "../config/schemas.ts";
 import { withDb } from "../db/connection.ts";
 import {
+  claimSchedule,
   listSchedules,
   markScheduleRun,
+  releaseSchedule,
   type Schedule,
 } from "../db/schedules.ts";
 import { createTask } from "../db/tasks.ts";
@@ -107,16 +109,35 @@ Is this schedule due to run? If yes, what tasks should be created?`;
 export async function processSchedules(
   dbPath: string,
   config: Required<BotholomewConfig>,
+  workerId: string,
 ): Promise<void> {
   const schedules = await withDb(dbPath, (conn) =>
     listSchedules(conn, { enabled: true }),
   );
   if (schedules.length === 0) return;
 
+  logger.phase("evaluating-schedules", `${schedules.length} enabled`);
+
   for (const schedule of schedules) {
+    // Only one worker evaluates a schedule per window. claimSchedule is an
+    // atomic UPDATE ... RETURNING guarded by both a claim-stale window and
+    // a minimum-interval-since-last-run window; if it returns null, another
+    // worker already holds the claim or the schedule ran too recently.
+    const claimed = await withDb(dbPath, (conn) =>
+      claimSchedule(conn, schedule.id, workerId, {
+        staleAfterSeconds: config.schedule_claim_stale_seconds,
+        minIntervalSeconds: config.schedule_min_interval_seconds,
+      }),
+    );
+    if (!claimed) {
+      logger.debug(
+        `Schedule "${schedule.name}" skipped: claimed by another worker or too recent`,
+      );
+      continue;
+    }
+
     try {
-      // LLM evaluation does no DB work — no connection held here.
-      const evaluation = await evaluateSchedule(config, schedule);
+      const evaluation = await evaluateSchedule(config, claimed);
 
       if (!evaluation.isDue) {
         logger.debug(
@@ -148,6 +169,13 @@ export async function processSchedules(
       );
     } catch (err) {
       logger.error(`Error processing schedule "${schedule.name}": ${err}`);
+    } finally {
+      // Release the claim so other workers (or the next tick) can re-evaluate
+      // once the min-interval window has elapsed. markScheduleRun above
+      // updates last_run_at, which is the actual cooldown.
+      await withDb(dbPath, (conn) =>
+        releaseSchedule(conn, schedule.id, workerId),
+      );
     }
   }
 }

package/src/worker/spawn.ts

@@ -0,0 +1,48 @@
+import { join } from "node:path";
+import { getBotholomewDir, getLogPath } from "../constants.ts";
+import { logger } from "../utils/logger.ts";
+import type { WorkerMode } from "./index.ts";
+
+export interface SpawnWorkerOptions {
+  mode?: WorkerMode;
+  taskId?: string;
+}
+
+/**
+ * Spawn a worker as a detached background process. Unlike the old daemon
+ * model, multiple workers per project are allowed and expected — this just
+ * launches a new one.
+ */
+export async function spawnWorker(
+  projectDir: string,
+  options: SpawnWorkerOptions = {},
+): Promise<{ pid: number }> {
+  const dotDir = getBotholomewDir(projectDir);
+  const dirExists = await Bun.file(join(dotDir, "config.json")).exists();
+  if (!dirExists) {
+    logger.error("Project not initialized. Run 'botholomew init' first.");
+    process.exit(1);
+  }
+
+  const logPath = getLogPath(projectDir);
+  const logFile = Bun.file(logPath);
+
+  const workerScript = new URL("./run.ts", import.meta.url).pathname;
+  const args = ["bun", "run", workerScript, projectDir];
+  if (options.mode === "persist") args.push("--persist");
+  if (options.taskId) args.push(`--task-id=${options.taskId}`);
+
+  const proc = Bun.spawn(args, {
+    stdio: ["ignore", logFile, logFile],
+    env: { ...process.env },
+  });
+  proc.unref();
+
+  const mode = options.mode ?? "once";
+  logger.success(
+    `Worker spawned in background (PID ${proc.pid}, mode=${mode}${options.taskId ? `, task=${options.taskId}` : ""})`,
+  );
+  logger.dim(`  Log: ${logPath}`);
+
+  return { pid: proc.pid ?? 0 };
+}

package/src/{daemon → worker}/tick.ts

@@ -1,28 +1,48 @@
 import type { McpxClient } from "@evantahler/mcpx";
 import type { BotholomewConfig } from "../config/schemas.ts";
 import { withDb } from "../db/connection.ts";
-import { listSchedules } from "../db/schedules.ts";
 import {
   claimNextTask,
+  claimSpecificTask,
   resetStaleTasks,
+  type Task,
   updateTaskStatus,
 } from "../db/tasks.ts";
 import { createThread, endThread, logInteraction } from "../db/threads.ts";
 import { logger } from "../utils/logger.ts";
 import { generateThreadTitle } from "../utils/title.ts";
-import type { DaemonStreamCallbacks } from "./llm.ts";
+import type { WorkerStreamCallbacks } from "./llm.ts";
 import { runAgentLoop } from "./llm.ts";
 import { buildSystemPrompt } from "./prompt.ts";
 import { processSchedules } from "./schedules.ts";
 
-export async function tick(
-  projectDir: string,
-  dbPath: string,
-  config: Required<BotholomewConfig>,
-  mcpxClient?: McpxClient | null,
-  callbacks?: DaemonStreamCallbacks,
-  tickNum = 1,
-): Promise<boolean> {
+export interface TickOptions {
+  projectDir: string;
+  dbPath: string;
+  config: Required<BotholomewConfig>;
+  workerId: string;
+  mcpxClient?: McpxClient | null;
+  callbacks?: WorkerStreamCallbacks;
+  tickNum?: number;
+  evalSchedules?: boolean;
+}
+
+/**
+ * Run one unit of work for a worker: optionally evaluate schedules, claim
+ * the next eligible task, and process it. Returns true if work was done.
+ */
+export async function tick(opts: TickOptions): Promise<boolean> {
+  const {
+    projectDir,
+    dbPath,
+    config,
+    workerId,
+    mcpxClient,
+    callbacks,
+    tickNum = 1,
+    evalSchedules = true,
+  } = opts;
+
   const tickStart = Date.now();
   logger.phase("tick-start", `#${tickNum}`);
 
@@ -36,16 +56,9 @@ export async function tick(
     );
   }
 
-  // Process schedules (may create new tasks). Check enabled count so we only
-  // log the phase when there's work to evaluate — the call itself is a no-op
-  // otherwise.
-  const enabledSchedules = await withDb(dbPath, (conn) =>
-    listSchedules(conn, { enabled: true }),
-  );
-  if (enabledSchedules.length > 0) {
-    logger.phase("evaluating-schedules", `${enabledSchedules.length} enabled`);
+  if (evalSchedules) {
     try {
-      await processSchedules(dbPath, config);
+      await processSchedules(dbPath, config, workerId);
     } catch (err) {
       logger.error(`Schedule processing failed: ${err}`);
     }
@@ -53,7 +66,7 @@ export async function tick(
 
   // Claim a task
   logger.phase("claiming-task");
-  const task = await withDb(dbPath, (conn) => claimNextTask(conn));
+  const task = await withDb(dbPath, (conn) => claimNextTask(conn, workerId));
   if (!task) {
     logger.info("No task claimed (queue empty or all blocked)");
     const elapsed = ((Date.now() - tickStart) / 1000).toFixed(1);
@@ -61,23 +74,77 @@ export async function tick(
     return false;
   }
 
+  await runClaimedTask({
+    projectDir,
+    dbPath,
+    config,
+    mcpxClient,
+    callbacks,
+    task,
+  });
+
+  const elapsed = ((Date.now() - tickStart) / 1000).toFixed(1);
+  logger.phase("tick-end", `#${tickNum} ${elapsed}s didWork=true`);
+  return true;
+}
+
+/**
+ * Claim and run a single, explicitly-named task. Returns true if the task
+ * was claimed and processed, false if it wasn't eligible (already claimed,
+ * not pending, or doesn't exist).
+ */
+export async function runSpecificTask(opts: {
+  projectDir: string;
+  dbPath: string;
+  config: Required<BotholomewConfig>;
+  workerId: string;
+  taskId: string;
+  mcpxClient?: McpxClient | null;
+  callbacks?: WorkerStreamCallbacks;
+}): Promise<boolean> {
+  const task = await withDb(opts.dbPath, (conn) =>
+    claimSpecificTask(conn, opts.taskId, opts.workerId),
+  );
+  if (!task) {
+    logger.warn(
+      `Task ${opts.taskId} is not available (already claimed, not pending, or missing)`,
+    );
+    return false;
+  }
+  await runClaimedTask({
+    projectDir: opts.projectDir,
+    dbPath: opts.dbPath,
+    config: opts.config,
+    mcpxClient: opts.mcpxClient,
+    callbacks: opts.callbacks,
+    task,
+  });
+  return true;
+}
+
+async function runClaimedTask(opts: {
+  projectDir: string;
+  dbPath: string;
+  config: Required<BotholomewConfig>;
+  mcpxClient?: McpxClient | null;
+  callbacks?: WorkerStreamCallbacks;
+  task: Task;
+}): Promise<void> {
+  const { projectDir, dbPath, config, mcpxClient, callbacks, task } = opts;
+
   logger.info(`Claimed task: ${task.name} (${task.id})`);
   callbacks?.onTaskStart(task);
 
-  // Create a thread for this tick
   const threadId = await withDb(dbPath, (conn) =>
-    createThread(conn, "daemon_tick", task.id, `Working: ${task.name}`),
+    createThread(conn, "worker_tick", task.id, `Working: ${task.name}`),
   );
 
-  // Build system prompt (includes task-relevant context from embeddings)
   const systemPrompt = await buildSystemPrompt(
     projectDir,
     task,
     dbPath,
     config,
-    {
-      hasMcpTools: mcpxClient != null,
-    },
+    { hasMcpTools: mcpxClient != null },
   );
 
   try {
@@ -92,8 +159,6 @@ export async function tick(
       callbacks,
     });
 
-    // Update task status and store output. Only completed tasks have an
-    // `output`; waiting/failed tasks put their reason in `waiting_reason`.
     const isComplete = result.status === "complete";
     await withDb(dbPath, (conn) =>
       updateTaskStatus(
@@ -105,7 +170,6 @@ export async function tick(
       ),
     );
 
-    // Log the status change
     await withDb(dbPath, (conn) =>
       logInteraction(conn, threadId, {
         role: "system",
@@ -116,7 +180,6 @@ export async function tick(
 
     logger.info(`Task ${task.id} -> ${result.status}`);
 
-    // Generate a descriptive title for the thread (fire-and-forget)
     void generateThreadTitle(
       config,
       dbPath,
@@ -140,9 +203,4 @@ export async function tick(
   } finally {
     await withDb(dbPath, (conn) => endThread(conn, threadId));
   }
-
-  const elapsed = ((Date.now() - tickStart) / 1000).toFixed(1);
-  logger.phase("tick-end", `#${tickNum} ${elapsed}s didWork=true`);
-
-  return true;
 }