scai 0.1.178 → 1.0.0

package/dist/agent/search/exactTarget.js

@@ -0,0 +1,151 @@
+/**
+ * Resolves explicit file-like targets for modular-agent search.
+ *
+ * Why this file exists:
+ * - exact-target search should salvage every concrete target it can
+ * - one ambiguous basename should not wipe out other resolved files
+ * - folder targets should expand into scoped child candidates
+ */
+import fs from "fs";
+import path from "path";
+import { extractFileReferences } from "../../utils/extractFileReferences.js";
+import { collectSearchableDirectories, collectSearchablePaths, dedupeStrings } from "./shared.js";
+function matchCandidateFiles(files, target) {
+    const normalizedTarget = target.replace(/\\/g, "/").toLowerCase();
+    const basenameTarget = path.basename(target).toLowerCase();
+    return files.filter((filePath) => {
+        const normalizedPath = filePath.replace(/\\/g, "/").toLowerCase();
+        const basename = path.basename(filePath).toLowerCase();
+        const stem = basename.replace(/\.[^.]+$/, "");
+        return normalizedPath.endsWith(`/${normalizedTarget}`) ||
+            basename === basenameTarget ||
+            stem === basenameTarget;
+    });
+}
+function matchCandidateDirectories(directories, target) {
+    const normalizedTarget = target.replace(/\\/g, "/").toLowerCase();
+    const basenameTarget = path.basename(target).toLowerCase();
+    return directories.filter((directoryPath) => {
+        const normalizedPath = directoryPath.replace(/\\/g, "/").toLowerCase();
+        const basename = path.basename(directoryPath).toLowerCase();
+        return normalizedPath.endsWith(`/${normalizedTarget}`) || basename === basenameTarget;
+    });
+}
+function collectScopedFolderFiles(folderPath) {
+    return collectSearchablePaths(folderPath, { allowIgnoredPaths: true });
+}
+function computeSharedDirectoryPrefixScore(candidatePath, anchorPaths) {
+    const candidateParts = path.dirname(candidatePath).split(path.sep).filter(Boolean);
+    let bestScore = 0;
+    for (const anchorPath of anchorPaths) {
+        const anchorParts = path.dirname(anchorPath).split(path.sep).filter(Boolean);
+        let score = 0;
+        while (score < candidateParts.length &&
+            score < anchorParts.length &&
+            candidateParts[score] === anchorParts[score]) {
+            score += 1;
+        }
+        bestScore = Math.max(bestScore, score);
+    }
+    return bestScore;
+}
+function chooseScopedAmbiguousMatch(matches, resolvedPaths) {
+    if (matches.length <= 1 || resolvedPaths.length === 0) {
+        return undefined;
+    }
+    const scoredMatches = matches
+        .map((filePath) => ({
+        filePath,
+        score: computeSharedDirectoryPrefixScore(filePath, resolvedPaths),
+    }))
+        .sort((left, right) => right.score - left.score);
+    if (scoredMatches[0]?.score <= 0) {
+        return undefined;
+    }
+    if (scoredMatches[1] && scoredMatches[0].score === scoredMatches[1].score) {
+        return undefined;
+    }
+    return scoredMatches[0]?.filePath;
+}
+export function runExactTargetSearch(rootDir, query, explicitTargets) {
+    const rawTargets = dedupeStrings([...explicitTargets, ...extractFileReferences(query)]).filter(Boolean);
+    if (rawTargets.length === 0) {
+        return {
+            lane: "exact-target",
+            query,
+            filePaths: [],
+        };
+    }
+    const files = collectSearchablePaths(rootDir);
+    const directories = collectSearchableDirectories(rootDir);
+    const resolvedPaths = [];
+    const ambiguousTargets = [];
+    for (const target of rawTargets) {
+        const absoluteCandidate = path.isAbsolute(target) ? target : path.join(rootDir, target);
+        if (fs.existsSync(absoluteCandidate)) {
+            const stats = fs.statSync(absoluteCandidate);
+            if (stats.isFile()) {
+                resolvedPaths.push(absoluteCandidate);
+                continue;
+            }
+            if (stats.isDirectory()) {
+                resolvedPaths.push(...collectScopedFolderFiles(absoluteCandidate));
+                continue;
+            }
+        }
+        const fileMatches = matchCandidateFiles(files, target);
+        if (fileMatches.length === 1) {
+            resolvedPaths.push(fileMatches[0]);
+            continue;
+        }
+        if (fileMatches.length > 1) {
+            const scopedMatch = chooseScopedAmbiguousMatch(fileMatches, resolvedPaths);
+            if (scopedMatch) {
+                resolvedPaths.push(scopedMatch);
+                continue;
+            }
+            resolvedPaths.push(...fileMatches);
+            ambiguousTargets.push(target);
+            continue;
+        }
+        const directoryMatches = matchCandidateDirectories(directories, target);
+        if (directoryMatches.length === 1) {
+            resolvedPaths.push(...collectScopedFolderFiles(directoryMatches[0]));
+            continue;
+        }
+        if (directoryMatches.length > 1) {
+            const scopedMatch = chooseScopedAmbiguousMatch(directoryMatches, resolvedPaths);
+            if (scopedMatch) {
+                resolvedPaths.push(...collectScopedFolderFiles(scopedMatch));
+                continue;
+            }
+            ambiguousTargets.push(target);
+        }
+    }
+    const dedupedResolvedPaths = dedupeStrings(resolvedPaths);
+    if (dedupedResolvedPaths.length > 0) {
+        return {
+            lane: "exact-target",
+            query,
+            filePaths: dedupedResolvedPaths,
+        };
+    }
+    if (ambiguousTargets.length > 0) {
+        return {
+            lane: "exact-target",
+            query,
+            filePaths: [],
+            failure: {
+                status: "failed",
+                failureClass: "ambiguous",
+                message: `Target is ambiguous inside the current repo/worktree: ${ambiguousTargets[0]}`,
+            },
+        };
+    }
+    return {
+        lane: "exact-target",
+        query,
+        filePaths: [],
+    };
+}
+//# sourceMappingURL=exactTarget.js.map

