codemini-cli 0.1.12 → 0.1.13

package/src/core/tools.js

@@ -4,6 +4,49 @@ import crypto from 'node:crypto';
 import { isDangerousCommand, runShellCommand } from './shell.js';
 import { evaluateCommandPolicy } from './command-policy.js';
 
+const SKIP_DIRS = new Set(['.git', 'node_modules', '.coder', '.codemini-cli', 'dist', 'coverage']);
+const TEXT_EXTENSIONS = new Set([
+  '.js',
+  '.jsx',
+  '.ts',
+  '.tsx',
+  '.json',
+  '.md',
+  '.mjs',
+  '.cjs',
+  '.py',
+  '.rb',
+  '.go',
+  '.rs',
+  '.java',
+  '.cs',
+  '.css',
+  '.scss',
+  '.html',
+  '.yml',
+  '.yaml',
+  '.sh',
+  '.ps1'
+]);
+const LANGUAGE_FILE_TYPES = {
+  js: ['js', 'jsx', 'mjs', 'cjs'],
+  ts: ['ts', 'tsx'],
+  py: ['py'],
+  python: ['py'],
+  md: ['md'],
+  json: ['json'],
+  css: ['css', 'scss'],
+  html: ['html'],
+  java: ['java'],
+  csharp: ['cs'],
+  cs: ['cs'],
+  go: ['go'],
+  rust: ['rs'],
+  ruby: ['rb'],
+  shell: ['sh', 'ps1'],
+  yaml: ['yml', 'yaml']
+};
+
 function resolveInWorkspace(root, targetPath = '.') {
   const absRoot = path.resolve(root);
   const absTarget = path.resolve(absRoot, targetPath);
@@ -13,11 +56,337 @@ function resolveInWorkspace(root, targetPath = '.') {
   return absTarget;
 }
 
+function toWorkspaceRelative(root, absPath) {
+  return path.relative(path.resolve(root), absPath).replace(/\\/g, '/');
+}
+
+function sha256(input) {
+  return `sha256:${crypto.createHash('sha256').update(String(input || '')).digest('hex')}`;
+}
+
+function sha1(input) {
+  return crypto.createHash('sha1').update(String(input || '')).digest('hex');
+}
+
+function trimLinePreview(line, maxLen = 180) {
+  const text = String(line || '').replace(/\t/g, '  ').trim();
+  if (text.length <= maxLen) return text;
+  return `${text.slice(0, maxLen - 3)}...`;
+}
+
+function escapeRegex(value) {
+  return String(value || '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function splitLines(text) {
+  return String(text || '').split('\n');
+}
+
+function detectTextFile(filePath) {
+  return TEXT_EXTENSIONS.has(path.extname(filePath).toLowerCase());
+}
+
+function normalizeFileTypes(args = {}) {
+  const explicit = Array.isArray(args?.file_types) ? args.file_types.map((item) => String(item || '').trim().toLowerCase()).filter(Boolean) : [];
+  const language = String(args?.language || '').trim().toLowerCase();
+  const languageTypes = LANGUAGE_FILE_TYPES[language] || [];
+  const merged = [...explicit, ...languageTypes];
+  return [...new Set(merged)];
+}
+
+async function walkTextFiles(root, startPath = '.', fileTypes = []) {
+  const abs = resolveInWorkspace(root, startPath);
+  const out = [];
+  const allowedExts = new Set((Array.isArray(fileTypes) ? fileTypes : []).map((item) => `.${String(item || '').replace(/^\./, '')}`));
+
+  async function visit(current) {
+    const stat = await fs.stat(current);
+    if (stat.isDirectory()) {
+      const name = path.basename(current);
+      if (SKIP_DIRS.has(name)) return;
+      const entries = await fs.readdir(current);
+      for (const entry of entries) {
+        await visit(path.join(current, entry));
+      }
+      return;
+    }
+    if (!detectTextFile(current)) return;
+    if (allowedExts.size > 0 && !allowedExts.has(path.extname(current).toLowerCase())) return;
+    out.push(current);
+  }
+
+  await visit(abs);
+  return out;
+}
+
+function getLineColumnForMatch(line, query, caseSensitive = false) {
+  const haystack = caseSensitive ? line : line.toLowerCase();
+  const needle = caseSensitive ? query : query.toLowerCase();
+  const index = haystack.indexOf(needle);
+  return index === -1 ? 1 : index + 1;
+}
+
+function classifyMatch(preview, query) {
+  const line = String(preview || '');
+  const escaped = escapeRegex(query);
+  const normalized = line.toLowerCase();
+  const queryLower = String(query || '').toLowerCase();
+  const definitionLeadPatterns = [
+    /^\s*(?:export\s+)?(?:async\s+)?function\b/i,
+    /^\s*(?:export\s+)?class\b/i,
+    /^\s*(?:export\s+)?(?:const|let|var)\b/i,
+    /^\s*(?:export\s+)?(?:interface|type|enum)\b/i,
+    /^\s*def\b/i,
+    /^\s*(?:public|private|protected)\s+[A-Za-z0-9_<>,[\]\s?]+\s+[A-Za-z0-9_$]+\s*\(/i
+  ];
+  if (definitionLeadPatterns.some((pattern) => pattern.test(line)) && normalized.includes(queryLower)) {
+    return 'definition';
+  }
+  if (new RegExp(String.raw`\b${escaped}\s*\(`, 'i').test(line)) return 'reference';
+  return 'text';
+}
+
+function matchSpecificity(preview, query) {
+  const line = String(preview || '');
+  const escaped = escapeRegex(query);
+  if (new RegExp(String.raw`\b${escaped}\b`, 'i').test(line)) return 0;
+  if (line.toLowerCase().includes(String(query || '').toLowerCase())) return 1;
+  return 2;
+}
+
+function findSymbolDefinition(lines, symbol) {
+  const escaped = String(symbol || '').replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const patterns = [
+    new RegExp(String.raw`\bfunction\s+${escaped}\b`),
+    new RegExp(String.raw`\basync\s+function\s+${escaped}\b`),
+    new RegExp(String.raw`\bexport\s+function\s+${escaped}\b`),
+    new RegExp(String.raw`\bexport\s+async\s+function\s+${escaped}\b`),
+    new RegExp(String.raw`\bclass\s+${escaped}\b`),
+    new RegExp(String.raw`\bconst\s+${escaped}\b`),
+    new RegExp(String.raw`\blet\s+${escaped}\b`),
+    new RegExp(String.raw`\bvar\s+${escaped}\b`)
+  ];
+  for (let i = 0; i < lines.length; i += 1) {
+    if (patterns.some((pattern) => pattern.test(lines[i]))) {
+      return i + 1;
+    }
+  }
+  for (let i = 0; i < lines.length; i += 1) {
+    if (new RegExp(String.raw`\b${escaped}\b`).test(lines[i])) {
+      return i + 1;
+    }
+  }
+  return 1;
+}
+
+function lineIndentSize(line) {
+  const match = String(line || '').match(/^\s*/);
+  return match ? match[0].length : 0;
+}
+
+function findBlockRange(lines, anchorLine) {
+  const total = lines.length;
+  const anchorIdx = Math.max(0, Math.min(total - 1, Number(anchorLine || 1) - 1));
+
+  let start = anchorIdx;
+  for (let i = anchorIdx; i >= 0; i -= 1) {
+    const line = String(lines[i] || '');
+    if (
+      /\b(function|class|interface|type|enum|const|let|var|export)\b/.test(line) ||
+      /=>\s*{/.test(line) ||
+      /<\w/.test(line)
+    ) {
+      start = i;
+      break;
+    }
+  }
+
+  let braceDepth = 0;
+  let seenBrace = false;
+  let end = anchorIdx;
+  for (let i = start; i < total; i += 1) {
+    const line = String(lines[i] || '');
+    for (const ch of line) {
+      if (ch === '{') {
+        braceDepth += 1;
+        seenBrace = true;
+      } else if (ch === '}') {
+        braceDepth -= 1;
+      }
+    }
+    end = i;
+    if (seenBrace && braceDepth <= 0 && i > start) {
+      return { startLine: start + 1, endLine: end + 1 };
+    }
+  }
+
+  const anchorText = String(lines[start] || '');
+  if (/^\s*def\b/.test(anchorText) || /:\s*$/.test(anchorText)) {
+    const baseIndent = lineIndentSize(anchorText);
+    end = start;
+    for (let i = start + 1; i < total; i += 1) {
+      const line = String(lines[i] || '');
+      if (!line.trim()) break;
+      if (lineIndentSize(line) <= baseIndent) break;
+      end = i;
+    }
+    return { startLine: start + 1, endLine: end + 1 };
+  }
+
+  const baseIndent = lineIndentSize(lines[start]);
+  end = start;
+  for (let i = start + 1; i < total; i += 1) {
+    const line = String(lines[i] || '');
+    if (!line.trim()) {
+      end = i;
+      continue;
+    }
+    if (lineIndentSize(line) <= baseIndent && i > anchorIdx) break;
+    end = i;
+  }
+  return { startLine: start + 1, endLine: end + 1 };
+}
+
+function extractImports(lines) {
+  return lines.filter((line) => /^\s*import\b/.test(String(line || ''))).map((line) => trimLinePreview(line, 220));
+}
+
+function extractImportSignatures(lines, maxItems = 6) {
+  const imports = [];
+  for (const line of lines) {
+    const text = String(line || '').trim();
+    if (!/^import\b/.test(text)) continue;
+    imports.push(trimLinePreview(text, 96));
+    if (imports.length >= maxItems) break;
+  }
+  return imports;
+}
+
+function extractTypeSignatures(lines, maxItems = 6) {
+  const out = [];
+  const patterns = [
+    /^\s*(?:export\s+)?type\s+[A-Za-z0-9_$]+.*$/,
+    /^\s*(?:export\s+)?interface\s+[A-Za-z0-9_$]+.*$/,
+    /^\s*(?:export\s+)?enum\s+[A-Za-z0-9_$]+.*$/,
+    /^\s*(?:export\s+)?class\s+[A-Za-z0-9_$]+.*$/,
+    /^\s*import\s+type\b.*$/
+  ];
+  for (const line of lines) {
+    const text = String(line || '').trim();
+    if (!patterns.some((pattern) => pattern.test(text))) continue;
+    out.push(trimLinePreview(text, 96));
+    if (out.length >= maxItems) break;
+  }
+  return out;
+}
+
+function extractLocalSymbols(lines, sourceSymbol = '') {
+  const out = [];
+  const seen = new Set();
+  const regex = /^\s*(?:export\s+)?(?:async\s+)?function\s+([A-Za-z0-9_$]+)|^\s*(?:export\s+)?class\s+([A-Za-z0-9_$]+)|^\s*(?:export\s+)?const\s+([A-Za-z0-9_$]+)\s*=/;
+  for (let i = 0; i < lines.length; i += 1) {
+    const match = String(lines[i] || '').match(regex);
+    const name = match?.[1] || match?.[2] || match?.[3] || '';
+    if (!name || name === sourceSymbol || seen.has(name)) continue;
+    seen.add(name);
+    out.push({
+      name,
+      line: i + 1,
+      signature: trimLinePreview(lines[i], 220)
+    });
+  }
+  return out.slice(0, 8);
+}
+
+function extractDirectCalls(lines, symbol, maxItems = 3, excludeRange = null) {
+  const escaped = escapeRegex(symbol);
+  const out = [];
+  for (let i = 0; i < lines.length && out.length < maxItems; i += 1) {
+    if (excludeRange && i + 1 >= excludeRange.startLine && i + 1 <= excludeRange.endLine) continue;
+    const line = String(lines[i] || '');
+    if (!new RegExp(String.raw`\b${escaped}\s*\(`).test(line)) continue;
+    const blockLine = findEnclosingSymbol(lines, i + 1);
+    const owner = blockLine ? trimLinePreview(lines[blockLine - 1], 220) : trimLinePreview(line, 220);
+    const ownerName = blockLine ? extractSymbolName(lines[blockLine - 1]) : '';
+    if (ownerName === symbol) continue;
+    out.push({
+      symbol: ownerName || '(anonymous)',
+      line: blockLine || i + 1,
+      preview: owner
+    });
+  }
+  return out;
+}
+
+function extractSymbolName(line) {
+  const text = String(line || '');
+  const match =
+    text.match(/\bfunction\s+([A-Za-z0-9_$]+)/) ||
+    text.match(/\bclass\s+([A-Za-z0-9_$]+)/) ||
+    text.match(/\bconst\s+([A-Za-z0-9_$]+)\s*=/) ||
+    text.match(/^\s*def\s+([A-Za-z0-9_]+)/);
+  return match?.[1] || '';
+}
+
+function findEnclosingSymbol(lines, anchorLine) {
+  for (let i = Math.max(0, anchorLine - 1); i >= 0; i -= 1) {
+    const name = extractSymbolName(lines[i]);
+    if (name) return i + 1;
+  }
+  return 0;
+}
+
+function buildUnifiedDiff(oldContent, newContent, filePath = 'file') {
+  const oldLines = splitLines(oldContent);
+  const newLines = splitLines(newContent);
+  let prefix = 0;
+  while (prefix < oldLines.length && prefix < newLines.length && oldLines[prefix] === newLines[prefix]) {
+    prefix += 1;
+  }
+
+  let suffix = 0;
+  while (
+    suffix < oldLines.length - prefix &&
+    suffix < newLines.length - prefix &&
+    oldLines[oldLines.length - 1 - suffix] === newLines[newLines.length - 1 - suffix]
+  ) {
+    suffix += 1;
+  }
+
+  const oldChanged = oldLines.slice(prefix, oldLines.length - suffix);
+  const newChanged = newLines.slice(prefix, newLines.length - suffix);
+  const oldStart = prefix + 1;
+  const newStart = prefix + 1;
+  const oldCount = Math.max(1, oldChanged.length);
+  const newCount = Math.max(1, newChanged.length);
+
+  const body = [
+    `--- ${filePath}`,
+    `+++ ${filePath}`,
+    `@@ -${oldStart},${oldCount} +${newStart},${newCount} @@`,
+    ...oldChanged.map((line) => `-${line}`),
+    ...newChanged.map((line) => `+${line}`)
+  ];
+  return body.join('\n');
+}
+
+async function getFileState(root, relativePath) {
+  const target = resolveInWorkspace(root, relativePath);
+  const stat = await fs.stat(target);
+  const content = await fs.readFile(target, 'utf8');
+  return {
+    target,
+    content,
+    lines: splitLines(content),
+    stat
+  };
+}
+
 async function readFile(root, args) {
   const target = resolveInWorkspace(root, args?.path);
   const stat = await fs.stat(target);
   const text = await fs.readFile(target, 'utf8');
-  const lines = text.split('\n');
+  const lines = splitLines(text);
   const totalLines = lines.length;
   const startLineRaw = Number(args?.start_line);
   const endLineRaw = Number(args?.end_line);
@@ -34,7 +403,7 @@ async function readFile(root, args) {
   endLine = Math.max(startLine, Math.min(endLine, totalLines));
 
   const tokenSeed = `${args?.path}|${stat.size}|${stat.mtimeMs}|${startLine}|${endLine}`;
-  const readToken = crypto.createHash('sha1').update(tokenSeed).digest('hex').slice(0, 16);
+  const readToken = sha1(tokenSeed).slice(0, 16);
 
   if (!includeContent) {
     return {
@@ -98,9 +467,7 @@ async function writeFile(root, args) {
       throw new Error(`write_file target is a directory: ${rawPath}`);
     }
   } catch (error) {
-    if (error?.code && error.code !== 'ENOENT') {
-      throw error;
-    }
+    if (error?.code && error.code !== 'ENOENT') throw error;
   }
   let before = '';
   let existed = true;
@@ -116,8 +483,8 @@ async function writeFile(root, args) {
     await fs.writeFile(target, args?.content || '', 'utf8');
   }
   const after = args?.append ? `${before}${args?.content || ''}` : args?.content || '';
-  const beforeLines = before.split('\n');
-  const afterLines = after.split('\n');
+  const beforeLines = splitLines(before);
+  const afterLines = splitLines(after);
   let changeLine = 0;
   const scanMax = Math.max(beforeLines.length, afterLines.length);
   for (let i = 0; i < scanMax; i += 1) {
@@ -165,8 +532,505 @@ async function runCommand(root, config, args) {
   return { ...result, command };
 }
 
-export function getBuiltinTools({ workspaceRoot = process.cwd(), config, sessionId = '' }) {
+async function searchCode(root, args) {
+  const query = String(args?.query || args?.symbol || '').trim();
+  if (!query) throw new Error('search_code requires query');
+  const maxResults = Math.max(1, Math.min(50, Number(args?.max_results || 12)));
+  const caseSensitive = Boolean(args?.case_sensitive);
+  const files = await walkTextFiles(root, args?.path || '.', normalizeFileTypes(args));
+  const matches = [];
+
+  for (const filePath of files) {
+    const content = await fs.readFile(filePath, 'utf8');
+    const lines = splitLines(content);
+    for (let idx = 0; idx < lines.length; idx += 1) {
+      const line = lines[idx];
+      const haystack = caseSensitive ? line : line.toLowerCase();
+      const needle = caseSensitive ? query : query.toLowerCase();
+      if (!haystack.includes(needle)) continue;
+      matches.push({
+        file: toWorkspaceRelative(root, filePath),
+        line: idx + 1,
+        column: getLineColumnForMatch(line, query, caseSensitive),
+        preview: trimLinePreview(line),
+        kind: classifyMatch(line, query),
+        symbolHint: query
+      });
+      if (matches.length >= maxResults) {
+        matches.sort((left, right) => {
+          const kindRank = { definition: 0, reference: 1, text: 2 };
+          const specificity = matchSpecificity(left.preview, query) - matchSpecificity(right.preview, query);
+          if (specificity !== 0) return specificity;
+          if (kindRank[left.kind] !== kindRank[right.kind]) return kindRank[left.kind] - kindRank[right.kind];
+          return left.file.localeCompare(right.file) || left.line - right.line;
+        });
+        return {
+          query,
+          matches,
+          definitions: matches.filter((item) => item.kind === 'definition'),
+          references: matches.filter((item) => item.kind === 'reference'),
+          text_matches: matches.filter((item) => item.kind === 'text'),
+          truncated: true
+        };
+      }
+    }
+  }
+
+  matches.sort((left, right) => {
+    const kindRank = { definition: 0, reference: 1, text: 2 };
+    const specificity = matchSpecificity(left.preview, query) - matchSpecificity(right.preview, query);
+    if (specificity !== 0) return specificity;
+    if (kindRank[left.kind] !== kindRank[right.kind]) return kindRank[left.kind] - kindRank[right.kind];
+    return left.file.localeCompare(right.file) || left.line - right.line;
+  });
+
+  return {
+    query,
+    matches,
+    definitions: matches.filter((item) => item.kind === 'definition'),
+    references: matches.filter((item) => item.kind === 'reference'),
+    text_matches: matches.filter((item) => item.kind === 'text'),
+    truncated: false
+  };
+}
+
+async function readBlock(root, args) {
+  const relativePath = String(args?.path || '').trim();
+  if (!relativePath) throw new Error('read_block requires path');
+  const { lines } = await getFileState(root, relativePath);
+  const symbol = String(args?.symbol || '').trim();
+  const anchorLine = symbol ? findSymbolDefinition(lines, symbol) : Number(args?.line || args?.anchor_line || 1);
+  const range = findBlockRange(lines, anchorLine);
+  return {
+    file: relativePath,
+    symbol: symbol || undefined,
+    mode: symbol ? 'symbol' : 'block',
+    start_line: range.startLine,
+    end_line: range.endLine,
+    content: lines.slice(range.startLine - 1, range.endLine).join('\n')
+  };
+}
+
+async function readSymbolContext(root, args) {
+  const relativePath = String(args?.path || '').trim();
+  const symbol = String(args?.symbol || '').trim();
+  if (!relativePath || !symbol) throw new Error('read_symbol_context requires path and symbol');
+  const { lines } = await getFileState(root, relativePath);
+  const mainBlock = await readBlock(root, { path: relativePath, symbol });
+  return {
+    file: relativePath,
+    symbol,
+    main_block: mainBlock,
+    related: {
+      imports: extractImports(lines),
+      import_signatures: extractImportSignatures(lines, Number(args?.max_related_imports || 4)),
+      type_signatures: extractTypeSignatures(lines, Number(args?.max_related_types || 4)),
+      local_symbols: extractLocalSymbols(lines, symbol),
+      calls: extractDirectCalls(lines, symbol, Number(args?.max_related_calls || 3), {
+        startLine: mainBlock.start_line,
+        endLine: mainBlock.end_line
+      })
+    }
+  };
+}
+
+async function validateEdit(root, args) {
+  const relativePath = String(args?.path || '').trim();
+  const kind = String(args?.kind || '').trim();
+  if (!relativePath || !kind) throw new Error('validate_edit requires path and kind');
+  const { content, lines } = await getFileState(root, relativePath);
+
+  if (kind === 'replace_block') {
+    const startLine = Number(args?.target?.start_line || args?.start_line);
+    const endLine = Number(args?.target?.end_line || args?.end_line);
+    if (!Number.isFinite(startLine) || !Number.isFinite(endLine) || startLine <= 0 || endLine < startLine) {
+      throw new Error('replace_block validation requires target.start_line and target.end_line');
+    }
+    const oldBlock = lines.slice(startLine - 1, endLine).join('\n');
+    return {
+      ok: true,
+      path: relativePath,
+      kind,
+      target: {
+        start_line: startLine,
+        end_line: endLine,
+        old_hash: sha256(oldBlock)
+      },
+      file_hash: sha256(content)
+    };
+  }
+
+  if (kind === 'replace_text' || kind === 'insert_before' || kind === 'insert_after') {
+    const probe = String(args?.old_text || args?.anchor_text || '');
+    if (!probe) throw new Error(`${kind} validation requires old_text or anchor_text`);
+    const occurrences = content.split(probe).length - 1;
+    return {
+      ok: occurrences === 1,
+      path: relativePath,
+      kind,
+      occurrences,
+      reason: occurrences === 1 ? 'unique match' : occurrences === 0 ? 'anchor not found' : 'anchor not unique',
+      file_hash: sha256(content)
+    };
+  }
+
+  throw new Error(`validate_edit does not support kind: ${kind}`);
+}
+
+function editResult(pathText, action, beforeContent, afterContent, changedLine = 1) {
+  const afterLines = splitLines(afterContent);
+  const previewStart = Math.max(0, changedLine - 1);
+  const diffPreview = afterLines.slice(previewStart, previewStart + 6).map((line, idx) => `${previewStart + idx + 1}| ${line}`).join('\n');
+  return {
+    ok: true,
+    path: pathText,
+    action,
+    changed_line: changedLine,
+    diff_preview: diffPreview,
+    diff: buildUnifiedDiff(beforeContent, afterContent, pathText),
+    new_hash: sha256(afterContent)
+  };
+}
+
+async function replaceBlock(root, args) {
+  const relativePath = String(args?.path || '').trim();
+  const newContent = String(args?.new_content || args?.content || '');
+  const target = args?.target || {};
+  const startLine = Number(target.start_line);
+  const endLine = Number(target.end_line);
+  const oldHash = String(target.old_hash || '');
+  const state = await getFileState(root, relativePath);
+  const oldBlock = state.lines.slice(startLine - 1, endLine).join('\n');
+  if (!oldHash || oldHash !== sha256(oldBlock)) {
+    throw new Error('replace_block old_hash mismatch');
+  }
+  const nextLines = [...state.lines.slice(0, startLine - 1), ...splitLines(newContent), ...state.lines.slice(endLine)];
+  const afterContent = nextLines.join('\n');
+  await fs.writeFile(state.target, afterContent, 'utf8');
+  return editResult(relativePath, 'replace_block', state.content, afterContent, startLine);
+}
+
+async function replaceText(root, args) {
+  const relativePath = String(args?.path || '').trim();
+  const oldText = String(args?.old_text || '');
+  const newText = String(args?.new_text || '');
+  const state = await getFileState(root, relativePath);
+  const occurrences = state.content.split(oldText).length - 1;
+  if (occurrences !== 1) {
+    throw new Error(occurrences === 0 ? 'replace_text old_text not found' : 'replace_text old_text not unique');
+  }
+  const afterContent = state.content.replace(oldText, newText);
+  await fs.writeFile(state.target, afterContent, 'utf8');
+  const changedLine = splitLines(state.content.slice(0, state.content.indexOf(oldText))).length;
+  return editResult(relativePath, 'replace_text', state.content, afterContent, changedLine);
+}
+
+async function insertRelative(root, args, mode) {
+  const relativePath = String(args?.path || '').trim();
+  const anchorText = String(args?.anchor_text || '');
+  const content = String(args?.content || '');
+  const state = await getFileState(root, relativePath);
+  const occurrences = state.content.split(anchorText).length - 1;
+  if (occurrences !== 1) {
+    throw new Error(occurrences === 0 ? `${mode} anchor not found` : `${mode} anchor not unique`);
+  }
+  const replacement = mode === 'insert_before' ? `${content}${anchorText}` : `${anchorText}${content}`;
+  const afterContent = state.content.replace(anchorText, replacement);
+  await fs.writeFile(state.target, afterContent, 'utf8');
+  const changedLine = splitLines(state.content.slice(0, state.content.indexOf(anchorText))).length;
+  return editResult(relativePath, mode, state.content, afterContent, changedLine);
+}
+
+async function generateDiff(root, args) {
+  const relativePath = String(args?.path || '').trim();
+  if (!relativePath) throw new Error('generate_diff requires path');
+  const state = await getFileState(root, relativePath);
+  const newContent = String(args?.new_content || '');
+  return {
+    path: relativePath,
+    old_hash: sha256(state.content),
+    new_hash: sha256(newContent),
+    diff: buildUnifiedDiff(state.content, newContent, relativePath)
+  };
+}
+
+async function locate(root, args) {
+  const result = await searchCode(root, args);
+  return {
+    query: result.query,
+    matches: result.matches,
+    definitions: result.definitions,
+    references: result.references,
+    text_matches: result.text_matches,
+    truncated: result.truncated
+  };
+}
+
+async function openTarget(root, args) {
+  const file = String(args?.file || args?.path || '').trim();
+  if (!file) throw new Error('open_target requires file');
+  const symbol = String(args?.symbol || '').trim();
+  const line = Number(args?.line || 1);
+  const mainBlock = symbol
+    ? await readSymbolContext(root, {
+        path: file,
+        symbol,
+        max_related_calls: args?.max_related_calls,
+        max_related_imports: args?.max_related_imports,
+        max_related_types: args?.max_related_types
+      })
+    : { file, symbol: '', main_block: await readBlock(root, { path: file, line }), related: { imports: [], local_symbols: [] } };
+  const block = mainBlock.main_block || mainBlock;
+  return {
+    file,
+    symbol: symbol || undefined,
+    main_block: block,
+    related: mainBlock.related || { imports: [], local_symbols: [] },
+    edit_target: {
+      start_line: block.start_line,
+      end_line: block.end_line,
+      old_hash: sha256(block.content)
+    }
+  };
+}
+
+async function editTarget(root, args) {
+  const file = String(args?.file || args?.path || '').trim();
+  const edit = args?.edit || {};
+  const kind = String(edit.kind || '').trim();
+  if (!file || !kind) throw new Error('edit_target requires file and edit.kind');
+  if (kind === 'replace_block') {
+    return replaceBlock(root, {
+      path: file,
+      target: edit.target,
+      new_content: edit.new_content
+    });
+  }
+  if (kind === 'replace_text') {
+    return replaceText(root, {
+      path: file,
+      old_text: edit.old_text,
+      new_text: edit.new_text
+    });
+  }
+  if (kind === 'insert_before') {
+    return insertRelative(root, { path: file, anchor_text: edit.anchor_text, content: edit.content }, 'insert_before');
+  }
+  if (kind === 'insert_after') {
+    return insertRelative(root, { path: file, anchor_text: edit.anchor_text, content: edit.content }, 'insert_after');
+  }
+  throw new Error(`edit_target does not support kind: ${kind}`);
+}
+
+export function getBuiltinTools({ workspaceRoot = process.cwd(), config }) {
   const definitions = [
+    {
+      type: 'function',
+      function: {
+        name: 'locate',
+        description: 'High-level search that returns compact candidate code locations',
+        parameters: {
+          type: 'object',
+          properties: {
+            query: { type: 'string' },
+            path: { type: 'string' },
+            max_results: { type: 'number' },
+            language: { type: 'string' },
+            file_types: { type: 'array', items: { type: 'string' } }
+          },
+          required: ['query']
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'open_target',
+        description: 'Open a candidate location and return the smallest useful code block plus edit metadata',
+        parameters: {
+          type: 'object',
+          properties: {
+            file: { type: 'string' },
+            path: { type: 'string' },
+            line: { type: 'number' },
+            symbol: { type: 'string' },
+            max_related_calls: { type: 'number' },
+            max_related_imports: { type: 'number' },
+            max_related_types: { type: 'number' }
+          },
+          required: ['file']
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'edit_target',
+        description: 'Apply a validated high-level edit against an opened target',
+        parameters: {
+          type: 'object',
+          properties: {
+            file: { type: 'string' },
+            path: { type: 'string' },
+            edit: { type: 'object' }
+          },
+          required: ['file', 'edit']
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'search_code',
+        description: 'Search code and return structured top matches with file, line, preview, and basic match kind',
+        parameters: {
+          type: 'object',
+          properties: {
+            query: { type: 'string' },
+            path: { type: 'string' },
+            max_results: { type: 'number' },
+            case_sensitive: { type: 'boolean' },
+            language: { type: 'string' },
+            file_types: { type: 'array', items: { type: 'string' } }
+          },
+          required: ['query']
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'read_block',
+        description: 'Read the smallest likely code block around a symbol or line from a file',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string' },
+            symbol: { type: 'string' },
+            line: { type: 'number' },
+            anchor_line: { type: 'number' }
+          },
+          required: ['path']
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'read_symbol_context',
+        description: 'Read a symbol block plus import and local symbol summaries',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string' },
+            symbol: { type: 'string' },
+            max_related_calls: { type: 'number' },
+            max_related_imports: { type: 'number' },
+            max_related_types: { type: 'number' }
+          },
+          required: ['path', 'symbol']
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'validate_edit',
+        description: 'Validate whether an edit target is stable before applying it',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string' },
+            kind: { type: 'string' },
+            target: { type: 'object' },
+            start_line: { type: 'number' },
+            end_line: { type: 'number' },
+            old_text: { type: 'string' },
+            anchor_text: { type: 'string' }
+          },
+          required: ['path', 'kind']
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'replace_block',
+        description: 'Replace a validated line block using an old_hash guard',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string' },
+            target: { type: 'object' },
+            new_content: { type: 'string' }
+          },
+          required: ['path', 'target', 'new_content']
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'replace_text',
+        description: 'Replace a unique text fragment in a file',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string' },
+            old_text: { type: 'string' },
+            new_text: { type: 'string' }
+          },
+          required: ['path', 'old_text', 'new_text']
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'insert_before',
+        description: 'Insert text before a unique anchor string',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string' },
+            anchor_text: { type: 'string' },
+            content: { type: 'string' }
+          },
+          required: ['path', 'anchor_text', 'content']
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'insert_after',
+        description: 'Insert text after a unique anchor string',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string' },
+            anchor_text: { type: 'string' },
+            content: { type: 'string' }
+          },
+          required: ['path', 'anchor_text', 'content']
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'generate_diff',
+        description: 'Generate a unified diff between the current file and proposed content',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string' },
+            new_content: { type: 'string' }
+          },
+          required: ['path', 'new_content']
+        }
+      }
+    },
     {
       type: 'function',
       function: {
@@ -220,6 +1084,18 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, session
   ];
 
   const handlers = {
+    locate: (args) => locate(workspaceRoot, args),
+    open_target: (args) => openTarget(workspaceRoot, args),
+    edit_target: (args) => editTarget(workspaceRoot, args),
+    search_code: (args) => searchCode(workspaceRoot, args),
+    read_block: (args) => readBlock(workspaceRoot, args),
+    read_symbol_context: (args) => readSymbolContext(workspaceRoot, args),
+    validate_edit: (args) => validateEdit(workspaceRoot, args),
+    replace_block: (args) => replaceBlock(workspaceRoot, args),
+    replace_text: (args) => replaceText(workspaceRoot, args),
+    insert_before: (args) => insertRelative(workspaceRoot, args, 'insert_before'),
+    insert_after: (args) => insertRelative(workspaceRoot, args, 'insert_after'),
+    generate_diff: (args) => generateDiff(workspaceRoot, args),
     read_file: (args) =>
       readFile(workspaceRoot, {
         ...args,