@remcp/runtime 0.2.0

package/src/tools/terminal.mjs

@@ -0,0 +1,182 @@
+import process from 'node:process';
+import { spawn } from 'node:child_process';
+import { runtimeConfig } from '../config.mjs';
+import { assertAllowedCommand } from '../policy.mjs';
+import { countEvent, recordEvent } from '../telemetry.mjs';
+import {
+  appendProcessOutput,
+  createProcessSession,
+  getProcessSession,
+  listProcessSessions,
+  markProcessExited,
+  readNewOutput,
+  readOutputRange,
+  totalLines,
+  waitForProcessExit,
+  waitForProcessActivity,
+} from '../sessions.mjs';
+import { clampInteger, fail, requireInteger, requireString, text } from '../util.mjs';
+
+function shellCommand() {
+  if (runtimeConfig.defaultShell) return runtimeConfig.defaultShell;
+  if (process.platform === 'win32') return process.env.ComSpec || 'cmd.exe';
+  return process.env.SHELL || '/bin/bash';
+}
+
+function shellArgs(command) {
+  if (process.platform === 'win32') return ['/d', '/s', '/c', command];
+  return ['-c', command];
+}
+
+function describeSession(session) {
+  const status = session.exited ? `exited${session.signal ? ` (${session.signal})` : session.exitCode === null ? '' : ` (code ${session.exitCode})`}` : 'running';
+  return { pid: session.pid, status, runtimeMs: (session.finishedAt || Date.now()) - session.startedAt, lines: totalLines(session) };
+}
+
+export async function startProcessTool(args) {
+  const command = requireString(args.command, 'command');
+  const verdict = assertAllowedCommand(command);
+  if (verdict.warned) {
+    countEvent('policyBlocks');
+    recordEvent('policy_block', { reason: verdict.findings?.[0]?.id || 'builtin', success: false });
+  }
+  const timeoutMs = clampInteger(args.timeout_ms, 1000, 0, 120000);
+  const shell = shellCommand();
+  const child = spawn(shell, shellArgs(command), {
+    cwd: process.cwd(),
+    env: process.env,
+    stdio: ['pipe', 'pipe', 'pipe'],
+    windowsHide: true,
+  });
+  if (!child.pid) fail('Could not start the command');
+  const session = createProcessSession({ pid: child.pid, child, command, shell });
+  recordEvent('session_started', { sessionKind: 'process', success: true });
+  child.stdout?.on('data', chunk => appendProcessOutput(session, chunk.toString('utf8')));
+  child.stderr?.on('data', chunk => appendProcessOutput(session, chunk.toString('utf8')));
+  child.on('error', error => { appendProcessOutput(session, `${error.message}\n`); markProcessExited(session, null, null); });
+  child.on('close', (code, signal) => markProcessExited(session, code, signal));
+  await waitForProcessExit(session, timeoutMs);
+  const headline = session.exited
+    ? `Process ${session.pid} finished${session.exitCode === null ? '' : ` with code ${session.exitCode}`}.`
+    : `Process ${session.pid} is running.`;
+  const output = session.lines.slice(-200).join('\n');
+  const partial = session.partial;
+  session.cursor = session.droppedLines + session.lines.length;
+  session.lastPartialRead = session.partial || null;
+  const warning = verdict.warned ? `Warning: this command matches the built-in dangerous-command guardrail (${verdict.findings.map(item => item.description).join(', ')}).\n` : '';
+  return text(`${warning}${[headline, output, partial].filter(Boolean).join('\n')}`);
+}
+
+export async function readProcessOutputTool(args) {
+  const pid = requireInteger(args.pid, 'pid');
+  const session = getProcessSession(pid);
+  if (!session) fail(`No ReMCP session with pid ${pid}`);
+  const timeoutMs = clampInteger(args.timeout_ms, 0, 0, 120000);
+  const hasOffset = args.offset !== undefined && args.offset !== null;
+  let slice;
+  let range;
+  if (hasOffset) {
+    // An explicit offset always means a line range: zero-based from the first line the
+    // session produced, or a negative value for the last N lines. Omit the argument to get
+    // only the output produced since the previous read. Lines evicted by the buffer cap are
+    // gone, so the earliest readable line is droppedLines.
+    const requested = Number(args.offset);
+    const page = readOutputRange(session, requested, clampInteger(args.length, 200, 1, 5000));
+    slice = page.slice;
+    range = `${page.start}-${page.end} of ${page.total}`;
+  } else {
+    if (timeoutMs) await waitForProcessActivity(session, timeoutMs);
+    slice = readNewOutput(session);
+    const first = Math.max(1, session.cursor - slice.length + 1);
+    range = slice.length ? `${first}-${session.cursor} of ${totalLines(session)}` : `no new output (${totalLines(session)} lines total)`;
+  }
+  const status = describeSession(session);
+  const header = `pid ${pid} ${status.status} · lines ${range}`;
+  return text(`${header}\n${slice.join('\n')}`);
+}
+
+function compileWaiter(pattern) {
+  try { return { regex: new RegExp(pattern) }; } catch { return { literal: pattern }; }
+}
+
+function waiterMatches(lines, matcher) {
+  if (matcher.literal) return lines.some(line => line.includes(matcher.literal));
+  matcher.regex.lastIndex = 0;
+  return lines.some(line => matcher.regex.test(line));
+}
+
+export async function waitForProcessOutputTool(args) {
+  const pid = requireInteger(args.pid, 'pid');
+  const session = getProcessSession(pid);
+  if (!session) fail(`No ReMCP session with pid ${pid}`);
+  const pattern = requireString(args.pattern, 'pattern');
+  const matcher = compileWaiter(pattern);
+  const timeoutMs = clampInteger(args.timeout_ms, 10000, 0, 120000);
+  const startLine = Math.max(0, session.cursor - session.droppedLines);
+  const deadline = Date.now() + timeoutMs;
+  let slice = session.lines.slice(startLine);
+  while (!waiterMatches(slice, matcher) && Date.now() < deadline && !session.exited) {
+    await waitForProcessActivity(session, Math.min(250, Math.max(20, deadline - Date.now())));
+    slice = session.lines.slice(startLine);
+  }
+  const matched = waiterMatches(slice, matcher);
+  session.cursor = session.droppedLines + session.lines.length;
+  session.lastPartialRead = session.partial || null;
+  const status = describeSession(session);
+  const headline = matched
+    ? `pid ${pid} ${status.status} · pattern matched`
+    : `pid ${pid} ${status.status} · pattern not matched within ${timeoutMs}ms`;
+  return text([headline, slice.join('\n')].filter(Boolean).join('\n'));
+}
+
+export async function interactWithProcessTool(args) {
+  const pid = requireInteger(args.pid, 'pid');
+  const session = getProcessSession(pid);
+  if (!session) fail(`No ReMCP session with pid ${pid}`);
+  if (session.exited) fail(`Process ${pid} already exited`);
+  const input = typeof args.input === 'string' ? args.input : fail('input must be a string');
+  const timeoutMs = clampInteger(args.timeout_ms, 1000, 0, 120000);
+  session.cursor = session.droppedLines + session.lines.length;
+  session.lastPartialRead = null;
+  session.child.stdin?.write(`${input}\n`);
+  await waitForProcessActivity(session, timeoutMs);
+  const slice = readNewOutput(session);
+  const status = describeSession(session);
+  return text([`pid ${pid} ${status.status}`, slice.join('\n')].filter(Boolean).join('\n'));
+}
+
+export async function forceTerminateTool(args) {
+  const pid = requireInteger(args.pid, 'pid');
+  const session = getProcessSession(pid);
+  if (!session) fail(`No ReMCP session with pid ${pid}`);
+  if (session.exited) return text(`Process ${pid} already exited.`);
+  try { session.child.kill('SIGTERM'); } catch {}
+  const deadline = Date.now() + 2000;
+  while (!session.exited && Date.now() < deadline) await waitForProcessActivity(session, 100);
+  if (!session.exited) {
+    try { session.child.kill('SIGKILL'); } catch {}
+    await waitForProcessActivity(session, 1000);
+  }
+  const status = describeSession(session);
+  return text(`Terminated session ${pid}. Status: ${status.status}.`);
+}
+
+export async function listSessionsTool() {
+  const sessions = listProcessSessions();
+  if (!sessions.length) return text('No active terminal sessions.');
+  const rows = sessions.map(session => {
+    const status = describeSession(session);
+    const blocked = session.exited ? '' : session.partial ? 'blocked-possibly' : 'idle-or-running';
+    return `pid ${status.pid} · ${status.status} · ${Math.round(status.runtimeMs / 1000)}s · ${blocked} · ${session.command.slice(0, 120)}`;
+  });
+  return text(rows.join('\n'));
+}
+
+export const terminalToolHandlers = {
+  start_process: startProcessTool,
+  read_process_output: readProcessOutputTool,
+  wait_for_process_output: waitForProcessOutputTool,
+  interact_with_process: interactWithProcessTool,
+  force_terminate: forceTerminateTool,
+  list_sessions: listSessionsTool,
+};

