@takara-ai/miru-code 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takara-ai/miru-code",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Miru (見る) — hybrid code search for agents. Bun, TypeScript, Takara embeddings.",
   "type": "module",
   "license": "MIT",

package/src/benchmark/compare.ts

@@ -1,8 +1,9 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { relativePathFromRoot } from "../index/incremental.ts";
+import { formatExpandResultsText, formatResultsText } from "../mcp/format-text.ts";
 import type { MiruIndex } from "../miru-index.ts";
-import { applySnippetsToResults, estimateResultTokens } from "../snippet.ts";
+import { applySnippetsToResults } from "../snippet.ts";
 import { countTokens, tokenCountMethod, tokenizerJsonPath } from "../token-count.ts";
 import type { SearchResult } from "../types.ts";
 import {
@@ -10,6 +11,8 @@ import {
   DEFAULT_EXPAND_BEFORE,
   dedupeResultsByFile,
   expandChunksAtLine,
+  formatExpandResults,
+  formatResults,
 } from "../utils.ts";
 import { type GrepFileHit, grepSearch } from "./grep.ts";
 import { agentBenchmarkFromTokens, attachAgentBenchmark, tokenSavingsPct } from "./summary.ts";
@@ -83,6 +86,7 @@ async function readLineWindowTokens(
   }
 }
 