package/dist/agent/search/exactTarget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exactTarget.js","sourceRoot":"","sources":["../../../src/agent/search/exactTarget.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,qBAAqB,EAAE,MAAM,sCAAsC,CAAC;AAE7E,OAAO,EAAE,4BAA4B,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAElG,SAAS,mBAAmB,CAAC,KAAe,EAAE,MAAc;IAC1D,MAAM,gBAAgB,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IAClE,MAAM,cAAc,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;IAC3D,OAAO,KAAK,CAAC,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE;QAC/B,MAAM,cAAc,GAAG,QAAQ,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;QAClE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,WAAW,EAAE,CAAC;QACvD,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QAC9C,OAAO,cAAc,CAAC,QAAQ,CAAC,IAAI,gBAAgB,EAAE,CAAC;YACpD,QAAQ,KAAK,cAAc;YAC3B,IAAI,KAAK,cAAc,CAAC;IAC5B,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,yBAAyB,CAAC,WAAqB,EAAE,MAAc;IACtE,MAAM,gBAAgB,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;IAClE,MAAM,cAAc,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,WAAW,EAAE,CAAC;IAC3D,OAAO,WAAW,CAAC,MAAM,CAAC,CAAC,aAAa,EAAE,EAAE;QAC1C,MAAM,cAAc,GAAG,aAAa,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,WAAW,EAAE,CAAC;QACvE,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAC,WAAW,EAAE,CAAC;QAC5D,OAAO,cAAc,CAAC,QAAQ,CAAC,IAAI,gBAAgB,EAAE,CAAC,IAAI,QAAQ,KAAK,cAAc,CAAC;IACxF,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,wBAAwB,CAAC,UAAkB;IAClD,OAAO,sBAAsB,CAAC,UAAU,EAAE,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,CAAC;AACzE,CAAC;AAED,SAAS,iCAAiC,CAAC,aAAqB,EAAE,WAAqB;IACrF,MAAM,cAAc,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACnF,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,KAAK,MAAM,UAAU,IAAI,WAAW,EAAE,CAAC;QACrC,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC7E,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,OACE,KAAK,GAAG,cAAc,CAAC,MAAM;YAC7B,KAAK,GAAG,WAAW,CAAC,MAAM;YAC1B,cAAc,CAAC,KAAK,CAAC,KAAK,WAAW,CAAC,KAAK,CAAC,EAC5C,CAAC;YACD,KAAK,IAAI,CAAC,CAAC;QACb,CAAC;QACD,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,KAAK,CAAC,CAAC;IACzC,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,0BAA0B,CAAC,OAAiB,EAAE,aAAuB;IAC5E,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,IAAI,aAAa,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtD,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,aAAa,GAAG,OAAO;SAC1B,GAAG,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QAClB,QAAQ;QACR,KAAK,EAAE,iCAAiC,CAAC,QAAQ,EAAE,aAAa,CAAC;KAClE,CAAC,CAAC;SACF,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;IAEnD,IAAI,aAAa,CAAC,CAAC,CAAC,EAAE,KAAK,IAAI,CAAC,EAAE,CAAC;QACjC,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,aAAa,CAAC,CAAC,CAAC,IAAI,aAAa,CAAC,CAAC,CAAC,CAAC,KAAK,KAAK,aAAa,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC;QAC1E,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,aAAa,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,OAAe,EAAE,KAAa,EAAE,eAAyB;IAC5F,MAAM,UAAU,GAAG,aAAa,CAAC,CAAC,GAAG,eAAe,EAAE,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IACxG,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO;YACL,IAAI,EAAE,cAAc;YACpB,KAAK;YACL,SAAS,EAAE,EAAE;SACd,CAAC;IACJ,CAAC;IAED,MAAM,KAAK,GAAG,sBAAsB,CAAC,OAAO,CAAC,CAAC;IAC9C,MAAM,WAAW,GAAG,4BAA4B,CAAC,OAAO,CAAC,CAAC;IAC1D,MAAM,aAAa,GAAa,EAAE,CAAC;IACnC,MAAM,gBAAgB,GAAa,EAAE,CAAC;IAEtC,KAAK,MAAM,MAAM,IAAI,UAAU,EAAE,CAAC;QAChC,MAAM,iBAAiB,GAAG,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;QACxF,IAAI,EAAE,CAAC,UAAU,CAAC,iBAAiB,CAAC,EAAE,CAAC;YACrC,MAAM,KAAK,GAAG,EAAE,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC;YAC7C,IAAI,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC;gBACnB,aAAa,CAAC,IAAI,CAAC,iBAAiB,CAAC,CAAC;gBACtC,SAAS;YACX,CAAC;YACD,IAAI,KAAK,CAAC,WAAW,EAAE,EAAE,CAAC;gBACxB,aAAa,CAAC,IAAI,CAAC,GAAG,wBAAwB,CAAC,iBAAiB,CAAC,CAAC,CAAC;gBACnE,SAAS;YACX,CAAC;QACH,CAAC;QAED,MAAM,WAAW,GAAG,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACvD,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7B,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;YACnC,SAAS;QACX,CAAC;QACD,IAAI,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC3B,MAAM,WAAW,GAAG,0BAA0B,CAAC,WAAW,EAAE,aAAa,CAAC,CAAC;YAC3E,IAAI,WAAW,EAAE,CAAC;gBAChB,aAAa,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;gBAChC,SAAS;YACX,CAAC;YACD,aAAa,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,CAAC;YACnC,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC9B,SAAS;QACX,CAAC;QAED,MAAM,gBAAgB,GAAG,yBAAyB,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;QACxE,IAAI,gBAAgB,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAClC,aAAa,CAAC,IAAI,CAAC,GAAG,wBAAwB,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;YACrE,SAAS;QACX,CAAC;QACD,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAChC,MAAM,WAAW,GAAG,0BAA0B,CAAC,gBAAgB,EAAE,aAAa,CAAC,CAAC;YAChF,IAAI,WAAW,EAAE,CAAC;gBAChB,aAAa,CAAC,IAAI,CAAC,GAAG,wBAAwB,CAAC,WAAW,CAAC,CAAC,CAAC;gBAC7D,SAAS;YACX,CAAC;YACD,gBAAgB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;IAED,MAAM,oBAAoB,GAAG,aAAa,CAAC,aAAa,CAAC,CAAC;IAC1D,IAAI,oBAAoB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpC,OAAO;YACL,IAAI,EAAE,cAAc;YACpB,KAAK;YACL,SAAS,EAAE,oBAAoB;SAChC,CAAC;IACJ,CAAC;IAED,IAAI,gBAAgB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChC,OAAO;YACL,IAAI,EAAE,cAAc;YACpB,KAAK;YACL,SAAS,EAAE,EAAE;YACb,OAAO,EAAE;gBACP,MAAM,EAAE,QAAQ;gBAChB,YAAY,EAAE,WAAW;gBACzB,OAAO,EAAE,yDAAyD,gBAAgB,CAAC,CAAC,CAAC,EAAE;aACxF;SACF,CAAC;IACJ,CAAC;IAED,OAAO;QACL,IAAI,EAAE,cAAc;QACpB,KAAK;QACL,SAAS,EAAE,EAAE;KACd,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Resolves explicit file-like targets for modular-agent search.\n *\n * Why this file exists:\n * - exact-target search should salvage every concrete target it can\n * - one ambiguous basename should not wipe out other resolved files\n * - folder targets should expand into scoped child candidates\n */\nimport fs from \"fs\";\nimport path from \"path\";\nimport { extractFileReferences } from \"../../utils/extractFileReferences.js\";\nimport type { AgentSearchPacket } from \"./types.js\";\nimport { collectSearchableDirectories, collectSearchablePaths, dedupeStrings } from \"./shared.js\";\n\nfunction matchCandidateFiles(files: string[], target: string): string[] {\n  const normalizedTarget = target.replace(/\\\\/g, \"/\").toLowerCase();\n  const basenameTarget = path.basename(target).toLowerCase();\n  return files.filter((filePath) => {\n    const normalizedPath = filePath.replace(/\\\\/g, \"/\").toLowerCase();\n    const basename = path.basename(filePath).toLowerCase();\n    const stem = basename.replace(/\\.[^.]+$/, \"\");\n    return normalizedPath.endsWith(`/${normalizedTarget}`) ||\n      basename === basenameTarget ||\n      stem === basenameTarget;\n  });\n}\n\nfunction matchCandidateDirectories(directories: string[], target: string): string[] {\n  const normalizedTarget = target.replace(/\\\\/g, \"/\").toLowerCase();\n  const basenameTarget = path.basename(target).toLowerCase();\n  return directories.filter((directoryPath) => {\n    const normalizedPath = directoryPath.replace(/\\\\/g, \"/\").toLowerCase();\n    const basename = path.basename(directoryPath).toLowerCase();\n    return normalizedPath.endsWith(`/${normalizedTarget}`) || basename === basenameTarget;\n  });\n}\n\nfunction collectScopedFolderFiles(folderPath: string): string[] {\n  return collectSearchablePaths(folderPath, { allowIgnoredPaths: true });\n}\n\nfunction computeSharedDirectoryPrefixScore(candidatePath: string, anchorPaths: string[]): number {\n  const candidateParts = path.dirname(candidatePath).split(path.sep).filter(Boolean);\n  let bestScore = 0;\n\n  for (const anchorPath of anchorPaths) {\n    const anchorParts = path.dirname(anchorPath).split(path.sep).filter(Boolean);\n    let score = 0;\n    while (\n      score < candidateParts.length &&\n      score < anchorParts.length &&\n      candidateParts[score] === anchorParts[score]\n    ) {\n      score += 1;\n    }\n    bestScore = Math.max(bestScore, score);\n  }\n\n  return bestScore;\n}\n\nfunction chooseScopedAmbiguousMatch(matches: string[], resolvedPaths: string[]): string | undefined {\n  if (matches.length <= 1 || resolvedPaths.length === 0) {\n    return undefined;\n  }\n\n  const scoredMatches = matches\n    .map((filePath) => ({\n      filePath,\n      score: computeSharedDirectoryPrefixScore(filePath, resolvedPaths),\n    }))\n    .sort((left, right) => right.score - left.score);\n\n  if (scoredMatches[0]?.score <= 0) {\n    return undefined;\n  }\n  if (scoredMatches[1] && scoredMatches[0].score === scoredMatches[1].score) {\n    return undefined;\n  }\n  return scoredMatches[0]?.filePath;\n}\n\nexport function runExactTargetSearch(rootDir: string, query: string, explicitTargets: string[]): AgentSearchPacket {\n  const rawTargets = dedupeStrings([...explicitTargets, ...extractFileReferences(query)]).filter(Boolean);\n  if (rawTargets.length === 0) {\n    return {\n      lane: \"exact-target\",\n      query,\n      filePaths: [],\n    };\n  }\n\n  const files = collectSearchablePaths(rootDir);\n  const directories = collectSearchableDirectories(rootDir);\n  const resolvedPaths: string[] = [];\n  const ambiguousTargets: string[] = [];\n\n  for (const target of rawTargets) {\n    const absoluteCandidate = path.isAbsolute(target) ? target : path.join(rootDir, target);\n    if (fs.existsSync(absoluteCandidate)) {\n      const stats = fs.statSync(absoluteCandidate);\n      if (stats.isFile()) {\n        resolvedPaths.push(absoluteCandidate);\n        continue;\n      }\n      if (stats.isDirectory()) {\n        resolvedPaths.push(...collectScopedFolderFiles(absoluteCandidate));\n        continue;\n      }\n    }\n\n    const fileMatches = matchCandidateFiles(files, target);\n    if (fileMatches.length === 1) {\n      resolvedPaths.push(fileMatches[0]);\n      continue;\n    }\n    if (fileMatches.length > 1) {\n      const scopedMatch = chooseScopedAmbiguousMatch(fileMatches, resolvedPaths);\n      if (scopedMatch) {\n        resolvedPaths.push(scopedMatch);\n        continue;\n      }\n      resolvedPaths.push(...fileMatches);\n      ambiguousTargets.push(target);\n      continue;\n    }\n\n    const directoryMatches = matchCandidateDirectories(directories, target);\n    if (directoryMatches.length === 1) {\n      resolvedPaths.push(...collectScopedFolderFiles(directoryMatches[0]));\n      continue;\n    }\n    if (directoryMatches.length > 1) {\n      const scopedMatch = chooseScopedAmbiguousMatch(directoryMatches, resolvedPaths);\n      if (scopedMatch) {\n        resolvedPaths.push(...collectScopedFolderFiles(scopedMatch));\n        continue;\n      }\n      ambiguousTargets.push(target);\n    }\n  }\n\n  const dedupedResolvedPaths = dedupeStrings(resolvedPaths);\n  if (dedupedResolvedPaths.length > 0) {\n    return {\n      lane: \"exact-target\",\n      query,\n      filePaths: dedupedResolvedPaths,\n    };\n  }\n\n  if (ambiguousTargets.length > 0) {\n    return {\n      lane: \"exact-target\",\n      query,\n      filePaths: [],\n      failure: {\n        status: \"failed\",\n        failureClass: \"ambiguous\",\n        message: `Target is ambiguous inside the current repo/worktree: ${ambiguousTargets[0]}`,\n      },\n    };\n  }\n\n  return {\n    lane: \"exact-target\",\n    query,\n    filePaths: [],\n  };\n}\n"]}

