@probelabs/probe 0.6.0-rc308 → 0.6.0-rc309

package/cjs/index.cjs

@@ -2187,6 +2187,70 @@ var init_extract = __esm({
   }
 });
 
+// src/symbols.js
+async function symbols(options) {
+  if (!options) {
+    throw new Error("Options object is required");
+  }
+  if (!options.files || !Array.isArray(options.files) || options.files.length === 0) {
+    throw new Error("At least one file path is required");
+  }
+  const binaryPath = await getBinaryPath(options.binaryOptions || {});
+  const cwd = await validateCwdPath(options.cwd);
+  const args = ["symbols", "--format", "json"];
+  if (options.allowTests) {
+    args.push("--allow-tests");
+  }
+  for (const file2 of options.files) {
+    args.push(escapeString(file2));
+  }
+  if (process.env.DEBUG === "1") {
+    console.error(`
+Symbols: files="${options.files.join(", ")}" cwd="${cwd}"`);
+  }
+  return new Promise((resolve9, reject2) => {
+    const childProcess = (0, import_child_process5.spawn)(binaryPath, args, {
+      stdio: ["pipe", "pipe", "pipe"],
+      cwd
+    });
+    let stdout = "";
+    let stderr = "";
+    childProcess.stdout.on("data", (data2) => {
+      stdout += data2.toString();
+    });
+    childProcess.stderr.on("data", (data2) => {
+      stderr += data2.toString();
+    });
+    childProcess.on("close", (code) => {
+      if (stderr && process.env.DEBUG === "1") {
+        console.error(`stderr: ${stderr}`);
+      }
+      if (code !== 0) {
+        reject2(new Error(`Symbols command failed with exit code ${code}: ${stderr}`));
+        return;
+      }
+      try {
+        const result = JSON.parse(stdout);
+        resolve9(result);
+      } catch (error40) {
+        reject2(new Error(`Failed to parse symbols output: ${error40.message}. Output: ${stdout.substring(0, 200)}`));
+      }
+    });
+    childProcess.on("error", (error40) => {
+      reject2(new Error(`Failed to spawn symbols process: ${error40.message}`));
+    });
+  });
+}
+var import_child_process5;
+var init_symbols = __esm({
+  "src/symbols.js"() {
+    "use strict";
+    import_child_process5 = require("child_process");
+    init_utils();
+    init_path_validation();
+  }
+});
+
 // src/grep.js
 async function grep(options) {
   if (!options || !options.pattern) {
@@ -2230,14 +2294,14 @@ async function grep(options) {
     throw new Error(`Grep failed: ${errorMessage}`);
   }
 }
-var import_child_process5, import_util5, execFileAsync2, GREP_FLAG_MAP;
+var import_child_process6, import_util5, execFileAsync2, GREP_FLAG_MAP;
 var init_grep = __esm({
   "src/grep.js"() {
     "use strict";
-    import_child_process5 = require("child_process");
+    import_child_process6 = require("child_process");
     import_util5 = require("util");
     init_utils();
-    execFileAsync2 = (0, import_util5.promisify)(import_child_process5.execFile);
+    execFileAsync2 = (0, import_util5.promisify)(import_child_process6.execFile);
     GREP_FLAG_MAP = {
       ignoreCase: "-i",
       lineNumbers: "-n",
@@ -27645,6 +27709,9 @@ function createTools(configOptions) {
   if (isToolAllowed("extract")) {
     tools2.extractTool = extractTool(configOptions);
   }
+  if (isToolAllowed("symbols")) {
+    tools2.symbolsTool = symbolsTool(configOptions);
+  }
   if (configOptions.enableDelegate && isToolAllowed("delegate")) {
     tools2.delegateTool = delegateTool(configOptions);
   }
@@ -27813,7 +27880,7 @@ function resolveTargetPath(target, cwd) {
   }
   return filePart + suffix;
 }
-var import_path6, searchDelegateSchema, searchSchema, searchAllSchema, querySchema, extractSchema, delegateSchema, listSkillsSchema, useSkillSchema, listFilesSchema, searchFilesSchema, readImageSchema, readMediaSchema, bashSchema, analyzeAllSchema, executePlanSchema, cleanupExecutePlanSchema, searchDescription, searchDelegateDescription, queryDescription, extractDescription, delegateDescription, bashDescription, analyzeAllDescription;
+var import_path6, searchDelegateSchema, searchSchema, searchAllSchema, querySchema, extractSchema, delegateSchema, listSkillsSchema, useSkillSchema, listFilesSchema, searchFilesSchema, readImageSchema, readMediaSchema, symbolsSchema, bashSchema, analyzeAllSchema, executePlanSchema, cleanupExecutePlanSchema, searchDescription, searchDelegateDescription, queryDescription, extractDescription, delegateDescription, bashDescription, analyzeAllDescription;
 var init_common = __esm({
   "src/tools/common.js"() {
     "use strict";
@@ -27872,6 +27939,9 @@ var init_common = __esm({
     readMediaSchema = external_exports2.object({
       path: external_exports2.string().describe("Path to the media file to read. Supports images (png, jpg, jpeg, webp, bmp, svg) and documents (pdf).")
     });
+    symbolsSchema = external_exports2.object({
+      file: external_exports2.string().describe("Path to the file to list symbols from. Returns a hierarchical tree of functions, classes, structs, constants, etc. with line numbers and nesting (e.g., methods inside classes/impl blocks).")
+    });
     bashSchema = external_exports2.object({
       command: external_exports2.string().describe("The bash command to execute"),
       workingDirectory: external_exports2.string().optional().describe("Directory to execute the command in (optional)"),
@@ -35281,14 +35351,21 @@ function createWrappedTools(baseTools) {
       baseTools.multiEditTool.execute
     );
   }
+  if (baseTools.symbolsTool) {
+    wrappedTools.symbolsToolInstance = wrapToolWithEmitter(
+      baseTools.symbolsTool,
+      "symbols",
+      baseTools.symbolsTool.execute
+    );
+  }
   return wrappedTools;
 }
-var import_child_process6, import_util13, import_crypto3, import_events, import_fs6, import_fs7, import_path8, toolCallEmitter, activeToolExecutions, wrapToolWithEmitter, listFilesTool, searchFilesTool, listFilesToolInstance, searchFilesToolInstance;
+var import_child_process7, import_util13, import_crypto3, import_events, import_fs6, import_fs7, import_path8, toolCallEmitter, activeToolExecutions, wrapToolWithEmitter, listFilesTool, searchFilesTool, listFilesToolInstance, searchFilesToolInstance;
 var init_probeTool = __esm({
   "src/agent/probeTool.js"() {
     "use strict";
     init_index();
-    import_child_process6 = require("child_process");
+    import_child_process7 = require("child_process");
     import_util13 = require("util");
     import_crypto3 = require("crypto");
     import_events = require("events");
@@ -73938,6 +74015,7 @@ CRITICAL - ALWAYS search before answering:
 You must NEVER answer questions about the codebase from memory or general knowledge. ALWAYS use the search and extract tools first to find the actual code, then base your answer ONLY on what you found. Even if you think you know the answer, you MUST verify it against the actual code. Your answers must be grounded in code evidence, not assumptions.
 
 When exploring code:
+- Use the symbols tool to get a quick overview of a file's structure (functions, classes, constants) before diving into details with extract
 - Provide clear, concise explanations based on user request
 - Find and highlight the most relevant code snippets, if required
 - Trace function calls and data flow through the system \u2014 follow the FULL call chain, not just the entry point
@@ -73968,6 +74046,7 @@ You think like a code explorer \u2014 you understand that codebases have layers:
 
 When searching:
 - Search for the MAIN concept first, then think: "what RELATED subsystems would a real codebase have?"
+- Use symbols to get a file's table of contents (functions, classes, constants with line numbers) before extracting \u2014 it helps you pick the right symbols to extract
 - Use extract to READ the code you find \u2014 look for function calls, type references, and imports that point to OTHER relevant code
 - If you find middleware, check: are there org-level or tenant-level variants?
 - If you find algorithms, check: are there different storage backends?
@@ -74011,6 +74090,7 @@ If the solution is clear, you can jump to implementation right away. If not, ask
 - Do not add code comments unless the logic is genuinely complex and non-obvious.
 
 # Before Implementation
+- Use symbols to get a quick overview of file structure (functions, classes, constants with line numbers) before reading or editing files.
 - Read tests first \u2014 find existing test files for the module you're changing. They reveal expected behavior, edge cases, and the project's testing patterns.
 - Read neighboring files \u2014 understand naming conventions, error handling patterns, import style, and existing utilities before creating new ones.
 - Trace the call chain \u2014 follow how the code you're changing is called and what depends on it. Check interfaces, types, and consumers.
@@ -74047,7 +74127,7 @@ Use the right tool:
 1. To MODIFY existing code \u2192 \`edit\` tool (old_string \u2192 new_string, or start_line/end_line)
 2. To CREATE a new file \u2192 \`create\` tool
 3. To CHANGE multiple files at once \u2192 \`multi_edit\` tool
-4. To READ code \u2192 \`extract\` or \`search\` tools
+4. To READ code \u2192 \`extract\` or \`search\` tools. Use \`symbols\` to get a file's table of contents (functions, classes, constants with line numbers) before extracting.
 5. If \`edit\` fails with "file has not been read yet" \u2192 use \`extract\` with the EXACT same file path you will pass to \`edit\`. Relative vs absolute path mismatch causes this error. Use the same path format consistently. If it still fails, use bash \`cat\` to read the file, then use \`create\` to write the entire modified file. Do NOT fall back to sed.
 
 Bash is fine for: formatters (gofmt, prettier, black), build/test/lint commands, git operations, and read-only file inspection (cat, head, tail). sed/awk should ONLY be used for trivial non-code tasks (e.g., config file tweaks) where the replacement is a simple literal string swap.
@@ -76501,6 +76581,7 @@ var require_stringify = __commonJS({
         nullStr: "null",
         simpleKeys: false,
         singleQuote: null,
+        trailingComma: false,
         trueStr: "true",
         verifyAliasOrder: true
       }, doc.schema.toStringOptions, options);
@@ -77018,12 +77099,19 @@ ${indent}${line}` : "\n";
         if (comment)
           reqNewline = true;
         let str = stringify.stringify(item, itemCtx, () => comment = null);
-        if (i < items.length - 1)
+        reqNewline || (reqNewline = lines.length > linesAtValue || str.includes("\n"));
+        if (i < items.length - 1) {
           str += ",";
+        } else if (ctx.options.trailingComma) {
+          if (ctx.options.lineWidth > 0) {
+            reqNewline || (reqNewline = lines.reduce((sum, line) => sum + line.length + 2, 2) + (str.length + 2) > ctx.options.lineWidth);
+          }
+          if (reqNewline) {
+            str += ",";
+          }
+        }
         if (comment)
           str += stringifyComment.lineComment(str, itemIndent, commentString(comment));
-        if (!reqNewline && (lines.length > linesAtValue || str.includes("\n")))
-          reqNewline = true;
         lines.push(str);
         linesAtValue = lines.length;
       }
@@ -80037,17 +80125,22 @@ var require_compose_node = __commonJS({
         case "block-map":
         case "block-seq":
         case "flow-collection":
-          node = composeCollection.composeCollection(CN, ctx, token, props, onError);
-          if (anchor)
-            node.anchor = anchor.source.substring(1);
+          try {
+            node = composeCollection.composeCollection(CN, ctx, token, props, onError);
+            if (anchor)
+              node.anchor = anchor.source.substring(1);
+          } catch (error40) {
+            const message = error40 instanceof Error ? error40.message : String(error40);
+            onError(token, "RESOURCE_EXHAUSTION", message);
+          }
           break;
         default: {
           const message = token.type === "error" ? token.message : `Unsupported token (type: ${token.type})`;
           onError(token, "UNEXPECTED_TOKEN", message);
-          node = composeEmptyNode(ctx, token.offset, void 0, null, props, onError);
           isSrcToken = false;
         }
       }
+      node ?? (node = composeEmptyNode(ctx, token.offset, void 0, null, props, onError));
       if (anchor && node.anchor === "")
         onError(anchor, "BAD_ALIAS", "Anchor cannot be an empty string");
       if (atKey && ctx.options.stringKeys && (!identity2.isScalar(node) || typeof node.value !== "string" || node.tag && node.tag !== "tag:yaml.org,2002:str")) {
@@ -95036,7 +95129,7 @@ async function executeBashCommand(command, options = {}) {
       [cmd, ...cmdArgs] = args;
       useShell = false;
     }
-    const child = (0, import_child_process7.spawn)(cmd, cmdArgs, {
+    const child = (0, import_child_process8.spawn)(cmd, cmdArgs, {
       cwd,
       env: processEnv,
       stdio: ["ignore", "pipe", "pipe"],
@@ -95232,11 +95325,11 @@ function validateExecutionOptions(options = {}) {
     warnings
   };
 }
-var import_child_process7, import_path13, import_fs10;
+var import_child_process8, import_path13, import_fs10;
 var init_bashExecutor = __esm({
   "src/agent/bashExecutor.js"() {
     "use strict";
-    import_child_process7 = require("child_process");
+    import_child_process8 = require("child_process");
     import_path13 = require("path");
     import_fs10 = require("fs");
     init_bashCommandUtils();
@@ -96762,7 +96855,7 @@ ${opts.schema}`;
         }
       }
       const toolCollector = [];
-      const proc2 = (0, import_child_process8.spawn)("sh", ["-c", shellCmd], {
+      const proc2 = (0, import_child_process9.spawn)("sh", ["-c", shellCmd], {
         env: { ...process.env, FORCE_COLOR: "0" },
         stdio: ["ignore", "pipe", "pipe"]
         // Ignore stdin since echo handles it
@@ -97117,11 +97210,11 @@ function combinePrompts(systemPrompt, customPrompt, agent) {
   }
   return systemPrompt || "";
 }
-var import_child_process8, import_crypto6, import_promises5, import_path15, import_os5, import_events3;
+var import_child_process9, import_crypto6, import_promises5, import_path15, import_os5, import_events3;
 var init_enhanced_claude_code = __esm({
   "src/agent/engines/enhanced-claude-code.js"() {
     "use strict";
-    import_child_process8 = require("child_process");
+    import_child_process9 = require("child_process");
     import_crypto6 = require("crypto");
     import_promises5 = __toESM(require("fs/promises"), 1);
     import_path15 = __toESM(require("path"), 1);
@@ -97163,7 +97256,7 @@ async function createCodexEngine(options = {}) {
   if (debug) {
     console.log("[DEBUG] Starting Codex MCP server...");
   }
-  const codexProcess = (0, import_child_process9.spawn)("codex", ["mcp-server"], {
+  const codexProcess = (0, import_child_process10.spawn)("codex", ["mcp-server"], {
     stdio: ["pipe", "pipe", "pipe"]
   });
   let requestId = 0;
@@ -97395,11 +97488,11 @@ function combinePrompts2(systemPrompt, customPrompt, agent) {
   }
   return systemPrompt || "";
 }
-var import_child_process9, import_crypto7, import_readline;
+var import_child_process10, import_crypto7, import_readline;
 var init_codex = __esm({
   "src/agent/engines/codex.js"() {
     "use strict";
-    import_child_process9 = require("child_process");
+    import_child_process10 = require("child_process");
     import_crypto7 = require("crypto");
     import_readline = require("readline");
     init_built_in_server();
@@ -98165,6 +98258,9 @@ var init_ProbeAgent = __esm({
         if (isToolAllowed("searchFiles")) {
           this.toolImplementations.searchFiles = searchFilesToolInstance;
         }
+        if (wrappedTools.symbolsToolInstance && isToolAllowed("symbols")) {
+          this.toolImplementations.symbols = wrappedTools.symbolsToolInstance;
+        }
         if (this.enableSkills) {
           const registry2 = this._getSkillsRegistry();
           const { listSkillsToolInstance, useSkillToolInstance } = createSkillToolInstances({
@@ -99196,6 +99292,10 @@ var init_ProbeAgent = __esm({
             schema: searchFilesSchema,
             description: "Find files matching a glob pattern with recursive search capability."
           },
+          symbols: {
+            schema: symbolsSchema,
+            description: "List all symbols (functions, classes, structs, constants, etc.) in a file. Returns a hierarchical tree with line numbers \u2014 like a table of contents for code."
+          },
           readMedia: {
             schema: readMediaSchema,
             description: "Read and load a media file (image or PDF document) for AI analysis. Supports: png, jpg, jpeg, webp, bmp, svg, pdf."
@@ -99851,7 +99951,8 @@ ${this.architectureContext.content}
 ${searchToolDesc1}
 - extract: Extract specific code sections with context
 - listFiles: Browse directory contents
-- searchFiles: Find files by name patterns`;
+- searchFiles: Find files by name patterns
+- symbols: List all symbols in a file (functions, classes, constants, etc.) with line numbers`;
         if (this.enableBash) {
           systemPrompt += `
 - bash: Execute bash commands for system operations (building, running tests, git, etc.). NEVER use bash for code exploration (no grep, cat, find, head, tail) \u2014 always use search and extract tools instead, they are faster and more accurate.`;
@@ -99906,7 +100007,8 @@ Workspace: ${this.allowedFolders.join(", ")}`;
 ${searchToolDesc2}
 - extract: Extract specific code sections with context
 - listFiles: Browse directory contents
-- searchFiles: Find files by name patterns`;
+- searchFiles: Find files by name patterns
+- symbols: List all symbols in a file (functions, classes, constants, etc.) with line numbers`;
         if (this.enableBash) {
           systemPrompt += `
 - bash: Execute bash commands for system operations (building, running tests, git, etc.). NEVER use bash for code exploration (no grep, cat, find, head, tail) \u2014 always use search and extract tools instead, they are faster and more accurate.`;
@@ -103351,7 +103453,7 @@ The "searches" field helps the caller understand what was attempted.
 - Deduplicate files across groups.
 </output-rules>`;
 }
-var import_ai5, import_fs12, CODE_SEARCH_SCHEMA, searchTool, queryTool, extractTool, delegateTool, analyzeAllTool;
+var import_ai5, import_fs12, CODE_SEARCH_SCHEMA, searchTool, queryTool, extractTool, delegateTool, analyzeAllTool, symbolsTool;
 var init_vercel = __esm({
   "src/tools/vercel.js"() {
     "use strict";
@@ -103359,6 +103461,7 @@ var init_vercel = __esm({
     init_search();
     init_query();
     init_extract();
+    init_symbols();
     init_delegate();
     init_analyzeAll();
     init_common();
@@ -104081,6 +104184,36 @@ Do NOT search for analogies or loosely related concepts. If the feature does not
         }
       });
     };
+    symbolsTool = (options = {}) => {
+      return (0, import_ai5.tool)({
+        name: "symbols",
+        description: "List all symbols (functions, classes, structs, constants, etc.) in a file. Returns a hierarchical tree with line numbers \u2014 like a table of contents for code files.",
+        inputSchema: symbolsSchema,
+        execute: async ({ file: file2 }) => {
+          try {
+            let filePath = file2;
+            if (options.cwd) {
+              const resolvedPaths = parseAndResolvePaths(file2, options.cwd);
+              if (resolvedPaths.length > 0) {
+                filePath = resolvedPaths[0];
+              }
+            }
+            const result = await symbols({
+              files: [filePath],
+              cwd: options.cwd,
+              binaryOptions: options.binaryOptions
+            });
+            if (result && result.length > 0) {
+              return JSON.stringify(result[0], null, 2);
+            }
+            return JSON.stringify({ file: file2, symbols: [] }, null, 2);
+          } catch (error40) {
+            console.error("Error executing symbols:", error40);
+            return formatErrorForAI(error40);
+          }
+        }
+      });
+    };
   }
 });
 
@@ -105241,6 +105374,10 @@ You are Probe, a specialized code intelligence assistant. Your objective is to a
     *   **Purpose:** Retrieve specific code blocks or entire files *after* \`search\` or \`query\` identifies the target.
     *   **Syntax:** Optional \`#symbol\` (e.g., \`#MyClass\`), \`#Lstart-Lend\` (e.g., \`#L50-L75\`).
     *   **Mandatory Argument:** \`path\` (specific file path, e.g., \`"src/utils/helpers.go"\`, or dependency file like \`"go:github.com/gin-gonic/gin/context.go"\`).
+*   \`symbols\`
+    *   **Purpose:** List all symbols (functions, classes, structs, constants, etc.) in a file \u2014 a table of contents with line numbers and nesting.
+    *   **Syntax:** \`file\` (path to the file to list symbols from).
+    *   **Use When:** You need to understand a file's structure before extracting specific parts, or to find the right symbol name/line number for \`extract\`.
 
 [Examples]
 
@@ -105375,6 +105512,8 @@ __export(tools_exports, {
   searchFilesSchema: () => searchFilesSchema,
   searchSchema: () => searchSchema,
   searchTool: () => searchTool,
+  symbolsSchema: () => symbolsSchema,
+  symbolsTool: () => symbolsTool,
   tools: () => tools,
   useSkillSchema: () => useSkillSchema
 });
@@ -105498,16 +105637,16 @@ function shouldIgnore(filePath, ignorePatterns) {
   }
   return false;
 }
-var import_fs15, import_path18, import_util14, import_child_process10, execAsync3;
+var import_fs15, import_path18, import_util14, import_child_process11, execAsync3;
 var init_file_lister = __esm({
   "src/utils/file-lister.js"() {
     "use strict";
     import_fs15 = __toESM(require("fs"), 1);
     import_path18 = __toESM(require("path"), 1);
     import_util14 = require("util");
-    import_child_process10 = require("child_process");
+    import_child_process11 = require("child_process");
     init_symlink_utils();
-    execAsync3 = (0, import_util14.promisify)(import_child_process10.exec);
+    execAsync3 = (0, import_util14.promisify)(import_child_process11.exec);
   }
 });
 
@@ -105583,6 +105722,9 @@ __export(index_exports, {
   searchSchema: () => searchSchema,
   searchTool: () => searchTool,
   setBinaryPath: () => setBinaryPath,
+  symbols: () => symbols,
+  symbolsSchema: () => symbolsSchema,
+  symbolsTool: () => symbolsTool,
   taskSchema: () => taskSchema,
   taskSystemPrompt: () => taskSystemPrompt,
   tools: () => tools_exports,
@@ -105596,6 +105738,7 @@ var init_index = __esm({
     init_search();
     init_query();
     init_extract();
+    init_symbols();
     init_grep();
     init_delegate();
     init_utils();
@@ -105673,6 +105816,9 @@ init_index();
   searchSchema,
   searchTool,
   setBinaryPath,
+  symbols,
+  symbolsSchema,
+  symbolsTool,
   taskSchema,
   taskSystemPrompt,
   tools,

package/index.d.ts

@@ -408,6 +408,58 @@ export interface QueryParams {
   sessionId?: string;
 }
 
+/**
+ * Symbols tool parameters
+ */
+export interface SymbolsParams {
+  /** Files to list symbols from */
+  files: string[];
+  /** Working directory for resolving relative paths */
+  cwd?: string;
+  /** Include test functions/methods */
+  allowTests?: boolean;
+  /** Binary options */
+  binaryOptions?: {
+    forceDownload?: boolean;
+    version?: string;
+  };
+}
+
+/**
+ * A node in the symbol tree
+ */
+export interface SymbolNode {
+  /** Symbol name */
+  name: string;
+  /** Symbol kind (function, struct, class, const, etc.) */
+  kind: string;
+  /** Clean signature without body */
+  signature: string;
+  /** Start line (1-indexed) */
+  line: number;
+  /** End line (1-indexed) */
+  end_line: number;
+  /** Nested symbols (methods inside classes/impl blocks, etc.) */
+  children?: SymbolNode[];
+}
+
+/**
+ * Symbols extracted from a single file
+ */
+export interface FileSymbols {
+  /** File path */
+  file: string;
+  /** Top-level symbols with optional nesting */
+  symbols: SymbolNode[];
+}
+
+/**
+ * Symbols tool function type
+ */
+export type SymbolsTool = (options?: SearchOptions) => {
+  execute(params: { file: string }): Promise<string>;
+};
+
 /**
  * Extract tool parameters
  */
@@ -537,6 +589,11 @@ export declare function grep(options: {
   };
 }): Promise<string>;
 
+/**
+ * List symbols (functions, structs, classes, constants, etc.) in files
+ */
+export declare function symbols(options: SymbolsParams): Promise<FileSymbols[]>;
+
 /**
  * Extract code blocks from files
  */
@@ -564,6 +621,11 @@ export declare function queryTool(options?: SearchOptions): ReturnType<QueryTool
  */
 export declare function extractTool(options?: SearchOptions): ReturnType<ExtractTool>;
 
+/**
+ * Create symbols tool instance
+ */
+export declare function symbolsTool(options?: SearchOptions): ReturnType<SymbolsTool>;
+
 /**
  * Get the path to the probe binary
  */
@@ -778,6 +840,7 @@ export declare function createTool(options?: EditToolOptions): {
 export declare const searchSchema: any;
 export declare const querySchema: any;
 export declare const extractSchema: any;
+export declare const symbolsSchema: any;
 export declare const editSchema: any;
 export declare const createSchema: any;
 export declare const attemptCompletionSchema: any;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@probelabs/probe",
-  "version": "0.6.0-rc308",
+  "version": "0.6.0-rc309",
   "description": "Node.js wrapper for the probe code search tool",
   "main": "src/index.js",
   "module": "src/index.js",

package/src/agent/ProbeAgent.js

@@ -56,6 +56,7 @@ import {
   searchFilesSchema,
   readImageSchema,
   readMediaSchema,
+  symbolsSchema,
   listSkillsSchema,
   useSkillSchema
 } from './tools.js';
@@ -945,6 +946,9 @@ export class ProbeAgent {
     if (isToolAllowed('searchFiles')) {
       this.toolImplementations.searchFiles = searchFilesToolInstance;
     }
+    if (wrappedTools.symbolsToolInstance && isToolAllowed('symbols')) {
+      this.toolImplementations.symbols = wrappedTools.symbolsToolInstance;
+    }
 
     if (this.enableSkills) {
       const registry = this._getSkillsRegistry();
@@ -2225,6 +2229,10 @@ export class ProbeAgent {
         schema: searchFilesSchema,
         description: 'Find files matching a glob pattern with recursive search capability.'
       },
+      symbols: {
+        schema: symbolsSchema,
+        description: 'List all symbols (functions, classes, structs, constants, etc.) in a file. Returns a hierarchical tree with line numbers — like a table of contents for code.'
+      },
       readMedia: {
         schema: readMediaSchema,
         description: 'Read and load a media file (image or PDF document) for AI analysis. Supports: png, jpg, jpeg, webp, bmp, svg, pdf.'
@@ -3019,7 +3027,8 @@ export class ProbeAgent {
 ${searchToolDesc1}
 - extract: Extract specific code sections with context
 - listFiles: Browse directory contents
-- searchFiles: Find files by name patterns`;
+- searchFiles: Find files by name patterns
+- symbols: List all symbols in a file (functions, classes, constants, etc.) with line numbers`;
 
     if (this.enableBash) {
       systemPrompt += `\n- bash: Execute bash commands for system operations (building, running tests, git, etc.). NEVER use bash for code exploration (no grep, cat, find, head, tail) — always use search and extract tools instead, they are faster and more accurate.`;
@@ -3085,7 +3094,8 @@ ${extractGuidance1}
 ${searchToolDesc2}
 - extract: Extract specific code sections with context
 - listFiles: Browse directory contents
-- searchFiles: Find files by name patterns`;
+- searchFiles: Find files by name patterns
+- symbols: List all symbols in a file (functions, classes, constants, etc.) with line numbers`;
 
     if (this.enableBash) {
       systemPrompt += `\n- bash: Execute bash commands for system operations (building, running tests, git, etc.). NEVER use bash for code exploration (no grep, cat, find, head, tail) — always use search and extract tools instead, they are faster and more accurate.`;

package/src/agent/probeTool.js

@@ -265,6 +265,15 @@ export function createWrappedTools(baseTools) {
     );
   }
 
+  // Wrap symbols tool
+  if (baseTools.symbolsTool) {
+    wrappedTools.symbolsToolInstance = wrapToolWithEmitter(
+      baseTools.symbolsTool,
+      'symbols',
+      baseTools.symbolsTool.execute
+    );
+  }
+
   return wrappedTools;
 }
 

package/src/agent/shared/prompts.js

@@ -12,6 +12,7 @@ CRITICAL - ALWAYS search before answering:
 You must NEVER answer questions about the codebase from memory or general knowledge. ALWAYS use the search and extract tools first to find the actual code, then base your answer ONLY on what you found. Even if you think you know the answer, you MUST verify it against the actual code. Your answers must be grounded in code evidence, not assumptions.
 
 When exploring code:
+- Use the symbols tool to get a quick overview of a file's structure (functions, classes, constants) before diving into details with extract
 - Provide clear, concise explanations based on user request
 - Find and highlight the most relevant code snippets, if required
 - Trace function calls and data flow through the system — follow the FULL call chain, not just the entry point
@@ -43,6 +44,7 @@ You think like a code explorer — you understand that codebases have layers:
 
 When searching:
 - Search for the MAIN concept first, then think: "what RELATED subsystems would a real codebase have?"
+- Use symbols to get a file's table of contents (functions, classes, constants with line numbers) before extracting — it helps you pick the right symbols to extract
 - Use extract to READ the code you find — look for function calls, type references, and imports that point to OTHER relevant code
 - If you find middleware, check: are there org-level or tenant-level variants?
 - If you find algorithms, check: are there different storage backends?
@@ -90,6 +92,7 @@ If the solution is clear, you can jump to implementation right away. If not, ask
 - Do not add code comments unless the logic is genuinely complex and non-obvious.
 
 # Before Implementation
+- Use symbols to get a quick overview of file structure (functions, classes, constants with line numbers) before reading or editing files.
 - Read tests first — find existing test files for the module you're changing. They reveal expected behavior, edge cases, and the project's testing patterns.
 - Read neighboring files — understand naming conventions, error handling patterns, import style, and existing utilities before creating new ones.
 - Trace the call chain — follow how the code you're changing is called and what depends on it. Check interfaces, types, and consumers.
@@ -126,7 +129,7 @@ Use the right tool:
 1. To MODIFY existing code → \`edit\` tool (old_string → new_string, or start_line/end_line)
 2. To CREATE a new file → \`create\` tool
 3. To CHANGE multiple files at once → \`multi_edit\` tool
-4. To READ code → \`extract\` or \`search\` tools
+4. To READ code → \`extract\` or \`search\` tools. Use \`symbols\` to get a file's table of contents (functions, classes, constants with line numbers) before extracting.
 5. If \`edit\` fails with "file has not been read yet" → use \`extract\` with the EXACT same file path you will pass to \`edit\`. Relative vs absolute path mismatch causes this error. Use the same path format consistently. If it still fails, use bash \`cat\` to read the file, then use \`create\` to write the entire modified file. Do NOT fall back to sed.
 
 Bash is fine for: formatters (gofmt, prettier, black), build/test/lint commands, git operations, and read-only file inspection (cat, head, tail). sed/awk should ONLY be used for trivial non-code tasks (e.g., config file tweaks) where the replacement is a simple literal string swap.