agentsmesh 0.41.0 → 0.42.0

package/dist/lessons.d.ts

@@ -42,6 +42,11 @@ interface RecallOptions {
      * compact/clear, which is the exact signal a wall-clock TTL only approximates.
      */
     readonly ttlMs?: number;
+    /**
+     * Migrate a legacy store first (default true). The hook passes false: the
+     * migration deletes files, so it only runs from a command the user runs.
+     */
+    readonly autoMigrate?: boolean;
 }
 interface RecallResult {
     /** Relevance-ranked, capped lessons (compact metadata lives on each entry). */

package/dist/lessons.js

@@ -1,11 +1,11 @@
 import { z } from 'zod';
 import { createHash, randomUUID } from 'crypto';
-import { readFileSync, existsSync, mkdirSync, writeFileSync, rmSync, statSync, renameSync, readdirSync, chmodSync, realpathSync, accessSync, constants, appendFileSync, rmdirSync, unlinkSync, openSync, readSync, closeSync } from 'fs';
-import { resolve, join, relative, sep, dirname, posix, basename, extname } from 'path';
+import { readFileSync, existsSync, mkdirSync, writeFileSync, rmSync, statSync, renameSync, readdirSync, realpathSync, chmodSync, accessSync, constants, appendFileSync, lstatSync, rmdirSync, unlinkSync, openSync, readSync, closeSync } from 'fs';
+import { join, relative, sep, resolve, dirname, posix, basename, extname } from 'path';
+import { mkdir, writeFile, rm, readFile, lstat, open, readdir, rmdir, unlink, stat, rename, realpath } from 'fs/promises';
+import { hostname, tmpdir } from 'os';
 import picomatch from 'picomatch';
 import { execFile, spawnSync } from 'child_process';
-import { hostname, tmpdir } from 'os';
-import { mkdir, writeFile, rm, readFile, lstat, open, readdir, rmdir, unlink, stat, rename, realpath } from 'fs/promises';
 import { setTimeout } from 'timers/promises';
 import { promisify } from 'util';
 import { stringify, parse, parseDocument, YAMLSeq, YAMLMap } from 'yaml';
@@ -566,6 +566,115 @@ function executableModeFor(path) {
 function stripBom(text) {
   return text.startsWith(UTF8_BOM) ? text.slice(UTF8_BOM.length) : text;
 }
+async function canonicalizePath(path) {
+  try {
+    return await realpath(path);
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    const parent = dirname(path);
+    if (parent === path) return resolve(path);
+    return join(await canonicalizePath(parent), basename(path));
+  }
+}
+function canonicalizePathSync(path) {
+  try {
+    return realpathSync(path);
+  } catch (error) {
+    if (error.code !== "ENOENT") return null;
+  }
+  try {
+    lstatSync(path);
+    return null;
+  } catch {
+    const parent = dirname(path);
+    if (parent === path) return resolve(path);
+    const realParent = canonicalizePathSync(parent);
+    return realParent === null ? null : join(realParent, basename(path));
+  }
+}
+function resolvesInsideRootSync(root, target) {
+  const realRoot = canonicalizePathSync(resolve(root));
+  const realTarget = canonicalizePathSync(resolve(target));
+  return realRoot !== null && realTarget !== null && isPathInside(realTarget, realRoot);
+}
+function isPathInside(target, root) {
+  return target === root || target.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
+}
+var display = (path) => path.replaceAll("\\", "/");
+async function assertPathInsideRoot(root, target) {
+  const rootAbs = resolve(root);
+  const targetAbs = resolve(target);
+  if (!isPathInside(targetAbs, rootAbs)) {
+    throw new Error(`Unsafe filesystem path: ${display(target)} is outside ${display(rootAbs)}`);
+  }
+  let realTarget;
+  let realRoot;
+  try {
+    [realTarget, realRoot] = await Promise.all([
+      canonicalizePath(targetAbs),
+      canonicalizePath(rootAbs)
+    ]);
+  } catch (cause) {
+    const detail = cause instanceof Error ? cause.message : String(cause);
+    throw new Error(
+      `Unsafe filesystem path: ${display(target)} could not be resolved (${detail})`,
+      { cause }
+    );
+  }
+  if (isPathInside(realTarget, realRoot)) return;
+  throw new Error(
+    `Unsafe filesystem path: ${display(target)} resolves to ${display(realTarget)} outside ${display(realRoot)}`
+  );
+}
+var BASE_REL = ".agentsmesh/lessons";
+function lessonsPaths(projectRoot) {
+  const base = join(projectRoot, BASE_REL);
+  return {
+    base,
+    graph: join(base, "lessons.json"),
+    config: join(base, "config.json"),
+    journal: join(base, "journal.md"),
+    index: join(base, "index.yaml"),
+    topicsDir: join(base, "topics")
+  };
+}
+function toRelPath(projectRoot, absolute) {
+  return relative(projectRoot, absolute).split(sep).join("/");
+}
+var LESSONS_PROCEDURAL_RULE = `## Lessons (BLOCKING)
+
+Graph \`.agentsmesh/lessons/lessons.json\` is canonical; never hand-edit it. Manual: \`lessons\` skill.
+
+**Recall:** before every file edit or state-changing command, MUST run \`agentsmesh lessons query --file <path> --cmd <command> --session auto\` and obey matches; at task start, ALSO run \`agentsmesh lessons query --keyword "<task terms>" --always --session auto\` for conceptual + universal rules no path/command names. Pure-read commands and recall itself are exempt.
+
+**Capture:** after any failure, user correction, regression, wrong assumption, useful surprise, repeated friction, or non-obvious fix, MUST self-critique and run \`agentsmesh lessons add "<imperative rule>" --topic <id> --trigger-file <glob> --evidence <sha|lesson-id>\`.
+
+**Before final:** report \`Lesson: captured <id>\` or \`Lesson: none\`. No recall/capture gate = task incomplete. No shell: use \`lessons_query\` / \`lessons_add\`.`;
+
+// src/lessons/lessons-dir-guard.ts
+function lessonsDirInsideProject(projectRoot) {
+  return resolvesInsideRootSync(projectRoot, lessonsPaths(projectRoot).base);
+}
+var LessonsDirOutsideProjectError = class extends Error {
+  code = "LESSONS_DIR_OUTSIDE_PROJECT";
+  constructor(projectRoot) {
+    const base = lessonsPaths(projectRoot).base;
+    let where = "a path that does not exist";
+    try {
+      where = realpathSync(base).replaceAll("\\", "/");
+    } catch {
+    }
+    super(
+      `${base.replaceAll("\\", "/")} resolves to ${where}, outside the project ${projectRoot.replaceAll("\\", "/")}. agentsmesh only writes lessons inside the project; replace the link with a real folder.`
+    );
+    this.name = "LessonsDirOutsideProjectError";
+  }
+};
+function assertLessonsDirInsideProject(projectRoot) {
+  if (!lessonsDirInsideProject(projectRoot)) throw new LessonsDirOutsideProjectError(projectRoot);
+}
+
+// src/lessons/graph-store.ts
 var LESSONS_GRAPH_PATH = ".agentsmesh/lessons/lessons.json";
 function graphFilePath(projectRoot) {
   return resolve(projectRoot, LESSONS_GRAPH_PATH);
@@ -620,6 +729,7 @@ function isWritable(path) {
   }
 }
 function saveLessonsGraph(projectRoot, graph) {
+  assertLessonsDirInsideProject(projectRoot);
   const path = graphFilePath(projectRoot);
   mkdirSync(dirname(path), { recursive: true });
   const mode = fileMode(path);
@@ -693,42 +803,8 @@ function makeTriggerId2(spec) {
   const hash = createHash("sha1").update(`${spec.kind}|${spec.pattern}`).digest("hex").slice(0, 8);
   return `t-${TRIGGER_PREFIX2[spec.kind]}-${hash}`;
 }
-var RULE_HEADING_RE = /^##\s+Rules\b.*$/i;
-var NEXT_HEADING_RE = /^##\s+/;
-var RULE_LINE_RE = /^(\d+)\.\s+(.+?)\s*$/;
-var EVIDENCE_TAIL_RE = /\s*\(Evidence:?\s+([^)]+)\)\s*$/;
-var EVIDENCE_REF_RE = /L\d+/g;
-function parseRulesSection(markdown) {
-  const lines = markdown.split(/\r?\n/);
-  let inRules = false;
-  const rules = [];
-  for (const line of lines) {
-    if (!inRules) {
-      if (RULE_HEADING_RE.test(line)) inRules = true;
-      continue;
-    }
-    if (NEXT_HEADING_RE.test(line)) break;
-    const m = RULE_LINE_RE.exec(line);
-    if (m === null) continue;
-    const ruleIndex = Number(m[1]);
-    let body = m[2];
-    const evidence = [];
-    let tail = EVIDENCE_TAIL_RE.exec(body);
-    while (tail !== null) {
-      const refs = tail[1];
-      const matches = refs.match(EVIDENCE_REF_RE);
-      if (matches !== null) evidence.unshift(...matches);
-      body = body.slice(0, tail.index).trimEnd();
-      tail = EVIDENCE_TAIL_RE.exec(body);
-    }
-    rules.push({ index: ruleIndex, body, evidence });
-  }
-  return rules;
-}
 var LEGACY_ARTIFACT_REL = [
   "index.yaml",
-  "journal.md",
-  "journal.legacy.md",
   "topics",
   "distill-ledger.yaml",
   "distill-proposal.md"
@@ -1681,30 +1757,6 @@ function parseRemovals(out2) {
   }
   return { deleted, renamedAway };
 }
-var BASE_REL = ".agentsmesh/lessons";
-function lessonsPaths(projectRoot) {
-  const base = join(projectRoot, BASE_REL);
-  return {
-    base,
-    graph: join(base, "lessons.json"),
-    config: join(base, "config.json"),
-    journal: join(base, "journal.md"),
-    index: join(base, "index.yaml"),
-    topicsDir: join(base, "topics")
-  };
-}
-function toRelPath(projectRoot, absolute) {
-  return relative(projectRoot, absolute).split(sep).join("/");
-}
-var LESSONS_PROCEDURAL_RULE = `## Lessons (BLOCKING)
-
-Graph \`.agentsmesh/lessons/lessons.json\` is canonical; never hand-edit it. Manual: \`lessons\` skill.
-
-**Recall:** before every file edit or state-changing command, MUST run \`agentsmesh lessons query --file <path> --cmd <command> --session auto\` and obey matches; at task start, ALSO run \`agentsmesh lessons query --keyword "<task terms>" --always --session auto\` for conceptual + universal rules no path/command names. Pure-read commands and recall itself are exempt.
-
-**Capture:** after any failure, user correction, regression, wrong assumption, useful surprise, repeated friction, or non-obvious fix, MUST self-critique and run \`agentsmesh lessons add "<imperative rule>" --topic <id> --trigger-file <glob> --evidence <sha|lesson-id>\`.
-
-**Before final:** report \`Lesson: captured <id>\` or \`Lesson: none\`. No recall/capture gate = task incomplete. No shell: use \`lessons_query\` / \`lessons_add\`.`;
 
 // src/lessons/project-files.ts
 var SKIP_DIRS = /* @__PURE__ */ new Set([".git", "node_modules"]);
@@ -2448,6 +2500,7 @@ function lessonsLockPath(projectRoot) {
   return resolve(projectRoot, ".agentsmesh/lessons", LESSONS_LOCK_FILENAME);
 }
 async function acquireLessonsLock(projectRoot, opts = {}) {
+  assertLessonsDirInsideProject(projectRoot);
   return acquireProcessLock(lessonsLockPath(projectRoot), {
     retries: opts.retries ?? LESSONS_LOCK_OPTIONS.retries,
     retryDelayMs: opts.retryDelayMs ?? LESSONS_LOCK_OPTIONS.retryDelayMs,
@@ -2987,44 +3040,47 @@ async function mergeLegacy(projectRoot, paths, specs, summaryByTopic, options) {
     triggerCount: addedTriggers.size
   };
 }
-async function canonicalizePath(path) {
-  try {
-    return await realpath(path);
-  } catch (error) {
-    if (error.code !== "ENOENT") throw error;
-    const parent = dirname(path);
-    if (parent === path) return resolve(path);
-    return join(await canonicalizePath(parent), basename(path));
-  }
-}
-function isPathInside(target, root) {
-  return target === root || target.startsWith(root.endsWith(sep) ? root : `${root}${sep}`);
+
+// src/lessons/import-legacy-rules.ts
+var HEADING = /^#{1,6}\s/;
+var SECTION_HEADING = /^#{1,2}\s/;
+var RULES_HEADING = /^##\s+(?:Rules|Lessons)\b/i;
+var ITEM = /^\s{0,3}(?:\d+[.)]|[-*+])\s+(.+?)\s*$/;
+var EVIDENCE_TAIL = /\s*\(Evidence:?\s+([^)]+)\)\s*$/;
+var EVIDENCE_REF = /L\d+/g;
+function withEvidence(index, text) {
+  let body = text;
+  const evidence = [];
+  let tail = EVIDENCE_TAIL.exec(body);
+  while (tail !== null) {
+    evidence.unshift(...tail[1].match(EVIDENCE_REF) ?? []);
+    body = body.slice(0, tail.index).trimEnd();
+    tail = EVIDENCE_TAIL.exec(body);
+  }
+  return { index, body, evidence };
 }
-var display = (path) => path.replaceAll("\\", "/");
-async function assertPathInsideRoot(root, target) {
-  const rootAbs = resolve(root);
-  const targetAbs = resolve(target);
-  if (!isPathInside(targetAbs, rootAbs)) {
-    throw new Error(`Unsafe filesystem path: ${display(target)} is outside ${display(rootAbs)}`);
-  }
-  let realTarget;
-  let realRoot;
-  try {
-    [realTarget, realRoot] = await Promise.all([
-      canonicalizePath(targetAbs),
-      canonicalizePath(rootAbs)
-    ]);
-  } catch (cause) {
-    const detail = cause instanceof Error ? cause.message : String(cause);
-    throw new Error(
-      `Unsafe filesystem path: ${display(target)} could not be resolved (${detail})`,
-      { cause }
-    );
-  }
-  if (isPathInside(realTarget, realRoot)) return;
-  throw new Error(
-    `Unsafe filesystem path: ${display(target)} resolves to ${display(realTarget)} outside ${display(realRoot)}`
-  );
+function parseRulesSection(markdown) {
+  const items = [];
+  let inRules = false;
+  let open2 = false;
+  let strayLine = null;
+  markdown.split(/\r?\n/).forEach((line, i) => {
+    if (HEADING.test(line)) {
+      if (SECTION_HEADING.test(line)) inRules = RULES_HEADING.test(line);
+      open2 = false;
+      return;
+    }
+    const item = ITEM.exec(line);
+    if (item !== null) {
+      if (inRules) items.push(item[1]);
+      else strayLine ??= i + 1;
+      open2 = inRules;
+      return;
+    }
+    if (line.trim() === "") open2 = false;
+    else if (open2) items[items.length - 1] += ` ${line.trim()}`;
+  });
+  return { rules: items.map((text, i) => withEvidence(i + 1, text)), strayLine };
 }
 
 // src/lessons/import-legacy-read.ts
@@ -3071,9 +3127,13 @@ async function readLegacySource(projectRoot, migratedAt) {
         `Legacy topic file is missing: ${cluster.file}. Refusing to migrate (legacy artifacts left intact).`
       );
     }
-    for (const { index: ruleIndex, body, evidence } of parseRulesSection(
-      readFileSync(topicFile, "utf8")
-    )) {
+    const parsed = parseRulesSection(readFileSync(topicFile, "utf8"));
+    if (parsed.strayLine !== null) {
+      throw new Error(
+        `Legacy lessons were not migrated: ${cluster.file} line ${parsed.strayLine} is a list item outside a "## Rules" or "## Lessons" section. Move it under one of them or delete it, then run \`agentsmesh lessons import-md\`. Nothing was changed.`
+      );
+    }
+    for (const { index: ruleIndex, body, evidence } of parsed.rules) {
       const lessonEvidence = [
         `legacy:${cluster.file}#rule-${ruleIndex}`,
         ...evidence.map((e) => `legacy:${e}`)
@@ -3477,7 +3537,7 @@ function isTelemetryEnabled(env = process.env, projectRoot) {
   return envOverride(env[TELEMETRY_ENV]) ?? (projectRoot !== void 0 && configFlag(projectRoot, "telemetry") === true);
 }
 function appendRecallRecord(projectRoot, record, env = process.env) {
-  if (!isTelemetryEnabled(env, projectRoot)) return;
+  if (!isTelemetryEnabled(env, projectRoot) || !lessonsDirInsideProject(projectRoot)) return;
   appendJsonl(recallLogPath(projectRoot), record, {
     maxRecords: MAX_RECALL_LOG_RECORDS,
     trimTriggerBytes: RECALL_LOG_TRIM_TRIGGER_BYTES
@@ -4072,7 +4132,7 @@ var EMPTY = { ids: /* @__PURE__ */ new Set(), stamps: null };
 // src/lessons/recall.ts
 async function recallLessons(projectRoot, query, options = {}) {
   try {
-    await maybeAutoMigrateLessons(projectRoot);
+    if (options.autoMigrate !== false) await maybeAutoMigrateLessons(projectRoot);
   } catch {
   }
   const preReadStamp = currentGraphStamp(projectRoot);
@@ -4226,7 +4286,7 @@ function captureLogPath(projectRoot) {
   return join(lessonsPaths(projectRoot).base, "capture-log.jsonl");
 }
 function appendCaptureRecord(projectRoot, record, env = process.env) {
-  if (!isTelemetryEnabled(env, projectRoot)) return;
+  if (!isTelemetryEnabled(env, projectRoot) || !lessonsDirInsideProject(projectRoot)) return;
   appendJsonl(captureLogPath(projectRoot), record, {
     maxRecords: MAX_CAPTURE_LOG_RECORDS,
     trimTriggerBytes: CAPTURE_LOG_TRIM_TRIGGER_BYTES
@@ -4665,11 +4725,13 @@ ${yamlStr}
 
 ${body}`;
 }
-var LESSONS_CONTRACT_START = "<!-- agentsmesh:lessons-contract:start -->";
-var LESSONS_CONTRACT_END = "<!-- agentsmesh:lessons-contract:end -->";
 function escapeRegExp(value) {
   return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+
+// src/targets/projection/managed-blocks.ts
+var LESSONS_CONTRACT_START = "<!-- agentsmesh:lessons-contract:start -->";
+var LESSONS_CONTRACT_END = "<!-- agentsmesh:lessons-contract:end -->";
 function managedBlockPattern(start, end) {
   return new RegExp(`${escapeRegExp(start)}[\\s\\S]*?${escapeRegExp(end)}`, "g");
 }
@@ -4814,6 +4876,7 @@ async function scaffoldLessons(projectRoot) {
   const created = [];
   const updated = [];
   const skipped = [];
+  assertLessonsDirInsideProject(projectRoot);
   mkdirSync(paths.base, { recursive: true });
   await maybeAutoMigrateLessons(projectRoot);
   if (existsSync(paths.graph)) {