skyloom 1.17.0 → 1.18.1

package/src/core/logger.ts

@@ -6,6 +6,10 @@
  *   log.info("chat_request", { userMessage: "hello", agent: "fog" });
  */
 
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
 export enum LogLevel {
   DEBUG = 0,
   INFO = 1,
@@ -13,6 +17,39 @@ export enum LogLevel {
   ERROR = 3,
 }
 
+/**
+ * Where log lines go. Defaults to stderr. In a full-screen TUI, stderr writes
+ * paint over the rendered frame (the "乱码" garbling), so the interactive UIs
+ * redirect logs to a file via setLogFile() instead.
+ */
+export type LogSink = (line: string) => void;
+let logSink: LogSink = (line) => { try { process.stderr.write(line); } catch { /* ignore */ } };
+
+/** Send all logs to `fn` instead of stderr. */
+export function setLogSink(fn: LogSink): void { logSink = fn; }
+
+/** Drop all log output (e.g. piped/headless contexts that want a clean stream). */
+export function silenceLogs(): void { logSink = () => { /* discard */ }; }
+
+/**
+ * Route logs to a file (appended), keeping them off the terminal so they can't
+ * corrupt an interactive TUI. Falls back to silencing if the file can't open.
+ */
+export function setLogFile(filePath?: string): string | null {
+  const target = filePath
+    ? (filePath.startsWith("~") ? path.join(os.homedir(), filePath.slice(1)) : filePath)
+    : path.join(os.homedir(), ".skyloom", "skyloom.log");
+  try {
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    const fd = fs.openSync(target, "a");
+    logSink = (line) => { try { fs.writeSync(fd, line); } catch { /* ignore */ } };
+    return target;
+  } catch {
+    silenceLogs();
+    return null;
+  }
+}
+
 export interface LogEntry {
   ts: string;
   level: string;
@@ -69,8 +106,9 @@ export class Logger {
       return value;
     });
 
-    // Write all logs to stderr to keep stdout clean for chat/TUI
-    process.stderr.write(line + "\n");
+    // Route through the configured sink (stderr by default; a file in TUI mode
+    // so log lines never paint over the rendered frame).
+    logSink(line + "\n");
   }
 
   debug(msg: string, extra?: Record<string, unknown>) {

package/src/core/patch.ts

@@ -0,0 +1,176 @@
+/**
+ * apply_patch — atomic, multi-file edits for larger refactors.
+ *
+ * Uses exact search/replace blocks (not line-number/context hunks), so it can't
+ * misapply against a drifted file: every SEARCH must match the current file
+ * content exactly and uniquely. The whole patch is validated first; disk is
+ * only touched once every operation is known to apply — so a bad block aborts
+ * the patch without leaving a half-applied tree.
+ *
+ * Format:
+ *   *** Update File: path
+ *   <<<<<<< SEARCH
+ *   exact old text
+ *   =======
+ *   new text
+ *   >>>>>>> REPLACE
+ *   (one or more blocks per file)
+ *
+ *   *** Add File: path
+ *   full file content
+ *
+ *   *** Delete File: path
+ *
+ * An optional `*** Begin Patch` / `*** End Patch` envelope is tolerated.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { countOccurrences, unifiedDiff } from './diff';
+
+export interface PatchBlock { search: string; replace: string; }
+export type PatchOp =
+  | { op: 'update'; path: string; blocks: PatchBlock[] }
+  | { op: 'add'; path: string; content: string }
+  | { op: 'delete'; path: string };
+
+const HDR_UPDATE = /^\*\*\* Update File:\s*(.+?)\s*$/;
+const HDR_ADD = /^\*\*\* Add File:\s*(.+?)\s*$/;
+const HDR_DELETE = /^\*\*\* Delete File:\s*(.+?)\s*$/;
+const MARK_SEARCH = '<<<<<<< SEARCH';
+const MARK_SEP = '=======';
+const MARK_REPLACE = '>>>>>>> REPLACE';
+
+export function parsePatch(text: string): { ops: PatchOp[] } | { error: string } {
+  const lines = text.split(/\r?\n/);
+  const ops: PatchOp[] = [];
+  let i = 0;
+
+  const isHeader = (l: string) => l.startsWith('*** ');
+
+  while (i < lines.length) {
+    const line = lines[i];
+    if (line.startsWith('*** Begin Patch') || line.startsWith('*** End Patch')) { i++; continue; }
+    if (line.trim() === '') { i++; continue; }
+
+    let m: RegExpMatchArray | null;
+    if ((m = line.match(HDR_UPDATE))) {
+      const filePath = m[1];
+      i++;
+      const blocks: PatchBlock[] = [];
+      while (i < lines.length && !isHeader(lines[i])) {
+        if (lines[i].trim() === '') { i++; continue; }
+        if (lines[i] !== MARK_SEARCH) {
+          return { error: `Malformed Update block for '${filePath}': expected '${MARK_SEARCH}', got ${JSON.stringify(lines[i].slice(0, 40))}` };
+        }
+        i++;
+        const search: string[] = [];
+        while (i < lines.length && lines[i] !== MARK_SEP) search.push(lines[i++]);
+        if (i >= lines.length) return { error: `Unterminated SEARCH (missing '${MARK_SEP}') for '${filePath}'` };
+        i++; // consume separator
+        const replace: string[] = [];
+        while (i < lines.length && lines[i] !== MARK_REPLACE) replace.push(lines[i++]);
+        if (i >= lines.length) return { error: `Unterminated REPLACE (missing '${MARK_REPLACE}') for '${filePath}'` };
+        i++; // consume replace marker
+        blocks.push({ search: search.join('\n'), replace: replace.join('\n') });
+      }
+      if (blocks.length === 0) return { error: `Update File '${filePath}' has no SEARCH/REPLACE blocks` };
+      ops.push({ op: 'update', path: filePath, blocks });
+    } else if ((m = line.match(HDR_ADD))) {
+      const filePath = m[1];
+      i++;
+      const content: string[] = [];
+      while (i < lines.length && !isHeader(lines[i])) content.push(lines[i++]);
+      while (content.length && content[content.length - 1] === '') content.pop();
+      ops.push({ op: 'add', path: filePath, content: content.length ? content.join('\n') + '\n' : '' });
+    } else if ((m = line.match(HDR_DELETE))) {
+      ops.push({ op: 'delete', path: m[1] });
+      i++;
+    } else {
+      return { error: `Unexpected line outside any file section: ${JSON.stringify(line.slice(0, 60))}` };
+    }
+  }
+
+  if (ops.length === 0) return { error: 'Patch contains no operations.' };
+  return { ops };
+}
+
+export interface ApplyOptions {
+  cwd?: string;
+  /** Optional workspace-fence check; return a non-null string to abort. */
+  fenceCheck?: (abs: string) => string | null;
+  /** Optional pre-write snapshot hook (for /rewind). */
+  snapshot?: (abs: string) => void;
+}
+
+interface PlannedChange {
+  op: 'update' | 'add' | 'delete';
+  path: string;
+  abs: string;
+  oldContent?: string;
+  newContent?: string;
+}
+
+/**
+ * Validate every operation, then apply them all. Returns a human summary on
+ * success or an `Error: …` string on the first validation failure (no writes).
+ */
+export function applyPatch(text: string, opts: ApplyOptions = {}): string {
+  const cwd = opts.cwd || process.cwd();
+  const parsed = parsePatch(text);
+  if ('error' in parsed) return `Error: ${parsed.error}`;
+
+  const plan: PlannedChange[] = [];
+
+  // ── Validate everything first (no disk mutation) ──
+  for (const op of parsed.ops) {
+    const abs = path.resolve(cwd, op.path);
+    if (opts.fenceCheck) { const f = opts.fenceCheck(abs); if (f) return f; }
+
+    if (op.op === 'update') {
+      if (!fs.existsSync(abs)) return `Error: Update target not found: ${op.path}`;
+      let content: string;
+      try { content = fs.readFileSync(abs, 'utf8'); } catch (e) { return `Error: cannot read ${op.path}: ${e}`; }
+      const orig = content;
+      for (const block of op.blocks) {
+        if (block.search === block.replace) return `Error: a SEARCH/REPLACE block for ${op.path} is a no-op (identical).`;
+        const n = countOccurrences(content, block.search);
+        if (n === 0) return `Error: SEARCH block not found in ${op.path}: ${JSON.stringify(block.search.slice(0, 80))}`;
+        if (n > 1) return `Error: SEARCH block is ambiguous in ${op.path} (appears ${n} times) — add more context to make it unique.`;
+        content = content.replace(block.search, () => block.replace); // literal replacement
+      }
+      plan.push({ op: 'update', path: op.path, abs, oldContent: orig, newContent: content });
+    } else if (op.op === 'add') {
+      if (fs.existsSync(abs)) return `Error: Add target already exists: ${op.path} (use Update File to modify it)`;
+      plan.push({ op: 'add', path: op.path, abs, newContent: op.content });
+    } else {
+      if (!fs.existsSync(abs)) return `Error: Delete target not found: ${op.path}`;
+      plan.push({ op: 'delete', path: op.path, abs });
+    }
+  }
+
+  // ── Apply (validation passed for all ops) ──
+  const summary: string[] = [];
+  for (const p of plan) {
+    try {
+      if (p.op === 'update') {
+        opts.snapshot?.(p.abs);
+        fs.writeFileSync(p.abs, p.newContent!, 'utf8');
+        const d = unifiedDiff(p.oldContent!, p.newContent!, { context: 0 });
+        summary.push(`~ ${p.path} (+${d.stat.added} -${d.stat.removed})`);
+      } else if (p.op === 'add') {
+        fs.mkdirSync(path.dirname(p.abs), { recursive: true });
+        fs.writeFileSync(p.abs, p.newContent!, 'utf8');
+        summary.push(`+ ${p.path} (new)`);
+      } else {
+        opts.snapshot?.(p.abs);
+        fs.unlinkSync(p.abs);
+        summary.push(`- ${p.path} (deleted)`);
+      }
+    } catch (e) {
+      return `Error: patch validated but failed while writing ${p.path}: ${e}\nPartial summary:\n${summary.join('\n')}`;
+    }
+  }
+
+  return `Applied patch — ${plan.length} file${plan.length !== 1 ? 's' : ''}:\n${summary.join('\n')}`;
+}

