sweet-search 2.6.16 → 2.7.0

package/mcp/server.js

@@ -12,6 +12,12 @@ import { existsSync, statSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { launchMaintainer } from '../core/indexing/maintainer-launcher.mjs';
+import {
+  collectSemanticShownSpans,
+  exactRereadOmissionEnabled,
+  validAgentSessionId,
+} from '../core/search/agent-span-ledger.js';
+import { sendAgentSpanOperation } from '../core/search/agent-span-client.js';
 
 import {
   SearchOutputSchema,
@@ -104,13 +110,26 @@ async function getConfig() {
 
 const coreDir = path.join(__dirname, '..', 'core');
 
-const searchDeps = { getSearcher };
+const searchDeps = { getSearcher, PROJECT_ROOT };
 const traceDeps = { PROJECT_ROOT };
 const indexDeps = { PROJECT_ROOT, coreDir };
 const healthDeps = { getConfig, PROJECT_ROOT };
 const repoMapDeps = { coreDir, PROJECT_ROOT };
 const vocabDeps = { coreDir };
 
+function requestAgentSessionId(extra) {
+  // A long-lived MCP process does not receive later shell-environment rotation
+  // after clear/compact. Never fall back to inherited process session ids.
+  return validAgentSessionId(extra?.sessionId) ? extra.sessionId : null;
+}
+
+async function touchAgentCall(extra, spans = [], { query, regex } = {}) {
+  if (!exactRereadOmissionEnabled()) return;
+  const sessionId = requestAgentSessionId(extra);
+  if (!sessionId) return;
+  await sendAgentSpanOperation({ operation: 'observe', sessionId, spans, query, regex });
+}
+
 // ---------------------------------------------------------------------------
 // MCP Server
 // ---------------------------------------------------------------------------
@@ -171,7 +190,10 @@ server.registerTool('search', {
     idempotentHint: true,
     openWorldHint: false,
   },
-}, async (args) => handleSearch(args, searchDeps));
+}, async (args, extra) => handleSearch(args, {
+  ...searchDeps,
+  agentSessionId: requestAgentSessionId(extra),
+}));
 
 server.registerTool('trace', {
   description: 'Trace callers, callees, and transitive impact paths for one specific symbol — returns a single structural-context package adapted to the token budget. USE WHEN the question is "who calls X", "what does X depend on", or "what would break if I changed X". For general code discovery use `search` instead; for navigation around an unfamiliar repo use `repo-map` first.',
@@ -194,7 +216,12 @@ server.registerTool('trace', {
     idempotentHint: true,
     openWorldHint: false,
   },
-}, async (args) => handleTrace(args, traceDeps));
+}, async (args, extra) => {
+  await touchAgentCall(extra, [], {
+    query: `${args.symbol} ${args.query || ''}`.trim(),
+  });
+  return handleTrace(args, traceDeps);
+});
 
 server.registerTool('index', {
   description: 'Index or re-index the codebase. USE BEFORE first search if the project has not been indexed yet, or after large source changes (`mode="full"`). The Claude Code SessionStart hook installed by `sweet-search init` keeps the incremental index fresh during normal sessions, so manual re-indexing is rarely needed.',
@@ -209,7 +236,10 @@ server.registerTool('index', {
     idempotentHint: false,
     openWorldHint: false,
   },
-}, async (args) => handleIndex(args, indexDeps));
+}, async (args, extra) => {
+  await touchAgentCall(extra);
+  return handleIndex(args, indexDeps);
+});
 
 server.registerTool('health', {
   description: 'Check health of every sweet-search subsystem (index, embedding model, late-interaction reranker, structural graph, daemon). USE WHEN searches return empty unexpectedly, results look stale, or latency is unusual — diagnoses missing index, model load failures, daemon issues. Read-only, fast.',
@@ -220,7 +250,8 @@ server.registerTool('health', {
     idempotentHint: true,
     openWorldHint: false,
   },
-}, async () => {
+}, async (_args, extra) => {
+  await touchAgentCall(extra);
   const structured = await checkHealth(healthDeps);
 
   const statusLines = Object.entries(structured.subsystems).map(
@@ -251,7 +282,10 @@ server.registerTool('repo-map', {
     idempotentHint: true,
     openWorldHint: false,
   },
-}, async (args) => handleRepoMap(args, repoMapDeps));
+}, async (args, extra) => {
+  await touchAgentCall(extra);
+  return handleRepoMap(args, repoMapDeps);
+});
 
 server.registerTool('vocab-prewarm', {
   description: 'Pre-warm sweet-search caches by mining the codebase for project-specific vocabulary across lexical / semantic / hybrid modes. USE ONCE after a fresh index to make the first batch of searches faster; generally not needed for one-off queries because the daemon-prewarm hook handles cold-start warmup automatically.',
@@ -272,7 +306,10 @@ server.registerTool('vocab-prewarm', {
     idempotentHint: true,
     openWorldHint: true,
   },
-}, async (args) => handleVocabPrewarm(args, vocabDeps));
+}, async (args, extra) => {
+  await touchAgentCall(extra);
+  return handleVocabPrewarm(args, vocabDeps);
+});
 
 server.registerTool('read', {
   description: 'Read 1-20 files (with optional line ranges) for exact code understanding. USE INSTEAD OF the native Read tool for code-discovery reads — batches multiple files in one call, attaches symbol-aware chunk metadata when the file is indexed, and returns the exact bytes from disk. Native Read remains fine for files you are about to Edit (Edit needs a prior Read of that exact file).',
@@ -284,10 +321,14 @@ server.registerTool('read', {
     })).min(1).max(20).describe('Files to read (1-20)'),
     includeMetadata: z.boolean().default(true).optional()
       .describe('Attach symbol-aware chunk metadata when the file is indexed'),
+    force: z.boolean().default(false).optional(),
   },
   outputSchema: ReadOutputSchema,
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-}, async (args) => handleRead(args, { PROJECT_ROOT }));
+}, async (args, extra) => handleRead(args, {
+  PROJECT_ROOT,
+  agentSessionId: requestAgentSessionId(extra),
+}));
 
 server.registerTool('read-semantic', {
   description: 'Read only the spans of a file relevant to a question. USE WHEN you know the file but the relevant span is unclear — selects spans via hybrid retrieval (lexical + symbol + ColBERT MaxSim, RRF-fused and LI-reranked), then re-reads exact lines from disk. Returns 1-N small spans instead of the full file. Avoid running this on multiple files unless the task is explicitly multi-file — call `search` with the question instead. Falls back to a plain read when the file is not indexed.',
@@ -309,7 +350,12 @@ server.registerTool('read-semantic', {
   },
   outputSchema: ReadSemanticOutputSchema,
   annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
-}, async (args) => handleReadSemantic(args, { PROJECT_ROOT }));
+}, async (args, extra) => {
+  const result = await handleReadSemantic(args, { PROJECT_ROOT });
+  const spans = collectSemanticShownSpans(result.structuredContent, { projectRoot: PROJECT_ROOT });
+  await touchAgentCall(extra, spans, { query: args.query });
+  return result;
+});
 
 // ---------------------------------------------------------------------------
 // Resources

