@causyne/agent 0.0.0-stage → 1.10.0

package/src/tools/browserAutomator.js

@@ -0,0 +1,252 @@
+import os from 'os';
+import fs from 'fs';
+import path from 'path';
+import { ensureCapability, loadCapabilityPackage } from '../provisioning/capabilityProvisioner.js';
+import { causyneHome } from '../utils/paths.js';
+
+function getChromeExecutablePath() {
+  const platform = os.platform();
+  if (platform === 'win32') {
+    return 'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe';
+  } else if (platform === 'darwin') {
+    return '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome';
+  } else {
+    return '/usr/bin/google-chrome';
+  }
+}
+
+function getChromeUserDataDir() {
+  const platform = os.platform();
+  const home = os.homedir();
+  if (platform === 'win32') {
+    return `${home}\\AppData\\Local\\Google\\Chrome\\User Data`;
+  } else if (platform === 'darwin') {
+    return `${home}/Library/Application Support/Google/Chrome`;
+  } else {
+    return `${home}/.config/google-chrome`;
+  }
+}
+
+let activeBrowser = null;
+let activePage = null;
+
+export const browserAct = {
+  schema: {
+    name: 'browser.act',
+    description: 'Automate Google Chrome using local profile to scrape sites or perform actions. IMPORTANT: First use "scrape" to get the page mapped to numerical indices. Then use "clickIndex" or "typeIndex" for flawless precision. Defaults to ~/.causyne/chrome_profile to protect your personal accounts from logout.',
+    parameters: {
+      type: 'object',
+      properties: {
+        usePersonalProfile: {
+          type: 'boolean',
+          description: 'Set to true ONLY if you explicitly want to use your personal Google Chrome profile. Defaults to false (uses safe dedicated profile ~/.causyne/chrome_profile).'
+        },
+        profileDirectory: {
+          type: 'string',
+          description: 'Specific profile sub-folder when usePersonalProfile is true (e.g. "Profile 1", "Default", "Profile 2").'
+        },
+        actions: {
+          type: 'array',
+          description: 'List of actions to perform in order',
+          items: {
+            type: 'object',
+            properties: {
+              type: { type: 'string', enum: ['goto', 'click', 'type', 'clickIndex', 'typeIndex', 'waitFor', 'scrape', 'selectOption', 'keyPress', 'scroll'] },
+              url: { type: 'string' },
+              selector: { type: 'string', description: 'CSS selector (legacy)' },
+              index: { type: 'number', description: 'Element index from the scrape map' },
+              text: { type: 'string' },
+              value: { type: 'string', description: 'Option value to select in dropdowns' },
+              key: { type: 'string', description: 'Key to press (Enter, Tab, ArrowDown, etc.)' },
+              humanDelayMs: { type: 'number', description: 'Keystroke delay in ms for natural human-like typing (default 45ms)' },
+              timeoutMs: { type: 'number' }
+            },
+            required: ['type']
+          }
+        }
+      },
+      required: ['actions']
+    }
+  },
+  async execute(args) {
+    const vision = await ensureCapability('vision');
+    if (!vision.ok) return { success: false, error: vision.reason, requiresConsent: vision.requiresConsent };
+    const puppeteer = await loadCapabilityPackage('puppeteer-core');
+
+    let results = [];
+
+    try {
+      if (!activeBrowser || !activeBrowser.isConnected()) {
+        const executablePath = getChromeExecutablePath();
+        const primaryUserDataDir = getChromeUserDataDir();
+        let connectedOrLaunched = false;
+        
+        // Layer 1: Attempt connection to active Chrome Remote Debugging port (9222) for zero-interruption live session reuse
+        try {
+          const controller = new AbortController();
+          const timeoutId = setTimeout(() => controller.abort(), 600);
+          const resp = await fetch('http://127.0.0.1:9222/json/version', { signal: controller.signal });
+          clearTimeout(timeoutId);
+          if (resp.ok) {
+            const data = await resp.json();
+            if (data.webSocketDebuggerUrl) {
+              activeBrowser = await puppeteer.connect({
+                browserWSEndpoint: data.webSocketDebuggerUrl,
+                defaultViewport: null
+              });
+              connectedOrLaunched = true;
+              results.push('[Sovereign Browser] Attached directly to active Chrome session via port 9222 (Layer 1).');
+            }
+          }
+        } catch (debugErr) {
+          // Port 9222 not active, proceed to Layer 2 / Layer 3 decision
+        }
+
+        // Sovereign Guard: Decide whether to launch dedicated profile (Layer 2) or personal profile (Layer 3)
+        if (!connectedOrLaunched) {
+          const fallbackDir = path.join(causyneHome(), 'chrome_profile');
+          if (!fs.existsSync(fallbackDir)) fs.mkdirSync(fallbackDir, { recursive: true });
+
+          if (!args.usePersonalProfile) {
+            // Layer 2: Sovereign Dedicated Agent Profile (100% Safe - Never risks logging out personal Chrome accounts)
+            activeBrowser = await puppeteer.launch({
+              executablePath,
+              userDataDir: fallbackDir,
+              headless: false,
+              defaultViewport: null,
+              args: ['--no-sandbox', '--disable-setuid-sandbox']
+            });
+            connectedOrLaunched = true;
+            results.push('[Sovereign Browser] Launched Chrome using Sovereign Dedicated Profile (~/.causyne/chrome_profile). Your personal Google Chrome accounts remain 100% untouched and protected.');
+          } else {
+            // Layer 3: Explicit Personal Profile Guard (Strictly when usePersonalProfile: true is requested)
+            try {
+              const profileArgs = ['--no-sandbox', '--disable-setuid-sandbox'];
+              if (args.profileDirectory) {
+                profileArgs.push(`--profile-directory=${args.profileDirectory}`);
+              }
+              activeBrowser = await puppeteer.launch({
+                executablePath,
+                userDataDir: primaryUserDataDir,
+                headless: false,
+                defaultViewport: null,
+                args: profileArgs
+              });
+              connectedOrLaunched = true;
+              results.push(`[Sovereign Browser] Launched primary profile (${args.profileDirectory || 'Default'}) explicitly requested via usePersonalProfile.`);
+            } catch (launchErr) {
+              const isProfileLock = launchErr.message.includes('already running') ||
+                                    launchErr.message.includes('SingletonLock') ||
+                                    launchErr.message.includes('EBUSY') ||
+                                    launchErr.message.includes('lock') ||
+                                    launchErr.message.includes('user data directory is already in use');
+              if (isProfileLock) {
+                // Safe fallback to dedicated profile so task never fails and never corrupts personal cookies
+                results.push(`[Sovereign Profile Guard] Your personal Chrome profile (${args.profileDirectory || 'Default'}) is currently running and locked without remote debugging port 9222. Automatically switched to Sovereign Dedicated Profile (~/.causyne/chrome_profile) to protect your personal account session from logout.`);
+                activeBrowser = await puppeteer.launch({
+                  executablePath,
+                  userDataDir: fallbackDir,
+                  headless: false,
+                  defaultViewport: null,
+                  args: ['--no-sandbox', '--disable-setuid-sandbox']
+                });
+                connectedOrLaunched = true;
+              } else {
+                throw launchErr;
+              }
+            }
+          }
+        }
+
+        const pages = await activeBrowser.pages();
+        activePage = pages[0] || (await activeBrowser.newPage());
+      }
+
+      for (const action of args.actions) {
+        if (action.type === 'goto') {
+          await activePage.goto(action.url, { waitUntil: 'networkidle2' });
+          results.push(`Navigated to ${action.url}`);
+        } 
+        else if (action.type === 'click') {
+          await activePage.waitForSelector(action.selector, { timeout: action.timeoutMs || 5000 });
+          await activePage.click(action.selector);
+          results.push(`Clicked ${action.selector}`);
+        } 
+        else if (action.type === 'type') {
+          await activePage.waitForSelector(action.selector, { timeout: action.timeoutMs || 5000 });
+          await activePage.type(action.selector, action.text, { delay: action.humanDelayMs || 45 });
+          results.push(`Typed text into ${action.selector} with human keystroke delay`);
+        }
+        // Phase 1 AGI Upgrade: DOM-to-Markdown Interaction
+        else if (action.type === 'clickIndex') {
+          const selector = `[data-causyne-id="${action.index}"]`;
+          await activePage.waitForSelector(selector, { timeout: action.timeoutMs || 5000 });
+          await activePage.click(selector);
+          results.push(`Clicked element mapped to index [${action.index}]`);
+        }
+        else if (action.type === 'typeIndex') {
+          const selector = `[data-causyne-id="${action.index}"]`;
+          await activePage.waitForSelector(selector, { timeout: action.timeoutMs || 5000 });
+          await activePage.type(selector, action.text, { delay: action.humanDelayMs || 45 });
+          results.push(`Typed text into element mapped to index [${action.index}] with human keystroke delay`);
+        }
+        else if (action.type === 'selectOption') {
+          if (action.index !== undefined) {
+            const selector = `[data-causyne-id="${action.index}"]`;
+            await activePage.waitForSelector(selector, { timeout: action.timeoutMs || 5000 });
+            await activePage.select(selector, action.value || action.text);
+          } else if (action.selector) {
+            await activePage.waitForSelector(action.selector, { timeout: action.timeoutMs || 5000 });
+            await activePage.select(action.selector, action.value || action.text);
+          }
+          results.push(`Selected option [${action.value || action.text}] from dropdown`);
+        }
+        else if (action.type === 'keyPress') {
+          await activePage.keyboard.press(action.key || 'Enter');
+          results.push(`Pressed keyboard key [${action.key || 'Enter'}]`);
+        }
+        else if (action.type === 'scroll') {
+          await activePage.evaluate(() => {
+            window.scrollBy({ top: window.innerHeight * 0.75, behavior: 'smooth' });
+          });
+          results.push(`Scrolled page smoothly`);
+        }
+        else if (action.type === 'waitFor') {
+          await activePage.waitForSelector(action.selector, { timeout: action.timeoutMs || 10000 });
+          results.push(`Element ${action.selector} appeared`);
+        } 
+        else if (action.type === 'scrape') {
+          // Phase 1 AGI Upgrade: AXTree Mapper injection
+          const mappedMarkdown = await activePage.evaluate(() => {
+            let idx = 1;
+            let lines = [];
+            const elements = document.querySelectorAll('a, button, input, textarea, [role="button"], select');
+            
+            elements.forEach(el => {
+              // Ignore hidden elements
+              const style = window.getComputedStyle(el);
+              if (style.display === 'none' || style.visibility === 'hidden' || el.offsetWidth === 0) return;
+              
+              let label = el.innerText || el.value || el.placeholder || el.getAttribute('aria-label') || el.name || 'unlabeled';
+              label = label.trim().replace(/\n/g, ' ');
+              if (!label) return; // Skip empty elements
+              
+              const tagName = el.tagName.toLowerCase();
+              lines.push(`[${idx}] ${tagName}: ${label}`);
+              
+              el.setAttribute('data-causyne-id', idx.toString());
+              idx++;
+            });
+            return lines.join('\n');
+          });
+          
+          results.push(`Scraped DOM Map:\n${mappedMarkdown}`);
+        }
+      }
+      
+      return { success: true, log: results };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+};

package/src/tools/checkSystemSpecs.js

@@ -0,0 +1,64 @@
+import os from 'os';
+import fs from 'fs/promises';
+
+export const checkSystemSpecs = {
+  schema: {
+    name: 'check_system_specs',
+    description: 'Check the hardware specifications of the local machine (RAM, CPU, OS, Disk Space) to evaluate if it can run heavyweight local AI models.',
+    parameters: {
+      type: 'object',
+      properties: {},
+      required: []
+    }
+  },
+  
+  execute: async (args, sandbox) => {
+    try {
+      const totalMemMB = Math.round(os.totalmem() / 1024 / 1024);
+      let freeMemMB = Math.round(os.freemem() / 1024 / 1024);
+      const cpuCores = os.cpus().length;
+      const cpuModel = os.cpus()[0]?.model || 'Unknown CPU';
+      const platform = os.platform();
+      const arch = os.arch();
+      
+      // Phase 1 AGI Upgrade: Native Memory Math (macOS Approximation without shell)
+      if (platform === 'darwin') {
+        // os.freemem() on Mac only shows "free", not "inactive" memory.
+        // We use a safe heuristic based on total memory minus an active buffer baseline.
+        // This avoids brittle shell execution (`vm_stat`).
+        const usedApproximation = totalMemMB - freeMemMB;
+        const inactiveApproximation = usedApproximation * 0.4; // rough estimate of inactive
+        freeMemMB = Math.round(freeMemMB + inactiveApproximation);
+      }
+
+      // Phase 1 AGI Upgrade: Native Disk Math
+      let diskSpace = "Unknown";
+      try {
+        const checkPath = (sandbox && sandbox.workspacePaths && sandbox.workspacePaths.length > 0) 
+            ? sandbox.workspacePaths[0] 
+            : process.cwd();
+            
+        const stats = await fs.statfs(checkPath);
+        // bavail (available blocks) * bsize (block size)
+        const freeBytes = stats.bavail * stats.bsize;
+        diskSpace = Math.round(freeBytes / 1024 / 1024 / 1024) + ' GB available';
+      } catch (e) {
+        diskSpace = "Could not verify disk space: " + e.message;
+      }
+
+      return {
+        success: true,
+        totalRamMB: totalMemMB,
+        freeRamMB: freeMemMB,
+        cpuCores: cpuCores,
+        cpuModel: cpuModel,
+        platform: platform,
+        architecture: arch,
+        diskSpace: diskSpace,
+        advice: freeMemMB < 4000 ? "WARNING: Less than 4GB RAM available. Insufficient for Stage 2 (Local AI Models). Please transition directly to Stage 3 (Pollinations Mode D), Stage 4 (Web Search), or Stage 5 (Procedural Mode A)." : "OK: Sufficient memory for Stage 2 (Local AI Models Mode B/C) execution."
+      };
+    } catch (err) {
+      return { success: false, error: err.message };
+    }
+  }
+};

package/src/tools/clipboard.js

@@ -0,0 +1,36 @@
+import { ensureCapability, loadCapabilityPackage } from '../provisioning/capabilityProvisioner.js';
+export const clipboard = {
+  schema: {
+    name: 'clipboard',
+    description: 'Read or write to the system clipboard securely without shell execution.',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: { type: 'string', enum: ['read', 'write'], description: 'Action to perform' },
+        text: { type: 'string', description: 'Text to write to the clipboard (required if action is write)' }
+      },
+      required: ['action']
+    }
+  },
+  async execute(args) {
+    try {
+      const capability = await ensureCapability('desktop');
+      if (!capability.ok) return { success: false, error: capability.reason, requiresConsent: capability.requiresConsent };
+      const clipboardy = await loadCapabilityPackage('clipboardy');
+
+      if (args.action === 'read') {
+        const content = await clipboardy.read();
+        return { success: true, output: content };
+      } 
+      else if (args.action === 'write') {
+        if (!args.text) {
+          return { success: false, error: 'Text argument is required for write action' };
+        }
+        await clipboardy.write(args.text);
+        return { success: true, output: `Successfully wrote ${Buffer.byteLength(args.text, 'utf8')} bytes to OS Clipboard.` };
+      }
+    } catch (error) {
+      return { success: false, error: `Clipboard action failed: ${error.message}` };
+    }
+  }
+};

