la-machina-engine 0.7.0 → 0.7.1

package/README.md

@@ -1181,6 +1181,15 @@ await writeKnowledgeIndex({ adapter: k, base: 'hr-policies' })
 await writeKnowledgeIndex({ adapter: k, base: 'sales-playbook' })
 ```
 
+**Forgot to build the index?** Both tools fall back to an in-memory
+build on first call when `_index.json` is missing or corrupted. The
+fallback caches for the rest of the run, so subsequent searches are
+free. This makes the index a performance optimisation (skip the walk
+on every fresh run), not a setup requirement — drop files into the
+folder and the agent can discover them immediately. Pre-build with
+`writeKnowledgeIndex()` for production-scale corpora where the
+first-call cost matters.
+
 **Configure the engine** to enable the tools (off by default):
 
 ```ts

package/dist/index.cjs

@@ -8201,75 +8201,8 @@ init_cjs_shims();
 var import_zod26 = require("zod");
 init_contract();
 
-// src/knowledge/scope.ts
+// src/knowledge/indexer.ts
 init_cjs_shims();
-var SAFE_PATH_RE = /^[a-zA-Z0-9_\-./]+$/;
-function parseFolderRef(raw) {
-  if (typeof raw !== "string" || raw.length === 0) {
-    throw new Error(`invalid knowledge folder ref: empty`);
-  }
-  if (raw.startsWith("/")) {
-    throw new Error(`invalid knowledge folder ref: absolute paths not allowed ("${raw}")`);
-  }
-  const trimmed = raw.replace(/\/+$/g, "");
-  if (trimmed.length === 0) {
-    throw new Error(`invalid knowledge folder ref: "${raw}"`);
-  }
-  if (!SAFE_PATH_RE.test(trimmed)) {
-    throw new Error(`invalid knowledge folder ref: unsafe characters in "${raw}"`);
-  }
-  if (trimmed.split("/").some((seg) => seg === ".." || seg === "." || seg === "")) {
-    throw new Error(`invalid knowledge folder ref: traversal in "${raw}"`);
-  }
-  const segs = trimmed.split("/");
-  const base = segs[0];
-  const subPath = segs.slice(1).join("/");
-  return { path: trimmed, base, subPath };
-}
-function relPathInScope(folder, relPath) {
-  if (folder.subPath === "") return true;
-  return relPath === folder.subPath || relPath.startsWith(`${folder.subPath}/`);
-}
-function parseKnowledgeRef(raw) {
-  if (typeof raw !== "string" || raw.length === 0) {
-    throw new Error("invalid knowledge ref: empty");
-  }
-  if (raw.startsWith("ext:")) {
-    const name = raw.slice("ext:".length);
-    if (!/^[a-zA-Z0-9_-]+$/.test(name) || name.length === 0) {
-      throw new Error(`invalid knowledge ref: external name "${name}" has unsafe characters`);
-    }
-    return { kind: "ext", target: name };
-  }
-  if (raw.startsWith("/")) {
-    throw new Error(`invalid knowledge ref: absolute paths not allowed ("${raw}")`);
-  }
-  const hashAt = raw.indexOf("#");
-  const filePath = hashAt === -1 ? raw : raw.slice(0, hashAt);
-  const section = hashAt === -1 ? void 0 : raw.slice(hashAt + 1);
-  if (!SAFE_PATH_RE.test(filePath)) {
-    throw new Error(`invalid knowledge ref: unsafe characters in "${filePath}"`);
-  }
-  if (filePath.split("/").some((seg) => seg === ".." || seg === "." || seg === "")) {
-    throw new Error(`invalid knowledge ref: traversal in "${filePath}"`);
-  }
-  if (section !== void 0) {
-    if (section.length > 0 && !/^[a-zA-Z0-9_-]+$/.test(section)) {
-      throw new Error(`invalid knowledge ref: unsafe characters in section "${section}"`);
-    }
-    return { kind: "section", target: filePath, section };
-  }
-  return { kind: "file", target: filePath };
-}
-function refInScope(folders, filePath) {
-  return folders.some((f) => {
-    if (filePath === f.base || filePath.startsWith(`${f.base}/`)) {
-      const relInBase = filePath === f.base ? "" : filePath.slice(f.base.length + 1);
-      return relPathInScope(f, relInBase);
-    }
-    return false;
-  });
-}
 
 // src/knowledge/tokenize.ts
 init_cjs_shims();
