cowork-cli 1.1.0 → 2.0.0

package/README.md

@@ -56,6 +56,7 @@ cwk "Explain the data flow in the engine/ models"
 - **Zero-Whitespace UI**: High-density terminal output designed for professionals. No fluff, no headers, just data.
 - **Interactive Feedback**: The AI can request clarifications via the `askUser` tool or trigger an interactive `[ Yes ]  No` toggle using `askConfirm`.
 - **Smart Discovery**: Built-in `searchText`, `findFile`, and `projectTree` tools that respect your `.gitignore`.
+- **Web Research**: Dynamically search the web (`webSearch`) and read documentation (`webFetch`) directly from the CLI.
 - **Surgical I/O**: Read entire files or specific line ranges (`readFileChunk`) with automatic binary detection.
 - **Piping Support**: Pipe logs or diffs directly into `cwk` for instant analysis.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cowork-cli",
-  "version": "1.1.0",
+  "version": "2.0.0",
   "description": "work with cowork",
   "bin": {
     "cwk": "bin/cli.js"
@@ -35,4 +35,4 @@
     "ipaddr.js": "^2.4.0",
     "openai": "^6.38.0"
   }
-}
+}

package/src/engine/models/BaseModel.js

@@ -181,6 +181,7 @@ export default class BaseModel {
           readFileChunk: 'peeking',
           searchText: 'searching',
           webFetch: 'fetching',
+          webSearch: 'searching web',
           findFile: 'finding',
           findDir: 'finding',
           listTools: 'listing'
@@ -189,7 +190,11 @@ export default class BaseModel {
         const label = toolLabels[name] || name;
         let displayArg = "";
 
-        if (name === 'searchText') displayArg = `'${args.pattern}' in ${args.path}`;
+        if (name === 'searchText') {
+          const ctx = (args.context != null && args.context !== 2) ? ` [C${args.context}]` : '';
+          displayArg = `'${args.pattern}' in ${args.path}${ctx}`;
+        }
+        else if (name === 'webSearch') displayArg = `'${args.query}'`;
         else if (name === 'findFile' || name === 'findDir') displayArg = `'${args.pattern}' in ${args.dirPath || '.'}`;
         else if (name === 'readFileChunk') displayArg = `${args.filePath} [L${args.startLine}-${args.endLine}]`;
         else displayArg = args.url || args.filePath || args.dirPath || args.path || args.pattern || JSON.stringify(args);

package/src/engine/tools/findDir.js

@@ -1,6 +1,6 @@
 import fs from 'fs/promises';
 import path from 'path';
-import { getIgnorePatterns, shouldIgnore } from '../../utils/fsUtils.js';
+import { getIgnorePatterns, isSafeEntry, loadNestedIgnores, safePath } from '../../utils/fsUtils.js';
 
 /**
  * findDir tool: Finds directories by name using regex.
@@ -13,10 +13,10 @@ import { getIgnorePatterns, shouldIgnore } from '../../utils/fsUtils.js';
 export default async function findDir({ pattern, dirPath = '.', recursive = true, limit = 15 }) {
   try {
     if (!pattern) return "Error: Search pattern cannot be empty.";
-    
+
     // Enforce max limit of 15
     const finalLimit = Math.min(limit, 15);
-    
+
     let regex;
     try {
       regex = new RegExp(pattern, 'i');
@@ -24,10 +24,17 @@ export default async function findDir({ pattern, dirPath = '.', recursive = true
       return `Error: Invalid regex pattern '${pattern}': ${e.message}`;
     }
 
-    const ignoreList = await getIgnorePatterns();
+    let resolvedPath;
+    try {
+      resolvedPath = safePath(dirPath);
+    } catch (err) {
+      return `Error: ${err.message}`;
+    }
+
+    const rootIgnoreList = await getIgnorePatterns();
     const results = [];
 
-    async function walk(currentPath) {
+    async function walk(currentPath, ignoreList) {
       if (results.length >= finalLimit) return;
 
       let items;
@@ -39,23 +46,24 @@ export default async function findDir({ pattern, dirPath = '.', recursive = true
 
       for (const item of items) {
         if (results.length >= finalLimit) break;
-        if (shouldIgnore(item.name, ignoreList)) continue;
+        if (!isSafeEntry(item, currentPath, ignoreList)) continue;
 
         const fullPath = path.join(currentPath, item.name);
-        
+
         if (item.isDirectory()) {
           if (regex.test(item.name)) {
             results.push(path.relative(process.cwd(), fullPath));
           }
-          
+
           if (recursive) {
-            await walk(fullPath);
+            const childIgnores = await loadNestedIgnores(fullPath, ignoreList);
+            await walk(fullPath, childIgnores);
           }
         }
       }
     }
 
-    await walk(dirPath);
+    await walk(resolvedPath, rootIgnoreList);
 
     if (results.length === 0) {
       return `No directories found matching "${pattern}" in "${dirPath}".`;

package/src/engine/tools/findFile.js

@@ -1,6 +1,6 @@
 import fs from 'fs/promises';
 import path from 'path';
-import { getIgnorePatterns, shouldIgnore } from '../../utils/fsUtils.js';
+import { getIgnorePatterns, isSafeEntry, loadNestedIgnores, safePath } from '../../utils/fsUtils.js';
 
 /**
  * findFile tool: Finds files by name using regex.
@@ -13,10 +13,10 @@ import { getIgnorePatterns, shouldIgnore } from '../../utils/fsUtils.js';
 export default async function findFile({ pattern, dirPath = '.', recursive = true, limit = 15 }) {
   try {
     if (!pattern) return "Error: Search pattern cannot be empty.";
-    
+
     // Enforce max limit of 15
     const finalLimit = Math.min(limit, 15);
-    
+
     let regex;
     try {
       regex = new RegExp(pattern, 'i');
@@ -24,11 +24,17 @@ export default async function findFile({ pattern, dirPath = '.', recursive = tru
       return `Error: Invalid regex pattern '${pattern}': ${e.message}`;
     }
 
-    const ignoreList = await getIgnorePatterns();
+    let resolvedPath;
+    try {
+      resolvedPath = safePath(dirPath);
+    } catch (err) {
+      return `Error: ${err.message}`;
+    }
+
+    const rootIgnoreList = await getIgnorePatterns();
     const results = [];
-    let totalFound = 0;
 
-    async function walk(currentPath) {
+    async function walk(currentPath, ignoreList) {
       if (results.length >= finalLimit) return;
 
       let items;
@@ -40,13 +46,14 @@ export default async function findFile({ pattern, dirPath = '.', recursive = tru
 
       for (const item of items) {
         if (results.length >= finalLimit) break;
-        if (shouldIgnore(item.name, ignoreList)) continue;
+        if (!isSafeEntry(item, currentPath, ignoreList)) continue;
 
         const fullPath = path.join(currentPath, item.name);
-        
+
         if (item.isDirectory()) {
           if (recursive) {
-            await walk(fullPath);
+            const childIgnores = await loadNestedIgnores(fullPath, ignoreList);
+            await walk(fullPath, childIgnores);
           }
         } else if (item.isFile()) {
           if (regex.test(item.name)) {
@@ -56,7 +63,7 @@ export default async function findFile({ pattern, dirPath = '.', recursive = tru
       }
     }
 
-    await walk(dirPath);
+    await walk(resolvedPath, rootIgnoreList);
 
     if (results.length === 0) {
       return `No files found matching "${pattern}" in "${dirPath}".`;

package/src/engine/tools/index.js

@@ -4,6 +4,7 @@ import projectTree from './projectTree.js';
 import readFileChunk from './readFileChunk.js';
 import searchText from './searchText.js';
 import webFetch from './webFetch.js';
+import webSearch from './webSearch.js';
 import listTools from './listTools.js';
 import findFile from './findFile.js';
 import findDir from './findDir.js';
@@ -73,13 +74,14 @@ export const toolDefinitions = [
     type: "function",
     function: {
       name: "searchText",
-      description: "Regex search in files/folders. Supports recursion and .gitignore.",
+      description: "Regex search in files/folders. Returns matching lines with surrounding context lines. Supports recursion and .gitignore.",
       parameters: {
         type: "object",
         properties: {
           pattern: { type: "string", description: "Regex or text pattern." },
           path: { type: "string", description: "File or directory to search." },
-          recursive: { type: "boolean", description: "Search subdirectories? (default: false)" }
+          recursive: { type: "boolean", description: "Search subdirectories? (default: false)" },
+          context: { type: "number", description: "Lines of context around each match (default: 2, max: 5)." }
         },
         required: ["pattern", "path"]
       }
@@ -99,6 +101,21 @@ export const toolDefinitions = [
       }
     }
   },
+  {
+    type: "function",
+    function: {
+      name: "webSearch",
+      description: "Search the web to find URLs, docs, and solutions. Returns a list of titles, URLs, and snippet summaries. Always use this first to find a URL before calling webFetch.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "The search term/query." },
+          limit: { type: "number", description: "Max results to return (default: 5, max: 20)." }
+        },
+        required: ["query"]
+      }
+    }
+  },
   {
     type: "function",
     function: {
@@ -182,6 +199,7 @@ const toolImplementations = {
   readFileChunk,
   searchText,
   webFetch,
+  webSearch,
   listTools,
   findFile,
   findDir,

package/src/engine/tools/listTools.js

@@ -30,9 +30,9 @@ export default async function listTools() {
     },
     {
       name: "searchText",
-      usage: "searchText({ pattern: 'TODO', path: 'src/', recursive: true })",
-      description: "Performs a regex search for text across files and directories. Respects .gitignore.",
-      whenToUse: "To find variable usages, search for specific strings, or locate technical debt across the codebase."
+      usage: "searchText({ pattern: 'safePath', path: 'src/', recursive: true, context: 3 })",
+      description: "Performs a regex search for text across files and directories. Returns each match with surrounding context lines (default: 2, max: 5). Overlapping context windows are merged. Respects .gitignore.",
+      whenToUse: "To find variable usages, trace function calls, or locate patterns across the codebase. Increase context when you need more surrounding code per match."
     },
     {
       name: "webFetch",
@@ -40,6 +40,12 @@ export default async function listTools() {
       description: "Fetches and extracts clean text from a web URL, removing HTML clutter.",
       whenToUse: "To gather information from online documentation, API references, or external technical articles."
     },
+    {
+      name: "webSearch",
+      usage: "webSearch({ query: 'nodejs fetch api example', limit: 5 })",
+      description: "Searches the web dynamically and returns a list of titles, direct URLs, and snippet summaries (default: 5, max: 20).",
+      whenToUse: "When you need to search the web for external documentation, solutions, or API references before using webFetch to read a specific page."
+    },
     {
       name: "findFile",
       usage: "findFile({ pattern: 'config.*\\\\.js$', dirPath: 'src/', limit: 10 })",
@@ -63,6 +69,12 @@ export default async function listTools() {
       usage: "askUser({ question: 'What is the API endpoint for this service?' })",
       description: "Asks the user a specific question via the terminal and waits for a text response.",
       whenToUse: "When you need specific information, clarification, or feedback from the user that cannot be found in the codebase."
+    },
+    {
+      name: "askConfirm",
+      usage: "askConfirm({ question: 'Should I proceed with deleting this file?' })",
+      description: "Asks the user a yes/no question using an interactive toggle. Returns { confirmed: true } for yes, { confirmed: false } for no, or { confirmed: false, dismissed: true } on cancellation.",
+      whenToUse: "When only a boolean decision is needed from the user. Prefer this over askUser for simple yes/no choices."
     }
   ];
 

package/src/engine/tools/projectTree.js

@@ -1,6 +1,6 @@
 import fs from 'fs/promises';
 import path from 'path';
-import { getIgnorePatterns, shouldIgnore } from '../../utils/fsUtils.js';
+import { getIgnorePatterns, isSafeEntry, loadNestedIgnores, safePath } from '../../utils/fsUtils.js';
 
 const MAX_DEPTH = 10;
 const MAX_ITEMS = 500;
@@ -15,17 +15,23 @@ export default async function projectTree({ dirPath }) {
   let itemCount = 0;
   let isTruncated = false;
 
+  let absolutePath;
+  try {
+    absolutePath = safePath(dirPath);
+  } catch (err) {
+    return `Error: ${err.message}`;
+  }
+
   try {
-    const absolutePath = path.resolve(dirPath);
     const stats = await fs.stat(absolutePath);
-    
+
     if (!stats.isDirectory()) {
       return `Error: '${dirPath}' is not a directory.`;
     }
 
-    const ignoreList = await getIgnorePatterns();
+    const rootIgnoreList = await getIgnorePatterns();
 
-    async function buildTree(currentDir, depth = 0, currentPrefix = '') {
+    async function buildTree(currentDir, depth = 0, currentPrefix = '', ignoreList = rootIgnoreList) {
       if (depth > MAX_DEPTH || itemCount >= MAX_ITEMS) {
         if (itemCount >= MAX_ITEMS) isTruncated = true;
         return '';
@@ -40,7 +46,7 @@ export default async function projectTree({ dirPath }) {
       }
 
       const filteredItems = items
-        .filter(item => !shouldIgnore(item.name, ignoreList))
+        .filter(item => isSafeEntry(item, currentDir, ignoreList))
         .sort((a, b) => {
           if (a.isDirectory() && !b.isDirectory()) return -1;
           if (!a.isDirectory() && b.isDirectory()) return 1;
@@ -64,7 +70,8 @@ export default async function projectTree({ dirPath }) {
 
         if (item.isDirectory()) {
           const fullPath = path.join(currentDir, item.name);
-          result += await buildTree(fullPath, depth + 1, currentPrefix + childPrefix);
+          const childIgnores = await loadNestedIgnores(fullPath, ignoreList);
+          result += await buildTree(fullPath, depth + 1, currentPrefix + childPrefix, childIgnores);
         }
       }
       return result;
@@ -72,7 +79,7 @@ export default async function projectTree({ dirPath }) {
 
     const rootName = path.basename(absolutePath) || absolutePath;
     const tree = await buildTree(absolutePath);
-    
+
     let finalOutput = `${rootName}/\n${tree || '└(empty)'}`;
     finalOutput = finalOutput.trimEnd();
 

package/src/engine/tools/readDir.js

@@ -1,5 +1,5 @@
 import fs from 'fs/promises';
-import { getIgnorePatterns, shouldIgnore } from '../../utils/fsUtils.js';
+import { getIgnorePatterns, isSafeEntry, safePath } from '../../utils/fsUtils.js';
 
 /**
  * Implementation of the readDir tool.
@@ -8,12 +8,19 @@ import { getIgnorePatterns, shouldIgnore } from '../../utils/fsUtils.js';
  * @returns {Promise<string>} List of files and folders or error message.
  */
 export default async function readDir({ dirPath }) {
+  let resolvedPath;
+  try {
+    resolvedPath = safePath(dirPath);
+  } catch (err) {
+    return `Error: ${err.message}`;
+  }
+
   try {
     const ignoreList = await getIgnorePatterns();
-    const items = await fs.readdir(dirPath, { withFileTypes: true });
-    
+    const items = await fs.readdir(resolvedPath, { withFileTypes: true });
+
     const formattedItems = items
-      .filter(item => !shouldIgnore(item.name, ignoreList))
+      .filter(item => isSafeEntry(item, resolvedPath, ignoreList))
       .map(item => {
         const type = item.isDirectory() ? '[D]' : '[F]';
         return `${type}${item.name}`;

package/src/engine/tools/readFile.js

@@ -1,5 +1,6 @@
 import fs from 'fs/promises';
 import { Buffer } from 'buffer';
+import { safePath } from '../../utils/fsUtils.js';
 
 const MAX_FILE_SIZE = 1024 * 1024; // 1MB limit
 
@@ -10,9 +11,16 @@ const MAX_FILE_SIZE = 1024 * 1024; // 1MB limit
  * @returns {Promise<string>} File content or error message.
  */
 export default async function readFile({ filePath }) {
+  let resolvedPath;
   try {
-    const stats = await fs.stat(filePath);
-    
+    resolvedPath = safePath(filePath);
+  } catch (err) {
+    return `Error: ${err.message}`;
+  }
+
+  try {
+    const stats = await fs.stat(resolvedPath);
+
     if (!stats.isFile()) {
       return `Error: '${filePath}' is not a file.`;
     }
@@ -22,17 +30,17 @@ export default async function readFile({ filePath }) {
     }
 
     // Binary check: read first 1KB and look for null bytes
-    const handle = await fs.open(filePath, 'r');
+    const handle = await fs.open(resolvedPath, 'r');
     const { bytesRead, buffer } = await handle.read(Buffer.alloc(1024), 0, 1024, 0);
     await handle.close();
-    
+
     for (let i = 0; i < bytesRead; i++) {
       if (buffer[i] === 0) {
         return `Error: '${filePath}' appears to be a binary file. Reading binary files is not supported.`;
       }
     }
 
-    const content = await fs.readFile(filePath, 'utf8');
+    const content = await fs.readFile(resolvedPath, 'utf8');
     return content;
   } catch (err) {
     if (err.code === 'ENOENT') return `Error: File not found at '${filePath}'.`;

package/src/engine/tools/readFileChunk.js

@@ -1,5 +1,6 @@
 import fs from 'fs/promises';
 import { Buffer } from 'buffer';
+import { safePath } from '../../utils/fsUtils.js';
 
 /**
  * Implementation of the readFileChunk tool.
@@ -10,22 +11,29 @@ import { Buffer } from 'buffer';
  * @returns {Promise<string>} File chunk or error message.
  */
 export default async function readFileChunk({ filePath, startLine, endLine }) {
+  let resolvedPath;
   try {
-    const stats = await fs.stat(filePath);
+    resolvedPath = safePath(filePath);
+  } catch (err) {
+    return `Error: ${err.message}`;
+  }
+
+  try {
+    const stats = await fs.stat(resolvedPath);
     if (!stats.isFile()) return `Error: '${filePath}' is not a file.`;
 
     // Binary check: read first 1KB and look for null bytes
-    const handle = await fs.open(filePath, 'r');
+    const handle = await fs.open(resolvedPath, 'r');
     const { bytesRead, buffer } = await handle.read(Buffer.alloc(1024), 0, 1024, 0);
     await handle.close();
-    
+
     for (let i = 0; i < bytesRead; i++) {
       if (buffer[i] === 0) return `Error: '${filePath}' appears to be a binary file. Reading binary files is not supported.`;
     }
 
-    const data = await fs.readFile(filePath, 'utf8');
+    const data = await fs.readFile(resolvedPath, 'utf8');
     const lines = data.split('\n');
-    
+
     // Boundary validation
     const totalLines = lines.length;
     const actualStart = Math.max(1, startLine);

package/src/engine/tools/searchText.js

@@ -1,21 +1,29 @@
 import fs from 'fs/promises';
 import path from 'path';
 import { Buffer } from 'buffer';
-import { getIgnorePatterns, shouldIgnore } from '../../utils/fsUtils.js';
+import { getIgnorePatterns, isSafeEntry, loadNestedIgnores, safePath } from '../../utils/fsUtils.js';
 
 const MAX_MATCHES_PER_FILE = 20;
 const MAX_TOTAL_MATCHES = 100;
 const MAX_DEPTH = 10;
+const CONTEXT_LINES = 2;
 
 /**
  * Enhanced searchText tool with recursion, ignore rules, and safety limits.
  */
-export default async function searchText({ pattern, path: searchPath, recursive = false }) {
+export default async function searchText({ pattern, path: searchPath, recursive = false, context = CONTEXT_LINES }) {
   let totalMatches = 0;
   let isTruncated = false;
 
+  let resolvedPath;
   try {
-    const stats = await fs.stat(searchPath);
+    resolvedPath = safePath(searchPath);
+  } catch (err) {
+    return `Error: ${err.message}`;
+  }
+
+  try {
+    const stats = await fs.stat(resolvedPath);
     if (!pattern) return "Error: Search pattern cannot be empty.";
 
     let regex;
@@ -25,15 +33,15 @@ export default async function searchText({ pattern, path: searchPath, recursive
       return `Error: Invalid regex pattern '${pattern}': ${e.message}`;
     }
 
-    const ignoreList = await getIgnorePatterns();
+    const rootIgnoreList = await getIgnorePatterns();
     const results = [];
 
-    const walk = async (currentPath, depth = 0) => {
+    const walk = async (currentPath, depth = 0, ignoreList = rootIgnoreList) => {
       if (totalMatches >= MAX_TOTAL_MATCHES) {
         isTruncated = true;
         return;
       }
-      
+
       if (depth > MAX_DEPTH) return;
 
       let items;
@@ -49,21 +57,23 @@ export default async function searchText({ pattern, path: searchPath, recursive
           break;
         }
 
-        if (shouldIgnore(item.name, ignoreList)) continue;
+        if (!isSafeEntry(item, currentPath, ignoreList)) continue;
 
         const fullPath = path.join(currentPath, item.name);
 
         if (item.isDirectory()) {
           if (recursive || depth === 0) {
-            await walk(fullPath, depth + 1);
+            const childIgnores = await loadNestedIgnores(fullPath, ignoreList);
+            await walk(fullPath, depth + 1, childIgnores);
           }
         } else if (item.isFile()) {
-          const fileMatches = await searchInFile(fullPath, regex);
+          const allowed = MAX_TOTAL_MATCHES - totalMatches;
+          const fileMatches = await searchInFile(fullPath, regex, context);
           if (fileMatches.length > 0) {
-            const allowedInFile = Math.min(fileMatches.length, MAX_TOTAL_MATCHES - totalMatches);
+            const allowedInFile = Math.min(fileMatches.length, allowed);
             results.push({
               file: path.relative(process.cwd(), fullPath),
-              matches: fileMatches.slice(0, allowedInFile)
+              blocks: fileMatches.slice(0, allowedInFile)
             });
             totalMatches += allowedInFile;
             if (fileMatches.length > allowedInFile) isTruncated = true;
@@ -73,24 +83,24 @@ export default async function searchText({ pattern, path: searchPath, recursive
     };
 
     if (stats.isFile()) {
-      const fileMatches = await searchInFile(searchPath, regex);
+      const fileMatches = await searchInFile(resolvedPath, regex, context);
       if (fileMatches.length > 0) {
         const allowed = Math.min(fileMatches.length, MAX_TOTAL_MATCHES);
         results.push({
-          file: path.relative(process.cwd(), searchPath),
-          matches: fileMatches.slice(0, allowed)
+          file: path.relative(process.cwd(), resolvedPath),
+          blocks: fileMatches.slice(0, allowed)
         });
         totalMatches = allowed;
         if (fileMatches.length > allowed) isTruncated = true;
       }
     } else {
-      await walk(searchPath);
+      await walk(resolvedPath);
     }
 
     if (results.length === 0) return "No matches found.";
 
     let output = results.map(res => {
-      return `[${res.file}]\n${res.matches.join('\n')}`;
+      return `[${res.file}]\n${res.blocks.join('\n---\n')}`;
     }).join('\n');
 
     if (isTruncated) {
@@ -99,35 +109,72 @@ export default async function searchText({ pattern, path: searchPath, recursive
 
     return output;
 
-
   } catch (err) {
     if (err.code === 'ENOENT') return `Error: Path not found at '${searchPath}'.`;
     return `Error searching text: ${err.message}`;
   }
 }
 
-async function searchInFile(filePath, regex) {
+async function searchInFile(filePath, regex, contextLines = CONTEXT_LINES) {
+  const CTX = Math.min(Math.max(0, contextLines), 5);
+
   try {
+    // Binary check — read first 1KB
     const handle = await fs.open(filePath, 'r');
     const { bytesRead, buffer } = await handle.read(Buffer.alloc(1024), 0, 1024, 0);
     await handle.close();
-    
+
     for (let i = 0; i < bytesRead; i++) {
       if (buffer[i] === 0) return []; // Skip binary
     }
 
     const content = await fs.readFile(filePath, 'utf8');
     const lines = content.split('\n');
-    const matches = [];
-    
+
+    // Collect all matching line indices (0-based)
+    const matchIndices = [];
     for (let i = 0; i < lines.length; i++) {
       if (regex.test(lines[i])) {
-        matches.push(`${i + 1}:${lines[i].trim()}`);
-        if (matches.length >= MAX_MATCHES_PER_FILE) break;
+        matchIndices.push(i);
+        if (matchIndices.length >= MAX_MATCHES_PER_FILE * 3) break; // Internal safety cap
+      }
+    }
+
+    if (matchIndices.length === 0) return [];
+
+    // Build context windows, merging overlapping ones
+    const blocks = [];
+    let currentBlock = null;
+
+    for (const idx of matchIndices) {
+      const start = Math.max(0, idx - CTX);
+      const end = Math.min(lines.length - 1, idx + CTX);
+
+      if (currentBlock && start <= currentBlock.end + 1) {
+        // Overlapping or adjacent — merge into current block
+        currentBlock.end = Math.max(currentBlock.end, end);
+        currentBlock.matchIndices.add(idx);
+      } else {
+        if (currentBlock) blocks.push(formatBlock(lines, currentBlock));
+        if (blocks.length >= MAX_MATCHES_PER_FILE) break;
+        currentBlock = { start, end, matchIndices: new Set([idx]) };
       }
     }
-    return matches;
+    if (currentBlock && blocks.length < MAX_MATCHES_PER_FILE) {
+      blocks.push(formatBlock(lines, currentBlock));
+    }
+
+    return blocks;
   } catch (err) {
     return [];
   }
 }
+
+function formatBlock(lines, block) {
+  let output = "";
+  for (let i = block.start; i <= block.end; i++) {
+    const prefix = block.matchIndices.has(i) ? "► " : "  ";
+    output += `${i + 1}:${prefix}${lines[i]}\n`;
+  }
+  return output.trim();
+}

package/src/engine/tools/webSearch.js

@@ -0,0 +1,78 @@
+const TIMEOUT_MS = 10000;
+const MAX_RESULTS_HARD_LIMIT = 20;
+
+/**
+ * Searches the web using DuckDuckGo HTML (zero dependencies).
+ * Extracts title, clean URL, and snippet summary.
+ * 
+ * @param {Object} args
+ * @param {string} args.query - The search query.
+ * @param {number} [args.limit=5] - Max results to return (max 20).
+ * @returns {Promise<string>} JSON string of search results or error message.
+ */
+export default async function webSearch({ query, limit = 5 }) {
+  if (!query) return "Error: Search query cannot be empty.";
+
+  const maxLimit = Math.min(Math.max(1, limit), MAX_RESULTS_HARD_LIMIT);
+
+  try {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), TIMEOUT_MS);
+
+    const response = await fetch('https://html.duckduckgo.com/html/', {
+      method: 'POST',
+      signal: controller.signal,
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
+      },
+      body: `q=${encodeURIComponent(query)}`
+    });
+
+    clearTimeout(timeoutId);
+
+    if (!response.ok) {
+      throw new Error(`HTTP error! status: ${response.status}`);
+    }
+
+    const html = await response.text();
+    const results = [];
+    
+    // Split HTML into result blocks. 
+    // The slice(1) skips the header block before the first result.
+    const blocks = html.split('class="links_main links_deep result__body"').slice(1);
+    
+    for (const block of blocks) {
+      if (results.length >= maxLimit) break;
+      
+      const titleMatch = block.match(/<h2 class="result__title">[\s\S]*?<a[^>]*>([\s\S]*?)<\/a>/i);
+      const snippetMatch = block.match(/<a class="result__snippet[^>]*href="([^"]+)"[^>]*>([\s\S]*?)<\/a>/i);
+      
+      if (titleMatch && snippetMatch) {
+        // Strip nested HTML tags (like <b> tags for highlighted keywords)
+        const title = titleMatch[1].replace(/<[^>]+>/g, '').trim();
+        const snippet = snippetMatch[2].replace(/<[^>]+>/g, '').trim();
+        
+        // Clean DuckDuckGo's tracking wrapper from the URL
+        let url = snippetMatch[1];
+        if (url.startsWith('//duckduckgo.com/l/?uddg=')) {
+          url = decodeURIComponent(url.split('uddg=')[1].split('&')[0]);
+        }
+        
+        results.push({ title, url, snippet });
+      }
+    }
+
+    if (results.length === 0) {
+      return "No results found.";
+    }
+
+    return JSON.stringify(results, null, 2);
+
+  } catch (err) {
+    if (err.name === 'AbortError') {
+      return `Error: Request timed out after ${TIMEOUT_MS}ms`;
+    }
+    return `Error searching web: ${err.message}`;
+  }
+}