botholomew 0.22.2 → 0.24.0

package/src/worker/approval.ts

@@ -0,0 +1,60 @@
+import type { ToolApprovalCallback } from "@evantahler/mcpx";
+import { ApprovalPendingError } from "../approvals/errors.ts";
+import {
+  callKey,
+  consumeApproval,
+  createApproval,
+  findByCallKey,
+} from "../approvals/store.ts";
+
+/**
+ * Mutable, per-worker holder for the task/thread currently being processed.
+ * The worker shares one long-lived `McpxClient` across ticks, so its approval
+ * callback can't close over a single task — it reads the current task/thread
+ * from this holder, which `runClaimedTask` updates before each agent loop.
+ * Ticks are sequential per worker, so there's no race.
+ */
+export interface WorkerApprovalCtx {
+  taskId: string | null;
+  threadId: string | null;
+}
+
+/**
+ * Build the worker's `onApprovalRequired` callback. A worker can't prompt a
+ * human, so it resolves a gated mcpx call against the on-disk approval queue:
+ *   - an existing **approved** record → consume it and allow the call,
+ *   - an existing **denied** record → return false (mcpx throws ToolApprovalDeniedError),
+ *   - a **pending** record → throw ApprovalPendingError (task parks, stays queued),
+ *   - **no record** → write a pending `approvals/<id>.md` and throw ApprovalPendingError.
+ */
+export function makeWorkerApprovalCallback(
+  projectDir: string,
+  workerId: string,
+  ctx: WorkerApprovalCtx,
+): ToolApprovalCallback {
+  return async ({ server, tool, args, reason }) => {
+    const key = callKey(server, tool, args);
+    const existing = await findByCallKey(projectDir, key);
+    if (existing) {
+      if (existing.status === "approved") {
+        await consumeApproval(projectDir, existing.id);
+        return true;
+      }
+      if (existing.status === "denied") {
+        return false;
+      }
+      // pending — already queued, still awaiting a human decision.
+      throw new ApprovalPendingError(existing.id, server, tool);
+    }
+    const created = await createApproval(projectDir, {
+      server,
+      tool,
+      args,
+      reason,
+      task_id: ctx.taskId,
+      thread_id: ctx.threadId,
+      worker_id: workerId,
+    });
+    throw new ApprovalPendingError(created.id, server, tool);
+  };
+}

package/src/worker/index.ts

@@ -1,10 +1,18 @@
 import { hostname } from "node:os";
 import ansis from "ansis";
 import { loadConfig } from "../config/loader.ts";
-import { createMcpxClient, resolveMcpxDir } from "../mcpx/client.ts";
+import {
+  buildApprovalPolicy,
+  createMcpxClient,
+  resolveMcpxDir,
+} from "../mcpx/client.ts";
 import { logger } from "../utils/logger.ts";
 import { uuidv7 } from "../utils/uuid.ts";
 import { markWorkerStopped, registerWorker } from "../workers/store.ts";
+import {
+  makeWorkerApprovalCallback,
+  type WorkerApprovalCtx,
+} from "./approval.ts";
 import { startHeartbeat, startReaper } from "./heartbeat.ts";
 import type { WorkerStreamCallbacks } from "./llm.ts";
 import { runSpecificTask, tick } from "./tick.ts";
@@ -41,6 +49,11 @@ export interface StartWorkerOptions {
    * out into unrelated schedule processing).
    */
   evalSchedules?: boolean;
