sparkecoder 0.1.57 → 0.1.59

package/dist/agent/index.js

@@ -1071,13 +1071,13 @@ var semantic_search_exports = {};
 __export(semantic_search_exports, {
   createSemanticSearchTool: () => createSemanticSearchTool
 });
-import { tool as tool7 } from "ai";
-import { z as z8 } from "zod";
-import { existsSync as existsSync10, readFileSync as readFileSync4 } from "fs";
+import { tool as tool8 } from "ai";
+import { z as z9 } from "zod";
+import { existsSync as existsSync11, readFileSync as readFileSync4 } from "fs";
 import { join as join4 } from "path";
 import { minimatch as minimatch3 } from "minimatch";
 function createSemanticSearchTool(options) {
-  return tool7({
+  return tool8({
     description: `Search the codebase using semantic similarity. This tool finds code by understanding its meaning, not just matching text.
 
 Use this tool when:
@@ -1142,7 +1142,7 @@ Returns matching code snippets with file paths, line numbers, and relevance scor
               continue;
             }
             const fullPath = join4(options.workingDirectory, filePath);
-            if (!existsSync10(fullPath)) {
+            if (!existsSync11(fullPath)) {
               continue;
             }
             let snippet = "";
@@ -1197,11 +1197,11 @@ var init_semantic_search = __esm({
     "use strict";
     init_semantic();
     init_config();
-    semanticSearchInputSchema = z8.object({
-      query: z8.string().describe("Natural language search query describing what you want to find"),
-      topK: z8.number().optional().default(10).describe("Number of results to return (default: 10, max: 50)"),
-      filePattern: z8.string().optional().describe('Filter results by file glob pattern (e.g., "*.ts", "src/**/*.py")'),
-      language: z8.string().optional().describe('Filter by programming language (e.g., "typescript", "python")')
+    semanticSearchInputSchema = z9.object({
+      query: z9.string().describe("Natural language search query describing what you want to find"),
+      topK: z9.number().optional().default(10).describe("Number of results to return (default: 10, max: 50)"),
+      filePattern: z9.string().optional().describe('Filter results by file glob pattern (e.g., "*.ts", "src/**/*.py")'),
+      language: z9.string().optional().describe('Filter by programming language (e.g., "typescript", "python")')
     });
   }
 });
@@ -1210,7 +1210,7 @@ var init_semantic_search = __esm({
 import {
   streamText as streamText2,
   generateText as generateText3,
-  tool as tool10,
+  tool as tool11,
   stepCountIs as stepCountIs2
 } from "ai";
 
@@ -1233,7 +1233,7 @@ var SUBAGENT_MODELS = {
 // src/agent/index.ts
 init_db();
 init_config();
-import { z as z11 } from "zod";
+import { z as z12 } from "zod";
 import { nanoid as nanoid3 } from "nanoid";
 
 // src/tools/bash.ts
@@ -2140,7 +2140,11 @@ async function createClient(serverId, handle, root) {
           dynamicRegistration: true
         },
         documentSymbol: {
-          dynamicRegistration: true
+          dynamicRegistration: true,
+          hierarchicalDocumentSymbolSupport: true,
+          symbolKind: {
+            valueSet: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26]
+          }
         }
       },
       workspace: {
@@ -2237,7 +2241,7 @@ async function createClient(serverId, handle, root) {
     },
     async waitForDiagnostics(filePath, timeoutMs = 5e3) {
       const normalized = normalizePath(filePath);
-      return new Promise((resolve9) => {
+      return new Promise((resolve10) => {
         const startTime = Date.now();
         let debounceTimer;
         let resolved = false;
@@ -2256,7 +2260,7 @@ async function createClient(serverId, handle, root) {
           if (resolved) return;
           resolved = true;
           cleanup();
-          resolve9(diagnostics.get(normalized) || []);
+          resolve10(diagnostics.get(normalized) || []);
         };
         const onDiagnostic = () => {
           if (debounceTimer) clearTimeout(debounceTimer);
@@ -2282,6 +2286,100 @@ async function createClient(serverId, handle, root) {
     getAllDiagnostics() {
       return new Map(diagnostics);
     },
+    async getDefinition(filePath, line, character) {
+      const normalized = normalizePath(filePath);
+      if (!fileVersions.has(normalized)) {
+        await client.notifyOpen(normalized);
+      }
+      try {
+        const result = await connection.sendRequest("textDocument/definition", {
+          textDocument: { uri: pathToFileURL(normalized).href },
+          position: { line, character }
+        });
+        if (!result) return [];
+        const items = Array.isArray(result) ? result : [result];
+        return items.map((r) => ({
+          uri: r.targetUri || r.uri,
+          range: r.targetRange || r.range
+        }));
+      } catch (error) {
+        console.error("[lsp] Error getting definition:", error);
+        return [];
+      }
+    },
+    async getReferences(filePath, line, character, includeDeclaration = false) {
+      const normalized = normalizePath(filePath);
+      if (!fileVersions.has(normalized)) {
+        await client.notifyOpen(normalized);
+      }
+      try {
+        const result = await connection.sendRequest("textDocument/references", {
+          textDocument: { uri: pathToFileURL(normalized).href },
+          position: { line, character },
+          context: { includeDeclaration }
+        });
+        return result || [];
+      } catch (error) {
+        console.error("[lsp] Error getting references:", error);
+        return [];
+      }
+    },
+    async getHover(filePath, line, character) {
+      const normalized = normalizePath(filePath);
+      if (!fileVersions.has(normalized)) {
+        await client.notifyOpen(normalized);
+      }
+      try {
+        const result = await connection.sendRequest("textDocument/hover", {
+          textDocument: { uri: pathToFileURL(normalized).href },
+          position: { line, character }
+        });
+        if (!result || !result.contents) return null;
+        if (typeof result.contents === "string") return result.contents;
+        if (result.contents.value) return result.contents.value;
+        if (Array.isArray(result.contents)) {
+          return result.contents.map((c) => typeof c === "string" ? c : c.value).join("\n");
+        }
+        return null;
+      } catch (error) {
+        console.error("[lsp] Error getting hover:", error);
+        return null;
+      }
+    },
+    async getDocumentSymbols(filePath) {
+      const normalized = normalizePath(filePath);
+      if (!fileVersions.has(normalized)) {
+        await client.notifyOpen(normalized);
+      }
+      try {
+        const result = await connection.sendRequest("textDocument/documentSymbol", {
+          textDocument: { uri: pathToFileURL(normalized).href }
+        });
+        if (!result || result.length === 0) return [];
+        if (result[0].range) {
+          return result;
+        }
+        return result.map((si) => ({
+          name: si.name,
+          kind: si.kind,
+          range: si.location?.range ?? { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } },
+          selectionRange: si.location?.range ?? { start: { line: 0, character: 0 }, end: { line: 0, character: 0 } },
+          detail: si.containerName
+        }));
+      } catch (error) {
+        console.error("[lsp] Error getting document symbols:", error);
+        return [];
+      }
+    },
+    async findWorkspaceSymbols(query) {
+      try {
+        const result = await connection.sendRequest("workspace/symbol", { query });
+        return result || [];
+      } catch (error) {
+        console.error("[lsp] Error finding workspace symbols:", error);
+        return [];
+      }
+    },
     async shutdown() {
       try {
         await connection.sendRequest("shutdown");
@@ -2404,6 +2502,24 @@ async function getAllDiagnostics() {
   }
   return results;
 }
+async function getReferences(filePath, line, character, includeDeclaration = false) {
+  const normalized = normalizePath(filePath);
+  const client = await getClientForFile(normalized);
+  if (!client) return [];
+  return client.getReferences(normalized, line, character, includeDeclaration);
+}
+async function getHover(filePath, line, character) {
+  const normalized = normalizePath(filePath);
+  const client = await getClientForFile(normalized);
+  if (!client) return null;
+  return client.getHover(normalized, line, character);
+}
+async function getDocumentSymbols(filePath) {
+  const normalized = normalizePath(filePath);
+  const client = await getClientForFile(normalized);
+  if (!client) return [];
+  return client.getDocumentSymbols(normalized);
+}
 async function formatDiagnosticsOutput(filePath, options = {}) {
   const diagnostics = await getDiagnostics(filePath);
   return formatDiagnosticsForAgent(filePath, diagnostics, options);
@@ -2499,7 +2615,7 @@ Working directory: ${options.workingDirectory}`,
                 isChunked: true
               });
               if (chunkCount > 1) {
-                await new Promise((resolve9) => setTimeout(resolve9, 0));
+                await new Promise((resolve10) => setTimeout(resolve10, 0));
               }
             }
           }
@@ -3027,8 +3143,8 @@ ${file.relativePath}:`);
 }
 
 // src/tools/search.ts
-import { tool as tool9 } from "ai";
-import { z as z10 } from "zod";
+import { tool as tool10 } from "ai";
+import { z as z11 } from "zod";
 
 // src/agent/subagent.ts
 import {
@@ -3200,8 +3316,8 @@ var Subagent = class {
       if (eventQueue.length > 0) {
         yield eventQueue.shift();
       } else if (!done) {
-        const event = await new Promise((resolve9) => {
-          resolveNext = resolve9;
+        const event = await new Promise((resolve10) => {
+          resolveNext = resolve10;
         });
         if (event) {
           yield event;
@@ -3213,14 +3329,466 @@ var Subagent = class {
 };
 
 // src/agent/subagents/search.ts
-import { tool as tool8 } from "ai";
-import { z as z9 } from "zod";
+import { tool as tool9 } from "ai";
+import { z as z10 } from "zod";
 import { exec as exec4 } from "child_process";
 import { promisify as promisify4 } from "util";
-import { readFile as readFile7, stat as stat3, readdir as readdir3 } from "fs/promises";
-import { resolve as resolve8, relative as relative7, isAbsolute as isAbsolute4 } from "path";
-import { existsSync as existsSync11 } from "fs";
+import { readFile as readFile8, stat as stat3, readdir as readdir4 } from "fs/promises";
+import { resolve as resolve9, relative as relative8, isAbsolute as isAbsolute5 } from "path";
+import { existsSync as existsSync12 } from "fs";
 init_semantic();
+
+// src/tools/code-graph.ts
+import { tool as tool7 } from "ai";
+import { z as z8 } from "zod";
+import { resolve as resolve8, relative as relative7, isAbsolute as isAbsolute4, basename as basename3 } from "path";
+import { readFile as readFile7, readdir as readdir3 } from "fs/promises";
+import { existsSync as existsSync10 } from "fs";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { execFileSync } from "child_process";
+var codeGraphInputSchema = z8.object({
+  symbol: z8.string().describe(
+    "The symbol name to inspect (function, component, class, type, variable, etc.)"
+  ),
+  filePath: z8.string().optional().describe(
+    "File path where the symbol is defined. If omitted, searches the workspace via grep."
+  ),
+  depth: z8.number().optional().default(2).describe(
+    "How many levels of references to traverse upward (default: 2, max: 3). Level 1 = direct usages, level 2 = usages of those usages."
+  )
+});
+function isPageFile(filePath) {
+  const normalized = filePath.replace(/\\/g, "/");
+  if (/\/app\/(.+\/)?(page|layout|loading|error|not-found)\.(tsx?|jsx?)$/.test(normalized)) return true;
+  if (/\/pages\/(?!_|api\/).+\.(tsx?|jsx?)$/.test(normalized)) return true;
+  return false;
+}
+function extractRoutePath(filePath, workingDirectory) {
+  const rel = relative7(workingDirectory, filePath).replace(/\\/g, "/");
+  const appMatch = rel.match(/(?:src\/)?app((?:\/[^/]+)*?)\/(?:page|layout|loading|error|not-found)\.\w+$/);
+  if (appMatch) return appMatch[1] || "/";
+  const pagesMatch = rel.match(/(?:src\/)?pages(\/.*?)(?:\/index)?\.\w+$/);
+  if (pagesMatch) return pagesMatch[1] || "/";
+  return void 0;
+}
+function symbolKindName(kind) {
+  const names = {
+    [5 /* Class */]: "class",
+    [12 /* Function */]: "function",
+    [6 /* Method */]: "method",
+    [7 /* Property */]: "property",
+    [13 /* Variable */]: "variable",
+    [11 /* Interface */]: "interface",
+    [10 /* Enum */]: "enum",
+    [14 /* Constant */]: "constant",
+    [9 /* Constructor */]: "constructor",
+    [2 /* Module */]: "module",
+    [3 /* Namespace */]: "namespace",
+    [26 /* TypeParameter */]: "type_param",
+    [8 /* Field */]: "field",
+    [22 /* EnumMember */]: "enum_member",
+    [19 /* Object */]: "object"
+  };
+  return names[kind] || "symbol";
+}
+function findContainingSymbol(symbols, line, character) {
+  for (const sym of symbols) {
+    if (!sym.range) continue;
+    const { start, end } = sym.range;
+    const afterStart = line > start.line || line === start.line && character >= start.character;
+    const beforeEnd = line < end.line || line === end.line && character < end.character;
+    if (afterStart && beforeEnd) {
+      if (sym.children?.length) {
+        const child = findContainingSymbol(sym.children, line, character);
+        if (child) return child;
+      }
+      return sym;
+    }
+  }
+  return null;
+}
+function findSymbolByName(symbols, name) {
+  for (const sym of symbols) {
+    if (sym.name === name && sym.selectionRange) return sym;
+    if (sym.children) {
+      const found = findSymbolByName(sym.children, name);
+      if (found) return found;
+    }
+  }
+  return null;
+}
+function cleanHoverText(text) {
+  return text.replace(/```\w*\n?/g, "").replace(/\n```/g, "").trim();
+}
+async function grepForSymbol(symbol, workingDirectory) {
+  const escaped = symbol.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const rgPatterns = [
+    `(export\\s+)?(default\\s+)?(function|const|let|var|class|interface|type|enum)\\s+${escaped}\\b`,
+    `(export\\s+)?(default\\s+)?\\b${escaped}\\s*[=:(]`
+  ];
+  for (const pattern of rgPatterns) {
+    try {
+      const result = execFileSync("rg", [
+        "-n",
+        "--no-heading",
+        "-e",
+        pattern,
+        "--glob",
+        "*.{ts,tsx,js,jsx}",
+        "-m",
+        "5"
+      ], {
+        cwd: workingDirectory,
+        encoding: "utf-8",
+        timeout: 5e3,
+        stdio: ["pipe", "pipe", "pipe"]
+      }).trim();
+      if (result) {
+        const firstLine = result.split("\n")[0];
+        const match = firstLine.match(/^(.+?):(\d+):(.*)/);
+        if (match) {
+          const col = match[3].indexOf(symbol);
+          return {
+            filePath: resolve8(workingDirectory, match[1]),
+            line: parseInt(match[2]) - 1,
+            char: col >= 0 ? col : 0
+          };
+        }
+      }
+    } catch {
+    }
+  }
+  const defPattern = new RegExp(
+    `(export|function|const|let|var|class|interface|type|enum)\\s+.*\\b${escaped}\\b`
+  );
+  const SUPPORTED_EXTS = /* @__PURE__ */ new Set([".ts", ".tsx", ".js", ".jsx"]);
+  const IGNORED_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "build", ".next", "coverage"]);
+  async function search(dir, maxFiles) {
+    if (maxFiles <= 0) return null;
+    let remaining = maxFiles;
+    try {
+      const entries = await readdir3(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (remaining <= 0) return null;
+        const fullPath = resolve8(dir, entry.name);
+        if (entry.isDirectory()) {
+          if (IGNORED_DIRS.has(entry.name) || entry.name.startsWith(".")) continue;
+          const found = await search(fullPath, remaining);
+          if (found) return found;
+          remaining -= 10;
+        } else if (entry.isFile()) {
+          const ext = entry.name.substring(entry.name.lastIndexOf("."));
+          if (!SUPPORTED_EXTS.has(ext)) continue;
+          remaining--;
+          const content = await readFile7(fullPath, "utf-8");
+          const lines = content.split("\n");
+          for (let i = 0; i < lines.length; i++) {
+            if (defPattern.test(lines[i])) {
+              const col = lines[i].indexOf(symbol);
+              if (col >= 0) {
+                return { filePath: fullPath, line: i, char: col };
+              }
+            }
+          }
+        }
+      }
+    } catch {
+    }
+    return null;
+  }
+  return search(workingDirectory, 200);
+}
+var MAX_REF_FILES = 15;
+var MAX_LEVEL2_PARENTS = 8;
+var MAX_LEVEL2_SYMBOLS_PER_PARENT = 3;
+function createCodeGraphTool(options) {
+  return tool7({
+    description: `Inspect a symbol's type information and usage graph using the TypeScript language server.
+
+Given a symbol name (function, component, class, type, etc.), this tool will:
+1. Find its definition and full type signature (parameters, return type)
+2. Find all references \u2014 what components/functions/files use this symbol
+3. Identify which pages/routes contain it in their component tree
+4. Show the file's symbol structure for surrounding context
+
+Use this to understand:
+- Component hierarchies (what renders what, which pages are affected)
+- Type signatures and parameter/return types before making changes
+- How deeply a symbol is used across the codebase
+- What will break if you change something
+
+Supports TypeScript, JavaScript, TSX, JSX files.
+Working directory: ${options.workingDirectory}`,
+    inputSchema: codeGraphInputSchema,
+    execute: async ({ symbol, filePath, depth }) => {
+      const maxDepth = Math.min(depth ?? 2, 3);
+      try {
+        let defFilePath;
+        let defLine = 0;
+        let defChar = 0;
+        let defSymbol = null;
+        if (filePath) {
+          const absPath = isAbsolute4(filePath) ? filePath : resolve8(options.workingDirectory, filePath);
+          if (!existsSync10(absPath)) {
+            return { success: false, error: `File not found: ${filePath}` };
+          }
+          if (!isSupported(absPath)) {
+            return { success: false, error: `File type not supported. Supports: ${getSupportedExtensions().join(", ")}` };
+          }
+          await touchFile(absPath, true);
+          const symbols = await getDocumentSymbols(absPath);
+          defSymbol = findSymbolByName(symbols, symbol);
+          if (defSymbol) {
+            defFilePath = absPath;
+            defLine = defSymbol.selectionRange.start.line;
+            defChar = defSymbol.selectionRange.start.character;
+          } else {
+            const content = await readFile7(absPath, "utf-8");
+            const lines2 = content.split("\n");
+            const defPattern = new RegExp(
+              `(export|function|const|let|var|class|interface|type|enum)\\s+.*\\b${symbol.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\\b`
+            );
+            for (let i = 0; i < lines2.length; i++) {
+              if (defPattern.test(lines2[i])) {
+                const col = lines2[i].indexOf(symbol);
+                if (col !== -1) {
+                  defFilePath = absPath;
+                  defLine = i;
+                  defChar = col;
+                  break;
+                }
+              }
+            }
+            if (!defFilePath) {
+              for (let i = 0; i < lines2.length; i++) {
+                const col = lines2[i].indexOf(symbol);
+                if (col !== -1) {
+                  defFilePath = absPath;
+                  defLine = i;
+                  defChar = col;
+                  break;
+                }
+              }
+            }
+          }
+        } else {
+          const found = await grepForSymbol(symbol, options.workingDirectory);
+          if (found) {
+            defFilePath = found.filePath;
+            defLine = found.line;
+            defChar = found.char;
+          }
+        }
+        if (!defFilePath) {
+          return {
+            success: false,
+            error: `Could not find symbol "${symbol}" in the codebase. Try providing a filePath.`
+          };
+        }
+        await touchFile(defFilePath, true);
+        const rawHover = await getHover(defFilePath, defLine, defChar);
+        const typeInfo = rawHover ? cleanHoverText(rawHover) : null;
+        const fileSymbols = await getDocumentSymbols(defFilePath);
+        if (!defSymbol && fileSymbols.length > 0) {
+          defSymbol = findSymbolByName(fileSymbols, symbol);
+        }
+        const references = await getReferences(defFilePath, defLine, defChar, false);
+        const refsByFile = /* @__PURE__ */ new Map();
+        for (const ref of references) {
+          const refPath = fileURLToPath2(ref.uri);
+          if (!refsByFile.has(refPath)) {
+            refsByFile.set(refPath, []);
+          }
+          refsByFile.get(refPath).push(ref);
+        }
+        const refFileInfos = [];
+        let processed = 0;
+        for (const [refPath, locs] of refsByFile) {
+          if (processed >= MAX_REF_FILES) break;
+          if (refPath === defFilePath) continue;
+          processed++;
+          const relPath = relative7(options.workingDirectory, refPath);
+          const pageFile = isPageFile(refPath);
+          const routePath = pageFile ? extractRoutePath(refPath, options.workingDirectory) : void 0;
+          await touchFile(refPath, false);
+          const refFileSymbols = await getDocumentSymbols(refPath);
+          const seen = /* @__PURE__ */ new Map();
+          for (const loc of locs) {
+            const container = findContainingSymbol(
+              refFileSymbols,
+              loc.range.start.line,
+              loc.range.start.character
+            );
+            if (container && !seen.has(container.name)) {
+              let containerHover = null;
+              try {
+                const raw = await getHover(
+                  refPath,
+                  container.selectionRange.start.line,
+                  container.selectionRange.start.character
+                );
+                if (raw) containerHover = cleanHoverText(raw).split("\n")[0];
+              } catch {
+              }
+              seen.set(container.name, {
+                name: container.name,
+                kind: symbolKindName(container.kind),
+                line: container.selectionRange.start.line + 1,
+                char: container.selectionRange.start.character,
+                typeInfo: containerHover || void 0
+              });
+            }
+          }
+          refFileInfos.push({
+            filePath: refPath,
+            relativePath: relPath,
+            isPage: pageFile,
+            routePath,
+            containingSymbols: Array.from(seen.values())
+          });
+        }
+        const level2Refs = [];
+        if (maxDepth >= 2) {
+          for (const refFile of refFileInfos.slice(0, MAX_LEVEL2_PARENTS)) {
+            for (const sym of refFile.containingSymbols.slice(0, MAX_LEVEL2_SYMBOLS_PER_PARENT)) {
+              try {
+                const symLineIdx = sym.line - 1;
+                const symChar = sym.char;
+                const l2Locations = await getReferences(
+                  refFile.filePath,
+                  symLineIdx,
+                  symChar,
+                  false
+                );
+                const l2Nodes = [];
+                const seenPaths = /* @__PURE__ */ new Set();
+                for (const loc of l2Locations.slice(0, 10)) {
+                  const l2Path = fileURLToPath2(loc.uri);
+                  if (l2Path === refFile.filePath || l2Path === defFilePath) continue;
+                  if (seenPaths.has(l2Path)) continue;
+                  seenPaths.add(l2Path);
+                  const l2Rel = relative7(options.workingDirectory, l2Path);
+                  const l2Page = isPageFile(l2Path);
+                  const l2Route = l2Page ? extractRoutePath(l2Path, options.workingDirectory) : void 0;
+                  let containerName;
+                  try {
+                    await touchFile(l2Path, false);
+                    const l2Symbols = await getDocumentSymbols(l2Path);
+                    const container = findContainingSymbol(l2Symbols, loc.range.start.line, loc.range.start.character);
+                    if (container) containerName = container.name;
+                  } catch {
+                  }
+                  l2Nodes.push({
+                    relativePath: l2Rel,
+                    isPage: l2Page,
+                    routePath: l2Route,
+                    containingSymbol: containerName
+                  });
+                }
+                if (l2Nodes.length > 0) {
+                  level2Refs.push({
+                    parentSymbol: sym.name,
+                    parentFile: refFile.relativePath,
+                    refs: l2Nodes
+                  });
+                }
+              } catch {
+              }
+            }
+          }
+        }
+        const relDefPath = relative7(options.workingDirectory, defFilePath);
+        const lines = [];
+        lines.push(`=== ${symbol} ===`);
+        lines.push(`File: ${relDefPath}:${defLine + 1}`);
+        if (defSymbol) lines.push(`Kind: ${symbolKindName(defSymbol.kind)}`);
+        if (typeInfo) lines.push(`Type: ${typeInfo}`);
+        const externalRefCount = references.filter((r) => fileURLToPath2(r.uri) !== defFilePath).length;
+        const externalFileCount = refsByFile.size - (refsByFile.has(defFilePath) ? 1 : 0);
+        if (refFileInfos.length > 0) {
+          lines.push("");
+          lines.push(`=== Referenced by (${externalRefCount} usages across ${externalFileCount} files) ===`);
+          const pages = refFileInfos.filter((r) => r.isPage);
+          const nonPages = refFileInfos.filter((r) => !r.isPage);
+          if (pages.length > 0) {
+            lines.push("");
+            lines.push("Pages/Routes:");
+            for (const page of pages) {
+              lines.push(`  ${page.relativePath}${page.routePath ? ` \u2192 ${page.routePath}` : ""}`);
+              for (const s of page.containingSymbols) {
+                lines.push(`    \u2514\u2500\u2500 ${s.name} (${s.kind}:${s.line})${s.typeInfo ? ` \u2014 ${s.typeInfo}` : ""}`);
+              }
+            }
+          }
+          if (nonPages.length > 0) {
+            lines.push("");
+            lines.push("Components/Functions:");
+            for (const ref of nonPages) {
+              lines.push(`  ${ref.relativePath}`);
+              for (const s of ref.containingSymbols) {
+                const typePart = s.typeInfo && s.typeInfo.length < 120 ? ` \u2014 ${s.typeInfo}` : "";
+                lines.push(`    \u2514\u2500\u2500 ${s.name} (${s.kind}:${s.line})${typePart}`);
+              }
+            }
+          }
+        } else {
+          lines.push("");
+          lines.push("No external references found (symbol may be unused or only used within the same file).");
+        }
+        if (level2Refs.length > 0) {
+          lines.push("");
+          lines.push("=== Extended tree (level 2) ===");
+          for (const l2 of level2Refs) {
+            lines.push("");
+            lines.push(`${l2.parentSymbol} (${l2.parentFile}) is used by:`);
+            for (const ref of l2.refs) {
+              const tag = ref.isPage ? " [PAGE]" : "";
+              const route = ref.routePath ? ` \u2192 ${ref.routePath}` : "";
+              const container = ref.containingSymbol ? ` in ${ref.containingSymbol}` : "";
+              lines.push(`  \u2514\u2500\u2500 ${ref.relativePath}${tag}${route}${container}`);
+            }
+          }
+        }
+        if (fileSymbols.length > 0) {
+          lines.push("");
+          lines.push(`=== File structure (${basename3(defFilePath)}) ===`);
+          for (const sym of fileSymbols) {
+            const marker = sym.name === symbol ? "  \u2190 target" : "";
+            lines.push(`  ${sym.name} (${symbolKindName(sym.kind)}:${sym.selectionRange.start.line + 1})${marker}`);
+            if (sym.children) {
+              for (const child of sym.children.slice(0, 10)) {
+                lines.push(`    \u2514\u2500\u2500 ${child.name} (${symbolKindName(child.kind)}:${child.selectionRange.start.line + 1})`);
+              }
+              if (sym.children.length > 10) {
+                lines.push(`    ... and ${sym.children.length - 10} more`);
+              }
+            }
+          }
+        }
+        const formattedResult = lines.join("\n");
+        return {
+          success: true,
+          symbol,
+          filePath: relDefPath,
+          line: defLine + 1,
+          kind: defSymbol ? symbolKindName(defSymbol.kind) : void 0,
+          typeInfo: typeInfo || void 0,
+          referenceCount: externalRefCount,
+          referenceFiles: externalFileCount,
+          pages: refFileInfos.filter((r) => r.isPage).map((r) => ({ path: r.relativePath, route: r.routePath })),
+          formattedResult
+        };
+      } catch (error) {
+        return {
+          success: false,
+          error: error instanceof Error ? error.message : String(error)
+        };
+      }
+    }
+  });
+}
+
+// src/agent/subagents/search.ts
 var execAsync4 = promisify4(exec4);
 var MAX_OUTPUT_CHARS4 = 1e4;
 var MAX_FILE_SIZE3 = 1 * 1024 * 1024;
@@ -3250,17 +3818,20 @@ ${contextBlock}
 - **glob**: Find files matching a name pattern. Best for file discovery.
 - **read_file**: Read contents of a specific file. Use to examine code found in searches.
 - **list_dir**: List directory contents. Use to understand project structure.
+- **code_graph**: Inspect a symbol's type hierarchy, references, and usage graph via the TypeScript language server. Returns type signatures, all files that reference the symbol, and which pages/routes contain it. Best for understanding component/function relationships and impact analysis.
 
 ## Search Strategy
 
 1. **Start with semantic_search** if available - it finds code by meaning, which is the fastest way to explore
 2. **Use grep** for exact symbol/string matches (function names, class names, imports)
-3. **Use glob** for file discovery by name patterns
-4. **Read key files** to get actual code content and understand context
-5. **Run searches in PARALLEL** - make multiple tool calls at once to cover different angles simultaneously. This is critical for speed.
+3. **Use code_graph** when you need to understand a symbol's type signature, what depends on it, or which pages use it. It's much more precise than grep for understanding relationships.
+4. **Use glob** for file discovery by name patterns
+5. **Read key files** to get actual code content and understand context
+6. **Run searches in PARALLEL** - make multiple tool calls at once to cover different angles simultaneously. This is critical for speed.
 
 ### Tool Selection Guide
 - Know the exact name? Use **grep** (e.g. \`getUserById\`, \`class AuthService\`)
+- Need type info, references, or impact analysis? Use **code_graph** (e.g. \`code_graph({ symbol: "UserCard" })\`)
 - Exploring a concept? Use **semantic_search** (e.g. "how does authentication work")
 - Looking for files? Use **glob** (e.g. \`**/*.config.ts\`, \`**/auth/**\`)
 - Need file content? Use **read_file** with optional line ranges for large files
@@ -3297,17 +3868,17 @@ Keep it concise but INCLUDE THE ACTUAL DATA.`;
   async getToolsAsync(options) {
     const workingDirectory = options.workingDirectory;
     const tools = {
-      grep: tool8({
+      grep: tool9({
         description: "Search for patterns in files using ripgrep. Returns matching lines with file paths and line numbers.",
-        inputSchema: z9.object({
-          pattern: z9.string().describe("The regex pattern to search for"),
-          path: z9.string().optional().describe("Subdirectory or file to search in (relative to working directory)"),
-          fileType: z9.string().optional().describe('File type to filter (e.g., "ts", "js", "py")'),
-          maxResults: z9.number().optional().default(50).describe("Maximum number of results to return")
+        inputSchema: z10.object({
+          pattern: z10.string().describe("The regex pattern to search for"),
+          path: z10.string().optional().describe("Subdirectory or file to search in (relative to working directory)"),
+          fileType: z10.string().optional().describe('File type to filter (e.g., "ts", "js", "py")'),
+          maxResults: z10.number().optional().default(50).describe("Maximum number of results to return")
         }),
         execute: async ({ pattern, path, fileType, maxResults }) => {
           try {
-            const searchPath = path ? resolve8(workingDirectory, path) : workingDirectory;
+            const searchPath = path ? resolve9(workingDirectory, path) : workingDirectory;
             let args = ["rg", "--line-number", "--no-heading"];
             if (fileType) {
               args.push("--type", fileType);
@@ -3344,11 +3915,11 @@ Keep it concise but INCLUDE THE ACTUAL DATA.`;
           }
         }
       }),
-      glob: tool8({
+      glob: tool9({
         description: "Find files matching a glob pattern. Returns list of matching file paths.",
-        inputSchema: z9.object({
-          pattern: z9.string().describe('Glob pattern (e.g., "**/*.ts", "src/**/*.tsx", "*.json")'),
-          maxResults: z9.number().optional().default(100).describe("Maximum number of files to return")
+        inputSchema: z10.object({
+          pattern: z10.string().describe('Glob pattern (e.g., "**/*.ts", "src/**/*.tsx", "*.json")'),
+          maxResults: z10.number().optional().default(100).describe("Maximum number of files to return")
         }),
         execute: async ({ pattern, maxResults }) => {
           try {
@@ -3375,17 +3946,17 @@ Keep it concise but INCLUDE THE ACTUAL DATA.`;
           }
         }
       }),
-      read_file: tool8({
+      read_file: tool9({
         description: "Read the contents of a file. Use this to examine specific files found in search.",
-        inputSchema: z9.object({
-          path: z9.string().describe("Path to the file (relative to working directory or absolute)"),
-          startLine: z9.number().optional().describe("Start reading from this line (1-indexed)"),
-          endLine: z9.number().optional().describe("Stop reading at this line (1-indexed, inclusive)")
+        inputSchema: z10.object({
+          path: z10.string().describe("Path to the file (relative to working directory or absolute)"),
+          startLine: z10.number().optional().describe("Start reading from this line (1-indexed)"),
+          endLine: z10.number().optional().describe("Stop reading at this line (1-indexed, inclusive)")
         }),
         execute: async ({ path, startLine, endLine }) => {
           try {
-            const absolutePath = isAbsolute4(path) ? path : resolve8(workingDirectory, path);
-            if (!existsSync11(absolutePath)) {
+            const absolutePath = isAbsolute5(path) ? path : resolve9(workingDirectory, path);
+            if (!existsSync12(absolutePath)) {
               return {
                 success: false,
                 error: `File not found: ${path}`
@@ -3398,7 +3969,7 @@ Keep it concise but INCLUDE THE ACTUAL DATA.`;
                 error: `File too large (${(stats.size / 1024 / 1024).toFixed(2)}MB). Use startLine/endLine to read portions.`
               };
             }
-            let content = await readFile7(absolutePath, "utf-8");
+            let content = await readFile8(absolutePath, "utf-8");
             if (startLine !== void 0 || endLine !== void 0) {
               const lines = content.split("\n");
               const start = (startLine ?? 1) - 1;
@@ -3407,7 +3978,7 @@ Keep it concise but INCLUDE THE ACTUAL DATA.`;
             }
             return {
               success: true,
-              path: relative7(workingDirectory, absolutePath),
+              path: relative8(workingDirectory, absolutePath),
               content: truncateOutput(content, MAX_OUTPUT_CHARS4),
               lineCount: content.split("\n").length
             };
@@ -3419,17 +3990,17 @@ Keep it concise but INCLUDE THE ACTUAL DATA.`;
           }
         }
       }),
-      list_dir: tool8({
+      list_dir: tool9({
         description: "List contents of a directory. Shows files and subdirectories.",
-        inputSchema: z9.object({
-          path: z9.string().optional().default(".").describe("Directory path (relative to working directory)"),
-          recursive: z9.boolean().optional().default(false).describe("List recursively (be careful with large directories)"),
-          maxDepth: z9.number().optional().default(2).describe("Maximum depth for recursive listing")
+        inputSchema: z10.object({
+          path: z10.string().optional().default(".").describe("Directory path (relative to working directory)"),
+          recursive: z10.boolean().optional().default(false).describe("List recursively (be careful with large directories)"),
+          maxDepth: z10.number().optional().default(2).describe("Maximum depth for recursive listing")
         }),
         execute: async ({ path, recursive, maxDepth }) => {
           try {
-            const absolutePath = isAbsolute4(path) ? path : resolve8(workingDirectory, path);
-            if (!existsSync11(absolutePath)) {
+            const absolutePath = isAbsolute5(path) ? path : resolve9(workingDirectory, path);
+            if (!existsSync12(absolutePath)) {
               return {
                 success: false,
                 error: `Directory not found: ${path}`
@@ -3453,20 +4024,20 @@ Keep it concise but INCLUDE THE ACTUAL DATA.`;
               const files = stdout.trim().split("\n").filter(Boolean);
               return {
                 success: true,
-                path: relative7(workingDirectory, absolutePath) || ".",
+                path: relative8(workingDirectory, absolutePath) || ".",
                 files,
                 count: files.length,
                 recursive: true
               };
             } else {
-              const entries = await readdir3(absolutePath, { withFileTypes: true });
+              const entries = await readdir4(absolutePath, { withFileTypes: true });
               const items = entries.slice(0, 200).map((e) => ({
                 name: e.name,
                 type: e.isDirectory() ? "directory" : "file"
               }));
               return {
                 success: true,
-                path: relative7(workingDirectory, absolutePath) || ".",
+                path: relative8(workingDirectory, absolutePath) || ".",
                 items,
                 count: items.length
               };
@@ -3478,6 +4049,9 @@ Keep it concise but INCLUDE THE ACTUAL DATA.`;
             };
           }
         }
+      }),
+      code_graph: createCodeGraphTool({
+        workingDirectory
       })
     };
     try {
@@ -3571,6 +4145,26 @@ Keep it concise but INCLUDE THE ACTUAL DATA.`;
               context: m.symbolName || m.language
             });
           }
+        } else if (step.toolName === "code_graph" && output.success) {
+          matchCount += output.referenceCount || 0;
+          if (output.filePath) {
+            findings.push({
+              type: "file",
+              path: output.filePath,
+              lineNumber: output.line,
+              content: output.typeInfo ? truncateOutput(output.typeInfo, 300) : void 0,
+              relevance: "high",
+              context: `${output.kind || "symbol"}${output.referenceCount ? `, ${output.referenceCount} refs` : ""}`
+            });
+          }
+          for (const page of (output.pages || []).slice(0, 10)) {
+            findings.push({
+              type: "file",
+              path: page.path,
+              relevance: "high",
+              context: page.route ? `route: ${page.route}` : "page"
+            });
+          }
         }
       }
     }
@@ -3592,7 +4186,7 @@ function createSearchSubagent(model) {
 // src/tools/search.ts
 var MAX_RESULT_CHARS = 1e4;
 function createSearchTool(options) {
-  return tool9({
+  return tool10({
     description: `Delegate an explore task to the explore_agent tool. Use this when you need to:
 - Find files or code matching a pattern
 - Explore the codebase structure
@@ -3602,11 +4196,12 @@ function createSearchTool(options) {
 The Explore agent will explore the codebase and return a summary of findings.
 This is more thorough than a simple grep because it can follow references and understand context.
 It also has access to semantic search to find code by meaning, not just text.
+It can also use code_graph to inspect a symbol's type hierarchy, references, and which pages/routes use it.
 
 CRITICAL: The explore agent has ZERO context. It cannot see the conversation, the user's message, devtools data, or any prior context. You MUST pass ALL relevant context via the "context" parameter. If the user selected a component (component name, file path, HTML, component stack) or there is a <devtools-context> block, you MUST copy that information into the "context" field verbatim. Without it the explore agent is searching blind.`,
-    inputSchema: z10.object({
-      query: z10.string().describe("What to search for. Be specific about what you're looking for."),
-      context: z10.string().describe("ALL context the explore agent needs. It has ZERO context on its own - no conversation history, no devtools data, nothing. You MUST include: any selected component info (name, file path, HTML, component stack), any <devtools-context> block (page URL, path, viewport), and any other relevant details from the user message. The explore agent literally only sees the query and this context field.")
+    inputSchema: z11.object({
+      query: z11.string().describe("What to search for. Be specific about what you're looking for."),
+      context: z11.string().describe("ALL context the explore agent needs. It has ZERO context on its own - no conversation history, no devtools data, nothing. You MUST include: any selected component info (name, file path, HTML, component stack), any <devtools-context> block (page URL, path, viewport), and any other relevant details from the user message. The explore agent literally only sees the query and this context field.")
     }),
     execute: async ({ query, context }, toolOptions) => {
       const toolCallId = toolOptions.toolCallId || `explore_agent_${Date.now()}`;
@@ -3750,6 +4345,9 @@ async function createTools(options) {
       sessionId: options.sessionId,
       workingDirectory: options.workingDirectory,
       onProgress: options.onSearchProgress
+    }),
+    code_graph: createCodeGraphTool({
+      workingDirectory: options.workingDirectory
     })
   };
   if (options.enableSemanticSearch !== false) {
@@ -3841,6 +4439,7 @@ You have access to powerful tools for:
 - **todo**: Manage your task list to track progress on complex operations
 - **load_skill**: Load specialized knowledge documents for specific tasks
 - **explore_agent**: Explore agent for semantic discovery - for exploratory questions and finding code by meaning
+- **code_graph**: Inspect a symbol's type hierarchy and usage graph via the TypeScript language server
 
 
 IMPORTANT: If you have zero context of where you are working, always explore it first to understand the structure before doing things for the user.
@@ -3930,6 +4529,33 @@ linter({ paths: ["src/"] })          // Check all files in a directory
 \`\`\`
 Use this proactively after making code changes to catch errors early.
 
+### Code Graph Tool
+The code_graph tool uses the TypeScript language server to inspect a symbol's type hierarchy and usage graph:
+\`\`\`
+code_graph({ symbol: "UserCard" })                                    // Search workspace for symbol
+code_graph({ symbol: "UserCard", filePath: "src/components.tsx" })     // Look up in a specific file
+code_graph({ symbol: "formatUser", filePath: "utils.ts", depth: 2 })  // Traverse 2 levels up the reference tree
+\`\`\`
+
+**What it returns:**
+- The symbol's full type signature (parameters, return type)
+- All files/functions/components that reference it (grouped into pages vs components)
+- Which Next.js pages/routes contain it in their component tree
+- Level-2 transitive usages (who uses the things that use this symbol)
+- The file's symbol structure for surrounding context
+
+**When to use code_graph:**
+- **To locate a component/function by name** when you don't have the file path \u2014 e.g. a user mentions a component from devtools but the path is missing or mangled. Just pass the symbol name and it will find the definition.
+- **Before making changes** to a function/component \u2014 understand what depends on it and what will break
+- **To understand component hierarchies** \u2014 what renders what, which pages are affected across the *entire* codebase (not just the current page)
+- **To get type signatures** (props, params, return types) without reading entire files
+- **After a devtools selection** when the task involves refactoring, changing props, or anything that could impact other consumers
+
+**When NOT to use code_graph:**
+- For exploratory "how does X work?" questions \u2014 use \`explore_agent\` instead
+- For exact string searches \u2014 use grep/rg directly
+- For non-TypeScript/JavaScript files \u2014 code_graph only supports TS/JS/TSX/JSX
+
 ### Searching and Exploration
 
 **Choose the right search approach:**
@@ -3937,7 +4563,8 @@ Use this proactively after making code changes to catch errors early.
 0. **Use paths to your advantage \u2014 skip searching if you already have what you need.**
    - If the user selected a component via devtools and you can see the component name, file path, and/or line number, you ALREADY know where the code is. Just use \`read_file\` to read that file directly \u2014 do NOT call \`explore_agent\` to "find" something you already have the location of.
    - If you received a **page path** (e.g. \`/dashboard\`, \`/settings/profile\`), map it to the corresponding file in the project structure. In Next.js this means \`app/dashboard/page.tsx\`, \`app/settings/profile/page.tsx\`, etc. In other frameworks, check the routing convention (e.g. \`pages/\`, \`src/routes/\`). Use \`read_file\` on the mapped path directly.
-   - If the file path doesn't exist or \`read_file\` fails, fall back to grep to locate it (e.g. \`rg "ComponentName" --type ts -l\`) since devtools paths can sometimes be slightly off or truncated.
+   - **If the file path is missing, truncated, or doesn't exist** (common with devtools \u2014 webpack paths can be mangled), use \`code_graph({ symbol: "ComponentName" })\` to locate the component. This searches the workspace for the symbol definition AND returns its type info, references, and page locations in one call \u2014 much better than raw grep for components.
+   - **After reading a devtools-selected component**, if the task involves changes that could affect other consumers (refactoring, changing props, renaming), use \`code_graph\` to see ALL files and pages that depend on it \u2014 the devtools component stack only shows the current page's hierarchy, not the full picture.
    - Read up and down component trees when you have the file path or page path to find what you're looking for.
 1. **Use the \`explore_agent\` tool (Explore agent)** for:
    - Semantic/exploratory questions: "How does authentication work?", "Where is user data processed?"
@@ -3955,7 +4582,14 @@ Use this proactively after making code changes to catch errors early.
    - If you skip the \`context\` field, the explore agent is searching completely blind and will waste time guessing.
    - NEVER call \`explore_agent\` with only a \`query\` and no \`context\` when the user's message contains devtools or component information.
 
-2. **Use direct commands (grep/rg, find)** for:
+2. **Use the \`code_graph\` tool** for:
+   - Understanding what depends on a specific symbol before changing it
+   - Tracing component/function usage up to page-level routes
+   - Getting type signatures (params, return types) without reading full files
+   - Finding exact components usages in the codebase
+   - Answering "what will break if I change this?" or "which pages use this component?"
+
+3. **Use direct commands (grep/rg, find)** for:
    - Exact string matches: \`rg "functionName"\`, \`rg "class MyClass"\`
    - Finding files by name: \`find . -name "*.config.ts"\`
    - Simple pattern matching when you know exactly what you're looking for
@@ -3963,7 +4597,11 @@ Use this proactively after making code changes to catch errors early.
 
 **Examples:**
 - User selected \`<LandingButton>\` at \`src/components/LandingButton.tsx:12\` \u2192 Just \`read_file("src/components/LandingButton.tsx")\`. Do NOT call explore_agent.
+- User selected \`<PricingCard>\` but no file path in the component stack \u2192 Use \`code_graph({ symbol: "PricingCard" })\` to find its definition, type info, and all usages at once.
+- User selected \`<UserCard>\` and says "refactor the props" \u2192 First \`read_file\` the component, then \`code_graph({ symbol: "UserCard" })\` to see every file/page that depends on it before changing the interface.
 - "Where is the API authentication handled?" (no file path given) \u2192 Use \`explore_agent\` tool
+- "What pages use the UserCard component?" \u2192 Use \`code_graph({ symbol: "UserCard" })\`
+- "What's the type signature of formatUser?" \u2192 Use \`code_graph({ symbol: "formatUser", filePath: "utils.ts" })\`
 - "Find all usages of getUserById" \u2192 Use \`rg "getUserById"\`
 - "How does the payment flow work?" \u2192 Use \`explore_agent\` tool
 - "Find files named config" \u2192 Use \`find . -name "*config*"\`
@@ -4535,9 +5173,9 @@ ${prompt}` });
         wrappedTools[name] = originalTool;
         continue;
       }
-      wrappedTools[name] = tool10({
+      wrappedTools[name] = tool11({
         description: originalTool.description || "",
-        inputSchema: originalTool.inputSchema || z11.object({}),
+        inputSchema: originalTool.inputSchema || z12.object({}),
         execute: async (input, toolOptions) => {
           const toolCallId = toolOptions.toolCallId || nanoid3();
           const execution = toolExecutionQueries.create({
@@ -4551,8 +5189,8 @@ ${prompt}` });
           this.pendingApprovals.set(toolCallId, await execution);
           options.onApprovalRequired?.(await execution);
           await sessionQueries.updateStatus(this.session.id, "waiting");
-          const approved = await new Promise((resolve9) => {
-            approvalResolvers.set(toolCallId, { resolve: resolve9, sessionId: this.session.id });
+          const approved = await new Promise((resolve10) => {
+            approvalResolvers.set(toolCallId, { resolve: resolve10, sessionId: this.session.id });
           });
           const resolverData = approvalResolvers.get(toolCallId);
           approvalResolvers.delete(toolCallId);