@probelabs/probe 0.6.0-rc203 → 0.6.0-rc205

package/build/tools/vercel.js

@@ -9,6 +9,7 @@ import { query } from '../query.js';
 import { extract } from '../extract.js';
 import { delegate } from '../delegate.js';
 import { searchSchema, querySchema, extractSchema, delegateSchema, searchDescription, queryDescription, extractDescription, delegateDescription, parseTargets, parseAndResolvePaths, resolveTargetPath } from './common.js';
+import { formatErrorForAI } from '../utils/error-types.js';
 
 const CODE_SEARCH_SCHEMA = {
 	type: 'object',
@@ -117,15 +118,29 @@ function parseDelegatedTargets(rawResponse) {
 
 function buildSearchDelegateTask({ searchQuery, searchPath, exact, language, allowTests }) {
 	return [
-		'You are a code-search subagent. Your ONLY job is to return ALL relevant code locations.',
-		'Use ONLY the search tool. Do NOT answer the question or explain anything.',
-		'Return ONLY valid JSON with this shape: {"targets": ["path/to/file.ext#Symbol", "path/to/file.ext:line", "path/to/file.ext:start-end"]}.',
-		'Prefer #Symbol when a function/class name is clear; otherwise use line numbers.',
-		`Search query: ${searchQuery}`,
+		'You are a code-search subagent. Your job is to find ALL relevant code locations for the given query.',
+		'',
+		'The query may be complex - it could be a natural language question, a multi-part request, or a simple keyword.',
+		'Break down complex queries into multiple searches to cover all aspects.',
+		'',
+		'Available tools:',
+		'- search: Find code matching keywords or patterns. Run multiple searches for different aspects of complex queries.',
+		'- extract: Verify code snippets to ensure targets are actually relevant before including them.',
+		'- listFiles: Understand directory structure to find where relevant code might live.',
+		'',
+		'Strategy for complex queries:',
+		'1. Analyze the query - identify key concepts, entities, and relationships',
+		'2. Run focused searches for each concept (e.g., "error handling" + "authentication" separately)',
+		'3. Use extract to verify relevance of promising results',
+		'4. Combine all relevant targets in your final response',
+		'',
+		`Query: ${searchQuery}`,
 		`Search path(s): ${searchPath}`,
 		`Options: exact=${exact ? 'true' : 'false'}, language=${language || 'auto'}, allow_tests=${allowTests ? 'true' : 'false'}.`,
-		'Run additional searches only if needed to capture all relevant locations.',
-		'Deduplicate targets.'
+		'',
+		'Return ONLY valid JSON: {"targets": ["path/to/file.ext#Symbol", "path/to/file.ext:line", "path/to/file.ext:start-end"]}',
+		'Prefer #Symbol when a function/class name is clear; otherwise use line numbers.',
+		'Deduplicate targets. Do NOT explain or answer - ONLY return the JSON targets.'
 	].join('\n');
 }
 
@@ -200,7 +215,7 @@ export const searchTool = (options = {}) => {
 					return await runRawSearch();
 				} catch (error) {
 					console.error('Error executing search command:', error);
-					return `Error executing search command: ${error.message}`;
+					return formatErrorForAI(error);
 				}
 			}
 
@@ -230,7 +245,7 @@ export const searchTool = (options = {}) => {
 					bashConfig: null,
 					architectureFileName: options.architectureFileName || null,
 					promptType: 'code-searcher',
-					allowedTools: ['search', 'attempt_completion'],
+					allowedTools: ['search', 'extract', 'listFiles', 'attempt_completion'],
 					searchDelegate: false,
 					schema: CODE_SEARCH_SCHEMA
 				});
@@ -269,7 +284,8 @@ export const searchTool = (options = {}) => {
 					return await runRawSearch();
 				} catch (fallbackError) {
 					console.error('Error executing search command:', fallbackError);
-					return `Error executing search command: ${fallbackError.message}`;
+					// Both delegation and fallback failed - provide detailed error
+					return formatErrorForAI(fallbackError);
 				}
 			}
 		}
@@ -322,7 +338,7 @@ export const queryTool = (options = {}) => {
 				return results;
 			} catch (error) {
 				console.error('Error executing query command:', error);
-				return `Error executing query command: ${error.message}`;
+				return formatErrorForAI(error);
 			}
 		}
 	});
