botholomew 0.15.5 → 0.16.0

package/src/tools/prompt/delete.ts

@@ -0,0 +1,103 @@
+import { unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { getPromptsDir } from "../../constants.ts";
+import {
+  PromptValidationError,
+  parsePromptFile,
+} from "../../utils/frontmatter.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  name: z
+    .string()
+    .describe("Prompt name without extension. Resolves to prompts/<name>.md."),
+});
+
+const outputSchema = z.object({
+  name: z.string(),
+  path: z.string().nullable(),
+  deleted: z.boolean(),
+  is_error: z.boolean(),
+  error_type: z.string().optional(),
+  message: z.string().optional(),
+  next_action_hint: z.string().optional(),
+});
+
+export const promptDeleteTool = {
+  name: "prompt_delete",
+  description:
+    "[[ bash equivalent command: rm ]] Delete a prompt file under prompts/. Files marked `agent-modification: false` are protected and will not be removed.",
+  group: "context",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    if (input.name.includes("/") || input.name.includes("..")) {
+      return {
+        name: input.name,
+        path: null,
+        deleted: false,
+        is_error: true,
+        error_type: "invalid_name",
+        message: `Invalid prompt name: ${input.name}`,
+      };
+    }
+
+    const filePath = join(getPromptsDir(ctx.projectDir), `${input.name}.md`);
+    const file = Bun.file(filePath);
+    if (!(await file.exists())) {
+      return {
+        name: input.name,
+        path: null,
+        deleted: false,
+        is_error: true,
+        error_type: "not_found",
+        message: `Prompt not found: prompts/${input.name}.md`,
+        next_action_hint: "Use prompt_list to see available prompts.",
+      };
+    }
+
+    const raw = await file.text();
+    try {
+      const { meta } = parsePromptFile(filePath, raw);
+      if (!meta["agent-modification"]) {
+        return {
+          name: input.name,
+          path: filePath,
+          deleted: false,
+          is_error: true,
+          error_type: "agent_modification_disabled",
+          message: `Agent deletion not allowed for prompts/${input.name}.md`,
+          next_action_hint:
+            "Edit the file manually with `botholomew prompts delete` or your editor.",
+        };
+      }
+    } catch (err) {
+      // A malformed prompt is still a valid target for deletion — the agent
+      // shouldn't be locked out of cleaning up an unparseable file. Surface
+      // the parse error in the message but allow the unlink.
+      const reason =
+        err instanceof PromptValidationError
+          ? err.reason
+          : err instanceof Error
+            ? err.message
+            : String(err);
+      await unlink(filePath);
+      return {
+        name: input.name,
+        path: filePath,
+        deleted: true,
+        is_error: false,
+        message: `Deleted unparseable prompt (${reason})`,
+      };
+    }
+
+    await unlink(filePath);
+    return {
+      name: input.name,
+      path: filePath,
+      deleted: true,
+      is_error: false,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/prompt/edit.ts

@@ -8,8 +8,9 @@ import {
 } from "../../fs/atomic.ts";
 import { applyLinePatches, LinePatchSchema } from "../../fs/patches.ts";
 import {
-  parseContextFile,
-  serializeContextFile,
+  PromptValidationError,
+  parsePromptFile,
+  serializePromptFile,
 } from "../../utils/frontmatter.ts";
 import type { ToolDefinition } from "../tool.ts";
 
@@ -17,7 +18,7 @@ const inputSchema = z.object({
   name: z
     .string()
     .describe(
-      "Prompt name without extension (e.g. 'beliefs', 'goals', 'capabilities'). Resolves to prompts/<name>.md.",
+      "Prompt name without extension (e.g. 'beliefs', 'goals'). Resolves to prompts/<name>.md.",
     ),
   patches: z.array(LinePatchSchema).describe("Patches to apply"),
 });
@@ -36,7 +37,7 @@ const outputSchema = z.object({
 export const promptEditTool = {
   name: "prompt_edit",
   description:
-    "[[ bash equivalent command: patch ]] Apply git-style line-range patches to a prompt file under prompts/. Operates on the whole file (frontmatter + body). Files marked `agent-modification: false` (e.g. soul.md) are protected. Use prompt_read first to inspect current line numbers.",
+    "[[ bash equivalent command: patch ]] Apply git-style line-range patches to a prompt file under prompts/. Operates on the whole file (frontmatter + body). Files marked `agent-modification: false` are protected. Use prompt_read first to inspect current line numbers.",
   group: "context",
   inputSchema,
   outputSchema,
@@ -65,11 +66,31 @@ export const promptEditTool = {
         is_error: true,
         error_type: "not_found",
         message: `Prompt not found: prompts/${input.name}.md`,
+        next_action_hint:
+          "Use prompt_list to see available prompts, or prompt_create to add a new one.",
       };
     }
 
     const original = file.content;
-    const preParsed = parseContextFile(original);
+    let preParsed: ReturnType<typeof parsePromptFile>;
+    try {
+      preParsed = parsePromptFile(filePath, original);
+    } catch (err) {
+      return {
+        name: input.name,
+        path: filePath,
+        applied: 0,
+        content: original,
+        is_error: true,
+        error_type: "invalid_frontmatter",
+        message:
+          err instanceof PromptValidationError
+            ? err.message
+            : `Existing prompt failed to parse: ${err instanceof Error ? err.message : String(err)}`,
+        next_action_hint:
+          "Fix the file's frontmatter directly before patching. Required keys: title, loading, agent-modification.",
+      };
+    }
     if (!preParsed.meta["agent-modification"]) {
       return {
         name: input.name,
@@ -83,9 +104,9 @@ export const promptEditTool = {
     }
 
     const updated = applyLinePatches(original, input.patches);
-    let postParsed: { meta: Record<string, unknown>; content: string };
+    let postParsed: ReturnType<typeof parsePromptFile>;
     try {
-      postParsed = parseContextFile(updated);
+      postParsed = parsePromptFile(filePath, updated);
     } catch (err) {
       return {
         name: input.name,
@@ -94,9 +115,12 @@ export const promptEditTool = {
         content: original,
         is_error: true,
         error_type: "invalid_frontmatter",
-        message: `Patched content failed to parse: ${err instanceof Error ? err.message : String(err)}`,
+        message:
+          err instanceof PromptValidationError
+            ? `Patched content failed to parse — ${err.reason}`
+            : `Patched content failed to parse: ${err instanceof Error ? err.message : String(err)}`,
         next_action_hint:
-          "Check that the frontmatter delimiters and YAML stay valid.",
+          "Check that the frontmatter delimiters and YAML stay valid (title, loading, agent-modification all required).",
       };
     }
     if (!postParsed.meta["agent-modification"]) {
@@ -113,10 +137,7 @@ export const promptEditTool = {
       };
     }
 
-    const serialized = serializeContextFile(
-      postParsed.meta,
-      postParsed.content,
-    );
+    const serialized = serializePromptFile(postParsed.meta, postParsed.content);
 
     try {
       await atomicWriteIfUnchanged(filePath, serialized, file.mtimeMs);

package/src/tools/prompt/list.ts

@@ -0,0 +1,109 @@
+import { readdir, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { getPromptsDir } from "../../constants.ts";
+import {
+  PromptValidationError,
+  parsePromptFile,
+} from "../../utils/frontmatter.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  limit: z
+    .number()
+    .optional()
+    .default(100)
+    .describe("Max number of prompts to return (default 100)"),
+  offset: z
+    .number()
+    .optional()
+    .default(0)
+    .describe("Skip the first N prompts (default 0)"),
+});
+
+const outputSchema = z.object({
+  prompts: z.array(
+    z.object({
+      name: z.string(),
+      title: z.string().nullable(),
+      loading: z.string().nullable(),
+      agent_modification: z.boolean(),
+      size_bytes: z.number(),
+      path: z.string(),
+      valid: z.boolean(),
+      error: z.string().nullable(),
+    }),
+  ),
+  total: z.number(),
+  is_error: z.boolean(),
+});
+
+export const promptListTool = {
+  name: "prompt_list",
+  description:
+    "[[ bash equivalent command: ls ]] List prompt files under prompts/. Returns name, title, loading mode, agent_modification flag, file size, and a valid/error pair per file (so you can see at a glance which prompts have broken frontmatter).",
+  group: "context",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    const dir = getPromptsDir(ctx.projectDir);
+    let entries: string[];
+    try {
+      entries = await readdir(dir);
+    } catch (err) {
+      if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+        return { prompts: [], total: 0, is_error: false };
+      }
+      throw err;
+    }
+
+    const mdFiles = entries.filter((f) => f.endsWith(".md")).sort();
+    const total = mdFiles.length;
+    const offset = input.offset ?? 0;
+    const limit = input.limit ?? 100;
+    const page = mdFiles.slice(offset, offset + limit);
+
+    const rows = await Promise.all(
+      page.map(async (filename) => {
+        const filePath = join(dir, filename);
+        const name = filename.replace(/\.md$/, "");
+        const [raw, st] = await Promise.all([
+          Bun.file(filePath).text(),
+          stat(filePath),
+        ]);
+        try {
+          const { meta } = parsePromptFile(filePath, raw);
+          return {
+            name,
+            title: meta.title,
+            loading: meta.loading,
+            agent_modification: meta["agent-modification"],
+            size_bytes: st.size,
+            path: filePath,
+            valid: true,
+            error: null,
+          };
+        } catch (err) {
+          const reason =
+            err instanceof PromptValidationError
+              ? err.reason
+              : err instanceof Error
+                ? err.message
+                : String(err);
+          return {
+            name,
+            title: null,
+            loading: null,
+            agent_modification: false,
+            size_bytes: st.size,
+            path: filePath,
+            valid: false,
+            error: reason,
+          };
+        }
+      }),
+    );
+
+    return { prompts: rows, total, is_error: false };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/prompt/read.ts

@@ -1,13 +1,17 @@
 import { join } from "node:path";
 import { z } from "zod";
 import { getPromptsDir } from "../../constants.ts";
+import {
+  PromptValidationError,
+  parsePromptFile,
+} from "../../utils/frontmatter.ts";
 import type { ToolDefinition } from "../tool.ts";
 
 const inputSchema = z.object({
   name: z
     .string()
     .describe(
-      "Prompt name without extension (e.g. 'beliefs', 'goals', 'capabilities'). Resolves to prompts/<name>.md.",
+      "Prompt name without extension (e.g. 'beliefs', 'goals'). Resolves to prompts/<name>.md.",
     ),
 });
 
@@ -15,16 +19,19 @@ const outputSchema = z.object({
   name: z.string(),
   path: z.string().nullable(),
   content: z.string(),
+  title: z.string().nullable(),
+  loading: z.string().nullable(),
   agent_modification: z.boolean(),
   is_error: z.boolean(),
   error_type: z.string().optional(),
   message: z.string().optional(),
+  next_action_hint: z.string().optional(),
 });
 
 export const promptReadTool = {
   name: "prompt_read",
   description:
-    "[[ bash equivalent command: cat ]] Read a prompt file under prompts/ (e.g. beliefs, goals, capabilities, soul). Returns the whole file (frontmatter + body) for use with prompt_edit.",
+    "[[ bash equivalent command: cat ]] Read a prompt file under prompts/. Returns the whole file (frontmatter + body) plus the parsed title / loading / agent_modification flags so you can decide whether prompt_edit will be accepted.",
   group: "context",
   inputSchema,
   outputSchema,
@@ -34,6 +41,8 @@ export const promptReadTool = {
         name: input.name,
         path: null,
         content: "",
+        title: null,
+        loading: null,
         agent_modification: false,
         is_error: true,
         error_type: "invalid_name",
@@ -47,24 +56,47 @@ export const promptReadTool = {
         name: input.name,
         path: null,
         content: "",
+        title: null,
+        loading: null,
         agent_modification: false,
         is_error: true,
         error_type: "not_found",
         message: `Prompt not found: prompts/${input.name}.md`,
+        next_action_hint: "Use prompt_list to see available prompts.",
       };
     }
     const content = await file.text();
-    // Cheap header sniff so the agent knows whether prompt_edit will be
-    // accepted before it constructs patches.
-    const agent_modification = /agent-modification:\s*true/.test(
-      content.split("---", 3).slice(0, 3).join("---"),
-    );
-    return {
-      name: input.name,
-      path: filePath,
-      content,
-      agent_modification,
-      is_error: false,
-    };
+    try {
+      const { meta } = parsePromptFile(filePath, content);
+      return {
+        name: input.name,
+        path: filePath,
+        content,
+        title: meta.title,
+        loading: meta.loading,
+        agent_modification: meta["agent-modification"],
+        is_error: false,
+      };
+    } catch (err) {
+      const message =
+        err instanceof PromptValidationError
+          ? err.message
+          : err instanceof Error
+            ? err.message
+            : String(err);
+      return {
+        name: input.name,
+        path: filePath,
+        content,
+        title: null,
+        loading: null,
+        agent_modification: false,
+        is_error: true,
+        error_type: "invalid_frontmatter",
+        message,
+        next_action_hint:
+          "Fix the file's frontmatter (required: title, loading, agent-modification). The raw content is returned for inspection.",
+      };
+    }
   },
 } satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;

package/src/tools/registry.ts

@@ -23,7 +23,10 @@ import { mcpInfoTool } from "./mcp/info.ts";
 import { mcpListToolsTool } from "./mcp/list-tools.ts";
 import { mcpSearchTool } from "./mcp/search.ts";
 // Prompt tools
+import { promptCreateTool } from "./prompt/create.ts";
+import { promptDeleteTool } from "./prompt/delete.ts";
 import { promptEditTool } from "./prompt/edit.ts";
+import { promptListTool } from "./prompt/list.ts";
 import { promptReadTool } from "./prompt/read.ts";
 // Schedule tools
 import { createScheduleTool } from "./schedule/create.ts";
@@ -83,8 +86,11 @@ export function registerAllTools(): void {
   registerTool(contextInfoTool);
   registerTool(contextExistsTool);
   registerTool(contextCountLinesTool);
+  registerTool(promptListTool);
   registerTool(promptReadTool);
+  registerTool(promptCreateTool);
   registerTool(promptEditTool);
+  registerTool(promptDeleteTool);
   registerTool(readLargeResultTool);
   registerTool(pipeToContextTool);
 

package/src/tools/tool.ts

@@ -17,6 +17,15 @@ export interface ToolContext {
   projectDir: string;
   config: Required<BotholomewConfig>;
   mcpxClient: McpxClient | null;
+  /**
+   * Identifier of the agent process running this tool, used as the holder
+   * id for per-path context locks (`src/context/locks.ts`) so the worker
+   * reaper can identify and release locks abandoned by a crashed worker.
+   * Workers pass their `workerId`; chat sessions pass a `chat:` prefixed
+   * id; tests and one-off CLI calls leave it `undefined` (the store falls
+   * back to `pid:<n>`).
+   */
+  workerId?: string;
   /**
    * Chat-mode only. Lets long-running tools (e.g. `sleep`) poll for
    * Esc-to-abort by reading `session.aborted`. Workers leave this `undefined`.

package/src/tui/App.tsx

@@ -216,6 +216,7 @@ function AppInner({
   const [splashDone, setSplashDone] = useState(skipSplash);
   const [error, setError] = useState<string | null>(null);
   const sessionRef = useRef<ChatSession | null>(null);
+  const shuttingDownRef = useRef(false);
   const [activeTab, setActiveTab] = useState<TabId>(1);
   const [workerRunning, setWorkerRunning] = useState(false);
   const [chatTitle, setChatTitle] = useState<string | undefined>(undefined);
@@ -275,16 +276,52 @@ function AppInner({
 
     return () => {
       cancelled = true;
+      // Fire-and-forget safety net: only triggers when unmount happens via a
+      // path that didn't go through performShutdown (which nulls sessionRef
+      // first). React doesn't await unmount cleanups, so the goodbye lands
+      // before mcpx finishes closing — that's fine for non-Ctrl-C paths.
       if (sessionRef.current) {
-        const threadId = sessionRef.current.threadId;
-        endChatSession(sessionRef.current);
+        const session = sessionRef.current;
+        const threadId = session.threadId;
+        abortActiveStream(session);
+        void endChatSession(session);
         process.stderr.write(
-          `\nThread: ${threadId}\nResume with: ${ansi.success}botholomew chat --thread-id ${threadId}${ansi.reset}\n`,
+          `\nThread: ${threadId}\nResume with: ${ansi.success}botholomew chat --thread-id ${threadId}${ansi.reset}\nBye!\n`,
         );
       }
     };
   }, [projectDir, resumeThreadId]);
 
+  const performShutdown = useCallback(async () => {
+    if (shuttingDownRef.current) {
+      // Second Ctrl-C while cleanup is in flight — give the user an escape
+      // hatch. 130 = standard SIGINT exit code.
+      process.exit(130);
+    }
+    shuttingDownRef.current = true;
+
+    const session = sessionRef.current;
+    // Null the ref so the useEffect cleanup that runs on Ink unmount becomes
+    // a no-op — otherwise it would double-print the goodbye and double-close
+    // the mcpx client.
+    sessionRef.current = null;
+
+    if (session) {
+      const threadId = session.threadId;
+      abortActiveStream(session);
+      try {
+        await endChatSession(session);
+      } catch {
+        // Best-effort: the user pressed Ctrl-C, surfacing a stack trace here
+        // would just hide the goodbye line.
+      }
+      process.stderr.write(
+        `\nThread: ${threadId}\nResume with: ${ansi.success}botholomew chat --thread-id ${threadId}${ansi.reset}\nBye!\n`,
+      );
+    }
+    exit();
+  }, [exit]);
+
   // Minimum splash screen duration
   useEffect(() => {
     const timer = setTimeout(() => setSplashDone(true), 2000);
@@ -333,9 +370,12 @@ function AppInner({
     (input: string, key: any) => {
       markActivityRef.current();
 
-      // Ctrl+C exits
+      // Ctrl+C exits. Routed through performShutdown so the in-flight LLM
+      // stream is aborted and mcpx is closed before we unmount Ink — without
+      // that, one Ctrl-C prints the goodbye but the process stays pinned by
+      // the open HTTPS socket and a second Ctrl-C is needed.
       if (input === "c" && key.ctrl) {
-        exit();
+        void performShutdown();
         return;
       }
 
@@ -417,7 +457,7 @@ function AppInner({
         }
       }
     },
-    [exit, syncQueue],
+    [performShutdown, syncQueue],
   );
 
   useInput(stableAppHandler);
@@ -669,7 +709,7 @@ function AppInner({
             syncQueue();
             processQueue();
           },
-          exit,
+          exit: () => void performShutdown(),
           clearChat: () => {
             const session = sessionRef.current;
             if (!session) return;
@@ -743,7 +783,7 @@ function AppInner({
       syncQueue();
       processQueue();
     },
-    [exit, processQueue, syncQueue],
+    [performShutdown, processQueue, syncQueue],
   );
 
   const sessionDbPath = sessionRef.current?.dbPath;

package/src/utils/frontmatter.ts

@@ -1,12 +1,18 @@
 import matter from "gray-matter";
+import { z } from "zod";
+
+// --------------------------------------------------------------------------
+// Loose context-file metadata
+//
+// Used for files under `context/` (URL imports, agent-authored notes) and the
+// auto-generated `prompts/capabilities.md`. Frontmatter is permissive here:
+// imported pages may carry source_url / imported_at; agent notes may have
+// nothing at all.
+// --------------------------------------------------------------------------
 
 export interface ContextFileMeta {
   loading?: "always" | "contextual";
   "agent-modification"?: boolean;
-  // Set by `botholomew context import <url>` so the saved file remembers
-  // where it came from. Optional so files written by other paths
-  // (prompts/, beliefs/, agent-authored notes) aren't required to
-  // carry import metadata.
   source_url?: string;
   imported_at?: string;
   title?: string;
@@ -30,3 +36,86 @@ export function serializeContextFile(
 ): string {
   return matter.stringify(`\n${content}\n`, meta);
 }
+
+// --------------------------------------------------------------------------
+// Strict prompt-file schema
+//
+// Every file under `prompts/*.md` must conform. Validation runs at load time
+// (worker + chat) and on every CRUD operation; failures throw
+// PromptValidationError with the offending path so the user can fix it.
+// --------------------------------------------------------------------------
+
+export const PromptFrontmatterSchema = z
+  .object({
+    title: z.string().min(1),
+    loading: z.enum(["always", "contextual"]),
+    "agent-modification": z.boolean(),
+  })
+  .strict();
+
+export type PromptFrontmatter = z.infer<typeof PromptFrontmatterSchema>;
+
+export class PromptValidationError extends Error {
+  constructor(
+    readonly path: string,
+    readonly reason: string,
+  ) {
+    super(`${path}: ${reason}`);
+    this.name = "PromptValidationError";
+  }
+}
+
+export function parsePromptFile(
+  path: string,
+  raw: string,
+): { meta: PromptFrontmatter; content: string } {
+  let parsed: { data: Record<string, unknown>; content: string };
+  try {
+    const m = matter(raw);
+    parsed = {
+      data: (m.data ?? {}) as Record<string, unknown>,
+      content: m.content,
+    };
+  } catch (err) {
+    throw new PromptValidationError(
+      path,
+      `invalid YAML frontmatter — ${err instanceof Error ? err.message : String(err)}`,
+    );
+  }
+
+  if (Object.keys(parsed.data).length === 0) {
+    throw new PromptValidationError(
+      path,
+      "missing frontmatter (required: title, loading, agent-modification)",
+    );
+  }
+
+  const result = PromptFrontmatterSchema.safeParse(parsed.data);
+  if (!result.success) {
+    throw new PromptValidationError(path, formatZodIssues(result.error.issues));
+  }
+
+  return { meta: result.data, content: parsed.content.trim() };
+}
+
+export function serializePromptFile(
+  meta: PromptFrontmatter,
+  content: string,
+): string {
+  return matter.stringify(`\n${content}\n`, meta);
+}
+
+function formatZodIssues(issues: z.ZodIssue[]): string {
+  return issues
+    .map((issue) => {
+      if (issue.code === "unrecognized_keys") {
+        const keys = (issue as z.ZodIssue & { keys?: string[] }).keys ?? [];
+        return `unrecognized frontmatter key(s): ${keys.join(", ")}`;
+      }
+      const field = issue.path.join(".");
+      return field
+        ? `frontmatter field '${field}': ${issue.message}`
+        : issue.message;
+    })
+    .join("; ");
+}