scai 0.1.178 → 1.0.0

package/dist/agent/search/batchPlanner.js

@@ -0,0 +1,274 @@
+/**
+ * Plans grouped semantic search batches from understand-owned term hints.
+ *
+ * Why this file exists:
+ * - grouped search expansion should have one owner in the search area
+ * - search should decide batch order and stop conditions without leaking that logic into lanes
+ * - semantic search should stay broad enough to recover, but still stop early on strong evidence
+ */
+import { finalizeLanePacket } from "./candidateRetentionPolicy.js";
+const WEAK_SEMANTIC_TERMS = new Set([
+    "agent",
+    "code",
+    "config",
+    "configuration",
+    "file",
+    "files",
+    "project",
+    "repo",
+    "repository",
+    "script",
+    "scripts",
+    "setting",
+    "source",
+    "test",
+    "tests",
+]);
+const SEARCH_TERM_GROUP_ORDER = [
+    "repo-anchor",
+    "command-path",
+    "generic",
+];
+function dedupeStrings(values) {
+    const seen = new Set();
+    const out = [];
+    for (const value of values) {
+        const trimmed = String(value ?? "").trim();
+        if (!trimmed) {
+            continue;
+        }
+        const key = trimmed.toLowerCase();
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        out.push(trimmed);
+    }
+    return out;
+}
+function dedupeMatches(matches) {
+    const seen = new Set();
+    const out = [];
+    for (const match of matches) {
+        const key = [match.filePath, match.line ?? "", match.column ?? "", match.matchKind, match.snippet].join("|");
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        out.push(match);
+    }
+    return out;
+}
+function buildTermGroupQuery(terms) {
+    return dedupeStrings(terms).join(" ");
+}
+function isWeakSemanticTerm(term) {
+    return WEAK_SEMANTIC_TERMS.has(String(term ?? "").trim().toLowerCase());
+}
+function looksLikeConfigurationIntent(context) {
+    const lowered = String(context.query ?? "").toLowerCase();
+    return /\b(where|which|what)\b/.test(lowered)
+        && /\b(set|setting|configured|configuration|register|registered|entry|entrypoint|command|commands|limit|count|max)\b/.test(lowered);
+}
+export function buildSemanticSearchBatchPlan(context) {
+    const batches = [{
+            query: context.query,
+            source: "base-query",
+        }];
+    const seenQueries = new Set([String(context.query ?? "").trim().toLowerCase()]);
+    const prioritizedGroups = SEARCH_TERM_GROUP_ORDER.flatMap((kind) => context.searchTermGroups
+        .map((group, index) => ({ group, index }))
+        .filter((entry) => entry.group.kind === kind));
+    for (const { group, index } of prioritizedGroups) {
+        const terms = dedupeStrings(group.terms);
+        if (terms.length === 0) {
+            continue;
+        }
+        const query = buildTermGroupQuery(terms);
+        const key = query.toLowerCase();
+        if (!query || seenQueries.has(key)) {
+            continue;
+        }
+        seenQueries.add(key);
+        batches.push({
+            query,
+            source: "search-term-group",
+            termGroupIndex: index,
+            kind: group.kind,
+            terms,
+        });
+    }
+    return batches;
+}
+function mergeRelatedFileScores(left = {}, right = {}) {
+    const merged = { ...left };
+    for (const [filePath, score] of Object.entries(right)) {
+        const current = merged[filePath];
+        merged[filePath] = typeof current === "number" ? Math.min(current, score) : score;
+    }
+    return merged;
+}
+function mergeSearchPackets(baseQuery, packets) {
+    const first = packets[0];
+    const mergedDebug = {
+        queriesRun: dedupeStrings(packets.flatMap((packet) => packet.debug?.queriesRun ?? [])),
+        recoveryUsed: packets.some((packet) => packet.debug?.recoveryUsed === true),
+        matchTerms: dedupeStrings(packets.flatMap((packet) => packet.debug?.matchTerms ?? [])),
+    };
+    const recoveryReasons = dedupeStrings(packets.flatMap((packet) => packet.debug?.recoveryReason ? [packet.debug.recoveryReason] : []));
+    return {
+        lane: first.lane,
+        query: baseQuery,
+        filePaths: dedupeStrings(packets.flatMap((packet) => packet.filePaths)),
+        matches: dedupeMatches(packets.flatMap((packet) => packet.matches ?? [])),
+        relatedFileScores: packets.reduce((acc, packet) => mergeRelatedFileScores(acc, packet.relatedFileScores), {}),
+        debug: {
+            queriesRun: mergedDebug.queriesRun,
+            recoveryUsed: mergedDebug.recoveryUsed,
+            matchTerms: mergedDebug.matchTerms,
+            ...(recoveryReasons.length > 0 ? { recoveryReason: recoveryReasons.join(",") } : {}),
+        },
+    };
+}
+function extractMatchedTerms(packet) {
+    return dedupeStrings((packet.matches ?? [])
+        .flatMap((match) => match.reasons ?? [])
+        .map((reason) => reason.match(/^term:(.+)$/i)?.[1] ?? "")
+        .filter(Boolean));
+}
+function extractTopHitConfirmations(packet) {
+    const confirmations = new Set();
+    for (const hit of packet.topHits ?? []) {
+        for (const reason of hit.reasons) {
+            if (!reason.startsWith("match-confirmation:")) {
+                continue;
+            }
+            for (const term of reason.slice("match-confirmation:".length).split(",")) {
+                const normalized = term.trim().toLowerCase();
+                if (!normalized || isWeakSemanticTerm(normalized)) {
+                    continue;
+                }
+                confirmations.add(normalized);
+            }
+        }
+    }
+    return Array.from(confirmations);
+}
+function hasConcreteSnippetEvidence(packet) {
+    const perFileConcreteTerms = new Map();
+    for (const match of packet.matches ?? []) {
+        const concreteTerms = (match.reasons ?? [])
+            .map((reason) => reason.match(/^term:(.+)$/i)?.[1]?.toLowerCase())
+            .filter((term) => Boolean(term))
+            .filter((term) => !isWeakSemanticTerm(term));
+        if (concreteTerms.length === 0) {
+            continue;
+        }
+        const current = perFileConcreteTerms.get(match.filePath) ?? new Set();
+        for (const term of concreteTerms) {
+            current.add(term);
+        }
+        perFileConcreteTerms.set(match.filePath, current);
+    }
+    return Array.from(perFileConcreteTerms.values()).some((terms) => terms.size >= 2);
+}
+function hasStrongMatchConfirmation(packet) {
+    const perFileStrongTerms = new Map();
+    for (const match of packet.matches ?? []) {
+        const terms = (match.reasons ?? [])
+            .map((reason) => reason.match(/^term:(.+)$/i)?.[1]?.toLowerCase())
+            .filter((term) => Boolean(term))
+            .filter((term) => !isWeakSemanticTerm(term));
+        if (terms.length === 0) {
+            continue;
+        }
+        const current = perFileStrongTerms.get(match.filePath) ?? new Set();
+        for (const term of terms) {
+            current.add(term);
+        }
+        perFileStrongTerms.set(match.filePath, current);
+    }
+    return Array.from(perFileStrongTerms.values()).some((terms) => terms.size >= 2);
+}
+function hasStrongTopHitAnchor(packet) {
+    return (packet.topHits ?? []).slice(0, 3).some((hit) => hit.reasons.some((reason) => reason === "path-anchor"
+        || reason.startsWith("exact-basename:")
+        || (reason.startsWith("symbol:")
+            && !isWeakSemanticTerm(String(reason.split(":")[1] ?? "").toLowerCase()))
+        || ((/^match-confirmation:/).test(reason)
+            && reason
+                .split(":")[1]
+                ?.split(",")
+                .map((term) => term.trim().toLowerCase())
+                .filter((term) => term && !isWeakSemanticTerm(term))
+                .length >= 2)));
+}
+function resolveStrongEnough(packet, context) {
+    const matchedTerms = extractMatchedTerms(packet).filter((term) => !isWeakSemanticTerm(term));
+    const topHitConfirmations = extractTopHitConfirmations(packet);
+    const configIntent = looksLikeConfigurationIntent(context);
+    const concreteSnippetEvidence = hasConcreteSnippetEvidence(packet);
+    const strongMatchConfirmation = hasStrongMatchConfirmation(packet);
+    if (hasStrongTopHitAnchor(packet)) {
+        if (!strongMatchConfirmation && !concreteSnippetEvidence && topHitConfirmations.length === 0) {
+            return { strongEnough: false, reason: "top hits are anchored but still too generic to stop" };
+        }
+        if (configIntent && topHitConfirmations.length < 2 && !concreteSnippetEvidence) {
+            return { strongEnough: false, reason: "top hits are anchored but still too generic for config intent" };
+        }
+        return { strongEnough: true, reason: "top hits include strong anchors" };
+    }
+    if (strongMatchConfirmation) {
+        return { strongEnough: true, reason: "one file has multiple concrete matched terms" };
+    }
+    if (concreteSnippetEvidence) {
+        return { strongEnough: true, reason: "snippets contain concrete multi-term evidence" };
+    }
+    if (matchedTerms.length >= 4 && topHitConfirmations.length >= 2 && !configIntent) {
+        return { strongEnough: true, reason: "matched terms are concrete and broad enough to stop" };
+    }
+    return { strongEnough: false, reason: "evidence is still driven by weak semantic terms" };
+}
+export async function runSemanticSearchBatches(memory, context, visibleLimit, runBatch) {
+    const batches = buildSemanticSearchBatchPlan(context);
+    const rawPackets = [];
+    const batchDebug = [];
+    for (let index = 0; index < batches.length; index += 1) {
+        const batch = batches[index];
+        const packet = await runBatch(batch.query);
+        rawPackets.push(packet);
+        const merged = mergeSearchPackets(context.query, rawPackets);
+        const scored = finalizeLanePacket("semantic", memory, merged, visibleLimit);
+        const confidence = resolveStrongEnough(scored, context);
+        const strongEnough = confidence.strongEnough;
+        const continued = index < batches.length - 1 && !strongEnough;
+        batchDebug.push({
+            query: batch.query,
+            source: batch.source,
+            ...(typeof batch.termGroupIndex === "number" ? { termGroupIndex: batch.termGroupIndex } : {}),
+            ...(batch.kind ? { kind: batch.kind } : {}),
+            ...(batch.terms ? { terms: batch.terms } : {}),
+            continued,
+            strongEnough,
+            strongReason: confidence.reason,
+        });
+        if (!continued) {
+            return {
+                ...merged,
+                debug: {
+                    ...(merged.debug ?? {}),
+                    batchDebug,
+                },
+            };
+        }
+    }
+    const merged = mergeSearchPackets(context.query, rawPackets);
+    return {
+        ...merged,
+        debug: {
+            ...(merged.debug ?? {}),
+            batchDebug,
+        },
+    };
+}
+//# sourceMappingURL=batchPlanner.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"batchPlanner.js","sourceRoot":"","sources":["../../../src/agent/search/batchPlanner.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Plans grouped semantic search batches from understand-owned term hints.\n *\n * Why this file exists:\n * - grouped search expansion should have one owner in the search area\n * - search should decide batch order and stop conditions without leaking that logic into lanes\n * - semantic search should stay broad enough to recover, but still stop early on strong evidence\n */\nimport { finalizeLanePacket } from \"./candidateRetentionPolicy.js\";\nimport type { AgentSearchContext } from \"./searchContext.js\";\nimport type { AgentSearchPacket } from \"./types.js\";\nimport type { AgentMemory, AgentSearchTermGroup, AgentSearchTermGroupKind } from \"../types.js\";\n\nconst WEAK_SEMANTIC_TERMS = new Set([\n  \"agent\",\n  \"code\",\n  \"config\",\n  \"configuration\",\n  \"file\",\n  \"files\",\n  \"project\",\n  \"repo\",\n  \"repository\",\n  \"script\",\n  \"scripts\",\n  \"setting\",\n  \"source\",\n  \"test\",\n  \"tests\",\n]);\n\nexport interface SearchBatchPlanEntry {\n  query: string;\n  source: \"base-query\" | \"search-term-group\";\n  termGroupIndex?: number;\n  kind?: AgentSearchTermGroupKind;\n  terms?: string[];\n}\n\ntype SearchBatchDebugEntry = {\n  query: string;\n  source: \"base-query\" | \"search-term-group\";\n  termGroupIndex?: number;\n  kind?: AgentSearchTermGroupKind;\n  terms?: string[];\n  continued: boolean;\n  strongEnough: boolean;\n  strongReason?: string;\n};\n\nconst SEARCH_TERM_GROUP_ORDER: AgentSearchTermGroupKind[] = [\n  \"repo-anchor\",\n  \"command-path\",\n  \"generic\",\n];\n\nfunction dedupeStrings(values: string[]): string[] {\n  const seen = new Set<string>();\n  const out: string[] = [];\n  for (const value of values) {\n    const trimmed = String(value ?? \"\").trim();\n    if (!trimmed) {\n      continue;\n    }\n    const key = trimmed.toLowerCase();\n    if (seen.has(key)) {\n      continue;\n    }\n    seen.add(key);\n    out.push(trimmed);\n  }\n  return out;\n}\n\nfunction dedupeMatches(matches: NonNullable<AgentSearchPacket[\"matches\"]>): NonNullable<AgentSearchPacket[\"matches\"]> {\n  const seen = new Set<string>();\n  const out: NonNullable<AgentSearchPacket[\"matches\"]> = [];\n  for (const match of matches) {\n    const key = [match.filePath, match.line ?? \"\", match.column ?? \"\", match.matchKind, match.snippet].join(\"|\");\n    if (seen.has(key)) {\n      continue;\n    }\n    seen.add(key);\n    out.push(match);\n  }\n  return out;\n}\n\nfunction buildTermGroupQuery(terms: string[]): string {\n  return dedupeStrings(terms).join(\" \");\n}\n\nfunction isWeakSemanticTerm(term: string): boolean {\n  return WEAK_SEMANTIC_TERMS.has(String(term ?? \"\").trim().toLowerCase());\n}\n\nfunction looksLikeConfigurationIntent(context: AgentSearchContext): boolean {\n  const lowered = String(context.query ?? \"\").toLowerCase();\n  return /\\b(where|which|what)\\b/.test(lowered)\n    && /\\b(set|setting|configured|configuration|register|registered|entry|entrypoint|command|commands|limit|count|max)\\b/.test(lowered);\n}\n\nexport function buildSemanticSearchBatchPlan(context: AgentSearchContext): SearchBatchPlanEntry[] {\n  const batches: SearchBatchPlanEntry[] = [{\n    query: context.query,\n    source: \"base-query\",\n  }];\n  const seenQueries = new Set([String(context.query ?? \"\").trim().toLowerCase()]);\n\n  const prioritizedGroups = SEARCH_TERM_GROUP_ORDER.flatMap((kind) =>\n    context.searchTermGroups\n      .map((group, index) => ({ group, index }))\n      .filter((entry) => entry.group.kind === kind)\n  );\n\n  for (const { group, index } of prioritizedGroups) {\n    const terms = dedupeStrings(group.terms);\n    if (terms.length === 0) {\n      continue;\n    }\n    const query = buildTermGroupQuery(terms);\n    const key = query.toLowerCase();\n    if (!query || seenQueries.has(key)) {\n      continue;\n    }\n    seenQueries.add(key);\n    batches.push({\n      query,\n      source: \"search-term-group\",\n      termGroupIndex: index,\n      kind: group.kind,\n      terms,\n    });\n  }\n\n  return batches;\n}\n\nfunction mergeRelatedFileScores(\n  left: Record<string, number> = {},\n  right: Record<string, number> = {}\n): Record<string, number> {\n  const merged = { ...left };\n  for (const [filePath, score] of Object.entries(right)) {\n    const current = merged[filePath];\n    merged[filePath] = typeof current === \"number\" ? Math.min(current, score) : score;\n  }\n  return merged;\n}\n\nfunction mergeSearchPackets(baseQuery: string, packets: AgentSearchPacket[]): AgentSearchPacket {\n  const first = packets[0];\n  const mergedDebug = {\n    queriesRun: dedupeStrings(packets.flatMap((packet) => packet.debug?.queriesRun ?? [])),\n    recoveryUsed: packets.some((packet) => packet.debug?.recoveryUsed === true),\n    matchTerms: dedupeStrings(packets.flatMap((packet) => packet.debug?.matchTerms ?? [])),\n  };\n  const recoveryReasons = dedupeStrings(\n    packets.flatMap((packet) => packet.debug?.recoveryReason ? [packet.debug.recoveryReason] : [])\n  );\n\n  return {\n    lane: first.lane,\n    query: baseQuery,\n    filePaths: dedupeStrings(packets.flatMap((packet) => packet.filePaths)),\n    matches: dedupeMatches(packets.flatMap((packet) => packet.matches ?? [])),\n    relatedFileScores: packets.reduce(\n      (acc, packet) => mergeRelatedFileScores(acc, packet.relatedFileScores),\n      {} as Record<string, number>\n    ),\n    debug: {\n      queriesRun: mergedDebug.queriesRun,\n      recoveryUsed: mergedDebug.recoveryUsed,\n      matchTerms: mergedDebug.matchTerms,\n      ...(recoveryReasons.length > 0 ? { recoveryReason: recoveryReasons.join(\",\") } : {}),\n    },\n  };\n}\n\nfunction extractMatchedTerms(packet: AgentSearchPacket): string[] {\n  return dedupeStrings(\n    (packet.matches ?? [])\n      .flatMap((match) => match.reasons ?? [])\n      .map((reason) => reason.match(/^term:(.+)$/i)?.[1] ?? \"\")\n      .filter(Boolean)\n  );\n}\n\nfunction extractTopHitConfirmations(packet: AgentSearchPacket): string[] {\n  const confirmations = new Set<string>();\n  for (const hit of packet.topHits ?? []) {\n    for (const reason of hit.reasons) {\n      if (!reason.startsWith(\"match-confirmation:\")) {\n        continue;\n      }\n      for (const term of reason.slice(\"match-confirmation:\".length).split(\",\")) {\n        const normalized = term.trim().toLowerCase();\n        if (!normalized || isWeakSemanticTerm(normalized)) {\n          continue;\n        }\n        confirmations.add(normalized);\n      }\n    }\n  }\n  return Array.from(confirmations);\n}\n\nfunction hasConcreteSnippetEvidence(packet: AgentSearchPacket): boolean {\n  const perFileConcreteTerms = new Map<string, Set<string>>();\n  for (const match of packet.matches ?? []) {\n    const concreteTerms = (match.reasons ?? [])\n      .map((reason) => reason.match(/^term:(.+)$/i)?.[1]?.toLowerCase())\n      .filter((term): term is string => Boolean(term))\n      .filter((term) => !isWeakSemanticTerm(term));\n    if (concreteTerms.length === 0) {\n      continue;\n    }\n    const current = perFileConcreteTerms.get(match.filePath) ?? new Set<string>();\n    for (const term of concreteTerms) {\n      current.add(term);\n    }\n    perFileConcreteTerms.set(match.filePath, current);\n  }\n\n  return Array.from(perFileConcreteTerms.values()).some((terms) => terms.size >= 2);\n}\n\nfunction hasStrongMatchConfirmation(packet: AgentSearchPacket): boolean {\n  const perFileStrongTerms = new Map<string, Set<string>>();\n  for (const match of packet.matches ?? []) {\n    const terms = (match.reasons ?? [])\n      .map((reason) => reason.match(/^term:(.+)$/i)?.[1]?.toLowerCase())\n      .filter((term): term is string => Boolean(term))\n      .filter((term) => !isWeakSemanticTerm(term));\n    if (terms.length === 0) {\n      continue;\n    }\n    const current = perFileStrongTerms.get(match.filePath) ?? new Set<string>();\n    for (const term of terms) {\n      current.add(term);\n    }\n    perFileStrongTerms.set(match.filePath, current);\n  }\n\n  return Array.from(perFileStrongTerms.values()).some((terms) => terms.size >= 2);\n}\n\nfunction hasStrongTopHitAnchor(packet: AgentSearchPacket): boolean {\n  return (packet.topHits ?? []).slice(0, 3).some((hit) =>\n    hit.reasons.some((reason) =>\n      reason === \"path-anchor\"\n      || reason.startsWith(\"exact-basename:\")\n      || (reason.startsWith(\"symbol:\")\n        && !isWeakSemanticTerm(String(reason.split(\":\")[1] ?? \"\").toLowerCase()))\n      || ((/^match-confirmation:/).test(reason)\n        && reason\n          .split(\":\")[1]\n          ?.split(\",\")\n          .map((term) => term.trim().toLowerCase())\n          .filter((term) => term && !isWeakSemanticTerm(term))\n          .length >= 2)\n    )\n  );\n}\n\nfunction resolveStrongEnough(packet: AgentSearchPacket, context: AgentSearchContext): {\n  strongEnough: boolean;\n  reason: string;\n} {\n  const matchedTerms = extractMatchedTerms(packet).filter((term) => !isWeakSemanticTerm(term));\n  const topHitConfirmations = extractTopHitConfirmations(packet);\n  const configIntent = looksLikeConfigurationIntent(context);\n  const concreteSnippetEvidence = hasConcreteSnippetEvidence(packet);\n  const strongMatchConfirmation = hasStrongMatchConfirmation(packet);\n  if (hasStrongTopHitAnchor(packet)) {\n    if (!strongMatchConfirmation && !concreteSnippetEvidence && topHitConfirmations.length === 0) {\n      return { strongEnough: false, reason: \"top hits are anchored but still too generic to stop\" };\n    }\n    if (configIntent && topHitConfirmations.length < 2 && !concreteSnippetEvidence) {\n      return { strongEnough: false, reason: \"top hits are anchored but still too generic for config intent\" };\n    }\n    return { strongEnough: true, reason: \"top hits include strong anchors\" };\n  }\n  if (strongMatchConfirmation) {\n    return { strongEnough: true, reason: \"one file has multiple concrete matched terms\" };\n  }\n  if (concreteSnippetEvidence) {\n    return { strongEnough: true, reason: \"snippets contain concrete multi-term evidence\" };\n  }\n  if (matchedTerms.length >= 4 && topHitConfirmations.length >= 2 && !configIntent) {\n    return { strongEnough: true, reason: \"matched terms are concrete and broad enough to stop\" };\n  }\n  return { strongEnough: false, reason: \"evidence is still driven by weak semantic terms\" };\n}\n\nexport async function runSemanticSearchBatches(\n  memory: AgentMemory,\n  context: AgentSearchContext,\n  visibleLimit: number,\n  runBatch: (query: string) => Promise<AgentSearchPacket>\n): Promise<AgentSearchPacket> {\n  const batches = buildSemanticSearchBatchPlan(context);\n  const rawPackets: AgentSearchPacket[] = [];\n  const batchDebug: SearchBatchDebugEntry[] = [];\n\n  for (let index = 0; index < batches.length; index += 1) {\n    const batch = batches[index];\n    const packet = await runBatch(batch.query);\n    rawPackets.push(packet);\n    const merged = mergeSearchPackets(context.query, rawPackets);\n    const scored = finalizeLanePacket(\"semantic\", memory, merged, visibleLimit);\n    const confidence = resolveStrongEnough(scored, context);\n    const strongEnough = confidence.strongEnough;\n    const continued = index < batches.length - 1 && !strongEnough;\n    batchDebug.push({\n      query: batch.query,\n      source: batch.source,\n      ...(typeof batch.termGroupIndex === \"number\" ? { termGroupIndex: batch.termGroupIndex } : {}),\n      ...(batch.kind ? { kind: batch.kind } : {}),\n      ...(batch.terms ? { terms: batch.terms } : {}),\n      continued,\n      strongEnough,\n      strongReason: confidence.reason,\n    });\n    if (!continued) {\n      return {\n        ...merged,\n        debug: {\n          ...(merged.debug ?? {}),\n          batchDebug,\n        },\n      };\n    }\n  }\n\n  const merged = mergeSearchPackets(context.query, rawPackets);\n  return {\n    ...merged,\n    debug: {\n      ...(merged.debug ?? {}),\n      batchDebug,\n    },\n  };\n}\n"]}