package/src/core/protocol.ts

@@ -0,0 +1,36 @@
+/**
+ * Engineering protocol — the working discipline injected into every agent's
+ * system prompt so it operates like a senior engineer, not just a code typist.
+ *
+ * Kept as a pure function (no `this`) so it can be unit-tested and evolved in
+ * one place. It deliberately names the project's own capabilities
+ * (code_search / get_diagnostics / run_bash) so the model actually uses the
+ * read→edit→verify loop instead of guessing.
+ */
+
+export function engineeringProtocol(lang: string = 'zh'): string {
+  if (lang === 'en') {
+    return [
+      '## Engineering Standard (work like a senior engineer)',
+      '- Understand before changing: read the target code and its tests/callers (code_search → read_file) before editing. Match the surrounding style, naming, and existing patterns.',
+      '- Reuse first: prefer utilities/libraries already in the project over inventing new ones; check how similar things are done here.',
+      '- Root cause, not symptom: reproduce the failure, find why it happens, fix the cause — never paper over it or hardcode around a test.',
+      '- Minimal, surgical diffs: change only what the task needs. No drive-by reformatting or unrelated edits.',
+      '- Verify your work: after editing code, run get_diagnostics on the changed files and run the project tests/build (run_bash). Do not claim done until it is green; report the real result.',
+      '- Be honest about uncertainty: never fabricate APIs, file paths, or results. If unsure, say so and check.',
+      '- Security & performance: validate inputs, handle errors for real, avoid obvious injection / DoS / performance traps.',
+      'You may read and modify Skyloom\'s own source.',
+    ].join('\n');
+  }
+  return [
+    '## 工程标准(像资深工程师一样工作)',
+    '- 改之前先理解:动手前先读目标代码及其测试/调用方(code_search → read_file),沿用周围的风格、命名与既有模式。',
+    '- 优先复用:优先用项目里已有的工具/库,而不是另造轮子;先看相似功能此处怎么做。',
+    '- 治根因不治症状:先复现失败,定位根本原因再修;绝不糊弄,绝不为了通过测试而硬编码。',
+    '- 最小手术式改动:只改任务所需,不顺手重排格式、不夹带无关修改。',
+    '- 改完必验证:改代码后对改动文件跑 get_diagnostics,并跑项目测试/构建(run_bash);未变绿不算完成,如实汇报真实结果。',
+    '- 诚实面对不确定:绝不编造 API、文件路径或结果;不确定就说明并去核实。',
+    '- 安全与性能:校验输入、做真实的错误处理,避开明显的注入/DoS/性能陷阱。',
+    '你可以阅读和修改 Skyloom 自身源码。',
+  ].join('\n');
+}

