@takara-ai/miru-code 1.8.1 → 1.8.2

package/package.json

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

package/src/installer/search-policy.ts

@@ -1,8 +1,8 @@
 /** Shared code-search policy text for instructions, Cursor rules, and sub-agents. */
 
 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` — do not re-search or Read the whole file.";
+  "Search returns compact snippets (~±15 lines). On `truncated: true`, call `expand` with " +
+  "`file_path` and `anchor_line` — only if the snippet doesn't already answer the question.";
 
 export interface NativeToolNames {
   explorationDenied: string;
@@ -13,30 +13,36 @@ export interface NativeToolNames {
 export function buildSearchPolicyTable(native: NativeToolNames): string {
   return `| Task | Use | Not |
 |------|-----|-----|
-| Quick lookup — where is X handled/defined? | Miru MCP \`search\` (once) | ${native.grep}, ${native.explorationDenied} |
-| How/where/what handles X? | Miru MCP \`search\` (once) | ${native.explorationDenied}, repeat searches |
+| Exact literal (identifier, quoted string, env var, error code) | Miru MCP \`locate\` | Miru \`search\`, ${native.grep} |
+| How/where/what handles X? (conceptual) | Miru MCP \`search\` (once) | ${native.grep}, ${native.explorationDenied} |
 | 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? | Miru MCP \`locate\` | ${native.grep}, Miru \`search\` |
 | Edit a known file:line | ${native.read} (after Miru found it) | ${native.read}-before-search |`;
 }
 
 export function buildSearchPolicyBody(native: NativeToolNames): string {
   return `DO NOT use ${native.explorationDenied} to explore how code works when Miru MCP is available.
 
+**Check first:** exact token (identifier, quoted string, env var, error code) → \`locate\`. Otherwise → \`search\`.
+
 ${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\`
+- \`search\` — one call per conceptual question; pass project root as \`repo\`
 - \`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)
 
+Call shapes:
+- \`locate(literal="<exact substring>", repo="<project root>")\` — prefer \`mode="locations"\`/\`"count"\`
+- \`search(query="<natural language>", repo="<project root>")\`
+
 Stop rules:
-- 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
+- Literal in the request → \`locate\`, not \`search\`
+- One \`search\` per question — no paraphrase retries
+- \`expand\` only if the snippet doesn't already answer
+- ${native.read} only to edit a path Miru already found, not to explore
 
 Native tools are allowed ONLY when:
 - reading a file you already located via Miru, to edit it
@@ -50,7 +56,7 @@ export function buildMcpWorkflow(native: NativeToolNames): string {
 
 1. Call \`search\` with \`repo\` set to the project root (local path or https:// git URL).
 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\`.
+3. On \`truncated: true\`, call \`expand\` — only if the snippet doesn't already answer.
 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.`;
 }