package/dist/agent/search/candidateRetentionPolicy.js

@@ -0,0 +1,184 @@
+/**
+ * Shapes lane results into the candidate set that policy will consume.
+ *
+ * Why this file exists:
+ * - lane execution and candidate shaping are different search concerns
+ * - fallback rules should be lane-aware instead of one-size-fits-all
+ * - read policy should receive a smaller, cleaner candidate frontier
+ */
+import fs from "fs";
+import path from "path";
+import { classifyFileRulePath } from "../../fileRules/searchPathClassification.js";
+import { MAX_WELL_KNOWN_REPO_FILES, WELL_KNOWN_REPO_FILE_BASENAMES } from "../../fileRules/wellKnownRepoFiles.js";
+import { rankAgentSearchHits } from "./ranking.js";
+const SPARSE_RESULT_THRESHOLD = 3;
+function dedupePaths(paths) {
+    const seen = new Set();
+    const out = [];
+    for (const filePath of paths) {
+        const normalized = path.normalize(String(filePath ?? "").trim());
+        if (!normalized || seen.has(normalized)) {
+            continue;
+        }
+        seen.add(normalized);
+        out.push(normalized);
+    }
+    return out;
+}
+function getLiteralSearchPenalty(filePath) {
+    const classification = classifyFileRulePath(filePath);
+    let penalty = 0;
+    if (classification.isDocumentation) {
+        penalty += 1;
+    }
+    if (classification.isGeneratedBuild || classification.isArtifact || classification.isLogLike || classification.isSourceMap || classification.isHarnessLike) {
+        penalty += 3;
+    }
+    return penalty;
+}
+function resolveRetrievalScope(memory) {
+    if (memory.task.hardFileTargets.length > 0) {
+        return "single-file";
+    }
+    const explicitTargetCount = memory.task.explicitTargets.filter((target) => {
+        const trimmed = String(target ?? "").trim();
+        return trimmed.includes("/") || /\.[A-Za-z0-9_]{1,10}$/.test(trimmed);
+    }).length;
+    return explicitTargetCount > 0 ? "single-file" : "repo-wide";
+}
+function preferCodeLikeMatches(route, rankedHits) {
+    if (route !== "fragment" && route !== "regex") {
+        return rankedHits;
+    }
+    const hasCodeLikeHit = rankedHits.some((hit) => getLiteralSearchPenalty(hit.filePath) === 0);
+    if (!hasCodeLikeHit) {
+        return rankedHits;
+    }
+    return [...rankedHits].sort((left, right) => {
+        const leftPenalty = getLiteralSearchPenalty(left.filePath);
+        const rightPenalty = getLiteralSearchPenalty(right.filePath);
+        if (leftPenalty !== rightPenalty) {
+            return leftPenalty - rightPenalty;
+        }
+        if (right.score !== left.score) {
+            return right.score - left.score;
+        }
+        return left.filePath.localeCompare(right.filePath);
+    });
+}
+function applyDeterministicPrefilter(args) {
+    const dedupedPaths = dedupePaths(args.filePaths);
+    if (dedupedPaths.length === 0) {
+        return [];
+    }
+    const scored = rankAgentSearchHits(dedupedPaths, args.relatedFileScores, args.query, args.matches ?? [], args.hintTerms ?? []);
+    if (scored.length === 0) {
+        return dedupedPaths.slice(0, args.limit);
+    }
+    const scope = resolveRetrievalScope(args.memory);
+    const baseKeepCount = scope === "single-file" ? Math.max(args.limit, 6) : Math.max(args.limit, 10);
+    const keepCount = Math.min(Math.max(3, baseKeepCount), scored.length);
+    const selected = new Set(scored.slice(0, keepCount).map(item => item.filePath));
+    for (const item of scored) {
+        if (item.reasons.includes("path-anchor") || item.reasons.some(reason => reason.startsWith("exact-basename:"))) {
+            selected.add(item.filePath);
+        }
+    }
+    return scored.filter(item => selected.has(item.filePath)).map(item => item.filePath);
+}
+function filterMatchesToVisibleFiles(packet, visibleFiles) {
+    if (!packet.matches || packet.matches.length === 0) {
+        return [];
+    }
+    const visible = new Set(visibleFiles);
+    const perFileCounts = new Map();
+    const filtered = packet.matches.filter((match) => visible.has(match.filePath));
+    const limited = [];
+    for (const match of filtered) {
+        const count = perFileCounts.get(match.filePath) ?? 0;
+        if (count >= 2) {
+            continue;
+        }
+        limited.push(match);
+        perFileCounts.set(match.filePath, count + 1);
+        if (limited.length >= 6) {
+            break;
+        }
+    }
+    return limited;
+}
+function shouldInjectRepoDefaults(route, memory, filePaths) {
+    if (route !== "semantic") {
+        return false;
+    }
+    if (memory.task.hardFileTargets.length > 0) {
+        return false;
+    }
+    if (memory.task.explicitTargets.some((target) => {
+        const trimmed = String(target ?? "").trim();
+        return trimmed.includes("/") || /\.[A-Za-z0-9_]{1,10}$/.test(trimmed);
+    })) {
+        return false;
+    }
+    const scope = resolveRetrievalScope(memory);
+    return scope === "repo-wide" && filePaths.length < SPARSE_RESULT_THRESHOLD;
+}
+function injectWellKnownRepoFiles(memory, filePaths) {
+    const dedupedPaths = dedupePaths(filePaths);
+    const candidates = WELL_KNOWN_REPO_FILE_BASENAMES
+        .map(fileName => path.join(memory.session.executionPath, fileName))
+        .filter(filePath => fs.existsSync(filePath))
+        .slice(0, MAX_WELL_KNOWN_REPO_FILES);
+    if (candidates.length === 0) {
+        return dedupedPaths;
+    }
+    const existing = new Set(dedupedPaths);
+    for (const filePath of candidates) {
+        existing.add(filePath);
+    }
+    return Array.from(existing);
+}
+/**
+ * Applies lane-aware prefiltering and fallback before candidates hit read policy.
+ * Example: semantic repo-wide search may add `README.md`, but exact-target search never should.
+ */
+export function finalizeLanePacket(route, memory, packet, limit) {
+    if (packet.filePaths.length === 0) {
+        return packet;
+    }
+    if (route === "exact-target") {
+        const exactPaths = dedupePaths(packet.filePaths);
+        const rankedHits = rankAgentSearchHits(exactPaths, packet.relatedFileScores ?? {}, packet.query, packet.matches, packet.debug?.matchTerms ?? []);
+        return {
+            ...packet,
+            filePaths: exactPaths,
+            matches: filterMatchesToVisibleFiles(packet, exactPaths),
+            topHits: rankedHits.slice(0, limit),
+        };
+    }
+    const relatedFileScores = packet.relatedFileScores ?? {};
+    const filteredPaths = route === "directory"
+        ? []
+        : applyDeterministicPrefilter({
+            memory,
+            filePaths: packet.filePaths,
+            query: packet.query,
+            relatedFileScores,
+            matches: packet.matches,
+            hintTerms: packet.debug?.matchTerms,
+            limit,
+        });
+    const expandedPaths = shouldInjectRepoDefaults(route, memory, filteredPaths)
+        ? injectWellKnownRepoFiles(memory, filteredPaths)
+        : filteredPaths;
+    const rankedHits = preferCodeLikeMatches(route, rankAgentSearchHits(expandedPaths, relatedFileScores, packet.query, packet.matches, packet.debug?.matchTerms ?? []));
+    const visibleHits = rankedHits.slice(0, limit);
+    const visibleFiles = visibleHits.map((hit) => hit.filePath);
+    return {
+        ...packet,
+        filePaths: visibleFiles,
+        matches: filterMatchesToVisibleFiles(packet, visibleFiles),
+        topHits: visibleHits,
+    };
+}
+//# sourceMappingURL=candidateRetentionPolicy.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"candidateRetentionPolicy.js","sourceRoot":"","sources":["../../../src/agent/search/candidateRetentionPolicy.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AACxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,6CAA6C,CAAC;AACnF,OAAO,EAAE,yBAAyB,EAAE,8BAA8B,EAAE,MAAM,uCAAuC,CAAC;AAElH,OAAO,EAAE,mBAAmB,EAA6B,MAAM,cAAc,CAAC;AAG9E,MAAM,uBAAuB,GAAG,CAAC,CAAC;AAIlC,SAAS,WAAW,CAAC,KAAe;IAClC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,KAAK,MAAM,QAAQ,IAAI,KAAK,EAAE,CAAC;QAC7B,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACjE,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC;YACxC,SAAS;QACX,CAAC;QACD,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACrB,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACvB,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,SAAS,uBAAuB,CAAC,QAAgB;IAC/C,MAAM,cAAc,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAAC;IACtD,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,cAAc,CAAC,eAAe,EAAE,CAAC;QACnC,OAAO,IAAI,CAAC,CAAC;IACf,CAAC;IACD,IAAI,cAAc,CAAC,gBAAgB,IAAI,cAAc,CAAC,UAAU,IAAI,cAAc,CAAC,SAAS,IAAI,cAAc,CAAC,WAAW,IAAI,cAAc,CAAC,aAAa,EAAE,CAAC;QAC3J,OAAO,IAAI,CAAC,CAAC;IACf,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,qBAAqB,CAAC,MAAmB;IAChD,IAAI,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3C,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,MAAM,mBAAmB,GAAG,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE;QACxE,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAC5C,OAAO,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,uBAAuB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACxE,CAAC,CAAC,CAAC,MAAM,CAAC;IAEV,OAAO,mBAAmB,GAAG,CAAC,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,WAAW,CAAC;AAC/D,CAAC;AAED,SAAS,qBAAqB,CAAC,KAAsB,EAAE,UAAkC;IACvF,IAAI,KAAK,KAAK,UAAU,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;QAC9C,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,MAAM,cAAc,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,uBAAuB,CAAC,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;IAC7F,IAAI,CAAC,cAAc,EAAE,CAAC;QACpB,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,OAAO,CAAC,GAAG,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QAC1C,MAAM,WAAW,GAAG,uBAAuB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC3D,MAAM,YAAY,GAAG,uBAAuB,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAC7D,IAAI,WAAW,KAAK,YAAY,EAAE,CAAC;YACjC,OAAO,WAAW,GAAG,YAAY,CAAC;QACpC,CAAC;QACD,IAAI,KAAK,CAAC,KAAK,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;YAC/B,OAAO,KAAK,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC;QAClC,CAAC;QACD,OAAO,IAAI,CAAC,QAAQ,CAAC,aAAa,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IACrD,CAAC,CAAC,CAAC;AACL,CAAC;AAED,SAAS,2BAA2B,CAAC,IAQpC;IACC,MAAM,YAAY,GAAG,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IACjD,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC9B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,MAAM,GAAG,mBAAmB,CAChC,YAAY,EACZ,IAAI,CAAC,iBAAiB,EACtB,IAAI,CAAC,KAAK,EACV,IAAI,CAAC,OAAO,IAAI,EAAE,EAClB,IAAI,CAAC,SAAS,IAAI,EAAE,CACrB,CAAC;IACF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3C,CAAC;IAED,MAAM,KAAK,GAAG,qBAAqB,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACjD,MAAM,aAAa,GAAG,KAAK,KAAK,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACnG,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IACtE,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAS,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;IAExF,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;QAC1B,IAAI,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC,EAAE,CAAC;YAC9G,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC9B,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACvF,CAAC;AAED,SAAS,2BAA2B,CAAC,MAAyB,EAAE,YAAsB;IACpF,IAAI,CAAC,MAAM,CAAC,OAAO,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACnD,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC;IACtC,MAAM,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;IAChD,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC/E,MAAM,OAAO,GAA8C,EAAE,CAAC;IAC9D,KAAK,MAAM,KAAK,IAAI,QAAQ,EAAE,CAAC;QAC7B,MAAM,KAAK,GAAG,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QACrD,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;YACf,SAAS;QACX,CAAC;QACD,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACpB,aAAa,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;QAC7C,IAAI,OAAO,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;YACxB,MAAM;QACR,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,SAAS,wBAAwB,CAAC,KAAsB,EAAE,MAAmB,EAAE,SAAmB;IAChG,IAAI,KAAK,KAAK,UAAU,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC3C,OAAO,KAAK,CAAC;IACf,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;QAC9C,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;QAC5C,OAAO,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,uBAAuB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACxE,CAAC,CAAC,EAAE,CAAC;QACH,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,KAAK,GAAG,qBAAqB,CAAC,MAAM,CAAC,CAAC;IAC5C,OAAO,KAAK,KAAK,WAAW,IAAI,SAAS,CAAC,MAAM,GAAG,uBAAuB,CAAC;AAC7E,CAAC;AAED,SAAS,wBAAwB,CAAC,MAAmB,EAAE,SAAmB;IACxE,MAAM,YAAY,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;IAC5C,MAAM,UAAU,GAAG,8BAA8B;SAC9C,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,aAAa,EAAE,QAAQ,CAAC,CAAC;SAClE,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;SAC3C,KAAK,CAAC,CAAC,EAAE,yBAAyB,CAAC,CAAC;IAEvC,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC5B,OAAO,YAAY,CAAC;IACtB,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC;IACvC,KAAK,MAAM,QAAQ,IAAI,UAAU,EAAE,CAAC;QAClC,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACzB,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAChC,KAAsB,EACtB,MAAmB,EACnB,MAAyB,EACzB,KAAa;IAEb,IAAI,MAAM,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClC,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,IAAI,KAAK,KAAK,cAAc,EAAE,CAAC;QAC7B,MAAM,UAAU,GAAG,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;QACjD,MAAM,UAAU,GAAG,mBAAmB,CACpC,UAAU,EACV,MAAM,CAAC,iBAAiB,IAAI,EAAE,EAC9B,MAAM,CAAC,KAAK,EACZ,MAAM,CAAC,OAAO,EACd,MAAM,CAAC,KAAK,EAAE,UAAU,IAAI,EAAE,CAC/B,CAAC;QACF,OAAO;YACL,GAAG,MAAM;YACT,SAAS,EAAE,UAAU;YACrB,OAAO,EAAE,2BAA2B,CAAC,MAAM,EAAE,UAAU,CAAC;YACxD,OAAO,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC;SACpC,CAAC;IACJ,CAAC;IAED,MAAM,iBAAiB,GAAG,MAAM,CAAC,iBAAiB,IAAI,EAAE,CAAC;IACzD,MAAM,aAAa,GAAG,KAAK,KAAK,WAAW;QACzC,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,2BAA2B,CAAC;YAC1B,MAAM;YACN,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,iBAAiB;YACjB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,SAAS,EAAE,MAAM,CAAC,KAAK,EAAE,UAAU;YACnC,KAAK;SACN,CAAC,CAAC;IAEP,MAAM,aAAa,GAAG,wBAAwB,CAAC,KAAK,EAAE,MAAM,EAAE,aAAa,CAAC;QAC1E,CAAC,CAAC,wBAAwB,CAAC,MAAM,EAAE,aAAa,CAAC;QACjD,CAAC,CAAC,aAAa,CAAC;IAElB,MAAM,UAAU,GAAG,qBAAqB,CACtC,KAAK,EACL,mBAAmB,CACjB,aAAa,EACb,iBAAiB,EACjB,MAAM,CAAC,KAAK,EACZ,MAAM,CAAC,OAAO,EACd,MAAM,CAAC,KAAK,EAAE,UAAU,IAAI,EAAE,CAC/B,CACF,CAAC;IACF,MAAM,WAAW,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAC/C,MAAM,YAAY,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAE5D,OAAO;QACL,GAAG,MAAM;QACT,SAAS,EAAE,YAAY;QACvB,OAAO,EAAE,2BAA2B,CAAC,MAAM,EAAE,YAAY,CAAC;QAC1D,OAAO,EAAE,WAAW;KACrB,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Shapes lane results into the candidate set that policy will consume.\n *\n * Why this file exists:\n * - lane execution and candidate shaping are different search concerns\n * - fallback rules should be lane-aware instead of one-size-fits-all\n * - read policy should receive a smaller, cleaner candidate frontier\n */\nimport fs from \"fs\";\nimport path from \"path\";\nimport { classifyFileRulePath } from \"../../fileRules/searchPathClassification.js\";\nimport { MAX_WELL_KNOWN_REPO_FILES, WELL_KNOWN_REPO_FILE_BASENAMES } from \"../../fileRules/wellKnownRepoFiles.js\";\nimport type { AgentMemory } from \"../types.js\";\nimport { rankAgentSearchHits, type AgentScoredSearchHit } from \"./ranking.js\";\nimport type { AgentSearchLane, AgentSearchPacket } from \"./types.js\";\n\nconst SPARSE_RESULT_THRESHOLD = 3;\n\ntype RetrievalScope = \"single-file\" | \"repo-wide\";\n\nfunction dedupePaths(paths: string[]): string[] {\n  const seen = new Set<string>();\n  const out: string[] = [];\n  for (const filePath of paths) {\n    const normalized = path.normalize(String(filePath ?? \"\").trim());\n    if (!normalized || seen.has(normalized)) {\n      continue;\n    }\n    seen.add(normalized);\n    out.push(normalized);\n  }\n  return out;\n}\n\nfunction getLiteralSearchPenalty(filePath: string): number {\n  const classification = classifyFileRulePath(filePath);\n  let penalty = 0;\n  if (classification.isDocumentation) {\n    penalty += 1;\n  }\n  if (classification.isGeneratedBuild || classification.isArtifact || classification.isLogLike || classification.isSourceMap || classification.isHarnessLike) {\n    penalty += 3;\n  }\n  return penalty;\n}\n\nfunction resolveRetrievalScope(memory: AgentMemory): RetrievalScope {\n  if (memory.task.hardFileTargets.length > 0) {\n    return \"single-file\";\n  }\n\n  const explicitTargetCount = memory.task.explicitTargets.filter((target) => {\n    const trimmed = String(target ?? \"\").trim();\n    return trimmed.includes(\"/\") || /\\.[A-Za-z0-9_]{1,10}$/.test(trimmed);\n  }).length;\n\n  return explicitTargetCount > 0 ? \"single-file\" : \"repo-wide\";\n}\n\nfunction preferCodeLikeMatches(route: AgentSearchLane, rankedHits: AgentScoredSearchHit[]): AgentScoredSearchHit[] {\n  if (route !== \"fragment\" && route !== \"regex\") {\n    return rankedHits;\n  }\n\n  const hasCodeLikeHit = rankedHits.some((hit) => getLiteralSearchPenalty(hit.filePath) === 0);\n  if (!hasCodeLikeHit) {\n    return rankedHits;\n  }\n\n  return [...rankedHits].sort((left, right) => {\n    const leftPenalty = getLiteralSearchPenalty(left.filePath);\n    const rightPenalty = getLiteralSearchPenalty(right.filePath);\n    if (leftPenalty !== rightPenalty) {\n      return leftPenalty - rightPenalty;\n    }\n    if (right.score !== left.score) {\n      return right.score - left.score;\n    }\n    return left.filePath.localeCompare(right.filePath);\n  });\n}\n\nfunction applyDeterministicPrefilter(args: {\n  memory: AgentMemory;\n  filePaths: string[];\n  query: string;\n  relatedFileScores: Record<string, number>;\n  matches?: AgentSearchPacket[\"matches\"];\n  hintTerms?: string[];\n  limit: number;\n}): string[] {\n  const dedupedPaths = dedupePaths(args.filePaths);\n  if (dedupedPaths.length === 0) {\n    return [];\n  }\n\n  const scored = rankAgentSearchHits(\n    dedupedPaths,\n    args.relatedFileScores,\n    args.query,\n    args.matches ?? [],\n    args.hintTerms ?? []\n  );\n  if (scored.length === 0) {\n    return dedupedPaths.slice(0, args.limit);\n  }\n\n  const scope = resolveRetrievalScope(args.memory);\n  const baseKeepCount = scope === \"single-file\" ? Math.max(args.limit, 6) : Math.max(args.limit, 10);\n  const keepCount = Math.min(Math.max(3, baseKeepCount), scored.length);\n  const selected = new Set<string>(scored.slice(0, keepCount).map(item => item.filePath));\n\n  for (const item of scored) {\n    if (item.reasons.includes(\"path-anchor\") || item.reasons.some(reason => reason.startsWith(\"exact-basename:\"))) {\n      selected.add(item.filePath);\n    }\n  }\n\n  return scored.filter(item => selected.has(item.filePath)).map(item => item.filePath);\n}\n\nfunction filterMatchesToVisibleFiles(packet: AgentSearchPacket, visibleFiles: string[]): NonNullable<AgentSearchPacket[\"matches\"]> {\n  if (!packet.matches || packet.matches.length === 0) {\n    return [];\n  }\n\n  const visible = new Set(visibleFiles);\n  const perFileCounts = new Map<string, number>();\n  const filtered = packet.matches.filter((match) => visible.has(match.filePath));\n  const limited: NonNullable<AgentSearchPacket[\"matches\"]> = [];\n  for (const match of filtered) {\n    const count = perFileCounts.get(match.filePath) ?? 0;\n    if (count >= 2) {\n      continue;\n    }\n    limited.push(match);\n    perFileCounts.set(match.filePath, count + 1);\n    if (limited.length >= 6) {\n      break;\n    }\n  }\n  return limited;\n}\n\nfunction shouldInjectRepoDefaults(route: AgentSearchLane, memory: AgentMemory, filePaths: string[]): boolean {\n  if (route !== \"semantic\") {\n    return false;\n  }\n  if (memory.task.hardFileTargets.length > 0) {\n    return false;\n  }\n  if (memory.task.explicitTargets.some((target) => {\n    const trimmed = String(target ?? \"\").trim();\n    return trimmed.includes(\"/\") || /\\.[A-Za-z0-9_]{1,10}$/.test(trimmed);\n  })) {\n    return false;\n  }\n\n  const scope = resolveRetrievalScope(memory);\n  return scope === \"repo-wide\" && filePaths.length < SPARSE_RESULT_THRESHOLD;\n}\n\nfunction injectWellKnownRepoFiles(memory: AgentMemory, filePaths: string[]): string[] {\n  const dedupedPaths = dedupePaths(filePaths);\n  const candidates = WELL_KNOWN_REPO_FILE_BASENAMES\n    .map(fileName => path.join(memory.session.executionPath, fileName))\n    .filter(filePath => fs.existsSync(filePath))\n    .slice(0, MAX_WELL_KNOWN_REPO_FILES);\n\n  if (candidates.length === 0) {\n    return dedupedPaths;\n  }\n\n  const existing = new Set(dedupedPaths);\n  for (const filePath of candidates) {\n    existing.add(filePath);\n  }\n  return Array.from(existing);\n}\n\n/**\n * Applies lane-aware prefiltering and fallback before candidates hit read policy.\n * Example: semantic repo-wide search may add `README.md`, but exact-target search never should.\n */\nexport function finalizeLanePacket(\n  route: AgentSearchLane,\n  memory: AgentMemory,\n  packet: AgentSearchPacket,\n  limit: number\n): AgentSearchPacket {\n  if (packet.filePaths.length === 0) {\n    return packet;\n  }\n\n  if (route === \"exact-target\") {\n    const exactPaths = dedupePaths(packet.filePaths);\n    const rankedHits = rankAgentSearchHits(\n      exactPaths,\n      packet.relatedFileScores ?? {},\n      packet.query,\n      packet.matches,\n      packet.debug?.matchTerms ?? []\n    );\n    return {\n      ...packet,\n      filePaths: exactPaths,\n      matches: filterMatchesToVisibleFiles(packet, exactPaths),\n      topHits: rankedHits.slice(0, limit),\n    };\n  }\n\n  const relatedFileScores = packet.relatedFileScores ?? {};\n  const filteredPaths = route === \"directory\"\n    ? []\n    : applyDeterministicPrefilter({\n        memory,\n        filePaths: packet.filePaths,\n        query: packet.query,\n        relatedFileScores,\n        matches: packet.matches,\n        hintTerms: packet.debug?.matchTerms,\n        limit,\n      });\n\n  const expandedPaths = shouldInjectRepoDefaults(route, memory, filteredPaths)\n    ? injectWellKnownRepoFiles(memory, filteredPaths)\n    : filteredPaths;\n\n  const rankedHits = preferCodeLikeMatches(\n    route,\n    rankAgentSearchHits(\n      expandedPaths,\n      relatedFileScores,\n      packet.query,\n      packet.matches,\n      packet.debug?.matchTerms ?? []\n    )\n  );\n  const visibleHits = rankedHits.slice(0, limit);\n  const visibleFiles = visibleHits.map((hit) => hit.filePath);\n\n  return {\n    ...packet,\n    filePaths: visibleFiles,\n    matches: filterMatchesToVisibleFiles(packet, visibleFiles),\n    topHits: visibleHits,\n  };\n}\n"]}