package/src/core/search.ts

@@ -0,0 +1,138 @@
+/**
+ * Code search — a dependency-light, cross-platform engine for "find where X is
+ * used and read it in context". Backs the code_search tool and is the fallback
+ * for grep when ripgrep/grep aren't installed (common on Windows), so search
+ * never silently returns nothing just because a binary is missing.
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import { globSync } from 'glob';
+
+export interface SearchOptions {
+  pattern: string;
+  /** Root directory to search (default: cwd). */
+  root?: string;
+  /** Glob to restrict files (e.g. "**\/*.ts"). Default: all files. */
+  glob?: string;
+  /** Case-insensitive match (default false). */
+  ignoreCase?: boolean;
+  /** Treat pattern as a regular expression (default true). */
+  regex?: boolean;
+  /** Lines of context around each match (default 0). */
+  context?: number;
+  /** Cap on total matches returned (default 200). */
+  maxResults?: number;
+  /** Skip files larger than this many bytes (default 2 MiB). */
+  maxFileBytes?: number;
+}
+
+export interface SearchMatch {
+  file: string;     // relative to root
+  line: number;     // 1-based
+  text: string;
+  before?: string[];
+  after?: string[];
+}
+
+export interface SearchResult {
+  matches: SearchMatch[];
+  filesScanned: number;
+  truncated: boolean;
+  error?: string;
+}
+
+/** Directories never worth searching — vendored, generated, or VCS internals. */
+const DEFAULT_IGNORES = [
+  '**/node_modules/**', '**/.git/**', '**/dist/**', '**/build/**',
+  '**/coverage/**', '**/.next/**', '**/out/**', '**/.cache/**',
+  '**/vendor/**', '**/.venv/**', '**/__pycache__/**',
+];
+
+function looksBinary(buf: Buffer): boolean {
+  const n = Math.min(buf.length, 8000);
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true; // NUL byte ⇒ binary
+  return false;
+}
+
+/** Pure-JS recursive code search. No external process required. */
+export function searchCode(opts: SearchOptions): SearchResult {
+  const root = path.resolve(opts.root || process.cwd());
+  const maxResults = opts.maxResults ?? 200;
+  const maxFileBytes = opts.maxFileBytes ?? 2 * 1024 * 1024;
+  const context = Math.max(0, opts.context ?? 0);
+
+  let matcher: (line: string) => boolean;
+  if (opts.regex === false) {
+    const needle = opts.ignoreCase ? opts.pattern.toLowerCase() : opts.pattern;
+    matcher = (line) => (opts.ignoreCase ? line.toLowerCase() : line).includes(needle);
+  } else {
+    let re: RegExp;
+    try {
+      re = new RegExp(opts.pattern, opts.ignoreCase ? 'i' : '');
+    } catch (e) {
+      return { matches: [], filesScanned: 0, truncated: false, error: `invalid regex: ${e}` };
+    }
+    matcher = (line) => re.test(line);
+  }
+
+  let files: string[];
+  try {
+    files = globSync(opts.glob || '**/*', {
+      cwd: root, nodir: true, dot: false, ignore: DEFAULT_IGNORES,
+    });
+  } catch (e) {
+    return { matches: [], filesScanned: 0, truncated: false, error: `glob failed: ${e}` };
+  }
+
+  const matches: SearchMatch[] = [];
+  let filesScanned = 0;
+  let truncated = false;
+
+  for (const rel of files) {
+    if (matches.length >= maxResults) { truncated = true; break; }
+    const abs = path.join(root, rel);
+    let buf: Buffer;
+    try {
+      const stat = fs.statSync(abs);
+      if (stat.size > maxFileBytes) continue;
+      buf = fs.readFileSync(abs);
+    } catch { continue; }
+    if (looksBinary(buf)) continue;
+
+    filesScanned++;
+    const lines = buf.toString('utf8').split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      if (!matcher(lines[i])) continue;
+      const m: SearchMatch = { file: rel.split(path.sep).join('/'), line: i + 1, text: lines[i] };
+      if (context > 0) {
+        m.before = lines.slice(Math.max(0, i - context), i);
+        m.after = lines.slice(i + 1, i + 1 + context);
+      }
+      matches.push(m);
+      if (matches.length >= maxResults) { truncated = true; break; }
+    }
+  }
+
+  return { matches, filesScanned, truncated };
+}
+
+/** Render a SearchResult as ripgrep-style `file:line:text` (with context). */
+export function formatSearchResult(res: SearchResult): string {
+  if (res.error) return `Search error: ${res.error}`;
+  if (res.matches.length === 0) return 'No matches found.';
+  const out: string[] = [];
+  let lastFile = '';
+  for (const m of res.matches) {
+    if (m.file !== lastFile) { if (out.length) out.push(''); lastFile = m.file; }
+    for (let k = 0; k < (m.before?.length || 0); k++) {
+      out.push(`${m.file}:${m.line - (m.before!.length - k)}- ${m.before![k]}`);
+    }
+    out.push(`${m.file}:${m.line}: ${m.text}`);
+    for (let k = 0; k < (m.after?.length || 0); k++) {
+      out.push(`${m.file}:${m.line + k + 1}- ${m.after![k]}`);
+    }
+  }
+  if (res.truncated) out.push(`\n…[results truncated at ${res.matches.length} matches — narrow the pattern or glob]`);
+  return out.join('\n');
+}

