@probelabs/probe 0.6.0-rc229 → 0.6.0-rc231

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@probelabs/probe",
-  "version": "0.6.0-rc229",
+  "version": "0.6.0-rc231",
   "description": "Node.js wrapper for the probe code search tool",
   "main": "src/index.js",
   "module": "src/index.js",
@@ -79,7 +79,7 @@
     "@ai-sdk/openai": "^2.0.10",
     "@anthropic-ai/claude-agent-sdk": "^0.1.46",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@probelabs/maid": "^0.0.23",
+    "@probelabs/maid": "^0.0.24",
     "adm-zip": "^0.5.16",
     "ai": "^5.0.0",
     "ajv": "^8.17.1",

package/src/agent/ProbeAgent.js

@@ -58,6 +58,8 @@ import {
   implementToolDefinition,
   editToolDefinition,
   createToolDefinition,
+  googleSearchToolDefinition,
+  urlContextToolDefinition,
   attemptCompletionSchema,
   parseXmlToolCallWithThinking
 } from './tools.js';
@@ -404,6 +406,10 @@ export class ProbeAgent {
     // Initialize the AI model
     this.initializeModel();
 
+    // Gemini built-in tools (provider-defined, server-side)
+    // These are enabled automatically when the provider is Google
+    this._geminiToolsEnabled = this._initializeGeminiBuiltinTools();
+
     // Note: MCP initialization is now done in initialize() method
     // Constructor must remain synchronous for backward compatibility
   }
@@ -1320,6 +1326,15 @@ export class ProbeAgent {
           abortSignal: controller.signal
         };
 
