@takara-ai/miru-code 0.4.11 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@takara-ai/miru-code",
-  "version": "0.4.11",
+  "version": "0.5.0",
   "description": "Miru (見る) — hybrid code search for agents. Bun, TypeScript, Takara embeddings.",
   "type": "module",
   "license": "MIT",
@@ -50,6 +50,9 @@
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "prepublishOnly": "bun run typecheck && bun test",
+    "benchmark:ab": "bun run scripts/search-ab-local.ts",
+    "benchmark:ab-multi": "bun run scripts/search-ab-multi.ts",
+    "benchmark:recall": "bun run scripts/benchmark-recall-tokens.ts",
     "benchmark:quality": "bun run scripts/benchmark-quality.ts",
     "benchmark:quantization": "bun run scripts/benchmark-quantization.ts"
   },

package/src/agents/claude.md

@@ -3,30 +3,3 @@ name: miru-code
 description: Code search via Miru MCP. Use search, expand, and find_related. DO NOT use Grep, Glob, or Read for exploration when Miru MCP is available.
 tools: Bash, Read
 ---
-
-When Miru MCP is available, use MCP `search`, `expand`, and `find_related` — not Grep, Glob, or Read-for-exploration.
-
-| Task | Tool |
-|------|------|
-| How/where/what handles X? | Miru `search` (once) |
-| Same file, more context | Miru `expand` |
-| Similar implementations | Miru `find_related` |
-| Exact literal confirmation | Grep |
-| Edit a located file | Read |
-
-### MCP workflow
-
-1. Call `search` with `repo` set to the project root; follow `guidance` in the response.
-2. If context is cut off, call `expand` with the hit's `file_path` and `line`.
-3. Use `find_related` for similar code in other files — not for same-file context.
-4. Read files only to edit or when `expand` still lacks context.
-
-### CLI fallback
-
-```bash
-miru search "authentication flow" .
-miru expand src/auth.ts 42 .
-miru find-related src/auth.ts 42 .
-```
-
-If `miru` is not on `$PATH`, use `bunx @takara-ai/miru-code`.

package/src/agents/copilot.md

@@ -2,15 +2,3 @@
 name: miru-code
 description: Code search via Miru MCP. Use search, expand, and find_related instead of grep_search or codebase_search when Miru is connected.
 ---
-
-When Miru MCP is available, use `search`, `expand`, and `find_related` instead of `grep_search`, `codebase_search`, or broad file reads.
-
-| Task | Tool |
-|------|------|
-| How/where/what handles X? | Miru `search` (once; follow `guidance`) |
-| Same file, more context | Miru `expand` |
-| Similar implementations | Miru `find_related` |
-| Exact literal confirmation | grep_search |
-| Edit a located file | read_file |
-
-Pass project root as `repo` on every MCP call.

package/src/agents/cursor.md

@@ -2,29 +2,3 @@
 name: miru-code
 description: Code search via Miru MCP. Use search, expand, and find_related. DO NOT use Grep, Glob, or SemanticSearch when Miru MCP is available.
 ---
-
-Use Miru MCP tools when connected:
-
-- `search` — one call per question; always pass project root as `repo`; read `guidance` in the response
-- `expand` — adjacent chunks in the same file when a hit looks truncated (`file_path` + `line`)
-- `find_related` — similar code in other files after a search hit
-
-Do not re-search with paraphrases when `guidance.sufficient` is true. Do not read whole files for exploration.
-
-| Task | Tool |
-|------|------|
-| How/where/what handles X? | Miru `search` (once) |
-| Same file, more context | Miru `expand` |
-| Similar implementations | Miru `find_related` |
-| Exact literal confirmation | Grep |
-| Edit a located file | Read |
-
-CLI fallback when MCP is unavailable:
-
-```bash
-miru search "authentication flow" .
-miru expand src/auth.ts 42 .
-miru find-related src/auth.ts 42 .
-```
-
-If `miru` is not on `$PATH`, use `bunx @takara-ai/miru-code`.

package/src/agents/gemini.md

@@ -2,17 +2,3 @@
 name: miru-code
 description: Code search via Miru MCP. Use search, expand, and find_related instead of grep_search or read_file for exploration.
 ---
-
-When Miru MCP is available, use `search`, `expand`, and `find_related` instead of `grep_search`, `glob`, or `read_file` for codebase exploration.
-
-| Task | Tool |
-|------|------|
-| How/where/what handles X? | Miru `search` (once; follow `guidance`) |
-| Same file, more context | Miru `expand` |
-| Similar implementations | Miru `find_related` |
-| Exact literal confirmation | grep_search |
-| Edit a located file | read_file |
-
-Pass project root as `repo` on every MCP call. Do not re-search when `guidance.sufficient` is true.
-
-CLI fallback: `miru search "query" .` or `bunx @takara-ai/miru-code search "query" .`