package/src/core/security.ts

@@ -77,6 +77,7 @@ const TOOL_DANGER_MAP: Record<string, DangerLevel> = {
 
   write_file: DangerLevel.LOW,
   edit_file: DangerLevel.LOW,
+  apply_patch: DangerLevel.LOW,
   copy_file: DangerLevel.LOW,
   move_file: DangerLevel.LOW,
   make_directory: DangerLevel.LOW,
@@ -164,7 +165,7 @@ export const PERMISSION_MODE_ALIASES: Record<string, ApprovalMode> = {
 };
 
 /** Tools that mutate the filesystem — the ones acceptEdits waves through. */
-const EDIT_TOOL_RE = /^(write_|edit_|append_|replace_|create_|make_|copy_|move_|delete_)/;
+const EDIT_TOOL_RE = /^(write_|edit_|append_|replace_|create_|make_|copy_|move_|delete_)|^apply_patch$/;
 export function isEditTool(toolName: string): boolean { return EDIT_TOOL_RE.test(toolName); }
 
 /**

package/src/core/tool.ts

@@ -46,6 +46,14 @@ export interface ToolDefinition {
    */
   idempotent?: boolean;
   timeout?: number;
+  /**
+   * Optional output guard: inspect the handler's result and return an error
+   * message if it's not valid (else null/undefined). A non-null return makes
+   * the call fail — routed through the same retry + circuit-breaker path as a
+   * thrown error — so a tool/plugin can reject malformed output instead of
+   * passing garbage back to the model as "success".
+   */
+  validateOutput?: (result: string, params: Record<string, unknown>) => string | null | undefined;
 }
 
 /** Order-stable JSON key so {a,b} and {b,a} hash to the same cache/dedup key. */
