sweet-search 2.5.2 → 2.5.3

package/eval/agent-read-workflows/bin/_ss-helpers.mjs

@@ -0,0 +1,471 @@
+#!/usr/bin/env node
+// Bench-local agent wrappers for Sweet Search. Each subcommand is a thin,
+// agent-friendly skin over the JS API:
+//   grep      → SweetSearch.bareGrep        (indexed lexical grep, gram-prefiltered)
+//   find      → SweetSearch.patternSearch   (ColGrep — regex candidates, MaxSim re-rank)
+//   read      → search-read.readFile        (filesystem-grounded read with optional line range)
+//   semantic  → search-read-semantic.readSemantic (query-specific spans within one file)
+//
+// Output is compact, deterministic, agent-readable (one match per line for
+// discovery; fenced code for reads). No colour codes. No JSON unless asked.
+
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+// 8-char SHA1 prefix is enough for grouping identical queries across
+// benchmark runs without bloating artifacts.
+function shortQueryHash(q) {
+  try { return createHash('sha1').update(String(q)).digest('hex').slice(0, 16); }
+  catch { return null; }
+}
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(__dirname, '../../..');
+
+// The agent's cwd is the target repo. SWEET_SEARCH_PROJECT_ROOT must point
+// at the repo so DB_PATHS resolves to the repo's own .sweet-search/.
+const PROJECT_ROOT = process.env.SWEET_SEARCH_PROJECT_ROOT || process.cwd();
+
+if (!existsSync(path.join(PROJECT_ROOT, '.sweet-search', 'codebase.db'))) {
+  process.stderr.write(
+    `[ss-*] no Sweet Search index at ${PROJECT_ROOT}/.sweet-search/codebase.db\n` +
+    `Run: SWEET_SEARCH_PROJECT_ROOT=${PROJECT_ROOT} node ${REPO_ROOT}/core/indexing/index-codebase-v21.js --full --sqlite-fast\n`
+  );
+  process.exit(2);
+}
+process.env.SWEET_SEARCH_PROJECT_ROOT = PROJECT_ROOT;
+
+const subcommand = process.argv[2];
+const rest = process.argv.slice(3);
+
+function parseFlag(args, name, fallback) {
+  const i = args.indexOf(name);
+  if (i === -1) return fallback;
+  const v = args[i + 1];
+  args.splice(i, 2);
+  return v;
+}
+function parseShortFlag(args, names, fallback) {
+  for (const n of names) {
+    const i = args.indexOf(n);
+    if (i !== -1) { const v = args[i + 1]; args.splice(i, 2); return v; }
+  }
+  return fallback;
+}
+
+async function getSweetSearch() {
+  const { SweetSearch } = await import(path.join(REPO_ROOT, 'core/search/sweet-search.js'));
+  const s = new SweetSearch({ projectRoot: PROJECT_ROOT });
+  await s.init();
+  return s;
+}
+
+async function ensureWarmServerReady({ timeoutMs = 60000, intervalMs = 500 } = {}) {
+  const { isServerRunning, autoSpawnServer } = await import(path.join(REPO_ROOT, 'core/search/search-server.js'));
+  if (await isServerRunning()) return true;
+
+  // autoSpawnServer has a short built-in timeout. It may return false while the
+  // detached server is still finishing model/index load, so poll afterwards.
+  await autoSpawnServer();
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await isServerRunning()) return true;
+    await new Promise(resolve => setTimeout(resolve, intervalMs));
+  }
+  return false;
+}
+
+// --- subcommands ----------------------------------------------------------
+
+async function cmdGrep(args) {
+  const k = +parseShortFlag(args, ['-k', '--top'], 20);
+  const regex = args[0];
+  if (!regex) {
+    process.stderr.write('Usage: ss-grep <regex> [-k N]\n');
+    process.exit(2);
+  }
+  const s = await getSweetSearch();
+  const result = await s.bareGrep(regex, null, { regex, maxMatches: k * 5, contextLines: 0 });
+  // Group by file, take first k matches across all files (ordered as bareGrep returns).
+  const grouped = new Map();
+  for (const r of result.results.slice(0, k * 5)) {
+    if (!grouped.has(r.file)) grouped.set(r.file, []);
+    grouped.get(r.file).push(r);
+  }
+  let printed = 0;
+  process.stdout.write(`# ss-grep: ${result.results.length} total match(es) for /${regex}/\n`);
+  for (const [file, lines] of grouped) {
+    for (const r of lines) {
+      const text = (r.matchText || '').replace(/\s+/g, ' ').trim().slice(0, 140);
+      process.stdout.write(`${file}:${r.line}: ${text}\n`);
+      printed++;
+      if (printed >= k) break;
+    }
+    if (printed >= k) break;
+  }
+  if (printed === 0) process.stdout.write('(no matches)\n');
+  process.exit(0);
+}
+
+async function cmdFind(args) {
+  // ColGrep pattern search with token-budgeted agent packaging — returns the
+  // FULL useful answer (ranked code blocks + confidence + sufficiency), the same
+  // agent packaging ss-search emits. ss-grep is the short/locator counterpart, so
+  // ss-find defaults to the full answer: it saves the follow-up read entirely.
+  // (Mirrors the agent-in-the-loop H2H adapter eval/agent-eval/tools/
+  // pattern-agent-tools.js, which calls search(...,{format:'agent'}).)
+  let format = 'agent';
+  if (args.includes('--full')) { format = 'agent_full'; args.splice(args.indexOf('--full'), 1); }
+  if (args.includes('--xl'))   { format = 'agent_full_xl'; args.splice(args.indexOf('--xl'), 1); }
+  const k = +parseShortFlag(args, ['-k', '--top'], 6);
+  const regex = parseFlag(args, '--regex', '');
+  const query = args[0];
+  if (!query) {
+    process.stderr.write('Usage: ss-find "<query>" --regex "<regex>" [--full|--xl] [-k N]\n');
+    process.exit(2);
+  }
+  const effectiveRegex = regex || '';
+  const s = await getSweetSearch();
+  if (!s.hasLateInteractionIndex) {
+    process.stderr.write(`[ss-find] no late-interaction index — falling back to ss-grep\n`);
+    return cmdGrep([effectiveRegex || query, '-k', String(k)]);
+  }
+  const response = await s.patternSearch(query, null, {
+    regex: effectiveRegex || `\\b\\w+\\b`,
+    k,
+    format,
+  });
+
+  // Header (visible to agent)
+  process.stdout.write(`# ss-find: ColGrep ${response.results?.length || 0} for "${query}" /${effectiveRegex || '*'}/` +
+    ` budget=${response.tokenBudget} used=${response.tokensUsed} subMode=${response.subMode ?? format}\n`);
+  if (response.confidence) {
+    process.stdout.write(`# confidence=${response.confidence}${response.confidenceReason ? ' (' + response.confidenceReason + ')' : ''}` +
+      `${response.sufficient ? ' sufficient=YES' : ' sufficient=no'}\n`);
+  }
+
+  // Per-result blocks — identical shape to ss-search's agent packaging.
+  for (const r of response.results || []) {
+    const sym = r.symbol ? ` [${r.symbolType || 'code'}: ${r.symbol}]` : '';
+    const kind = r.expansionKind ? ` kind=${r.expansionKind}` : '';
+    const stale = r.stale ? ' STALE' : '';
+    process.stdout.write(`\n## #${r.rank} ${r.file}:${r.startLine}-${r.endLine}${sym} (${r.presentation}${kind}${stale}) score=${(r.score || 0).toFixed(3)}\n`);
+    if (r.headerContext) {
+      process.stdout.write(`### imports\n\`\`\`\n${r.headerContext}\n\`\`\`\n`);
+    }
+    if (r.code) {
+      process.stdout.write(`\`\`\`\n${r.code}\n\`\`\`\n`);
+    } else if (r.summary) {
+      process.stdout.write(`${r.summary}\n`);
+    }
+    if (r.neighbors && r.neighbors.rendered) {
+      process.stdout.write(`### related (1-hop graph, ~${r.neighbors.tokens} tok)\n${r.neighbors.rendered}\n`);
+    }
+  }
+  if (!response.results || response.results.length === 0) process.stdout.write('(no matches)\n');
+  process.exit(0);
+}
+
+async function cmdRead(args) {
+  const file = args[0];
+  if (!file) {
+    process.stderr.write('Usage: ss-read <file>             # whole file\n');
+    process.stderr.write('       ss-read <file> <start>     # ONE line\n');
+    process.stderr.write('       ss-read <file> <start> <end>\n');
+    process.exit(2);
+  }
+  // If start is provided and end is omitted, read EXACTLY that one line —
+  // no open-ended start-to-EOF (which a previous version did and which
+  // caused accidental over-reading on large files).
+  let start = null, end = null;
+  if (args[1] != null) {
+    start = +args[1];
+    if (!Number.isFinite(start) || start < 1) {
+      process.stderr.write(`[ss-read] invalid start line: "${args[1]}"\n`);
+      process.exit(2);
+    }
+    if (args[2] != null) {
+      end = +args[2];
+      if (!Number.isFinite(end) || end < start) {
+        process.stderr.write(`[ss-read] invalid end line: "${args[2]}" (must be ≥ start ${start})\n`);
+        process.exit(2);
+      }
+    } else {
+      end = start;     // single-line read
+    }
+  }
+  const { readFile } = await import(path.join(REPO_ROOT, 'core/search/search-read.js'));
+  const r = await readFile({ path: file, projectRoot: PROJECT_ROOT, startLine: start ?? undefined, endLine: end ?? undefined });
+  if (!r.ok) {
+    process.stderr.write(`[ss-read] error: ${r.error}\n`);
+    process.exit(1);
+  }
+  const range = r.range ? ` (lines ${r.range.startLine}-${r.range.endLine} of ${r.totalLines})` : ` (${r.totalLines} lines)`;
+  const fence = r.language ? '```' + r.language : '```';
+  process.stdout.write(`# ss-read ${r.file}${range}\n${fence}\n${r.text}\n\`\`\`\n`);
+  process.exit(0);
+}
+
+async function cmdAgentSearch(args) {
+  // Main sweet-search auto/CatBoost search with token-budgeted agent packaging.
+  //
+  // Usage:
+  //   ss-search "<query>"                                  → format=agent (auto-pick 4k/8k/12k)
+  //   ss-search "<query>" --full                           → force 8k (rarely needed; default auto-picks)
+  //   ss-search "<query>" --xl                             → force 12k (rarely needed; default auto-picks)
+  //   ss-search "<query>" -k 5                             → top-K results
+  //   ss-search "<query>" --mode hybrid                    → force a mode (default: auto/CatBoost)
+  //
+  // Output is agent-readable: a meta header with routed mode + budget,
+  // followed by per-result blocks with file/line + fenced code. A trailing
+  // structured marker line `<<SS_ROUTE_META>>{...json...}` lets the bench
+  // post-process parse routing/budget telemetry without affecting the agent.
+  let format = 'agent';
+  if (args.includes('--full')) { format = 'agent_full'; args.splice(args.indexOf('--full'), 1); }
+  if (args.includes('--xl'))   { format = 'agent_full_xl'; args.splice(args.indexOf('--xl'), 1); }
+  const k = +parseShortFlag(args, ['-k', '--top'], 5);
+  const mode = parseFlag(args, '--mode', 'auto');
+  const query = args[0];
+  if (!query) {
+    process.stderr.write('Usage: ss-search "<query>" [--full|--xl] [-k N] [--mode auto|lexical|semantic|hybrid]\n');
+    process.exit(2);
+  }
+
+  const { queryServer } = await import(path.join(REPO_ROOT, 'core/search/search-server.js'));
+  const serverUsed = await ensureWarmServerReady();
+  if (!serverUsed) {
+    process.stderr.write('[ss-search] warm server is not ready; refusing cold direct search in benchmark wrapper\n');
+    process.exit(1);
+  }
+
+  const response = await queryServer(query, { topK: k, mode, format });
+  if (response?.error) {
+    process.stderr.write(`[ss-search] server error: ${response.error}\n`);
+    process.exit(1);
+  }
+
+  // REPO ISOLATION: refuse to return results from a daemon serving a different
+  // repo. The bench harness uses /tmp/sweet-search.sock, which is a global socket;
+  // a multi-repo bench fan-out previously reused a stale daemon and silently
+  // returned cross-repo matches. Fail closed instead.
+  const requestedProjectRoot = path.resolve(PROJECT_ROOT);
+  const serverProjectRoot = response?.serverProjectRoot
+    ? path.resolve(response.serverProjectRoot) : null;
+  const repoMatches = serverProjectRoot != null && serverProjectRoot === requestedProjectRoot;
+  if (!repoMatches) {
+    process.stderr.write(
+      `[ss-search] repo isolation violation: requested projectRoot=${requestedProjectRoot} ` +
+      `but server reports serverProjectRoot=${serverProjectRoot ?? '<null>'}. ` +
+      `Refusing to surface cross-repo results.\n`
+    );
+    // Emit a structured trailer anyway so the bench can capture the failure.
+    const failMeta = {
+      query,
+      queryHash: shortQueryHash(query),
+      queryLen: query.length,
+      routedMode: response?.stats?.routing?.mode || null,
+      routeConfidence: typeof response?.stats?.routing?.confidence === 'number'
+        ? response.stats.routing.confidence : null,
+      routeMethod: response?.stats?.routing?.method || null,
+      routerLatency_us: typeof response?.stats?.routing?.latency_us === 'number'
+        ? response.stats.routing.latency_us : null,
+      serverUsed: true,
+      serverProjectRoot,
+      requestedProjectRoot,
+      repoMatches: false,
+      error: 'repo-isolation-mismatch',
+    };
+    process.stdout.write(`\n<<SS_ROUTE_META>>${JSON.stringify(failMeta)}\n`);
+    process.exit(3);
+  }
+
+  // The packaged response shape comes from packageForAgent (or pattern's own
+  // packager when CatBoost routes to pattern). Both include:
+  //   .results[] with {rank, file, startLine, endLine, symbol, symbolType,
+  //                    presentation, code, codeTokens, expansionKind, ...}
+  //   .tokenBudget, .tokensUsed, .subMode, .confidence, .sufficient
+  //   .stats.routing (when produced by the main pipeline)
+  const routing = response.stats?.routing || {};
+  const routedMode = routing.mode || 'pattern';
+  const routeConfidence = typeof routing.confidence === 'number' ? routing.confidence : null;
+  // Route attribution: where did the decision come from? Values produced by
+  // core/query/query-router.js: 'file_pattern', 'wasm_catboost', 'wasm_rejected',
+  // 'fallback_error', 'invalid_input', 'query_too_long', 'empty_query'. When
+  // the user forced a mode, routing.method is undefined and routing.forced
+  // is true.
+  const routeMethod = routing.method || (routing.forced ? 'forced' : null);
+  const routerLatency_us = typeof routing.latency_us === 'number' ? routing.latency_us : null;
+  const tierCounts = (response.results || []).reduce((acc, r) => {
+    acc[r.presentation] = (acc[r.presentation] || 0) + 1;
+    return acc;
+  }, {});
+  const sandwichCount = (response.results || []).filter(r => r.expansionKind === 'sandwich').length;
+  const neighborCount = (response.results || []).reduce((acc, r) => acc + (r.neighbors?.count || 0), 0);
+  const headerCount = (response.results || []).filter(r => r.headerContext).length;
+
+  // Header (visible to agent)
+  const conf = routeConfidence != null ? ` conf=${routeConfidence.toFixed(2)}` : '';
+  process.stdout.write(`# ss-search: routed=${routedMode}${conf} budget=${response.tokenBudget} used=${response.tokensUsed}` +
+    ` results=${response.results.length} subMode=${response.subMode}\n`);
+  if (response.confidence) {
+    process.stdout.write(`# confidence=${response.confidence}${response.confidenceReason ? ' (' + response.confidenceReason + ')' : ''}` +
+      `${response.sufficient ? ' sufficient=YES' : ' sufficient=no'}\n`);
+  }
+
+  // Per-result blocks
+  for (const r of response.results || []) {
+    const sym = r.symbol ? ` [${r.symbolType || 'code'}: ${r.symbol}]` : '';
+    const kind = r.expansionKind ? ` kind=${r.expansionKind}` : '';
+    const stale = r.stale ? ' STALE' : '';
+    process.stdout.write(`\n## #${r.rank} ${r.file}:${r.startLine}-${r.endLine}${sym} (${r.presentation}${kind}${stale}) score=${(r.score || 0).toFixed(3)}\n`);
+    if (r.headerContext) {
+      process.stdout.write(`### imports\n\`\`\`\n${r.headerContext}\n\`\`\`\n`);
+    }
+    if (r.code) {
+      process.stdout.write(`\`\`\`\n${r.code}\n\`\`\`\n`);
+    } else if (r.summary) {
+      process.stdout.write(`${r.summary}\n`);
+    }
+    // Render the 1-hop graph-neighbour tier directly under top-1's code block.
+    // The package surfaces `r.neighbors` only on the rank that earned the
+    // reservation (typically top-1). Each line carries `file:line` so the
+    // agent can cite the neighbour without an extra search.
+    if (r.neighbors && r.neighbors.rendered) {
+      process.stdout.write(`### related (1-hop graph, ~${r.neighbors.tokens} tok)\n${r.neighbors.rendered}\n`);
+    }
+  }
+
+  if (!response.results || response.results.length === 0) {
+    process.stdout.write('(no matches)\n');
+  }
+
+  // Structured trailer for bench post-processing (audit/summariseRun can parse).
+  // Route attribution fields (queryHash, routeMethod, routerLatency_us, query)
+  // let downstream analysis link a routing decision to its query and
+  // attribute failures to fast-path vs WASM vs fallback.
+  const meta = {
+    query,                     // exact query text (already bounded by SEARCH_SERVER_MAX_QUERY_LENGTH)
+    queryHash: shortQueryHash(query),
+    queryLen: query.length,
+    routedMode,
+    routeConfidence,
+    routeMethod,
+    routerLatency_us,
+    serverUsed,
+    serverProjectRoot,
+    requestedProjectRoot,
+    repoMatches,
+    serverPid: response.serverPid ?? null,
+    tokenBudget: response.tokenBudget,
+    tokensUsed: response.tokensUsed,
+    subMode: response.subMode,
+    resultCount: response.results?.length || 0,
+    tierCounts,
+    sandwichCount,
+    neighborCount,
+    headerCount,
+    confidence: response.confidence || null,
+    sufficient: response.sufficient ?? null,
+    sufficiencyReasons: Array.isArray(response.sufficiencyReasons) ? response.sufficiencyReasons : null,
+    unresolvedExternalCount: typeof response.unresolvedExternalCount === 'number'
+      ? response.unresolvedExternalCount : null,
+  };
+  process.stdout.write(`\n<<SS_ROUTE_META>>${JSON.stringify(meta)}\n`);
+  process.exit(0);
+}
+
+async function cmdSemantic(args) {
+  const file = args[0];
+  const query = args[1];
+  if (!file || !query) {
+    process.stderr.write('Usage: ss-semantic <file> "<question>" [--max-tokens N]\n');
+    process.exit(2);
+  }
+  const maxTokens = +parseFlag(args.slice(2), '--max-tokens', 800);
+  const { readSemantic } = await import(path.join(REPO_ROOT, 'core/search/search-read-semantic.js'));
+  const r = await readSemantic({
+    path: file, query, projectRoot: PROJECT_ROOT,
+    maxChars: maxTokens * 4, verbose: false,
+  });
+  if (!r.ok) {
+    process.stderr.write(`[ss-semantic] error: ${r.reason || 'unknown'}\n`);
+    process.exit(1);
+  }
+  process.stdout.write(`# ss-semantic ${r.file} | "${query}" | spans=${r.spans?.length ?? 0} | ~tokens=${r.approxTokensReturned}${r.fellBack ? ' [FALLBACK]' : ''}\n`);
+  for (const span of r.spans || []) {
+    const fence = r.language ? '```' + r.language : '```';
+    const sym = span.symbols?.length ? ` [${span.symbols.join(', ')}]` : '';
+    process.stdout.write(`### ${r.file}:${span.startLine}-${span.endLine}${sym}\n${fence}\n${span.text}\n\`\`\`\n`);
+  }
+  process.exit(0);
+}
+
+async function cmdTrace(args) {
+  let json = false;
+  if (args.includes('--json')) {
+    json = true;
+    args.splice(args.indexOf('--json'), 1);
+  }
+  const symbol = args[0];
+  if (!symbol) {
+    process.stderr.write('Usage: ss-trace <symbol> [--in <file>] [--query <hint>] [--depth N] [--budget N]\n');
+    process.exit(2);
+  }
+  const { traceSymbol, formatStructuralContext } = await import(path.join(REPO_ROOT, 'core/search/search-trace.js'));
+
+  const opts = { projectRoot: PROJECT_ROOT };
+  const file = parseFlag(args, '--in', null) || parseFlag(args, '--file', null);
+  const queryHint = parseFlag(args, '--query', '') || parseFlag(args, '--hint', '');
+  const depth = parseFlag(args, '--depth', null);
+  const budget = parseFlag(args, '--budget', null);
+  if (file) opts.filePath = file;
+  if (queryHint) opts.queryHint = queryHint;
+  if (depth != null) opts.maxDepth = +depth;
+  if (budget != null) opts.tokenBudget = +budget;
+
+  const response = traceSymbol(symbol, opts);
+  if (json) process.stdout.write(JSON.stringify(response, null, 2) + '\n');
+  else process.stdout.write(formatStructuralContext(response) + '\n');
+
+  const meta = {
+    symbol,
+    queryHash: shortQueryHash(`${symbol}:${queryHint || ''}`),
+    target: response.target ? {
+      name: response.target.name,
+      type: response.target.type,
+      file: response.target.filePath,
+      startLine: response.target.startLine,
+    } : null,
+    tokenBudget: response.tokenBudget,
+    tokensUsed: response.tokensUsed,
+    budgetTier: response.budgetTier,
+    budgetReason: response.budgetReason,
+    callers: response.sections?.callers?.total || 0,
+    callees: response.sections?.callees?.total || 0,
+    impactPaths: response.sections?.impact?.total || 0,
+    latencyMs: response.stats?.latencyMs ?? null,
+    sufficient: !!response.target,
+  };
+  process.stdout.write(`\n<<SS_TRACE_META>>${JSON.stringify(meta)}\n`);
+  process.exit(response.target ? 0 : 1);
+}
+
+(async () => {
+  try {
+    if (subcommand === 'grep') await cmdGrep(rest);
+    else if (subcommand === 'find') await cmdFind(rest);
+    else if (subcommand === 'read') await cmdRead(rest);
+    else if (subcommand === 'semantic') await cmdSemantic(rest);
+    else if (subcommand === 'trace') await cmdTrace(rest);
+    else if (subcommand === 'agent-search') await cmdAgentSearch(rest);
+    else { process.stderr.write(`unknown subcommand: ${subcommand}\n`); process.exit(2); }
+  } catch (err) {
+    process.stderr.write(`[ss-*] crash: ${err.stack || err.message || err}\n`);
+    process.exit(1);
+  }
+})();
+
+// Mark unused for lint:
+void readFileSync;