package/src/tools/codeSearchAst.js

@@ -0,0 +1,101 @@
+import fs from 'fs';
+import path from 'path';
+import * as acorn from 'acorn';
+import * as walk from 'acorn-walk';
+
+export const codeSearchAst = {
+  schema: {
+    name: 'code_search_ast',
+    description: "Search for function, class, and variable definitions in a file using AST (Abstract Syntax Tree) without loading the entire file body. Ideal for understanding large codebases without eating up context window tokens.",
+    parameters: {
+      type: "object",
+      properties: {
+        targetFile: {
+          type: "string",
+          description: "Absolute path to the file to parse."
+        }
+      },
+      required: ["targetFile"]
+    }
+  },
+
+  // Named execute() like every other tool — as run() it was registered but the
+  // agent loop's toolRegistry[name].execute lookup could never reach it.
+  async execute({ targetFile }) {
+    if (!fs.existsSync(targetFile)) {
+      return `Error: File not found at ${targetFile}`;
+    }
+
+    try {
+      const code = fs.readFileSync(targetFile, 'utf8');
+      const ext = path.extname(targetFile).toLowerCase();
+      let output = `File: ${targetFile}\nStructure Summary:\n\n`;
+
+      if (ext === '.js' || ext === '.ts' || ext === '.jsx' || ext === '.tsx') {
+        // Use Acorn for deep, accurate JS/TS parsing
+        // We configure acorn to allow modern syntax and jsx/ts (tolerant mode via loose/default)
+        // Note: acorn natively only supports standard JS. For TS/JSX, we use standard regex fallback if acorn fails.
+        try {
+          const ast = acorn.parse(code, { ecmaVersion: 'latest', sourceType: 'module' });
+          const structures = [];
+
+          walk.simple(ast, {
+            FunctionDeclaration(node) {
+              const name = node.id ? node.id.name : 'anonymous';
+              structures.push(`Function: ${name}(...) [Line: ${node.loc ? node.loc.start.line : 'unknown'}]`);
+            },
+            ClassDeclaration(node) {
+              const name = node.id ? node.id.name : 'anonymous';
+              structures.push(`Class: ${name} [Line: ${node.loc ? node.loc.start.line : 'unknown'}]`);
+            },
+            VariableDeclarator(node) {
+              if (node.id && node.id.name && node.init) {
+                if (node.init.type === 'ArrowFunctionExpression' || node.init.type === 'FunctionExpression') {
+                  structures.push(`Arrow/Var Function: ${node.id.name} [Line: ${node.loc ? node.loc.start.line : 'unknown'}]`);
+                } else if (node.id.name.toUpperCase() === node.id.name) { // Detect constants
+                  structures.push(`Constant: ${node.id.name}`);
+                }
+              }
+            }
+          });
+
+          if (structures.length === 0) {
+            output += "No major functions or classes found via AST.\n";
+          } else {
+            output += structures.join('\n');
+          }
+          return output;
+
+        } catch (acornError) {
+          // If acorn fails (e.g., on TS or JSX syntax), fallback to regex
+          output += `[AST Parse Warning: ${acornError.message}. Falling back to Regex Pseudo-AST]\n`;
+        }
+      }
+
+      // Regex Pseudo-AST Fallback (for Python, Java, Go, or TS/JSX if acorn fails)
+      const lines = code.split('\n');
+      const results = [];
+      const functionRegex = /^(?:export\s+)?(?:async\s+)?(?:function\s+|class\s+|const\s+\w+\s*=\s*(?:async\s*)?(?:\([^)]*\)|[^=]+)\s*=>|def\s+|class\s+|func\s+|public\s+class\s+|public\s+static\s+|type\s+|interface\s+)/;
+
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (functionRegex.test(line)) {
+          // Clean up the line to just show the signature (remove opening brace if present)
+          let signature = line.replace(/\{$/, '').trim();
+          results.push(`Line ${i + 1}: ${signature}`);
+        }
+      }
+
+      if (results.length === 0) {
+        output += "No structural definitions found.\n";
+      } else {
+        output += results.join('\n');
+      }
+
+      return output;
+
+    } catch (e) {
+      return `Error analyzing file: ${e.message}`;
+    }
+  }
+};

