@takara-ai/miru-code 1.1.3 → 1.2.1

package/src/installer/config.ts

@@ -6,6 +6,11 @@ const CODEX_MCP_BLOCK = `[mcp_servers.miru]
 command = "bunx"
 args = ["@takara-ai/miru-code"]
 `;
+/** Same Codex block with `--benchmark` preserved across reinstall. */
+const CODEX_MCP_BLOCK_BENCHMARK = `[mcp_servers.miru]
+command = "bunx"
+args = ["@takara-ai/miru-code", "--benchmark"]
+`;
 
 /** Strip line and block comments so JSONC configs can be parsed. */
 export function stripJsonComments(text: string): string {
@@ -487,12 +492,19 @@ export async function mergeTomlBlock(path: string): Promise<InstallAction> {
   const existed = await Bun.file(path).exists();
   const existing = existed ? await Bun.file(path).text() : "";
 
-  if (existing.includes(CODEX_MCP_BLOCK.trim())) {
+  const defaultBlock = CODEX_MCP_BLOCK.trim();
+  const benchmarkBlock = CODEX_MCP_BLOCK_BENCHMARK.trim();
+  if (existing.includes(defaultBlock) || existing.includes(benchmarkBlock)) {
     return "unchanged";
   }
 
+  const preserveBenchmark =
+    existing.includes(CODEX_MCP_HEADER) &&
+    (existing.includes('"--benchmark"') || existing.includes("'--benchmark'"));
+  const block = preserveBenchmark ? CODEX_MCP_BLOCK_BENCHMARK : CODEX_MCP_BLOCK;
+
   const base = stripTomlSection(existing, CODEX_MCP_HEADER).replace(/\n+$/, "");
-  const next = base.length > 0 ? `${base}\n\n${CODEX_MCP_BLOCK}` : CODEX_MCP_BLOCK;
+  const next = base.length > 0 ? `${base}\n\n${block}` : block;
   await Bun.write(path, next.endsWith("\n") ? next : `${next}\n`);
   return existed ? "updated" : "created";
 }

package/src/installer/hooks/opencode-plugin.ts

@@ -3,28 +3,12 @@
  * Installed to ~/.config/opencode/plugins/miru-search-guard.ts
  */
 
-const REDIRECT = "Use Miru MCP search (repo = project root) instead of grep/glob/bash exploration.";
+const REDIRECT =
+  "Use Miru MCP (repo = project root): `locate` for exact literals, `search` for meaning-based questions — not grep/glob/bash exploration.";
 
 const GREP_TOOLS = new Set(["grep", "glob", "codesearch", "codebase_search", "search"]);
 const SHELL_TOOLS = new Set(["bash", "shell", "sh"]);
 
-function isLiteral(pattern: string): boolean {
-  const trimmed = pattern.trim();
-  if (!trimmed) {
-    return false;
-  }
-  if (/^[`'"][^`'"]+[`'"]$/.test(trimmed)) {
-    return true;
-  }
-  if (/^[A-Z][A-Z0-9_]{2,}$/.test(trimmed)) {
-    return true;
-  }
-  if (/^[a-zA-Z_][a-zA-Z0-9_.]*$/.test(trimmed) && trimmed.length <= 48) {
-    return true;
-  }
-  return false;
-}
-
 function isExplorationShell(command: string): boolean {
   const cmd = command.trim();
   if (!cmd) {
@@ -43,9 +27,11 @@ function shouldBlock(tool: string, args: Record<string, unknown>): boolean {
   if (name.includes("miru")) {
     return false;
   }
+  if (name === "glob") {
+    return true;
+  }
   if (GREP_TOOLS.has(name)) {
-    const pattern = String(args.pattern ?? args.query ?? args.regex ?? args.needle ?? "");
-    return !isLiteral(pattern);
+    return true;
   }
   if (SHELL_TOOLS.has(name)) {
     const command = String(args.command ?? args.cmd ?? "");

package/src/installer/hooks/search-guard.ts

@@ -2,7 +2,7 @@ import { SEARCH_GUARD_EXPAND_HINT } from "../search-policy.ts";
 
 const REDIRECT_PREFIX =
   "Use Miru MCP instead of built-in search tools (pass project root as `repo`). " +
-  "Grep/Glob/Shell are only for exact literal confirmation or non-code tasks.";
+  "Prefer Miru `locate` for exact literals and `search` for meaning-based questions.";
 
 const MIRU_TOOL_RE = /miru/i;
 
@@ -121,6 +121,9 @@ export function searchGuardBlockReason(
   toolInput: Record<string, unknown>,
 ): string {
   const query = suggestedMiruQuery(toolName, toolInput);
+  if (GREP_TOOL_RE.test(toolName) && isLiteralGrepPattern(grepPatternFromInput(toolInput))) {
+    return `${REDIRECT_PREFIX} Try Miru \`locate\` with literal "${query.replace(/^['"`]|['"`]$/g, "")}". ${SEARCH_GUARD_EXPAND_HINT}`;
+  }
   return `${REDIRECT_PREFIX} Try Miru \`search\` with query "${query}". ${SEARCH_GUARD_EXPAND_HINT}`;
 }
 
@@ -166,10 +169,6 @@ export function evaluateSearchGuard(payload: HookPayload): GuardDecision {
   }
 
   if (GREP_TOOL_RE.test(toolName)) {
-    const pattern = grepPatternFromInput(toolInput);
-    if (isLiteralGrepPattern(pattern)) {
-      return { block: false, reason: "" };
-    }
     return { block: true, reason: searchGuardBlockReason(toolName, toolInput) };
   }
 

package/src/installer/installer.ts

@@ -1,6 +1,7 @@
 import { unlink } from "node:fs/promises";
 import { loadAgentTemplate } from "../agents.ts";
-import { brandTitle, dim, divider, green, hint, success, writeStdout } from "../cli-ui.ts";
+import { clearBenchmarkHistory } from "../benchmark/history.ts";
+import { brandTitle, dim, divider, green, hint, info, success, writeStdout } from "../cli-ui.ts";
 import { ensureCredentials } from "../setup.ts";
 import {
   AGENT_TARGETS,
@@ -10,6 +11,7 @@ import {
   type InstallMode,
   isAgentDetected,
 } from "./agents.ts";
+import { withPreservedBenchmarkFlag } from "./benchmark-mode.ts";
 import {
   mergeJsonMember,
   mergeTomlBlock,
@@ -17,6 +19,7 @@ import {
   removeMarked,
   removeTomlBlock,
   replaceOrAppendMarked,
+  stripJsonComments,
 } from "./config.ts";
 import { mergeHooks, removeHooks } from "./hooks/install.ts";
 import { promptConfirm, promptMultiSelect, requireInteractiveTerminal } from "./prompt.ts";
@@ -54,6 +57,33 @@ const ACTION_ICON: Partial<Record<InstallAction, string>> = {
   error: dim("✗"),
 };
 
+async function readExistingJsonMcpEntry(
+  path: string,
+  sectionKey: string,
+  memberKey: string,
+): Promise<Record<string, unknown> | null> {
+  if (!(await Bun.file(path).exists())) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(stripJsonComments(await Bun.file(path).text())) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return null;
+    }
+    const section = (parsed as Record<string, unknown>)[sectionKey];
+    if (!section || typeof section !== "object" || Array.isArray(section)) {
+      return null;
+    }
+    const entry = (section as Record<string, unknown>)[memberKey];
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      return null;
+    }
+    return entry as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
 async function applyMcp(agent: AgentTarget, mode: InstallMode): Promise<WriteResult | null> {
   const mcp = agent.mcp;
   if (!mcp) {
@@ -66,10 +96,14 @@ async function applyMcp(agent: AgentTarget, mode: InstallMode): Promise<WriteRes
     return { path: mcp.path, action };
   }
 
-  const action =
-    mode === "install"
-      ? await mergeJsonMember(mcp.path, mcp.key, mcp.memberKey, mcp.entry)
-      : await removeJsonMember(mcp.path, mcp.key, mcp.memberKey);
+  if (mode !== "install") {
+    const action = await removeJsonMember(mcp.path, mcp.key, mcp.memberKey);
+    return { path: mcp.path, action };
+  }
+
+  const existing = await readExistingJsonMcpEntry(mcp.path, mcp.key, mcp.memberKey);
+  const entry = withPreservedBenchmarkFlag(mcp.entry, existing);
+  const action = await mergeJsonMember(mcp.path, mcp.key, mcp.memberKey, entry);
   return { path: mcp.path, action };
 }
 
@@ -235,6 +269,18 @@ async function apply(
   writeStdout("");
 }
 
+/** Local Miru state cleaned up during uninstall (global, not per-agent). */
+export async function removeUninstallLocalData(): Promise<{
+  benchmarkHistoryCleared: boolean;
+  benchmarkHistoryPath: string;
+}> {
+  const result = await clearBenchmarkHistory();
+  return {
+    benchmarkHistoryCleared: result.cleared,
+    benchmarkHistoryPath: result.path,
+  };
+}
+
 export async function runInstaller(mode: InstallMode): Promise<void> {
   const install = mode === "install";
   requireInteractiveTerminal(`miru ${mode}`);
@@ -297,6 +343,13 @@ export async function runInstaller(mode: InstallMode): Promise<void> {
 
   await apply(mode, chosenAgents, chosenIntegrations);
 
+  if (!install) {
+    const local = await removeUninstallLocalData();
+    if (local.benchmarkHistoryCleared) {
+      info(`Removed benchmark report ${local.benchmarkHistoryPath}`);
+    }
+  }
+
   success(install ? "Done. Restart agents to apply changes." : "Done. Configuration removed.");
   writeStdout("");
 }

package/src/installer/search-policy.ts

@@ -18,7 +18,7 @@ export function buildSearchPolicyTable(native: NativeToolNames): string {
 | Same file, more context | Miru MCP \`expand\` on \`truncated: true\` | Re-search, ${native.read} whole file |
 | Similar code elsewhere | Miru MCP \`find_related\` | ${native.grep} chains |
 | Search docs or config | Miru \`search\` | ${native.grep} README paths |
-| Exact literal string in a file? | ${native.grep} | Miru |
+| Exact literal string in a file? | Miru MCP \`locate\` | ${native.grep}, Miru \`search\` |
 | Edit a known file:line | ${native.read} (after Miru found it) | ${native.read}-before-search |`;
 }
 
@@ -29,6 +29,7 @@ ${SNIPPET_GUIDANCE}
 
 Use Miru MCP tools:
 - \`search\` — one call per question; pass project root as \`repo\`
+- \`locate\` — exact substring (env var, symbol, error code); prefer \`mode=count\` or \`locations\`
 - \`expand\` — more context in the same file when \`truncated: true\` (\`file_path\` + \`anchor_line\`)
 - \`find_related\` — similar code in other files (hits may also be snippets; use \`expand\` if truncated)
 
@@ -38,7 +39,6 @@ Stop rules:
 - ${native.read} is for editing a path Miru already gave you, not for exploration
 
 Native tools are allowed ONLY when:
-- confirming an exact literal string (env var name, error code, quoted text)
 - reading a file you already located via Miru, to edit it
 - searching outside the indexed repo
 
@@ -49,15 +49,17 @@ export function buildMcpWorkflow(native: NativeToolNames): string {
   return `### MCP workflow
 
 1. Call \`search\` with \`repo\` set to the project root (local path or https:// git URL).
-2. If a hit has \`truncated: true\`, call \`expand\` with \`file_path\` and \`anchor_line\`.
-3. Use \`find_related\` to trace similar code in other files — not for more context in the same file.
-4. ${native.read} via \`absolute_path\` only when editing or when \`expand\` still lacks context.`;
+2. For exact literals, call \`locate\` (prefer \`mode=count\` or \`locations\`).
+3. If a hit has \`truncated: true\`, call \`expand\` with \`file_path\` and \`anchor_line\`.
+4. Use \`find_related\` to trace similar code in other files — not for more context in the same file.
+5. ${native.read} via \`absolute_path\` only when editing or when \`expand\` still lacks context.`;
 }
 
 const CLI_FALLBACK = `### CLI fallback (no MCP in this session)
 
 \`\`\`bash
 miru search "authentication flow" .
+miru locate DATABASE_URL . --mode locations
 miru expand src/auth.ts 42 .
 miru find-related src/auth.ts 42 .
 \`\`\`
@@ -65,7 +67,7 @@ miru find-related src/auth.ts 42 .
 If \`miru\` is not on \`$PATH\`, use \`bunx @takara-ai/miru-code\`.`;
 
 export function buildSubagentBody(native: NativeToolNames): string {
-  return `When Miru MCP is available, use MCP \`search\`, \`expand\`, and \`find_related\` — not ${native.explorationDenied} for exploration.
+  return `When Miru MCP is available, use MCP \`search\`, \`locate\`, \`expand\`, and \`find_related\` — not ${native.explorationDenied} for exploration.
 
 ${buildSearchPolicyBody(native)}
 
@@ -108,7 +110,7 @@ alwaysApply: true
 
 ${SEARCH_POLICY_BODY}
 
-When Miru MCP is connected, call \`search\` once per question. On \`truncated: true\`, call \`expand\` with \`file_path\` and \`anchor_line\`. Never use Cursor SemanticSearch or Grep for codebase questions unless confirming an exact literal.`;
+When Miru MCP is connected, call \`search\` once per question. On \`truncated: true\`, call \`expand\` with \`file_path\` and \`anchor_line\`. Use \`locate\` for exact literals — not Grep. Never use Cursor SemanticSearch for codebase questions.`;
 
 export const SUBAGENT_BODY = buildSubagentBody(DEFAULT_NATIVE_TOOLS);
 
@@ -119,15 +121,28 @@ export const MCP_SERVER_INSTRUCTIONS =
   "Workflow: (1) `search` once per question — do NOT re-search with paraphrases. " +
   "(2) On `truncated: true`, call `expand` with `file_path` and `anchor_line` — do NOT read the whole file. " +
   "(3) `find_related` traces similar code in other files, not more context in the same file. " +
+  "(4) `locate` finds exact substrings (env vars, symbols, error codes) — prefer over Grep; use mode=count or locations when possible. " +
   "Always pass the project root as `repo`. Local repos return `absolute_path` on each hit — use Read only to edit. " +
-  "Native grep is only for confirming a known exact literal (env var name, quoted string) or files outside the indexed repo.";
+  "Native Grep/Glob only outside the indexed repo or for non-code tasks.";
+
+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}. " +
+  "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.";
 
 export const MCP_SEARCH_TOOL_DESCRIPTION =
   "Your default search for all code search queries in this indexed repo — the best, fastest, and cheapest way to find code; better than any other tool. " +
   "Returns compact snippets (~±15 lines). One call per question is usually enough. " +
-  "Built-in grep is only when you already have an exact literal string to confirm. " +
+  "For exact literals (env vars, symbols, error codes), use `locate` instead. " +
   "When a hit has `truncated: true`, call `expand` with `file_path` and `anchor_line` — not re-search or Read.";
 
+export const MCP_LOCATE_TOOL_DESCRIPTION =
+  "Exact substring locator over the Miru index. Use for known literals (env vars, symbols, error codes, quoted text) — not meaning-based questions (`search`). " +
+  "Returns ALL matches by default as compact {n,files,hits} — do NOT fall back to Grep/rg when n is large. " +
+  "Prefer mode=locations (or count for totals only); use lines when you need matching line text. " +
+  "Optional `limit` only if you intentionally want a sample. In benchmark mode, includes compact token savings vs agent Grep.";
+
 export const MCP_EXPAND_TOOL_DESCRIPTION =
   "More context in the SAME file as a search hit. Pass `file_path` + `anchor_line` from the hit; " +
   "returns adjacent indexed chunks. Use when `truncated: true` — NOT for similar code in other files (use find_related). " +
@@ -137,5 +152,9 @@ export const MCP_FIND_RELATED_TOOL_DESCRIPTION =
   "Find code similar to a file:line in OTHER parts of the codebase. Results may be snippets; use `expand` when `truncated: true`. " +
   "For more context in the same file, use `expand` instead.";
 
+export const MCP_READ_BENCHMARK_TOOL_DESCRIPTION =
+  "Cumulative Miru vs Grep token savings from saved `search` and `locate` calls. Returns compact totals {n,saved,save_pct,miru,grep}. " +
+  "Do not call unless the user asks about savings.";
+
 export const SEARCH_GUARD_EXPAND_HINT =
   "If a hit has `truncated: true`, call `expand` with `file_path` and `anchor_line` — do not re-search or read the whole file.";

package/src/literal.ts

@@ -0,0 +1,139 @@
+/** Exact literal location over already-indexed Miru chunks (no disk re-walk). */
+
+import type { Chunk } from "./types.ts";
+
+export type LiteralMode = "count" | "locations" | "lines";
+
+export interface LiteralHit {
+  file_path: string;
+  line: number;
+  /** Present only in `lines` mode. */
+  text?: string;
+}
+
+export interface LiteralLocateResult {
+  literal: string;
+  mode: LiteralMode;
+  /** Total unique file:line matches. */
+  n: number;
+  /** Unique files with at least one match. */
+  files: number;
+  /** True only when an explicit `limit` cut the hit list short. */
+  truncated: boolean;
+  hits: LiteralHit[];
+}
+
+export interface LiteralLocateOptions {
+  mode?: LiteralMode;
+  /**
+   * Optional cap on returned hits (ignored for `count`).
+   * Omit for all matches — agents must not fall back to Grep when truncated.
+   */
+  limit?: number;
+  ignore_case?: boolean;
+}
+
+function resolveLimit(limit: number | undefined): number | null {
+  if (limit == null || !Number.isFinite(limit)) {
+    return null;
+  }
+  return Math.max(1, Math.floor(limit));
+}
+
+function includesLiteral(haystack: string, needle: string, ignoreCase: boolean): boolean {
+  if (!ignoreCase) {
+    return haystack.includes(needle);
+  }
+  return haystack.toLowerCase().includes(needle.toLowerCase());
+}
+
+/**
+ * Scan indexed chunks for an exact substring. Dedupes by file:line when chunks overlap.
+ * Only covers indexed content (same corpus as `search` / `expand`).
+ * Returns every match unless `limit` is set.
+ */
+export function locateLiteral(
+  chunks: readonly Chunk[],
+  literal: string,
+  options: LiteralLocateOptions = {},
+): LiteralLocateResult {
+  const needle = literal;
+  const mode = options.mode ?? "lines";
+  const ignoreCase = options.ignore_case === true;
+  const limit = resolveLimit(options.limit);
+
+  if (!needle) {
+    return { literal: needle, mode, n: 0, files: 0, truncated: false, hits: [] };
+  }
+
+  const seen = new Set<string>();
+  const fileSet = new Set<string>();
+  const hits: LiteralHit[] = [];
+  let n = 0;
+
+  for (const chunk of chunks) {
+    if (!includesLiteral(chunk.content, needle, ignoreCase)) {
+      continue;
+    }
+    const lines = chunk.content.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+      const lineText = lines[i] ?? "";
+      if (!includesLiteral(lineText, needle, ignoreCase)) {
+        continue;
+      }
+      const line = chunk.start_line + i;
+      const key = `${chunk.file_path}:${line}`;
+      if (seen.has(key)) {
+        continue;
+      }
+      seen.add(key);
+      fileSet.add(chunk.file_path);
+      n += 1;
+      if (mode === "count") {
+        continue;
+      }
+      if (limit != null && hits.length >= limit) {
+        continue;
+      }
+      const hit: LiteralHit = { file_path: chunk.file_path, line };
+      if (mode === "lines") {
+        hit.text = lineText;
+      }
+      hits.push(hit);
+    }
+  }
+
+  return {
+    literal: needle,
+    mode,
+    n,
+    files: fileSet.size,
+    truncated: mode !== "count" && limit != null && n > hits.length,
+    hits: mode === "count" ? [] : hits,
+  };
+}
+
+/** Compact agent-facing JSON (minimal keys). */
+export function formatLiteralLocate(result: LiteralLocateResult): Record<string, unknown> {
+  const base: Record<string, unknown> = {
+    literal: result.literal,
+    mode: result.mode,
+    n: result.n,
+    files: result.files,
+  };
+
+  if (result.mode === "count") {
+    return base;
+  }
+
+  if (result.truncated) {
+    base.truncated = true;
+  }
+  base.hits = result.hits.map((hit) => {
+    if (hit.text !== undefined) {
+      return { f: hit.file_path, l: hit.line, t: hit.text };
+    }
+    return { f: hit.file_path, l: hit.line };
+  });
+  return base;
+}

package/src/mcp/index-cache.ts

@@ -4,7 +4,7 @@ import { walkFiles } from "../index/file-walker.ts";
 import { getExtensions } from "../index/files.ts";
 import { normalizeRelativePath, relativePathFromRoot } from "../index/incremental.ts";
 import { MiruIndex } from "../miru-index.ts";
-import type { ContentType } from "../types.ts";
+import { type ContentType, defaultContentTypes } from "../types.ts";
 import {
   computeSourceCacheKey,
   isAllowedRepoSource,
@@ -71,7 +71,7 @@ export class IndexCache {
   private readonly entries = new Map<string, CacheEntry>();
   readonly watchers = new Map<string, WatcherHandle>();
 
-  constructor(content: ContentType[] = ["code"], defaultRef: string | null = null) {
+  constructor(content: ContentType[] = defaultContentTypes(), defaultRef: string | null = null) {
     this.content = content;
     this.defaultRef = defaultRef;
   }

package/src/mcp/serve.ts

@@ -1,4 +1,4 @@
-import type { ContentType } from "../types.ts";
+import { type ContentType, defaultContentTypes } from "../types.ts";
 import { IndexCache } from "./index-cache.ts";
 import { createMcpServer } from "./server.ts";
 import { StdioTransport } from "./stdio.ts";
@@ -6,9 +6,10 @@ import { StdioTransport } from "./stdio.ts";
 export async function serveMcp(options: {
   ref?: string | null;
   content?: ContentType[];
+  benchmark?: boolean;
 }): Promise<void> {
-  const cache = new IndexCache(options.content ?? ["code"], options.ref ?? null);
-  const server = createMcpServer(cache);
+  const cache = new IndexCache(options.content ?? defaultContentTypes(), options.ref ?? null);
+  const server = createMcpServer(cache, { benchmark: options.benchmark ?? false });
   const transport = new StdioTransport();
   await server.connect(transport);
 }