package/src/agents/kiro.md

@@ -2,9 +2,3 @@
 name: miru-code
 description: Code search via Miru MCP. Use search, expand, and find_related for codebase exploration instead of built-in grep or file search.
 ---
-
-When Miru MCP is available, use `search`, `expand`, and `find_related` before any built-in search or broad file reads.
-
-Pass project root as `repo`. Follow `guidance` in search responses. Use `expand` for truncated hits in the same file. Use Grep only for exact literal confirmation.
-
-CLI fallback: `miru search "query" .`

package/src/agents/opencode.md

@@ -3,9 +3,3 @@ name: miru-code
 description: Code search via Miru MCP. Use search, expand, and find_related instead of grep or glob for exploration.
 mode: subagent
 ---
-
-When Miru MCP is available, use `search`, `expand`, and `find_related` instead of grep, glob, or read-for-exploration.
-
-Pass project root as `repo` on every MCP call. Follow `guidance` in search responses.
-
-CLI fallback: `miru search "query" .`

package/src/agents.ts

@@ -1,17 +1,56 @@
 import { mkdir, readFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import {
+  buildSubagentBody,
+  type NativeToolNames,
+} from "./installer/search-policy.ts";
 
 export type AgentId = "claude" | "copilot" | "cursor" | "gemini" | "kiro" | "opencode";
 
 const AGENTS_DIR = join(import.meta.dir, "agents");
 
+const AGENT_NATIVE_TOOLS: Record<AgentId, NativeToolNames> = {
+  claude: {
+    explorationDenied: "Grep, Glob, SemanticSearch, or Read",
+    grep: "Grep",
+    read: "Read",
+  },
+  cursor: {
+    explorationDenied: "Grep, Glob, SemanticSearch, or Read",
+    grep: "Grep",
+    read: "Read",
+  },
+  copilot: {
+    explorationDenied: "grep_search, codebase_search, glob, or read_file",
+    grep: "grep_search",
+    read: "read_file",
+  },
+  gemini: {
+    explorationDenied: "grep_search, glob, or read_file",
+    grep: "grep_search",
+    read: "read_file",
+  },
+  kiro: {
+    explorationDenied: "built-in grep, file search, or broad file reads",
+    grep: "Grep",
+    read: "Read",
+  },
+  opencode: {
+    explorationDenied: "grep, glob, or read-for-exploration",
+    grep: "grep",
+    read: "read",
+  },
+};
+
 export function agentDestination(agent: AgentId): string {
   const baseDir = agent === "copilot" ? ".github" : `.${agent}`;
   return join(baseDir, "agents", "miru-code.md");
 }
 
 export async function loadAgentTemplate(agent: AgentId): Promise<string> {
-  return readFile(join(AGENTS_DIR, `${agent}.md`), "utf-8");
+  const frontmatter = (await readFile(join(AGENTS_DIR, `${agent}.md`), "utf-8")).trim();
+  const body = buildSubagentBody(AGENT_NATIVE_TOOLS[agent]);
+  return `${frontmatter}\n\n${body}\n`;
 }
 
 export async function writeAgentFile(

package/src/index/create.ts

@@ -9,8 +9,10 @@ import { BM25Index } from "./bm25.ts";
 import { walkFiles } from "./file-walker.ts";
 import { detectLanguage, getExtensions, getFileStatus, readFileText } from "./files.ts";
 import type { SemanticIndex } from "./semantic-index.ts";
+import { loadRootEntryChunks } from "./entry-chunks.ts";
 import { enrichForBm25 } from "./sparse.ts";
 import { buildSemanticIndex } from "./vector-storage.ts";
+import { searchImprovementsEnabled } from "../ranking/features.ts";
 
 const DEFAULT_PIPELINE_EMBED_BATCH = 64;
 const DEFAULT_PIPELINE_EMBED_INFLIGHT = 8;
@@ -145,6 +147,17 @@ export async function createIndexFromPath(
     await Promise.race(runningFiles);
   }
 
+  if (searchImprovementsEnabled()) {
+    const entryChunks = await loadRootEntryChunks(
+      resolved,
+      displayRoot ? root : undefined,
+    );
+    if (entryChunks.length > 0) {
+      readyBySeq.set(fileSeq++, entryChunks);
+      flushReadySequentialChunks();
+    }
+  }
+
   flushReadySequentialChunks();
   await maybeScheduleEmbed(true);
   await Promise.all(embedPromises);

package/src/index/entry-chunks.ts

@@ -0,0 +1,71 @@
+import { join, relative } from "node:path";
+import type { Chunk } from "../types.ts";
+
+function indexedPath(absPath: string, repoRoot: string, displayRoot?: string): string {
+  if (displayRoot) {
+    return relative(displayRoot, absPath).replace(/\\/g, "/");
+  }
+  return absPath.replace(/\\/g, "/");
+}
+
+async function packageJsonEntryChunks(
+  absPath: string,
+  repoRoot: string,
+  displayRoot?: string,
+): Promise<Chunk[]> {
+  let pkg: Record<string, unknown>;
+  try {
+    pkg = JSON.parse(await Bun.file(absPath).text()) as Record<string, unknown>;
+  } catch {
+    return [];
+  }
+
+  const entryLines = ["[package entry]"];
+
+  const bin = pkg.bin;
+  if (typeof bin === "string") {
+    entryLines.push(`bin: ${bin}`);
+  } else if (bin && typeof bin === "object") {
+    for (const [name, target] of Object.entries(bin)) {
+      entryLines.push(`bin ${name}: ${String(target)}`);
+    }
+  }
+
+  if (typeof pkg.main === "string") {
+    entryLines.push(`main: ${pkg.main}`);
+  }
+
+  const types = pkg.types ?? pkg.typings;
+  if (typeof types === "string") {
+    entryLines.push(`types: ${types}`);
+  }
+
+  if (entryLines.length <= 1) {
+    return [];
+  }
+
+  const filePath = indexedPath(absPath, repoRoot, displayRoot);
+  const content = `${entryLines.join("\n")}\n`;
+
+  return [
+    {
+      content,
+      file_path: filePath,
+      start_line: 1,
+      end_line: entryLines.length,
+      language: "json",
+    },
+  ];
+}
+
+/** Synthetic chunks for root config entry points (bin/main) when indexing code repos. */
+export async function loadRootEntryChunks(
+  repoRoot: string,
+  displayRoot?: string,
+): Promise<Chunk[]> {
+  const pkgPath = join(repoRoot, "package.json");
+  if (!(await Bun.file(pkgPath).exists())) {
+    return [];
+  }
+  return packageJsonEntryChunks(pkgPath, repoRoot, displayRoot);
+}

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

@@ -1,3 +1,5 @@
+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.";
@@ -119,10 +121,7 @@ export function searchGuardBlockReason(
   toolInput: Record<string, unknown>,
 ): string {
   const query = suggestedMiruQuery(toolName, toolInput);
-  return (
-    `${REDIRECT_PREFIX} Try Miru \`search\` with query "${query}". ` +
-    "If the hit looks truncated, call `expand` on its file_path + line — do not re-search or read the whole file."
-  );
+  return `${REDIRECT_PREFIX} Try Miru \`search\` with query "${query}". ${SEARCH_GUARD_EXPAND_HINT}`;
 }
 
 /** Map host-specific stdin JSON into a common evaluation shape. */

package/src/installer/prompt.ts

@@ -15,11 +15,31 @@ const ESC = "\x1b";
 const HIDE_CURSOR = `${ESC}[?25l`;
 const SHOW_CURSOR = `${ESC}[?25h`;
 const CLEAR_LINE = `${ESC}[2K`;
+const CURSOR_START = `${ESC}[G`;
 
 function writeRaw(text: string): void {
   output.write(text);
 }
 
+function createFrameWriter(): (lines: string[]) => void {
+  let previousLineCount = 0;
+
+  return (lines: string[]) => {
+    if (previousLineCount > 0) {
+      writeRaw(`${ESC}[${previousLineCount}A${CURSOR_START}`);
+    }
+    writeRaw(`${CLEAR_LINE}${lines.join(`\n${CLEAR_LINE}`)}\n`);
+    const extra = previousLineCount - lines.length;
+    if (extra > 0) {
+      for (let i = 0; i < extra; i++) {
+        writeRaw(`${CLEAR_LINE}\n`);
+      }
+      writeRaw(`${ESC}[${extra}A${CURSOR_START}`);
+    }
+    previousLineCount = lines.length;
+  };
+}
+
 function readKey(): Promise<Buffer> {
   return new Promise((resolve, reject) => {
     const onData = (chunk: Buffer) => {
@@ -90,12 +110,12 @@ async function withRawMode<T>(fn: () => Promise<T>): Promise<T> {
   }
 }
 
-function renderMultiSelect<T>(
+function buildMultiSelectLines<T>(
   title: string,
   items: Array<{ label: string; value: T; checked: boolean }>,
   cursor: number,
   footer: string,
-): void {
+): string[] {
   const lines: string[] = [];
   lines.push("");
   lines.push(bold(title));
@@ -113,7 +133,7 @@ function renderMultiSelect<T>(
   }
   lines.push("");
   lines.push(dim(footer));
-  writeRaw(`${CLEAR_LINE}${lines.join(`\n${CLEAR_LINE}`)}\n`);
+  return lines;
 }
 
 export async function promptMultiSelect<T>(
@@ -130,10 +150,11 @@ export async function promptMultiSelect<T>(
 
   const footer = "↑↓ move  space toggle  a all  enter confirm  ctrl-c cancel";
   let cursor = 0;
+  const drawFrame = createFrameWriter();
 
   return withRawMode(async () => {
     while (true) {
-      renderMultiSelect(title, items, cursor, footer);
+      drawFrame(buildMultiSelectLines(title, items, cursor, footer));
       const key = parseKey(await readKey());
 
       if (key === "ctrl-c") {
@@ -163,11 +184,13 @@ export async function promptMultiSelect<T>(
   });
 }
 
-function renderConfirm(question: string, yesSelected: boolean): void {
+function buildConfirmLines(question: string, yesSelected: boolean): string[] {
   const yes = yesSelected ? green(bold(" Yes ")) : dim(" Yes ");
   const no = yesSelected ? dim(" No ") : green(bold(" No "));
-  writeRaw(`${CLEAR_LINE}${question}  ${yes} / ${no}\n`);
-  writeRaw(`${CLEAR_LINE}${dim("←→ or y/n to choose  enter to confirm  ctrl-c to cancel")}\n`);
+  return [
+    `${question}  ${yes} / ${no}`,
+    dim("←→ or y/n to choose  enter to confirm  ctrl-c to cancel"),
+  ];
 }
 
 export async function promptConfirm(question: string, defaultYes = true): Promise<boolean> {
@@ -186,10 +209,11 @@ export async function promptConfirm(question: string, defaultYes = true): Promis
   }
 
   let yesSelected = defaultYes;
+  const drawFrame = createFrameWriter();
 
   return withRawMode(async () => {
     while (true) {
-      renderConfirm(question, yesSelected);
+      drawFrame(buildConfirmLines(question, yesSelected));
       const key = parseKey(await readKey());
 
       if (key === "ctrl-c") {

package/src/installer/search-policy.ts

@@ -1,32 +1,86 @@
 /** Shared code-search policy text for instructions, Cursor rules, and sub-agents. */
 
-export const SEARCH_POLICY_TABLE = `| Task | Use | Not |
+export const SNIPPET_GUIDANCE =
+  "Search returns compact snippets (~±15 lines around the best match). " +
+  "When a hit has `truncated: true`, call `expand` with `file_path` and `anchor_line` " +
+  "(or `start_line`) — do not re-search or Read the whole file.";
+
+export interface NativeToolNames {
+  explorationDenied: string;
+  grep: string;
+  read: string;
+}
+
+export function buildSearchPolicyTable(native: NativeToolNames): string {
+  return `| Task | Use | Not |
 |------|-----|-----|
-| How/where/what handles X? | Miru MCP \`search\` (once) | Grep, Glob, SemanticSearch, repeat searches |
-| Same file, more context | Miru MCP \`expand\` | Re-search, Read whole file |
-| Similar code elsewhere | Miru MCP \`find_related\` | Grep chains |
-| Search docs or config | Miru \`search\` with \`content\` | Grep README paths |
-| Exact literal exists? | Grep | Miru |
-| Edit a known file:line | Read (after Miru found it) | Read-before-search |`;
+| How/where/what handles X? | Miru MCP \`search\` (once) | ${native.explorationDenied}, repeat searches |
+| 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 exists? | ${native.grep} | Miru |
+| Edit a known file:line | ${native.read} (after Miru found it) | ${native.read}-before-search |`;
+}
 
-export const SEARCH_POLICY_BODY = `DO NOT use Grep, Glob, SemanticSearch, or Read to explore how code works when Miru MCP is available.
+export function buildSearchPolicyBody(native: NativeToolNames): string {
+  return `DO NOT use ${native.explorationDenied} to explore how code works when Miru MCP is available.
+
+${SNIPPET_GUIDANCE}
 
 Use Miru MCP tools:
-- \`search\` — one call per question; pass project root as \`repo\`; read \`guidance.sufficient\` and \`suggested_next\` in the response
-- \`expand\` — adjacent chunks in the same file when a hit looks truncated (\`file_path\` + \`line\` from the hit)
-- \`find_related\` — similar code in other files after a \`search\` hit
+- \`search\` — one call per question; pass project root as \`repo\`
+- \`expand\` — more context in the same file when \`truncated: true\` (\`file_path\` + \`anchor_line\` or \`start_line\`)
+- \`find_related\` — similar code in other files (hits may also be snippets; use \`expand\` if truncated)
 
 Stop rules:
-- If \`guidance.sufficient\` is true, answer — do not re-search with paraphrases
-- If context is cut off in one file, call \`expand\` — not another \`search\` or a full-file Read
-- Read is for editing a path Miru already gave you, not for exploration
+- Answer from the first \`search\` — do not re-search with paraphrases
+- On \`truncated: true\`, call \`expand\` — not another \`search\` or a full-file ${native.read}
+- ${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
 
-${SEARCH_POLICY_TABLE}`;
+${buildSearchPolicyTable(native)}`;
+}
+
+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\` (or \`start_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.`;
+}
+
+const CLI_FALLBACK = `### CLI fallback (no MCP in this session)
+
+\`\`\`bash
+miru search "authentication flow" .
+miru expand src/auth.ts 42 .
+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.
+
+${buildSearchPolicyBody(native)}
+
+${buildMcpWorkflow(native)}
+
+${CLI_FALLBACK}`;
+}
+
+export const DEFAULT_NATIVE_TOOLS: NativeToolNames = {
+  explorationDenied: "Grep, Glob, SemanticSearch, or Read",
+  grep: "Grep",
+  read: "Read",
+};
+
+export const SEARCH_POLICY_BODY = buildSearchPolicyBody(DEFAULT_NATIVE_TOOLS);
 
 export const INSTRUCTIONS_MARKDOWN = `## Miru Code Search
 
@@ -54,25 +108,31 @@ alwaysApply: true
 
 ${SEARCH_POLICY_BODY}
 
-When Miru MCP is connected, call \`search\` once per question and follow \`guidance\` in the response. Use \`expand\` for same-file context. 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\`. Never use Cursor SemanticSearch or Grep for codebase questions unless confirming an exact literal.`;
 
-export const SUBAGENT_BODY = `When Miru MCP is available, use MCP \`search\`, \`expand\`, and \`find_related\` — not Grep, Glob, SemanticSearch, or Read-for-exploration.
+export const SUBAGENT_BODY = buildSubagentBody(DEFAULT_NATIVE_TOOLS);
 
-${SEARCH_POLICY_BODY}
+export const MCP_SERVER_INSTRUCTIONS =
+  "DO NOT use Grep, Glob, SemanticSearch, or Read to explore code when this server is available. " +
+  `${SNIPPET_GUIDANCE} ` +
+  "Workflow: (1) `search` once per question — do NOT re-search with paraphrases. " +
+  "(2) On `truncated: true`, call `expand` with `file_path` and `anchor_line` (or `start_line`) — do NOT read the whole file. " +
+  "(3) `find_related` traces similar code in other files, not more context in the same file. " +
+  "Always pass the project root as `repo`. Local repos return `absolute_path` on each hit — use Read only to edit. " +
+  "Native search is only for exact literal confirmation or files outside the indexed repo.";
 
-### MCP workflow
+export const MCP_SEARCH_TOOL_DESCRIPTION =
+  "DEFAULT code exploration tool. Returns compact snippets (~±15 lines). One call per question is usually enough. " +
+  "When a hit has `truncated: true`, call `expand` with `file_path` and `anchor_line` (or `start_line`) — not re-search or Read.";
 
-1. Call \`search\` with \`repo\` set to the project root (local path or https:// git URL).
-2. If \`guidance.suggested_next\` is \`expand\`, call \`expand\` with the hit's \`file_path\` and \`line\`.
-3. Use \`find_related\` to trace similar code in other files — not for more context in the same file.
-4. Read via \`absolute_path\` only when editing or when \`expand\` still lacks context.
+export const MCP_EXPAND_TOOL_DESCRIPTION =
+  "More context in the SAME file as a search hit. Pass `file_path` + `anchor_line` or `start_line` from a truncated hit; " +
+  "returns adjacent indexed chunks. Use when `truncated: true` — NOT for similar code in other files (use find_related). " +
+  "Prefer this over re-searching or reading the whole file.";
 
-### CLI fallback (no MCP in this session)
+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.";
 
-\`\`\`bash
-miru search "authentication flow" .
-miru expand src/auth.ts 42 .
-miru find-related src/auth.ts 42 .
-\`\`\`
-
-If \`miru\` is not on \`$PATH\`, use \`bunx @takara-ai/miru-code\`.`;
+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.";