package/eval/agent-read-workflows/bin/ss-find

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+# ss-find: ColGrep / patternSearch — regex candidates re-ranked by MaxSim
+# against your natural-language query, returned as the FULL agent answer
+# (ranked code blocks + confidence/sufficiency), so no follow-up read is needed.
+# Use for behavioural / semantic questions where lexical alone won't pinpoint the
+# chunk. (ss-grep is the short file:line locator.)
+#
+# Usage:  ss-find "<query>" --regex "<regex>" [--full|--xl] [-k N]
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+TMPERR=$(mktemp)
+node "$DIR/_ss-helpers.mjs" find "$@" 2>"$TMPERR"
+RC=$?
+[ $RC -ne 0 ] && cat "$TMPERR" >&2
+rm -f "$TMPERR"
+exit $RC

package/eval/agent-read-workflows/bin/ss-grep

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# ss-grep: indexed bare grep (gram-prefiltered) over the cwd's Sweet Search index.
+# Compact agent-friendly output: file:line  matchText
+#
+# Usage:  ss-grep <regex> [-k N]
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+TMPERR=$(mktemp)
+node "$DIR/_ss-helpers.mjs" grep "$@" 2>"$TMPERR"
+RC=$?
+[ $RC -ne 0 ] && cat "$TMPERR" >&2
+rm -f "$TMPERR"
+exit $RC

