opencode-codebase-index 0.5.2 → 0.6.1

package/dist/index.js

@@ -6,13 +6,7 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
-  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
-}) : x)(function(x) {
-  if (typeof require !== "undefined") return require.apply(this, arguments);
-  throw Error('Dynamic require of "' + x + '" is not supported');
-});
-var __commonJS = (cb, mod) => function __require2() {
+var __commonJS = (cb, mod) => function __require() {
   return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
 };
 var __copyProps = (to, from, except, desc) => {
@@ -34,7 +28,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 
 // node_modules/eventemitter3/index.js
 var require_eventemitter3 = __commonJS({
-  "node_modules/eventemitter3/index.js"(exports, module) {
+  "node_modules/eventemitter3/index.js"(exports, module2) {
     "use strict";
     var has = Object.prototype.hasOwnProperty;
     var prefix = "~";
@@ -188,15 +182,15 @@ var require_eventemitter3 = __commonJS({
     EventEmitter3.prototype.addListener = EventEmitter3.prototype.on;
     EventEmitter3.prefixed = prefix;
     EventEmitter3.EventEmitter = EventEmitter3;
-    if ("undefined" !== typeof module) {
-      module.exports = EventEmitter3;
+    if ("undefined" !== typeof module2) {
+      module2.exports = EventEmitter3;
     }
   }
 });
 
 // node_modules/ignore/index.js
 var require_ignore = __commonJS({
-  "node_modules/ignore/index.js"(exports, module) {
+  "node_modules/ignore/index.js"(exports, module2) {
     "use strict";
     function makeArray(subject) {
       return Array.isArray(subject) ? subject : [subject];
@@ -645,10 +639,10 @@ var require_ignore = __commonJS({
     ) {
       setupWindows();
     }
-    module.exports = factory;
+    module2.exports = factory;
     factory.default = factory;
-    module.exports.isPathValid = isPathValid;
-    define(module.exports, /* @__PURE__ */ Symbol.for("setupWindows"), setupWindows);
+    module2.exports.isPathValid = isPathValid;
+    define(module2.exports, /* @__PURE__ */ Symbol.for("setupWindows"), setupWindows);
   }
 });
 
@@ -664,7 +658,7 @@ var DEFAULT_INCLUDE = [
   "**/*.{py,pyi}",
   "**/*.{go,rs,java,kt,scala}",
   "**/*.{c,cpp,cc,h,hpp}",
-  "**/*.{rb,php,swift}",
+  "**/*.{rb,php,inc,swift}",
   "**/*.{vue,svelte,astro}",
   "**/*.{sql,graphql,proto}",
   "**/*.{yaml,yml,toml}",
@@ -759,6 +753,27 @@ var DEFAULT_PROVIDER_MODELS = {
   "ollama": "nomic-embed-text"
 };
 
+// src/config/env-substitution.ts
+var ENV_REFERENCE_PATTERN = /^\{env:([A-Z_][A-Z0-9_]*)\}$/;
+var ENV_REFERENCE_LIKE_PATTERN = /\{env:[^}]+\}/;
+function substituteEnvString(value, keyPath) {
+  const match = value.match(ENV_REFERENCE_PATTERN);
+  if (!match) {
+    if (ENV_REFERENCE_LIKE_PATTERN.test(value)) {
+      throw new Error(
+        `Invalid environment variable reference at '${keyPath}'. Expected the entire string to match '{env:VAR_NAME}' with VAR_NAME matching [A-Z_][A-Z0-9_]*.`
+      );
+    }
+    return value;
+  }
+  const variableName = match[1];
+  const envValue = process.env[variableName];
+  if (envValue === void 0) {
+    throw new Error(`Missing environment variable '${variableName}' referenced by config at '${keyPath}'.`);
+  }
+  return envValue;
+}
+
 // src/config/schema.ts
 function getDefaultIndexingConfig() {
   return {
@@ -816,11 +831,27 @@ function isValidScope(value) {
 function isStringArray(value) {
   return Array.isArray(value) && value.every((item) => typeof item === "string");
 }
+function getResolvedString(value, keyPath) {
+  if (typeof value !== "string") {
+    return void 0;
+  }
+  return substituteEnvString(value, keyPath);
+}
+function getResolvedStringArray(value, keyPath) {
+  if (!isStringArray(value)) {
+    return void 0;
+  }
+  return value.map((item, index) => substituteEnvString(item, `${keyPath}[${index}]`));
+}
 function isValidLogLevel(value) {
   return typeof value === "string" && VALID_LOG_LEVELS.includes(value);
 }
 function parseConfig(raw) {
   const input = raw && typeof raw === "object" ? raw : {};
+  const embeddingProviderValue = getResolvedString(input.embeddingProvider, "$root.embeddingProvider");
+  const scopeValue = getResolvedString(input.scope, "$root.scope");
+  const includeValue = getResolvedStringArray(input.include, "$root.include");
+  const excludeValue = getResolvedStringArray(input.exclude, "$root.exclude");
   const defaultIndexing = getDefaultIndexingConfig();
   const defaultSearch = getDefaultSearchConfig();
   const defaultDebug = getDefaultDebugConfig();
@@ -863,19 +894,23 @@ function parseConfig(raw) {
   let embeddingProvider;
   let embeddingModel = void 0;
   let customProvider = void 0;
-  if (input.embeddingProvider === "custom") {
+  if (embeddingProviderValue === "custom") {
     embeddingProvider = "custom";
     const rawCustom = input.customProvider && typeof input.customProvider === "object" ? input.customProvider : null;
-    if (rawCustom && typeof rawCustom.baseUrl === "string" && rawCustom.baseUrl.trim().length > 0 && typeof rawCustom.model === "string" && rawCustom.model.trim().length > 0 && typeof rawCustom.dimensions === "number" && Number.isInteger(rawCustom.dimensions) && rawCustom.dimensions > 0) {
+    const baseUrlValue = getResolvedString(rawCustom?.baseUrl, "$root.customProvider.baseUrl");
+    const modelValue = getResolvedString(rawCustom?.model, "$root.customProvider.model");
+    const apiKeyValue = getResolvedString(rawCustom?.apiKey, "$root.customProvider.apiKey");
+    if (rawCustom && typeof baseUrlValue === "string" && baseUrlValue.trim().length > 0 && typeof modelValue === "string" && modelValue.trim().length > 0 && typeof rawCustom.dimensions === "number" && Number.isInteger(rawCustom.dimensions) && rawCustom.dimensions > 0) {
       customProvider = {
-        baseUrl: rawCustom.baseUrl.trim().replace(/\/+$/, ""),
-        model: rawCustom.model,
+        baseUrl: baseUrlValue.trim().replace(/\/+$/, ""),
+        model: modelValue,
         dimensions: rawCustom.dimensions,
-        apiKey: typeof rawCustom.apiKey === "string" ? rawCustom.apiKey : void 0,
+        apiKey: apiKeyValue,
         maxTokens: typeof rawCustom.maxTokens === "number" ? rawCustom.maxTokens : void 0,
         timeoutMs: typeof rawCustom.timeoutMs === "number" ? Math.max(1e3, rawCustom.timeoutMs) : void 0,
         concurrency: typeof rawCustom.concurrency === "number" ? Math.max(1, Math.floor(rawCustom.concurrency)) : void 0,
-        requestIntervalMs: typeof rawCustom.requestIntervalMs === "number" ? Math.max(0, Math.floor(rawCustom.requestIntervalMs)) : void 0
+        requestIntervalMs: typeof rawCustom.requestIntervalMs === "number" ? Math.max(0, Math.floor(rawCustom.requestIntervalMs)) : void 0,
+        maxBatchSize: typeof rawCustom.maxBatchSize === "number" ? Math.max(1, Math.floor(rawCustom.maxBatchSize)) : typeof rawCustom.max_batch_size === "number" ? Math.max(1, Math.floor(rawCustom.max_batch_size)) : void 0
       };
       if (!/\/v\d+\/?$/.test(customProvider.baseUrl)) {
         console.warn(
@@ -887,10 +922,16 @@ function parseConfig(raw) {
         "embeddingProvider is 'custom' but customProvider config is missing or invalid. Required fields: baseUrl (string), model (string), dimensions (positive integer)."
       );
     }
-  } else if (isValidProvider(input.embeddingProvider)) {
-    embeddingProvider = input.embeddingProvider;
-    if (input.embeddingModel) {
-      embeddingModel = isValidModel(input.embeddingModel, embeddingProvider) ? input.embeddingModel : DEFAULT_PROVIDER_MODELS[embeddingProvider];
+  } else if (isValidProvider(embeddingProviderValue)) {
+    embeddingProvider = embeddingProviderValue;
+    const rawEmbeddingModel = input.embeddingModel;
+    if (typeof rawEmbeddingModel === "string") {
+      const embeddingModelValue = substituteEnvString(rawEmbeddingModel, "$root.embeddingModel");
+      if (embeddingModelValue) {
+        embeddingModel = isValidModel(embeddingModelValue, embeddingProvider) ? embeddingModelValue : DEFAULT_PROVIDER_MODELS[embeddingProvider];
+      }
+    } else if (rawEmbeddingModel) {
+      embeddingModel = DEFAULT_PROVIDER_MODELS[embeddingProvider];
     }
   } else {
     embeddingProvider = "auto";
@@ -899,9 +940,9 @@ function parseConfig(raw) {
     embeddingProvider,
     embeddingModel,
     customProvider,
-    scope: isValidScope(input.scope) ? input.scope : "project",
-    include: isStringArray(input.include) ? input.include : DEFAULT_INCLUDE,
-    exclude: isStringArray(input.exclude) ? input.exclude : DEFAULT_EXCLUDE,
+    scope: isValidScope(scopeValue) ? scopeValue : "project",
+    include: includeValue ?? DEFAULT_INCLUDE,
+    exclude: excludeValue ?? DEFAULT_EXCLUDE,
     indexing,
     search,
     debug
@@ -2085,7 +2126,8 @@ function createCustomProviderInfo(config) {
       dimensions: config.dimensions,
       maxTokens: config.maxTokens ?? 8192,
       costPer1MTokens: 0,
-      timeoutMs: config.timeoutMs ?? 3e4
+      timeoutMs: config.timeoutMs ?? 3e4,
+      maxBatchSize: config.maxBatchSize
     }
   };
 }
@@ -2348,21 +2390,24 @@ var CustomEmbeddingProvider = class {
     this.credentials = credentials;
     this.modelInfo = modelInfo;
   }
-  async embedQuery(query) {
-    const result = await this.embedBatch([query]);
-    return {
-      embedding: result.embeddings[0],
-      tokensUsed: result.totalTokensUsed
-    };
-  }
-  async embedDocument(document) {
-    const result = await this.embedBatch([document]);
-    return {
-      embedding: result.embeddings[0],
-      tokensUsed: result.totalTokensUsed
-    };
+  splitIntoRequestBatches(texts) {
+    const maxBatchSize = this.modelInfo.maxBatchSize;
+    if (!maxBatchSize || texts.length <= maxBatchSize) {
+      return [texts];
+    }
+    const batches = [];
+    for (let i = 0; i < texts.length; i += maxBatchSize) {
+      batches.push(texts.slice(i, i + maxBatchSize));
+    }
+    return batches;
   }
-  async embedBatch(texts) {
+  async embedRequest(texts) {
+    if (texts.length === 0) {
+      return {
+        embeddings: [],
+        totalTokensUsed: 0
+      };
+    }
     const headers = {
       "Content-Type": "application/json"
     };
@@ -2423,6 +2468,34 @@ var CustomEmbeddingProvider = class {
     }
     throw new Error("Custom embedding API returned unexpected response format. Expected OpenAI-compatible format with data[].embedding.");
   }
+  async embedQuery(query) {
+    const result = await this.embedBatch([query]);
+    return {
+      embedding: result.embeddings[0],
+      tokensUsed: result.totalTokensUsed
+    };
+  }
+  async embedDocument(document) {
+    const result = await this.embedBatch([document]);
+    return {
+      embedding: result.embeddings[0],
+      tokensUsed: result.totalTokensUsed
+    };
+  }
+  async embedBatch(texts) {
+    const requestBatches = this.splitIntoRequestBatches(texts);
+    const embeddings = [];
+    let totalTokensUsed = 0;
+    for (const batch of requestBatches) {
+      const result = await this.embedRequest(batch);
+      embeddings.push(...result.embeddings);
+      totalTokensUsed += result.totalTokensUsed;
+    }
+    return {
+      embeddings,
+      totalTokensUsed
+    };
+  }
   getModelInfo() {
     return this.modelInfo;
   }
@@ -2925,6 +2998,7 @@ function initializeLogger(config) {
 // src/native/index.ts
 import * as path3 from "path";
 import * as os2 from "os";
+import * as module from "module";
 import { fileURLToPath } from "url";
 function getNativeBinding() {
   const platform2 = os2.platform();
@@ -2944,17 +3018,22 @@ function getNativeBinding() {
     throw new Error(`Unsupported platform: ${platform2}-${arch2}`);
   }
   let currentDir;
+  let requireTarget;
   if (typeof import.meta !== "undefined" && import.meta.url) {
     currentDir = path3.dirname(fileURLToPath(import.meta.url));
+    requireTarget = import.meta.url;
   } else if (typeof __dirname !== "undefined") {
     currentDir = __dirname;
+    requireTarget = __filename;
   } else {
     currentDir = process.cwd();
+    requireTarget = path3.join(currentDir, "index.js");
   }
   const isDevMode = currentDir.includes("/src/native");
   const packageRoot = isDevMode ? path3.resolve(currentDir, "../..") : path3.resolve(currentDir, "..");
   const nativePath = path3.join(packageRoot, "native", bindingName);
-  return __require(nativePath);
+  const require2 = module.createRequire(requireTarget);
+  return require2(nativePath);
 }
 var native = getNativeBinding();
 function parseFiles(files) {
@@ -3436,7 +3515,36 @@ var Database = class {
 // src/git/index.ts
 import { existsSync as existsSync3, readFileSync as readFileSync3, readdirSync, statSync } from "fs";
 import * as path4 from "path";
-import { execSync } from "child_process";
+function readPackedRefs(gitDir) {
+  const packedRefsPath = path4.join(gitDir, "packed-refs");
+  if (!existsSync3(packedRefsPath)) {
+    return [];
+  }
+  try {
+    return readFileSync3(packedRefsPath, "utf-8").split("\n").map((line) => line.trim()).filter((line) => line.length > 0 && !line.startsWith("#") && !line.startsWith("^"));
+  } catch {
+    return [];
+  }
+}
+function resolveCommonGitDir(gitDir) {
+  const commonDirPath = path4.join(gitDir, "commondir");
+  if (!existsSync3(commonDirPath)) {
+    return gitDir;
+  }
+  try {
+    const raw = readFileSync3(commonDirPath, "utf-8").trim();
+    if (!raw) {
+      return gitDir;
+    }
+    const resolved = path4.isAbsolute(raw) ? raw : path4.resolve(gitDir, raw);
+    if (existsSync3(resolved)) {
+      return resolved;
+    }
+  } catch {
+    return gitDir;
+  }
+  return gitDir;
+}
 function resolveGitDir(repoRoot) {
   const gitPath = path4.join(repoRoot, ".git");
   if (!existsSync3(gitPath)) {
@@ -3490,37 +3598,20 @@ function getCurrentBranch(repoRoot) {
 }
 function getBaseBranch(repoRoot) {
   const gitDir = resolveGitDir(repoRoot);
+  const refStoreDir = gitDir ? resolveCommonGitDir(gitDir) : null;
   const candidates = ["main", "master", "develop", "trunk"];
-  if (gitDir) {
+  if (refStoreDir) {
     for (const candidate of candidates) {
-      const refPath = path4.join(gitDir, "refs", "heads", candidate);
+      const refPath = path4.join(refStoreDir, "refs", "heads", candidate);
       if (existsSync3(refPath)) {
         return candidate;
       }
-      const packedRefsPath = path4.join(gitDir, "packed-refs");
-      if (existsSync3(packedRefsPath)) {
-        try {
-          const content = readFileSync3(packedRefsPath, "utf-8");
-          if (content.includes(`refs/heads/${candidate}`)) {
-            return candidate;
-          }
-        } catch {
-        }
+      const packedRefs = readPackedRefs(refStoreDir);
+      if (packedRefs.some((line) => line.endsWith(` refs/heads/${candidate}`))) {
+        return candidate;
       }
     }
   }
-  try {
-    const result = execSync("git remote show origin", {
-      cwd: repoRoot,
-      encoding: "utf-8",
-      stdio: ["pipe", "pipe", "pipe"]
-    });
-    const match = result.match(/HEAD branch: (.+)/);
-    if (match) {
-      return match[1].trim();
-    }
-  } catch {
-  }
   return getCurrentBranch(repoRoot) ?? "main";
 }
 function getBranchOrDefault(repoRoot) {
@@ -3538,7 +3629,7 @@ function getHeadPath(repoRoot) {
 }
 
 // src/indexer/index.ts
-var CALL_GRAPH_LANGUAGES = /* @__PURE__ */ new Set(["typescript", "tsx", "javascript", "jsx", "python", "go", "rust"]);
+var CALL_GRAPH_LANGUAGES = /* @__PURE__ */ new Set(["typescript", "tsx", "javascript", "jsx", "python", "go", "rust", "php"]);
 var CALL_GRAPH_SYMBOL_CHUNK_TYPES = /* @__PURE__ */ new Set([
   "function_declaration",
   "function",
@@ -3559,7 +3650,8 @@ var CALL_GRAPH_SYMBOL_CHUNK_TYPES = /* @__PURE__ */ new Set([
   "struct_item",
   "enum_item",
   "trait_item",
-  "mod_item"
+  "mod_item",
+  "trait_declaration"
 ]);
 function float32ArrayToBuffer(arr) {
   const float32 = new Float32Array(arr);
@@ -3941,8 +4033,8 @@ function stripFilePathHint(query) {
   const stripped = query.replace(FILE_PATH_HINT_SUFFIX_REGEX, "").trim();
   return stripped.length > 0 ? stripped : query;
 }
-function buildDeterministicIdentifierPass(query, candidates, limit) {
-  if (classifyQueryIntentRaw(query) !== "source") {
+function buildDeterministicIdentifierPass(query, candidates, limit, prioritizeSourcePaths = classifyQueryIntentRaw(query) === "source") {
+  if (!prioritizeSourcePaths) {
     return [];
   }
   const primary = extractPrimaryIdentifierQueryHint(query);
@@ -4158,9 +4250,8 @@ function rankHybridResults(query, semanticResults, keywordResults, options) {
   const fused = options.fusionStrategy === "rrf" ? fuseResultsRrf(semanticResults, keywordResults, options.rrfK, overfetchLimit) : fuseResultsWeighted(semanticResults, keywordResults, options.hybridWeight, overfetchLimit);
   const rerankPoolLimit = Math.max(overfetchLimit, options.rerankTopN * 3, options.limit * 6);
   const rerankPool = fused.slice(0, rerankPoolLimit);
-  const intent = classifyQueryIntentRaw(query);
   return rerankResults(query, rerankPool, options.rerankTopN, {
-    prioritizeSourcePaths: intent === "source"
+    prioritizeSourcePaths: options.prioritizeSourcePaths ?? classifyQueryIntentRaw(query) === "source"
   });
 }
 function rankSemanticOnlyResults(query, semanticResults, options) {
@@ -4170,11 +4261,11 @@ function rankSemanticOnlyResults(query, semanticResults, options) {
     prioritizeSourcePaths: options.prioritizeSourcePaths ?? false
   });
 }
-function promoteIdentifierMatches(query, combined, semanticCandidates, keywordCandidates, database, branchChunkIds) {
+function promoteIdentifierMatches(query, combined, semanticCandidates, keywordCandidates, database, branchChunkIds, prioritizeSourcePaths = classifyQueryIntentRaw(query) === "source") {
   if (combined.length === 0) {
     return combined;
   }
-  if (classifyQueryIntentRaw(query) !== "source") {
+  if (!prioritizeSourcePaths) {
     return combined;
   }
   const identifierHints = extractIdentifierHints(query);
@@ -4264,8 +4355,8 @@ function promoteIdentifierMatches(query, combined, semanticCandidates, keywordCa
   const remainder = combined.filter((candidate) => !promotedIds.has(candidate.id));
   return [...promoted, ...remainder];
 }
-function buildSymbolDefinitionLane(query, database, branchChunkIds, limit, fallbackCandidates) {
-  if (classifyQueryIntentRaw(query) !== "source") {
+function buildSymbolDefinitionLane(query, database, branchChunkIds, limit, fallbackCandidates, prioritizeSourcePaths = classifyQueryIntentRaw(query) === "source") {
+  if (!prioritizeSourcePaths) {
     return [];
   }
   const identifierHints = extractIdentifierHints(query);
@@ -4410,8 +4501,8 @@ function buildSymbolDefinitionLane(query, database, branchChunkIds, limit, fallb
   const withFallback = Array.from(symbolCandidates.values()).sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
   return withFallback.slice(0, Math.max(limit * 2, limit));
 }
-function buildIdentifierDefinitionLane(query, candidates, limit) {
-  if (classifyQueryIntentRaw(query) !== "source") {
+function buildIdentifierDefinitionLane(query, candidates, limit, prioritizeSourcePaths = classifyQueryIntentRaw(query) === "source") {
+  if (!prioritizeSourcePaths) {
     return [];
   }
   const primaryHint = extractPrimaryIdentifierQueryHint(query);
@@ -5343,6 +5434,7 @@ var Indexer = class {
     const rrfK = this.config.search.rrfK;
     const rerankTopN = this.config.search.rerankTopN;
     const filterByBranch = options?.filterByBranch ?? true;
+    const sourceIntent = options?.definitionIntent === true || classifyQueryIntentRaw(query) === "source";
     this.logger.search("debug", "Starting search", {
       query,
       maxResults,
@@ -5394,7 +5486,8 @@ var Indexer = class {
       rrfK,
       rerankTopN,
       limit: maxResults,
-      hybridWeight
+      hybridWeight,
+      prioritizeSourcePaths: sourceIntent
     });
     const fusionMs = performance2.now() - fusionStartTime;
     const rescued = promoteIdentifierMatches(
@@ -5403,30 +5496,33 @@ var Indexer = class {
       semanticCandidates,
       keywordCandidates,
       database,
-      branchChunkIds
+      branchChunkIds,
+      sourceIntent
     );
     const union = unionCandidates(semanticCandidates, keywordCandidates);
     const deterministicIdentifierLane = buildDeterministicIdentifierPass(
       query,
       union,
-      maxResults
+      maxResults,
+      sourceIntent
     );
     const identifierLane = buildIdentifierDefinitionLane(
       query,
       union,
-      maxResults
+      maxResults,
+      sourceIntent
     );
     const symbolLane = buildSymbolDefinitionLane(
       query,
       database,
       branchChunkIds,
       maxResults,
-      union
+      union,
+      sourceIntent
     );
     const prePrimaryLane = mergeTieredResults(deterministicIdentifierLane, identifierLane, maxResults * 4);
     const primaryLane = mergeTieredResults(prePrimaryLane, symbolLane, maxResults * 4);
     const tiered = mergeTieredResults(primaryLane, rescued, maxResults * 4);
-    const sourceIntent = classifyQueryIntentRaw(query) === "source";
     const hasCodeHints = extractCodeTermHints(query).length > 0 || extractIdentifierHints(query).length > 0;
     const baseFiltered = tiered.filter((r) => {
       if (r.score < this.config.search.minScore) return false;
@@ -7872,6 +7968,22 @@ function formatLogs(logs) {
     return `[${l.timestamp}] [${l.level.toUpperCase()}] [${l.category}] ${l.message}${dataStr}`;
   }).join("\n");
 }
+function formatDefinitionLookup(results, query) {
+  if (results.length === 0) {
+    return `No definition found for "${query}". Try codebase_search for broader discovery, or verify the symbol name.`;
+  }
+  const formatted = results.map((r, idx) => {
+    const header2 = r.name ? `[${idx + 1}] ${r.chunkType} "${r.name}" in ${r.filePath}:${r.startLine}-${r.endLine}` : `[${idx + 1}] ${r.chunkType} in ${r.filePath}:${r.startLine}-${r.endLine}`;
+    return `${header2} (score: ${r.score.toFixed(2)})
+\`\`\`
+${truncateContent(r.content)}
+\`\`\``;
+  });
+  const header = results.length === 1 ? `Definition found for "${query}":` : `Found ${results.length} definition candidates for "${query}":`;
+  return `${header}
+
+${formatted.join("\n\n")}`;
+}
 function formatSearchResults(results, scoreFormat = "similarity") {
   const formatted = results.map((r, idx) => {
     const header = r.name ? `[${idx + 1}] ${r.chunkType} "${r.name}" in ${r.filePath}:${r.startLine}-${r.endLine}` : `[${idx + 1}] ${r.chunkType} in ${r.filePath}:${r.startLine}-${r.endLine}`;
@@ -8057,6 +8169,24 @@ var codebase_search = tool({
 ${formatSearchResults(results, "score")}`;
   }
 });
+var implementation_lookup = tool({
+  description: "Jump to symbol definition. Find WHERE something is defined. Returns the authoritative source location(s) for a function, class, method, type, or variable. Prefers real implementation files over tests, docs, examples, and fixtures. Use when you need the definition site, not all usages.",
+  args: {
+    query: z.string().describe("Symbol name or natural language description (e.g., 'validateToken', 'where is the payment handler defined')"),
+    limit: z.number().optional().default(5).describe("Maximum number of results"),
+    fileType: z.string().optional().describe("Filter by file extension (e.g., 'ts', 'py')"),
+    directory: z.string().optional().describe("Filter by directory path (e.g., 'src/utils')")
+  },
+  async execute(args) {
+    const indexer = getIndexer();
+    const results = await indexer.search(args.query, args.limit ?? 5, {
+      fileType: args.fileType,
+      directory: args.directory,
+      definitionIntent: true
+    });
+    return formatDefinitionLookup(results, args.query);
+  }
+});
 var call_graph = tool({
   description: "Query the call graph to find callers or callees of a function/method. Use to understand code flow and dependencies between functions.",
   args: {
@@ -8197,7 +8327,8 @@ var plugin = async ({ directory }) => {
       index_metrics,
       index_logs,
       find_similar,
-      call_graph
+      call_graph,
+      implementation_lookup
     },
     async config(cfg) {
       cfg.command = cfg.command ?? {};