+        // Strip Gemini provider-defined tools when falling back to non-Google provider
+        // These tools have no execute function and would cause errors on other providers
+        if (config.provider !== 'google' && fallbackOptions.tools) {
+          delete fallbackOptions.tools;
+          if (this.debug) {
+            console.error(`[DEBUG] Stripped Gemini built-in tools for fallback to ${config.provider} provider`);
+          }
+        }
+
         const providerRetryManager = new RetryManager({
           maxRetries: config.maxRetries ?? this.retryConfig.maxRetries ?? 3,
           initialDelay: this.retryConfig.initialDelay ?? 1000,
@@ -1442,6 +1457,83 @@ export class ProbeAgent {
     }
   }
 
+  /**
+   * Initialize Gemini built-in tools (gemini_google_search, gemini_url_context).
+   * These are provider-defined tools that execute server-side on Google's infrastructure.
+   * They are only available when the provider is Google Gemini.
+   * @returns {{ googleSearch: boolean, urlContext: boolean }} Which tools were enabled
+   * @private
+   */
+  _initializeGeminiBuiltinTools() {
+    const isToolAllowed = (toolName) => this.allowedTools.isEnabled(toolName);
+    const result = { googleSearch: false, urlContext: false };
+
+    if (this.apiType !== 'google') {
+      // Log info about unavailability for non-Google providers
+      if (isToolAllowed('gemini_google_search') || isToolAllowed('gemini_url_context')) {
+        if (this.debug) {
+          console.error(`[DEBUG] Gemini built-in tools (gemini_google_search, gemini_url_context) are not available: provider is '${this.apiType}', not 'google'. These tools require the Google Gemini provider.`);
+        }
+      }
+      return result;
+    }
+
+    // Check SDK support
+    if (!this.provider || !this.provider.tools) {
+      console.error('[ProbeAgent] Gemini built-in tools unavailable: @ai-sdk/google does not expose provider.tools. Upgrade to @ai-sdk/google v2.0.14+.');
+      return result;
+    }
+
+    if (isToolAllowed('gemini_google_search')) {
+      result.googleSearch = true;
+      if (this.debug) {
+        console.error('[DEBUG] Gemini built-in tool enabled: gemini_google_search');
+      }
+    }
+
+    if (isToolAllowed('gemini_url_context')) {
+      result.urlContext = true;
+      if (this.debug) {
+        console.error('[DEBUG] Gemini built-in tool enabled: gemini_url_context');
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Build Gemini provider-defined tools object for streamText().
+   * Returns undefined if no Gemini tools are enabled.
+   * @returns {Object|undefined}
+   * @private
+   */
+  _buildGeminiProviderTools() {
+    if (this.apiType !== 'google' || !this._geminiToolsEnabled) {
+      return undefined;
+    }
+
+    const { googleSearch, urlContext } = this._geminiToolsEnabled;
+    if (!googleSearch && !urlContext) {
+      return undefined;
+    }
+
+    if (!this.provider || !this.provider.tools) {
+      return undefined;
+    }
+
+    const tools = {};
+    const providerTools = this.provider.tools;
+
+    if (googleSearch && providerTools.googleSearch) {
+      tools.google_search = providerTools.googleSearch({});
+    }
+    if (urlContext && providerTools.urlContext) {
+      tools.url_context = providerTools.urlContext({});
+    }
+
+    return Object.keys(tools).length > 0 ? tools : undefined;
+  }
+
   /**
    * Initialize AWS Bedrock model
    */
@@ -2404,10 +2496,9 @@ ${extractGuidance}
       toolDefinitions += `${taskToolDefinition}\n`;
     }
 
-    // Always include attempt_completion (unless explicitly disabled in raw AI mode)
-    if (isToolAllowed('attempt_completion')) {
-      toolDefinitions += `${attemptCompletionToolDefinition}\n`;
-    }
+    // Always include attempt_completion unconditionally - it's a completion signal, not a tool
+    // This ensures agents can always complete their work, regardless of tool restrictions
+    toolDefinitions += `${attemptCompletionToolDefinition}\n`;
 
     // Delegate tool (require both enableDelegate flag AND allowedTools permission)
     // Place after attempt_completion as it's an optional tool
@@ -2420,6 +2511,14 @@ ${extractGuidance}
       toolDefinitions += `${analyzeAllToolDefinition}\n`;
     }
 
+    // Gemini built-in tools (only when using Google provider)
+    if (this._geminiToolsEnabled?.googleSearch && isToolAllowed('gemini_google_search')) {
+      toolDefinitions += `${googleSearchToolDefinition}\n`;
+    }
+    if (this._geminiToolsEnabled?.urlContext && isToolAllowed('gemini_url_context')) {
+      toolDefinitions += `${urlContextToolDefinition}\n`;
+    }
+
     // Build XML tool guidelines with dynamic examples based on allowed tools
     // Build examples only for allowed tools
     let toolExamples = '';
@@ -2497,6 +2596,12 @@ The configuration is loaded from src/config.js lines 15-25 which contains the da
       availableToolsList += '- attempt_completion: Finalize the task and provide the result to the user.\n';
       availableToolsList += '- attempt_complete: Quick completion using previous response (shorthand).\n';
     }
+    if (this._geminiToolsEnabled?.googleSearch && isToolAllowed('gemini_google_search')) {
+      availableToolsList += '- gemini_google_search: (auto) Web search via Google — invoked automatically by the model when it needs current information.\n';
+    }
+    if (this._geminiToolsEnabled?.urlContext && isToolAllowed('gemini_url_context')) {
+      availableToolsList += '- gemini_url_context: (auto) URL content reader via Google — automatically fetches and reads URLs mentioned in the conversation.\n';
+    }
 
     let xmlToolGuidelines = `
 # Tool Use Formatting
@@ -3049,12 +3154,21 @@ Follow these instructions carefully:
               // Prepare messages with potential image content
               const messagesForAI = this.prepareMessagesWithImages(currentMessages);
 
-              const result = await this.streamTextWithRetryAndFallback({
+              // Build streamText options, including Gemini provider-defined tools if applicable
+              const streamOptions = {
                 model: this.provider ? this.provider(this.model) : this.model,
                 messages: messagesForAI,
                 maxTokens: maxResponseTokens,
                 temperature: 0.3,
-              });
+              };
+
+              // Inject Gemini built-in tools (gemini_google_search, gemini_url_context) when using Google provider
+              const geminiProviderTools = this._buildGeminiProviderTools();
+              if (geminiProviderTools) {
+                streamOptions.tools = geminiProviderTools;
+              }
+
+              const result = await this.streamTextWithRetryAndFallback(streamOptions);
 
               // Get the promise reference BEFORE consuming stream (doesn't lock it)
               const usagePromise = result.usage;
@@ -3189,8 +3303,9 @@ Follow these instructions carefully:
           if (this.enableSkills && this.allowedTools.isEnabled('listSkills')) validTools.push('listSkills');
           if (this.enableSkills && this.allowedTools.isEnabled('useSkill')) validTools.push('useSkill');
           if (this.allowedTools.isEnabled('readImage')) validTools.push('readImage');
-          // Always allow attempt_completion - it's a completion signal, not a tool
+          // Always allow attempt_completion in validTools - it's a completion signal, not a tool
           // This ensures agents can complete even when disableTools: true is set (fixes #333)
+          // The tool DEFINITION may be hidden in raw AI mode, but we still need to recognize it
           validTools.push('attempt_completion');
 
           // Edit tools (require both allowEdit flag AND allowedTools permission)
@@ -3585,6 +3700,12 @@ Follow these instructions carefully:
 
                 let toolResultContent = typeof toolResult === 'string' ? toolResult : JSON.stringify(toolResult, null, 2);
 
+                // Convert absolute workspace paths to relative in tool results
+                if (this.workspaceRoot && toolResultContent) {
+                  const wsPrefix = this.workspaceRoot.endsWith(sep) ? this.workspaceRoot : this.workspaceRoot + sep;
+                  toolResultContent = toolResultContent.split(wsPrefix).join('');
+                }
+
                 // Truncate if output exceeds token limit
                 try {
                   const truncateResult = await truncateIfNeeded(toolResultContent, this.tokenCounter, this.sessionId, this.maxOutputTokens);

package/src/agent/mcp/config.js

@@ -15,7 +15,13 @@ const __dirname = dirname(__filename);
  * Timeout configuration constants
  */
 export const DEFAULT_TIMEOUT = 30000; // 30 seconds
-export const MAX_TIMEOUT = 600000; // 10 minutes max to prevent resource exhaustion
+export const MAX_TIMEOUT = (() => {
+  if (process.env.MCP_MAX_TIMEOUT) {
+    const parsed = parseInt(process.env.MCP_MAX_TIMEOUT, 10);
+    if (!isNaN(parsed) && parsed >= 30000 && parsed <= 7200000) return parsed;
+  }
+  return 1800000; // 30 minutes default - workflow tools (code checkouts, AI exploration) need time
+})();
 
 /**
  * Validate and normalize a timeout value

package/src/agent/tasks/taskTool.js

@@ -23,7 +23,8 @@ export const taskItemSchema = z.object({
  */
 export const taskSchema = z.object({
   action: z.enum(['create', 'update', 'complete', 'delete', 'list']),
-  tasks: z.array(z.union([z.string(), taskItemSchema])).optional(),
+  // Accept both array and JSON string (AI models sometimes serialize as string)
+  tasks: z.union([z.array(z.union([z.string(), taskItemSchema])), z.string()]).optional(),
   id: z.string().optional(),
   title: z.string().optional(),
   description: z.string().optional(),
@@ -142,6 +143,25 @@ SKIP TASKS for single-goal requests, even if they require multiple searches:
 **Key insight**: Multiple *internal steps* (search, read, analyze) are NOT the same as multiple *goals*.
 A single investigation with many steps is still ONE task, not many.
 
+## Task Granularity
+
+Tasks represent LOGICAL UNITS OF WORK, not individual files or steps:
+- "Fix 8 similar test files" → ONE task (same type of fix across files)
+- "Update API + tests + docs" → THREE tasks (different types of work)
+- "Implement feature in 5 files" → ONE task (single feature)
+
+**Rule of thumb**: If you're creating more than 3-4 tasks, you're probably too granular.
+
+**Anti-patterns to avoid**:
+- One task per file ❌
+- One task per function ❌
+- One task per repository (when same type of work) ❌
+
+**Good patterns**:
+- One task per distinct deliverable ✓
+- One task per phase (implement, test, document) ✓
+- One task per different type of work ✓
+
 MODIFY TASKS when (during execution):
 - You discover the problem is more complex than expected → Add new tasks
 - A single task covers too much scope → Split into smaller tasks
@@ -314,7 +334,17 @@ export function createTaskTool(options = {}) {
           return `Error: Invalid task parameters - ${validation.error.message}`;
         }
 
-        const { action, tasks, id, title, description, status, priority, dependencies, after } = validation.data;
+        const { action, tasks: rawTasks, id, title, description, status, priority, dependencies, after } = validation.data;
+
+        // Parse tasks if passed as JSON string (common AI model behavior)
+        let tasks = rawTasks;
+        if (typeof rawTasks === 'string') {
+          try {
+            tasks = JSON.parse(rawTasks);
+          } catch (e) {
+            return `Error: Invalid tasks JSON - ${e.message}`;
+          }
+        }
 
         switch (action) {
           case 'create': {

package/src/agent/tools.js

@@ -27,6 +27,8 @@ import {
   bashToolDefinition,
   editToolDefinition,
   createToolDefinition,
+  googleSearchToolDefinition,
+  urlContextToolDefinition,
   parseXmlToolCall
 } from '../index.js';
 import { randomUUID } from 'crypto';
@@ -108,6 +110,8 @@ export {
   editToolDefinition,
   createToolDefinition,
   attemptCompletionToolDefinition,
+  googleSearchToolDefinition,
+  urlContextToolDefinition,
   parseXmlToolCall
 };
 

package/src/index.js

@@ -35,6 +35,8 @@ import {
 	analyzeAllToolDefinition,
 	attemptCompletionToolDefinition,
 	bashToolDefinition,
+	googleSearchToolDefinition,
+	urlContextToolDefinition,
 	parseXmlToolCall
 } from './tools/common.js';
 import {
@@ -114,6 +116,8 @@ export {
 	bashToolDefinition,
 	editToolDefinition,
 	createToolDefinition,
+	googleSearchToolDefinition,
+	urlContextToolDefinition,
 	// Export parser function
 	parseXmlToolCall,
 	// Export task management

package/src/tools/common.js

@@ -386,6 +386,30 @@ User: Check system info
 </examples>
 `;
 
+export const googleSearchToolDefinition = `
+## gemini_google_search (Gemini Built-in)
+Description: Web search powered by Google. This is a built-in Gemini capability that automatically searches the web when the model needs current information. The model decides when to search and integrates results directly into its response with source citations.
+
+This tool is invoked automatically by the model — you do NOT need to use XML tool calls for it. Simply ask questions that require up-to-date or real-world information and the model will search the web as needed.
+
+Capabilities:
+- Real-time web search with grounded citations
+- Automatic query generation and result synthesis
+- Source attribution with URLs
+`;
+
+export const urlContextToolDefinition = `
+## gemini_url_context (Gemini Built-in)
+Description: URL content reader powered by Google. This is a built-in Gemini capability that automatically fetches and analyzes the content of URLs mentioned in the conversation. When you include URLs in your message, the model can read and understand their content.
+
+This tool is invoked automatically by the model — you do NOT need to use XML tool calls for it. Simply include URLs in your message and the model will fetch and analyze their content.
+
+Capabilities:
+- Fetch and read web page content from URLs in the prompt
+- Supports up to 20 URLs per request
+- Processes HTML content (does not execute JavaScript)
+`;
+
 export const searchDescription = 'Search code in the repository. Free-form questions are accepted, but Elasticsearch-style keyword queries work best. Use this tool first for any code-related questions.';
 export const queryDescription = 'Search code using ast-grep structural pattern matching. Use this tool to find specific code structures like functions, classes, or methods.';
 export const extractDescription = 'Extract code blocks from files based on file paths and optional line numbers. Use this tool to see complete context after finding relevant files.';

package/src/utils/path-validation.js

@@ -55,9 +55,9 @@ export function safeRealpath(inputPath) {
  * - Does NOT restrict access to specific directories (that's the responsibility
  *   of higher-level components like ProbeAgent with allowedFolders)
  *
- * @param {string} inputPath - The path to validate
+ * @param {string} inputPath - The path to validate (can be a file or directory; file paths are resolved to their parent directory)
  * @param {string} [defaultPath] - Default path to use if inputPath is not provided
- * @returns {Promise<string>} Normalized absolute path
+ * @returns {Promise<string>} Normalized absolute directory path. If inputPath is a file, returns its parent directory.
  * @throws {PathError} If the path is invalid or doesn't exist
  */
 export async function validateCwdPath(inputPath, defaultPath = process.cwd()) {
@@ -72,6 +72,32 @@ export async function validateCwdPath(inputPath, defaultPath = process.cwd()) {
 	try {
 		const stats = await fs.stat(normalizedPath);
 		if (!stats.isDirectory()) {
+			// If the path is a file, resolve to its parent directory
+			// This handles cases where a file path is passed as cwd
+			// Use safeRealpath to resolve symlinks before extracting parent directory
+			const resolvedPath = safeRealpath(normalizedPath);
+			const dirPath = path.dirname(resolvedPath);
+			try {
+				const dirStats = await fs.stat(dirPath);
+				if (dirStats.isDirectory()) {
+					return safeRealpath(dirPath);
+				}
+			} catch (dirError) {
+				if (dirError.code === 'ENOENT') {
+					throw new PathError(`Parent directory does not exist for file: ${normalizedPath}`, {
+						suggestion: 'The specified path is a file whose parent directory does not exist.',
+						details: { path: normalizedPath, parentPath: dirPath, type: 'file' }
+					});
+				}
+				if (dirError.code === 'EACCES') {
+					throw new PathError(`Permission denied accessing parent directory: ${dirPath}`, {
+						recoverable: false,
+						suggestion: 'Permission denied accessing the parent directory of the specified file.',
+						details: { path: normalizedPath, parentPath: dirPath, type: 'file' }
+					});
+				}
+				throw dirError;
+			}
 			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' }