@@ -433,7 +449,7 @@ export const extractTool = (options = {}) => {
 				return results;
 			} catch (error) {
 				console.error('Error executing extract command:', error);
-				return `Error executing extract command: ${error.message}`;
+				return formatErrorForAI(error);
 			}
 		}
 	});

package/build/utils/error-types.js

@@ -0,0 +1,303 @@
+/**
+ * Structured error types for AI-friendly error handling
+ * @module utils/error-types
+ */
+
+/**
+ * Error categories for classification
+ */
+export const ErrorCategory = {
+  PATH_ERROR: 'path_error',           // Path doesn't exist, not a directory, permission denied
+  PARAMETER_ERROR: 'parameter_error', // Invalid parameters provided
+  TIMEOUT_ERROR: 'timeout_error',     // Operation timed out
+  API_ERROR: 'api_error',             // AI provider errors (rate limit, token limit)
+  DELEGATION_ERROR: 'delegation_error', // Subagent failures
+  INTERNAL_ERROR: 'internal_error'    // Unexpected system errors
+};
+
+/**
+ * Escape special characters for XML output
+ * @param {string} str - String to escape
+ * @returns {string} - Escaped string
+ */
+function escapeXml(str) {
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+/**
+ * Base class for structured errors with AI-friendly information
+ */
+export class ProbeError extends Error {
+  /**
+   * Create a ProbeError
+   * @param {string} message - Error message
+   * @param {Object} options - Options
+   * @param {string} [options.category] - Error category from ErrorCategory
+   * @param {boolean} [options.recoverable] - Whether the error is recoverable by AI action
+   * @param {string} [options.suggestion] - Suggested action for recovery
+   * @param {Object} [options.details] - Additional error details
+   * @param {Error} [options.originalError] - Original error that was wrapped
+   */
+  constructor(message, options = {}) {
+    super(message);
+    this.name = 'ProbeError';
+    this.category = options.category || ErrorCategory.INTERNAL_ERROR;
+    this.recoverable = options.recoverable ?? false;
+    this.suggestion = options.suggestion || null;
+    this.details = options.details || {};
+    this.originalError = options.originalError || null;
+  }
+
+  /**
+   * Format error as XML for AI consumption
+   * @returns {string} - XML-formatted error
+   */
+  toXml() {
+    const parts = [
+      `<error type="${this.category}" recoverable="${this.recoverable}">`,
+      `<message>${escapeXml(this.message)}</message>`
+    ];
+
+    if (this.suggestion) {
+      parts.push(`<suggestion>${escapeXml(this.suggestion)}</suggestion>`);
+    }
+
+    if (Object.keys(this.details).length > 0) {
+      parts.push(`<details>${escapeXml(JSON.stringify(this.details))}</details>`);
+    }
+
+    parts.push('</error>');
+    return parts.join('\n');
+  }
+
+  /**
+   * Format error for plain text (backward compatible)
+   * @returns {string} - Plain text error
+   */
+  toString() {
+    return `Error: ${this.message}`;
+  }
+}
+
+/**
+ * Path-related errors (not found, not a directory, permission denied)
+ */
+export class PathError extends ProbeError {
+  constructor(message, options = {}) {
+    super(message, {
+      ...options,
+      category: ErrorCategory.PATH_ERROR,
+      recoverable: options.recoverable ?? true,
+      suggestion: options.suggestion || 'Please verify the path exists or try searching in a different directory.'
+    });
+    this.name = 'PathError';
+  }
+}
+
+/**
+ * Parameter validation errors
+ */
+export class ParameterError extends ProbeError {
+  constructor(message, options = {}) {
+    super(message, {
+      ...options,
+      category: ErrorCategory.PARAMETER_ERROR,
+      recoverable: options.recoverable ?? true,
+      suggestion: options.suggestion || 'Please check and correct the parameter values.'
+    });
+    this.name = 'ParameterError';
+  }
+}
+
+/**
+ * Timeout errors
+ */
+export class TimeoutError extends ProbeError {
+  constructor(message, options = {}) {
+    super(message, {
+      ...options,
+      category: ErrorCategory.TIMEOUT_ERROR,
+      recoverable: options.recoverable ?? true,
+      suggestion: options.suggestion || 'The operation timed out. Try a more specific query or increase the timeout.'
+    });
+    this.name = 'TimeoutError';
+  }
+}
+
+/**
+ * API/AI provider errors (rate limit, token limit, etc.)
+ */
+export class ApiError extends ProbeError {
+  constructor(message, options = {}) {
+    super(message, {
+      ...options,
+      category: ErrorCategory.API_ERROR,
+      recoverable: options.recoverable ?? false,
+      suggestion: options.suggestion || 'This is an API provider error. The system will retry automatically if possible.'
+    });
+    this.name = 'ApiError';
+  }
+}
+
+/**
+ * Delegation/subagent errors
+ */
+export class DelegationError extends ProbeError {
+  constructor(message, options = {}) {
+    super(message, {
+      ...options,
+      category: ErrorCategory.DELEGATION_ERROR,
+      recoverable: options.recoverable ?? true,
+      suggestion: options.suggestion || 'The delegated task failed. Consider breaking down the task further or trying a different approach.'
+    });
+    this.name = 'DelegationError';
+  }
+}
+
+/**
+ * Categorize any error into a structured ProbeError
+ * @param {Error|string} error - Error to categorize
+ * @returns {ProbeError} - Structured error with category and suggestions
+ */
+export function categorizeError(error) {
+  // If already a ProbeError, return as-is
+  if (error instanceof ProbeError) {
+    return error;
+  }
+
+  const message = error?.message || String(error);
+  const lowerMessage = message.toLowerCase();
+  // error.code could be a string (like 'ENOENT') or a number (like 429)
+  const errorCode = error?.code != null ? String(error.code).toLowerCase() : '';
+
+  // Path-related errors
+  if (lowerMessage.includes('path does not exist') ||
+      lowerMessage.includes('no such file or directory') ||
+      errorCode === 'enoent') {
+    return new PathError(message, {
+      originalError: error,
+      suggestion: 'The specified path does not exist. Please verify the path or use a different directory.'
+    });
+  }
+
+  if (lowerMessage.includes('not a directory') || errorCode === 'enotdir') {
+    return new PathError(message, {
+      originalError: error,
+      suggestion: 'The path is not a directory. Please provide a valid directory path.'
+    });
+  }
+
+  if (lowerMessage.includes('permission denied') || errorCode === 'eacces') {
+    return new PathError(message, {
+      originalError: error,
+      recoverable: false,
+      suggestion: 'Permission denied. This is a system-level restriction that cannot be resolved by changing the query.'
+    });
+  }
+
+  // Timeout errors
+  if (lowerMessage.includes('timed out') ||
+      lowerMessage.includes('timeout') ||
+      errorCode === 'etimedout' ||
+      error?.killed === true) {
+    return new TimeoutError(message, {
+      originalError: error,
+      suggestion: 'The operation timed out. Try a more specific query, reduce the search scope, or increase the timeout.'
+    });
+  }
+
+  // API errors - rate limiting and overload
+  const rateLimitPatterns = ['rate_limit', 'rate limit', '429', 'too many requests', 'overloaded'];
+  if (rateLimitPatterns.some(p => lowerMessage.includes(p))) {
+    return new ApiError(message, {
+      originalError: error,
+      recoverable: true,
+      suggestion: 'API rate limit or overload encountered. The system will retry automatically with backoff.'
+    });
+  }
+
+  // API errors - server errors
+  const serverErrorPatterns = ['500', '502', '503', '504', 'internal server error', 'bad gateway', 'service unavailable'];
+  if (serverErrorPatterns.some(p => lowerMessage.includes(p))) {
+    return new ApiError(message, {
+      originalError: error,
+      recoverable: true,
+      suggestion: 'API server error encountered. The system will retry automatically.'
+    });
+  }
+
+  // API errors - context/token limits
+  if ((lowerMessage.includes('context') || lowerMessage.includes('token')) &&
+      (lowerMessage.includes('limit') || lowerMessage.includes('exceed'))) {
+    return new ApiError(message, {
+      originalError: error,
+      recoverable: true,
+      suggestion: 'Context or token limit exceeded. The conversation may be automatically compacted.'
+    });
+  }
+
+  // Parameter validation errors (check before API auth to catch 'invalid parameter' first)
+  if (lowerMessage.includes('invalid parameter') ||
+      lowerMessage.includes('missing parameter') ||
+      lowerMessage.includes('required') ||
+      lowerMessage.includes('must be')) {
+    return new ParameterError(message, {
+      originalError: error
+    });
+  }
+
+  // API errors - authentication (after parameter errors to avoid catching 'invalid parameter')
+  if (lowerMessage.includes('invalid') && (lowerMessage.includes('api') || lowerMessage.includes('key') || lowerMessage.includes('auth'))) {
+    return new ApiError(message, {
+      originalError: error,
+      recoverable: false,
+      suggestion: 'API authentication error. Please check the API key configuration.'
+    });
+  }
+
+  // Delegation errors
+  if (lowerMessage.includes('delegation failed') ||
+      lowerMessage.includes('delegate agent') ||
+      lowerMessage.includes('subagent')) {
+    return new DelegationError(message, {
+      originalError: error
+    });
+  }
+
+  // Network errors
+  if (errorCode === 'econnreset' ||
+      errorCode === 'econnrefused' ||
+      errorCode === 'enotfound' ||
+      lowerMessage.includes('network') ||
+      lowerMessage.includes('connection')) {
+    return new ApiError(message, {
+      originalError: error,
+      recoverable: true,
+      suggestion: 'Network error encountered. The system will retry automatically.'
+    });
+  }
+
+  // Default: internal error
+  return new ProbeError(message, {
+    category: ErrorCategory.INTERNAL_ERROR,
+    recoverable: false,
+    originalError: error,
+    suggestion: 'An unexpected error occurred. Please check the error message for details.'
+  });
+}
+
+/**
+ * Format an error for AI consumption as XML
+ * Works with both ProbeError and regular Error objects
+ * @param {Error} error - Error to format
+ * @returns {string} - XML-formatted error string
+ */
+export function formatErrorForAI(error) {
+  const structuredError = categorizeError(error);
+  return structuredError.toXml();
+}

package/build/utils/path-validation.js

@@ -5,6 +5,7 @@
 
 import path from 'path';
 import { promises as fs } from 'fs';
+import { PathError } from './error-types.js';
 
 /**
  * Validates and normalizes a path to be used as working directory (cwd).
@@ -18,7 +19,7 @@ import { promises as fs } from 'fs';
  * @param {string} inputPath - The path to validate
  * @param {string} [defaultPath] - Default path to use if inputPath is not provided
  * @returns {Promise<string>} Normalized absolute path
- * @throws {Error} If the path is invalid or doesn't exist
+ * @throws {PathError} If the path is invalid or doesn't exist
  */
 export async function validateCwdPath(inputPath, defaultPath = process.cwd()) {
 	// Use default if not provided
@@ -32,11 +33,28 @@ export async function validateCwdPath(inputPath, defaultPath = process.cwd()) {
 	try {
 		const stats = await fs.stat(normalizedPath);
 		if (!stats.isDirectory()) {
-			throw new Error(`Path is not a directory: ${normalizedPath}`);
+			throw new PathError(`Path is not a directory: ${normalizedPath}`, {
+				suggestion: 'The specified path is a file, not a directory. Please provide a directory path for searching.',
+				details: { path: normalizedPath, type: 'file' }
+			});
 		}
 	} catch (error) {
+		// Re-throw if already a PathError
+		if (error instanceof PathError) {
+			throw error;
+		}
 		if (error.code === 'ENOENT') {
-			throw new Error(`Path does not exist: ${normalizedPath}`);
+			throw new PathError(`Path does not exist: ${normalizedPath}`, {
+				suggestion: 'The specified path does not exist. Please verify the path is correct or use a different directory.',
+				details: { path: normalizedPath }
+			});
+		}
+		if (error.code === 'EACCES') {
+			throw new PathError(`Permission denied: ${normalizedPath}`, {
+				recoverable: false,
+				suggestion: 'Permission denied accessing this path. This is a system-level restriction.',
+				details: { path: normalizedPath }
+			});
 		}
 		throw error;
 	}