botholomew 0.23.0 → 0.24.0

package/README.md

@@ -233,12 +233,13 @@ semantic search, append-only versioning, and URL refresh all live there.
 |---|---|
 | `botholomew init` | Initialize the current directory as a project (refuses on iCloud/Dropbox/NFS without `--force`) |
 | `botholomew status` | One-command dashboard: workers, task counts/claims, schedules (with a live "due?" check), quarantined files, store info. `--json` for scripting, `--no-evaluate` to skip the LLM schedule check |
-| `botholomew worker run\|start` | Run a worker (foreground or background); `--persist` for long-running, `--task-id <id>` to target one task |
+| `botholomew worker run\|start` | Run a worker (foreground or background); `--persist` for long-running, `--task-id <id>` to target one task, `--unsafe` to bypass the tool-approval gate |
 | `botholomew worker list\|status\|stop\|kill\|reap` | Inspect and manage running workers |
-| `botholomew chat` | Interactive Ink/React TUI |
+| `botholomew chat` | Interactive Ink/React TUI (`--unsafe` to bypass the tool-approval gate) |
 | `botholomew dream` | Reflect on recent threads — consolidate learnings into the knowledge store and update beliefs/goals (`--since`, `--dry-run`); also `/dream` in chat |
 | `botholomew task list\|add\|view\|update\|reset\|delete` | Manage the task queue (markdown files in `tasks/`) |
 | `botholomew schedule list\|add\|view\|enable\|disable\|trigger\|delete` | Recurring work (markdown files in `schedules/`) |