@@ -430,6 +438,13 @@ export class ToolRegistry extends EventEmitter {
           if (timer) clearTimeout(timer);
         }
 
+        // Output guard: a non-null message means the result is invalid. Throw so
+        // it flows through the same retry + breaker path as any other failure.
+        if (tool.validateOutput) {
+          const outErr = tool.validateOutput(result, params);
+          if (outErr) throw new Error(`invalid tool output: ${outErr}`);
+        }
+
         const duration = Date.now() - startTime;
 
         // Cache result

package/src/tools/builtin.ts

@@ -12,6 +12,8 @@ import { isPrivateIp, assertFetchAllowed, fenceRoot, fenceCheck } from './guards
 import { webSearch, formatSearchResults, readPage } from './websearch';
 import { countOccurrences, unifiedDiff } from '../core/diff';
 import { getDiagnostics, formatDiagnostics } from '../core/diagnostics';
+import { searchCode, formatSearchResult } from '../core/search';
+import { applyPatch } from '../core/patch';
 
 // Re-exported so existing importers/tests keep resolving these from builtin.
 export { isPrivateIp, assertFetchAllowed, fenceRoot, fenceCheck };
@@ -142,6 +144,30 @@ export function registerBuiltinTools(registry: ToolRegistry): void {
     },
   });
 