+  /**
+   * Bypass the mcpx approval gate for this run (allow every tool, like
+   * Claude Code's --dangerously-skip-permissions). Overrides `approvals.enabled`.
+   */
+  unsafe?: boolean;
 }
 
 function buildForegroundCallbacks(): WorkerStreamCallbacks {
@@ -87,12 +100,29 @@ export async function startWorker(
 
   const config = await loadConfig(projectDir);
 
-  const mcpxClient = await createMcpxClient(resolveMcpxDir(projectDir, config));
+  const workerId = options.workerId ?? uuidv7();
+
+  // Approval gate wiring. The callback reads the current task/thread from a
+  // mutable holder that `runClaimedTask` updates before each agent loop.
+  const approvalCtx: WorkerApprovalCtx = { taskId: null, threadId: null };
+  const approvalPolicy = buildApprovalPolicy(config, {
+    unsafe: options.unsafe,
+  });
+  const mcpxClient = await createMcpxClient(
+    resolveMcpxDir(projectDir, config),
+    {
+      approvalPolicy,
+      onApprovalRequired: approvalPolicy
+        ? makeWorkerApprovalCallback(projectDir, workerId, approvalCtx)
+        : undefined,
+    },
+  );
   if (mcpxClient) {
-    logger.info("MCPX client initialized with external tools");
+    logger.info(
+      `MCPX client initialized with external tools${approvalPolicy ? " (approval gate active)" : ""}`,
+    );
   }
 
-  const workerId = options.workerId ?? uuidv7();
   await registerWorker(projectDir, {
     id: workerId,
     pid: process.pid,
@@ -149,6 +179,7 @@ export async function startWorker(
           taskId,
           mcpxClient,
           callbacks,
+          approvalCtx,
         });
       } else {
         await tick({
@@ -159,6 +190,7 @@ export async function startWorker(
           callbacks,
           tickNum: 1,
           evalSchedules,
+          approvalCtx,
         });
       }
       return;
@@ -179,6 +211,7 @@ export async function startWorker(
           callbacks,
           tickNum,
           evalSchedules: true,
+          approvalCtx,
         });
       } catch (err) {
         logger.error(`Tick failed: ${err}`);

package/src/worker/llm.ts

@@ -115,6 +115,11 @@ export async function runAgentLoop(input: {
 
   const maxTurns = config.max_turns;
   let nudgeCount = 0;
+  // Set by mcp_exec (via ToolContext.onApprovalPending) when a gated call has
+  // no decision yet. We park the task as `waiting` after the turn so it can be
+  // re-queued once a human approves — robust even if the agent ignores the
+  // wait_task hint in the structured tool result.
+  let pendingApprovalId: string | null = null;
   for (let turn = 0; !maxTurns || turn < maxTurns; turn++) {
     const startTime = Date.now();
     fitToContextWindow(messages, systemPrompt, maxInputTokens);
@@ -256,6 +261,9 @@ export async function runAgentLoop(input: {
           config,
           mcpxClient: input.mcpxClient ?? null,
           workerId,
+          onApprovalPending: (id) => {
+            pendingApprovalId = id;
+          },
         });
         const elapsed = Date.now() - start;
         callbacks?.onToolEnd(tc.name, result.output, result.isError, elapsed);
@@ -306,6 +314,15 @@ export async function runAgentLoop(input: {
 
     messages.push({ role: "tool", content: toolResultContent });
 
+    // A gated mcpx call with no decision yet — park the task. It'll be
+    // re-queued to `pending` when a human approves/denies the request.
+    if (pendingApprovalId) {
+      return {
+        status: "waiting",
+        reason: `Awaiting human approval (${pendingApprovalId})`,
+      };
+    }
+
     // Touch describeModel so the import isn't flagged unused on a clean build.
     void describeModel;
   }
@@ -326,6 +343,7 @@ interface ToolCallCtx {
   config: BotholomewConfig;
   mcpxClient: McpxClient | null;
   workerId?: string;
+  onApprovalPending?: (approvalId: string) => void;
 }
 
 async function executeToolCall(

package/src/worker/run.ts

@@ -9,7 +9,7 @@
 import { startWorker } from "./index.ts";
 
 const USAGE =
-  "Usage: bun run src/worker/run.ts <projectDir> [--worker-id=<uuid>] [--log-path=<path>] [--persist] [--task-id=<uuid>] [--no-eval-schedules]";
+  "Usage: bun run src/worker/run.ts <projectDir> [--worker-id=<uuid>] [--log-path=<path>] [--persist] [--task-id=<uuid>] [--no-eval-schedules] [--unsafe]";
 
 /**
  * Parse worker args (`<projectDir> [flags]`) and start the worker. Shared by
@@ -25,6 +25,7 @@ export async function runWorkerFromArgv(args: string[]): Promise<void> {
   const flags = args.slice(1);
   const persist = flags.includes("--persist");
   const noEvalSchedules = flags.includes("--no-eval-schedules");
+  const unsafe = flags.includes("--unsafe");
   const taskIdArg = flags.find((a) => a.startsWith("--task-id="));
   const taskId = taskIdArg ? taskIdArg.slice("--task-id=".length) : undefined;
   const workerIdArg = flags.find((a) => a.startsWith("--worker-id="));
@@ -42,6 +43,7 @@ export async function runWorkerFromArgv(args: string[]): Promise<void> {
     workerId,
     logPath,
     evalSchedules: noEvalSchedules ? false : undefined,
+    unsafe,
   });
 }
 

package/src/worker/spawn.ts

@@ -11,6 +11,8 @@ import { WORKER_RUN_SENTINEL } from "./sentinel.ts";
 export interface SpawnWorkerOptions {
   mode?: WorkerMode;
   taskId?: string;
+  /** Propagate `--unsafe` to the detached worker (bypass the approval gate). */
+  unsafe?: boolean;
 }
 
 /**
@@ -67,6 +69,7 @@ export async function spawnWorker(
   args.push(`--worker-id=${workerId}`, `--log-path=${logPath}`);
   if (options.mode === "persist") args.push("--persist");
   if (options.taskId) args.push(`--task-id=${options.taskId}`);
+  if (options.unsafe) args.push("--unsafe");
 
   const proc = Bun.spawn(args, {
     stdio: ["ignore", logFile, logFile],

package/src/worker/tick.ts

@@ -17,6 +17,7 @@ import {
 import { createThread, endThread, logInteraction } from "../threads/store.ts";
 import { logger } from "../utils/logger.ts";
 import { generateThreadTitle } from "../utils/title.ts";
+import type { WorkerApprovalCtx } from "./approval.ts";
 import type { WorkerStreamCallbacks } from "./llm.ts";
 import { runAgentLoop } from "./llm.ts";
 import { buildSystemPrompt } from "./prompt.ts";
@@ -30,6 +31,8 @@ export interface TickOptions {
   callbacks?: WorkerStreamCallbacks;
   tickNum?: number;
   evalSchedules?: boolean;
+  /** Holder the mcpx approval callback reads; set per-task before the loop. */
+  approvalCtx?: WorkerApprovalCtx;
 }
 
 /**
@@ -50,6 +53,7 @@ export async function tick(opts: TickOptions): Promise<boolean> {
     callbacks,
     tickNum = 1,
     evalSchedules = true,
+    approvalCtx,
   } = opts;
 
   const tickStart = Date.now();
@@ -93,6 +97,7 @@ export async function tick(opts: TickOptions): Promise<boolean> {
       mcpxClient,
       callbacks,
       task,
+      approvalCtx,
     });
   } finally {
     await mem.close();
@@ -114,6 +119,7 @@ export async function runSpecificTask(opts: {
   taskId: string;
   mcpxClient?: McpxClient | null;
   callbacks?: WorkerStreamCallbacks;
+  approvalCtx?: WorkerApprovalCtx;
 }): Promise<boolean> {
   const task = await claimSpecificTask(
     opts.projectDir,
@@ -137,6 +143,7 @@ export async function runSpecificTask(opts: {
       mcpxClient: opts.mcpxClient,
       callbacks: opts.callbacks,
       task,
+      approvalCtx: opts.approvalCtx,
     });
   } finally {
     await mem.close();
@@ -152,9 +159,18 @@ async function runClaimedTask(opts: {
   mcpxClient?: McpxClient | null;
   callbacks?: WorkerStreamCallbacks;
   task: Task;
+  approvalCtx?: WorkerApprovalCtx;
 }): Promise<void> {
-  const { projectDir, withMem, config, workerId, mcpxClient, callbacks, task } =
-    opts;
+  const {
+    projectDir,
+    withMem,
+    config,
+    workerId,
+    mcpxClient,
+    callbacks,
+    task,
+    approvalCtx,
+  } = opts;
 
   logger.info(`Claimed task: ${task.name} (${task.id})`);
   if (!callbacks && task.description) {
@@ -169,6 +185,13 @@ async function runClaimedTask(opts: {
     `Working: ${task.name}`,
   );
 
+  // Point the (shared) mcpx approval callback at this task/thread so any
+  // approval record it writes is attributable and the task can be re-queued.
+  if (approvalCtx) {
+    approvalCtx.taskId = task.id;
+    approvalCtx.threadId = threadId;
+  }
+
   let systemPrompt: string;
   try {
     systemPrompt = await buildSystemPrompt(projectDir, task, config, {

package/src/workers/store.ts

@@ -87,7 +87,7 @@ export async function registerWorker(
  */
 export async function heartbeat(projectDir: string, id: string): Promise<void> {
   const worker = await readWorker(projectDir, id);
-  if (!worker || worker.status !== "running") return;
+  if (worker?.status !== "running") return;
   worker.last_heartbeat_at = new Date().toISOString();
   await writeWorker(projectDir, worker);
 }
@@ -97,7 +97,7 @@ export async function markWorkerStopped(
   id: string,
 ): Promise<void> {
   const worker = await readWorker(projectDir, id);
-  if (!worker || worker.status !== "running") return;
+  if (worker?.status !== "running") return;
   worker.status = "stopped";
   worker.stopped_at = new Date().toISOString();
   await writeWorker(projectDir, worker);
@@ -130,7 +130,7 @@ export async function reapDeadWorkers(
   const reaped: string[] = [];
   for (const id of ids) {
     const w = await readWorker(projectDir, id);
-    if (!w || w.status !== "running") continue;
+    if (w?.status !== "running") continue;
     const heartbeatMs = Date.parse(w.last_heartbeat_at);
     if (Number.isFinite(heartbeatMs) && heartbeatMs >= cutoff) continue;
     w.status = "dead";
@@ -162,7 +162,7 @@ export async function pruneStoppedWorkers(
   const pruned: string[] = [];
   for (const id of ids) {
     const w = await readWorker(projectDir, id);
-    if (!w || w.status !== "stopped" || !w.stopped_at) continue;
+    if (w?.status !== "stopped" || !w.stopped_at) continue;
     const stoppedMs = Date.parse(w.stopped_at);
     if (Number.isFinite(stoppedMs) && stoppedMs >= cutoff) continue;
     try {