@probelabs/probe 0.6.0-rc307 → 0.6.0-rc309

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.

package/src/agent/tools.js

@@ -5,6 +5,7 @@ import {
   extractTool,
   delegateTool,
   analyzeAllTool,
+  symbolsTool,
   createExecutePlanTool,
   createCleanupExecutePlanTool,
   bashTool,
@@ -27,6 +28,7 @@ import {
   searchFilesSchema,
   readImageSchema,
   readMediaSchema,
+  symbolsSchema,
   listSkillsSchema,
   useSkillSchema
 } from '../index.js';
@@ -52,6 +54,9 @@ export function createTools(configOptions) {
   if (isToolAllowed('extract')) {
     tools.extractTool = extractTool(configOptions);
   }
+  if (isToolAllowed('symbols')) {
+    tools.symbolsTool = symbolsTool(configOptions);
+  }
   if (configOptions.enableDelegate && isToolAllowed('delegate')) {
     tools.delegateTool = delegateTool(configOptions);
   }
@@ -111,6 +116,7 @@ export {
   searchFilesSchema,
   readImageSchema,
   readMediaSchema,
+  symbolsSchema,
   listSkillsSchema,
   useSkillSchema
 };

package/src/index.js

@@ -14,6 +14,7 @@ dotenv.config();
 import { search } from './search.js';
 import { query } from './query.js';
 import { extract } from './extract.js';
+import { symbols } from './symbols.js';
 import { grep } from './grep.js';
 import { delegate } from './delegate.js';
 import { getBinaryPath, setBinaryPath } from './utils.js';
@@ -33,6 +34,7 @@ import {
 	searchFilesSchema,
 	readImageSchema,
 	readMediaSchema,
+	symbolsSchema,
 	listSkillsSchema,
 	useSkillSchema
 } from './tools/common.js';
@@ -41,7 +43,7 @@ import {
 	createSchema,
 	multiEditSchema
 } from './tools/edit.js';
-import { searchTool, queryTool, extractTool, delegateTool, analyzeAllTool } from './tools/vercel.js';
+import { searchTool, queryTool, extractTool, delegateTool, analyzeAllTool, symbolsTool } from './tools/vercel.js';
 import { createExecutePlanTool, createCleanupExecutePlanTool } from './tools/executePlan.js';
 import { bashTool } from './tools/bash.js';
 import { editTool, createTool, multiEditTool } from './tools/edit.js';
@@ -62,6 +64,7 @@ export {
 	search,
 	query,
 	extract,
+	symbols,
 	grep,
 	delegate,
 	getBinaryPath,
@@ -91,6 +94,7 @@ export {
 	extractTool,
 	delegateTool,
 	analyzeAllTool,
+	symbolsTool,
 	createExecutePlanTool,
 	createCleanupExecutePlanTool,
 	bashTool,
@@ -117,6 +121,7 @@ export {
 	searchFilesSchema,
 	readImageSchema,
 	readMediaSchema,
+	symbolsSchema,
 	listSkillsSchema,
 	useSkillSchema,
 	// Export task management

package/src/symbols.js

@@ -0,0 +1,86 @@
+/**
+ * Symbols functionality for the probe package
+ * @module symbols
+ */
+
+import { spawn } from 'child_process';
+import { getBinaryPath, escapeString } from './utils.js';
+import { validateCwdPath } from './utils/path-validation.js';
+
+/**
+ * List symbols (functions, structs, classes, constants, etc.) in files
+ *
+ * @param {Object} options - Symbols options
+ * @param {string[]} options.files - Files to list symbols from
+ * @param {string} [options.cwd] - Working directory for resolving relative file paths
+ * @param {boolean} [options.allowTests] - Include test functions/methods
+ * @param {Object} [options.binaryOptions] - Options for getting the binary
+ * @returns {Promise<Object[]>} - Array of FileSymbols objects (parsed JSON)
+ * @throws {Error} If the command fails
+ */
+export 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 file of options.files) {
+		args.push(escapeString(file));
+	}
+
+	if (process.env.DEBUG === '1') {
+		console.error(`\nSymbols: files="${options.files.join(', ')}" cwd="${cwd}"`);
+	}
+
+	return new Promise((resolve, reject) => {
+		const childProcess = spawn(binaryPath, args, {
+			stdio: ['pipe', 'pipe', 'pipe'],
+			cwd
+		});
+
+		let stdout = '';
+		let stderr = '';
+
+		childProcess.stdout.on('data', (data) => {
+			stdout += data.toString();
+		});
+
+		childProcess.stderr.on('data', (data) => {
+			stderr += data.toString();
+		});
+
+		childProcess.on('close', (code) => {
+			if (stderr && process.env.DEBUG === '1') {
+				console.error(`stderr: ${stderr}`);
+			}
+
+			if (code !== 0) {
+				reject(new Error(`Symbols command failed with exit code ${code}: ${stderr}`));
+				return;
+			}
+
+			try {
+				const result = JSON.parse(stdout);
+				resolve(result);
+			} catch (error) {
+				reject(new Error(`Failed to parse symbols output: ${error.message}. Output: ${stdout.substring(0, 200)}`));
+			}
+		});
+
+		childProcess.on('error', (error) => {
+			reject(new Error(`Failed to spawn symbols process: ${error.message}`));
+		});
+	});
+}

package/src/tools/common.js

@@ -72,6 +72,10 @@ export const readMediaSchema = z.object({
 	path: z.string().describe('Path to the media file to read. Supports images (png, jpg, jpeg, webp, bmp, svg) and documents (pdf).')
 });
 
+export const symbolsSchema = z.object({
+	file: z.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).')
+});
+
 export const bashSchema = z.object({
 	command: z.string().describe('The bash command to execute'),
 	workingDirectory: z.string().optional().describe('Directory to execute the command in (optional)'),

package/src/tools/index.js

@@ -4,7 +4,7 @@
  */
 
 // Export Vercel AI SDK tool generators
-export { searchTool, queryTool, extractTool, delegateTool } from './vercel.js';
+export { searchTool, queryTool, extractTool, delegateTool, symbolsTool } from './vercel.js';
 export { bashTool } from './bash.js';
 export { editTool, createTool, multiEditTool } from './edit.js';
 
@@ -31,6 +31,7 @@ export {
 	searchFilesSchema,
 	readImageSchema,
 	readMediaSchema,
+	symbolsSchema,
 	listSkillsSchema,
 	useSkillSchema
 } from './common.js';

package/src/tools/system-message.js

@@ -33,6 +33,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 — 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]
 

package/src/tools/vercel.js

@@ -7,9 +7,10 @@ import { tool, generateText } from 'ai';
 import { search } from '../search.js';
 import { query } from '../query.js';
 import { extract } from '../extract.js';
+import { symbols } from '../symbols.js';
 import { delegate } from '../delegate.js';
 import { analyzeAll } from './analyzeAll.js';
-import { searchSchema, searchDelegateSchema, querySchema, extractSchema, delegateSchema, analyzeAllSchema, searchDescription, searchDelegateDescription, queryDescription, extractDescription, delegateDescription, analyzeAllDescription, parseTargets, parseAndResolvePaths, resolveTargetPath } from './common.js';
+import { searchSchema, searchDelegateSchema, querySchema, extractSchema, symbolsSchema, delegateSchema, analyzeAllSchema, searchDescription, searchDelegateDescription, queryDescription, extractDescription, delegateDescription, analyzeAllDescription, parseTargets, parseAndResolvePaths, resolveTargetPath } from './common.js';
 import { existsSync } from 'fs';
 import { formatErrorForAI } from '../utils/error-types.js';
 import { annotateOutputWithHashes } from './hashline.js';
@@ -1344,3 +1345,37 @@ export const analyzeAllTool = (options = {}) => {
 		}
 	});
 };
+
+export const symbolsTool = (options = {}) => {
+	return tool({
+		name: 'symbols',
+		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 files.',
+		inputSchema: symbolsSchema,
+		execute: async ({ file }) => {
+			try {
+				let filePath = file;
+				if (options.cwd) {
+					const resolvedPaths = parseAndResolvePaths(file, options.cwd);
+					if (resolvedPaths.length > 0) {
+						filePath = resolvedPaths[0];
+					}
+				}
+
+				const result = await symbols({
+					files: [filePath],
+					cwd: options.cwd,
+					binaryOptions: options.binaryOptions
+				});
+
+				// Schema accepts single file, so return first result directly
+				if (result && result.length > 0) {
+					return JSON.stringify(result[0], null, 2);
+				}
+				return JSON.stringify({ file, symbols: [] }, null, 2);
+			} catch (error) {
+				console.error('Error executing symbols:', error);
+				return formatErrorForAI(error);
+			}
+		}
+	});
+};