+  registry.register({
+    name: 'apply_patch',
+    description: 'Apply an atomic, multi-file edit in one call — ideal for larger refactors touching several places/files. The whole patch is validated before anything is written, so a bad block aborts cleanly with no half-applied changes. Each SEARCH must match the file exactly and uniquely. Format:\n*** Update File: path\n<<<<<<< SEARCH\nold exact text\n=======\nnew text\n>>>>>>> REPLACE\n(repeat blocks; also *** Add File: path / full content, and *** Delete File: path)',
+    parameters: [
+      { name: 'patch', type: 'string', description: 'The patch text in the *** Update/Add/Delete File + SEARCH/REPLACE format', required: true },
+    ],
+    handler: async (params) => {
+      let snapshot: ((abs: string) => void) | undefined;
+      try {
+        const { getFileCheckpoints } = require('../core/file_checkpoint');
+        const cp = getFileCheckpoints();
+        snapshot = (abs: string) => { try { cp.snapshot(abs); } catch { /* best-effort */ } };
+      } catch { /* checkpointing optional */ }
+      try {
+        return applyPatch(String(params.patch || ''), {
+          fenceCheck: (abs: string) => fenceCheck(abs),
+          snapshot,
+        });
+      } catch (e) {
+        return `Error applying patch: ${e}`;
+      }
+    },
+  });
+
   registry.register({
     name: 'delete_file',
     description: 'Delete a file at the given path.',
@@ -334,6 +360,9 @@ export function registerBuiltinTools(registry: ToolRegistry): void {
       { name: 'engine', type: 'string', description: 'Optional provider: tavily|brave|serper|searxng|jina|duckduckgo|bing|baidu|sogou. Default: auto (uses a configured API key if present, else the keyless Jina endpoint, else scraping).', required: false },
       { name: 'max_results', type: 'number', description: 'Max results to return (default 8, capped at 20)', required: false },
     ],
+    // Larger than webSearch's internal budget (~22s) so the waterfall returns a
+    // clear "no results" message rather than being cut off as a generic timeout.
+    timeout: 45000,
     handler: async (params) => {
       const query = String(params.query || '').trim();
       if (!query) return 'Error: query is required';
@@ -470,10 +499,39 @@ export function registerBuiltinTools(registry: ToolRegistry): void {
 
   // ── Utility Tools ──
 
+  registry.register({
+    name: 'code_search',
+    idempotent: true,
+    description: 'Search source code for a regex pattern across files. Returns file:line matches with optional surrounding context. Use this to find where a symbol/string is defined or used. Restrict scope with glob (e.g. "**/*.ts") and add context lines to read around hits.',
+    parameters: [
+      { name: 'pattern', type: 'string', description: 'Regex (or literal if regex=false) to search for', required: true },
+      { name: 'path', type: 'string', description: 'Root directory to search (default: cwd)', required: false },
+      { name: 'glob', type: 'string', description: 'Restrict to files matching this glob, e.g. "**/*.ts"', required: false },
+      { name: 'context', type: 'number', description: 'Lines of context around each match (default 0)', required: false },
+      { name: 'ignore_case', type: 'boolean', description: 'Case-insensitive match (default false)', required: false },
+      { name: 'regex', type: 'boolean', description: 'Treat pattern as regex (default true; false = literal substring)', required: false },
+      { name: 'max_results', type: 'number', description: 'Max matches to return (default 200)', required: false },
+    ],
+    handler: async (params) => {
+      const root = params.path ? path.resolve(params.path as string) : process.cwd();
+      const fenced = fenceCheck(root); if (fenced) return fenced;
+      const res = searchCode({
+        pattern: String(params.pattern || ''),
+        root,
+        glob: params.glob ? String(params.glob) : undefined,
+        context: params.context != null ? Number(params.context) : 0,
+        ignoreCase: params.ignore_case === true,
+        regex: params.regex !== false,
+        maxResults: params.max_results != null ? Number(params.max_results) : 200,
+      });
+      return formatSearchResult(res);
+    },
+  });
+
   registry.register({
     name: 'grep',
     idempotent: true,
-    description: 'Search for a pattern in files using ripgrep or grep.',
+    description: 'Search for a regex pattern in files using ripgrep/grep, with a built-in fallback when neither is installed. For richer control (glob, context, ignore-case) prefer code_search.',
     parameters: [
       { name: 'pattern', type: 'string', description: 'Regex pattern to search for', required: true },
       { name: 'path', type: 'string', description: 'Directory to search in', required: false },
@@ -496,12 +554,13 @@ export function registerBuiltinTools(registry: ToolRegistry): void {
           const out = execFileSync(bin, args, { encoding: 'utf-8', maxBuffer: 1024 * 1024 });
           return out || 'No matches found.';
         } catch (e: any) {
-          // exit status 1 = ran successfully, zero matches; anything else
-          // (e.g. binary not installed) falls through to the next variant.
+          // exit status 1 = ran successfully, zero matches. Any other failure
+          // (e.g. binary not installed) falls through to the next variant, then
+          // to the pure-JS engine so search works even with no rg/grep.
           if (e?.status === 1) return 'No matches found.';
         }
       }
-      return 'No matches found.';
+      return formatSearchResult(searchCode({ pattern: pat, root: searchDir, maxResults: 200 }));
     },
   });
 

package/src/tools/websearch.ts

@@ -44,7 +44,9 @@ export interface WebHttp {
 }
 
 const UA = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36';
-const DEFAULT_TIMEOUT = 15000;
+// Per-request timeout. Kept short so a dead/slow provider fails fast and the
+// waterfall moves on quickly rather than burning 15s each across five providers.
+const DEFAULT_TIMEOUT = 8000;
 
 /** Default HTTP client backed by axios. */
 export const defaultHttp: WebHttp = {
@@ -294,40 +296,54 @@ export interface WebSearchOptions {
   env?: EnvMap;              // defaults to process.env
   http?: WebHttp;           // defaults to axios-backed client
   onProviderError?: (provider: string, error: string) => void;
+  /** Total wall-clock budget for the waterfall; stop trying once exceeded. */
+  budgetMs?: number;
 }
 
 /**
  * Run a web search through the provider waterfall. Returns the first provider
  * that yields results, or a response with an empty result set + the list of
- * providers that were tried.
+ * providers that were tried. A total time budget caps the waterfall so the tool
+ * returns a clear "no results" message instead of being killed by an outer
+ * timeout (which would surface as an opaque "Tool execution timeout").
  */
-export async function webSearch(query: string, opts: WebSearchOptions = {}): Promise<SearchResponse & { tried: string[] }> {
+export async function webSearch(query: string, opts: WebSearchOptions = {}): Promise<SearchResponse & { tried: string[]; errors?: number }> {
   const q = (query || '').trim();
   if (!q) throw new Error('query is required');
   const max = Math.max(1, Math.min(20, Math.floor(opts.max ?? 8)));
   const env = opts.env ?? (process.env as EnvMap);
   const http = opts.http ?? defaultHttp;
   const pinned = (opts.engine || env.SKYLOOM_SEARCH_ENGINE || '').trim();
+  const budgetMs = opts.budgetMs ?? 22000;
+  const start = Date.now();
 
   const providers = resolveProviders(env, pinned);
   const tried: string[] = [];
+  let errors = 0;
   for (const provider of providers) {
+    // Out of time: stop the waterfall and return what we have (a clear empty
+    // result), rather than letting a slow tail provider blow the tool timeout.
+    if (tried.length > 0 && Date.now() - start > budgetMs) break;
     tried.push(provider.id);
     try {
       const res = await provider.run(http, env, q, max);
       if (res.results.length > 0 || res.answer) return { ...res, tried };
     } catch (e: any) {
+      errors++;
       opts.onProviderError?.(provider.id, String(e?.message || e));
     }
   }
-  return { provider: 'none', results: [], tried };
+  return { provider: 'none', results: [], tried, errors };
 }
 
 /** Format a SearchResponse as compact text for an LLM tool result. */
-export function formatSearchResults(res: SearchResponse & { tried?: string[] }): string {
+export function formatSearchResults(res: SearchResponse & { tried?: string[]; errors?: number }): string {
   if (!res.results.length && !res.answer) {
     const tried = res.tried?.length ? ` (tried: ${res.tried.join(', ')})` : '';
-    return `No search results found${tried}. Try a simpler query, or set a search API key (TAVILY_API_KEY / BRAVE_API_KEY / SERPER_API_KEY) for more reliable results.`;
+    const note = res.errors && res.errors > 0
+      ? ' Every provider errored or timed out — likely no/blocked network connectivity or rate limiting in this environment.'
+      : '';
+    return `No search results found${tried}.${note} Try a simpler query, or set a search API key (TAVILY_API_KEY / BRAVE_API_KEY / SERPER_API_KEY) for more reliable results.`;
   }
   const parts: string[] = [];
   if (res.answer) parts.push(`Answer: ${res.answer}\n`);