package/dist/agent/search/fragment.js

@@ -0,0 +1,110 @@
+/**
+ * Runs fixed-string sentence-fragment search for quoted snippets in modular-agent search.
+ *
+ * Why this file exists:
+ * - quoted code snippets should not collapse into broad semantic retrieval
+ * - fragment search should stay separate from regex and semantic lanes
+ */
+import { extractQuotedFragments } from "./searchContext.js";
+import { classifyFileRulePath } from "../../fileRules/searchPathClassification.js";
+import { collectFixedStringMatches, collectSearchablePaths, dedupeStrings } from "./shared.js";
+function isFragmentSearchablePath(filePath) {
+    const classification = classifyFileRulePath(filePath);
+    return !classification.isGeneratedBuild
+        && !classification.isArtifact
+        && !classification.isLogLike
+        && !classification.isSourceMap
+        && !classification.isHarnessLike;
+}
+function computeFragmentFileBonus(filePath) {
+    const classification = classifyFileRulePath(filePath);
+    const normalized = filePath.replace(/\\/g, "/").toLowerCase();
+    if (classification.isDocumentation) {
+        return -4;
+    }
+    if (normalized.includes("/__tests__/") || normalized.endsWith(".test.ts") || normalized.endsWith(".spec.ts")) {
+        return 6;
+    }
+    if (normalized.includes("/src/")) {
+        return 3;
+    }
+    return 0;
+}
+function computeFragmentSnippetContextBonus(snippet) {
+    const trimmed = String(snippet ?? "").trim();
+    if (!trimmed) {
+        return 0;
+    }
+    let bonus = 0;
+    if (/\b(?:it|test|describe)\s*\(/.test(trimmed)) {
+        bonus += 6;
+    }
+    if (/\b(?:query|userQuery|prompt|input|expected|fixture)\s*:/.test(trimmed)) {
+        bonus -= 5;
+    }
+    if (/^const\s+[A-Za-z0-9_]+\s*=/.test(trimmed)) {
+        bonus -= 4;
+    }
+    if (/^\{?\s*(?:path|filePath|targetFile)\s*:/.test(trimmed)) {
+        bonus -= 3;
+    }
+    return bonus;
+}
+export function runFragmentSearch(rootDir, query, limit = 5) {
+    const fragments = extractQuotedFragments(query);
+    if (fragments.length === 0) {
+        return {
+            lane: "fragment",
+            query,
+            filePaths: [],
+        };
+    }
+    // Quoted fragment lookups need to search test files too, because many literal snippets only live in tests.
+    const files = collectSearchablePaths(rootDir, { allowIgnoredPaths: true })
+        .filter(isFragmentSearchablePath);
+    const matches = collectFixedStringMatches(files, fragments, "fragment-content", {
+        caseSensitive: true,
+        maxPerFile: 2,
+        // Keep the frontier wide enough that test/source hits are not dropped behind earlier doc matches.
+        maxTotal: Math.max(limit * 8, 24),
+    });
+    const bestScores = new Map();
+    const perFileMatchCount = new Map();
+    for (const match of matches) {
+        const adjustedScore = (match.score ?? 1) + computeFragmentSnippetContextBonus(match.snippet);
+        bestScores.set(match.filePath, Math.max(bestScores.get(match.filePath) ?? Number.NEGATIVE_INFINITY, adjustedScore));
+        perFileMatchCount.set(match.filePath, (perFileMatchCount.get(match.filePath) ?? 0) + 1);
+    }
+    const scoredHits = Array.from(bestScores.entries())
+        .map(([filePath, matchScore]) => ({
+        filePath,
+        matchScore,
+        duplicatePenalty: Math.max(0, (perFileMatchCount.get(filePath) ?? 0) - 1),
+        totalScore: matchScore + computeFragmentFileBonus(filePath) - Math.max(0, (perFileMatchCount.get(filePath) ?? 0) - 1) * 3,
+    }))
+        .sort((left, right) => {
+        if (right.totalScore !== left.totalScore) {
+            return right.totalScore - left.totalScore;
+        }
+        if (left.duplicatePenalty !== right.duplicatePenalty) {
+            return left.duplicatePenalty - right.duplicatePenalty;
+        }
+        if (right.matchScore !== left.matchScore) {
+            return right.matchScore - left.matchScore;
+        }
+        return left.filePath.localeCompare(right.filePath);
+    });
+    const preferredHits = scoredHits.some((entry) => !classifyFileRulePath(entry.filePath).isDocumentation)
+        ? scoredHits.filter((entry) => !classifyFileRulePath(entry.filePath).isDocumentation)
+        : scoredHits;
+    const hits = preferredHits.slice(0, limit).map((entry) => entry.filePath);
+    const relatedFileScores = Object.fromEntries(preferredHits.map((entry) => [entry.filePath, -entry.totalScore]));
+    return {
+        lane: "fragment",
+        query,
+        filePaths: dedupeStrings(hits),
+        matches,
+        relatedFileScores,
+    };
+}
+//# sourceMappingURL=fragment.js.map

package/dist/agent/search/fragment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fragment.js","sourceRoot":"","sources":["../../../src/agent/search/fragment.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Runs fixed-string sentence-fragment search for quoted snippets in modular-agent search.\n *\n * Why this file exists:\n * - quoted code snippets should not collapse into broad semantic retrieval\n * - fragment search should stay separate from regex and semantic lanes\n */\nimport { extractQuotedFragments } from \"./searchContext.js\";\nimport { classifyFileRulePath } from \"../../fileRules/searchPathClassification.js\";\nimport type { AgentSearchPacket } from \"./types.js\";\nimport { collectFixedStringMatches, collectSearchablePaths, dedupeStrings } from \"./shared.js\";\n\nfunction isFragmentSearchablePath(filePath: string): boolean {\n  const classification = classifyFileRulePath(filePath);\n  return !classification.isGeneratedBuild\n    && !classification.isArtifact\n    && !classification.isLogLike\n    && !classification.isSourceMap\n    && !classification.isHarnessLike;\n}\n\nfunction computeFragmentFileBonus(filePath: string): number {\n  const classification = classifyFileRulePath(filePath);\n  const normalized = filePath.replace(/\\\\/g, \"/\").toLowerCase();\n  if (classification.isDocumentation) {\n    return -4;\n  }\n  if (normalized.includes(\"/__tests__/\") || normalized.endsWith(\".test.ts\") || normalized.endsWith(\".spec.ts\")) {\n    return 6;\n  }\n  if (normalized.includes(\"/src/\")) {\n    return 3;\n  }\n  return 0;\n}\n\nfunction computeFragmentSnippetContextBonus(snippet: string): number {\n  const trimmed = String(snippet ?? \"\").trim();\n  if (!trimmed) {\n    return 0;\n  }\n  let bonus = 0;\n  if (/\\b(?:it|test|describe)\\s*\\(/.test(trimmed)) {\n    bonus += 6;\n  }\n  if (/\\b(?:query|userQuery|prompt|input|expected|fixture)\\s*:/.test(trimmed)) {\n    bonus -= 5;\n  }\n  if (/^const\\s+[A-Za-z0-9_]+\\s*=/.test(trimmed)) {\n    bonus -= 4;\n  }\n  if (/^\\{?\\s*(?:path|filePath|targetFile)\\s*:/.test(trimmed)) {\n    bonus -= 3;\n  }\n  return bonus;\n}\n\nexport function runFragmentSearch(rootDir: string, query: string, limit = 5): AgentSearchPacket {\n  const fragments = extractQuotedFragments(query);\n  if (fragments.length === 0) {\n    return {\n      lane: \"fragment\",\n      query,\n      filePaths: [],\n    };\n  }\n\n  // Quoted fragment lookups need to search test files too, because many literal snippets only live in tests.\n  const files = collectSearchablePaths(rootDir, { allowIgnoredPaths: true })\n    .filter(isFragmentSearchablePath);\n  const matches = collectFixedStringMatches(files, fragments, \"fragment-content\", {\n    caseSensitive: true,\n    maxPerFile: 2,\n    // Keep the frontier wide enough that test/source hits are not dropped behind earlier doc matches.\n    maxTotal: Math.max(limit * 8, 24),\n  });\n  const bestScores = new Map<string, number>();\n  const perFileMatchCount = new Map<string, number>();\n  for (const match of matches) {\n    const adjustedScore = (match.score ?? 1) + computeFragmentSnippetContextBonus(match.snippet);\n    bestScores.set(match.filePath, Math.max(bestScores.get(match.filePath) ?? Number.NEGATIVE_INFINITY, adjustedScore));\n    perFileMatchCount.set(match.filePath, (perFileMatchCount.get(match.filePath) ?? 0) + 1);\n  }\n  const scoredHits = Array.from(bestScores.entries())\n    .map(([filePath, matchScore]) => ({\n      filePath,\n      matchScore,\n      duplicatePenalty: Math.max(0, (perFileMatchCount.get(filePath) ?? 0) - 1),\n      totalScore: matchScore + computeFragmentFileBonus(filePath) - Math.max(0, (perFileMatchCount.get(filePath) ?? 0) - 1) * 3,\n    }))\n    .sort((left, right) => {\n      if (right.totalScore !== left.totalScore) {\n        return right.totalScore - left.totalScore;\n      }\n      if (left.duplicatePenalty !== right.duplicatePenalty) {\n        return left.duplicatePenalty - right.duplicatePenalty;\n      }\n      if (right.matchScore !== left.matchScore) {\n        return right.matchScore - left.matchScore;\n      }\n      return left.filePath.localeCompare(right.filePath);\n    });\n  const preferredHits = scoredHits.some((entry) => !classifyFileRulePath(entry.filePath).isDocumentation)\n    ? scoredHits.filter((entry) => !classifyFileRulePath(entry.filePath).isDocumentation)\n    : scoredHits;\n\n  const hits = preferredHits.slice(0, limit).map((entry) => entry.filePath);\n  const relatedFileScores = Object.fromEntries(preferredHits.map((entry) => [entry.filePath, -entry.totalScore]));\n\n  return {\n    lane: \"fragment\",\n    query,\n    filePaths: dedupeStrings(hits),\n    matches,\n    relatedFileScores,\n  };\n}\n"]}

