agentsmesh 0.35.0 → 0.37.0

package/dist/{init-C3pMnqoU.d.ts → init-BtgoRmIs.d.ts}

@@ -84,6 +84,8 @@ interface LessonsQuery {
 interface MatchedLesson {
     readonly id: string;
     readonly lesson: Lesson;
+    /** Set when the lesson was reached by its wording, not a trigger (lexical retrieval). */
+    readonly lexical?: true;
 }
 /**
  * Recall primitive — returns every active lesson whose triggers match any of
@@ -98,6 +100,8 @@ interface RankReason {
     readonly bm25: number;
     readonly specificity: number;
     readonly topicCoherence: number;
+    /** Reached by rule wording rather than a trigger (see lexical-retrieval.ts). */
+    readonly lexical?: true;
 }
 interface RankedLesson {
     readonly id: string;
@@ -379,13 +383,8 @@ declare function importLegacyLessons(projectRoot: string, options: ImportLegacyO
 /**
  * Cross-platform process lock backed by an atomic mkdir.
  *
- * Acquire semantics: mkdir with no `recursive` option is atomic per POSIX and
- * returns EEXIST if the directory already exists. That makes it a reliable
- * cross-process mutex without any third-party dependency.
- *
  * Stale recovery: the holder writes its PID and start timestamp into the lock
- * dir. On contention we peek at the PID: a dead same-host holder is evicted at
- * once. A live holder (or one on another host, whose PID we cannot probe) is
+ * dir. A dead same-host holder is evicted at once. A live or remote holder is
  * evicted only past `staleMs` — an hours-long bound that catches a hung
  * process or a recycled PID, never a slow but healthy run.
  */

package/dist/lessons.d.ts

@@ -1,5 +1,5 @@
-import { o as RankedLesson, j as LessonsQuery, A as AddLessonInput, a as AddLessonOptions, b as AddLessonResult } from './init-C3pMnqoU.js';
-export { c as AddLessonTriggers, D as DEFAULT_RECALL_LIMIT, X as DEFAULT_RECALL_MAX_TOKENS, I as ImportLegacyOptions, d as ImportLegacyReport, Y as LESSONS_LOCK_FILENAME, L as LESSONS_PROCEDURAL_RULE, e as Lesson, f as LessonStatus, g as LessonsGraph, Z as LessonsGraphExistsError, h as LessonsGraphSchema, i as LessonsPaths, M as MatchedLesson, k as MergeLessonsOptions, l as MergeLessonsResult, m as MutateOptions, R as RankOptions, n as RankReason, S as ScaffoldLessonsResult, p as StripMarkersOptions, q as StripMarkersReport, T as Topic, r as Trigger, s as TriggerKind, U as UnknownTopicError, V as ValidationFinding, t as ValidationLevel, u as ValidationReport, v as acquireLessonsLock, w as addLesson, x as graphFilePath, y as importLegacyLessons, _ as lessonsLockPath, z as lessonsPaths, B as loadLessonsGraph, C as mergeLessons, E as mutateLessonsGraph, F as parseGraph, G as queryLessons, H as rankLessons, J as scaffoldLessons, K as serializeGraph, N as stripLegacyMarkers, O as stripMarkersInGraph, P as toRelPath, Q as tryLoadLessonsGraph, W as validateLessonsGraph } from './init-C3pMnqoU.js';
+import { o as RankedLesson, j as LessonsQuery, A as AddLessonInput, a as AddLessonOptions, b as AddLessonResult } from './init-BtgoRmIs.js';
+export { c as AddLessonTriggers, D as DEFAULT_RECALL_LIMIT, X as DEFAULT_RECALL_MAX_TOKENS, I as ImportLegacyOptions, d as ImportLegacyReport, Y as LESSONS_LOCK_FILENAME, L as LESSONS_PROCEDURAL_RULE, e as Lesson, f as LessonStatus, g as LessonsGraph, Z as LessonsGraphExistsError, h as LessonsGraphSchema, i as LessonsPaths, M as MatchedLesson, k as MergeLessonsOptions, l as MergeLessonsResult, m as MutateOptions, R as RankOptions, n as RankReason, S as ScaffoldLessonsResult, p as StripMarkersOptions, q as StripMarkersReport, T as Topic, r as Trigger, s as TriggerKind, U as UnknownTopicError, V as ValidationFinding, t as ValidationLevel, u as ValidationReport, v as acquireLessonsLock, w as addLesson, x as graphFilePath, y as importLegacyLessons, _ as lessonsLockPath, z as lessonsPaths, B as loadLessonsGraph, C as mergeLessons, E as mutateLessonsGraph, F as parseGraph, G as queryLessons, H as rankLessons, J as scaffoldLessons, K as serializeGraph, N as stripLegacyMarkers, O as stripMarkersInGraph, P as toRelPath, Q as tryLoadLessonsGraph, W as validateLessonsGraph } from './init-BtgoRmIs.js';
 import 'zod';
 
 /**

package/dist/lessons.js

@@ -2,11 +2,11 @@ import { z } from 'zod';
 import { readFileSync, existsSync, mkdirSync, writeFileSync, rmSync, statSync, renameSync, readdirSync, realpathSync, appendFileSync } from 'fs';
 import { resolve, dirname, join, relative, sep, basename, extname } from 'path';
 import { stringify, parse, parseDocument, YAMLSeq, YAMLMap } from 'yaml';
-import { createHash } from 'crypto';
+import { createHash, randomUUID } from 'crypto';
 import picomatch from 'picomatch';
-import { mkdir, rm, writeFile, readFile, stat, lstat, unlink, rename, chmod } from 'fs/promises';
+import { mkdir, rm, writeFile, readFile, stat, lstat, open, rename } from 'fs/promises';
 import { tmpdir, hostname } from 'os';
-import 'timers/promises';
+import { setTimeout as setTimeout$1 } from 'timers/promises';
 
 // src/lessons/graph-schema.ts
 var CURRENT_GRAPH_VERSION = 2;
@@ -1190,8 +1190,7 @@ async function acquireProcessLock(lockPath, opts = {}) {
     if (acquired) return acquired;
     const existing = await inspectLock(lockPath);
     if (existing !== "young" && isStale(existing, stale)) {
-      await rm(lockPath, { recursive: true, force: true }).catch(() => {
-      });
+      await rm(lockPath, { recursive: true, force: true });
       continue;
     }
     if (attempt >= retries) {
@@ -1215,7 +1214,13 @@ async function tryAcquire(lockPath) {
     started: Date.now(),
     hostname: getHostname()
   };
-  await writeFile(metadataPath, JSON.stringify(metadata), "utf-8");
+  try {
+    await writeFile(metadataPath, JSON.stringify(metadata), "utf-8");
+  } catch (error) {
+    await rm(lockPath, { recursive: true, force: true }).catch(() => {
+    });
+    throw error;
+  }
   let released = false;
   const cleanup = () => {
     if (released) return;
@@ -2169,6 +2174,42 @@ function safeRealpath(path) {
   }
 }
 
+// src/lessons/lexical-retrieval.ts
+var LEXICAL_LIMIT = 3;
+var LEXICAL_MIN_TERMS = 2;
+var GENERIC = new Set(
+  "top left right bottom before after first last next new old use used using run make keep set get add all any each every not no never always only one two more less same other than then into from over under out up down off via per so if else when where which what who how why do does did done can could should would will may might has have had are was were been being also still just even very both either such these those they them their we you your our he she his her my me our us own same here there now then again once about above below between during through until while because but by need needs needed way ways thing things".split(" ")
+);
+function isKeywordOnlyQuery(query) {
+  return query.keyword !== void 0 && query.file === void 0 && query.command === void 0;
+}
+function matchLessons(graph, query) {
+  const triggered = queryLessons(graph, query);
+  const lexical = isKeywordOnlyQuery(query) && query.keyword !== void 0 ? lexicalCandidates(
+    graph,
+    query.keyword,
+    triggered.map((m) => m.id)
+  ) : [];
+  return { matches: [...triggered, ...lexical], lexicalCount: lexical.length };
+}
+function lexicalCandidates(graph, keyword, excludeIds) {
+  const terms = [...new Set(tokenize(keyword))];
+  if (terms.length < LEXICAL_MIN_TERMS) return [];
+  const excluded = new Set(excludeIds);
+  const corpus = buildCorpus(graph);
+  const scored = [];
+  for (const [id, lesson] of Object.entries(graph.lessons)) {
+    if (lesson.status !== "active" || lesson.scope === "always" || excluded.has(id)) continue;
+    const ruleTerms = new Set(tokenize(lesson.rule));
+    let shared = 0;
+    for (const t of terms) if (!GENERIC.has(t) && ruleTerms.has(t)) shared += 1;
+    if (shared < LEXICAL_MIN_TERMS) continue;
+    scored.push({ id, lesson, score: bm25(terms, lesson.rule, corpus) });
+  }
+  scored.sort((a, b) => b.score !== a.score ? b.score - a.score : a.id < b.id ? -1 : 1);
+  return scored.slice(0, LEXICAL_LIMIT).map(({ id, lesson }) => ({ id, lesson, lexical: true }));
+}
+
 // src/lessons/ranking-signals.ts
 function buildFanout(graph) {
   const fanout = /* @__PURE__ */ new Map();
@@ -2235,7 +2276,7 @@ function rankLessons(graph, query, matches, options = {}) {
   const narrowness = buildNarrowness(graph);
   const coherence = buildTopicCoherence(matches);
   const matchedTriggerIds = collectMatchedTriggerIds(graph, query);
-  const scored = matches.map(({ id, lesson }) => {
+  const scored = matches.map(({ id, lesson, lexical }) => {
     const hitTriggers = lesson.triggers.filter((t) => matchedTriggerIds.has(t));
     let specificity = 0;
     for (const t of hitTriggers) {
@@ -2251,7 +2292,8 @@ function rankLessons(graph, query, matches, options = {}) {
       matchedTriggers: hitTriggers,
       // Absent from the log ⇒ neutral 1, so a lesson with no outcome data never
       // sinks below one that has merely been recorded.
-      effectiveness: options.effectiveness?.get(id) ?? 1
+      effectiveness: options.effectiveness?.get(id) ?? 1,
+      lexical
     };
   });
   const bm25Ranks = rankMap(scored.map((s) => ({ id: s.id, value: s.bm25 })));
@@ -2266,7 +2308,8 @@ function rankLessons(graph, query, matches, options = {}) {
       matchedTriggers: s.matchedTriggers,
       bm25: s.bm25,
       specificity: s.specificity,
-      topicCoherence: s.topicCoherence
+      topicCoherence: s.topicCoherence,
+      ...s.lexical === true ? { lexical: true } : {}
     }
   })).sort((a, b) => {
     if (b.score !== a.score) return b.score - a.score;
@@ -2324,6 +2367,33 @@ function loadRecallConfig(projectRoot) {
     return fallback;
   }
 }
+
+// src/lessons/recall-telemetry.ts
+function recordRecallTelemetry(projectRoot, graph, query, matches, lessons, options = {}) {
+  if (!isTelemetryEnabled(process.env, projectRoot)) return;
+  const byKind = collectMatchedTriggersByKind(graph, query);
+  const countVia = (set) => matches.filter(({ lesson }) => lesson.triggers.some((t) => set.has(t))).length;
+  const session = options.session ?? sessionId();
+  appendRecallRecord(projectRoot, {
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    hasFile: query.file !== void 0,
+    hasCommand: query.command !== void 0,
+    hasKeyword: query.keyword !== void 0,
+    totalMatches: matches.length,
+    returnedCount: lessons.length,
+    returnedTokens: lessons.reduce((sum, l) => sum + estTokens(l.lesson.rule), 0),
+    truncated: matches.length > lessons.length,
+    matchedByKind: {
+      file: countVia(byKind.file_glob),
+      command: countVia(byKind.command_pattern),
+      keyword: countVia(byKind.keyword),
+      ...options.lexical !== void 0 ? { text: options.lexical } : {}
+    },
+    lessonIds: lessons.map((l) => l.id),
+    bypassed: options.bypassed === true,
+    ...session !== void 0 ? { session } : {}
+  });
+}
 function outcomeLogPath(projectRoot) {
   return join(lessonsPaths(projectRoot).base, "outcome-log.jsonl");
 }
@@ -2490,7 +2560,7 @@ async function recallLessons(projectRoot, query, options = {}) {
   const graph = load.graph;
   refreshCommandFastpath(projectRoot, graph, preReadStamp);
   const matchQuery = query.file === void 0 ? query : { ...query, file: normalizeRecallFile(query.file, projectRoot) };
-  const matches = queryLessons(graph, matchQuery);
+  const { matches, lexicalCount } = matchLessons(graph, matchQuery);
   const dedup = openSessionDedup({
     explicit: options.sessionId,
     disabled: options.noDedup,
@@ -2515,34 +2585,11 @@ async function recallLessons(projectRoot, query, options = {}) {
     );
   recordRecallTelemetry(projectRoot, graph, matchQuery, matches, lessons, {
     bypassed: false,
-    session: options.sessionId
+    session: options.sessionId,
+    lexical: lexicalCount
   });
   return { lessons, totalMatches: matches.length, suppressed: matches.length - forRank.length };
 }
-function recordRecallTelemetry(projectRoot, graph, query, matches, lessons, options = {}) {
-  if (!isTelemetryEnabled(process.env, projectRoot)) return;
-  const byKind = collectMatchedTriggersByKind(graph, query);
-  const countVia = (set) => matches.filter(({ lesson }) => lesson.triggers.some((t) => set.has(t))).length;
-  const session = options.session ?? sessionId();
-  appendRecallRecord(projectRoot, {
-    ts: (/* @__PURE__ */ new Date()).toISOString(),
-    hasFile: query.file !== void 0,
-    hasCommand: query.command !== void 0,
-    hasKeyword: query.keyword !== void 0,
-    totalMatches: matches.length,
-    returnedCount: lessons.length,
-    returnedTokens: lessons.reduce((sum, l) => sum + estTokens(l.lesson.rule), 0),
-    truncated: matches.length > lessons.length,
-    matchedByKind: {
-      file: countVia(byKind.file_glob),
-      command: countVia(byKind.command_pattern),
-      keyword: countVia(byKind.keyword)
-    },
-    lessonIds: lessons.map((l) => l.id),
-    bypassed: options.bypassed === true,
-    ...session !== void 0 ? { session } : {}
-  });
-}
 
 // src/lessons/prune.ts
 function planPrune(graph, options = {}) {
@@ -2996,6 +3043,91 @@ function shouldNormalizeLineEndings(path) {
   const base = basename(path).toLowerCase();
   return TEXT_DOTFILES.has(base);
 }
+var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".bmp",
+  ".ico",
+  ".webp",
+  ".avif",
+  ".tiff",
+  ".pdf",
+  ".zip",
+  ".gz",
+  ".tgz",
+  ".bz2",
+  ".xz",
+  ".7z",
+  ".rar",
+  ".jar",
+  ".woff",
+  ".woff2",
+  ".ttf",
+  ".otf",
+  ".eot",
+  ".mp3",
+  ".mp4",
+  ".wav",
+  ".ogg",
+  ".webm",
+  ".mov",
+  ".wasm",
+  ".bin",
+  ".dat",
+  ".db",
+  ".sqlite",
+  ".so",
+  ".dylib",
+  ".dll",
+  ".exe",
+  ".class",
+  ".pyc",
+  // Office and design documents are zip or proprietary containers.
+  ".xlsx",
+  ".xls",
+  ".docx",
+  ".doc",
+  ".pptx",
+  ".ppt",
+  ".odt",
+  ".ods",
+  ".psd",
+  ".ai",
+  ".sketch",
+  ".fig",
+  ".heic",
+  ".heif",
+  // Archives, columnar data, models and compressed payloads.
+  ".tar",
+  ".zst",
+  ".br",
+  ".lz4",
+  ".parquet",
+  ".avro",
+  ".orc",
+  ".pkl",
+  ".npy",
+  ".npz",
+  ".onnx",
+  ".pt",
+  ".safetensors",
+  ".gguf",
+  ".sqlite3",
+  ".avi",
+  ".mkv",
+  ".flac",
+  ".aac",
+  ".m4a",
+  ".ttc"
+]);
+function isBinaryPayloadPath(path) {
+  return BINARY_EXTENSIONS.has(extname(path).toLowerCase());
+}
+function payloadEncodingFor(path) {
+  return isBinaryPayloadPath(path) ? "latin1" : "utf-8";
+}
 function normalizeLineEndings(content) {
   return content.replace(/\r\n?/g, "\n");
 }
@@ -3003,11 +3135,28 @@ var EXECUTABLE_SCRIPT_EXTENSIONS = /* @__PURE__ */ new Set([".sh", ".bash", ".zs
 function executableModeFor(path) {
   return EXECUTABLE_SCRIPT_EXTENSIONS.has(extname(path).toLowerCase()) ? 493 : void 0;
 }
+var TRANSIENT_RENAME_CODES = /* @__PURE__ */ new Set(["EPERM", "EACCES", "EBUSY", "ENOTEMPTY", "EEXIST"]);
+async function renameWithRetry(from, to, options = {}) {
+  const attempts = options.attempts ?? 5;
+  const delayMs = options.delayMs ?? 50;
+  for (let attempt = 0; ; attempt++) {
+    try {
+      await rename(from, to);
+      return;
+    } catch (err) {
+      const code = err.code;
+      const transient = code !== void 0 && TRANSIENT_RENAME_CODES.has(code);
+      if (!transient || attempt >= attempts - 1) throw err;
+      await setTimeout$1(delayMs * 2 ** attempt);
+    }
+  }
+}
 
 // src/utils/filesystem/fs.ts
 async function readFileSafe(path) {
   try {
-    const data = await readFile(path, "utf-8");
+    const data = await readFile(path, payloadEncodingFor(path));
+    if (isBinaryPayloadPath(path)) return data;
     return data.startsWith(UTF8_BOM) ? data.slice(UTF8_BOM.length) : data;
   } catch (err) {
     const e = err;
@@ -3031,40 +3180,28 @@ async function writeFileAtomic(path, content, options) {
         { errnoCode: "EISDIR" }
       );
     }
-    if (info.isSymbolicLink()) {
-      await unlink(path).catch((e) => {
-        if (e.code !== "ENOENT") throw e;
-      });
-    }
   } catch (err) {
     if (err instanceof FileSystemError) throw err;
     const e = err;
     if (e.code !== "ENOENT") throw err;
   }
-  const tmpPath = `${path}.tmp`;
+  const tmpPath = `${path}.tmp-${randomUUID()}`;
   const payload = shouldNormalizeLineEndings(path) ? normalizeLineEndings(content) : content;
   const mode = executableModeFor(path);
+  let handle;
+  let ownsTemporaryFile = false;
   try {
-    try {
-      const tmpInfo = await lstat(tmpPath);
-      if (tmpInfo.isSymbolicLink()) {
-        await unlink(tmpPath);
-      }
-    } catch (tmpErr) {
-      if (tmpErr.code !== "ENOENT") throw tmpErr;
-    }
-    const writeOpts = {
-      encoding: "utf-8",
-      flag: "w"
-    };
-    if (mode !== void 0) writeOpts.mode = mode;
-    await writeFile(tmpPath, payload, writeOpts);
-    await rename(tmpPath, path);
-    if (mode !== void 0) {
-      await chmod(path, mode);
-    }
+    handle = await open(tmpPath, "wx", mode);
+    ownsTemporaryFile = true;
+    await handle.writeFile(payload, payloadEncodingFor(path));
+    if (mode !== void 0) await handle.chmod(mode);
+    await handle.close();
+    handle = void 0;
+    await renameWithRetry(tmpPath, path);
   } catch (err) {
-    await rm(tmpPath, { force: true }).catch(() => {
+    await handle?.close().catch(() => {
+    });
+    if (ownsTemporaryFile) await rm(tmpPath, { force: true }).catch(() => {
     });
     const e = err;
     throw new FileSystemError(