package/src/tools/codeSearcher.js

@@ -0,0 +1,230 @@
+import fs from 'fs/promises';
+import fsSync from 'fs';
+import path from 'path';
+import os from 'os';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { causyneHome } from '../utils/paths.js';
+
+const execFileAsync = promisify(execFile);
+
+// Helper: Check system ripgrep binary availability
+function getRipgrepBinary() {
+  const isWin = process.platform === 'win32';
+  const candidates = isWin
+    ? ['C:\\Program Files\\ripgrep\\rg.exe', 'rg.exe']
+    : ['/opt/homebrew/bin/rg', '/usr/local/bin/rg', '/usr/bin/rg', 'rg'];
+
+  for (const bin of candidates) {
+    try {
+      if (fsSync.existsSync(bin)) return bin;
+    } catch (e) {}
+  }
+  return null;
+}
+
+// Helper: V5 Cortex SQLite Cache (non-blocking schema init)
+function getCortexDb() {
+  try {
+    const dbPath = path.join(causyneHome(), 'cortex.db');
+    if (!fsSync.existsSync(path.dirname(dbPath))) {
+      fsSync.mkdirSync(path.dirname(dbPath), { recursive: true });
+    }
+    // Lazy check if better-sqlite3 is available in dependencies
+    const Database = require('better-sqlite3');
+    const db = new Database(dbPath, { timeout: 2000 });
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS code_search_cache (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        query TEXT,
+        search_path TEXT,
+        results_json TEXT,
+        timestamp DATETIME DEFAULT CURRENT_TIMESTAMP
+      );
+      CREATE INDEX IF NOT EXISTS idx_code_search_query ON code_search_cache(query, search_path);
+    `);
+    return db;
+  } catch (e) {
+    return null;
+  }
+}
+
+export const codeSearcher = {
+  schema: {
+    name: 'code.search_ripgrep',
+    description: 'Blazing fast regex, string, and AST symbol search across entire codebases using dual-engine ripgrep + fast Node stream and V5 Cortex SQLite caching. Surpasses standard CLI glob search.',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'The exact string, symbol, or regular expression pattern to look for across files.' },
+        searchPath: { type: 'string', description: 'Absolute root directory or file path to search. Defaults to current working directory.' },
+        isRegex: { type: 'boolean', description: 'If true, treats query as a regular expression pattern. If false, treats as literal string.' },
+        caseInsensitive: { type: 'boolean', description: 'If true, performs case-insensitive search (default true).' },
+        filePattern: { type: 'string', description: 'Optional glob filter (e.g. "*.js", "*.py", "*.kt", "*.ts") to restrict search to specific file extensions.' },
+        astMode: { type: 'boolean', description: 'If true, filters results specifically for AST symbol definitions (classes, functions, interfaces, structs, defs).' }
+      },
+      required: ['query']
+    }
+  },
+
+  async execute(args) {
+    try {
+      const query = args.query;
+      if (!query) return { success: false, error: 'Query parameter is required.' };
+
+      const targetDir = (args.searchPath || process.cwd()).replace(/^~\//, os.homedir() + '/');
+      const isRegex = args.isRegex === true;
+      const caseInsensitive = args.caseInsensitive !== false; // default true
+      const filePattern = args.filePattern || '*';
+      const astMode = args.astMode === true;
+
+      // Check V5 Cortex SQLite Cache first
+      let db = null;
+      try {
+        db = getCortexDb();
+        if (db) {
+          const cacheKey = `${query}_${isRegex}_${caseInsensitive}_${filePattern}_${astMode}`;
+          const row = db.prepare('SELECT results_json FROM code_search_cache WHERE query = ? AND search_path = ? AND timestamp >= datetime("now", "-10 minutes") LIMIT 1').get(cacheKey, targetDir);
+          if (row && row.results_json) {
+            const cachedResults = JSON.parse(row.results_json);
+            return {
+              success: true,
+              output: JSON.stringify({
+                engine: 'Cortex Neural Cache (0ms)',
+                query: query,
+                total_matches: cachedResults.length,
+                matches: cachedResults
+              }, null, 2)
+            };
+          }
+        }
+      } catch (cacheErr) {}
+
+      const matches = [];
+      const MAX_MATCHES = 100;
+      const rgBin = getRipgrepBinary();
+
+      // Dual-Engine 1: Ripgrep Binary
+      if (rgBin) {
+        const rgArgs = ['-n', '--no-heading', `--max-count=${MAX_MATCHES}`];
+        if (caseInsensitive) rgArgs.push('-i');
+        if (!isRegex) rgArgs.push('-F');
+        if (filePattern && filePattern !== '*') rgArgs.push('-g', filePattern);
+        
+        // If AST mode, build an AST regex around the symbol
+        let finalQuery = query;
+        if (astMode && !isRegex) {
+          rgArgs.push('-e');
+          finalQuery = `(class|function|def|interface|struct|const|let|var|type|func|module)\\s+[^\\s(]*${query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`;
+        } else {
+          rgArgs.push('-e', finalQuery);
+        }
+        rgArgs.push(targetDir);
+
+        try {
+          const { stdout } = await execFileAsync(rgBin, rgArgs, { maxBuffer: 10 * 1024 * 1024 });
+          const lines = stdout.split('\n').filter(Boolean);
+          for (const line of lines) {
+            if (matches.length >= MAX_MATCHES) break;
+            const parts = line.split(':');
+            if (parts.length >= 3) {
+              const file = parts[0];
+              const lineNo = parseInt(parts[1], 10) || 0;
+              const content = parts.slice(2).join(':').trim();
+              matches.push({ File: file, LineNumber: lineNo, LineContent: content });
+            }
+          }
+        } catch (rgErr) {
+          // If exit code is 1, ripgrep simply found no matches. Otherwise fall through to Node stream.
+          if (rgErr.code !== 1 && rgErr.code !== 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') {
+            // Fallback to async Node stream
+          }
+        }
+      }
+
+      // Dual-Engine 2: Fast Asynchronous Node Stream Fallback (if rg returned empty or not installed)
+      if (matches.length === 0 && (!rgBin || !fsSync.existsSync(rgBin))) {
+        const EXCLUDE_DIRS = new Set(['node_modules', '.git', '.gradle', 'build', 'dist', '.idea', '.causyne_trash']);
+        
+        let patternRegExp;
+        try {
+          let pat = isRegex ? query : query.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+          if (astMode && !isRegex) {
+            pat = `(class|function|def|interface|struct|const|let|var|type|func|module)\\s+[^\\s(]*${pat}`;
+          }
+          patternRegExp = new RegExp(pat, caseInsensitive ? 'i' : '');
+        } catch (regErr) {
+          return { success: false, error: `Invalid regex pattern: ${regErr.message}` };
+        }
+
+        const extFilter = (filePattern && filePattern !== '*' && filePattern.startsWith('*.'))
+          ? filePattern.slice(1).toLowerCase()
+          : null;
+
+        async function walkSearch(dir) {
+          if (matches.length >= MAX_MATCHES) return;
+          let dirents;
+          try {
+            dirents = await fs.readdir(dir, { withFileTypes: true });
+          } catch (e) {
+            return;
+          }
+
+          const promises = [];
+          for (const dirent of dirents) {
+            if (matches.length >= MAX_MATCHES) break;
+            if (dirent.isDirectory()) {
+              if (!EXCLUDE_DIRS.has(dirent.name)) {
+                promises.push(walkSearch(path.join(dir, dirent.name)));
+              }
+            } else if (dirent.isFile()) {
+              if (extFilter && !dirent.name.toLowerCase().endsWith(extFilter)) continue;
+              
+              promises.push(
+                fs.readFile(path.join(dir, dirent.name), 'utf8')
+                  .then(content => {
+                    const lines = content.split('\n');
+                    for (let i = 0; i < lines.length; i++) {
+                      if (matches.length >= MAX_MATCHES) break;
+                      if (patternRegExp.test(lines[i])) {
+                        matches.push({
+                          File: path.join(dir, dirent.name),
+                          LineNumber: i + 1,
+                          LineContent: lines[i].trim()
+                        });
+                      }
+                    }
+                  })
+                  .catch(() => {}) // Ignore binary/unreadable files
+              );
+            }
+          }
+          await Promise.all(promises);
+        }
+
+        await walkSearch(targetDir);
+      }
+
+      // Cache matches in Cortex SQLite if db active
+      if (db && matches.length > 0) {
+        try {
+          const cacheKey = `${query}_${isRegex}_${caseInsensitive}_${filePattern}_${astMode}`;
+          db.prepare('INSERT INTO code_search_cache (query, search_path, results_json) VALUES (?, ?, ?)')
+            .run(cacheKey, targetDir, JSON.stringify(matches));
+        } catch (cacheStoreErr) {}
+      }
+
+      return {
+        success: true,
+        output: JSON.stringify({
+          engine: rgBin ? `Ripgrep Binary (${rgBin})` : 'Node Async Stream Engine',
+          query: query,
+          total_matches: matches.length,
+          matches: matches.length > 0 ? matches : "No matches found in target codebase."
+        }, null, 2)
+      };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+};