package/eval/agent-read-workflows/bin/ss-read

@@ -0,0 +1,14 @@
+#!/usr/bin/env bash
+# ss-read: filesystem-grounded read of one file.
+#   ss-read <file>                  # whole file
+#   ss-read <file> <start>          # ONE line (NOT start-to-EOF)
+#   ss-read <file> <start> <end>    # explicit range
+# Open-ended start-to-EOF is intentionally not supported in the bench wrapper
+# to prevent accidental over-reading. To pull a span, give an explicit end.
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+TMPERR=$(mktemp)
+node "$DIR/_ss-helpers.mjs" read "$@" 2>"$TMPERR"
+RC=$?
+[ $RC -ne 0 ] && cat "$TMPERR" >&2
+rm -f "$TMPERR"
+exit $RC

package/eval/agent-read-workflows/bin/ss-search

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# ss-search: Sweet Search auto/CatBoost-routed search with token-budgeted
+# agent packaging. Exercises the main sweet-search pipeline (lexical /
+# semantic / hybrid / structural) with auto-tier budget by default.
+#
+# Usage:
+#   ss-search "<query>"                    # auto-picks 4k / 8k / 12k from signals
+#   ss-search "<query>" --full             # force 8k (rarely needed; default auto-picks)
+#   ss-search "<query>" --xl               # force 12k (rarely needed; default auto-picks)
+#   ss-search "<query>" -k N               # top-K (default 5)
+#   ss-search "<query>" --mode hybrid      # force a mode (default: auto)
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+TMPERR=$(mktemp)
+node "$DIR/_ss-helpers.mjs" agent-search "$@" 2>"$TMPERR"
+RC=$?
+[ $RC -ne 0 ] && cat "$TMPERR" >&2
+rm -f "$TMPERR"
+exit $RC

