@probelabs/probe 0.6.0-rc308 → 0.6.0-rc309

package/README.md

@@ -23,6 +23,7 @@ During installation, the package will automatically download the appropriate pro
 - **Search Code**: Search for patterns in your codebase using Elasticsearch-like query syntax
 - **Query Code**: Find specific code structures using tree-sitter patterns
 - **Extract Code**: Extract code blocks from files based on file paths and line numbers
+- **List Symbols**: Get a file's table of contents — functions, classes, constants with line numbers and nesting
 - **Edit Code**: AI-powered code editing with text replacement (fuzzy matching), AST-aware symbol replace/insert across 16 languages, and line-targeted editing with optional hash-based integrity verification
 - **AI Tools Integration**: Ready-to-use tools for Vercel AI SDK, LangChain, and other AI frameworks
 - **System Message**: Default system message for AI assistants with instructions on using probe tools
@@ -297,6 +298,7 @@ const agent5 = new ProbeAgent({
 - `search` - Semantic code search
 - `query` - Tree-sitter pattern matching
 - `extract` - Extract code blocks
+- `symbols` - List all symbols in a file with line numbers
 - `listFiles` - List files and directories
 - `searchFiles` - Find files by glob pattern
 - `bash` - Execute bash commands (requires `enableBash: true`)
@@ -709,6 +711,29 @@ const results = await extract({
   - `forceDownload`: Force download even if binary exists
   - `version`: Specific version to download
 
+### Symbols
+
+```javascript
+import { symbols } from '@probelabs/probe';
+
+const result = await symbols({
+  files: ['src/main.rs'],
+  cwd: '/path/to/project',
+  allowTests: false
+});
+
+// result is an array of FileSymbols
+// result[0].file => 'src/main.rs'
+// result[0].symbols => [{ name, kind, signature, line, end_line, children }, ...]
+```
+
+#### Parameters
+
+- `files` (required): Array of file paths to list symbols from
+- `cwd`: Working directory for resolving relative paths
+- `allowTests`: Include test functions/methods (default: false)
+- `binaryOptions`: Options for getting the binary
+
 ### Binary Management
 
 ```javascript

package/build/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/build/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/build/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/build/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/build/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/build/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/build/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/build/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/build/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/build/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);
+			}
+		}
+	});
+};