+/** Tokens of the MCP `expand` text body (headers + chunk content), matching what agents receive. */
 function miruExpandTokens(
   index: MiruIndex,
   repoPath: string,
@@ -94,7 +98,7 @@ function miruExpandTokens(
   }
   const [{ meta }] = applySnippetsToResults([top], query);
   const line = meta.truncated ? meta.anchor_line : top.chunk.start_line;
-  const { chunks } = expandChunksAtLine(
+  const { anchor, chunks } = expandChunksAtLine(
     index.chunks,
     top.chunk.file_path,
     line,
@@ -102,8 +106,18 @@ function miruExpandTokens(
     DEFAULT_EXPAND_BEFORE,
     DEFAULT_EXPAND_AFTER,
   );
+  if (!anchor) {
+    return { tokens: 0, lineSpan: 0 };
+  }
+  const text = formatExpandResultsText(
+    formatExpandResults(top.chunk.file_path, line, anchor, chunks, {
+      repoRoot: repoPath,
+      before: DEFAULT_EXPAND_BEFORE,
+      after: DEFAULT_EXPAND_AFTER,
+    }),
+  );
   return {
-    tokens: chunks.reduce((sum, chunk) => sum + countTokens(chunk.content), 0),
+    tokens: countTokens(text),
     lineSpan: expandLineSpan(chunks),
   };
 }
@@ -164,8 +178,10 @@ export async function benchmarkSearchComparison(options: {
     const started = performance.now();
     const raw = await index.search({ query, topK, rerank: true });
     const results = (dedupeByFile ? dedupeResultsByFile(raw) : raw).slice(0, topK);
-    const snippetResults = applySnippetsToResults(results, query).map((entry) => entry.result);
-    const searchTokens = estimateResultTokens(snippetResults);
+    // Count the MCP tool text body (path headers + snippets), not bare chunk content.
+    const searchTokens = countTokens(
+      formatResultsText(formatResults(query, results, { repoRoot: repoPath, snippet: true })),
+    );
     const expand = miruExpandTokens(index, repoPath, results[0], query);
     return {
       results,
@@ -264,6 +280,7 @@ export function toAgentBenchmarkSummary(block: SearchBenchmarkBlock): AgentBench
     block.accuracy.rank1_match,
   );
   summary.save_pct = block.efficiency.token_savings_pct;
+  summary.search_tok = block.miru.search_tokens;
   if (block.accuracy.miru_only.length > 0) {
     summary.miru_only = block.accuracy.miru_only.slice(0, MAX_AGENT_MIRU_ONLY);
   }

package/src/benchmark/locate-compare.ts

@@ -1,10 +1,11 @@
 /**
- * Compare Miru `locate` agent payload tokens vs the costlier native Grep path.
+ * Compare Miru `locate` MCP response tokens vs the costlier native Grep path.
  *
- * Baseline mirrors Cursor/Claude Grep-style output: fixed-string matches with
- * ±GREP_CONTEXT lines (not slim `rg -n`). That is the expensive path agents
- * take without `locate`, so savings measure real workflow cost — not an
- * apples-to-apples payload contest against optimally-minimal ripgrep.
+ * Miru side counts the agent-facing text body (`formatLiteralLocateText`), not
+ * the intermediate JSON payload. Baseline mirrors Cursor/Claude Grep-style
+ * output: fixed-string matches with ±GREP_CONTEXT lines (not slim `rg -n`).
+ * That is the expensive path agents take without `locate`, so savings measure
+ * real workflow cost — not an apples-to-apples contest against minimal ripgrep.
  */
 
 import {
@@ -13,6 +14,7 @@ import {
   type LiteralLocateOptions,
   type LiteralLocateResult,
 } from "../literal.ts";
+import { formatLiteralLocateText } from "../mcp/format-text.ts";
 import type { MiruIndex } from "../miru-index.ts";
 import { countTokens } from "../token-count.ts";
 import { GREP_CONTEXT } from "./grep.ts";
@@ -44,11 +46,16 @@ export async function benchmarkLocateComparison(options: {
   const result = options.index.locateLiteral(options.literal, locateOpts);
   const miruMs = performance.now() - miruStart;
   const payload = formatLiteralLocate(result);
-  const miruTok = countTokens(JSON.stringify(payload));
+  const miruTok = countTokens(formatLiteralLocateText(payload));
 
   // Unbounded agent-style Grep dump (±context) — the costlier path without locate.
-  const grep = await rgLiteralOutput(options.repoPath, options.literal, {
-    context: GREP_CONTEXT,
+  // Never use less context than the caller actually requested via context_lines,
+  // or a locate call that returns inline context looks artificially expensive
+  // against a baseline that didn't have to fetch that context at all. Likewise,
+  // grep every variant `match_variants`/an array `literal` actually matched —
+  // one grep pattern isn't equivalent recall, so it isn't a fair baseline.
+  const grep = await rgLiteralOutput(options.repoPath, result.literals ?? [options.literal], {
+    context: Math.max(GREP_CONTEXT, locateOpts.context_lines ?? 0),
     maxCount: 0,
     ignoreCase: locateOpts.ignore_case,
   });

package/src/benchmark/rg-literal.ts

@@ -61,13 +61,14 @@ function parsePathLinePrefix(line: string): { path: string; line: number } | nul
 
 export async function rgLiteralOutput(
   repoRoot: string,
-  literal: string,
+  literal: string | readonly string[],
   options: {
     context?: number;
     maxCount?: number;
     ignoreCase?: boolean;
   } = {},
 ): Promise<RgLiteralOutput> {
+  const literals = Array.isArray(literal) ? literal : [literal as string];
   const context = options.context ?? 0;
   const maxCount = options.maxCount ?? 20;
   const tool = selectBenchmarkSearchTool();
@@ -76,7 +77,7 @@ export async function rgLiteralOutput(
   }
   const start = performance.now();
   const proc = Bun.spawn(
-    buildLiteralArgs(tool, repoRoot, literal, context, maxCount, !!options.ignoreCase),
+    buildLiteralArgs(tool, repoRoot, literals, context, maxCount, !!options.ignoreCase),
     {
       stdout: "pipe",
       stderr: "pipe",
@@ -90,10 +91,14 @@ export async function rgLiteralOutput(
   return { text, tokens: countTokens(text), latency_ms, ...stats };
 }
 
+/**
+ * OR-matches every literal, mirroring what an agent without `locate` would have to run
+ * to get the same recall as `literals`/`match_variants` (one pattern isn't equivalent).
+ */
 function buildLiteralArgs(
   tool: "rg" | "grep" | "findstr",
   repoRoot: string,
-  literal: string,
+  literals: readonly string[],
   context: number,
   maxCount: number,
   ignoreCase: boolean,
@@ -109,7 +114,10 @@ function buildLiteralArgs(
     if (maxCount > 0) {
       args.push("-m", String(maxCount));
     }
-    args.push(literal, repoRoot);
+    for (const l of literals) {
+      args.push("-e", l);
+    }
+    args.push(repoRoot);
     return args;
   }
   if (tool === "grep") {
@@ -132,10 +140,17 @@ function buildLiteralArgs(
     if (maxCount > 0) {
       args.push("-m", String(maxCount));
     }
-    args.push(literal, repoRoot);
+    for (const l of literals) {
+      args.push("-e", l);
+    }
+    args.push(repoRoot);
     return args;
   }
-  const args = ["findstr", "/S", "/N", "/P", `/C:${literal}`, "*"];
+  const args = ["findstr", "/S", "/N", "/P"];
+  for (const l of literals) {
+    args.push(`/C:${l}`);
+  }
+  args.push("*");
   if (ignoreCase) {
     args.splice(4, 0, "/I");
   }

package/src/benchmark/summary.ts

@@ -20,10 +20,19 @@ export function agentBenchmarkFromTokens(
   };
 }
 
-/** Attach compact `benchmark` to an MCP tool payload. */
+/** Attach compact `benchmark` to an MCP tool payload (JSON path / tests). */
 export function attachAgentBenchmark<T extends Record<string, unknown>>(
   payload: T,
   benchmark: AgentBenchmarkSummary,
 ): T & { benchmark: AgentBenchmarkSummary } {
   return { ...payload, benchmark };
 }
+
+/**
+ * Append a compact trailing JSON object so plaintext MCP bodies can still expose
+ * `benchmark` without wrapping the result in JSON scaffolding.
+ * `miru_tok` counts the body only — never this trailer.
+ */
+export function appendAgentBenchmark(body: string, benchmark: AgentBenchmarkSummary): string {
+  return `${body}\n\n${JSON.stringify({ benchmark })}`;
+}

package/src/benchmark/types.ts

@@ -42,7 +42,12 @@ export interface SearchBenchmarkBlock {
   };
 }
 
-/** Compact per-search stats attached to MCP `search` responses (agent-facing). */
+/**
+ * Compact per-search stats appended to MCP `search` / `locate` responses.
+ * `miru_tok` is the agent-facing MCP text body for that tool (search also adds
+ * one expand body for workflow vs grep+read). Not JSON scaffolding, not the
+ * trailing `{"benchmark":...}` line.
+ */
 export interface AgentBenchmarkSummary {
   save_pct: number;
   miru_tok: number;
@@ -51,6 +56,11 @@ export interface AgentBenchmarkSummary {
   rank1: boolean;
   /** Present only when non-empty; capped at 3 paths. */
   miru_only?: string[];
+  /**
+   * Search only: tokens of the search MCP text body alone (before expand).
+   * `miru_tok` = search_tok + expand body when present.
+   */
+  search_tok?: number;
 }
 
 /** Compact cumulative rollup for MCP `read_benchmark` (agent-facing). */

package/src/help.ts

@@ -165,8 +165,9 @@ export function printCommandHelp(command: string): void {
       writeStdout("Override path with MIRU_BENCHMARK_HISTORY_PATH. Append-only JSONL of savings.");
       writeStdout("Repo paths in the report are plaintext — use `clear` on shared machines.");
       writeStdout("");
-      writeStdout("Savings compare Miru workflow tokens to a Grep baseline");
-      writeStdout("(rg search + read of the top matched file), not the agent's full tool chain.");
+      writeStdout("Savings compare Miru MCP response tokens (search text + expand text)");
+      writeStdout("to a Grep baseline (rg search + read of the top matched file),");
+      writeStdout("not bare chunk content and not the agent's full tool chain.");
       writeStdout("Local paths only — git URL repos skip comparison with benchmark_skipped.");
       writeStdout("");
       return;

package/src/installer/search-policy.ts

@@ -127,7 +127,10 @@ export const MCP_SERVER_INSTRUCTIONS =
 
 export const MCP_BENCHMARK_SERVER_INSTRUCTIONS =
   `${MCP_SERVER_INSTRUCTIONS} ` +
-  "BENCHMARK MODE: each `search` and `locate` includes compact `benchmark` {save_pct,miru_tok,grep_tok,saved_tok,rank1}. " +
+  "BENCHMARK MODE: each `search` and `locate` ends with a compact JSON line " +
+  '`{"benchmark":{save_pct,miru_tok,grep_tok,saved_tok,rank1[,search_tok,miru_only]}}`. ' +
+  "Results stay plain text. For search, `miru_tok` is search MCP text + one expand (workflow vs grep+read); " +
+  "`search_tok` is this search body alone. " +
   "Call `read_benchmark` for cumulative totals across both. Do not narrate benchmark stats unless the user asks. " +
   "To leave benchmark mode, tell the user to run `miru benchmark off` and restart the agent.";
 

package/src/mcp/format-text.ts

@@ -0,0 +1,67 @@
+import type { ExpandResults } from "../utils.ts";
+
+/** Plain-text rendering of `formatResults()` output — same info as the JSON shape, no scaffolding. */
+export function formatResultsText(payload: {
+  query: string;
+  results: Record<string, unknown>[];
+}): string {
+  if (payload.results.length === 0) {
+    return "No results found.";
+  }
+
+  const blocks = payload.results.map((result) => {
+    const chunk = result.chunk as Record<string, unknown>;
+    const startLine = chunk.truncated ? chunk.full_start_line : chunk.start_line;
+    const endLine = chunk.truncated ? chunk.full_end_line : chunk.end_line;
+    const truncatedNote = chunk.truncated ? " [truncated: call expand for full chunk]" : "";
+    const header = `${chunk.file_path}:${startLine}-${endLine}${truncatedNote}`;
+    return `${header}\n${chunk.content}`;
+  });
+
+  return blocks.join("\n\n");
+}
+
+/** Plain-text rendering of `formatLiteralLocate()` output. */
+export function formatLiteralLocateText(payload: Record<string, unknown>): string {
+  const label =
+    (payload.literals as string[] | undefined)?.join(" | ") ?? (payload.literal as string);
+  const n = payload.n as number;
+  const files = payload.files as number;
+  const truncatedNote = payload.truncated ? " (truncated — pass a narrower include/exclude)" : "";
+  const header = `"${label}": ${n} match${n === 1 ? "" : "es"} across ${files} file${files === 1 ? "" : "s"}${truncatedNote}`;
+
+  const hits = payload.hits as
+    | Array<{ f: string; l: number; t?: string; ctx?: string[]; ctx_l?: number }>
+    | undefined;
+  if (!hits) {
+    return header;
+  }
+
+  const lines = [header, ""];
+  for (const hit of hits) {
+    lines.push(hit.t !== undefined ? `${hit.f}:${hit.l}: ${hit.t}` : `${hit.f}:${hit.l}`);
+    if (hit.ctx != null && hit.ctx_l !== undefined) {
+      const ctxStart = hit.ctx_l;
+      for (let i = 0; i < hit.ctx.length; i++) {
+        lines.push(`  ${ctxStart + i}: ${hit.ctx[i]}`);
+      }
+    }
+  }
+  return lines.join("\n");
+}
+
+/** Plain-text rendering of `formatExpandResults()` output. */
+export function formatExpandResultsText(payload: ExpandResults): string {
+  const anchorRange = payload.anchor
+    ? `${payload.anchor.start_line}-${payload.anchor.end_line}`
+    : null;
+  const header = `${payload.file_path} — ${payload.chunk_count} chunk${payload.chunk_count === 1 ? "" : "s"} around line ${payload.line}`;
+
+  const blocks = payload.chunks.map((chunk) => {
+    const range = `${chunk.start_line}-${chunk.end_line}`;
+    const isAnchor = anchorRange === range;
+    return `${range}${isAnchor ? " (anchor)" : ""}\n${chunk.content}`;
+  });
+
+  return `${header}\n\n${blocks.join("\n\n")}`;
+}

package/src/mcp/index-cache.ts

@@ -65,6 +65,11 @@ export function shouldIgnoreWatchPath(relativePath: string | null | undefined):
   return false;
 }
 
+/**
+ * Session cache of MiruIndex instances. Keeps them fresh by reconciling
+ * mtimes on load (`checkAndQueueStaleFiles`) and applying incremental
+ * updates from fs.watch (`flushFileUpdates` / `applyFileChanges`).
+ */
 export class IndexCache {
   private readonly content: ContentType[];
   private readonly defaultRef: string | null;

package/src/mcp/server.ts

@@ -1,13 +1,14 @@
 import * as z from "zod";
 import packageJson from "../../package.json";
-import { attachSearchBenchmark, benchmarkSearchComparison } from "../benchmark/compare.ts";
+import { benchmarkSearchComparison, toAgentBenchmarkSummary } from "../benchmark/compare.ts";
 import {
   appendBenchmarkQuery,
   readBenchmarkRollup,
   recordFromAgentSummary,
   recordFromBenchmark,
 } from "../benchmark/history.ts";
-import { attachLocateBenchmark, benchmarkLocateComparison } from "../benchmark/locate-compare.ts";
+import { benchmarkLocateComparison } from "../benchmark/locate-compare.ts";
+import { appendAgentBenchmark } from "../benchmark/summary.ts";
 import {
   MCP_BENCHMARK_SERVER_INSTRUCTIONS,
   MCP_EXPAND_TOOL_DESCRIPTION,
@@ -32,6 +33,11 @@ import {
   MAX_MCP_TOP_K,
   resolveChunk,
 } from "../utils.ts";
+import {
+  formatExpandResultsText,
+  formatLiteralLocateText,
+  formatResultsText,
+} from "./format-text.ts";
 import { getIndexForRepo, type IndexCache, toolText } from "./index-cache.ts";
 import { MiruMcpServer } from "./runtime.ts";
 
@@ -43,14 +49,11 @@ const REPO_DESCRIPTION =
 const BENCHMARK_LOCAL_ONLY_NOTE =
   "Benchmark comparisons require a local repo path; git URL repos are skipped.";
 
-function withBenchmarkSkipped<T extends Record<string, unknown>>(
-  payload: T,
-): T & { benchmark_skipped: "local_repo_only"; note: string } {
-  return {
-    ...payload,
+function withBenchmarkSkippedNote(body: string): string {
+  return `${body}\n\n${JSON.stringify({
     benchmark_skipped: "local_repo_only",
     note: BENCHMARK_LOCAL_ONLY_NOTE,
-  };
+  })}`;
 }
 
 export function createMcpServer(
@@ -108,20 +111,18 @@ export function createMcpServer(
           });
           const results = comparison.results;
           if (results.length === 0) {
-            return toolText(JSON.stringify({ error: "No results found." }));
+            return toolText("No results found.");
           }
           try {
             await appendBenchmarkQuery(recordFromBenchmark(repoRoot, comparison.benchmark));
           } catch {
             // History is best-effort; never fail the search on persist errors.
           }
+          const body = formatResultsText(
+            formatResults(query, results, { repoRoot, snippet: true }),
+          );
           return toolText(
-            JSON.stringify(
-              attachSearchBenchmark(
-                formatResults(query, results, { repoRoot, snippet: true }),
-                comparison.benchmark,
-              ),
-            ),
+            appendAgentBenchmark(body, toAgentBenchmarkSummary(comparison.benchmark)),
           );
         }
 
@@ -130,13 +131,14 @@ export function createMcpServer(
           results = dedupeResultsByFile(results);
         }
         if (results.length === 0) {
-          return toolText(JSON.stringify({ error: "No results found." }));
+          return toolText("No results found.");
         }
         const payload = formatResults(query, results, { repoRoot, snippet: true });
+        const body = formatResultsText(payload);
         if (benchmark && !repoRoot) {
-          return toolText(JSON.stringify(withBenchmarkSkipped(payload)));
+          return toolText(withBenchmarkSkippedNote(body));
         }
-        return toolText(JSON.stringify(payload));
+        return toolText(body);
       } catch (err) {
         return toolText(err instanceof Error ? err.message : String(err));
       }
@@ -212,18 +214,18 @@ export function createMcpServer(
             } catch {
               // History is best-effort; never fail locate on persist errors.
             }
-            return toolText(
-              JSON.stringify(attachLocateBenchmark(comparison.payload, comparison.benchmark)),
-            );
+            const body = formatLiteralLocateText(comparison.payload);
+            return toolText(appendAgentBenchmark(body, comparison.benchmark));
           }
         }
 
         const result = index.locateLiteral(literal, locateOpts);
         const payload = formatLiteralLocate(result);
+        const body = formatLiteralLocateText(payload);
         if (benchmark && !localRepoRoot(repo)) {
-          return toolText(JSON.stringify(withBenchmarkSkipped(payload)));
+          return toolText(withBenchmarkSkippedNote(body));
         }
-        return toolText(JSON.stringify(payload));
+        return toolText(body);
       } catch (err) {
         return toolText(err instanceof Error ? err.message : String(err));
       }
@@ -277,7 +279,7 @@ export function createMcpServer(
           );
         }
         return toolText(
-          JSON.stringify(
+          formatExpandResultsText(
             formatExpandResults(filePath, anchorLine, anchor, expanded, {
               repoRoot,
               before: beforeCount,
@@ -327,12 +329,10 @@ export function createMcpServer(
         }
         const results = await index.findRelated(chunk, clampMcpTopK(topK));
         if (results.length === 0) {
-          return toolText(
-            JSON.stringify({ error: `No related chunks found for ${filePath}:${anchorLine}.` }),
-          );
+          return toolText(`No related chunks found for ${filePath}:${anchorLine}.`);
         }
         return toolText(
-          JSON.stringify(
+          formatResultsText(
             formatResults(`Chunks related to ${filePath}:${anchorLine}`, results, {
               repoRoot,
               snippet: true,