@@ -64,6 +70,7 @@ miru expand src/auth.ts 42 .
 miru find-related src/auth.ts 42 .
 \`\`\`
 
+After large refactors or CLI-only use, run \`miru clear <path>\` to rebuild the disk cache.
 If \`miru\` is not on \`$PATH\`, use \`bunx @takara-ai/miru-code\`.`;
 
 export function buildSubagentBody(native: NativeToolNames): string {
@@ -90,16 +97,7 @@ ${SEARCH_POLICY_BODY}
 
 Run \`miru setup\` once — the MCP server loads credentials from \`credentials.json\`, and interactive first use can auto-start device login when nothing is stored.
 
-CLI fallback when MCP is unavailable:
-
-\`\`\`bash
-miru search "authentication flow" .
-miru expand src/auth.ts 42 .
-miru find-related src/auth.ts 42 .
-\`\`\`
-
-After large refactors or CLI-only use, run \`miru clear <path>\` to rebuild the disk cache.
-If \`miru\` is not on \`$PATH\`, use \`bunx @takara-ai/miru-code\`.`;
+${CLI_FALLBACK}`;
 
 export const CURSOR_RULES_MDC = `---
 description: Miru MCP is the default for all code exploration
@@ -110,20 +108,19 @@ 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\`. Use \`locate\` for exact literals — not Grep. Never use Cursor SemanticSearch for codebase questions.`;
+When Miru MCP is connected: literal in the request → \`locate\`, not Grep or \`search\`. Otherwise \`search\` once. \`expand\` only if the snippet doesn't already answer. Never use Cursor SemanticSearch for codebase questions.`;
 
 export const SUBAGENT_BODY = buildSubagentBody(DEFAULT_NATIVE_TOOLS);
 
 export const MCP_SERVER_INSTRUCTIONS =
   "Miru `search` is your default for all code search queries in indexed repos — the best, fastest, and cheapest way to find code; better than any other tool. " +
   "DO NOT use Grep, grep_search, codebase_search, Glob, SemanticSearch, or Read to explore code when this server is available. " +
+  "Exact token (identifier, quoted string, env var, error code) → `locate`; everything else → `search` once, no paraphrase retries. " +
   `${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` — 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. " +
+  "`find_related` traces similar code elsewhere, not more context in the same file. " +
+  "Always pass the project root as `repo`; local repos return `absolute_path` — use Read only to edit. " +
   "Native Grep/Glob only outside the indexed repo or for non-code tasks. " +
+  "Default indexed scope is code, config, and docs; an empty result can mean out-of-scope, not nonexistent. " +
   "On credential errors, call this server's `auth` tool — not the host `mcp_auth` tool.";
 
 export const MCP_BENCHMARK_SERVER_INSTRUCTIONS =
@@ -137,25 +134,25 @@ export const MCP_BENCHMARK_SERVER_INSTRUCTIONS =
 
 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. " +
-  "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.";
+  "Returns compact snippets (~±15 lines). One call per question. " +
+  "Exact literal (env var, symbol, error code, quoted text)? Use `locate` instead. " +
+  "On `truncated: true`, call `expand` — only if the snippet doesn't already answer the question.";
 
 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`). " +
+  "Exact substring locator over the Miru index. Use for known literals (env vars, symbols, error codes, quoted text) — not meaning-based questions (`search`), " +
+  'even ones phrased as "where is X" or "what handles X" if X is a literal. ' +
   "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. " +
-  "Pass an array to `literal` to match several spellings in one call; " +
-  'or set `match_variants: true` to also match other ways the same word is written in code (e.g. "rateLimit" also finds "rate_limit"). ' +
-  "Use `include`/`exclude` (gitignore-style globs) to scope to part of a monorepo. " +
-  "Use `context_lines` in `lines` mode to get surrounding lines inline instead of a follow-up `expand`/Read. " +
+  "Pass an array to `literal` for several spellings in one call. " +
+  '`match_variants: true` also matches other casings (e.g. "rateLimit" also finds "rate_limit"). ' +
+  "`include`/`exclude` (gitignore-style globs) scope to part of a monorepo; " +
+  "`context_lines` in `lines` mode gets inline context instead of a follow-up `expand`. " +
   "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). " +
-  "Prefer this over re-searching or reading the whole file.";
+  "More context in the SAME file as a search hit. Pass `file_path` + `anchor_line` from the hit. " +
+  "Use only if `truncated: true` and the snippet doesn't already answer the question — not for similar code elsewhere (use find_related).";
 
 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`. " +
@@ -165,5 +162,4 @@ 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.";
+export const SEARCH_GUARD_EXPAND_HINT = SNIPPET_GUIDANCE;

package/src/mcp/index-cache.ts

@@ -1,5 +1,6 @@
 import { watch } from "node:fs";
 import { relative, resolve } from "node:path";
+import { isCredentialsError } from "../auth/errors.ts";
 import { walkFiles } from "../index/file-walker.ts";
 import { getExtensions } from "../index/files.ts";
 import { normalizeRelativePath, relativePathFromRoot } from "../index/incremental.ts";
@@ -13,7 +14,6 @@ import {
 } from "../utils.ts";
 
 const CACHE_MAX_SIZE = 10;
-const BUN_WATCH_RECONCILE_INTERVAL_MS = 500;
 
 /** Directory names we skip for MCP fs.watch update triggers (aligned with file-walker). */
 const WATCH_IGNORED_DIR_NAMES = new Set([
@@ -45,6 +45,8 @@ type CacheEntry = {
   pendingPaths: Set<string>;
   flushQueued: boolean;
   updateChain: Promise<void>;
+  /** Dead-credentials failure from a background re-embed; `get()` throws it until a retry clears it. */
+  lastError: Error | null;
 };
 
 export function mcpWatchEnabled(): boolean {
@@ -98,6 +100,7 @@ export class IndexCache {
         pendingPaths: new Set(),
         flushQueued: false,
         updateChain: Promise.resolve(),
+        lastError: null,
       };
       this.entries.set(cacheKey, entry);
     }
@@ -171,6 +174,9 @@ export class IndexCache {
       throw new Error(`Failed to load index for ${source}`);
     }
     await entry.updateChain;
+    if (entry.lastError) {
+      throw entry.lastError;
+    }
     return index;
   }
 
@@ -183,39 +189,11 @@ export class IndexCache {
     }
   }
 
-  private queueIndexedPaths(source: string, index: MiruIndex): void {
-    const cacheKey = computeSourceCacheKey(source);
-    const entry = this.ensureEntry(cacheKey, source);
-    for (const chunk of index.chunks) {
-      entry.pendingPaths.add(normalizeRelativePath(chunk.file_path));
-    }
-    this.scheduleFlush(cacheKey, source, entry);
-  }
-
-  /** macOS recursive fs.watch often omits filename; refresh all indexed paths incrementally. */
-  private noteAmbiguousDirectoryChange(source: string): void {
-    const cacheKey = computeSourceCacheKey(source);
-    const entry = this.entries.get(cacheKey);
-    if (!entry) {
-      return;
-    }
-
-    if (entry.index) {
-      this.queueIndexedPaths(source, entry.index);
-      return;
-    }
-
-    if (entry.task) {
-      void entry.task.then((index) => {
-        entry.index = index;
-        this.queueIndexedPaths(source, index);
-      });
-    }
-  }
-
   private noteFileChange(source: string, filename: string | null | undefined): void {
     if (!filename) {
-      this.noteAmbiguousDirectoryChange(source);
+      // macOS recursive fs.watch could omit the filename on old Bun releases (pre-1.3.14
+      // fs.watch rewrite); confirmed fixed on current Bun. No reconcile fallback for
+      // this case anymore -- an event with no filename is simply dropped.
       return;
     }
     if (shouldIgnoreWatchPath(filename)) {
@@ -253,34 +231,38 @@ export class IndexCache {
         return;
       }
 
+      const requeue = (err?: unknown): void => {
+        if (err !== undefined && isCredentialsError(err)) {
+          entry.lastError = err instanceof Error ? err : new Error(String(err));
+        }
+        for (const p of paths) {
+          entry.pendingPaths.add(p);
+        }
+      };
+
       // Prefer an index already in hand (or published on the entry). Never await
       // entry.task while that task is itself waiting on this flush — that deadlocks.
       let index = knownIndex ?? entry.index;
       if (!index && entry.task) {
         try {
           index = await entry.task;
-        } catch {
-          for (const p of paths) {
-            entry.pendingPaths.add(p);
-          }
+        } catch (err) {
+          requeue(err);
           return;
         }
       }
       if (!index) {
-        for (const p of paths) {
-          entry.pendingPaths.add(p);
-        }
+        requeue();
         return;
       }
 
       try {
         await index.applyFileChanges(paths);
-      } catch {
-        for (const p of paths) {
-          entry.pendingPaths.add(p);
-        }
+      } catch (err) {
+        requeue(err);
         return;
       }
+      entry.lastError = null;
       if (!isGitUrl(source)) {
         try {
           await index.saveToCache(resolve(source), { force: true });
@@ -364,40 +346,13 @@ export class IndexCache {
         this.noteFileChange(path, filename);
       });
     } catch {
-      // Recursive fs.watch is unavailable on some platforms. The reconciliation
-      // fallback below keeps local indexes current there.
+      // Recursive fs.watch is unavailable on some platforms (no fallback here
+      // anymore -- such a local index will only refresh on next cold load).
     }
 
-    // Bun 1.3 on macOS can create a recursive watcher without delivering file
-    // events. Reconcile periodically in Bun so a silent watcher cannot leave an
-    // MCP index stale. Native watchers remain the fast path everywhere else.
-    let reconcileInFlight = false;
-    const reconcile = (): void => {
-      if (reconcileInFlight) {
-        return;
-      }
-      const cacheKey = computeSourceCacheKey(path);
-      const entry = this.entries.get(cacheKey);
-      if (!entry?.index) {
-        return;
-      }
-      reconcileInFlight = true;
-      void this.checkAndQueueStaleFiles(path, entry.index, cacheKey).finally(() => {
-        reconcileInFlight = false;
-      });
-    };
-    const interval =
-      process.versions.bun || !nativeWatcher
-        ? setInterval(reconcile, BUN_WATCH_RECONCILE_INTERVAL_MS)
-        : null;
-    interval?.unref();
-
     this.watchers.set(resolved, {
       close: () => {
         nativeWatcher?.close();
-        if (interval) {
-          clearInterval(interval);
-        }
       },
     });
   }

package/src/mcp/server.ts

@@ -226,10 +226,17 @@ export function createMcpServer(
       inputSchema: {
         literal: z
           .union([z.string().min(1), z.array(z.string().min(1)).min(1)])
+          .optional()
           .describe(
             "Exact substring to find (env var, symbol, error code, quoted text). " +
               "Pass an array to OR-match several substrings (e.g. spelling/casing variants) in one call.",
           ),
+        query: z
+          .union([z.string().min(1), z.array(z.string().min(1)).min(1)])
+          .optional()
+          .describe(
+            "Alias for `literal` — accepted so a call shaped like `search(query=...)` still resolves as an exact-substring lookup.",
+          ),
         repo: z.string().describe(REPO_DESCRIPTION),
         mode: z
           .enum(["count", "locations", "lines"])
@@ -270,13 +277,17 @@ export function createMcpServer(
           .describe("Lines of context before/after each match, like `grep -C` (mode=lines only)."),
       },
     },
-    async ({ literal, repo, ...locateOpts }) => {
+    async ({ literal, query, repo, ...locateOpts }) => {
+      const lit = literal ?? query;
+      if (lit == null) {
+        return toolErrorText(new Error("locate requires `literal` (exact substring to find)."));
+      }
       try {
         const index = await getIndexForRepo(repo, cache);
 
         let skip: BenchmarkSkipReason | undefined;
         const repoRoot = localRepoRoot(repo);
-        if (benchmark && repoRoot && typeof literal === "string") {
+        if (benchmark && repoRoot && typeof lit === "string") {
           if (locateOpts.limit != null) {
             skip = "limited_locate";
           } else if (!selectComparableLiteralSearchTool()) {
@@ -285,7 +296,7 @@ export function createMcpServer(
           if (!skip) {
             const comparison = await withGrepTimeoutFallback(() =>
               benchmarkLocateComparison({
-                literal,
+                literal: lit,
                 repoPath: repoRoot,
                 index,
                 locate: locateOpts,
@@ -302,7 +313,7 @@ export function createMcpServer(
           skip = "local_repo_only";
         }
 
-        const result = index.locateLiteral(literal, locateOpts);
+        const result = index.locateLiteral(lit, locateOpts);
         const payload = formatLiteralLocate(result);
         const body = formatLiteralLocateText(payload);
         return toolText(skip ? withBenchmarkSkippedNote(body, skip) : body);

package/src/types.ts

@@ -1,7 +1,7 @@
 export type ContentType = "code" | "docs" | "config";
 
-/** Default index corpus: source code plus config (json/yaml/toml/…). */
-export const DEFAULT_CONTENT_TYPES: readonly ContentType[] = ["code", "config"];
+/** Default index corpus: source code, config (json/yaml/toml/…), and docs (md/rst/txt). */
+export const DEFAULT_CONTENT_TYPES: readonly ContentType[] = ["code", "config", "docs"];
 
 /** Mutable copy of {@link DEFAULT_CONTENT_TYPES} for API defaults. */
 export function defaultContentTypes(): ContentType[] {

package/src/version.ts

@@ -1,3 +1,4 @@
+import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import packageJson from "../package.json";
 import { resolveCacheFolder } from "./cache.ts";
@@ -79,7 +80,12 @@ function updateCheckPath(): string {
 
 async function readUpdateCheckCache(): Promise<UpdateCheckCache | null> {
   try {
-    const raw = await Bun.file(updateCheckPath()).text();
+    // node:fs/promises, not Bun.file().text(): a rejecting Bun.file() read
+    // (the common case here — no cache on a fresh install) doesn't keep
+    // Bun's Windows event loop alive, so the process can exit silently
+    // before this ever settles. Confirmed regression in Bun 1.4.0-1.4.2:
+    // github.com/oven-sh/bun/issues/39787 (fix open, not yet released).
+    const raw = await readFile(updateCheckPath(), "utf8");
     const parsed = JSON.parse(raw) as UpdateCheckCache;
     if (typeof parsed.checkedAt !== "number" || typeof parsed.latest !== "string") {
       return null;