package/dist/agent/search/index.js

@@ -0,0 +1,166 @@
+/**
+ * Exposes one small search facade for the modular agent runtime.
+ *
+ * Why this file exists:
+ * - tool-backed actions should call one search entrypoint
+ * - route choice, lane execution, and candidate shaping should stay behind one facade
+ * - read policy should consume already-shaped search packets instead of raw lane output
+ * - Stage 2 builds one pre-search packet once and threads it through the search area
+ */
+import { logAgentSearchInput, logAgentSearchOutput } from "../logging/index.js";
+import { finalizeLanePacket } from "./candidateRetentionPolicy.js";
+import { DEFAULT_INTERNAL_SEMANTIC_LIMIT, DEFAULT_VISIBLE_SEARCH_LIMIT } from "./limits.js";
+import { runDirectorySearch as runDirectorySearchLane } from "./directory.js";
+import { runExactTargetSearch } from "./exactTarget.js";
+import { runFragmentSearch } from "./fragment.js";
+import { runRegexSearch as runRegexSearchLane } from "./regex.js";
+import { runShellSearch, shouldFallbackFromShell } from "./shell.js";
+import { classifySearchLane } from "./laneClassifier.js";
+import { buildSearchContext, isDirectoryLikeHint } from "./searchContext.js";
+import { runSemanticSearchBatches } from "./batchPlanner.js";
+import { runSemanticSearch } from "./semantic.js";
+function buildSearchOutputPayload(packet, fallbackUsed) {
+    return {
+        lane: packet.lane,
+        candidateCount: packet.filePaths.length,
+        filePaths: packet.filePaths,
+        topHits: packet.topHits ?? [],
+        matchesPreview: packet.matches?.slice(0, 6).map((match) => ({
+            filePath: match.filePath,
+            line: match.line,
+            column: match.column,
+            snippet: match.snippet,
+            matchKind: match.matchKind,
+            reasons: match.reasons,
+        })) ?? [],
+        failure: packet.failure ?? null,
+        ...(packet.directoryPath ? { directoryPath: packet.directoryPath } : {}),
+        ...(typeof packet.matchCount === "number" ? { matchCount: packet.matchCount } : {}),
+        ...(packet.lane === "semantic" && packet.debug ? {
+            semanticDebug: {
+                queriesRun: packet.debug.queriesRun?.slice(0, 3) ?? [],
+                recoveryUsed: packet.debug.recoveryUsed,
+                recoveryReason: packet.debug.recoveryReason,
+                matchTerms: packet.debug.matchTerms?.slice(0, 8) ?? [],
+            },
+        } : {}),
+        ...(packet.debug?.batchDebug ? {
+            searchBatchDebug: packet.debug.batchDebug,
+        } : {}),
+        route: {
+            chosenLane: packet.lane,
+            fallbackUsed: packet.lane === "semantic"
+                ? Boolean(packet.debug?.recoveryUsed) || fallbackUsed
+                : fallbackUsed,
+        },
+    };
+}
+async function runLane(route, context, memory, semanticRetrievalLimit, visibleLimit) {
+    switch (route) {
+        case "directory": {
+            const folderHint = context.softHints.find(isDirectoryLikeHint)
+                ?? context.explicitTargets.find(isDirectoryLikeHint)
+                ?? context.resolvedTargets.find((resolution) => resolution.kind === "resolved-folder")?.folderPath
+                ?? memory.session.executionPath;
+            return runDirectorySearchLane(memory.session.executionPath, folderHint);
+        }
+        case "exact-target":
+            return runExactTargetSearch(memory.session.executionPath, context.query, context.explicitTargets);
+        case "fragment":
+            return runFragmentSearch(memory.session.executionPath, context.query, visibleLimit);
+        case "regex":
+            return runRegexSearchLane(memory.session.executionPath, context.query, "content");
+        case "shell-content":
+            return runShellSearch(memory.session.executionPath, context.query, visibleLimit);
+        case "semantic":
+        default:
+            return runSemanticSearch(memory.session.executionPath, context.query, semanticRetrievalLimit);
+    }
+}
+function resolveSemanticRetrievalLimit(visibleLimit) {
+    return Math.max(visibleLimit, DEFAULT_INTERNAL_SEMANTIC_LIMIT);
+}
+async function runSearchLane(route, context, memory, semanticRetrievalLimit, visibleLimit) {
+    if (route !== "semantic") {
+        return runLane(route, context, memory, semanticRetrievalLimit, visibleLimit);
+    }
+    return runSemanticSearchBatches(memory, context, visibleLimit, async (batchQuery) => runSemanticSearch(memory.session.executionPath, batchQuery, semanticRetrievalLimit));
+}
+export async function runSearchDb(memory, query, limit = DEFAULT_VISIBLE_SEARCH_LIMIT) {
+    const stepId = memory.task.currentStepId;
+    const context = buildSearchContext(memory, query, {
+        allowDirectoryLane: false,
+        allowRegexLane: false,
+    });
+    logAgentSearchInput(memory, context, stepId);
+    const routeDecision = classifySearchLane(context);
+    const route = routeDecision.lane;
+    const semanticRetrievalLimit = resolveSemanticRetrievalLimit(limit);
+    const packet = await runSearchLane(route, context, memory, semanticRetrievalLimit, limit);
+    if (packet.lane === "exact-target" && packet.filePaths.length === 0 && packet.failure?.failureClass !== "ambiguous") {
+        const semantic = await runSemanticSearchBatches(memory, context, limit, async (batchQuery) => runSemanticSearch(memory.session.executionPath, batchQuery, semanticRetrievalLimit));
+        const finalized = finalizeLanePacket("semantic", memory, semantic, limit);
+        logAgentSearchOutput(memory, buildSearchOutputPayload(finalized, true), stepId);
+        return finalized;
+    }
+    if (shouldFallbackFromShell(packet)) {
+        const semantic = await runSemanticSearch(memory.session.executionPath, query, semanticRetrievalLimit);
+        const finalized = finalizeLanePacket("semantic", memory, semantic, limit);
+        logAgentSearchOutput(memory, buildSearchOutputPayload(finalized, true), stepId);
+        return finalized;
+    }
+    const finalized = finalizeLanePacket(packet.lane, memory, packet, limit);
+    logAgentSearchOutput(memory, buildSearchOutputPayload(finalized, false), stepId);
+    return finalized;
+}
+export async function runSearchAuto(memory, query, limit = DEFAULT_VISIBLE_SEARCH_LIMIT) {
+    const stepId = memory.task.currentStepId;
+    const context = buildSearchContext(memory, query, {
+        allowDirectoryLane: true,
+        allowRegexLane: true,
+    });
+    logAgentSearchInput(memory, context, stepId);
+    const routeDecision = classifySearchLane(context);
+    const route = routeDecision.lane;
+    const semanticRetrievalLimit = resolveSemanticRetrievalLimit(limit);
+    const packet = await runSearchLane(route, context, memory, semanticRetrievalLimit, limit);
+    if (packet.lane === "exact-target" && packet.filePaths.length === 0 && packet.failure?.failureClass !== "ambiguous") {
+        const semantic = await runSemanticSearchBatches(memory, context, limit, async (batchQuery) => runSemanticSearch(memory.session.executionPath, batchQuery, semanticRetrievalLimit));
+        const finalized = finalizeLanePacket("semantic", memory, semantic, limit);
+        logAgentSearchOutput(memory, buildSearchOutputPayload(finalized, true), stepId);
+        return finalized;
+    }
+    if (shouldFallbackFromShell(packet)) {
+        const semantic = await runSemanticSearch(memory.session.executionPath, query, semanticRetrievalLimit);
+        const finalized = finalizeLanePacket("semantic", memory, semantic, limit);
+        logAgentSearchOutput(memory, buildSearchOutputPayload(finalized, true), stepId);
+        return finalized;
+    }
+    const finalized = finalizeLanePacket(packet.lane, memory, packet, limit);
+    logAgentSearchOutput(memory, buildSearchOutputPayload(finalized, false), stepId);
+    return finalized;
+}
+export function runLoggedDirectorySearch(memory, folderPath) {
+    const stepId = memory.task.currentStepId;
+    const context = buildSearchContext(memory, folderPath, {
+        allowDirectoryLane: true,
+        allowRegexLane: false,
+    });
+    logAgentSearchInput(memory, context, stepId);
+    const packet = runDirectorySearchLane(memory.session.executionPath, folderPath);
+    logAgentSearchOutput(memory, buildSearchOutputPayload(packet, false), stepId);
+    return packet;
+}
+export function runLoggedRegexSearch(memory, pattern, target, flags) {
+    const stepId = memory.task.currentStepId;
+    const context = buildSearchContext(memory, pattern, {
+        allowDirectoryLane: false,
+        allowRegexLane: true,
+    });
+    logAgentSearchInput(memory, context, stepId);
+    const packet = runRegexSearchLane(memory.session.executionPath, pattern, target, flags);
+    logAgentSearchOutput(memory, buildSearchOutputPayload(packet, false), stepId);
+    return packet;
+}
+export { runDirectorySearchLane as runDirectorySearch, runRegexSearchLane as runRegexSearch };
+//# sourceMappingURL=index.js.map