package/eval/agent-read-workflows/bin/ss-semantic

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# ss-semantic: query-specific spans inside ONE file using read-semantic.
+# Default --max-tokens cap of 800 keeps spans focused.
+#
+# Usage:  ss-semantic <file> "<question>" [--max-tokens N]
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+TMPERR=$(mktemp)
+node "$DIR/_ss-helpers.mjs" semantic "$@" 2>"$TMPERR"
+RC=$?
+[ $RC -ne 0 ] && cat "$TMPERR" >&2
+rm -f "$TMPERR"
+exit $RC

package/eval/agent-read-workflows/bin/ss-trace

@@ -0,0 +1,11 @@
+#!/usr/bin/env bash
+# ss-trace: unified structural context for one symbol (callers, callees, impact).
+#
+# Usage: ss-trace <symbol> [--in <file>] [--query <hint>] [--depth N] [--budget N]
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+TMPERR=$(mktemp)
+node "$DIR/_ss-helpers.mjs" trace "$@" 2>"$TMPERR"
+RC=$?
+[ $RC -ne 0 ] && cat "$TMPERR" >&2
+rm -f "$TMPERR"
+exit $RC

package/mcp/read-tool.js

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+
+const ReadFileResultSchema = z.object({
+  file: z.string(),
+  absolutePath: z.string().optional(),
+  ok: z.boolean(),
+  exact: z.boolean().optional(),
+  indexed: z.boolean().optional(),
+  language: z.string().nullable().optional(),
+  totalLines: z.number().int().optional(),
+  bytes: z.number().int().optional(),
+  mtimeMs: z.number().optional(),
+  range: z.object({
+    startLine: z.number().int(),
+    endLine: z.number().int(),
+  }).nullable().optional(),
+  text: z.string().optional(),
+  chunks: z.array(z.object({
+    id: z.string(),
+    symbol: z.string().nullable().optional(),
+    type: z.string().nullable().optional(),
+    startLine: z.number().int().nullable().optional(),
+    endLine: z.number().int().nullable().optional(),
+    signature: z.string().nullable().optional(),
+  })).optional(),
+  error: z.string().optional(),
+  timings: z.object({ totalMs: z.number() }).optional(),
+});
+
+export const ReadOutputSchema = z.object({
+  files: z.array(ReadFileResultSchema),
+  totalMs: z.number(),
+});
+
+const ReadSemanticSpanSchema = z.object({
+  startLine: z.number().int(),
+  endLine: z.number().int(),
+  score: z.number(),
+  symbols: z.array(z.string()).optional(),
+  types: z.array(z.string()).optional(),
+  chunkIds: z.array(z.string()).optional(),
+  text: z.string(),
+  truncated: z.boolean().optional(),
+});
+
+export const ReadSemanticOutputSchema = z.object({
+  file: z.string(),
+  query: z.string(),
+  ok: z.boolean(),
+  indexed: z.boolean(),
+  fellBack: z.boolean(),
+  reason: z.string().optional(),
+  language: z.string().nullable().optional(),
+  totalLines: z.number().int().optional(),
+  spans: z.array(ReadSemanticSpanSchema),
+  charsReturned: z.number().int().optional(),
+  approxTokensReturned: z.number().int().optional(),
+  signals: z.record(z.string(), z.any()).optional(),
+  timings: z.record(z.string(), z.number()).optional(),
+});
+
+/**
+ * @param {{ files: Array<{path: string, startLine?: number, endLine?: number}>, includeMetadata?: boolean }} args
+ * @param {{ PROJECT_ROOT: string }} deps
+ */
+export async function handleRead(args, deps) {
+  try {
+    const { readFiles, formatReadResults } = await import('../core/search/index.js');
+    const result = await readFiles(args.files || [], {
+      projectRoot: deps.PROJECT_ROOT,
+      includeMetadata: args.includeMetadata !== false,
+    });
+    return {
+      content: [{ type: 'text', text: formatReadResults(result, 'agent') }],
+      structuredContent: result,
+    };
+  } catch (err) {
+    const msg = (err.message || 'read failed').split('\n')[0];
+    return { content: [{ type: 'text', text: `read error: ${msg}` }], isError: true };
+  }
+}
+
+/**
+ * @param {{ file: string, query: string, topK?: number, threshold?: number, contextLines?: number, maxChars?: number, maxTokens?: number, verbose?: boolean }} args
+ * @param {{ PROJECT_ROOT: string }} deps
+ */
+export async function handleReadSemantic(args, deps) {
+  try {
+    const { readSemantic, formatReadSemanticResult } = await import('../core/search/index.js');
+    const result = await readSemantic({
+      path: args.file,
+      query: args.query,
+      topK: args.topK,
+      threshold: args.threshold,
+      contextLines: args.contextLines,
+      maxChars: args.maxChars,
+      maxTokens: args.maxTokens,
+      projectRoot: deps.PROJECT_ROOT,
+      verbose: args.verbose,
+    });
+    return {
+      content: [{ type: 'text', text: formatReadSemanticResult(result, 'agent') }],
+      structuredContent: result,
+    };
+  } catch (err) {
+    const msg = (err.message || 'read-semantic failed').split('\n')[0];
+    return { content: [{ type: 'text', text: `read-semantic error: ${msg}` }], isError: true };
+  }
+}