@remcp/runtime 0.2.0

package/src/tools/files.mjs

@@ -0,0 +1,239 @@
+import path from 'node:path';
+import { constants } from 'node:fs';
+import { access, copyFile, mkdir, readFile, readdir, rename, stat, unlink, writeFile } from 'node:fs/promises';
+import { runtimeConfig } from '../config.mjs';
+import { countEvent, recordEvent } from '../telemetry.mjs';
+import { clampInteger, displayPath, fail, looksBinary, pageLines, resolveSafePath, splitLines, text } from '../util.mjs';
+
+const MAX_INLINE_FILE_BYTES = 5 * 1024 * 1024;
+
+async function readTextFile(absolute) {
+  const info = await stat(absolute).catch(() => fail(`File not found: ${displayPath(absolute)}`));
+  if (info.isDirectory()) fail(`${displayPath(absolute)} is a directory, not a file`);
+  if (info.size > MAX_INLINE_FILE_BYTES) fail(`File is too large to read inline (${info.size} bytes)`);
+  const buffer = await readFile(absolute);
+  if (looksBinary(buffer)) fail(`${displayPath(absolute)} looks like a binary file and cannot be read as text`);
+  return { info, content: buffer.toString('utf8') };
+}
+
+export async function readFileTool(args) {
+  const absolute = await resolveSafePath(args.path);
+  const { content } = await readTextFile(absolute);
+  const lines = splitLines(content);
+  const offset = Number.isFinite(Number(args.offset)) ? Math.trunc(Number(args.offset)) : 0;
+  const length = clampInteger(args.length, runtimeConfig.maxReadLines, 1, 10000);
+  const { start, end, slice } = pageLines(lines, offset, length);
+  const header = lines.length ? `${displayPath(absolute)} (lines ${start + 1}-${end} of ${lines.length})` : `${displayPath(absolute)} (empty file)`;
+  return text(`${header}\n${slice.join('\n')}`);
+}
+
+export async function readMultipleFilesTool(args) {
+  if (!Array.isArray(args.paths) || !args.paths.length) fail('paths must be a non-empty array');
+  if (args.paths.length > 50) fail('paths accepts at most 50 entries per call');
+  const sections = [];
+  for (const entry of args.paths) {
+    let absolute;
+    try {
+      absolute = await resolveSafePath(entry, 'paths[]');
+    } catch (error) {
+      sections.push(`${String(entry)}: error - ${error instanceof Error ? error.message : String(error)}`);
+      continue;
+    }
+    try {
+      const { content } = await readTextFile(absolute);
+      const lines = splitLines(content);
+      const limit = runtimeConfig.maxReadLines;
+      const slice = lines.slice(0, limit);
+      const suffix = lines.length > limit ? `\n… ${lines.length - limit} more lines truncated` : '';
+      sections.push(`${displayPath(absolute)}:\n${slice.join('\n')}${suffix}`);
+    } catch (error) {
+      sections.push(`${displayPath(absolute)}: error - ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return text(sections.join('\n\n'));
+}
+
+async function listEntry(base, depth, maxDepth, prefix) {
+  const entries = await readdir(base, { withFileTypes: true });
+  entries.sort((a, b) => Number(b.isDirectory()) - Number(a.isDirectory()) || a.name.localeCompare(b.name));
+  const rows = [];
+  for (const entry of entries) {
+    const child = path.join(base, entry.name);
+    if (entry.isDirectory()) {
+      rows.push(`${prefix}[DIR] ${entry.name}`);
+      if (depth < maxDepth) rows.push(...await listEntry(child, depth + 1, maxDepth, `${prefix}  `.replace(/ {2}$/, '') + '  '));
+    } else if (entry.isSymbolicLink()) {
+      rows.push(`${prefix}[LINK] ${entry.name}`);
+    } else {
+      const info = await stat(child).catch(() => null);
+      rows.push(`${prefix}[FILE] ${entry.name}${info ? ` (${info.size} bytes)` : ''}`);
+    }
+  }
+  return rows;
+}
+
+export async function listDirectoryTool(args) {
+  const absolute = await resolveSafePath(args.path);
+  const info = await stat(absolute).catch(() => fail(`Path not found: ${displayPath(absolute)}`));
+  if (!info.isDirectory()) fail(`${displayPath(absolute)} is not a directory`);
+  const depth = clampInteger(args.depth, 1, 1, 5);
+  const rows = await listEntry(absolute, 1, depth, '');
+  return text(`${displayPath(absolute)}\n${rows.join('\n') || '(empty)'}`);
+}
+
+export async function getFileInfoTool(args) {
+  const absolute = await resolveSafePath(args.path);
+  const info = await stat(absolute).catch(() => fail(`Path not found: ${displayPath(absolute)}`));
+  const payload = {
+    path: displayPath(absolute),
+    type: info.isDirectory() ? 'directory' : info.isSymbolicLink() ? 'symlink' : 'file',
+    size: info.size,
+    createdAt: info.birthtime.toISOString(),
+    modifiedAt: info.mtime.toISOString(),
+    permissions: `0${(info.mode & 0o777).toString(8)}`,
+  };
+  if (info.isFile() && info.size <= MAX_INLINE_FILE_BYTES) {
+    const buffer = await readFile(absolute).catch(() => null);
+    if (buffer && !looksBinary(buffer)) {
+      const lines = splitLines(buffer.toString('utf8'));
+      payload.lineCount = lines.length;
+      payload.lastLine = Math.max(0, lines.length - 1);
+    }
+  }
+  return text(JSON.stringify(payload, null, 2));
+}
+
+function assertWritableSize(content) {
+  const bytes = Buffer.byteLength(content, 'utf8');
+  if (bytes > runtimeConfig.maxWriteBytes) {
+    countEvent('writeDenials');
+    recordEvent('write_denied', { reason: 'size_limit' });
+    fail(`Content is ${bytes} bytes, above the ${runtimeConfig.maxWriteBytes}-byte write limit for this device`);
+  }
+  return bytes;
+}
+
+export async function writeFileTool(args) {
+  const absolute = await resolveSafePath(args.path);
+  const content = typeof args.content === 'string' ? args.content : fail('content must be a string');
+  const mode = String(args.mode || 'rewrite').toLowerCase();
+  if (!['rewrite', 'append'].includes(mode)) fail('mode must be rewrite or append');
+  const bytes = assertWritableSize(content);
+  await mkdir(path.dirname(absolute), { recursive: true });
+  await writeFile(absolute, content, mode === 'append' ? { encoding: 'utf8', flag: 'a' } : 'utf8');
+  countEvent('bytesWritten', bytes);
+  return text(`${mode === 'append' ? 'Appended' : 'Wrote'} ${bytes} bytes to ${displayPath(absolute)}.`);
+}
+
+function normalizeForFuzzy(value) {
+  return splitLines(value).map(line => line.replace(/[ \t]+/g, ' ').trim());
+}
+
+// Whitespace-tolerant fallback: models frequently re-indent an exact block they just
+// read. Every candidate window is compared with collapsed whitespace, and the edit is
+// applied only when the number of candidate windows matches expected_replacements.
+function fuzzyMatchStarts(lines, target) {
+  const normalized = lines.map(line => line.replace(/[ \t]+/g, ' ').trim());
+  const starts = [];
+  for (let start = 0; start + target.length <= normalized.length; start += 1) {
+    let equal = true;
+    for (let index = 0; index < target.length; index += 1) {
+      if (normalized[start + index] !== target[index]) { equal = false; break; }
+    }
+    if (equal) starts.push(start);
+  }
+  return starts;
+}
+
+export async function editBlockTool(args) {
+  const absolute = await resolveSafePath(args.file_path, 'file_path');
+  const oldString = typeof args.old_string === 'string' ? args.old_string : fail('old_string must be a string');
+  const newString = typeof args.new_string === 'string' ? args.new_string : fail('new_string must be a string');
+  if (!oldString) fail('old_string must not be empty');
+  if (oldString === newString) fail('old_string and new_string are identical');
+  const allowFuzzy = args.allow_fuzzy !== false;
+  const expected = Number.isInteger(Number(args.expected_replacements)) ? Math.max(1, Math.trunc(Number(args.expected_replacements))) : 1;
+  const { content } = await readTextFile(absolute);
+  const occurrences = content.split(oldString).length - 1;
+  if (occurrences === expected) {
+    const updated = content.split(oldString).join(newString);
+    assertWritableSize(updated);
+    await writeFile(absolute, updated, 'utf8');
+    const delta = splitLines(updated).length - splitLines(content).length;
+    return text(`Replaced ${occurrences} occurrence(s) in ${displayPath(absolute)} (${delta >= 0 ? '+' : ''}${delta} lines).`);
+  }
+  if (occurrences > 0) {
+    fail(`Expected ${expected} occurrence(s) of old_string but found ${occurrences}. Add more surrounding context.`);
+  }
+  if (!allowFuzzy) fail('old_string was not found in the file');
+  const target = normalizeForFuzzy(oldString);
+  const lines = splitLines(content);
+  const starts = target.length ? fuzzyMatchStarts(lines, target) : [];
+  if (starts.length !== expected) {
+    fail(starts.length
+      ? `old_string matched ${starts.length} block(s) after whitespace normalization, expected ${expected}. Add more surrounding context.`
+      : 'old_string was not found in the file, even after whitespace normalization');
+  }
+  const replacement = splitLines(newString);
+  const endsWithNewline = /\n$/.test(content);
+  for (const start of [...starts].reverse()) lines.splice(start, target.length, ...replacement);
+  const updated = `${lines.join('\n')}${endsWithNewline && lines.length ? '\n' : ''}`;
+  assertWritableSize(updated);
+  await writeFile(absolute, updated, 'utf8');
+  const delta = lines.length - splitLines(content).length;
+  return text(`Replaced ${starts.length} occurrence(s) in ${displayPath(absolute)} using whitespace-tolerant matching (${delta >= 0 ? '+' : ''}${delta} lines). Re-read the file if exact formatting matters.`);
+}
+
+export async function createDirectoryTool(args) {
+  const absolute = await resolveSafePath(args.path);
+  await mkdir(absolute, { recursive: true });
+  return text(`Directory ready: ${displayPath(absolute)}`);
+}
+
+async function pathExists(target) {
+  try { await access(target, constants.F_OK); return true; } catch { return false; }
+}
+
+export async function moveFileTool(args) {
+  const source = await resolveSafePath(args.source, 'source');
+  const destination = await resolveSafePath(args.destination, 'destination');
+  if (source === destination) fail('source and destination are the same path');
+  await stat(source).catch(() => fail(`Source not found: ${displayPath(source)}`));
+  if (await pathExists(destination)) fail(`Destination already exists: ${displayPath(destination)}. Remove it first or pick another name.`);
+  await mkdir(path.dirname(destination), { recursive: true });
+  try {
+    await rename(source, destination);
+  } catch (error) {
+    if (error?.code !== 'EXDEV') throw error;
+    const info = await stat(source);
+    if (info.isDirectory()) fail('Moving a directory across filesystems is not supported; copy it manually or move within one volume');
+    await copyFile(source, destination);
+    await unlink(source);
+  }
+  return text(`Moved ${displayPath(source)} to ${displayPath(destination)}.`);
+}
+
+export async function copyFileTool(args) {
+  const source = await resolveSafePath(args.source, 'source');
+  const destination = await resolveSafePath(args.destination, 'destination');
+  if (source === destination) fail('source and destination are the same path');
+  const info = await stat(source).catch(() => fail(`Source not found: ${displayPath(source)}`));
+  if (info.isDirectory()) fail('copy_file copies single files only; create the directory and copy its files individually');
+  const overwrite = args.overwrite === true;
+  if (!overwrite && await pathExists(destination)) fail(`Destination already exists: ${displayPath(destination)}. Pass overwrite: true to replace it.`);
+  await mkdir(path.dirname(destination), { recursive: true });
+  await copyFile(source, destination, overwrite ? 0 : constants.COPYFILE_EXCL);
+  return text(`Copied ${displayPath(source)} to ${displayPath(destination)} (${info.size} bytes).`);
+}
+
+export const fileToolHandlers = {
+  read_file: readFileTool,
+  read_multiple_files: readMultipleFilesTool,
+  list_directory: listDirectoryTool,
+  get_file_info: getFileInfoTool,
+  write_file: writeFileTool,
+  edit_block: editBlockTool,
+  create_directory: createDirectoryTool,
+  move_file: moveFileTool,
+  copy_file: copyFileTool,
+};

package/src/tools/search.mjs

@@ -0,0 +1,251 @@
+import path from 'node:path';
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { spawn, spawnSync } from 'node:child_process';
+import { runtimeConfig } from '../config.mjs';
+import { countEvent, recordEvent } from '../telemetry.mjs';
+import {
+  appendSearchResults,
+  createSearchSession,
+  finishSearchSession,
+  getSearchSession,
+  listSearchSessions,
+  waitForSearchResults,
+} from '../sessions.mjs';
+import { clampInteger, displayPath, fail, globToRegExp, looksBinary, requireString, resolveSafePath, splitLines, text } from '../util.mjs';
+
+const SKIP_DIRECTORIES = new Set(['node_modules', '.git', '.hg', '.svn', 'dist', 'build', '.cache', '__pycache__', '.venv', 'venv']);
+const SKIP_GLOBS = ['!**/node_modules/**', '!**/.git/**', '!**/.hg/**', '!**/.svn/**', '!**/dist/**', '!**/build/**', '!**/.cache/**', '!**/__pycache__/**', '!**/.venv/**', '!**/venv/**'];
+const MAX_FALLBACK_FILE_BYTES = 2 * 1024 * 1024;
+const MAX_PATTERN_LENGTH = 400;
+
+let ripgrepPath;
+
+function ripgrep() {
+  if (ripgrepPath !== undefined) return ripgrepPath;
+  try {
+    const result = spawnSync('rg', ['--version'], { encoding: 'utf8' });
+    ripgrepPath = !result.error && result.status === 0 ? 'rg' : null;
+  } catch { ripgrepPath = null; }
+  return ripgrepPath;
+}
+
+function normalizePattern(value, literal) {
+  const pattern = requireString(value, 'pattern');
+  if (pattern.length > MAX_PATTERN_LENGTH) fail(`pattern must be at most ${MAX_PATTERN_LENGTH} characters`);
+  if (literal) return { regex: null, literal: pattern, patternIsLiteral: true };
+  try { return { regex: new RegExp(pattern, 'g'), literal: null, patternIsLiteral: false }; } catch (error) {
+    // Silently downgrading an invalid regular expression to a substring search changes the
+    // meaning of the call without telling anyone.
+    fail(`pattern is not a valid regular expression (${error instanceof Error ? error.message : String(error)}). Pass literalSearch: true to search for this text literally.`);
+  }
+}
+
+// "*.js|*.ts" is the documented alternation form; ripgrep needs one -g per glob.
+function splitGlobs(value) {
+  return String(value || '').split('|').map(part => part.trim()).filter(Boolean);
+}
+
+// A file search pattern without any glob metacharacter means "files whose name contains
+// this text", which is how callers read `pattern: "auth"`.
+function fileNameGlob(pattern) {
+  return /[*?[\]{}]/.test(pattern) ? pattern : `*${pattern}*`;
+}
+
+function matchLine(line, matcher, ignoreCase) {
+  if (matcher.literal) {
+    return ignoreCase ? line.toLowerCase().includes(matcher.literal.toLowerCase()) : line.includes(matcher.literal);
+  }
+  matcher.regex.lastIndex = 0;
+  return matcher.regex.test(line);
+}
+
+function formatContentResult(file, lineNumber, line, contextLines) {
+  const rows = [`${displayPath(file)}:${lineNumber}: ${line}`];
+  for (const entry of contextLines) rows.push(`${displayPath(file)}-${entry.number}- ${entry.text}`);
+  return rows.join('\n');
+}
+
+async function walk(target, options, onFile) {
+  const info = await stat(target).catch(() => fail(`Search path not found: ${displayPath(target)}`));
+  if (info.isFile()) { await onFile(target); return; }
+  const entries = await readdir(target, { withFileTypes: true });
+  for (const entry of entries) {
+    if (options.stopped()) return;
+    if (!options.includeHidden && entry.name.startsWith('.')) continue;
+    const child = path.join(target, entry.name);
+    if (entry.isDirectory()) {
+      if (options.skipDirectories.has(entry.name)) continue;
+      await walk(child, options, onFile);
+    } else if (entry.isFile()) {
+      await onFile(child);
+    }
+  }
+}
+
+function runRipgrep(session, { path: target, pattern, searchType, filePattern, ignoreCase, includeHidden, includeIgnored, contextLines, maxResults, patternIsLiteral }) {
+  // Flags must come before the `--` separator: anything after it is treated as a path,
+  // which silently turned `--hidden` into a search target.
+  const args = ['--no-heading', '--color', 'never'];
+  if (ignoreCase) args.push('--ignore-case');
+  if (includeHidden) args.push('--hidden');
+  if (!includeIgnored) for (const glob of SKIP_GLOBS) args.push('-g', glob);
+  for (const glob of splitGlobs(filePattern)) args.push('-g', glob);
+  if (searchType === 'files') {
+    args.push('--files');
+    args.push('-g', fileNameGlob(pattern));
+    args.push('--', target);
+  } else {
+    args.push('--line-number', '--with-filename');
+    if (patternIsLiteral) args.push('--fixed-strings');
+    if (contextLines) args.push('-C', String(contextLines));
+    args.push('--', pattern, target);
+  }
+  const child = spawn(ripgrep(), args, { stdio: ['ignore', 'pipe', 'pipe'] });
+  session.cancel = () => child.kill('SIGTERM');
+  let buffer = '';
+  let stderr = '';
+  let collected = 0;
+  let capped = false;
+  child.stdout.on('data', chunk => {
+    buffer += chunk.toString('utf8');
+    const lines = buffer.split('\n');
+    buffer = lines.pop() ?? '';
+    const batch = [];
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      batch.push(line);
+      collected += 1;
+      if (collected >= maxResults) { capped = true; child.kill('SIGTERM'); break; }
+    }
+    appendSearchResults(session, batch);
+  });
+  child.stderr.on('data', chunk => { stderr = `${stderr}${chunk.toString('utf8')}`.slice(-2000); });
+  child.on('error', error => finishSearchSession(session, 'failed', error.message));
+  child.on('close', code => {
+    if (session.status !== 'running') { finishSearchSession(session, session.status); return; }
+    // ripgrep exits 2 for a real error (bad pattern, unreadable path) and 0/1 otherwise.
+    if (code === 2 && stderr.trim()) { finishSearchSession(session, 'failed', stderr.trim().split('\n')[0]); return; }
+    finishSearchSession(session, capped ? 'capped' : 'completed');
+  });
+}
+
+async function runFallback(session, { path: target, matcher, searchType, filePattern, ignoreCase, contextLines, maxResults, includeHidden, includeIgnored }) {
+  const fileGlobs = splitGlobs(filePattern).map(globToRegExp);
+  const nameGlob = searchType === 'files' ? globToRegExp(fileNameGlob(session.pattern)) : null;
+  const nameLiteral = searchType === 'files' && !/[*?[\]{}]/.test(session.pattern) ? session.pattern : null;
+  let collected = 0;
+  await walk(target, { includeHidden, skipDirectories: includeIgnored ? new Set() : SKIP_DIRECTORIES, stopped: () => session.status !== 'running' || collected >= maxResults }, async file => {
+    if (session.status !== 'running' || collected >= maxResults) return;
+    if (fileGlobs.length && !fileGlobs.some(glob => glob.test(path.basename(file)))) return;
+    if (searchType === 'files') {
+      const base = path.basename(file);
+      const matches = (nameGlob && nameGlob.test(base)) || (nameLiteral && (ignoreCase ? base.toLowerCase().includes(nameLiteral.toLowerCase()) : base.includes(nameLiteral)));
+      if (!matches) return;
+      collected += 1;
+      appendSearchResults(session, [displayPath(file)]);
+      return;
+    }
+    const info = await stat(file).catch(() => null);
+    if (!info || info.size > MAX_FALLBACK_FILE_BYTES) return;
+    const buffer = await readFile(file).catch(() => null);
+    if (!buffer || looksBinary(buffer)) return;
+    const lines = splitLines(buffer.toString('utf8'));
+    for (let index = 0; index < lines.length; index += 1) {
+      if (session.status !== 'running' || collected >= maxResults) return;
+      if (!matchLine(lines[index], matcher, ignoreCase)) continue;
+      const context = [];
+      if (contextLines) {
+        for (let offset = Math.max(0, index - contextLines); offset <= Math.min(lines.length - 1, index + contextLines); offset += 1) {
+          if (offset === index) continue;
+          context.push({ number: offset + 1, text: lines[offset] });
+        }
+      }
+      collected += 1;
+      appendSearchResults(session, [formatContentResult(file, index + 1, lines[index], context)]);
+    }
+  });
+  finishSearchSession(session, session.status === 'running' ? (collected >= maxResults ? 'capped' : 'completed') : session.status);
+}
+
+export async function startSearchTool(args) {
+  const target = await resolveSafePath(args.path);
+  await stat(target).catch(() => fail(`Search path not found: ${displayPath(target)}`));
+  const pattern = requireString(args.pattern, 'pattern');
+  const searchType = String(args.searchType || 'content').toLowerCase();
+  if (!['content', 'files'].includes(searchType)) fail('searchType must be content or files');
+  const filePattern = typeof args.filePattern === 'string' && args.filePattern.trim() ? args.filePattern.trim() : null;
+  if (filePattern && path.isAbsolute(filePattern)) fail('filePattern must be a relative glob such as "*.ts"');
+  const ignoreCase = args.ignoreCase === true;
+  const includeHidden = args.includeHidden === true;
+  const includeIgnored = args.includeIgnored === true;
+  const contextLines = clampInteger(args.contextLines, 0, 0, 10);
+  const maxResults = clampInteger(args.maxResults, 200, 1, 5000);
+  const matcher = searchType === 'content' ? normalizePattern(pattern, args.literalSearch === true) : { regex: null, literal: pattern, patternIsLiteral: false };
+  const session = createSearchSession({ type: searchType, pattern, path: target, filePattern });
+  countEvent('searchesStarted');
+  recordEvent('session_started', { sessionKind: 'search', success: true });
+  const options = { path: target, pattern, searchType, filePattern, ignoreCase, includeHidden, includeIgnored, contextLines, maxResults, matcher, patternIsLiteral: matcher.patternIsLiteral === true };
+  // Literal searches also go to ripgrep through --fixed-strings; the JavaScript fallback
+  // only runs when ripgrep is unavailable.
+  if (ripgrep()) runRipgrep(session, options);
+  else void runFallback(session, options).catch(error => finishSearchSession(session, 'failed', error instanceof Error ? error.message : String(error)));
+  await waitForSearchResults(session, 1, 1500);
+  const initial = session.results.slice(0, 50);
+  const status = session.error ? `failed: ${session.error}` : session.status;
+  return text([
+    `searchId: ${session.id} · type: ${searchType} · status: ${status} · results so far: ${session.results.length}`,
+    `pattern: ${pattern} · path: ${displayPath(target)}`,
+    initial.join('\n'),
+    session.results.length > initial.length ? `… ${session.results.length - initial.length} more results buffered; use get_more_search_results with searchId ${session.id}` : '',
+  ].filter(Boolean).join('\n'));
+}
+
+export async function getMoreSearchResultsTool(args) {
+  const sessionId = requireString(args.sessionId, 'sessionId');
+  const session = getSearchSession(sessionId) || fail(`No search session ${sessionId}`);
+  const length = clampInteger(args.length, 100, 1, 1000);
+  const offset = Number.isFinite(Number(args.offset)) ? Math.trunc(Number(args.offset)) : 0;
+  if (offset >= 0) await waitForSearchResults(session, offset + length, 1000);
+  const total = session.results.length;
+  let start;
+  let end;
+  if (offset < 0) {
+    start = Math.max(0, total + offset);
+    end = total;
+  } else {
+    start = Math.min(offset, total);
+    end = Math.min(start + length, total);
+  }
+  const status = session.error ? `failed: ${session.error}` : session.status;
+  return text([
+    `searchId: ${session.id} · status: ${status} · results ${start}-${end} of ${total}`,
+    session.results.slice(start, end).join('\n'),
+  ].filter(Boolean).join('\n'));
+}
+
+export async function stopSearchTool(args) {
+  const sessionId = requireString(args.sessionId, 'sessionId');
+  const session = getSearchSession(sessionId) || fail(`No search session ${sessionId}`);
+  if (session.status !== 'running') return text(`Search ${sessionId} already ${session.status} with ${session.results.length} results.`);
+  session.status = 'stopped';
+  try { session.cancel?.(); } catch {}
+  finishSearchSession(session, 'stopped');
+  return text(`Stopped search ${sessionId} with ${session.results.length} results buffered.`);
+}
+
+export async function listSearchesTool() {
+  const sessions = listSearchSessions();
+  if (!sessions.length) return text('No active searches.');
+  const rows = sessions.map(session => {
+    const runtimeMs = (session.finishedAt || Date.now()) - session.startedAt;
+    return `${session.id} · ${session.type} · ${session.status} · ${session.results.length} results · ${Math.round(runtimeMs / 1000)}s · ${session.pattern} (${displayPath(session.path)})`;
+  });
+  return text(rows.join('\n'));
+}
+
+export const searchToolHandlers = {
+  start_search: startSearchTool,
+  get_more_search_results: getMoreSearchResultsTool,
+  stop_search: stopSearchTool,
+  list_searches: listSearchesTool,
+};

package/src/tools/stats.mjs

@@ -0,0 +1,71 @@
+import process from 'node:process';
+import { describeConfig, runtimeConfig } from '../config.mjs';
+import { dangerousPatternIds } from '../policy.mjs';
+import { listProcessSessions, listSearchSessions } from '../sessions.mjs';
+import { telemetryStatus } from '../telemetry.mjs';
+import { VERSION } from '../version.mjs';
+import { text } from '../util.mjs';
+
+// Read-only introspection. Unlike the upstream Desktop Commander there is deliberately
+// no set_config_value: a model must not be able to rewrite its own device limits.
+export async function getRuntimeInfoTool() {
+  const telemetry = telemetryStatus();
+  return text(JSON.stringify({
+    version: VERSION,
+    runtime: describeConfig(),
+    policy: {
+      allowedRoots: [...runtimeConfig.allowedRoots],
+      blockedCommands: [...runtimeConfig.blockedCommands],
+      dangerousCommands: runtimeConfig.dangerousCommands,
+      builtinGuardrailIds: dangerousPatternIds,
+      note: 'Guardrails reduce accidents and prompt-injected one-liners; they are not an operating-system sandbox.',
+    },
+    telemetry: {
+      enabled: telemetry.enabled,
+      transport: telemetry.transport,
+      endpoint: telemetry.endpoint,
+      thirdParty: telemetry.thirdParty,
+      installPing: telemetry.installPing,
+      remoteFeatureFlags: telemetry.remoteFeatureFlags,
+    },
+    limits: {
+      maxOutputBytes: runtimeConfig.maxOutputBytes,
+      maxReadLines: runtimeConfig.maxReadLines,
+      maxBufferedLines: runtimeConfig.maxBufferedLines,
+      maxWriteBytes: runtimeConfig.maxWriteBytes,
+      maxConcurrentConnections: 1,
+    },
+  }, null, 2));
+}
+
+export async function getRuntimeStatsTool() {
+  const telemetry = telemetryStatus();
+  const processes = listProcessSessions();
+  const searches = listSearchSessions();
+  const running = processes.filter(session => !session.exited).length;
+  return text(JSON.stringify({
+    runtimeVersion: VERSION,
+    uptimeSeconds: telemetry.uptimeSeconds,
+    counters: telemetry.counters,
+    topTools: telemetry.topTools,
+    sessions: {
+      processSessions: processes.length,
+      processSessionsRunning: running,
+      searchSessions: searches.length,
+      searchSessionsRunning: searches.filter(session => session.status === 'running').length,
+    },
+    telemetry: {
+      enabled: telemetry.enabled,
+      transport: telemetry.transport,
+      endpoint: telemetry.endpoint,
+      buffered: telemetry.buffered,
+      sentEvents: telemetry.sentEvents,
+      droppedEvents: telemetry.droppedEvents,
+    },
+  }, null, 2));
+}
+
+export const statsToolHandlers = {
+  get_runtime_info: getRuntimeInfoTool,
+  get_runtime_stats: getRuntimeStatsTool,
+};

package/src/tools/system.mjs

@@ -0,0 +1,64 @@
+import process from 'node:process';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { clampInteger, fail, requireInteger, text } from '../util.mjs';
+
+const run = promisify(execFile);
+
+const PROTECTED_PIDS = new Set([0, 1]);
+const SECRET_FLAG = /((?:^|\s)(?:--)?[A-Za-z0-9_-]*(?:TOKEN|SECRET|PASSWORD|PASSWD|API_?KEY|AUTHORIZATION)[A-Za-z0-9_-]*)([=:]\s*)(\S+)/gi;
+
+export function redactSecrets(command) {
+  return String(command).replace(SECRET_FLAG, '$1$2***');
+}
+
+export async function listProcessesTool(args = {}) {
+  const limit = clampInteger(args.limit, 100, 1, 1000);
+  const rows = [];
+  const parsed = [];
+  if (process.platform === 'win32') {
+    const { stdout } = await run('tasklist', ['/FO', 'CSV', '/NH'], { maxBuffer: 8 * 1024 * 1024 }).catch(error => fail(`Could not list processes: ${error.message}`));
+    for (const line of stdout.split(/\r?\n/)) {
+      const parts = line.split('","').map(part => part.replace(/^"|"$/g, ''));
+      if (parts.length >= 5) parsed.push({ mem: parts[4], row: `${redactSecrets(parts[0])},${parts[1]},${parts[2]},${parts[4]}` });
+    }
+  } else {
+    const { stdout } = await run('ps', ['-eo', 'pid=,ppid=,pcpu=,pmem=,etime=,comm=,args='], { maxBuffer: 8 * 1024 * 1024 }).catch(error => fail(`Could not list processes: ${error.message}`));
+    for (const line of stdout.split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      const match = trimmed.match(/^(\d+)\s+(\d+)\s+([\d.]+)\s+([\d.]+)\s+(\S+)\s+(\S+)\s*(.*)$/);
+      if (!match) continue;
+      const [, pid, ppid, cpu, mem, elapsed, comm, args] = match;
+      parsed.push({ cpu: Number(cpu), mem: Number(mem), row: `${pid},${ppid},${cpu},${mem},${elapsed},${redactSecrets((args || comm).slice(0, 200))}` });
+    }
+    parsed.sort((a, b) => b.cpu - a.cpu || b.mem - a.mem);
+  }
+  rows.push('pid,ppid,cpu%,mem%,elapsed,command');
+  rows.push(...parsed.slice(0, limit).map(entry => entry.row));
+  if (parsed.length > limit) rows.push(`… ${parsed.length - limit} more processes hidden; call list_processes with a higher limit to see them`);
+  return text(rows.join('\n'));
+}
+
+export async function killProcessTool(args) {
+  const pid = requireInteger(args.pid, 'pid');
+  if (PROTECTED_PIDS.has(pid)) fail(`Refusing to terminate protected pid ${pid}`);
+  if (pid === process.pid) fail('Refusing to terminate the ReMCP runtime process');
+  if (pid === process.ppid) fail('Refusing to terminate the ReMCP agent process that hosts this runtime');
+  try {
+    if (process.platform === 'win32') await run('taskkill', ['/PID', String(pid), '/T', '/F']);
+    else process.kill(pid, 'SIGTERM');
+  } catch (error) {
+    fail(`Could not terminate pid ${pid}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (process.platform !== 'win32') {
+    await new Promise(resolve => setTimeout(resolve, 1500));
+    try { process.kill(pid, 0); process.kill(pid, 'SIGKILL'); } catch {}
+  }
+  return text(`Termination signal sent to pid ${pid}.`);
+}
+
+export const systemToolHandlers = {
+  list_processes: listProcessesTool,
+  kill_process: killProcessTool,
+};