package/dist/agent/search/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agent/search/index.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Exposes one small search facade for the modular agent runtime.\n *\n * Why this file exists:\n * - tool-backed actions should call one search entrypoint\n * - route choice, lane execution, and candidate shaping should stay behind one facade\n * - read policy should consume already-shaped search packets instead of raw lane output\n * - Stage 2 builds one pre-search packet once and threads it through the search area\n */\nimport { logAgentSearchInput, logAgentSearchOutput } from \"../logging/index.js\";\nimport type { AgentMemory } from \"../types.js\";\nimport type { AgentSearchPacket } from \"./types.js\";\nimport { finalizeLanePacket } from \"./candidateRetentionPolicy.js\";\nimport { DEFAULT_INTERNAL_SEMANTIC_LIMIT, DEFAULT_VISIBLE_SEARCH_LIMIT } from \"./limits.js\";\nimport { runDirectorySearch as runDirectorySearchLane } from \"./directory.js\";\nimport { runExactTargetSearch } from \"./exactTarget.js\";\nimport { runFragmentSearch } from \"./fragment.js\";\nimport { runRegexSearch as runRegexSearchLane } from \"./regex.js\";\nimport { runShellSearch, shouldFallbackFromShell } from \"./shell.js\";\nimport { classifySearchLane } from \"./laneClassifier.js\";\nimport { chooseSearchRoute } from \"./routePolicy.js\";\nimport { buildSearchContext, isDirectoryLikeHint, type AgentSearchContext } from \"./searchContext.js\";\nimport { runSemanticSearchBatches } from \"./batchPlanner.js\";\nimport { runSemanticSearch } from \"./semantic.js\";\n\nfunction buildSearchOutputPayload(\n  packet: AgentSearchPacket,\n  fallbackUsed: boolean\n) {\n  return {\n    lane: packet.lane,\n    candidateCount: packet.filePaths.length,\n    filePaths: packet.filePaths,\n    topHits: packet.topHits ?? [],\n    matchesPreview: packet.matches?.slice(0, 6).map((match) => ({\n      filePath: match.filePath,\n      line: match.line,\n      column: match.column,\n      snippet: match.snippet,\n      matchKind: match.matchKind,\n      reasons: match.reasons,\n    })) ?? [],\n    failure: packet.failure ?? null,\n    ...(packet.directoryPath ? { directoryPath: packet.directoryPath } : {}),\n    ...(typeof packet.matchCount === \"number\" ? { matchCount: packet.matchCount } : {}),\n    ...(packet.lane === \"semantic\" && packet.debug ? {\n      semanticDebug: {\n        queriesRun: packet.debug.queriesRun?.slice(0, 3) ?? [],\n        recoveryUsed: packet.debug.recoveryUsed,\n        recoveryReason: packet.debug.recoveryReason,\n        matchTerms: packet.debug.matchTerms?.slice(0, 8) ?? [],\n      },\n    } : {}),\n    ...(packet.debug?.batchDebug ? {\n      searchBatchDebug: packet.debug.batchDebug,\n    } : {}),\n    route: {\n      chosenLane: packet.lane,\n      fallbackUsed: packet.lane === \"semantic\"\n        ? Boolean(packet.debug?.recoveryUsed) || fallbackUsed\n        : fallbackUsed,\n    },\n  } as const;\n}\n\nasync function runLane(\n  route: AgentSearchPacket[\"lane\"],\n  context: AgentSearchContext,\n  memory: AgentMemory,\n  semanticRetrievalLimit: number,\n  visibleLimit: number\n): Promise<AgentSearchPacket> {\n  switch (route) {\n    case \"directory\": {\n      const folderHint = context.softHints.find(isDirectoryLikeHint)\n        ?? context.explicitTargets.find(isDirectoryLikeHint)\n        ?? context.resolvedTargets.find((resolution) => resolution.kind === \"resolved-folder\")?.folderPath\n        ?? memory.session.executionPath;\n      return runDirectorySearchLane(memory.session.executionPath, folderHint);\n    }\n    case \"exact-target\":\n      return runExactTargetSearch(memory.session.executionPath, context.query, context.explicitTargets);\n    case \"fragment\":\n      return runFragmentSearch(memory.session.executionPath, context.query, visibleLimit);\n    case \"regex\":\n      return runRegexSearchLane(memory.session.executionPath, context.query, \"content\");\n    case \"shell-content\":\n      return runShellSearch(memory.session.executionPath, context.query, visibleLimit);\n    case \"semantic\":\n    default:\n      return runSemanticSearch(\n        memory.session.executionPath,\n        context.query,\n        semanticRetrievalLimit\n      );\n  }\n}\n\nfunction resolveSemanticRetrievalLimit(visibleLimit: number): number {\n  return Math.max(visibleLimit, DEFAULT_INTERNAL_SEMANTIC_LIMIT);\n}\n\nasync function runSearchLane(\n  route: AgentSearchPacket[\"lane\"],\n  context: AgentSearchContext,\n  memory: AgentMemory,\n  semanticRetrievalLimit: number,\n  visibleLimit: number\n): Promise<AgentSearchPacket> {\n  if (route !== \"semantic\") {\n    return runLane(route, context, memory, semanticRetrievalLimit, visibleLimit);\n  }\n  return runSemanticSearchBatches(\n    memory,\n    context,\n    visibleLimit,\n    async (batchQuery) => runSemanticSearch(\n      memory.session.executionPath,\n      batchQuery,\n      semanticRetrievalLimit\n    )\n  );\n}\n\nexport async function runSearchDb(\n  memory: AgentMemory,\n  query: string,\n  limit = DEFAULT_VISIBLE_SEARCH_LIMIT\n): Promise<AgentSearchPacket> {\n  const stepId = memory.task.currentStepId;\n  const context = buildSearchContext(memory, query, {\n    allowDirectoryLane: false,\n    allowRegexLane: false,\n  });\n  logAgentSearchInput(memory, context, stepId);\n\n  const routeDecision = classifySearchLane(context);\n  const route = routeDecision.lane;\n  const semanticRetrievalLimit = resolveSemanticRetrievalLimit(limit);\n  const packet = await runSearchLane(route, context, memory, semanticRetrievalLimit, limit);\n  if (packet.lane === \"exact-target\" && packet.filePaths.length === 0 && packet.failure?.failureClass !== \"ambiguous\") {\n    const semantic = await runSemanticSearchBatches(\n      memory,\n      context,\n      limit,\n      async (batchQuery) => runSemanticSearch(\n        memory.session.executionPath,\n        batchQuery,\n        semanticRetrievalLimit\n      )\n    );\n    const finalized = finalizeLanePacket(\"semantic\", memory, semantic, limit);\n    logAgentSearchOutput(memory, buildSearchOutputPayload(finalized, true), stepId);\n    return finalized;\n  }\n  if (shouldFallbackFromShell(packet)) {\n    const semantic = await runSemanticSearch(\n      memory.session.executionPath,\n      query,\n      semanticRetrievalLimit\n    );\n    const finalized = finalizeLanePacket(\"semantic\", memory, semantic, limit);\n    logAgentSearchOutput(memory, buildSearchOutputPayload(finalized, true), stepId);\n    return finalized;\n  }\n  const finalized = finalizeLanePacket(packet.lane, memory, packet, limit);\n  logAgentSearchOutput(memory, buildSearchOutputPayload(finalized, false), stepId);\n  return finalized;\n}\n\nexport async function runSearchAuto(\n  memory: AgentMemory,\n  query: string,\n  limit = DEFAULT_VISIBLE_SEARCH_LIMIT\n): Promise<AgentSearchPacket> {\n  const stepId = memory.task.currentStepId;\n  const context = buildSearchContext(memory, query, {\n    allowDirectoryLane: true,\n    allowRegexLane: true,\n  });\n  logAgentSearchInput(memory, context, stepId);\n\n  const routeDecision = classifySearchLane(context);\n  const route = routeDecision.lane;\n  const semanticRetrievalLimit = resolveSemanticRetrievalLimit(limit);\n  const packet = await runSearchLane(route, context, memory, semanticRetrievalLimit, limit);\n  if (packet.lane === \"exact-target\" && packet.filePaths.length === 0 && packet.failure?.failureClass !== \"ambiguous\") {\n    const semantic = await runSemanticSearchBatches(\n      memory,\n      context,\n      limit,\n      async (batchQuery) => runSemanticSearch(\n        memory.session.executionPath,\n        batchQuery,\n        semanticRetrievalLimit\n      )\n    );\n    const finalized = finalizeLanePacket(\"semantic\", memory, semantic, limit);\n    logAgentSearchOutput(memory, buildSearchOutputPayload(finalized, true), stepId);\n    return finalized;\n  }\n  if (shouldFallbackFromShell(packet)) {\n    const semantic = await runSemanticSearch(\n      memory.session.executionPath,\n      query,\n      semanticRetrievalLimit\n    );\n    const finalized = finalizeLanePacket(\"semantic\", memory, semantic, limit);\n    logAgentSearchOutput(memory, buildSearchOutputPayload(finalized, true), stepId);\n    return finalized;\n  }\n  const finalized = finalizeLanePacket(packet.lane, memory, packet, limit);\n  logAgentSearchOutput(memory, buildSearchOutputPayload(finalized, false), stepId);\n  return finalized;\n}\n\nexport function runLoggedDirectorySearch(memory: AgentMemory, folderPath: string): AgentSearchPacket {\n  const stepId = memory.task.currentStepId;\n  const context = buildSearchContext(memory, folderPath, {\n    allowDirectoryLane: true,\n    allowRegexLane: false,\n  });\n  logAgentSearchInput(memory, context, stepId);\n  const packet = runDirectorySearchLane(memory.session.executionPath, folderPath);\n  logAgentSearchOutput(memory, buildSearchOutputPayload(packet, false), stepId);\n  return packet;\n}\n\nexport function runLoggedRegexSearch(\n  memory: AgentMemory,\n  pattern: string,\n  target: \"path\" | \"content\" | \"both\",\n  flags?: string\n): AgentSearchPacket {\n  const stepId = memory.task.currentStepId;\n  const context = buildSearchContext(memory, pattern, {\n    allowDirectoryLane: false,\n    allowRegexLane: true,\n  });\n  logAgentSearchInput(memory, context, stepId);\n  const packet = runRegexSearchLane(memory.session.executionPath, pattern, target, flags);\n  logAgentSearchOutput(memory, buildSearchOutputPayload(packet, false), stepId);\n  return packet;\n}\n\nexport { runDirectorySearchLane as runDirectorySearch, runRegexSearchLane as runRegexSearch };\n"]}

