@remnic/core 1.1.30 → 9.3.515

package/dist/{chunk-GIF42EW3.js → chunk-UP6MOYCB.js}

@@ -5,14 +5,14 @@ import {
 import {
   computeTransferOutputRel,
   isTransferPathExcluded
-} from "./chunk-I6K5FBRQ.js";
+} from "./chunk-UI3NYK34.js";
 import {
   listFilesRecursive,
   readUtf8FileStrict,
   sha256String,
   toPosixRelPath,
   writeJsonFile
-} from "./chunk-AGZQD76C.js";
+} from "./chunk-GCGJW34D.js";
 
 // src/transfer/export-json.ts
 import path from "path";
@@ -60,4 +60,4 @@ async function exportJsonBundle(opts) {
 export {
   exportJsonBundle
 };
-//# sourceMappingURL=chunk-GIF42EW3.js.map
+//# sourceMappingURL=chunk-UP6MOYCB.js.map

package/dist/{chunk-K4FLSOR5.js → chunk-USYGGIJZ.js}

@@ -2,13 +2,16 @@ import {
   isTemporalQuery,
   recencyWindowBoundsFromPrompt
 } from "./chunk-V3RXWQIE.js";
+import {
+  isAbortError
+} from "./chunk-PVGDJXVK.js";
 import {
   log
 } from "./chunk-2ODBA7MQ.js";
 
 // src/retrieval-agents.ts
 import path from "path";
-import { readdir, readFile, stat } from "fs/promises";
+import { lstat, readdir, readFile, realpath, stat } from "fs/promises";
 var PARALLEL_AGENT_WEIGHTS = {
   direct: 1,
   // entity-first: high precision
@@ -38,8 +41,24 @@ function overlapScore(queryTokens, candidateTokens) {
   const hits = queryTokens.filter((t) => candidateSet.has(t)).length;
   return hits / Math.max(queryTokens.length, candidateTokens.length);
 }
+async function resolveContainedRegularFile(memoryDir, candidatePath, canonicalRoot) {
+  try {
+    const root = canonicalRoot ?? await realpath(memoryDir);
+    const absolute = path.isAbsolute(candidatePath) ? path.resolve(candidatePath) : path.resolve(memoryDir, candidatePath);
+    const entryStat = await lstat(absolute);
+    if (entryStat.isSymbolicLink()) return null;
+    const fileStat = await stat(absolute);
+    if (!fileStat.isFile()) return null;
+    const canonical = await realpath(absolute);
+    if (canonical !== root && !canonical.startsWith(root + path.sep)) return null;
+    return absolute;
+  } catch {
+    return null;
+  }
+}
 async function runDirectAgent(query, memoryDir, maxResults = 10) {
   try {
+    const canonicalRoot = await realpath(memoryDir);
     const entitiesDir = path.join(memoryDir, "entities");
     let entries;
     try {
@@ -56,9 +75,12 @@ async function runDirectAgent(query, memoryDir, maxResults = 10) {
       const entityTokens = nameWithoutExt.split("-").filter((t) => t.length >= 2).map((t) => t.toLowerCase());
       const score = overlapScore(queryTokens, entityTokens);
       if (score <= 0) continue;
+      const fullPath = path.join(entitiesDir, entry);
+      const safePath = await resolveContainedRegularFile(memoryDir, fullPath, canonicalRoot);
+      if (!safePath) continue;
       results.push({
         docid: nameWithoutExt,
-        path: path.join(entitiesDir, entry),
+        path: safePath,
         snippet: "",
         // populated by augmentWithDirectAndTemporal after merge
         score,
@@ -74,6 +96,7 @@ async function runDirectAgent(query, memoryDir, maxResults = 10) {
 }
 async function runTemporalAgent(query, memoryDir, maxResults = 20, candidatePaths) {
   try {
+    const canonicalRoot = await realpath(memoryDir);
     let dateIndex = {};
     try {
       const indexPath = path.join(memoryDir, "state", "index_time.json");
@@ -185,20 +208,21 @@ async function runTemporalAgent(query, memoryDir, maxResults = 20, candidatePath
       }
       return result;
     }).catch(() => /* @__PURE__ */ new Map()) : Promise.resolve(/* @__PURE__ */ new Map());
-    const [existenceResults, pathToTags] = await Promise.all([
-      Promise.all(entries.map(([p]) => stat(p).then(() => true).catch(() => false))),
+    const [safePathResults, pathToTags] = await Promise.all([
+      Promise.all(entries.map(([p]) => resolveContainedRegularFile(memoryDir, p, canonicalRoot))),
       tagIndexPromise
     ]);
     const results = [];
     for (let i = 0; i < entries.length; i++) {
-      if (!existenceResults[i]) continue;
       const [p, dateStr] = entries[i];
+      const safePath = safePathResults[i];
+      if (!safePath) continue;
       const ageMs = todayMs - new Date(dateStr).getTime();
       const ageDays = ageMs / 864e5;
       const recencyScore = Math.exp(-ageDays / 30);
       let topicBoost = 0;
       if (topicTokens.length > 0) {
-        const tags = pathToTags.get(p);
+        const tags = pathToTags.get(p) ?? pathToTags.get(safePath);
         if (tags && tags.length > 0) {
           const tagSet = new Set(tags.flatMap((t) => tokenize(t)));
           const hits = topicTokens.filter((t) => tagSet.has(t)).length;
@@ -206,10 +230,10 @@ async function runTemporalAgent(query, memoryDir, maxResults = 20, candidatePath
         }
       }
       const score = recencyScore * (1 + topicBoost * 0.3);
-      const baseName = path.basename(p, ".md");
+      const baseName = path.basename(safePath, ".md");
       results.push({
         docid: baseName,
-        path: p,
+        path: safePath,
         snippet: "",
         // populated by augmentWithDirectAndTemporal after merge
         score,
@@ -233,6 +257,7 @@ async function runContextualAgent(query, qmd, collection, maxResults, signal) {
     );
     return results.map((r) => ({ ...r, agentSource: "contextual" }));
   } catch (err) {
+    if (isAbortError(err)) throw err;
     log.debug(`ContextualAgent error: ${err}`);
     return [];
   }
@@ -264,15 +289,18 @@ function stripFrontmatter(raw) {
   if (end === -1) return raw;
   return raw.slice(end + 4).replace(/^\n+/, "");
 }
-async function populateEmptySnippets(results) {
+async function populateEmptySnippets(results, memoryDir) {
   const needsSnippet = results.filter((r) => !r.snippet && r.path);
   if (needsSnippet.length === 0) return results;
+  const canonicalRoot = memoryDir ? await realpath(memoryDir).catch(() => null) : null;
   const toRead = needsSnippet.slice(0, MAX_SNIPPET_READS);
   const snippetMap = /* @__PURE__ */ new Map();
   await Promise.all(
     toRead.map(async (r) => {
       try {
-        const raw = await readFile(r.path, "utf-8");
+        const safePath = canonicalRoot && r.path ? await resolveContainedRegularFile(memoryDir, r.path, canonicalRoot) : null;
+        if (!safePath) return;
+        const raw = await readFile(safePath, "utf-8");
         const body = stripFrontmatter(raw);
         const preview = body.slice(0, SNIPPET_PREVIEW_CHARS).replace(/\s+/g, " ").trim();
         if (preview) snippetMap.set(r.path, preview);
@@ -283,7 +311,7 @@ async function populateEmptySnippets(results) {
   if (snippetMap.size === 0) return results;
   return results.map((r) => r.path && snippetMap.has(r.path) ? { ...r, snippet: snippetMap.get(r.path) } : r);
 }
-async function mergeWithAgentResults(contextualResults, directResults, temporalResults, weights, maxResults) {
+async function mergeWithAgentResults(contextualResults, directResults, temporalResults, weights, maxResults, memoryDir) {
   if (directResults.length === 0 && temporalResults.length === 0) {
     return contextualResults.slice(0, maxResults);
   }
@@ -296,7 +324,7 @@ async function mergeWithAgentResults(contextualResults, directResults, temporalR
     weights,
     maxResults
   );
-  return populateEmptySnippets(merged);
+  return populateEmptySnippets(merged, memoryDir);
 }
 async function augmentWithDirectAndTemporal(query, memoryDir, contextualResults, weights, maxPerAgent, maxResults, candidatePaths) {
   if (maxPerAgent === 0) return contextualResults;
@@ -331,7 +359,7 @@ async function augmentWithDirectAndTemporal(query, memoryDir, contextualResults,
     weights,
     maxResults
   );
-  return populateEmptySnippets(merged);
+  return populateEmptySnippets(merged, memoryDir);
 }
 async function parallelRetrieval(query, qmd, memoryDir, options = {}) {
   const maxResults = options.maxResults ?? 20;
@@ -351,6 +379,7 @@ async function parallelRetrieval(query, qmd, memoryDir, options = {}) {
       return [];
     }) : Promise.resolve([]),
     runContextual ? runContextualAgent(query, qmd, options.collection, maxPerAgent, options.signal).catch((err) => {
+      if (isAbortError(err)) throw err;
       log.debug(`parallelRetrieval: ContextualAgent failed \u2014 ${err}`);
       return [];
     }) : Promise.resolve([])
@@ -364,7 +393,7 @@ async function parallelRetrieval(query, qmd, memoryDir, options = {}) {
     options.agentWeights ?? PARALLEL_AGENT_WEIGHTS,
     maxResults
   );
-  return populateEmptySnippets(merged);
+  return populateEmptySnippets(merged, memoryDir);
 }
 
 export {
@@ -377,4 +406,4 @@ export {
   augmentWithDirectAndTemporal,
   parallelRetrieval
 };
-//# sourceMappingURL=chunk-K4FLSOR5.js.map
+//# sourceMappingURL=chunk-USYGGIJZ.js.map

package/dist/chunk-USYGGIJZ.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/retrieval-agents.ts"],"sourcesContent":["/**\n * Parallel Specialized Retrieval (v9.1 — ASMR-inspired)\n *\n * Replaces single-pass hybrid search with three parallel specialized agents:\n *\n *   1. DirectFactAgent  — entity-first lookup via entity filename index (<5ms)\n *   2. ContextualAgent  — existing hybridSearch (same cost as current single-pass)\n *   3. TemporalAgent    — temporal index prefilter + recency scoring (<10ms)\n *\n * All agents run via Promise.all(), so total latency = max(agents), not sum.\n * No new LLM inference is introduced — agents reuse existing search primitives.\n *\n * Graceful degradation: any agent error/timeout does not block the others.\n *\n * References:\n *   - Supermemory ASMR: https://blog.supermemory.ai/...\n *   - Spec: docs/ideas/parallel-specialized-retrieval.md\n */\n\nimport path from \"node:path\";\nimport { lstat, readdir, readFile, realpath, stat } from \"node:fs/promises\";\nimport { log } from \"./logger.js\";\nimport type { QmdSearchResult } from \"./types.js\";\nimport type { QmdClient } from \"./qmd.js\";\nimport { isTemporalQuery, recencyWindowBoundsFromPrompt } from \"./temporal-index.js\";\nimport { isAbortError } from \"./abort-error.js\";\n\n// ─── Types ───────────────────────────────────────────────────────────────────\n\nexport type SearchAgentSource = \"direct\" | \"contextual\" | \"temporal\";\n\nexport interface ParallelSearchResult extends QmdSearchResult {\n  /** Which retrieval agent produced this result. */\n  agentSource: SearchAgentSource;\n}\n\n/** Source-based weights applied during merge. Higher = higher confidence/precision. */\nexport const PARALLEL_AGENT_WEIGHTS: Record<SearchAgentSource, number> = {\n  direct: 1.0, // entity-first: high precision\n  temporal: 0.85, // recency-boosted: relevant but broader\n  contextual: 0.7, // semantic: broadest, lower precision\n};\n\n// ─── Query classification ────────────────────────────────────────────────────\n\n/**\n * Decide whether a given agent should run for this query.\n * Agent 1 (direct) is the only one that may be skipped — when the query\n * contains no proper-noun-like tokens, entity lookups will return nothing.\n * Agents 2 (contextual) and 3 (temporal) always run.\n */\nexport function shouldRunAgent(\n  agent: SearchAgentSource,\n  query: string,\n  knownEntityCount: number,\n): boolean {\n  switch (agent) {\n    case \"direct\":\n      // Skip only if query has no word-like tokens at all. Both capitalized and\n      // lowercase entity names are stored (normalizeEntityName lowercases them),\n      // so gating on capitalization would silently skip most real entity lookups.\n      return knownEntityCount > 0 || /\\b\\w{2,}/.test(query);\n    case \"temporal\":\n      // Only run temporal agent when the query actually asks about a time window.\n      // Running it for every query injects recency bias into semantic searches.\n      return isTemporalQuery(query);\n    case \"contextual\":\n      return true;\n    default:\n      return true;\n  }\n}\n\n// ─── Helpers ─────────────────────────────────────────────────────────────────\n\nfunction tokenize(value: string): string[] {\n  return value\n    .toLowerCase()\n    .replace(/[^a-z0-9]+/g, \" \")\n    .trim()\n    .split(/\\s+/)\n    .filter((t) => t.length >= 2);\n}\n\nfunction overlapScore(queryTokens: string[], candidateTokens: string[]): number {\n  if (queryTokens.length === 0 || candidateTokens.length === 0) return 0;\n  const candidateSet = new Set(candidateTokens);\n  const hits = queryTokens.filter((t) => candidateSet.has(t)).length;\n  return hits / Math.max(queryTokens.length, candidateTokens.length);\n}\n\nasync function resolveContainedRegularFile(\n  memoryDir: string,\n  candidatePath: string,\n  canonicalRoot?: string,\n): Promise<string | null> {\n  try {\n    const root = canonicalRoot ?? await realpath(memoryDir);\n    const absolute = path.isAbsolute(candidatePath)\n      ? path.resolve(candidatePath)\n      : path.resolve(memoryDir, candidatePath);\n    const entryStat = await lstat(absolute);\n    if (entryStat.isSymbolicLink()) return null;\n    const fileStat = await stat(absolute);\n    if (!fileStat.isFile()) return null;\n    const canonical = await realpath(absolute);\n    if (canonical !== root && !canonical.startsWith(root + path.sep)) return null;\n    return absolute;\n  } catch {\n    return null;\n  }\n}\n\n// ─── Agent 1: Direct Facts ───────────────────────────────────────────────────\n\n/**\n * Direct Facts Agent — entity-first retrieval.\n *\n * Reads entity filenames from the entities directory and scores them by\n * keyword overlap with the query. Returns matching entity file paths as\n * QmdSearchResult[]. Zero LLM inference; pure file I/O.\n *\n * Cost: readdir on entities/ + filename scoring. Typically <5ms.\n *\n */\nexport async function runDirectAgent(\n  query: string,\n  memoryDir: string,\n  maxResults = 10,\n): Promise<ParallelSearchResult[]> {\n  try {\n    const canonicalRoot = await realpath(memoryDir);\n    const entitiesDir = path.join(memoryDir, \"entities\");\n    let entries: string[];\n    try {\n      entries = await readdir(entitiesDir);\n    } catch {\n      return []; // entities dir missing or unreadable — not an error\n    }\n\n    const queryTokens = tokenize(query);\n    if (queryTokens.length === 0) return [];\n\n    const results: ParallelSearchResult[] = [];\n    for (const entry of entries) {\n      if (!entry.endsWith(\".md\")) continue;\n\n      // Filename tokens: split on hyphens (normalizeEntityName uses hyphens)\n      const nameWithoutExt = entry.slice(0, -3);\n      const entityTokens = nameWithoutExt.split(\"-\").filter((t) => t.length >= 2).map((t) => t.toLowerCase());\n\n      const score = overlapScore(queryTokens, entityTokens);\n      if (score <= 0) continue;\n\n      const fullPath = path.join(entitiesDir, entry);\n      const safePath = await resolveContainedRegularFile(memoryDir, fullPath, canonicalRoot);\n      if (!safePath) continue;\n\n      results.push({\n        docid: nameWithoutExt,\n        path: safePath,\n        snippet: \"\", // populated by augmentWithDirectAndTemporal after merge\n        score,\n        transport: \"scoped_prefilter\",\n        agentSource: \"direct\",\n      });\n    }\n\n    return results\n      .sort((a, b) => b.score - a.score)\n      .slice(0, maxResults);\n  } catch (err) {\n    log.debug(`DirectFactAgent error: ${err}`);\n    return [];\n  }\n}\n\n// ─── Agent 3: Temporal ───────────────────────────────────────────────────────\n\n/**\n * Temporal Agent — recency-focused retrieval.\n *\n * Uses the temporal index (index_time.json) to find memories from the\n * recent time window derived from the query (default: last 7 days).\n * Combines recency decay with query-filename token overlap so results stay\n * relevant to the query content, not just recency. Zero LLM inference; File I/O + math.\n *\n * Cost: read index_time.json + date range scan. Typically <10ms.\n */\nexport async function runTemporalAgent(\n  query: string,\n  memoryDir: string,\n  maxResults = 20,\n  /** Optional candidate set from query-aware prefilter. Applied BEFORE the top-K cap so\n   * in-scope entries are not displaced by newer out-of-scope entries. */\n  candidatePaths?: Set<string> | null,\n): Promise<ParallelSearchResult[]> {\n  try {\n    const canonicalRoot = await realpath(memoryDir);\n    // Read index_time.json once — used for both date-range filtering and recency scoring.\n    let dateIndex: Record<string, string[]> = {};\n    try {\n      const indexPath = path.join(memoryDir, \"state\", \"index_time.json\");\n      const raw = await readFile(indexPath, \"utf-8\");\n      const parsed = JSON.parse(raw) as { dates?: Record<string, string[]> };\n      dateIndex = parsed.dates ?? {};\n    } catch {\n      return []; // Index missing or unreadable — nothing to return\n    }\n\n    // Derive both window edges from the same function so fromDate/toDate always use\n    // consistent pattern-matching and priority ordering.\n    const { fromDate, toDate } = recencyWindowBoundsFromPrompt(query);\n\n    // Build path → date map, filtering to the recency window in one pass.\n    // Apply candidatePaths here (before scoring + top-K) so in-scope entries are\n    // not displaced by newer out-of-scope entries at the slice boundary.\n    const pathToDate = new Map<string, string>();\n    for (const [date, datePaths] of Object.entries(dateIndex)) {\n      // toDate is an exclusive upper bound (the first day NOT included in the window).\n      // e.g. \"3 days ago\" → fromDate=\"2026-03-12\", toDate=\"2026-03-13\" → only includes 2026-03-12.\n      if (date >= fromDate && date < toDate) {\n        for (const p of datePaths) {\n          // Skip paths excluded by the query-aware prefilter scope\n          if (candidatePaths && !candidatePaths.has(p)) continue;\n          if (!pathToDate.has(p)) pathToDate.set(p, date);\n        }\n      }\n    }\n\n    if (pathToDate.size === 0) return [];\n\n    const todayMs = Date.now();\n\n    // Extract non-temporal topic tokens for tag-based relevance boost.\n    // Purely temporal words (dates, relative time) and common stopwords are stripped\n    // so the signal reflects the subject the user is asking about (e.g. \"auth\" in\n    // \"what changed in auth last week\"), not the time window itself.\n    const TEMPORAL_STOPWORDS = new Set([\n      \"today\", \"yesterday\", \"this\", \"last\", \"week\", \"month\", \"year\",\n      \"morning\", \"night\", \"now\", \"earlier\", \"since\", \"after\", \"before\",\n      \"ago\", \"hours\", \"days\", \"weeks\", \"months\",\n      \"january\", \"february\", \"march\", \"april\", \"may\", \"june\",\n      \"july\", \"august\", \"september\", \"october\", \"november\", \"december\",\n      \"monday\", \"tuesday\", \"wednesday\", \"thursday\", \"friday\", \"saturday\", \"sunday\",\n      \"what\", \"when\", \"where\", \"who\", \"why\", \"how\", \"the\", \"a\", \"an\",\n      \"and\", \"or\", \"in\", \"on\", \"at\", \"to\", \"of\", \"for\", \"with\", \"by\",\n      \"from\", \"changed\", \"happened\", \"was\", \"were\", \"is\", \"are\", \"did\",\n      \"about\", \"that\", \"have\", \"had\", \"has\", \"been\", \"any\", \"all\",\n    ]);\n    const topicTokens = tokenize(query).filter((t) => !TEMPORAL_STOPWORDS.has(t));\n\n    // Load tag index for topical scoring, in parallel with existence checks.\n    // Fail-open: if the tag index is unavailable, topicBoost = 0 and scores\n    // degrade gracefully to recency-only ordering (existing behaviour).\n    const entries = [...pathToDate.entries()];\n    const tagIndexPromise: Promise<Map<string, string[]>> = topicTokens.length > 0\n      ? readFile(path.join(memoryDir, \"state\", \"index_tags.json\"), \"utf-8\")\n          .then((raw) => {\n            const parsed = JSON.parse(raw) as { tags?: Record<string, { paths?: string[] } | string[]> };\n            const result = new Map<string, string[]>();\n            for (const [tag, node] of Object.entries(parsed.tags ?? {})) {\n              const tagPaths = Array.isArray(node) ? node : (node.paths ?? []);\n              for (const tp of tagPaths) {\n                const existing = result.get(tp);\n                if (existing) existing.push(tag);\n                else result.set(tp, [tag]);\n              }\n            }\n            return result;\n          })\n          .catch(() => new Map<string, string[]>())\n      : Promise.resolve(new Map<string, string[]>());\n\n    // Parallel: existence checks + tag index read.\n    const [safePathResults, pathToTags] = await Promise.all([\n      Promise.all(entries.map(([p]) => resolveContainedRegularFile(memoryDir, p, canonicalRoot))),\n      tagIndexPromise,\n    ]);\n\n    const results: ParallelSearchResult[] = [];\n\n    for (let i = 0; i < entries.length; i++) {\n      const [p, dateStr] = entries[i];\n      const safePath = safePathResults[i];\n      if (!safePath) continue; // skip stale or out-of-root index entry\n      const ageMs = todayMs - new Date(dateStr).getTime();\n      const ageDays = ageMs / 86_400_000;\n      // Exponential recency decay with half-life of ~30 days.\n      // score ≈ 1.0 at day 0, ≈ 0.79 at 7 days, ≈ 0.36 at 30 days, ≈ 0.13 at 60 days.\n      const recencyScore = Math.exp(-ageDays / 30);\n\n      // Topical boost: fraction of non-temporal query tokens matched by this file's tags.\n      // Adds up to +30% on recency score for a perfect tag match; zero when query is\n      // purely temporal (no topic tokens) or the tag index doesn't cover the file.\n      let topicBoost = 0;\n      if (topicTokens.length > 0) {\n        const tags = pathToTags.get(p) ?? pathToTags.get(safePath);\n        if (tags && tags.length > 0) {\n          const tagSet = new Set(tags.flatMap((t) => tokenize(t)));\n          const hits = topicTokens.filter((t) => tagSet.has(t)).length;\n          topicBoost = hits / topicTokens.length;\n        }\n      }\n      const score = recencyScore * (1 + topicBoost * 0.3);\n\n      const baseName = path.basename(safePath, \".md\");\n\n      results.push({\n        docid: baseName,\n        path: safePath,\n        snippet: \"\", // populated by augmentWithDirectAndTemporal after merge\n        score,\n        transport: \"scoped_prefilter\",\n        agentSource: \"temporal\",\n      });\n    }\n\n    return results\n      .sort((a, b) => b.score - a.score)\n      .slice(0, maxResults);\n  } catch (err) {\n    log.debug(`TemporalAgent error: ${err}`);\n    return [];\n  }\n}\n\n// ─── Agent 2: Contextual ─────────────────────────────────────────────────────\n\n/**\n * Contextual Agent — broad semantic/hybrid search.\n *\n * Delegates to the existing hybridSearch (BM25 + vector). Same cost as the\n * current single-pass retrieval — this agent introduces no additional LLM calls.\n */\nexport async function runContextualAgent(\n  query: string,\n  qmd: QmdClient,\n  collection: string | undefined,\n  maxResults: number,\n  signal?: AbortSignal,\n): Promise<ParallelSearchResult[]> {\n  try {\n    const results = await qmd.hybridSearch(\n      query,\n      collection,\n      maxResults,\n      signal ? { signal } : undefined,\n    );\n    return results.map((r: QmdSearchResult) => ({ ...r, agentSource: \"contextual\" as const }));\n  } catch (err) {\n    if (isAbortError(err)) throw err;\n    log.debug(`ContextualAgent error: ${err}`);\n    return [];\n  }\n}\n\n// ─── Merge helper ─────────────────────────────────────────────────────────────\n\n/**\n * Merge results from multiple agents into a single deduplicated, weighted list.\n * Preserves snippets: if a higher-scoring result lacks a snippet, the existing\n * snippet from a lower-scoring source is retained.\n */\nfunction mergeAgentResults(\n  allResults: ParallelSearchResult[],\n  weights: Record<SearchAgentSource, number>,\n  maxResults: number,\n): QmdSearchResult[] {\n  const merged = new Map<string, QmdSearchResult>();\n  for (const result of allResults) {\n    const key = result.path || result.docid;\n    const weightedScore = result.score * weights[result.agentSource];\n    const existing = merged.get(key);\n    if (!existing || weightedScore > existing.score) {\n      merged.set(key, {\n        docid: result.docid,\n        path: result.path,\n        // Preserve any snippet from the existing entry when the new one has none\n        snippet: result.snippet || existing?.snippet || \"\",\n        score: weightedScore,\n        transport: \"hybrid\",\n      });\n    }\n  }\n  return [...merged.values()]\n    .sort((a, b) => b.score - a.score)\n    .slice(0, maxResults);\n}\n\n/**\n * For merged results that have an empty snippet, attempt to read the first\n * 200 characters of the file as a fallback preview. Bounded to MAX_SNIPPET_READS\n * to cap I/O when many specialized-agent results are present.\n */\nconst SNIPPET_PREVIEW_CHARS = 200;\nconst MAX_SNIPPET_READS = 8;\n\n/** Strip YAML frontmatter (---...---) and return the document body. */\nfunction stripFrontmatter(raw: string): string {\n  if (!raw.startsWith(\"---\")) return raw;\n  const end = raw.indexOf(\"\\n---\", 3);\n  if (end === -1) return raw;\n  // Skip the closing \"---\" line and any leading blank lines\n  return raw.slice(end + 4).replace(/^\\n+/, \"\");\n}\n\nasync function populateEmptySnippets(results: QmdSearchResult[], memoryDir?: string): Promise<QmdSearchResult[]> {\n  const needsSnippet = results.filter((r) => !r.snippet && r.path);\n  if (needsSnippet.length === 0) return results;\n  const canonicalRoot = memoryDir ? await realpath(memoryDir).catch(() => null) : null;\n\n  const toRead = needsSnippet.slice(0, MAX_SNIPPET_READS);\n  const snippetMap = new Map<string, string>();\n\n  await Promise.all(\n    toRead.map(async (r) => {\n      try {\n        const safePath = canonicalRoot && r.path\n          ? await resolveContainedRegularFile(memoryDir!, r.path, canonicalRoot)\n          : null;\n        if (!safePath) return;\n        const raw = await readFile(safePath, \"utf-8\");\n        // Memory files start with YAML frontmatter — skip it so the snippet\n        // contains actual memory content, not metadata fields.\n        const body = stripFrontmatter(raw);\n        const preview = body.slice(0, SNIPPET_PREVIEW_CHARS).replace(/\\s+/g, \" \").trim();\n        if (preview) snippetMap.set(r.path, preview);\n      } catch {\n        // File unreadable — leave snippet empty\n      }\n    }),\n  );\n\n  if (snippetMap.size === 0) return results;\n  return results.map((r) => (r.path && snippetMap.has(r.path) ? { ...r, snippet: snippetMap.get(r.path)! } : r));\n}\n\n/**\n * Merge pre-computed direct and temporal agent results with contextual results.\n *\n * This is the merge half of augmentWithDirectAndTemporal. Expose it separately so\n * callers that started agents concurrently with the contextual search (for true\n * parallel latency) can merge after all three complete, without re-running agents.\n *\n * Handles the same cases as augmentWithDirectAndTemporal:\n * - Returns contextual unchanged (no reweighting) when both agents return nothing\n * - Applies maxResults cap in all paths\n * - Populates snippets for results discovered only by specialized agents\n */\nexport async function mergeWithAgentResults(\n  contextualResults: QmdSearchResult[],\n  directResults: ParallelSearchResult[],\n  temporalResults: ParallelSearchResult[],\n  weights: Record<SearchAgentSource, number>,\n  maxResults: number,\n  memoryDir?: string,\n): Promise<QmdSearchResult[]> {\n  if (directResults.length === 0 && temporalResults.length === 0) {\n    return contextualResults.slice(0, maxResults);\n  }\n\n  const contextualTagged: ParallelSearchResult[] = contextualResults.map((r) => ({\n    ...r,\n    agentSource: \"contextual\" as const,\n  }));\n\n  const merged = mergeAgentResults(\n    [...contextualTagged, ...directResults, ...temporalResults],\n    weights,\n    maxResults,\n  );\n  return populateEmptySnippets(merged, memoryDir);\n}\n\n// ─── Augmentation helper (used by tests; orchestrator uses inline logic) ─────\n//\n// NOTE: This function passes the same `memoryDir` to both direct and temporal\n// agents. The orchestrator's inline implementation differs: it passes a\n// namespace-specific storage dir to runDirectAgent and the shared root to\n// runTemporalAgent. augmentWithDirectAndTemporal is intentionally simpler\n// (single-dir assumption) and is exercised by unit tests where both agents\n// operate on the same temporary directory.\n\n/**\n * Augment a set of contextual (hybridSearch) results with direct and temporal\n * agent results, returning a merged, deduplicated list.\n *\n * **Test helper** — production recall uses the inline orchestrator path which\n * passes namespace-specific directories to each agent. This function uses a\n * simplified single-directory contract suitable for unit tests.\n *\n * Direct and temporal agents run in parallel, then all three are merged with\n * configurable weights.\n *\n * Contextual weight is always applied to `contextualResults` so scoring is\n * consistent regardless of whether direct/temporal agents return anything.\n *\n * Snippets: snippets from contextual results are preserved during merge. For\n * results discovered only by direct/temporal agents (no contextual match),\n * the first ~200 chars of the file are read as a fallback preview so downstream\n * formatters and rerankers have content to work with, not just a path.\n */\nexport async function augmentWithDirectAndTemporal(\n  query: string,\n  memoryDir: string,\n  contextualResults: QmdSearchResult[],\n  weights: Record<SearchAgentSource, number>,\n  maxPerAgent: number,\n  maxResults: number,\n  /** Optional candidate set from query-aware prefilter (time/tag scoped). Agents' results are\n   * filtered to this set when provided so recall stays within the operator-specified scope. */\n  candidatePaths?: Set<string> | null,\n): Promise<QmdSearchResult[]> {\n  // maxPerAgent=0 is a hard disable: skip agents entirely and return contextual unchanged\n  if (maxPerAgent === 0) return contextualResults;\n\n  const knownEntityCount = (query.match(/\\b[A-Z][a-z]{1,}/g) ?? []).length;\n  const runDirect = shouldRunAgent(\"direct\", query, knownEntityCount);\n  const runTemporal = shouldRunAgent(\"temporal\", query, knownEntityCount);\n\n  const startMs = Date.now();\n  const [directResults, temporalResults] = await Promise.all([\n    runDirect\n      ? runDirectAgent(query, memoryDir, maxPerAgent).catch((err) => {\n        log.debug(`augmentWithDirectAndTemporal: DirectAgent failed — ${err}`);\n        return [] as ParallelSearchResult[];\n      })\n      : Promise.resolve([] as ParallelSearchResult[]),\n    runTemporal\n      // Pass candidatePaths so scope-filtering happens before the top-K cap inside runTemporalAgent,\n      // preventing out-of-scope newer entries from displacing in-scope ones at the slice boundary.\n      ? runTemporalAgent(query, memoryDir, maxPerAgent, candidatePaths).catch((err) => {\n        log.debug(`augmentWithDirectAndTemporal: TemporalAgent failed — ${err}`);\n        return [] as ParallelSearchResult[];\n      })\n      : Promise.resolve([] as ParallelSearchResult[]),\n  ]);\n  const durationMs = Date.now() - startMs;\n\n  // Direct agent results (entities/) intentionally bypass candidatePaths.\n  //\n  // Why: candidatePaths is built from temporal + tag indexes, which never include\n  // entity files (entities/*.md). Applying the filter here would silently drop ALL\n  // direct-agent results for any scoped query, making the direct agent a no-op.\n  // Entity files are identified by filename matching (query tokens vs. entity name),\n  // so they are already query-scoped independently of the time/tag prefilter.\n  // Temporal results are scoped inside runTemporalAgent() before the top-K cap.\n  const scopedDirect = directResults;\n\n  // Tag contextual results with their source so they can participate in weighted merge.\n  // We do NOT cap contextual here: contextualResults comes from fetchQmdMemoryResultsWithArtifactTopUp\n  // which intentionally over-fetches so downstream phases (graph expansion, lifecycle filtering,\n  // reranking) can drop candidates. Capping before the merge would remove that headroom.\n  const contextualTagged: ParallelSearchResult[] = contextualResults.map((r) => ({\n    ...r,\n    agentSource: \"contextual\" as const,\n  }));\n\n  log.debug(\n    `augmentWithDirectAndTemporal: direct=${scopedDirect.length} temporal=${temporalResults.length} contextual=${contextualTagged.length} agentMs=${durationMs}ms`,\n  );\n\n  // If no specialized agents contributed anything (e.g. fresh setup without entities/ or temporal\n  // index), skip reweighting entirely — applying the contextual weight penalty with zero benefit\n  // would silently reduce every result score by ~30% compared to the non-augmented path.\n  if (scopedDirect.length === 0 && temporalResults.length === 0) {\n    return (contextualResults as QmdSearchResult[]).slice(0, maxResults);\n  }\n\n  // Merge all three; contextual first so its snippets are preserved when a higher-scoring\n  // direct/temporal result overrides the same path (see mergeAgentResults snippet logic).\n  // Note: maxPerAgent=0 is handled by the early-return guard above; we never reach here with 0.\n  const merged = mergeAgentResults(\n    [...contextualTagged, ...scopedDirect, ...temporalResults],\n    weights,\n    maxResults,\n  );\n\n  // Populate snippets for results discovered only by direct/temporal (no contextual preview)\n  return populateEmptySnippets(merged, memoryDir);\n}\n\n// ─── Orchestrator ─────────────────────────────────────────────────────────────\n\nexport interface ParallelRetrievalOptions {\n  collection?: string;\n  maxResults?: number;\n  signal?: AbortSignal;\n  /** If true, skip the contextual agent (hybridSearch is already running externally). */\n  skipContextual?: boolean;\n  /** Max results per agent (capped before merge). */\n  maxResultsPerAgent?: number;\n  /** Override default agent weights. Falls back to PARALLEL_AGENT_WEIGHTS when absent. */\n  agentWeights?: Record<SearchAgentSource, number>;\n}\n\n/**\n * Run parallel specialized retrieval agents and merge results.\n *\n * When `skipContextual` is true, only the direct and temporal agents run.\n * This is the intended usage inside the orchestrator, where hybridSearch\n * already runs as the primary search — we augment with the cheap extra agents.\n *\n * Total latency = max(agent_latencies), not sum.\n * Agent errors are isolated — others still return results.\n */\nexport async function parallelRetrieval(\n  query: string,\n  qmd: QmdClient,\n  memoryDir: string,\n  options: ParallelRetrievalOptions = {},\n): Promise<QmdSearchResult[]> {\n  const maxResults = options.maxResults ?? 20;\n  const maxPerAgent = options.maxResultsPerAgent ?? maxResults;\n  const startMs = Date.now();\n\n  // Rough entity detection: count proper-noun-like tokens in query\n  const knownEntityCount = (query.match(/\\b[A-Z][a-z]{1,}/g) ?? []).length;\n\n  const runDirect = shouldRunAgent(\"direct\", query, knownEntityCount);\n  const runTemporal = shouldRunAgent(\"temporal\", query, knownEntityCount);\n  const runContextual = !options.skipContextual && shouldRunAgent(\"contextual\", query, knownEntityCount);\n\n  const [directResults, temporalResults, contextualResults] = await Promise.all([\n    runDirect\n      ? runDirectAgent(query, memoryDir, maxPerAgent).catch((err) => {\n        log.debug(`parallelRetrieval: DirectAgent failed — ${err}`);\n        return [] as ParallelSearchResult[];\n      })\n      : Promise.resolve([] as ParallelSearchResult[]),\n    runTemporal\n      ? runTemporalAgent(query, memoryDir, maxPerAgent).catch((err) => {\n        log.debug(`parallelRetrieval: TemporalAgent failed — ${err}`);\n        return [] as ParallelSearchResult[];\n      })\n      : Promise.resolve([] as ParallelSearchResult[]),\n    runContextual\n      ? runContextualAgent(query, qmd, options.collection, maxPerAgent, options.signal).catch((err) => {\n        if (isAbortError(err)) throw err;\n        log.debug(`parallelRetrieval: ContextualAgent failed — ${err}`);\n        return [] as ParallelSearchResult[];\n      })\n      : Promise.resolve([] as ParallelSearchResult[]),\n  ]);\n\n  const durationMs = Date.now() - startMs;\n  log.debug(\n    `parallelRetrieval: direct=${directResults.length} temporal=${temporalResults.length} contextual=${contextualResults.length} durationMs=${durationMs}ms`,\n  );\n\n  // Contextual results go first so their snippets are preserved when a higher-scoring\n  // direct/temporal result overrides the same path in mergeAgentResults.\n  const merged = mergeAgentResults(\n    [...contextualResults, ...directResults, ...temporalResults],\n    options.agentWeights ?? PARALLEL_AGENT_WEIGHTS,\n    maxResults,\n  );\n  return populateEmptySnippets(merged, memoryDir);\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-FIT6DMX6.js → chunk-UWY7GIVS.js}

@@ -1,6 +1,6 @@
 // src/network/webdav.ts
-import { createReadStream } from "fs";
-import { mkdir, readdir, realpath, stat } from "fs/promises";
+import { constants } from "fs";
+import { mkdir, open, readdir, realpath, stat } from "fs/promises";
 import { createServer } from "http";
 import { timingSafeEqual } from "crypto";
 import path from "path";
@@ -12,10 +12,45 @@ function hostToUrlAuthority(host) {
   }
   return host;
 }
+function validateWebDavAuth(auth) {
+  if (typeof auth.username !== "string" || auth.username.trim().length === 0) {
+    throw new Error("webdav auth.username must be a non-empty string");
+  }
+  if (typeof auth.password !== "string" || auth.password.trim().length === 0) {
+    throw new Error("webdav auth.password must be a non-empty string");
+  }
+  return auth;
+}
+async function openWebDavFileForRead(absolutePath) {
+  let handle = null;
+  try {
+    handle = await open(absolutePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const info = await handle.stat();
+    if (!info.isFile()) {
+      await handle.close().catch(() => {
+      });
+      return { ok: false, code: 403, message: "path is not a file" };
+    }
+    return { ok: true, handle, size: info.size };
+  } catch (err) {
+    await handle?.close().catch(() => {
+    });
+    const code = err.code;
+    if (code === "ELOOP") {
+      return { ok: false, code: 403, message: "path escaped allowlist via symlink" };
+    }
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      return { ok: false, code: 404, message: "not found" };
+    }
+    return { ok: false, code: 404, message: "not found" };
+  }
+}
 var WebDavServer = class _WebDavServer {
   options;
   allowedRoots;
   server = null;
+  startPromise = null;
+  listening = false;
   boundPort;
   constructor(options, allowedRoots) {
     this.options = options;
@@ -28,7 +63,7 @@ var WebDavServer = class _WebDavServer {
       host: input.host ?? "127.0.0.1",
       port: input.port,
       allowlistDirs: input.allowlistDirs,
-      auth: input.auth
+      auth: input.auth ? validateWebDavAuth(input.auth) : void 0
     };
     if (!Array.isArray(options.allowlistDirs) || options.allowlistDirs.length === 0) {
       throw new Error("webdav allowlistDirs must include at least one directory");
@@ -55,9 +90,10 @@ var WebDavServer = class _WebDavServer {
     if (!this.options.enabled) {
       throw new Error("webdav server is disabled; set enabled=true to start");
     }
-    if (this.server) {
+    if (this.server && this.listening) {
       return this.status();
     }
+    if (this.startPromise) return this.startPromise;
     const server = createServer((req, res) => {
       this.handle(req, res).catch((err) => {
         if (res.headersSent) {
@@ -69,43 +105,74 @@ var WebDavServer = class _WebDavServer {
       });
     });
     this.server = server;
+    this.listening = false;
+    this.startPromise = (async () => {
+      try {
+        await new Promise((resolve, reject) => {
+          const onError = (err) => {
+            server.removeListener("listening", onListening);
+            server.removeListener("close", onClose);
+            reject(err);
+          };
+          const onListening = () => {
+            server.removeListener("error", onError);
+            server.removeListener("close", onClose);
+            resolve();
+          };
+          const onClose = () => {
+            server.removeListener("error", onError);
+            server.removeListener("listening", onListening);
+            reject(new Error("webdav server closed before listening"));
+          };
+          server.once("error", onError);
+          server.once("listening", onListening);
+          server.once("close", onClose);
+          server.listen(this.options.port, this.options.host);
+        });
+      } catch (err) {
+        if (this.server === server) {
+          this.server = null;
+        }
+        this.listening = false;
+        server.close();
+        throw err;
+      }
+      const address = server.address();
+      if (address && typeof address !== "string") {
+        this.boundPort = address.port;
+      }
+      this.listening = true;
+      return this.status();
+    })();
     try {
-      await new Promise((resolve, reject) => {
-        const onError = (err) => {
-          server.removeListener("listening", onListening);
-          reject(err);
-        };
-        const onListening = () => {
-          server.removeListener("error", onError);
-          resolve();
-        };
-        server.once("error", onError);
-        server.once("listening", onListening);
-        server.listen(this.options.port, this.options.host);
-      });
-    } catch (err) {
-      this.server = null;
-      server.close();
-      throw err;
-    }
-    const address = server.address();
-    if (address && typeof address !== "string") {
-      this.boundPort = address.port;
+      return await this.startPromise;
+    } finally {
+      this.startPromise = null;
     }
-    return this.status();
   }
   async stop() {
     if (!this.server) return;
     const server = this.server;
-    this.server = null;
-    this.boundPort = this.options.port;
+    const pendingStart = this.startPromise;
     await new Promise((resolve, reject) => {
-      server.close((err) => err ? reject(err) : resolve());
+      server.close((err) => {
+        if (err && err.code !== "ERR_SERVER_NOT_RUNNING") {
+          reject(err);
+          return;
+        }
+        resolve();
+      });
     });
+    await pendingStart?.catch(() => void 0);
+    if (this.server === server) {
+      this.server = null;
+    }
+    this.listening = false;
+    this.boundPort = this.options.port;
   }
   status() {
     return {
-      running: this.server !== null,
+      running: this.server !== null && this.listening,
       host: this.options.host,
       port: this.boundPort,
       rootCount: this.allowedRoots.length
@@ -137,11 +204,11 @@ var WebDavServer = class _WebDavServer {
       return;
     }
     if (method === "PROPFIND") {
-      await this.handlePropfind(resolved.absolutePath, resolved.displayPath, res);
+      await this.handlePropfind(resolved.absolutePath, resolved.rootAbsolute, resolved.displayPath, res);
       return;
     }
     if (method === "GET" || method === "HEAD") {
-      await this.handleRead(method, resolved.absolutePath, res);
+      await this.handleRead(method, resolved.absolutePath, resolved.rootAbsolute, res);
       return;
     }
     res.writeHead(405, {
@@ -221,11 +288,11 @@ var WebDavServer = class _WebDavServer {
       if (!this.isPathInside(root.absolute, canonicalCandidate)) {
         return { ok: false, code: 403, message: "path escaped allowlist via symlink" };
       }
-      return { ok: true, absolutePath: canonicalCandidate, displayPath: `/${segments.join("/")}` };
+      return { ok: true, absolutePath: canonicalCandidate, displayPath: `/${segments.join("/")}`, rootAbsolute: root.absolute };
     } catch (err) {
       const code = err.code;
       if (code === "ENOENT") {
-        return { ok: true, absolutePath: candidate, displayPath: `/${segments.join("/")}` };
+        return { ok: true, absolutePath: candidate, displayPath: `/${segments.join("/")}`, rootAbsolute: root.absolute };
       }
       if (code === "ENOTDIR" || code === "ELOOP") {
         return { ok: false, code: 400, message: "invalid path" };
@@ -233,31 +300,43 @@ var WebDavServer = class _WebDavServer {
       throw err;
     }
   }
-  async handleRead(method, absolutePath, res) {
-    let info;
-    try {
-      info = await stat(absolutePath);
-    } catch {
-      res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
-      res.end("not found");
+  async handleRead(method, absolutePath, rootAbsolute, res) {
+    const revalidated = await this.revalidatePathInsideRoot(absolutePath, rootAbsolute);
+    if (!revalidated.ok) {
+      res.writeHead(revalidated.code, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end(revalidated.message);
       return;
     }
-    if (!info.isFile()) {
-      res.writeHead(403, { "Content-Type": "text/plain; charset=utf-8" });
-      res.end("path is not a file");
+    const opened = await openWebDavFileForRead(revalidated.absolutePath);
+    if (!opened.ok) {
+      res.writeHead(opened.code, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end(opened.message);
       return;
     }
-    res.writeHead(200, {
-      "Content-Length": String(info.size),
-      "Content-Type": "application/octet-stream"
-    });
-    if (method === "HEAD") {
-      res.end();
-      return;
+    const { handle, size } = opened;
+    try {
+      res.writeHead(200, {
+        "Content-Length": String(size),
+        "Content-Type": "application/octet-stream"
+      });
+      if (method === "HEAD") {
+        res.end();
+        return;
+      }
+      await pipeline(handle.createReadStream({ autoClose: false }), res);
+    } finally {
+      await handle.close().catch(() => {
+      });
     }
-    await pipeline(createReadStream(absolutePath), res);
   }
-  async handlePropfind(absolutePath, displayPath, res) {
+  async handlePropfind(absolutePath, rootAbsolute, displayPath, res) {
+    const revalidated = await this.revalidatePathInsideRoot(absolutePath, rootAbsolute);
+    if (!revalidated.ok) {
+      res.writeHead(revalidated.code, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end(revalidated.message);
+      return;
+    }
+    absolutePath = revalidated.absolutePath;
     let info;
     try {
       info = await stat(absolutePath);
@@ -295,6 +374,24 @@ var WebDavServer = class _WebDavServer {
     }
     return target.startsWith(`${root}${path.sep}`);
   }
+  async revalidatePathInsideRoot(absolutePath, rootAbsolute) {
+    try {
+      const canonical = await realpath(absolutePath);
+      if (!this.isPathInside(rootAbsolute, canonical)) {
+        return { ok: false, code: 403, message: "path escaped allowlist via symlink" };
+      }
+      return { ok: true, absolutePath: canonical };
+    } catch (err) {
+      const code = err.code;
+      if (code === "ENOENT" || code === "ENOTDIR") {
+        return { ok: false, code: 404, message: "not found" };
+      }
+      if (code === "ELOOP") {
+        return { ok: false, code: 403, message: "path escaped allowlist via symlink" };
+      }
+      throw err;
+    }
+  }
 };
 function xmlEscape(value) {
   return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
@@ -305,6 +402,7 @@ function toEncodedHref(pathname) {
 
 export {
   hostToUrlAuthority,
+  openWebDavFileForRead,
   WebDavServer
 };
-//# sourceMappingURL=chunk-FIT6DMX6.js.map
+//# sourceMappingURL=chunk-UWY7GIVS.js.map