package/mcp/tool-handlers.js

@@ -1,15 +1,15 @@
 // mcp/tool-handlers.js — Extracted tool handler functions (SOLID refactor)
 // Each handler receives its dependencies via a `deps` parameter.
-
 import { z } from 'zod';
 import { existsSync } from 'node:fs';
 import { spawn } from 'node:child_process';
 import path from 'node:path';
-
+import { collectAgentShownSpans, exactRereadOmissionEnabled, renderShownFullTrailer, shownSpanTrailerEnabled } from '../core/search/agent-span-ledger.js';
+import { sendAgentSpanOperation } from '../core/search/agent-span-client.js';
+import { renderRegexDialectHint } from '../core/search/regex-dialect.js';
 // ---------------------------------------------------------------------------
 // Output schemas (Zod — SDK converts to JSON Schema for clients)
 // ---------------------------------------------------------------------------
-
 const SearchResultSchema = z.object({
   file: z.string(),
   score: z.number(),
@@ -25,6 +25,22 @@ const SearchResultSchema = z.object({
   presentation: z.enum(['full', 'preview', 'summary']).optional(),
   code: z.string().nullable().optional(),
   codeTokens: z.number().int().optional(),
+  continuation: z.object({
+    kind: z.enum(['symbol', 'trailer']),
+    file: z.string(),
+    startLine: z.number().int(),
+    endLine: z.number().int(),
+    symbol: z.string(),
+    symbolType: z.string().nullable().optional(),
+    code: z.string().nullable().optional(),
+    rendered: z.string(),
+    tokens: z.number().int(),
+  }).optional(),
+  familyManifest: z.object({
+    rendered: z.string(),
+    tokens: z.number().int(),
+    groups: z.array(z.string()),
+  }).optional(),
 });
 
 export const SearchOutputSchema = z.object({
@@ -102,10 +118,11 @@ let _healthDb = null;
 
 /**
  * @param {{ query: string, k: number, mode: string, structural?: boolean, regex?: string, format?: string, tokenBudget?: number }} args
- * @param {{ getSearcher: () => Promise<object> }} deps
+ * @param {{ getSearcher: () => Promise<object>, PROJECT_ROOT?: string, agentSessionId?: string }} deps
  */
-export async function handleSearch({ query, k, mode, structural, regex, format, tokenBudget }, { getSearcher }) {
+export async function handleSearch({ query, k, mode, structural, regex, format, tokenBudget }, deps) {
   try {
+    const { getSearcher } = deps;
     const searcher = await getSearcher();
     const searchMode = structural ? 'structural' : mode;
     const searchResult = await searcher.search(query, {
@@ -116,11 +133,25 @@ export async function handleSearch({ query, k, mode, structural, regex, format,
       ...(regex && { regex }),
       ...(format && { format }),
       ...(tokenBudget && { tokenBudget }),
+      _isAgentFormat: format === 'agent',
     });
 
     // Agent mode: return the fully packaged response directly
     if (searchResult.format === 'agent') {
       const agentResults = searchResult.results || [];
+      const exactReread = exactRereadOmissionEnabled() && deps.agentSessionId;
+      const shownTrailerEnabled = shownSpanTrailerEnabled();
+      const shownSpans = (exactReread || shownTrailerEnabled)
+        ? collectAgentShownSpans(agentResults, { projectRoot: deps.PROJECT_ROOT }) : [];
+      if (exactReread) {
+        await sendAgentSpanOperation({
+          operation: 'observe',
+          sessionId: deps.agentSessionId,
+          spans: shownSpans,
+          query,
+          regex,
+        });
+      }
       const lines = agentResults
         .filter(r => r.presentation !== 'summary')
         .map((r) => {
@@ -134,7 +165,14 @@ export async function handleSearch({ query, k, mode, structural, regex, format,
                 .map(n => `${n.name} (${n.type === 'function' ? 'fn' : (n.type || 'sym')} ${n.startLine}-${n.endLine} ${n.position})`)
                 .join(' · ')} — sweep: read-semantic ${r.file}`
             : '';
-          return header + symbolInfo + code + sameFile;
+          const continuation = r.continuation?.rendered
+            ? `\n   ${r.continuation.rendered.replace(/^#\s*/, '')}`
+              + (r.continuation.kind === 'symbol' && r.continuation.code
+                ? `\n\`\`\`\n${r.continuation.code}\n\`\`\`` : '')
+            : '';
+          const family = r.familyManifest?.rendered
+            ? `\n   ${r.familyManifest.rendered.replace(/^#\s*/, '')}` : '';
+          return header + symbolInfo + code + sameFile + continuation + family;
         });
 
       const summaries = agentResults
@@ -144,9 +182,13 @@ export async function handleSearch({ query, k, mode, structural, regex, format,
       const confidence = `Confidence: ${searchResult.confidence} (${searchResult.confidenceReason})`;
       const budget = `Tokens: ${searchResult.tokensUsed}/${searchResult.tokenBudget}`;
 
-      const text = lines.length > 0
+      let text = lines.length > 0
         ? `${confidence} | ${budget}\n\n${lines.join('\n\n')}${summaries.length ? '\n\nAlso found:\n' + summaries.join('\n') : ''}`
         : `No results found for "${query}"`;
+      const regexDialectNote = renderRegexDialectHint(searchResult.stats?.regexDialectHint);
+      if (regexDialectNote) text += `\n\n${regexDialectNote}`;
+      const shownTrailer = shownTrailerEnabled ? renderShownFullTrailer(shownSpans) : '';
+      if (shownTrailer) text += `\n\n${shownTrailer}`;
 
       // Shape structuredContent to conform to SearchOutputSchema
       const structured = {
@@ -161,6 +203,14 @@ export async function handleSearch({ query, k, mode, structural, regex, format,
           presentation: r.presentation,
           code: r.code ?? null,
           codeTokens: r.codeTokens,
+          ...(r.continuation ? { continuation: r.continuation } : {}),
+          ...(r.familyManifest ? {
+            familyManifest: {
+              rendered: r.familyManifest.rendered,
+              tokens: r.familyManifest.tokens,
+              groups: r.familyManifest.groups,
+            },
+          } : {}),
         })),
         totalFound: searchResult.totalResults,
         mode: searchResult.mode,
@@ -189,6 +239,9 @@ export async function handleSearch({ query, k, mode, structural, regex, format,
     }
 
     // Standard benchmark mode
+    if (exactRereadOmissionEnabled() && deps.agentSessionId) {
+      await sendAgentSpanOperation({ operation: 'observe', sessionId: deps.agentSessionId, spans: [] });
+    }
     const { results, stats } = searchResult;
     const structured = {
       format: 'benchmark',

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sweet-search",
-  "version": "2.6.16",
-  "description": "Sweet Search - SOTA Hybrid Code Search Engine with WASM CatBoost Query Router, Semantic/Lexical/Structural Search, and Multilingual Support",
+  "version": "2.7.0",
+  "description": "Local code search for AI agents: six fast, purpose-built tools that return ranked answers, not raw grep. Because maybe grep isn't all you need... 🍬",
   "type": "module",
   "main": "core/search/sweet-search.js",
   "exports": {
@@ -167,13 +167,13 @@
     "vitest": "^4.0.16"
   },
   "optionalDependencies": {
-    "@sweet-search/native-darwin-arm64": "2.6.16",
-    "@sweet-search/native-darwin-x64": "2.6.16",
-    "@sweet-search/native-linux-arm64-gnu": "2.6.16",
-    "@sweet-search/native-linux-arm64-gnu-cuda": "2.6.16",
-    "@sweet-search/native-linux-x64-gnu": "2.6.16",
-    "@sweet-search/native-linux-x64-gnu-cuda": "2.6.16",
-    "@sweet-search/bg-priority": "2.6.16"
+    "@sweet-search/native-darwin-arm64": "2.7.0",
+    "@sweet-search/native-darwin-x64": "2.7.0",
+    "@sweet-search/native-linux-arm64-gnu": "2.7.0",
+    "@sweet-search/native-linux-arm64-gnu-cuda": "2.7.0",
+    "@sweet-search/native-linux-x64-gnu": "2.7.0",
+    "@sweet-search/native-linux-x64-gnu-cuda": "2.7.0",
+    "@sweet-search/bg-priority": "2.7.0"
   },
   "engines": {
     "node": ">=18.0.0"

package/scripts/init.js

@@ -994,7 +994,8 @@ export function registerPrewarmSessionStartHook({
     };
   }
 
-  const command = `node ${hookPath}`;
+  const command = `node ${hookPath} --agent-session-hook`;
+  const dropCommand = `node ${hookPath} --agent-session-drop`;
 
   const settingsDir = join(projectRoot, '.claude');
   const settingsPath = join(settingsDir, 'settings.json');
@@ -1012,6 +1013,7 @@ export function registerPrewarmSessionStartHook({
   const sessionStart = Array.isArray(settings.hooks.SessionStart) ? settings.hooks.SessionStart : [];
 
   const entry = {
+    matcher: 'startup|resume|clear|compact',
     hooks: [
       {
         type: 'command',
@@ -1035,6 +1037,29 @@ export function registerPrewarmSessionStartHook({
   }
   settings.hooks.SessionStart = sessionStart;
 
+  // Claude exposes a real SessionEnd event. Drop the bounded RAM receipt
+  // bucket immediately instead of waiting for daemon/session LRU eviction.
+  const sessionEnd = Array.isArray(settings.hooks.SessionEnd) ? settings.hooks.SessionEnd : [];
+  const endEntry = {
+    hooks: [
+      {
+        type: 'command',
+        command: dropCommand,
+        timeout: 2000,
+        continueOnError: true,
+      },
+    ],
+  };
+  const ownedEndIdx = sessionEnd.findIndex((group) =>
+    Array.isArray(group?.hooks) &&
+    group.hooks.some((h) => typeof h?.command === 'string'
+      && h.command.includes(PREWARM_HOOK_FILENAME)
+      && h.command.includes('--agent-session-drop'))
+  );
+  if (ownedEndIdx >= 0) sessionEnd[ownedEndIdx] = endEntry;
+  else sessionEnd.push(endEntry);
+  settings.hooks.SessionEnd = sessionEnd;
+
   try {
     mkdirSync(settingsDir, { recursive: true });
     const tmpPath = settingsPath + '.tmp';
@@ -1103,7 +1128,7 @@ export function registerCodexSessionStartHook({ projectRoot, packageRoot, skippe
   // a repo), which fixes both path resolution AND the launcher's own
   // `process.cwd()` project-root detection, while staying machine-portable
   // (no absolute path is written into the often-committed hooks.json).
-  const command = `cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" && node ${JSON.stringify(hookPath)}`;
+  const command = `cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" && node ${JSON.stringify(hookPath)} --agent-session-hook`;
   const codexDir = join(projectRoot, '.codex');
   const hooksPath = join(codexDir, CODEX_HOOKS_FILENAME);
 
@@ -1119,12 +1144,12 @@ export function registerCodexSessionStartHook({ projectRoot, packageRoot, skippe
   doc.hooks = doc.hooks || {};
   const sessionStart = Array.isArray(doc.hooks.SessionStart) ? doc.hooks.SessionStart : [];
 
-  // `matcher` mirrors the official Codex SessionStart example: fire on a new
-  // session and on resume (the cases where the daemon may not be running yet).
+  // Start/resume prewarm the daemon; clear/compact also reset shown-span
+  // receipts for the new context epoch.
   // `timeout` is in seconds (per Codex's hooks docs); the launcher detaches and
   // returns in well under a second, so a small budget is plenty.
   const entry = {
-    matcher: 'startup|resume',
+    matcher: 'startup|resume|clear|compact',
     hooks: [
       {
         type: 'command',

package/scripts/inject-agent-instructions.js

@@ -54,8 +54,10 @@ function escapeRegex(s) {
 // champion (PHASE7 M++ — held-out 0.988 Maximin, OOD 0.952, HOMP/SCS/counter
 // all pass, 5-cell cross-harness validated — plus the stop-discipline scoping
 // edits that fix M++'s over-stopping on FIX tasks, plus the verdict-gated
-// trust line that scans already-delivered lower ranks before any new search;
-// tool routing unchanged), injected VERBATIM into the harness files.
+// trust line that scans already-delivered lower ranks before any new search,
+// plus the P2 fix-surface paragraph that maps a multi-site edit surface in
+// ONE call before the first edit; tool routing unchanged), injected VERBATIM
+// into the harness files.
 // Per-harness shims (Cursor frontmatter, @imports) are applied at write-time,
 // not embedded here.
 //

package/scripts/uninstall.js

@@ -406,7 +406,7 @@ function pruneEmptyAncestors(start, stopAt) {
 }
 
 /**
- * Remove the sweet-search-owned SessionStart entry from `.claude/settings.json`,
+ * Remove the sweet-search-owned SessionStart and SessionEnd entries from `.claude/settings.json`,
  * preserving every other hook, permission, and top-level key. Detection is
  * filename-based (see PREWARM_HOOK_FILENAME) — only entries whose command
  * references the sweet-search preheat script are removed.
@@ -437,31 +437,33 @@ export function removePrewarmSessionStartHook(projectRoot, { dryRun = false } =
     return { status: 'error', detail: `settings.json is not valid JSON: ${err.message}` };
   }
 
-  const sessionStart = settings?.hooks?.SessionStart;
-  if (!Array.isArray(sessionStart) || sessionStart.length === 0) {
-    return { status: 'not-found', detail: 'no SessionStart entries' };
+  const changes = [];
+  for (const event of ['SessionStart', 'SessionEnd']) {
+    const groups = settings?.hooks?.[event];
+    if (!Array.isArray(groups)) continue;
+    const filtered = groups.filter((group) =>
+      !(Array.isArray(group?.hooks) &&
+        group.hooks.some((h) => typeof h?.command === 'string' && h.command.includes(PREWARM_HOOK_FILENAME)))
+    );
+    if (filtered.length !== groups.length) changes.push({ event, groups, filtered });
   }
 
-  const filtered = sessionStart.filter((group) =>
-    !(Array.isArray(group?.hooks) &&
-      group.hooks.some((h) => typeof h?.command === 'string' && h.command.includes(PREWARM_HOOK_FILENAME)))
-  );
-
-  if (filtered.length === sessionStart.length) {
+  if (changes.length === 0) {
     return { status: 'not-found', detail: 'no matching entry' };
   }
 
+  const removedCount = changes.reduce((sum, change) => sum + change.groups.length - change.filtered.length, 0);
+
   if (dryRun) {
-    return { status: 'dry-run', detail: `would remove ${sessionStart.length - filtered.length} entry` };
+    return { status: 'dry-run', detail: `would remove ${removedCount} entries` };
   }
 
-  if (filtered.length === 0) {
-    delete settings.hooks.SessionStart;
-    if (settings.hooks && Object.keys(settings.hooks).length === 0) {
-      delete settings.hooks;
-    }
-  } else {
-    settings.hooks.SessionStart = filtered;
+  for (const { event, filtered } of changes) {
+    if (filtered.length === 0) delete settings.hooks[event];
+    else settings.hooks[event] = filtered;
+  }
+  if (settings.hooks && Object.keys(settings.hooks).length === 0) {
+    delete settings.hooks;
   }
 
   try {
@@ -472,7 +474,7 @@ export function removePrewarmSessionStartHook(projectRoot, { dryRun = false } =
     return { status: 'error', detail: `write failed: ${err.message}` };
   }
 
-  return { status: 'removed', detail: `spliced out ${sessionStart.length - filtered.length} entry` };
+  return { status: 'removed', detail: `spliced out ${removedCount} entries` };
 }
 
 /**