+| `botholomew approval list\|view\|approve\|deny` | Review and decide pending outbound-tool approvals (markdown files in `approvals/`) |
 | `botholomew membot add\|ls\|tree\|read\|write\|search\|info\|versions\|diff\|refresh\|…` | Knowledge-store passthrough to [`membot`](https://github.com/evantahler/membot) — `--config` is resolved from `membot_scope` (default `~/.membot`) |
 | `botholomew membot import-global` | Seed the project from `~/.membot` (copies `index.duckdb` + `config.json` in) |
 | `botholomew capabilities` | Rescan built-in + MCPX tools and rewrite `prompts/capabilities.md` |
@@ -322,6 +323,9 @@ Topics worth understanding in detail:
   create, edit, and search them at runtime.
 - **[MCPX integration](docs/mcpx.md)** — configuring external servers and
   how MCP tools are merged into the agent's toolset.
+- **[Approvals](docs/approvals.md)** — the human-in-the-loop gate on outbound
+  mcpx tool calls: default deny, the allowlist, the worker approval queue,
+  and `--unsafe`.
 - **[Configuration](docs/configuration.md)** — every key in `config.json`
   and its default.
 - **[Doc captures](docs/captures.md)** — how the screenshots and GIFs in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botholomew",
-  "version": "0.23.0",
+  "version": "0.24.0",
   "description": "An autonomous AI agent for knowledge work — works your task queue while you sleep.",
   "type": "module",
   "bin": {
@@ -31,7 +31,7 @@
   "dependencies": {
     "@ai-sdk/anthropic": "^3.0.81",
     "@ai-sdk/openai-compatible": "^2.0.48",
-    "@evantahler/mcpx": "0.21.11",
+    "@evantahler/mcpx": "0.22.2",
     "ai": "^6.0.197",
     "ansis": "^4.3.1",
     "commander": "^15.0.0",

package/src/approvals/decide.ts

@@ -0,0 +1,36 @@
+import { getTask, updateTaskStatus } from "../tasks/store.ts";
+import { logger } from "../utils/logger.ts";
+import type { Approval } from "./schema.ts";
+import { decideApproval, getApproval } from "./store.ts";
+
+/**
+ * Apply a human decision to a pending approval and re-queue its originating
+ * task. Shared by the CLI (`botholomew approval approve|deny`) and the chat
+ * TUI approvals panel so both behave identically:
+ *   - mark the record approved/denied,
+ *   - flip the parked task back to `pending` so a worker re-claims it; on the
+ *     re-run the recorded decision short-circuits the gated call.
+ *
+ * Returns the updated approval, or null if it didn't exist / wasn't pending.
+ */
+export async function decideAndRequeue(
+  projectDir: string,
+  id: string,
+  decision: "approved" | "denied",
+  decidedBy: string,
+): Promise<Approval | null> {
+  const existing = await getApproval(projectDir, id);
+  if (!existing || existing.status !== "pending") return null;
+  const decided = await decideApproval(projectDir, id, decision, decidedBy);
+  if (decided.task_id) {
+    const task = await getTask(projectDir, decided.task_id);
+    if (task) {
+      await updateTaskStatus(projectDir, decided.task_id, "pending");
+    } else {
+      logger.warn(
+        `Originating task ${decided.task_id} no longer exists; not re-queued.`,
+      );
+    }
+  }
+  return decided;
+}

package/src/approvals/errors.ts

@@ -0,0 +1,22 @@
+/**
+ * Thrown by a worker's `onApprovalRequired` callback when a gated mcpx call has
+ * no decision yet (a fresh `approvals/<id>.md` was just written, or an existing
+ * one is still pending). It propagates out of `McpxClient.exec()` — unlike a
+ * `false` return, which mcpx turns into `ToolApprovalDeniedError`. `mcp_exec`
+ * catches it, signals the worker loop to park the task as `waiting`, and returns
+ * a structured "awaiting approval" result to the agent.
+ */
+export class ApprovalPendingError extends Error {
+  readonly approvalId: string;
+  readonly server: string;
+  readonly tool: string;
+  constructor(approvalId: string, server: string, tool: string) {
+    super(
+      `Tool "${server}/${tool}" is awaiting human approval (${approvalId}).`,
+    );
+    this.name = "ApprovalPendingError";
+    this.approvalId = approvalId;
+    this.server = server;
+    this.tool = tool;
+  }
+}

package/src/approvals/schema.ts

@@ -0,0 +1,48 @@
+import { z } from "zod";
+
+export const APPROVAL_STATUSES = ["pending", "approved", "denied"] as const;
+
+export type ApprovalStatus = (typeof APPROVAL_STATUSES)[number];
+
+/**
+ * Frontmatter validator for `approvals/<id>.md`. An approval record describes a
+ * single gated mcpx tool call a worker wanted to make. Strict so a hand-edited
+ * or stale file doesn't silently round-trip with bad data; a parse failure
+ * quarantines the file (skip, log) the same way tasks/schedules do.
+ *
+ * `call_key` is a stable hash of (server, tool, args) so a re-run of the same
+ * task can match the human's decision to the concrete call that was approved.
+ */
+export const ApprovalFrontmatterSchema = z.object({
+  id: z.string().min(1),
+  status: z.enum(APPROVAL_STATUSES).default("pending"),
+  server: z.string(),
+  tool: z.string(),
+  /** JSON-encoded tool arguments (kept as a string to avoid nested-YAML quirks). */
+  args: z.string().default("{}"),
+  /** Stable hash of server+tool+args; how a re-run matches a prior decision. */
+  call_key: z.string(),
+  /** Originating task/thread/worker — null when the request came from chat. */
+  task_id: z.string().nullable().default(null),
+  thread_id: z.string().nullable().default(null),
+  worker_id: z.string().nullable().default(null),
+  /** Human-readable label for why the gate fired (e.g. "not-allowlisted"). */
+  reason: z.string().default(""),
+  created_at: z.string(),
+  updated_at: z.string(),
+  decided_at: z.string().nullable().default(null),
+  decided_by: z.string().nullable().default(null),
+});
+
+export type ApprovalFrontmatter = z.infer<typeof ApprovalFrontmatterSchema>;
+
+/**
+ * In-memory approval representation: frontmatter parsed + filesystem mtime so
+ * callers can detect concurrent edits before committing a write.
+ */
+export interface Approval extends ApprovalFrontmatter {
+  /** Filesystem mtime in epoch ms, used for atomic-write-if-unchanged. */
+  mtimeMs: number;
+  /** Markdown body (everything after the frontmatter). */
+  body: string;
+}

package/src/approvals/store.ts

@@ -0,0 +1,276 @@
+import { createHash } from "node:crypto";
+import { readdir, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import matter from "gray-matter";
+import { getApprovalsDir } from "../constants.ts";
+import {
+  atomicWrite,
+  atomicWriteIfUnchanged,
+  readWithMtime,
+} from "../fs/atomic.ts";
+import { logger } from "../utils/logger.ts";
+import { uuidv7 } from "../utils/uuid.ts";
+import {
+  type Approval,
+  type ApprovalFrontmatter,
+  ApprovalFrontmatterSchema,
+  type ApprovalStatus,
+} from "./schema.ts";
+
+export function approvalFilePath(projectDir: string, id: string): string {
+  return join(getApprovalsDir(projectDir), `${id}.md`);
+}
+
+/**
+ * Stable key for an mcpx call: a hash over server + tool + canonicalized args
+ * (object keys sorted recursively) so the same logical call always produces
+ * the same key regardless of argument ordering.
+ */
+export function callKey(
+  server: string,
+  tool: string,
+  args: Record<string, unknown> | undefined,
+): string {
+  const canonical = canonicalize(args ?? {});
+  const payload = JSON.stringify({ server, tool, args: canonical });
+  return createHash("sha256").update(payload).digest("hex").slice(0, 32);
+}
+
+function canonicalize(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (value && typeof value === "object") {
+    const out: Record<string, unknown> = {};
+    for (const k of Object.keys(value as Record<string, unknown>).sort()) {
+      out[k] = canonicalize((value as Record<string, unknown>)[k]);
+    }
+    return out;
+  }
+  return value;
+}
+
+function approvalBody(fm: ApprovalFrontmatter): string {
+  let argsPretty = fm.args;
+  try {
+    argsPretty = JSON.stringify(JSON.parse(fm.args), null, 2);
+  } catch {
+    // leave as-is
+  }
+  return [
+    `# Approval: ${fm.server}/${fm.tool}`,
+    "",
+    `Status: **${fm.status}**`,
+    "",
+    "## Arguments",
+    "",
+    "```json",
+    argsPretty,
+    "```",
+  ].join("\n");
+}
+
+export function serializeApproval(
+  fm: ApprovalFrontmatter,
+  body?: string,
+): string {
+  const content = body ?? approvalBody(fm);
+  return matter.stringify(
+    `\n${content.trim()}\n`,
+    fm as Record<string, unknown>,
+  );
+}
+
+export interface ApprovalParseOk {
+  ok: true;
+  approval: Approval;
+}
+export interface ApprovalParseFail {
+  ok: false;
+  reason: string;
+}
+
+export function parseApprovalFile(
+  raw: string,
+  mtimeMs: number,
+): ApprovalParseOk | ApprovalParseFail {
+  let parsed: matter.GrayMatterFile<string>;
+  try {
+    parsed = matter(raw);
+  } catch (err) {
+    return { ok: false, reason: `frontmatter parse error: ${err}` };
+  }
+  const result = ApprovalFrontmatterSchema.safeParse(parsed.data);
+  if (!result.success) {
+    return {
+      ok: false,
+      reason: `frontmatter validation failed: ${result.error.message}`,
+    };
+  }
+  return {
+    ok: true,
+    approval: { ...result.data, mtimeMs, body: parsed.content.trim() },
+  };
+}
+
+export async function listApprovalFiles(projectDir: string): Promise<string[]> {
+  const dir = getApprovalsDir(projectDir);
+  try {
+    const names = await readdir(dir);
+    return names.filter((n) => n.endsWith(".md")).map((n) => n.slice(0, -3));
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw err;
+  }
+}
+
+export async function getApproval(
+  projectDir: string,
+  id: string,
+): Promise<Approval | null> {
+  const file = await readWithMtime(approvalFilePath(projectDir, id));
+  if (!file) return null;
+  const parsed = parseApprovalFile(file.content, file.mtimeMs);
+  if (!parsed.ok) {
+    logger.warn(`Approval ${id} is malformed: ${parsed.reason}`);
+    return null;
+  }
+  return parsed.approval;
+}
+
+export async function listApprovals(
+  projectDir: string,
+  filters?: { status?: ApprovalStatus; limit?: number; offset?: number },
+): Promise<Approval[]> {
+  const ids = await listApprovalFiles(projectDir);
+  const approvals: Approval[] = [];
+  for (const id of ids) {
+    const a = await getApproval(projectDir, id);
+    if (!a) continue;
+    if (filters?.status && a.status !== filters.status) continue;
+    approvals.push(a);
+  }
+  // Newest-first by id (uuidv7 is time-ordered) for deterministic pagination.
+  approvals.sort((a, b) => (a.id < b.id ? 1 : -1));
+  const offset = filters?.offset ?? 0;
+  const limit = filters?.limit ?? approvals.length;
+  return approvals.slice(offset, offset + limit);
+}
+
+export async function createApproval(
+  projectDir: string,
+  params: {
+    server: string;
+    tool: string;
+    args?: Record<string, unknown>;
+    reason?: string;
+    task_id?: string | null;
+    thread_id?: string | null;
+    worker_id?: string | null;
+  },
+): Promise<Approval> {
+  const id = uuidv7();
+  const now = new Date().toISOString();
+  const fm: ApprovalFrontmatter = {
+    id,
+    status: "pending",
+    server: params.server,
+    tool: params.tool,
+    args: JSON.stringify(params.args ?? {}),
+    call_key: callKey(params.server, params.tool, params.args),
+    task_id: params.task_id ?? null,
+    thread_id: params.thread_id ?? null,
+    worker_id: params.worker_id ?? null,
+    reason: params.reason ?? "",
+    created_at: now,
+    updated_at: now,
+    decided_at: null,
+    decided_by: null,
+  };
+  await atomicWrite(approvalFilePath(projectDir, id), serializeApproval(fm));
+  const fresh = await getApproval(projectDir, id);
+  if (!fresh) throw new Error(`Failed to read freshly created approval ${id}`);
+  return fresh;
+}
+
+export class ApprovalNotFoundError extends Error {
+  constructor(readonly id: string) {
+    super(`Approval not found: ${id}`);
+    this.name = "ApprovalNotFoundError";
+  }
+}
+
+/**
+ * Record a human decision (approve/deny) on a pending approval. Atomic
+ * write-if-unchanged so a concurrent edit doesn't get clobbered.
+ */
+export async function decideApproval(
+  projectDir: string,
+  id: string,
+  decision: "approved" | "denied",
+  decidedBy: string,
+): Promise<Approval> {
+  const a = await getApproval(projectDir, id);
+  if (!a) throw new ApprovalNotFoundError(id);
+  const fm: ApprovalFrontmatter = {
+    ...stripRuntime(a),
+    status: decision,
+    decided_at: new Date().toISOString(),
+    decided_by: decidedBy,
+    updated_at: new Date().toISOString(),
+  };
+  await atomicWriteIfUnchanged(
+    approvalFilePath(projectDir, id),
+    serializeApproval(fm),
+    a.mtimeMs,
+  );
+  const fresh = await getApproval(projectDir, id);
+  if (!fresh) throw new ApprovalNotFoundError(id);
+  return fresh;
+}
+
+/**
+ * Find the most-recent approval record for a call key (any status), or null.
+ * Used by the worker callback to resolve a gated call against a prior decision.
+ */
+export async function findByCallKey(
+  projectDir: string,
+  key: string,
+): Promise<Approval | null> {
+  const all = await listApprovals(projectDir);
+  for (const a of all) {
+    // listApprovals is newest-first, so the first match is the latest.
+    if (a.call_key === key) return a;
+  }
+  return null;
+}
+
+/**
+ * Delete an approval record. Approvals are single-use: once an approved record
+ * has authorized its call, it's consumed so a later identical call re-prompts.
+ */
+export async function consumeApproval(
+  projectDir: string,
+  id: string,
+): Promise<boolean> {
+  try {
+    await unlink(approvalFilePath(projectDir, id));
+    return true;
+  } catch (err) {
+    if ((err as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw err;
+  }
+}
+
+export async function deleteAllApprovals(projectDir: string): Promise<number> {
+  const ids = await listApprovalFiles(projectDir);
+  let n = 0;
+  for (const id of ids) {
+    if (await consumeApproval(projectDir, id)) n++;
+  }
+  return n;
+}
+
+/** Drop the in-memory-only fields before writing frontmatter back to disk. */
+function stripRuntime(a: Approval): ApprovalFrontmatter {
+  const { mtimeMs: _m, body: _b, ...fm } = a;
+  return fm;
+}

package/src/chat/approval.ts

@@ -0,0 +1,62 @@
+/**
+ * Bridge between the mcpx approval callback (which runs deep inside a chat turn,
+ * awaiting a boolean) and the Ink TUI (which renders a prompt and resolves it on
+ * a keypress). The mcpx client is constructed before the TUI mounts, so the
+ * callback can't reference React state directly — it talks to this bridge, and
+ * a TUI hook subscribes to drive the prompt.
+ *
+ * Gated tool calls within a single turn run in parallel (`Promise.all`), so the
+ * bridge holds a FIFO queue and surfaces one request at a time.
+ */
+export interface ChatApprovalRequest {
+  server: string;
+  tool: string;
+  args: Record<string, unknown>;
+  reason: string;
+}
+
+interface PendingApproval {
+  req: ChatApprovalRequest;
+  resolve: (approved: boolean) => void;
+}
+
+export interface ChatApprovalBridge {
+  /** Called by the mcpx callback; resolves once the user decides. */
+  request(req: ChatApprovalRequest): Promise<boolean>;
+  /** The request currently awaiting a decision (head of the queue), or null. */
+  current(): ChatApprovalRequest | null;
+  /** Resolve the head request with the user's decision. */
+  resolve(approved: boolean): void;
+  /** Subscribe to queue changes (UI re-render). Returns an unsubscribe fn. */
+  subscribe(cb: () => void): () => void;
+}
+
+export function createApprovalBridge(): ChatApprovalBridge {
+  const queue: PendingApproval[] = [];
+  const listeners = new Set<() => void>();
+  const notify = () => {
+    for (const l of listeners) l();
+  };
+  return {
+    request(req) {
+      return new Promise<boolean>((resolve) => {
+        queue.push({ req, resolve });
+        notify();
+      });
+    },
+    current() {
+      return queue[0]?.req ?? null;
+    },
+    resolve(approved) {
+      const head = queue.shift();
+      head?.resolve(approved);
+      notify();
+    },
+    subscribe(cb) {
+      listeners.add(cb);
+      return () => {
+        listeners.delete(cb);
+      };
+    },
+  };
+}

package/src/chat/session.ts

@@ -3,7 +3,11 @@ import { loadConfig } from "../config/loader.ts";
 import type { BotholomewConfig } from "../config/schemas.ts";
 import type { AbortHandle } from "../llm/abort.ts";
 import { BotholomewLlmError } from "../llm/types.ts";
-import { createMcpxClient, resolveMcpxDir } from "../mcpx/client.ts";
+import {
+  buildApprovalPolicy,
+  createMcpxClient,
+  resolveMcpxDir,
+} from "../mcpx/client.ts";
 import { loadSkills } from "../skills/loader.ts";
 import type { SkillDefinition } from "../skills/parser.ts";
 import {
@@ -16,6 +20,7 @@ import {
 } from "../threads/store.ts";
 import { generateThreadTitle } from "../utils/title.ts";
 import { type ChatTurnCallbacks, runChatTurn } from "./agent.ts";
+import { type ChatApprovalBridge, createApprovalBridge } from "./approval.ts";
 
 export interface ChatSession {
   threadId: string;
@@ -25,6 +30,8 @@ export interface ChatSession {
   skills: Map<string, SkillDefinition>;
   // biome-ignore lint/suspicious/noExplicitAny: mcpx client
   mcpxClient: any;
+  /** Drives the inline tool-approval prompt in the TUI. */
+  approvalBridge: ChatApprovalBridge;
   cleanup: () => Promise<void>;
   /** Set by `runChatTurn` while a `streamText(...)` is in flight. */
   activeAbort: AbortHandle | null;
@@ -65,6 +72,7 @@ export function requireProviderCreds(config: BotholomewConfig): void {
 export async function startChatSession(
   projectDir: string,
   existingThreadId?: string,
+  opts: { unsafe?: boolean } = {},
 ): Promise<ChatSession> {
   const config = await loadConfig(projectDir);
 
@@ -106,7 +114,27 @@ export async function startChatSession(
     );
   }
 
-  const mcpxClient = await createMcpxClient(resolveMcpxDir(projectDir, config));
+  // The approval gate. The bridge must exist before the mcpx client so the
+  // client's callback can reference it. When the gate is off (`--unsafe` or
+  // `approvals.enabled: false`) the policy is undefined and the callback is
+  // never invoked.
+  const approvalBridge = createApprovalBridge();
+  const approvalPolicy = buildApprovalPolicy(config, { unsafe: opts.unsafe });
+  const mcpxClient = await createMcpxClient(
+    resolveMcpxDir(projectDir, config),
+    {
+      approvalPolicy,
+      onApprovalRequired: approvalPolicy
+        ? (req) =>
+            approvalBridge.request({
+              server: req.server,
+              tool: req.tool,
+              args: req.args,
+              reason: req.reason,
+            })
+        : undefined,
+    },
+  );
   const skills = await loadSkills(projectDir);
 
   const cleanup = async () => {
@@ -120,6 +148,7 @@ export async function startChatSession(
     messages,
     skills,
     mcpxClient,
+    approvalBridge,
     cleanup,
     activeAbort: null,
     aborted: false,

package/src/cli.ts

@@ -2,6 +2,7 @@
 
 import ansis from "ansis";
 import { program } from "commander";
+import { registerApprovalCommand } from "./commands/approval.ts";
 import { registerCapabilitiesCommand } from "./commands/capabilities.ts";
 import { registerChatCommand } from "./commands/chat.ts";
 import { registerCheckUpdateCommand } from "./commands/check-update.ts";
@@ -64,6 +65,7 @@ registerWorkerCommand(program);
 registerTaskCommand(program);
 registerThreadCommand(program);
 registerScheduleCommand(program);
+registerApprovalCommand(program);
 registerChatCommand(program);
 registerDreamCommand(program);
 registerMembotCommand(program);