@@ -8346,6 +8279,220 @@ function scoreOverlap(sectionWords, queryTokens) {
   return n;
 }
 
+// src/knowledge/indexer.ts
+var HEADING_RE = /^(#{1,6})[ \t]+(.+?)\s*$/;
+var WIKI_LINK_RE = /\[\[([^\]|#]+)(?:[#|][^\]]*)?\]\]/g;
+var FORMAT_BY_EXT = {
+  md: "md",
+  markdown: "md",
+  txt: "txt",
+  json: "json",
+  csv: "csv",
+  html: "html",
+  htm: "html",
+  pdf: "pdf",
+  docx: "docx"
+};
+var PREVIEW_CHARS = 200;
+async function buildKnowledgeIndex(options) {
+  const { adapter, base } = options;
+  const safeBase = base.replace(/^\/+|\/+$/g, "");
+  if (safeBase.length === 0 || safeBase.includes("..")) {
+    throw new Error(`buildKnowledgeIndex: invalid base "${base}"`);
+  }
+  const files = await listFilesRecursive(adapter, safeBase);
+  const sections = [];
+  const filesMeta = {};
+  for (const fileRel of files) {
+    if (fileRel === "_index.json") continue;
+    const fullPath = `${safeBase}/${fileRel}`;
+    const ext = (fileRel.split(".").pop() ?? "").toLowerCase();
+    const format = FORMAT_BY_EXT[ext];
+    if (format === void 0) continue;
+    const raw = await adapter.readFile(fullPath);
+    if (raw === null) continue;
+    const sizeBytes = byteLength3(raw);
+    const meta = { format, size: sizeBytes };
+    if (format === "md" || format === "txt") {
+      const fileSections = splitSections(raw, fileRel);
+      sections.push(...fileSections);
+      const wikiLinks = extractWikiLinks(raw);
+      if (wikiLinks.length > 0) meta.wikiLinks = wikiLinks;
+    }
+    filesMeta[fileRel] = meta;
+  }
+  return {
+    schema: "v1",
+    base: safeBase,
+    builtAt: options.nowIso ?? (/* @__PURE__ */ new Date()).toISOString(),
+    fileCount: Object.keys(filesMeta).length,
+    sections,
+    files: filesMeta
+  };
+}
+async function writeKnowledgeIndex(options) {
+  const index = await buildKnowledgeIndex(options);
+  await options.adapter.writeFile(`${index.base}/_index.json`, JSON.stringify(index, null, 2));
+  return index;
+}
+async function listFilesRecursive(adapter, dir) {
+  const out = [];
+  const stack = [""];
+  while (stack.length > 0) {
+    const sub = stack.pop();
+    const fullDir = sub === "" ? dir : `${dir}/${sub}`;
+    let entries = [];
+    try {
+      entries = await adapter.listDir(fullDir);
+    } catch {
+      continue;
+    }
+    for (const name of entries) {
+      const childRel = sub === "" ? name : `${sub}/${name}`;
+      const childFull = `${dir}/${childRel}`;
+      const isDir = await adapter.isDirectory(childFull).catch(() => false);
+      if (isDir) {
+        stack.push(childRel);
+      } else {
+        out.push(childRel);
+      }
+    }
+  }
+  return out.sort();
+}
+function splitSections(content, relPath) {
+  const lines = content.split(/\r?\n/);
+  const out = [];
+  const heads = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const m = HEADING_RE.exec(line);
+    if (m) heads.push({ line: i + 1, depth: m[1].length, heading: m[2].trim() });
+  }
+  const leadInEndLine = heads.length > 0 ? heads[0].line - 1 : lines.length;
+  const leadInBody = lines.slice(0, leadInEndLine).join("\n").trim();
+  if (leadInBody.length > 0) {
+    out.push({
+      relPath,
+      heading: "",
+      slug: `${relPath}#`,
+      depth: 0,
+      words: tokenize(leadInBody),
+      preview: makePreview(leadInBody),
+      startLine: 1,
+      endLine: leadInEndLine
+    });
+  }
+  for (let i = 0; i < heads.length; i++) {
+    const h = heads[i];
+    const startLine = h.line;
+    const endLine = i + 1 < heads.length ? heads[i + 1].line - 1 : lines.length;
+    const body = lines.slice(startLine - 1, endLine).join("\n");
+    out.push({
+      relPath,
+      heading: h.heading,
+      slug: `${relPath}#${slugify(h.heading)}`,
+      depth: h.depth,
+      words: tokenize(body),
+      preview: makePreview(body),
+      startLine,
+      endLine
+    });
+  }
+  return out;
+}
+function makePreview(body) {
+  const trimmed = body.replace(/^#{1,6}\s+.+$\r?\n?/m, "").trim();
+  if (trimmed.length <= PREVIEW_CHARS) return trimmed;
+  return trimmed.slice(0, PREVIEW_CHARS) + "\u2026";
+}
+function slugify(text2) {
+  return text2.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function extractWikiLinks(text2) {
+  const seen = /* @__PURE__ */ new Set();
+  let m;
+  WIKI_LINK_RE.lastIndex = 0;
+  while ((m = WIKI_LINK_RE.exec(text2)) !== null) {
+    const target = m[1].trim();
+    if (target.length > 0) seen.add(target);
+  }
+  return [...seen].sort();
+}
+function byteLength3(s) {
+  return new TextEncoder().encode(s).byteLength;
+}
+
+// src/knowledge/scope.ts
+init_cjs_shims();
+var SAFE_PATH_RE = /^[a-zA-Z0-9_\-./]+$/;
+function parseFolderRef(raw) {
+  if (typeof raw !== "string" || raw.length === 0) {
+    throw new Error(`invalid knowledge folder ref: empty`);
+  }
+  if (raw.startsWith("/")) {
+    throw new Error(`invalid knowledge folder ref: absolute paths not allowed ("${raw}")`);
+  }
+  const trimmed = raw.replace(/\/+$/g, "");
+  if (trimmed.length === 0) {
+    throw new Error(`invalid knowledge folder ref: "${raw}"`);
+  }
+  if (!SAFE_PATH_RE.test(trimmed)) {
+    throw new Error(`invalid knowledge folder ref: unsafe characters in "${raw}"`);
+  }
+  if (trimmed.split("/").some((seg) => seg === ".." || seg === "." || seg === "")) {
+    throw new Error(`invalid knowledge folder ref: traversal in "${raw}"`);
+  }
+  const segs = trimmed.split("/");
+  const base = segs[0];
+  const subPath = segs.slice(1).join("/");
+  return { path: trimmed, base, subPath };
+}
+function relPathInScope(folder, relPath) {
+  if (folder.subPath === "") return true;
+  return relPath === folder.subPath || relPath.startsWith(`${folder.subPath}/`);
+}
+function parseKnowledgeRef(raw) {
+  if (typeof raw !== "string" || raw.length === 0) {
+    throw new Error("invalid knowledge ref: empty");
+  }
+  if (raw.startsWith("ext:")) {
+    const name = raw.slice("ext:".length);
+    if (!/^[a-zA-Z0-9_-]+$/.test(name) || name.length === 0) {
+      throw new Error(`invalid knowledge ref: external name "${name}" has unsafe characters`);
+    }
+    return { kind: "ext", target: name };
+  }
+  if (raw.startsWith("/")) {
+    throw new Error(`invalid knowledge ref: absolute paths not allowed ("${raw}")`);
+  }
+  const hashAt = raw.indexOf("#");
+  const filePath = hashAt === -1 ? raw : raw.slice(0, hashAt);
+  const section = hashAt === -1 ? void 0 : raw.slice(hashAt + 1);
+  if (!SAFE_PATH_RE.test(filePath)) {
+    throw new Error(`invalid knowledge ref: unsafe characters in "${filePath}"`);
+  }
+  if (filePath.split("/").some((seg) => seg === ".." || seg === "." || seg === "")) {
+    throw new Error(`invalid knowledge ref: traversal in "${filePath}"`);
+  }
+  if (section !== void 0) {
+    if (section.length > 0 && !/^[a-zA-Z0-9_-]+$/.test(section)) {
+      throw new Error(`invalid knowledge ref: unsafe characters in section "${section}"`);
+    }
+    return { kind: "section", target: filePath, section };
+  }
+  return { kind: "file", target: filePath };
+}
+function refInScope(folders, filePath) {
+  return folders.some((f) => {
+    if (filePath === f.base || filePath.startsWith(`${f.base}/`)) {
+      const relInBase = filePath === f.base ? "" : filePath.slice(f.base.length + 1);
+      return relPathInScope(f, relInBase);
+    }
+    return false;
+  });
+}
+
 // src/tools/searchKnowledge.ts
 var DEFAULT_MAX_RESULTS = 5;
 var inputSchema18 = import_zod26.z.object({
@@ -8430,17 +8577,24 @@ function truncatePreview(s) {
 async function loadIndex(adapter, base, cache) {
   const cached2 = cache.get(base);
   if (cached2 !== void 0) return cached2;
-  let raw;
+  let raw = null;
   try {
     raw = await adapter.readFile(`${base}/_index.json`);
   } catch {
-    return null;
+    raw = null;
+  }
+  if (raw !== null) {
+    try {
+      const parsed = JSON.parse(raw);
+      cache.set(base, parsed);
+      return parsed;
+    } catch {
+    }
   }
-  if (raw === null) return null;
   try {
-    const parsed = JSON.parse(raw);
-    cache.set(base, parsed);
-    return parsed;
+    const built = await buildKnowledgeIndex({ adapter, base });
+    cache.set(base, built);
+    return built;
   } catch {
     return null;
   }
@@ -8599,7 +8753,7 @@ function createReadKnowledgeTool(opts) {
         const idx = await loadIndex2(opts.adapter, base, indexCache);
         if (idx === null) {
           return {
-            content: `ERR_KNOWLEDGE_INDEX_MISSING: no _index.json for base "${base}"`,
+            content: `ERR_KNOWLEDGE_REF_NOT_FOUND: base "${base}" has no readable files`,
             isError: true
           };
         }
@@ -8705,17 +8859,24 @@ ${payload}`,
 async function loadIndex2(adapter, base, cache) {
   const cached2 = cache.get(base);
   if (cached2 !== void 0) return cached2;
-  let raw;
+  let raw = null;
   try {
     raw = await adapter.readFile(`${base}/_index.json`);
   } catch {
-    return null;
+    raw = null;
+  }
+  if (raw !== null) {
+    try {
+      const idx = JSON.parse(raw);
+      cache.set(base, idx);
+      return idx;
+    } catch {
+    }
   }
-  if (raw === null) return null;
   try {
-    const idx = JSON.parse(raw);
-    cache.set(base, idx);
-    return idx;
+    const built = await buildKnowledgeIndex({ adapter, base });
+    cache.set(base, built);
+    return built;
   } catch {
     return null;
   }
@@ -11239,153 +11400,6 @@ function buildToolRegistry(options) {
 // src/index.ts
 init_contract();
 init_fetchData();
-
-// src/knowledge/indexer.ts
-init_cjs_shims();
-var HEADING_RE = /^(#{1,6})[ \t]+(.+?)\s*$/;
-var WIKI_LINK_RE = /\[\[([^\]|#]+)(?:[#|][^\]]*)?\]\]/g;
-var FORMAT_BY_EXT = {
-  md: "md",
-  markdown: "md",
-  txt: "txt",
-  json: "json",
-  csv: "csv",
-  html: "html",
-  htm: "html",
-  pdf: "pdf",
-  docx: "docx"
-};
-var PREVIEW_CHARS = 200;
-async function buildKnowledgeIndex(options) {
-  const { adapter, base } = options;
-  const safeBase = base.replace(/^\/+|\/+$/g, "");
-  if (safeBase.length === 0 || safeBase.includes("..")) {
-    throw new Error(`buildKnowledgeIndex: invalid base "${base}"`);
-  }
-  const files = await listFilesRecursive(adapter, safeBase);
-  const sections = [];
-  const filesMeta = {};
-  for (const fileRel of files) {
-    if (fileRel === "_index.json") continue;
-    const fullPath = `${safeBase}/${fileRel}`;
-    const ext = (fileRel.split(".").pop() ?? "").toLowerCase();
-    const format = FORMAT_BY_EXT[ext];
-    if (format === void 0) continue;
-    const raw = await adapter.readFile(fullPath);
-    if (raw === null) continue;
-    const sizeBytes = byteLength3(raw);
-    const meta = { format, size: sizeBytes };
-    if (format === "md" || format === "txt") {
-      const fileSections = splitSections(raw, fileRel);
-      sections.push(...fileSections);
-      const wikiLinks = extractWikiLinks(raw);
-      if (wikiLinks.length > 0) meta.wikiLinks = wikiLinks;
-    }
-    filesMeta[fileRel] = meta;
-  }
-  return {
-    schema: "v1",
-    base: safeBase,
-    builtAt: options.nowIso ?? (/* @__PURE__ */ new Date()).toISOString(),
-    fileCount: Object.keys(filesMeta).length,
-    sections,
-    files: filesMeta
-  };
-}
-async function writeKnowledgeIndex(options) {
-  const index = await buildKnowledgeIndex(options);
-  await options.adapter.writeFile(`${index.base}/_index.json`, JSON.stringify(index, null, 2));
-  return index;
-}
-async function listFilesRecursive(adapter, dir) {
-  const out = [];
-  const stack = [""];
-  while (stack.length > 0) {
-    const sub = stack.pop();
-    const fullDir = sub === "" ? dir : `${dir}/${sub}`;
-    let entries = [];
-    try {
-      entries = await adapter.listDir(fullDir);
-    } catch {
-      continue;
-    }
-    for (const name of entries) {
-      const childRel = sub === "" ? name : `${sub}/${name}`;
-      const childFull = `${dir}/${childRel}`;
-      const isDir = await adapter.isDirectory(childFull).catch(() => false);
-      if (isDir) {
-        stack.push(childRel);
-      } else {
-        out.push(childRel);
-      }
-    }
-  }
-  return out.sort();
-}
-function splitSections(content, relPath) {
-  const lines = content.split(/\r?\n/);
-  const out = [];
-  const heads = [];
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i];
-    const m = HEADING_RE.exec(line);
-    if (m) heads.push({ line: i + 1, depth: m[1].length, heading: m[2].trim() });
-  }
-  const leadInEndLine = heads.length > 0 ? heads[0].line - 1 : lines.length;
-  const leadInBody = lines.slice(0, leadInEndLine).join("\n").trim();
-  if (leadInBody.length > 0) {
-    out.push({
-      relPath,
-      heading: "",
-      slug: `${relPath}#`,
-      depth: 0,
-      words: tokenize(leadInBody),
-      preview: makePreview(leadInBody),
-      startLine: 1,
-      endLine: leadInEndLine
-    });
-  }
-  for (let i = 0; i < heads.length; i++) {
-    const h = heads[i];
-    const startLine = h.line;
-    const endLine = i + 1 < heads.length ? heads[i + 1].line - 1 : lines.length;
-    const body = lines.slice(startLine - 1, endLine).join("\n");
-    out.push({
-      relPath,
-      heading: h.heading,
-      slug: `${relPath}#${slugify(h.heading)}`,
-      depth: h.depth,
-      words: tokenize(body),
-      preview: makePreview(body),
-      startLine,
-      endLine
-    });
-  }
-  return out;
-}
-function makePreview(body) {
-  const trimmed = body.replace(/^#{1,6}\s+.+$\r?\n?/m, "").trim();
-  if (trimmed.length <= PREVIEW_CHARS) return trimmed;
-  return trimmed.slice(0, PREVIEW_CHARS) + "\u2026";
-}
-function slugify(text2) {
-  return text2.toLowerCase().trim().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
-}
-function extractWikiLinks(text2) {
-  const seen = /* @__PURE__ */ new Set();
-  let m;
-  WIKI_LINK_RE.lastIndex = 0;
-  while ((m = WIKI_LINK_RE.exec(text2)) !== null) {
-    const target = m[1].trim();
-    if (target.length > 0) seen.add(target);
-  }
-  return [...seen].sort();
-}
-function byteLength3(s) {
-  return new TextEncoder().encode(s).byteLength;
-}
-
-// src/index.ts
 init_orchestrate();
 init_planParser();
 init_retry();