botholomew 0.15.5 → 0.16.0

package/src/context/store.ts

@@ -12,7 +12,12 @@ import {
 } from "node:fs/promises";
 import { dirname, join, posix, relative, sep } from "node:path";
 import { CONTEXT_DIR, PROTECTED_AREAS } from "../constants.ts";
-import { atomicWrite } from "../fs/atomic.ts";
+import {
+  atomicWrite,
+  atomicWriteIfUnchanged,
+  MtimeConflictError,
+  readWithMtime,
+} from "../fs/atomic.ts";
 import { applyLinePatches, type LinePatch } from "../fs/patches.ts";
 import {
   getCanonicalRoot,
@@ -20,6 +25,11 @@ import {
   resolveInRoot,
   toRelativePath,
 } from "../fs/sandbox.ts";
+import { withContextLock } from "./locks.ts";
+
+function defaultHolderId(): string {
+  return `pid:${process.pid}`;
+}
 
 /**
  * Disk-backed replacement for the old DuckDB context_items CRUD layer. All
@@ -310,7 +320,10 @@ export async function writeContextFile(
   projectDir: string,
   path: string,
   content: string,
-  opts: { onConflict?: "error" | "overwrite" } = {},
+  opts: {
+    onConflict?: "error" | "overwrite";
+    holderId?: string;
+  } = {},
 ): Promise<ContextEntry> {
   const abs = await resolveContext(projectDir, path);
   const normalized = normalizeContextPath(path);
@@ -321,28 +334,35 @@ export async function writeContextFile(
     );
   }
   const conflict = opts.onConflict ?? "overwrite";
-  let exists = false;
-  try {
-    const st = await stat(abs);
-    if (st.isDirectory()) throw new IsDirectoryError(normalized);
-    exists = true;
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
-  }
-  if (exists && conflict === "error") {
-    throw new PathConflictError(normalized);
-  }
-  await mkdir(dirname(abs), { recursive: true });
-  await atomicWrite(abs, content);
-  const entry = await getInfo(projectDir, normalized);
-  if (!entry) throw new Error(`Wrote ${normalized} but could not stat`);
-  return entry;
+  return withContextLock(
+    projectDir,
+    normalized,
+    opts.holderId ?? defaultHolderId(),
+    async () => {
+      let exists = false;
+      try {
+        const st = await stat(abs);
+        if (st.isDirectory()) throw new IsDirectoryError(normalized);
+        exists = true;
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+      }
+      if (exists && conflict === "error") {
+        throw new PathConflictError(normalized);
+      }
+      await mkdir(dirname(abs), { recursive: true });
+      await atomicWrite(abs, content);
+      const entry = await getInfo(projectDir, normalized);
+      if (!entry) throw new Error(`Wrote ${normalized} but could not stat`);
+      return entry;
+    },
+  );
 }
 
 export async function deleteContextPath(
   projectDir: string,
   path: string,
-  opts: { recursive?: boolean } = {},
+  opts: { recursive?: boolean; holderId?: string } = {},
 ): Promise<{ removed: number; was_directory: boolean; was_symlink: boolean }> {
   const abs = await resolveContext(projectDir, path, {
     allowSymlinkLeaf: true,
@@ -351,61 +371,80 @@ export async function deleteContextPath(
   if (normalized === "") {
     throw new PathEscapeError("refusing to delete the context root", path);
   }
-  let lst: Awaited<ReturnType<typeof lstat>>;
-  try {
-    lst = await lstat(abs);
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
-      throw new NotFoundError(normalized);
-    }
-    throw err;
-  }
-  // A symlink (to a file or a directory, broken or not) is removed with a
-  // plain unlink — never follow into the target. This is what enforces
-  // "the symlink can be deleted, but not the original content".
-  if (lst.isSymbolicLink()) {
-    await unlink(abs);
-    return { removed: 1, was_directory: false, was_symlink: true };
-  }
-  if (lst.isDirectory()) {
-    if (!opts.recursive) {
-      throw new IsDirectoryError(normalized);
-    }
-    const removedPaths = await collectFiles(abs);
-    await rm(abs, { recursive: true, force: false });
-    return {
-      removed: removedPaths.length,
-      was_directory: true,
-      was_symlink: false,
-    };
-  }
-  await unlink(abs);
-  return { removed: 1, was_directory: false, was_symlink: false };
+  return withContextLock(
+    projectDir,
+    normalized,
+    opts.holderId ?? defaultHolderId(),
+    async () => {
+      let lst: Awaited<ReturnType<typeof lstat>>;
+      try {
+        lst = await lstat(abs);
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+          throw new NotFoundError(normalized);
+        }
+        throw err;
+      }
+      // A symlink (to a file or a directory, broken or not) is removed with
+      // a plain unlink — never follow into the target. This is what enforces
+      // "the symlink can be deleted, but not the original content".
+      if (lst.isSymbolicLink()) {
+        await unlink(abs);
+        return { removed: 1, was_directory: false, was_symlink: true };
+      }
+      if (lst.isDirectory()) {
+        if (!opts.recursive) {
+          throw new IsDirectoryError(normalized);
+        }
+        const removedPaths = await collectFiles(abs);
+        await rm(abs, { recursive: true, force: false });
+        return {
+          removed: removedPaths.length,
+          was_directory: true,
+          was_symlink: false,
+        };
+      }
+      await unlink(abs);
+      return { removed: 1, was_directory: false, was_symlink: false };
+    },
+  );
 }
 
 export async function moveContextPath(
   projectDir: string,
   src: string,
   dst: string,
+  opts: { holderId?: string } = {},
 ): Promise<void> {
   const srcAbs = await resolveContext(projectDir, src);
   const dstAbs = await resolveContext(projectDir, dst);
-  try {
-    await stat(srcAbs);
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code === "ENOENT") {
-      throw new NotFoundError(normalizeContextPath(src));
-    }
-    throw err;
-  }
-  try {
-    await stat(dstAbs);
-    throw new PathConflictError(normalizeContextPath(dst));
-  } catch (err) {
-    if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
-  }
-  await mkdir(dirname(dstAbs), { recursive: true });
-  await fsRename(srcAbs, dstAbs);
+  const srcNorm = normalizeContextPath(src);
+  const dstNorm = normalizeContextPath(dst);
+  // Acquire both locks in a stable order to avoid AB/BA deadlocks between
+  // concurrent moves that swap two paths. Sorted lexicographically.
+  const [firstNorm, secondNorm] =
+    srcNorm < dstNorm ? [srcNorm, dstNorm] : [dstNorm, srcNorm];
+  const holder = opts.holderId ?? defaultHolderId();
+  return withContextLock(projectDir, firstNorm, holder, () =>
+    withContextLock(projectDir, secondNorm, holder, async () => {
+      try {
+        await stat(srcAbs);
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code === "ENOENT") {
+          throw new NotFoundError(srcNorm);
+        }
+        throw err;
+      }
+      try {
+        await stat(dstAbs);
+        throw new PathConflictError(dstNorm);
+      } catch (err) {
+        if ((err as NodeJS.ErrnoException).code !== "ENOENT") throw err;
+      }
+      await mkdir(dirname(dstAbs), { recursive: true });
+      await fsRename(srcAbs, dstAbs);
+    }),
+  );
 }
 
 export async function copyContextPath(
@@ -770,15 +809,26 @@ export async function applyPatches(
   projectDir: string,
   path: string,
   patches: Patch[],
+  opts: { holderId?: string } = {},
 ): Promise<{ applied: number; lines: number }> {
-  const content = await readContextFile(projectDir, path);
-  const newContent = applyLinePatches(content, patches);
-  await writeContextFile(projectDir, path, newContent, {
-    onConflict: "overwrite",
+  const abs = await resolveContext(projectDir, path);
+  const normalized = normalizeContextPath(path);
+  const holder = opts.holderId ?? defaultHolderId();
+  return withContextLock(projectDir, normalized, holder, async () => {
+    const read = await readWithMtime(abs);
+    if (!read) throw new NotFoundError(normalized);
+    const newContent = applyLinePatches(read.content, patches);
+    // The lock keeps other context tools out of this critical section, but
+    // an external editor (vim, IDE) can still mutate the file in parallel.
+    // The mtime guard catches that — agents and humans don't silently lose
+    // edits to each other.
+    await atomicWriteIfUnchanged(abs, newContent, read.mtimeMs);
+    return { applied: patches.length, lines: newContent.split("\n").length };
   });
-  return { applied: patches.length, lines: newContent.split("\n").length };
 }
 
+export { MtimeConflictError };
+
 /**
  * Convert an absolute filesystem path back to a context-relative path. Used
  * when rendering search hits or worker output that originated in store.ts.

package/src/fs/atomic.ts

@@ -1,3 +1,4 @@
+import { randomBytes } from "node:crypto";
 import { constants as fsConstants } from "node:fs";
 import {
   mkdir,
@@ -10,6 +11,17 @@ import {
 } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
+/**
+ * Build a temp suffix that is unique even when two callers in the same
+ * process race on the same target in the same millisecond. The 8 random
+ * bytes drown out any chance of `pid + Date.now()` collision and let the
+ * O_EXCL temp open in atomicWrite act as a real safety net rather than a
+ * suggestion.
+ */
+function defaultTempSuffix(): string {
+  return `${process.pid}.${Date.now()}.${randomBytes(8).toString("hex")}`;
+}
+
 /**
  * Write `content` to `targetPath` atomically: write to a sibling temp file,
  * fsync, then rename. The rename is atomic on POSIX same-filesystem; the
@@ -24,9 +36,17 @@ export async function atomicWrite(
   opts: { tempSuffix?: string } = {},
 ): Promise<void> {
   await mkdir(dirname(targetPath), { recursive: true });
-  const suffix = opts.tempSuffix ?? `${process.pid}.${Date.now()}`;
+  const suffix = opts.tempSuffix ?? defaultTempSuffix();
   const tmp = `${targetPath}.tmp.${suffix}`;
-  const fh = await open(tmp, "w", 0o644);
+  // O_EXCL surfaces a temp-file collision rather than letting two writers
+  // truncate each other's bytes. With the random default suffix this is the
+  // belt-and-suspenders guarantee that concurrent writes to the same target
+  // never silently lose data on the way to rename().
+  const fh = await open(
+    tmp,
+    fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY,
+    0o644,
+  );
   try {
     if (typeof content === "string") {
       await fh.writeFile(content, "utf-8");
@@ -89,9 +109,13 @@ export async function atomicWriteIfUnchanged(
   opts: { tempSuffix?: string } = {},
 ): Promise<void> {
   await mkdir(dirname(targetPath), { recursive: true });
-  const suffix = opts.tempSuffix ?? `${process.pid}.${Date.now()}`;
+  const suffix = opts.tempSuffix ?? defaultTempSuffix();
   const tmp = `${targetPath}.tmp.${suffix}`;
-  const fh = await open(tmp, "w", 0o644);
+  const fh = await open(
+    tmp,
+    fsConstants.O_CREAT | fsConstants.O_EXCL | fsConstants.O_WRONLY,
+    0o644,
+  );
   try {
     await fh.writeFile(content, "utf-8");
     await fh.sync();

package/src/init/index.ts

@@ -36,7 +36,6 @@ import {
   DEFAULT_CONFIG,
   DEFAULT_MCPX_SERVERS,
   GOALS_MD,
-  SOUL_MD,
   STANDUP_SKILL,
   SUMMARIZE_SKILL,
 } from "./templates.ts";
@@ -74,9 +73,8 @@ export async function initProject(
 
   // Persistent-context template files
   const pcDir = getPromptsDir(projectDir);
-  await Bun.write(join(pcDir, "soul.md"), SOUL_MD);
-  await Bun.write(join(pcDir, "beliefs.md"), BELIEFS_MD);
   await Bun.write(join(pcDir, "goals.md"), GOALS_MD);
+  await Bun.write(join(pcDir, "beliefs.md"), BELIEFS_MD);
   await Bun.write(join(pcDir, "capabilities.md"), CAPABILITIES_MD);
 
   // Default skills
@@ -117,7 +115,9 @@ export async function initProject(
   logger.dim("");
   logger.dim("Layout:");
   logger.dim(`  ${CONFIG_DIR}/         settings`);
-  logger.dim(`  prompts/   soul, beliefs, goals, capabilities`);
+  logger.dim(
+    `  prompts/         goals, beliefs, capabilities (and any you add)`,
+  );
   logger.dim(`  ${CONTEXT_DIR}/        agent-writable knowledge tree`);
   logger.dim(`  ${TASKS_DIR}/          one markdown file per task`);
   logger.dim(`    ${LOCKS_SUBDIR}/        worker claim lockfiles`);

package/src/init/templates.ts

@@ -1,20 +1,26 @@
 import { DEFAULT_CONFIG as SCHEMA_DEFAULT_CONFIG } from "../config/schemas.ts";
 
-export const SOUL_MD = `---
+export const GOALS_MD = `---
+title: Goals
 loading: always
-agent-modification: false
+agent-modification: true
 ---
 
-# Soul
+# Goals
 
 You are Botholomew, an AI agent for knowledge work, personified by a wise owl. You help humans manage information, research topics, organize knowledge, and complete intellectual tasks.
 
 You are thoughtful, thorough, and proactive. You work through your task queue methodically, prioritizing appropriately and asking for clarification when needed.
 
 You are direct: lead with the answer, skip preambles, disagree when you have reason to, and never flatter.
+
+*The list below is the current set of goals for this project. Update it as goals are completed or new ones are added.*
+
+- Get set up and ready to help.
 `;
 
 export const BELIEFS_MD = `---
+title: Beliefs
 loading: always
 agent-modification: true
 ---
@@ -28,20 +34,8 @@ agent-modification: true
 - I should ask for help when I'm stuck rather than guessing.
 `;
 
-export const GOALS_MD = `---
-loading: always
-agent-modification: true
----
-
-# Goals
-
-*These are the current goals for this project.*
-*Botholomew updates this file as goals are completed or new ones are added.*
-
-- Get set up and ready to help.
-`;
-
 export const CAPABILITIES_MD = `---
+title: Capabilities
 loading: always
 agent-modification: true
 ---

package/src/tools/file/copy.ts

@@ -33,7 +33,9 @@ export const contextCopyTool = {
   execute: async (input, ctx) => {
     try {
       if (input.overwrite && (await fileExists(ctx.projectDir, input.dst))) {
-        await deleteContextPath(ctx.projectDir, input.dst);
+        await deleteContextPath(ctx.projectDir, input.dst, {
+          holderId: ctx.workerId,
+        });
       }
       await copyContextPath(ctx.projectDir, input.src, input.dst);
       return { src: input.src, dst: input.dst, is_error: false };

package/src/tools/file/delete.ts

@@ -39,6 +39,7 @@ export const contextDeleteTool = {
     try {
       const result = await deleteContextPath(ctx.projectDir, input.path, {
         recursive: input.recursive,
+        holderId: ctx.workerId,
       });
       return {
         deleted: result.removed,

package/src/tools/file/edit.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 import {
   applyPatches,
   IsDirectoryError,
+  MtimeConflictError,
   NotFoundError,
   readContextFile,
 } from "../../context/store.ts";
@@ -19,6 +20,7 @@ const outputSchema = z.object({
   is_error: z.boolean(),
   error_type: z.string().optional(),
   message: z.string().optional(),
+  next_action_hint: z.string().optional(),
 });
 
 export const contextEditTool = {
@@ -34,6 +36,7 @@ export const contextEditTool = {
         ctx.projectDir,
         input.path,
         input.patches,
+        { holderId: ctx.workerId },
       );
       const content = await readContextFile(ctx.projectDir, input.path);
       return { applied, content, is_error: false };
@@ -56,6 +59,17 @@ export const contextEditTool = {
           message: `context/${err.path} is a directory`,
         };
       }
+      if (err instanceof MtimeConflictError) {
+        return {
+          applied: 0,
+          content: "",
+          is_error: true,
+          error_type: "mtime_conflict",
+          message: `context/${input.path} was modified concurrently — another writer (or an external editor) changed it between read and write.`,
+          next_action_hint:
+            "Call context_read to fetch the current content, recompute your patches against the new line numbers, and retry.",
+        };
+      }
       throw err;
     }
   },

package/src/tools/file/move.ts

@@ -32,9 +32,14 @@ export const contextMoveTool = {
   execute: async (input, ctx) => {
     try {
       if (input.overwrite && (await fileExists(ctx.projectDir, input.dst))) {
-        await deleteContextPath(ctx.projectDir, input.dst, { recursive: true });
+        await deleteContextPath(ctx.projectDir, input.dst, {
+          recursive: true,
+          holderId: ctx.workerId,
+        });
       }
-      await moveContextPath(ctx.projectDir, input.src, input.dst);
+      await moveContextPath(ctx.projectDir, input.src, input.dst, {
+        holderId: ctx.workerId,
+      });
       return { src: input.src, dst: input.dst, is_error: false };
     } catch (err) {
       if (err instanceof NotFoundError) {

package/src/tools/file/write.ts

@@ -38,7 +38,7 @@ export const contextWriteTool = {
         ctx.projectDir,
         input.path,
         input.content,
-        { onConflict: input.on_conflict ?? "error" },
+        { onConflict: input.on_conflict ?? "error", holderId: ctx.workerId },
       );
       return { path: entry.path, is_error: false };
     } catch (err) {

package/src/tools/prompt/create.ts

@@ -0,0 +1,136 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { getPromptsDir } from "../../constants.ts";
+import { atomicWrite } from "../../fs/atomic.ts";
+import {
+  PromptValidationError,
+  parsePromptFile,
+  serializePromptFile,
+} from "../../utils/frontmatter.ts";
+import type { ToolDefinition } from "../tool.ts";
+
+const inputSchema = z.object({
+  name: z
+    .string()
+    .min(1)
+    .describe(
+      "Prompt name without extension (e.g. 'style-notes'). Resolves to prompts/<name>.md.",
+    ),
+  title: z
+    .string()
+    .min(1)
+    .describe("Human-readable title shown in prompt_list output."),
+  loading: z
+    .enum(["always", "contextual"])
+    .describe(
+      "'always' includes the prompt in every system prompt. 'contextual' includes it only when the latest user/task text shares keywords with the body.",
+    ),
+  agent_modification: z
+    .boolean()
+    .describe(
+      "If true, prompt_edit and prompt_delete may modify or remove this file. If false, the file is read-only to the agent.",
+    ),
+  body: z
+    .string()
+    .describe("Markdown body (everything after the frontmatter)."),
+  on_conflict: z
+    .enum(["error", "overwrite"])
+    .optional()
+    .default("error")
+    .describe(
+      "What to do if a prompt with this name already exists. Defaults to 'error'.",
+    ),
+});
+
+const outputSchema = z.object({
+  name: z.string().nullable(),
+  path: z.string().nullable(),
+  created: z.boolean(),
+  content: z.string(),
+  is_error: z.boolean(),
+  error_type: z.string().optional(),
+  message: z.string().optional(),
+  next_action_hint: z.string().optional(),
+});
+
+const VALID_NAME = /^[a-zA-Z0-9._-]+$/;
+
+export const promptCreateTool = {
+  name: "prompt_create",
+  description:
+    "[[ bash equivalent command: touch ]] Create a new prompt file under prompts/. Frontmatter (title, loading, agent-modification) is set from the arguments and re-validated before the file is committed. Fails with path_conflict if a prompt with this name exists unless on_conflict='overwrite'.",
+  group: "context",
+  inputSchema,
+  outputSchema,
+  execute: async (input, ctx) => {
+    if (!VALID_NAME.test(input.name) || input.name.includes("..")) {
+      return {
+        name: null,
+        path: null,
+        created: false,
+        content: "",
+        is_error: true,
+        error_type: "invalid_name",
+        message: `Invalid prompt name: ${input.name}`,
+        next_action_hint:
+          "Use [a-zA-Z0-9._-] only — no slashes, no '..', no extension.",
+      };
+    }
+
+    const dir = getPromptsDir(ctx.projectDir);
+    const filePath = join(dir, `${input.name}.md`);
+    const exists = await Bun.file(filePath).exists();
+    if (exists && input.on_conflict !== "overwrite") {
+      return {
+        name: input.name,
+        path: filePath,
+        created: false,
+        content: "",
+        is_error: true,
+        error_type: "path_conflict",
+        message: `Prompt already exists: prompts/${input.name}.md`,
+        next_action_hint:
+          "Pass on_conflict='overwrite' to replace, or use prompt_edit for a partial change.",
+      };
+    }
+
+    const meta = {
+      title: input.title,
+      loading: input.loading,
+      "agent-modification": input.agent_modification,
+    };
+    const serialized = serializePromptFile(meta, input.body);
+
+    // Round-trip validation: refuse to write content that wouldn't load back.
+    try {
+      parsePromptFile(filePath, serialized);
+    } catch (err) {
+      return {
+        name: input.name,
+        path: filePath,
+        created: false,
+        content: serialized,
+        is_error: true,
+        error_type: "invalid_frontmatter",
+        message:
+          err instanceof PromptValidationError
+            ? err.message
+            : `Generated content failed validation: ${err instanceof Error ? err.message : String(err)}`,
+        next_action_hint:
+          "Pick a title without unusual characters that break YAML.",
+      };
+    }
+
+    await mkdir(dir, { recursive: true });
+    await atomicWrite(filePath, serialized);
+
+    return {
+      name: input.name,
+      path: filePath,
+      created: !exists,
+      content: serialized,
+      is_error: false,
+    };
+  },
+} satisfies ToolDefinition<typeof inputSchema, typeof outputSchema>;