package/dist/agent/search/directory.js

@@ -0,0 +1,51 @@
+/**
+ * Lists direct directory children for modular-agent search.
+ *
+ * Why this file exists:
+ * - direct folder listing is its own search lane
+ * - folder summary shaping belongs with the directory lane, not generic retention
+ */
+import fs from "fs";
+import path from "path";
+import { collectDirectDirectoryEntries } from "./shared.js";
+/**
+ * Formats one compact folder listing summary for answers and follow-up prompts.
+ * Example: `Contents of /repo/cli: [dir] src`.
+ */
+export function renderDirectoryListingSummary(folderPath, entries) {
+    const header = folderPath ? `Contents of ${folderPath}:` : "Directory contents:";
+    if (entries.length === 0) {
+        return `${header}\n[empty]`;
+    }
+    return [
+        header,
+        ...entries.map(entry => `${entry.kind === "folder" ? "[dir]" : "[file]"} ${entry.name}`),
+    ].join("\n");
+}
+export function runDirectorySearch(rootDir, rawTarget) {
+    const folderPath = rawTarget && rawTarget.trim().length > 0
+        ? (path.isAbsolute(rawTarget) ? rawTarget : path.join(rootDir, rawTarget))
+        : rootDir;
+    if (!fs.existsSync(folderPath) || !fs.statSync(folderPath).isDirectory()) {
+        return {
+            lane: "directory",
+            query: rawTarget,
+            filePaths: [],
+            failure: {
+                status: "failed",
+                failureClass: "scope-missing",
+                message: "Could not resolve a folder to list.",
+            },
+        };
+    }
+    const entries = collectDirectDirectoryEntries(folderPath);
+    return {
+        lane: "directory",
+        query: rawTarget,
+        filePaths: [],
+        directoryPath: folderPath,
+        directoryEntries: entries,
+        summary: renderDirectoryListingSummary(folderPath, entries),
+    };
+}
+//# sourceMappingURL=directory.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"directory.js","sourceRoot":"","sources":["../../../src/agent/search/directory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,MAAM,IAAI,CAAC;AACpB,OAAO,IAAI,MAAM,MAAM,CAAC;AAExB,OAAO,EAAE,6BAA6B,EAAE,MAAM,aAAa,CAAC;AAE5D;;;GAGG;AACH,MAAM,UAAU,6BAA6B,CAC3C,UAA8B,EAC9B,OAAyD;IAEzD,MAAM,MAAM,GAAG,UAAU,CAAC,CAAC,CAAC,eAAe,UAAU,GAAG,CAAC,CAAC,CAAC,qBAAqB,CAAC;IACjF,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,GAAG,MAAM,WAAW,CAAC;IAC9B,CAAC;IACD,OAAO;QACL,MAAM;QACN,GAAG,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;KACzF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,SAAiB;IACnE,MAAM,UAAU,GAAG,SAAS,IAAI,SAAS,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;QACzD,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;QAC1E,CAAC,CAAC,OAAO,CAAC;IAEZ,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC;QACzE,OAAO;YACL,IAAI,EAAE,WAAW;YACjB,KAAK,EAAE,SAAS;YAChB,SAAS,EAAE,EAAE;YACb,OAAO,EAAE;gBACP,MAAM,EAAE,QAAQ;gBAChB,YAAY,EAAE,eAAe;gBAC7B,OAAO,EAAE,qCAAqC;aAC/C;SACF,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,6BAA6B,CAAC,UAAU,CAAC,CAAC;IAC1D,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,KAAK,EAAE,SAAS;QAChB,SAAS,EAAE,EAAE;QACb,aAAa,EAAE,UAAU;QACzB,gBAAgB,EAAE,OAAO;QACzB,OAAO,EAAE,6BAA6B,CAAC,UAAU,EAAE,OAAO,CAAC;KAC5D,CAAC;AACJ,CAAC","sourcesContent":["/**\n * Lists direct directory children for modular-agent search.\n *\n * Why this file exists:\n * - direct folder listing is its own search lane\n * - folder summary shaping belongs with the directory lane, not generic retention\n */\nimport fs from \"fs\";\nimport path from \"path\";\nimport type { AgentSearchPacket } from \"./types.js\";\nimport { collectDirectDirectoryEntries } from \"./shared.js\";\n\n/**\n * Formats one compact folder listing summary for answers and follow-up prompts.\n * Example: `Contents of /repo/cli: [dir] src`.\n */\nexport function renderDirectoryListingSummary(\n  folderPath: string | undefined,\n  entries: Array<{ name: string; kind: \"file\" | \"folder\" }>\n): string {\n  const header = folderPath ? `Contents of ${folderPath}:` : \"Directory contents:\";\n  if (entries.length === 0) {\n    return `${header}\\n[empty]`;\n  }\n  return [\n    header,\n    ...entries.map(entry => `${entry.kind === \"folder\" ? \"[dir]\" : \"[file]\"} ${entry.name}`),\n  ].join(\"\\n\");\n}\n\nexport function runDirectorySearch(rootDir: string, rawTarget: string): AgentSearchPacket {\n  const folderPath = rawTarget && rawTarget.trim().length > 0\n    ? (path.isAbsolute(rawTarget) ? rawTarget : path.join(rootDir, rawTarget))\n    : rootDir;\n\n  if (!fs.existsSync(folderPath) || !fs.statSync(folderPath).isDirectory()) {\n    return {\n      lane: \"directory\",\n      query: rawTarget,\n      filePaths: [],\n      failure: {\n        status: \"failed\",\n        failureClass: \"scope-missing\",\n        message: \"Could not resolve a folder to list.\",\n      },\n    };\n  }\n\n  const entries = collectDirectDirectoryEntries(folderPath);\n  return {\n    lane: \"directory\",\n    query: rawTarget,\n    filePaths: [],\n    directoryPath: folderPath,\n    directoryEntries: entries,\n    summary: renderDirectoryListingSummary(folderPath, entries),\n  };\n}\n"]}