package/dist/agent/search/laneClassifier.js

@@ -0,0 +1,119 @@
+import { isDirectoryLikeHint, isStrongFileLikeRef } from "./searchContext.js";
+/**
+ * Detects direct folder-content questions before file search runs.
+ * Example: `list files in cli/src/agent/search` should use the directory lane.
+ */
+export function looksLikeDirectoryListingQuery(context) {
+    const lowered = String(context.query ?? "").toLowerCase();
+    const hasStrongFileTarget = context.explicitTargets.some(isStrongFileLikeRef);
+    if (hasStrongFileTarget) {
+        return false;
+    }
+    const hasListingVerb = /\b(list|contents?|files|folders|show)\b/.test(lowered);
+    const hasFolderWord = /\b(folder|directory|contents?)\b/.test(lowered);
+    const hasFolderHint = context.softHints.some(isDirectoryLikeHint) || context.explicitTargets.some(isDirectoryLikeHint);
+    const asksForExplanation = /\b(why|how|what does|explain|trace|summari[sz]e)\b/.test(lowered);
+    return hasListingVerb && (hasFolderWord || hasFolderHint) && !asksForExplanation;
+}
+function resolveExplicitFolderTarget(context) {
+    return context.resolvedTargets.find((resolution) => resolution.kind === "resolved-folder")?.folderPath;
+}
+function resolveExplicitFileTarget(context) {
+    const resolvedFile = context.resolvedTargets.find((resolution) => resolution.kind === "resolved-file");
+    if (resolvedFile?.kind === "resolved-file") {
+        return resolvedFile.filePath;
+    }
+    if (context.explicitTargets.some(isStrongFileLikeRef)) {
+        return context.explicitTargets.find(isStrongFileLikeRef);
+    }
+    if (context.quotedFragments.length === 0 && context.explicitTargets.length > 0) {
+        return context.explicitTargets[0];
+    }
+    return undefined;
+}
+function hasUnresolvedExplicitTarget(context) {
+    if (context.explicitTargets.length === 0) {
+        return false;
+    }
+    if (resolveExplicitFolderTarget(context) || resolveExplicitFileTarget(context)) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Detects broad read-only repo questions that are best served by literal content search first.
+ * Example: `where do I set the max count for how many loops the agent can run?` should try grep-like search.
+ */
+function looksLikeShellContentQuery(context) {
+    if (context.explicitTargets.length > 0 || context.quotedFragments.length > 0 || context.regexLike) {
+        return false;
+    }
+    const lowered = String(context.query ?? "").toLowerCase();
+    const asksForOwner = /\b(where|which|what)\b/.test(lowered) &&
+        /\b(set|sets|setting|defined|defines|configured|configures|controls|decides|owner|owns|limit|limits|threshold|count|max)\b/.test(lowered);
+    const asksForSpecificField = /\bwhere\b.+\b(set|defined|configured)\b/.test(lowered) ||
+        /\bwhich\s+file\b.+\b(set|defines|configures|controls|decides)\b/.test(lowered) ||
+        /\bwhat\s+file\b.+\b(set|defines|configures|controls|decides)\b/.test(lowered);
+    const broadScope = context.scopeKind === "broad-repo" || context.scopeKind === "general";
+    return broadScope && (asksForOwner || asksForSpecificField);
+}
+/**
+ * Chooses one search lane from the shared context packet.
+ * Example: a resolved folder target uses `directory`, while a quoted snippet uses `fragment`.
+ */
+export function classifySearchLane(context) {
+    const resolvedFolder = resolveExplicitFolderTarget(context);
+    if (resolvedFolder && context.allowDirectoryLane) {
+        return {
+            lane: "directory",
+            reason: "resolved explicit folder target",
+            resolvedTarget: resolvedFolder,
+        };
+    }
+    if (context.allowDirectoryLane && looksLikeDirectoryListingQuery(context)) {
+        return {
+            lane: "directory",
+            reason: "directory-listing wording with folder-like hints",
+            resolvedTarget: context.softHints.find(isDirectoryLikeHint)
+                ?? context.explicitTargets.find(isDirectoryLikeHint),
+        };
+    }
+    const resolvedFile = resolveExplicitFileTarget(context);
+    if (resolvedFile) {
+        return {
+            lane: "exact-target",
+            reason: "explicit file-like or resolved file target",
+            resolvedTarget: resolvedFile,
+        };
+    }
+    if (context.quotedFragments.length > 0) {
+        return {
+            lane: "fragment",
+            reason: "quoted fragment present in the query",
+        };
+    }
+    if (context.allowRegexLane && context.regexLike) {
+        return {
+            lane: "regex",
+            reason: "regex-like query with regex lane enabled",
+        };
+    }
+    if (hasUnresolvedExplicitTarget(context)) {
+        return {
+            lane: "exact-target",
+            reason: "unresolved explicit target still needs exact-target search",
+            resolvedTarget: context.explicitTargets[0],
+        };
+    }
+    if (looksLikeShellContentQuery(context)) {
+        return {
+            lane: "shell-content",
+            reason: "broad read-only question with no explicit target",
+        };
+    }
+    return {
+        lane: "semantic",
+        reason: "no explicit lane signals matched",
+    };
+}
+//# sourceMappingURL=laneClassifier.js.map