package/src/util.mjs

@@ -0,0 +1,147 @@
+import os from 'node:os';
+import path from 'node:path';
+import { realpath } from 'node:fs/promises';
+import { runtimeConfig } from './config.mjs';
+
+export class ToolError extends Error {}
+
+export function fail(message) {
+  throw new ToolError(String(message));
+}
+
+export function expandHome(value) {
+  const text = String(value ?? '');
+  if (text === '~') return os.homedir();
+  if (text.startsWith('~/') || text.startsWith('~\\')) return path.join(os.homedir(), text.slice(2));
+  return text;
+}
+
+export function requireString(value, field) {
+  if (typeof value !== 'string' || !value.trim()) fail(`${field} is required`);
+  return value.trim();
+}
+
+export function requireInteger(value, field) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) fail(`${field} must be a positive integer`);
+  return parsed;
+}
+
+export function clampInteger(value, fallback, min, max) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.min(max, Math.max(min, Math.trunc(parsed)));
+}
+
+export function resolveInputPath(value, field = 'path') {
+  const raw = expandHome(requireString(value, field));
+  if (raw.includes('\0')) fail(`${field} contains an invalid character`);
+  const absolute = path.resolve(raw);
+  if (runtimeConfig.allowedRoots.length && !isInsideAnyRoot(absolute)) {
+    fail(`Path is outside the directories this device allows: ${runtimeConfig.allowedRoots.join(', ')}`);
+  }
+  return absolute;
+}
+
+export function isInsideRoot(candidate, root) {
+  return candidate === root || candidate.startsWith(root + path.sep);
+}
+
+function isInsideAnyRoot(candidate) {
+  return runtimeConfig.allowedRoots.some(root => isInsideRoot(candidate, root));
+}
+
+// Resolve symlinks for the deepest path segment that exists, then re-append the
+// segments that do not exist yet. A lexical prefix check alone is not enough:
+// `<allowed>/link -> /etc` would otherwise pass the allowlist and read /etc.
+export async function canonicalizePath(target) {
+  let current = path.resolve(target);
+  const missing = [];
+  for (;;) {
+    try {
+      const resolved = await realpath(current);
+      return missing.length ? path.join(resolved, ...missing) : resolved;
+    } catch (error) {
+      if (error?.code !== 'ENOENT' && error?.code !== 'ENOTDIR') return missing.length ? path.join(current, ...missing) : current;
+      const parent = path.dirname(current);
+      if (parent === current) return missing.length ? path.join(current, ...missing) : current;
+      missing.unshift(path.basename(current));
+      current = parent;
+    }
+  }
+}
+
+let resolvedRootsPromise;
+function resolvedRoots() {
+  if (!resolvedRootsPromise) {
+    resolvedRootsPromise = Promise.all(runtimeConfig.allowedRoots.map(async root => {
+      try { return await realpath(root); } catch { return root; }
+    }));
+  }
+  return resolvedRootsPromise;
+}
+
+// Canonical, allowlist-checked path for every file tool. The canonical path is what
+// callers must use, so a symlink cannot be swapped between the check and the access.
+export async function resolveSafePath(value, field = 'path') {
+  const absolute = resolveInputPath(value, field);
+  if (!runtimeConfig.allowedRoots.length) return absolute;
+  const canonical = await canonicalizePath(absolute);
+  const roots = await resolvedRoots();
+  if (!roots.some(root => isInsideRoot(canonical, root))) {
+    fail(`Path resolves outside the directories this device allows: ${runtimeConfig.allowedRoots.join(', ')}`);
+  }
+  return canonical;
+}
+
+export function displayPath(absolute) {
+  const home = os.homedir();
+  return absolute.startsWith(home + path.sep) ? `~/${absolute.slice(home.length + 1)}` : absolute;
+}
+
+export function truncate(text, maxBytes) {
+  const limit = maxBytes || runtimeConfig.maxOutputBytes;
+  const buffer = Buffer.from(text, 'utf8');
+  if (buffer.length <= limit) return text;
+  const head = buffer.subarray(0, Math.floor(limit * 0.7)).toString('utf8');
+  const tail = buffer.subarray(buffer.length - Math.floor(limit * 0.2)).toString('utf8');
+  return `${head}\n… output truncated (${buffer.length} bytes, limit ${limit}) …\n${tail}`;
+}
+
+export function text(value, isError = false) {
+  const body = typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+  return { content: [{ type: 'text', text: truncate(body) }], ...(isError ? { isError: true } : {}) };
+}
+
+export function splitLines(value) {
+  const normalized = String(value).replace(/\r\n/g, '\n').replace(/\r/g, '\n');
+  if (normalized === '') return [];
+  const lines = normalized.split('\n');
+  if (lines.length > 1 && lines[lines.length - 1] === '') lines.pop();
+  return lines;
+}
+
+export function looksBinary(buffer) {
+  return buffer.subarray(0, 8000).includes(0);
+}
+
+export function pageLines(lines, offset, length) {
+  const total = lines.length;
+  const requested = Math.trunc(offset || 0);
+  if (requested < 0) {
+    const count = Math.min(Math.abs(requested), total);
+    return { start: total - count, end: total, slice: lines.slice(total - count) };
+  }
+  const start = Math.min(requested, total);
+  const end = Math.min(start + Math.max(1, Math.trunc(length || runtimeConfig.maxReadLines)), total);
+  return { start, end, slice: lines.slice(start, end) };
+}
+
+export function globToRegExp(pattern) {
+  const escaped = String(pattern).replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*/g, '\u0000')
+    .replace(/\*/g, '[^/]*')
+    .replace(/\?/g, '.')
+    .replace(/\u0000/g, '.*');
+  return new RegExp(`^${escaped}$`);
+}

package/src/version.mjs

@@ -0,0 +1,6 @@
+import { readFileSync } from 'node:fs';
+
+const manifest = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+
+export const PACKAGE_NAME = manifest.name;
+export const VERSION = manifest.version;