botholomew 0.7.13 → 0.8.0

package/src/config/schemas.ts

@@ -9,6 +9,12 @@ export interface BotholomewConfig {
   max_tick_duration_seconds?: number;
   system_prompt_override?: string;
   max_turns?: number;
+  worker_heartbeat_interval_seconds?: number;
+  worker_dead_after_seconds?: number;
+  worker_reap_interval_seconds?: number;
+  worker_stopped_retention_seconds?: number;
+  schedule_min_interval_seconds?: number;
+  schedule_claim_stale_seconds?: number;
 }
 
 export const DEFAULT_CONFIG: Required<BotholomewConfig> = {
@@ -22,4 +28,10 @@ export const DEFAULT_CONFIG: Required<BotholomewConfig> = {
   max_tick_duration_seconds: 120,
   system_prompt_override: "",
   max_turns: 0,
+  worker_heartbeat_interval_seconds: 15,
+  worker_dead_after_seconds: 60,
+  worker_reap_interval_seconds: 30,
+  worker_stopped_retention_seconds: 3600,
+  schedule_min_interval_seconds: 60,
+  schedule_claim_stale_seconds: 300,
 };

package/src/constants.ts

@@ -13,19 +13,14 @@ export const DEFAULTS = {
   UPDATE_CHECK_TIMEOUT_MS: 5_000,
 } as const;
 export const DB_FILENAME = "data.duckdb";
-export const PID_FILENAME = "daemon.pid";
-export const LOG_FILENAME = "daemon.log";
+export const LOG_FILENAME = "worker.log";
 export const CONFIG_FILENAME = "config.json";
 export const MCPX_DIR = "mcpx";
 export const SKILLS_DIR = "skills";
 export const MCPX_SERVERS_FILENAME = "servers.json";
 export const EMBEDDING_DIMENSION = 1536;
 export const EMBEDDING_MODEL = "text-embedding-3-small";
-
-export const LAUNCHD_LABEL_PREFIX = "com.botholomew.";
-export const SYSTEMD_UNIT_PREFIX = "botholomew-";
 export const LOG_MAX_BYTES = 10 * 1024 * 1024; // 10 MB
-export const WATCHDOG_LOG_FILENAME = "watchdog.log";
 
 export function getBotholomewDir(projectDir: string): string {
   return join(projectDir, BOTHOLOMEW_DIR);
@@ -35,10 +30,6 @@ export function getDbPath(projectDir: string): string {
   return join(projectDir, BOTHOLOMEW_DIR, DB_FILENAME);
 }
 
-export function getPidPath(projectDir: string): string {
-  return join(projectDir, BOTHOLOMEW_DIR, PID_FILENAME);
-}
-
 export function getLogPath(projectDir: string): string {
   return join(projectDir, BOTHOLOMEW_DIR, LOG_FILENAME);
 }
@@ -54,20 +45,3 @@ export function getMcpxDir(projectDir: string): string {
 export function getSkillsDir(projectDir: string): string {
   return join(projectDir, BOTHOLOMEW_DIR, SKILLS_DIR);
 }
-
-export function getWatchdogLogPath(projectDir: string): string {
-  return join(projectDir, BOTHOLOMEW_DIR, WATCHDOG_LOG_FILENAME);
-}
-
-/**
- * Convert an absolute directory path into a service-name-safe string.
- * e.g. "/Users/evan/myproject" → "users-evan-myproject"
- */
-export function sanitizePathForServiceName(projectDir: string): string {
-  return projectDir
-    .toLowerCase()
-    .replace(/[/\\:]+/g, "-")
-    .replace(/^-+/, "")
-    .replace(/-+$/, "")
-    .replace(/-+/g, "-");
-}

package/src/db/schedules.ts

@@ -9,6 +9,8 @@ export interface Schedule {
   frequency: string;
   last_run_at: Date | null;
   enabled: boolean;
+  claimed_by: string | null;
+  claimed_at: Date | null;
   created_at: Date;
   updated_at: Date;
 }
@@ -20,6 +22,8 @@ interface ScheduleRow {
   frequency: string;
   last_run_at: string | null;
   enabled: boolean;
+  claimed_by: string | null;
+  claimed_at: string | null;
   created_at: string;
   updated_at: string;
 }
@@ -32,6 +36,8 @@ function rowToSchedule(row: ScheduleRow): Schedule {
     frequency: row.frequency,
     last_run_at: row.last_run_at ? new Date(row.last_run_at) : null,
     enabled: !!row.enabled,
+    claimed_by: row.claimed_by ?? null,
+    claimed_at: row.claimed_at ? new Date(row.claimed_at) : null,
     created_at: new Date(row.created_at),
     updated_at: new Date(row.updated_at),
   };
@@ -145,3 +151,63 @@ export async function markScheduleRun(
     id,
   );
 }
+
+/**
+ * Atomically claim a schedule for evaluation. Returns the schedule if
+ * successfully claimed, or null if another worker already holds the claim
+ * or the schedule ran too recently to re-evaluate.
+ *
+ * `staleAfterSeconds`: how long an existing claim is considered still-held
+ * before another worker may steal it (protects against crashed claimers).
+ * `minIntervalSeconds`: minimum gap since `last_run_at` before re-evaluation.
+ */
+export async function claimSchedule(
+  db: DbConnection,
+  id: string,
+  claimedBy: string,
+  opts: { staleAfterSeconds: number; minIntervalSeconds: number },
+): Promise<Schedule | null> {
+  const row = await db.queryGet<ScheduleRow>(
+    `UPDATE schedules
+     SET claimed_by = ?1,
+         claimed_at = current_timestamp::VARCHAR
+     WHERE id = ?2
+       AND enabled = true
+       AND (
+         claimed_by IS NULL
+         OR claimed_at IS NULL
+         OR claimed_at::TIMESTAMP
+            < current_timestamp - to_seconds(CAST(?3 AS BIGINT))
+       )
+       AND (
+         last_run_at IS NULL
+         OR last_run_at::TIMESTAMP
+            < current_timestamp - to_seconds(CAST(?4 AS BIGINT))
+       )
+     RETURNING *`,
+    claimedBy,
+    id,
+    opts.staleAfterSeconds,
+    opts.minIntervalSeconds,
+  );
+  return row ? rowToSchedule(row) : null;
+}
+
+/**
+ * Release a schedule claim without modifying `last_run_at`. Safe to call
+ * even if the claim has already expired — the WHERE guard ensures we only
+ * clear our own claim.
+ */
+export async function releaseSchedule(
+  db: DbConnection,
+  id: string,
+  claimedBy: string,
+): Promise<void> {
+  await db.queryRun(
+    `UPDATE schedules
+     SET claimed_by = NULL, claimed_at = NULL
+     WHERE id = ?1 AND claimed_by = ?2`,
+    id,
+    claimedBy,
+  );
+}

package/src/db/schema.ts

@@ -11,11 +11,9 @@ interface Migration {
 const sqlDir = join(import.meta.dir, "sql");
 
 function loadMigrations(): Migration[] {
-  const files = readdirSync(sqlDir)
-    .filter((f) => f.endsWith(".sql"))
-    .sort();
+  const files = readdirSync(sqlDir).filter((f) => f.endsWith(".sql"));
 
-  return files.map((file) => {
+  const migrations = files.map((file) => {
     const match = file.match(/^(\d+)-(.+)\.sql$/);
     if (!match) throw new Error(`Invalid migration filename: ${file}`);
     const id = match[1];
@@ -27,6 +25,9 @@ function loadMigrations(): Migration[] {
       sql: readFileSync(join(sqlDir, file), "utf-8"),
     };
   });
+
+  // Sort by numeric id so `12-` runs after `2-`, not between `11-` and `2-`.
+  return migrations.sort((a, b) => a.id - b.id);
 }
 
 export async function migrate(db: DbConnection): Promise<void> {

package/src/db/sql/12-workers.sql

@@ -0,0 +1,66 @@
+-- Worker agents: replaces the PID-file + OS-watchdog single-daemon model
+-- with multiple in-DB registered workers that heartbeat and can be reaped.
+
+CREATE TABLE workers (
+  id TEXT PRIMARY KEY,
+  pid INTEGER NOT NULL,
+  hostname TEXT NOT NULL,
+  mode TEXT NOT NULL CHECK(mode IN ('persist', 'once')),
+  task_id TEXT,
+  status TEXT NOT NULL CHECK(status IN ('running', 'stopped', 'dead')),
+  started_at TEXT NOT NULL DEFAULT (current_timestamp::VARCHAR),
+  last_heartbeat_at TEXT NOT NULL DEFAULT (current_timestamp::VARCHAR),
+  stopped_at TEXT
+);
+
+CREATE INDEX idx_workers_status_heartbeat ON workers(status, last_heartbeat_at);
+
+-- Schedule claim columns: only one worker evaluates a schedule per window.
+ALTER TABLE schedules ADD COLUMN claimed_by TEXT;
+ALTER TABLE schedules ADD COLUMN claimed_at TEXT;
+
+-- Rewrite threads.type values: daemon_tick → worker_tick. The existing
+-- CHECK constraint forbids the new value, so we rebuild both threads and
+-- interactions (whose FK to threads would block a DROP). Dropping the FK
+-- follows the 7-drop_embeddings_fk.sql precedent.
+CREATE TABLE threads_backup AS SELECT * FROM threads;
+CREATE TABLE interactions_backup AS SELECT * FROM interactions;
+
+DROP TABLE interactions;
+DROP TABLE threads;
+
+CREATE TABLE threads (
+  id TEXT PRIMARY KEY,
+  type TEXT NOT NULL CHECK(type IN ('worker_tick', 'chat_session')),
+  task_id TEXT,
+  title TEXT NOT NULL DEFAULT '',
+  started_at TEXT NOT NULL DEFAULT (current_timestamp::VARCHAR),
+  ended_at TEXT,
+  metadata TEXT
+);
+
+CREATE TABLE interactions (
+  id TEXT PRIMARY KEY,
+  thread_id TEXT NOT NULL,
+  sequence INTEGER NOT NULL,
+  role TEXT NOT NULL CHECK(role IN ('user', 'assistant', 'system', 'tool')),
+  kind TEXT NOT NULL CHECK(kind IN ('message', 'thinking', 'tool_use', 'tool_result', 'context_update', 'status_change')),
+  content TEXT NOT NULL,
+  tool_name TEXT,
+  tool_input TEXT,
+  duration_ms INTEGER,
+  token_count INTEGER,
+  created_at TEXT NOT NULL DEFAULT (current_timestamp::VARCHAR),
+  UNIQUE(thread_id, sequence)
+);
+
+INSERT INTO threads
+SELECT id,
+       CASE WHEN type = 'daemon_tick' THEN 'worker_tick' ELSE type END,
+       task_id, title, started_at, ended_at, metadata
+FROM threads_backup;
+
+INSERT INTO interactions SELECT * FROM interactions_backup;
+
+DROP TABLE threads_backup;
+DROP TABLE interactions_backup;

package/src/db/tasks.ts

@@ -270,7 +270,7 @@ export async function resetStaleTasks(
 
 export async function claimNextTask(
   db: DbConnection,
-  claimedBy = "daemon",
+  claimedBy: string,
 ): Promise<Task | null> {
   // Find highest-priority unblocked pending task
   // Use application-level filtering for blocked_by since DuckDB doesn't have json_each
@@ -321,3 +321,27 @@ export async function claimNextTask(
 
   return null;
 }
+
+/**
+ * Atomically claim a specific task by id. Returns the task if successfully
+ * claimed, or null if the task doesn't exist, is already claimed, or isn't
+ * in `pending` state.
+ */
+export async function claimSpecificTask(
+  db: DbConnection,
+  taskId: string,
+  claimedBy: string,
+): Promise<Task | null> {
+  const row = await db.queryGet<TaskRow>(
+    `UPDATE tasks
+     SET status = 'in_progress',
+         claimed_by = ?1,
+         claimed_at = current_timestamp::VARCHAR,
+         updated_at = current_timestamp::VARCHAR
+     WHERE id = ?2 AND status = 'pending'
+     RETURNING *`,
+    claimedBy,
+    taskId,
+  );
+  return row ? rowToTask(row) : null;
+}

package/src/db/threads.ts

@@ -4,7 +4,7 @@ import { uuidv7 } from "./uuid.ts";
 
 export interface Thread {
   id: string;
-  type: "daemon_tick" | "chat_session";
+  type: "worker_tick" | "chat_session";
   task_id: string | null;
   title: string;
   started_at: Date;

package/src/db/workers.ts

@@ -0,0 +1,207 @@
+import type { DbConnection } from "./connection.ts";
+import { buildWhereClause, sanitizeInt } from "./query.ts";
+
+export const WORKER_MODES = ["persist", "once"] as const;
+export const WORKER_STATUSES = ["running", "stopped", "dead"] as const;
+
+export interface Worker {
+  id: string;
+  pid: number;
+  hostname: string;
+  mode: (typeof WORKER_MODES)[number];
+  task_id: string | null;
+  status: (typeof WORKER_STATUSES)[number];
+  started_at: Date;
+  last_heartbeat_at: Date;
+  stopped_at: Date | null;
+}
+
+interface WorkerRow {
+  id: string;
+  pid: number;
+  hostname: string;
+  mode: string;
+  task_id: string | null;
+  status: string;
+  started_at: string;
+  last_heartbeat_at: string;
+  stopped_at: string | null;
+}
+
+function rowToWorker(row: WorkerRow): Worker {
+  return {
+    id: row.id,
+    pid: row.pid,
+    hostname: row.hostname,
+    mode: row.mode as Worker["mode"],
+    task_id: row.task_id,
+    status: row.status as Worker["status"],
+    started_at: new Date(row.started_at),
+    last_heartbeat_at: new Date(row.last_heartbeat_at),
+    stopped_at: row.stopped_at ? new Date(row.stopped_at) : null,
+  };
+}
+
+export async function registerWorker(
+  db: DbConnection,
+  params: {
+    id: string;
+    pid: number;
+    hostname: string;
+    mode: Worker["mode"];
+    taskId?: string | null;
+  },
+): Promise<Worker> {
+  const row = await db.queryGet<WorkerRow>(
+    `INSERT INTO workers (id, pid, hostname, mode, task_id, status)
+     VALUES (?1, ?2, ?3, ?4, ?5, 'running')
+     RETURNING *`,
+    params.id,
+    params.pid,
+    params.hostname,
+    params.mode,
+    params.taskId ?? null,
+  );
+  if (!row) throw new Error("INSERT did not return a row");
+  return rowToWorker(row);
+}
+
+export async function heartbeat(db: DbConnection, id: string): Promise<void> {
+  await db.queryRun(
+    `UPDATE workers
+     SET last_heartbeat_at = current_timestamp::VARCHAR
+     WHERE id = ?1 AND status = 'running'`,
+    id,
+  );
+}
+
+export async function markWorkerStopped(
+  db: DbConnection,
+  id: string,
+): Promise<void> {
+  await db.queryRun(
+    `UPDATE workers
+     SET status = 'stopped',
+         stopped_at = current_timestamp::VARCHAR
+     WHERE id = ?1 AND status = 'running'`,
+    id,
+  );
+}
+
+export async function markWorkerDead(
+  db: DbConnection,
+  id: string,
+): Promise<void> {
+  await db.queryRun(
+    `UPDATE workers
+     SET status = 'dead',
+         stopped_at = current_timestamp::VARCHAR
+     WHERE id = ?1 AND status = 'running'`,
+    id,
+  );
+}
+
+/**
+ * Find running workers whose heartbeat is older than `staleAfterSeconds`,
+ * mark them dead, and release any tasks/schedule claims they held back
+ * to the pool. Returns the ids of reaped workers.
+ */
+export async function reapDeadWorkers(
+  db: DbConnection,
+  staleAfterSeconds: number,
+): Promise<string[]> {
+  const stale = await db.queryAll<{ id: string }>(
+    `UPDATE workers
+     SET status = 'dead',
+         stopped_at = current_timestamp::VARCHAR
+     WHERE status = 'running'
+       AND last_heartbeat_at::TIMESTAMP
+           < current_timestamp - to_seconds(CAST(?1 AS BIGINT))
+     RETURNING id`,
+    staleAfterSeconds,
+  );
+  const reapedIds = stale.map((r) => r.id);
+  if (reapedIds.length === 0) return reapedIds;
+
+  for (const reapedId of reapedIds) {
+    await db.queryRun(
+      `UPDATE tasks
+       SET status = 'pending',
+           claimed_by = NULL,
+           claimed_at = NULL,
+           updated_at = current_timestamp::VARCHAR
+       WHERE claimed_by = ?1 AND status = 'in_progress'`,
+      reapedId,
+    );
+    await db.queryRun(
+      `UPDATE schedules
+       SET claimed_by = NULL,
+           claimed_at = NULL
+       WHERE claimed_by = ?1`,
+      reapedId,
+    );
+  }
+  return reapedIds;
+}
+
+/**
+ * Delete cleanly-stopped workers (status='stopped') whose `stopped_at` is
+ * older than `afterSeconds`. Dead workers are intentionally left alone —
+ * they're forensic evidence that something crashed.
+ * Returns the ids that were pruned.
+ */
+export async function pruneStoppedWorkers(
+  db: DbConnection,
+  afterSeconds: number,
+): Promise<string[]> {
+  const rows = await db.queryAll<{ id: string }>(
+    `DELETE FROM workers
+     WHERE status = 'stopped'
+       AND stopped_at IS NOT NULL
+       AND stopped_at::TIMESTAMP
+           < current_timestamp - to_seconds(CAST(?1 AS BIGINT))
+     RETURNING id`,
+    afterSeconds,
+  );
+  return rows.map((r) => r.id);
+}
+
+export async function listWorkers(
+  db: DbConnection,
+  filters?: {
+    status?: Worker["status"];
+    limit?: number;
+    offset?: number;
+  },
+): Promise<Worker[]> {
+  const { where, params } = buildWhereClause([["status", filters?.status]]);
+  const limit = filters?.limit ? `LIMIT ${sanitizeInt(filters.limit)}` : "";
+  const offset = filters?.offset ? `OFFSET ${sanitizeInt(filters.offset)}` : "";
+
+  const rows = await db.queryAll<WorkerRow>(
+    `SELECT * FROM workers ${where}
+     ORDER BY started_at DESC, id DESC
+     ${limit} ${offset}`,
+    ...params,
+  );
+  return rows.map(rowToWorker);
+}
+
+export async function getWorker(
+  db: DbConnection,
+  id: string,
+): Promise<Worker | null> {
+  const row = await db.queryGet<WorkerRow>(
+    "SELECT * FROM workers WHERE id = ?1",
+    id,
+  );
+  return row ? rowToWorker(row) : null;
+}
+
+export async function deleteWorker(
+  db: DbConnection,
+  id: string,
+): Promise<boolean> {
+  const result = await db.queryRun("DELETE FROM workers WHERE id = ?1", id);
+  return result.changes > 0;
+}

package/src/init/index.ts

@@ -77,7 +77,9 @@ export async function initProject(
   logger.dim("Next steps:");
   logger.dim("  1. Set ANTHROPIC_API_KEY or add it to .botholomew/config.json");
   logger.dim("  2. Run 'botholomew task add' to create your first task");
-  logger.dim("  3. Run 'botholomew daemon start' to start the daemon");
+  logger.dim(
+    "  3. Run 'botholomew worker start --persist' to start a background worker",
+  );
 }
 
 async function updateGitignore(projectDir: string): Promise<void> {

package/src/tools/context/read-large-result.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { readLargeResultPage } from "../../daemon/large-results.ts";
+import { readLargeResultPage } from "../../worker/large-results.ts";
 import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({

package/src/tools/mcp/exec.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
-import { fakeMcpExec, isCaptureMode } from "../../daemon/fake-mcp.ts";
 import { formatCallToolResult } from "../../mcpx/client.ts";
+import { fakeMcpExec, isCaptureMode } from "../../worker/fake-mcp.ts";
 import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({

package/src/tools/mcp/search.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { fakeMcpSearch, isCaptureMode } from "../../daemon/fake-mcp.ts";
+import { fakeMcpSearch, isCaptureMode } from "../../worker/fake-mcp.ts";
 import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({

package/src/tools/registry.ts

@@ -43,6 +43,8 @@ import { waitTaskTool } from "./task/wait.ts";
 import { listThreadsTool } from "./thread/list.ts";
 import { viewThreadTool } from "./thread/view.ts";
 import { registerTool } from "./tool.ts";
+// Worker tools
+import { spawnWorkerTool } from "./worker/spawn.ts";
 
 export function registerAllTools(): void {
   // Task
@@ -91,4 +93,7 @@ export function registerAllTools(): void {
   registerTool(mcpSearchTool);
   registerTool(mcpInfoTool);
   registerTool(mcpExecTool);
+
+  // Worker
+  registerTool(spawnWorkerTool);
 }

package/src/tools/thread/list.ts

@@ -4,7 +4,7 @@ import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({
   type: z
-    .enum(["daemon_tick", "chat_session"])
+    .enum(["worker_tick", "chat_session"])
     .optional()
     .describe("Filter by thread type"),
   limit: z.number().optional().describe("Max number of threads to return"),
@@ -27,7 +27,7 @@ const outputSchema = z.object({
 
 export const listThreadsTool = {
   name: "list_threads",
-  description: "List conversation threads (daemon ticks or chat sessions).",
+  description: "List conversation threads (worker ticks or chat sessions).",
   group: "thread",
   inputSchema,
   outputSchema,

package/src/tools/worker/spawn.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+import { spawnWorker } from "../../worker/spawn.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  task_id: z
+    .string()
+    .optional()
+    .describe(
+      "Specific task ID to run. If omitted, the worker claims the next eligible task from the queue.",
+    ),
+  persist: z
+    .boolean()
+    .optional()
+    .describe(
+      "If true, spawn a long-running worker that loops over the tick cycle. Defaults to false (one-shot).",
+    ),
+});
+
+const outputSchema = z.object({
+  worker_pid: z.number(),
+  mode: z.enum(["once", "persist"]),
+  message: z.string(),
+  is_error: z.boolean(),
+});
+
+export const spawnWorkerTool = {
+  name: "spawn_worker",
+  description:
+    "Spawn a background worker to run a task without blocking this chat. One-shot by default (claims one task and exits). Use for work the user wants executed now rather than simply queued.",
+  group: "worker",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    const mode = input.persist ? "persist" : "once";
+    const { pid } = await spawnWorker(ctx.projectDir, {
+      mode,
+      taskId: input.task_id,
+    });
+    const target = input.task_id
+      ? `task ${input.task_id}`
+      : "next eligible task";
+    return {
+      worker_pid: pid,
+      mode,
+      message: `Spawned ${mode} worker (pid ${pid}) for ${target}.`,
+      is_error: false,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;