@capekai/core 1.0.11 → 1.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capekai/core",
-  "version": "1.0.11",
+  "version": "1.0.12",
   "description": "Bun-native composable agent runtime and framework for Capek.",
   "license": "MIT",
   "repository": {

package/src/internal/hosts.ts

@@ -42,6 +42,7 @@ export { executeSchedulerTool } from '../scheduler/scheduler-tool';
 export { executeSessionSearchTool } from '../session-search/session-search-tool';
 export { executeSkillManageTool, buildSkillManageToolDescription } from '../skills/skill-manage-tool';
 export { executeMemoryTool } from '../memory/memory-tool';
+export { withKnowledgeMutationLock } from '../runtime/knowledge-mutation-lock';
 export {
   addEntry,
   entriesToContent,

package/src/memory/registry.ts

@@ -1,6 +1,7 @@
 import { existsSync } from 'fs';
 import { mkdir, readFile, writeFile } from 'fs/promises';
 import { join } from 'path';
+import { withKnowledgeMutationLock } from '../runtime/knowledge-mutation-lock';
 
 const USER_FILE = 'USER.md';
 const MEMORY_FILE = 'MEMORY.md';
@@ -72,7 +73,11 @@ function fullResult(existing: string, target: MemoryTarget, entries: string[], r
   };
 }
 
-export async function addEntry(basePath: string, target: MemoryTarget, content: string): Promise<MemoryActionResult> {
+export function addEntry(basePath: string, target: MemoryTarget, content: string): Promise<MemoryActionResult> {
+  return withKnowledgeMutationLock(basePath, () => addEntryUnlocked(basePath, target, content));
+}
+
+async function addEntryUnlocked(basePath: string, target: MemoryTarget, content: string): Promise<MemoryActionResult> {
   const trimmed = content.trim();
   if (!trimmed) return { success: false, error: 'Content cannot be empty.' };
   const entry = `- ${trimmed}`;
@@ -115,7 +120,11 @@ function findOne(content: string, entries: string[], target: MemoryTarget, oldTe
   return matches[0];
 }
 
-export async function replaceEntry(basePath: string, target: MemoryTarget, oldText: string, content: string): Promise<MemoryActionResult> {
+export function replaceEntry(basePath: string, target: MemoryTarget, oldText: string, content: string): Promise<MemoryActionResult> {
+  return withKnowledgeMutationLock(basePath, () => replaceEntryUnlocked(basePath, target, oldText, content));
+}
+
+async function replaceEntryUnlocked(basePath: string, target: MemoryTarget, oldText: string, content: string): Promise<MemoryActionResult> {
   const trimmed = content.trim();
   if (!trimmed) return { success: false, error: 'New content cannot be empty.' };
   const loaded = await readExisting(basePath, target);
@@ -128,7 +137,11 @@ export async function replaceEntry(basePath: string, target: MemoryTarget, oldTe
   return { success: true, result: { target, action: 'replace', path: fileName(target), usage: { chars: next.length, limit: charLimit(target) }, entry: trimmed } };
 }
 
-export async function removeEntry(basePath: string, target: MemoryTarget, oldText: string): Promise<MemoryActionResult> {
+export function removeEntry(basePath: string, target: MemoryTarget, oldText: string): Promise<MemoryActionResult> {
+  return withKnowledgeMutationLock(basePath, () => removeEntryUnlocked(basePath, target, oldText));
+}
+
+async function removeEntryUnlocked(basePath: string, target: MemoryTarget, oldText: string): Promise<MemoryActionResult> {
   const loaded = await readExisting(basePath, target);
   if ('success' in loaded) return loaded;
   const match = findOne(loaded.content, loaded.entries, target, oldText);

package/src/runtime/knowledge-mutation-lock.ts

@@ -0,0 +1,45 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+
+const tails = new Map<string, Promise<void>>();
+const active = new AsyncLocalStorage<{ held: boolean }>();
+
+function directoryKey(directory: string): string {
+  if (!directory.trim() || directory.includes('\0')) throw new Error('Invalid knowledge directory');
+  let current = resolve(directory);
+  const missing: string[] = [];
+  for (;;) {
+    try {
+      return join(realpathSync(current), ...missing.reverse());
+    } catch (error: unknown) {
+      if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+      const parent = dirname(current);
+      if (parent === current) throw error;
+      missing.push(basename(current));
+      current = parent;
+    }
+  }
+}
+
+/** Serialize managed read-modify-write operations by canonical directory.
+ * Process-local only: external writers must be handled by host revision policy.
+ * Do not call managed memory/skill mutators inside this callback; they acquire
+ * the same primitive themselves. Permission waits belong outside the lock. */
+export async function withKnowledgeMutationLock<T>(directory: string, callback: () => Promise<T>): Promise<T> {
+  if (active.getStore()?.held) throw new Error('Nested knowledge mutation locks are not supported');
+  const key = directoryKey(directory);
+  const previous = tails.get(key) ?? Promise.resolve();
+  let release!: () => void;
+  const tail = new Promise<void>(resolve => { release = resolve; });
+  tails.set(key, tail);
+  await previous;
+  const state = { held: true };
+  try {
+    return await active.run(state, callback);
+  } finally {
+    state.held = false;
+    release();
+    if (tails.get(key) === tail) tails.delete(key);
+  }
+}

package/src/skills/skill-manage-tool.ts

@@ -4,6 +4,7 @@ import { join } from 'path';
 import type { PermissionAsk } from '@capekai/tool';
 import { PermissionRiskLevel } from '@capekai/tool';
 import { scanSkillsFromDir } from './registry';
+import { withKnowledgeMutationLock } from '../runtime/knowledge-mutation-lock';
 
 type SkillManageAction = 'list' | 'create' | 'update' | 'patch' | 'delete';
 export interface SkillManageResult {
@@ -137,49 +138,51 @@ export async function executeSkillManageTool(input: Record<string, unknown>, roo
     if (!approved) return { success: false, error: 'USER_REJECTION' };
   }
 
-  if (action === 'create') {
-    if (!description) return { success: false, error: 'description is required for create action.' };
-    if (!content) return { success: false, error: 'content is required for create action.' };
-    const path = skillPath(root, safeName);
-    if (existsSync(path)) return { success: false, error: `Skill "${safeName}" already exists. Use update or patch instead.` };
-    await mkdir(skillDir(root, safeName), { recursive: true });
-    await writeFile(path, frontmatter(safeName, description) + '\n' + content + '\n', 'utf-8');
-    return { success: true, title: `Skill created: ${safeName}`, action, name: safeName, description, path: `${safeName}/SKILL.md`, summary: 'Created workspace skill.' };
-  }
+  return withKnowledgeMutationLock(root, async (): Promise<SkillManageResult> => {
+    if (action === 'create') {
+      if (!description) return { success: false, error: 'description is required for create action.' };
+      if (!content) return { success: false, error: 'content is required for create action.' };
+      const path = skillPath(root, safeName);
+      if (existsSync(path)) return { success: false, error: `Skill "${safeName}" already exists. Use update or patch instead.` };
+      await mkdir(skillDir(root, safeName), { recursive: true });
+      await writeFile(path, frontmatter(safeName, description) + '\n' + content + '\n', 'utf-8');
+      return { success: true, title: `Skill created: ${safeName}`, action, name: safeName, description, path: `${safeName}/SKILL.md`, summary: 'Created workspace skill.' };
+    }
 
-  const resolved = await resolveSkillFolder(rawName, root);
-  if (!resolved) {
-    const names = await availableNames(root);
-    return { success: false, error: `Skill "${rawName}" does not exist.${names.length ? ` Available skills: ${names.join(', ')}` : action === 'delete' ? '' : ' No skills exist yet. Use create first.'}` };
-  }
-  const relativePath = `${resolved.folderName}/SKILL.md`;
-  if (action === 'delete') {
-    await rm(skillDir(root, resolved.folderName), { recursive: true, force: true });
-    return { success: true, title: `Skill deleted: ${resolved.folderName}`, action, name: resolved.folderName, path: relativePath, summary: 'Removed workspace skill directory.' };
-  }
-  let existing: string;
-  try { existing = await readFile(resolved.skillMdPath, 'utf-8'); } catch { return { success: false, error: 'Failed to read existing skill file.' }; }
-
-  if (action === 'update') {
-    if (!content) return { success: false, error: 'content is required for update action.' };
-    const existingDescription = existing.match(/^description:\s*(.+)$/m)?.[1].replace(/^['"]|['"]$/g, '') ?? '';
-    const existingName = existing.match(/^name:\s*(.+)$/m)?.[1].replace(/^['"]|['"]$/g, '').trim() ?? resolved.folderName;
-    const effectiveDescription = description ?? existingDescription;
-    await writeFile(resolved.skillMdPath, frontmatter(existingName, effectiveDescription) + '\n' + content + '\n', 'utf-8');
-    return { success: true, title: `Skill updated: ${existingName}`, action, name: existingName, description: effectiveDescription, path: relativePath, summary: 'Replaced skill body.' };
-  }
+    const resolved = await resolveSkillFolder(rawName, root);
+    if (!resolved) {
+      const names = await availableNames(root);
+      return { success: false, error: `Skill "${rawName}" does not exist.${names.length ? ` Available skills: ${names.join(', ')}` : action === 'delete' ? '' : ' No skills exist yet. Use create first.'}` };
+    }
+    const relativePath = `${resolved.folderName}/SKILL.md`;
+    if (action === 'delete') {
+      await rm(skillDir(root, resolved.folderName), { recursive: true, force: true });
+      return { success: true, title: `Skill deleted: ${resolved.folderName}`, action, name: resolved.folderName, path: relativePath, summary: 'Removed workspace skill directory.' };
+    }
+    let existing: string;
+    try { existing = await readFile(resolved.skillMdPath, 'utf-8'); } catch { return { success: false, error: 'Failed to read existing skill file.' }; }
+
+    if (action === 'update') {
+      if (!content) return { success: false, error: 'content is required for update action.' };
+      const existingDescription = existing.match(/^description:\s*(.+)$/m)?.[1].replace(/^['"]|['"]$/g, '') ?? '';
+      const existingName = existing.match(/^name:\s*(.+)$/m)?.[1].replace(/^['"]|['"]$/g, '').trim() ?? resolved.folderName;
+      const effectiveDescription = description ?? existingDescription;
+      await writeFile(resolved.skillMdPath, frontmatter(existingName, effectiveDescription) + '\n' + content + '\n', 'utf-8');
+      return { success: true, title: `Skill updated: ${existingName}`, action, name: existingName, description: effectiveDescription, path: relativePath, summary: 'Replaced skill body.' };
+    }
 
-  if (!oldString) return { success: false, error: 'oldString is required for patch action.' };
-  if (newString === undefined || newString === null) return { success: false, error: 'newString is required for patch action.' };
-  const matches = existing.split(oldString).length - 1;
-  if (matches === 0) return { success: false, error: 'oldString not found in skill file. Load the skill via the "skill" tool first to see the exact content, then copy the exact text to oldString.' };
-  if (matches > 1) return { success: false, error: `oldString matched ${matches} locations. Provide a more specific oldString.` };
-  let patched = existing.replace(oldString, newString);
-  if (description) patched = patched.replace(/^(description:\s*).*$/m, `$1${description}`);
-  await writeFile(resolved.skillMdPath, patched, 'utf-8');
-  const resultName = patched.match(/^name:\s*(.+)$/m)?.[1].replace(/^['"]|['"]$/g, '').trim() ?? resolved.folderName;
-  const resultDescription = description ?? patched.match(/^description:\s*(.+)$/m)?.[1].replace(/^['"]|['"]$/g, '');
-  return { success: true, title: `Skill patched: ${resultName}`, action, name: resultName, description: resultDescription, path: relativePath, summary: 'Replaced one matching block.' };
+    if (!oldString) return { success: false, error: 'oldString is required for patch action.' };
+    if (newString === undefined || newString === null) return { success: false, error: 'newString is required for patch action.' };
+    const matches = existing.split(oldString).length - 1;
+    if (matches === 0) return { success: false, error: 'oldString not found in skill file. Load the skill via the "skill" tool first to see the exact content, then copy the exact text to oldString.' };
+    if (matches > 1) return { success: false, error: `oldString matched ${matches} locations. Provide a more specific oldString.` };
+    let patched = existing.replace(oldString, newString);
+    if (description) patched = patched.replace(/^(description:\s*).*$/m, `$1${description}`);
+    await writeFile(resolved.skillMdPath, patched, 'utf-8');
+    const resultName = patched.match(/^name:\s*(.+)$/m)?.[1].replace(/^['"]|['"]$/g, '').trim() ?? resolved.folderName;
+    const resultDescription = description ?? patched.match(/^description:\s*(.+)$/m)?.[1].replace(/^['"]|['"]$/g, '');
+    return { success: true, title: `Skill patched: ${resultName}`, action, name: resultName, description: resultDescription, path: relativePath, summary: 'Replaced one matching block.' };
+  });
 }
 
 export const SKILL_MANAGE_GUIDANCE = `You can create and update workspace skills using the skill_manage tool.