@wonderwhy-er/desktop-commander
Version:
MCP server for terminal operations and file editing
634 lines (633 loc) • 27.3 kB
JavaScript
import { spawn } from 'child_process';
import path from 'path';
import { DEFAULT_COMMAND_TIMEOUT } from './config.js';
import { configManager } from './config-manager.js';
import { capture } from "./utils/capture.js";
import { analyzeProcessState } from './utils/process-detection.js';
/**
* Standard Windows PATHEXT value, used to repair a corrupted PATHEXT before
* spawning child shells.
*
* On some Windows Claude Desktop / DXT launches the server process inherits a
* broken PATHEXT (observed as ".CPL" only). Because we build the child env from
* { ...process.env }, that broken value would propagate into every spawned
* shell, stripping ".EXE" and breaking resolution of git / node / python / rg /
* etc. (and even full-path .exe invocations under PowerShell). See issue #481.
*/
const STANDARD_PATHEXT = '.COM;.EXE;.BAT;.CMD;.VBS;.VBE;.JS;.JSE;.WSF;.WSH;.MSC';
/**
* Return a healthy PATHEXT for spawned Windows shells.
* - Unset -> use the standard list.
* - Missing ".EXE" -> corrupted; merge the standard list with whatever was
* present (preserves any extra extensions, order-stable).
* - Otherwise -> leave the inherited value untouched.
*/
function getRepairedPathExt() {
const current = process.env.PATHEXT;
if (!current)
return STANDARD_PATHEXT;
const exts = current.split(';').map(e => e.trim().toUpperCase()).filter(Boolean);
if (!exts.includes('.EXE')) {
return [...new Set([...STANDARD_PATHEXT.split(';'), ...exts])].join(';');
}
return current;
}
/**
* Output buffering caps. Without a cap, a process emitting enough output makes
* string concatenation throw "RangeError: Invalid string length" at V8's max
* string size (~536M chars) inside a stdout 'data' handler — an uncaught
* exception that kills the whole server (index.ts exits on uncaughtException).
* The cap also bounds the join() cost in snapshot reads and the periodic
* process-state scan, both of which are O(total output).
*/
export const MAX_BUFFERED_OUTPUT_CHARS = 50 * 1024 * 1024; // per session; oldest lines evicted first
const MAX_LINE_CHARS = 1024 * 1024; // force-split longer lines so eviction can work
const MAX_WAIT_OUTPUT_CHARS = 2 * 1024 * 1024; // start_process wait buffer (prompt/state detection)
/**
* Get the appropriate spawn configuration for a given shell
* This handles login shell flags for different shell types
*/
function getShellSpawnArgs(shellPath, command) {
const shellName = path.basename(shellPath).toLowerCase();
// Unix shells with login flag support
if (shellName.includes('bash') || shellName.includes('zsh')) {
return {
executable: shellPath,
args: ['-l', '-c', command],
useShellOption: false
};
}
// PowerShell Core (cross-platform, supports -Login)
if (shellName === 'pwsh' || shellName === 'pwsh.exe') {
return {
executable: shellPath,
args: ['-Login', '-Command', command],
useShellOption: false
};
}
// Windows PowerShell 5.1 (no login flag support)
if (shellName === 'powershell' || shellName === 'powershell.exe') {
return {
executable: shellPath,
args: ['-Command', command],
useShellOption: false
};
}
// CMD
if (shellName === 'cmd' || shellName === 'cmd.exe') {
return {
executable: shellPath,
args: ['/c', command],
windowsVerbatim: true,
useShellOption: false
};
}
// Fish shell (uses -l for login, -c for command)
if (shellName.includes('fish')) {
return {
executable: shellPath,
args: ['-l', '-c', command],
useShellOption: false
};
}
// Unknown/other shells - use shell option for safety
// This provides a fallback for shells we don't explicitly handle
return {
executable: command,
args: [],
useShellOption: shellPath
};
}
export class TerminalManager {
constructor() {
this.sessions = new Map();
this.completedSessions = new Map();
}
/**
* Send input to a running process
* @param pid Process ID
* @param input Text to send to the process
* @returns Whether input was successfully sent
*/
sendInputToProcess(pid, input) {
const session = this.sessions.get(pid);
if (!session) {
return false;
}
try {
if (session.process.stdin && !session.process.stdin.destroyed) {
// Ensure input ends with a newline for most REPLs
const inputWithNewline = input.endsWith('\n') ? input : input + '\n';
session.process.stdin.write(inputWithNewline);
return true;
}
return false;
}
catch (error) {
console.error(`Error sending input to process ${pid}:`, error);
return false;
}
}
async executeCommand(command, timeoutMs = DEFAULT_COMMAND_TIMEOUT, shell, collectTiming = false) {
// Get the shell from config if not specified
let shellToUse = shell;
if (!shellToUse) {
try {
const config = await configManager.getConfig();
shellToUse = config.defaultShell || true;
}
catch (error) {
// If there's an error getting the config, fall back to default
shellToUse = true;
}
}
// For REPL interactions, we need to ensure stdin, stdout, and stderr are properly configured
// Note: No special stdio options needed here, Node.js handles pipes by default
// Enhance SSH commands automatically
let enhancedCommand = command;
if (command.trim().startsWith('ssh ') && !command.includes(' -t')) {
enhancedCommand = command.replace(/^ssh /, 'ssh -t ');
console.log(`Enhanced SSH command: ${enhancedCommand}`);
}
// Get the appropriate spawn configuration for the shell
let spawnConfig;
let spawnOptions;
if (typeof shellToUse === 'string') {
// Use shell-specific configuration with login flags where appropriate
spawnConfig = getShellSpawnArgs(shellToUse, enhancedCommand);
spawnOptions = {
env: {
...process.env,
TERM: 'xterm-256color' // Better terminal compatibility
},
windowsHide: true // Prevent visible console windows on Windows
};
// Add shell option if needed (for unknown shells)
if (spawnConfig.useShellOption) {
spawnOptions.shell = spawnConfig.useShellOption;
}
}
else {
// Boolean or undefined shell - use default shell option behavior
spawnConfig = {
executable: enhancedCommand,
args: [],
useShellOption: shellToUse
};
spawnOptions = {
shell: shellToUse,
env: {
...process.env,
TERM: 'xterm-256color'
},
windowsHide: true // Prevent visible console windows on Windows
};
}
// Repair PATHEXT on Windows before spawning. On some Windows DXT launches
// the server process inherits a corrupted PATHEXT (e.g. ".CPL"), which we
// would otherwise propagate via { ...process.env } and break command
// resolution (git, node, python, rg, ...) in the spawned shell. See #481.
if (process.platform === 'win32' && spawnOptions.env) {
spawnOptions.env.PATHEXT = getRepairedPathExt();
}
// On Windows, when we invoke cmd.exe directly and pass the user's command as a
// single argument, Node/libuv applies MSVCRT-style quoting that escapes embedded
// double quotes as \" . cmd.exe does not understand that escaping, so any command
// containing quotes (e.g. a quoted path with spaces like "C:\Program Files\app.exe")
// is corrupted before the shell ever parses it. Passing arguments verbatim lets
// cmd handle its own quoting. Scoped to shells that set windowsVerbatim (cmd only)
// because PowerShell/pwsh have different quote rules and must NOT use verbatim.
if (process.platform === 'win32' && spawnConfig.windowsVerbatim) {
spawnOptions.windowsVerbatimArguments = true;
}
// Spawn the process with appropriate arguments
const childProcess = spawn(spawnConfig.executable, spawnConfig.args, spawnOptions);
let output = '';
// Ensure childProcess.pid is defined before proceeding
if (!childProcess.pid) {
// Return a consistent error object instead of throwing
return {
pid: -1, // Use -1 to indicate an error state
output: 'Error: Failed to get process ID. The command could not be executed.',
isBlocked: false
};
}
const session = {
pid: childProcess.pid,
process: childProcess,
outputLines: [], // Line-based buffer
lastReadIndex: 0, // Track where "new" output starts
isBlocked: false,
startTime: new Date(),
bufferedChars: 0,
evictedLines: 0,
evictedChars: 0
};
this.sessions.set(childProcess.pid, session);
// Timing telemetry
const startTime = Date.now();
let firstOutputTime;
let lastOutputTime;
const outputEvents = [];
let exitReason = 'timeout';
return new Promise((resolve) => {
let resolved = false;
let periodicCheck = null;
// Quick prompt patterns for immediate detection
const quickPromptPatterns = />>>\s*$|>\s*$|\$\s*$|#\s*$/;
const resolveOnce = (result) => {
if (resolved)
return;
resolved = true;
if (periodicCheck)
clearInterval(periodicCheck);
// Add timing info if requested
if (collectTiming) {
const endTime = Date.now();
result.timingInfo = {
startTime,
endTime,
totalDurationMs: endTime - startTime,
exitReason,
firstOutputTime,
lastOutputTime,
timeToFirstOutputMs: firstOutputTime ? firstOutputTime - startTime : undefined,
outputEvents: outputEvents.length > 0 ? outputEvents : undefined
};
}
resolve(result);
};
childProcess.stdout.on('data', (data) => {
const text = data.toString();
const now = Date.now();
if (!firstOutputTime)
firstOutputTime = now;
lastOutputTime = now;
// `output` only feeds the wait-phase result and prompt/state detection,
// so stop growing it once resolved and keep only a bounded tail.
if (!resolved) {
output += text;
if (output.length > MAX_WAIT_OUTPUT_CHARS) {
output = output.slice(-Math.floor(MAX_WAIT_OUTPUT_CHARS / 2));
}
}
// Append to line-based buffer
this.appendToLineBuffer(session, text);
// Record output event if collecting timing
if (collectTiming) {
outputEvents.push({
timestamp: now,
deltaMs: now - startTime,
source: 'stdout',
length: text.length,
snippet: text.slice(0, 50).replace(/\n/g, '\\n')
});
}
// Immediate check for obvious prompts
if (quickPromptPatterns.test(text)) {
session.isBlocked = true;
exitReason = 'early_exit_quick_pattern';
if (collectTiming && outputEvents.length > 0) {
outputEvents[outputEvents.length - 1].matchedPattern = 'quick_pattern';
}
resolveOnce({
pid: childProcess.pid,
output,
isBlocked: true
});
}
});
childProcess.stderr.on('data', (data) => {
const text = data.toString();
const now = Date.now();
if (!firstOutputTime)
firstOutputTime = now;
lastOutputTime = now;
if (!resolved) {
output += text;
if (output.length > MAX_WAIT_OUTPUT_CHARS) {
output = output.slice(-Math.floor(MAX_WAIT_OUTPUT_CHARS / 2));
}
}
// Append to line-based buffer
this.appendToLineBuffer(session, text);
// Record output event if collecting timing
if (collectTiming) {
outputEvents.push({
timestamp: now,
deltaMs: now - startTime,
source: 'stderr',
length: text.length,
snippet: text.slice(0, 50).replace(/\n/g, '\\n')
});
}
});
// Periodic comprehensive check every 100ms
periodicCheck = setInterval(() => {
if (output.trim()) {
const processState = analyzeProcessState(output, childProcess.pid);
if (processState.isWaitingForInput) {
session.isBlocked = true;
exitReason = 'early_exit_periodic_check';
resolveOnce({
pid: childProcess.pid,
output,
isBlocked: true
});
}
}
}, 100);
// Timeout fallback
setTimeout(() => {
session.isBlocked = true;
exitReason = 'timeout';
resolveOnce({
pid: childProcess.pid,
output,
isBlocked: true
});
}, timeoutMs);
childProcess.on('exit', (code) => {
if (childProcess.pid) {
// Store completed session before removing active session
this.completedSessions.set(childProcess.pid, {
pid: childProcess.pid,
outputLines: [...session.outputLines], // Copy line buffer
exitCode: code,
startTime: session.startTime,
endTime: new Date(),
evictedLines: session.evictedLines,
evictedChars: session.evictedChars
});
// Keep only last 100 completed sessions
if (this.completedSessions.size > 100) {
const oldestKey = Array.from(this.completedSessions.keys())[0];
this.completedSessions.delete(oldestKey);
}
this.sessions.delete(childProcess.pid);
}
exitReason = 'process_exit';
resolveOnce({
pid: childProcess.pid,
output,
isBlocked: false
});
});
});
}
/**
* Append text to a session's line buffer
* Handles partial lines and newline splitting
*/
appendToLineBuffer(session, text) {
if (!text)
return;
// Split text into lines, keeping track of whether text ends with newline
const lines = text.split('\n');
for (let i = 0; i < lines.length; i++) {
const line = lines[i];
const isLastFragment = i === lines.length - 1;
const endsWithNewline = text.endsWith('\n');
if (session.outputLines.length === 0) {
// First line ever
session.outputLines.push(line);
}
else if (i === 0) {
// First fragment - append to last line (might be partial)
session.outputLines[session.outputLines.length - 1] += line;
}
else {
// Subsequent lines - add as new lines
session.outputLines.push(line);
}
}
// Appended text contributes exactly its length to the joined buffer
// (its newlines become the join separators).
session.bufferedChars += text.length;
// A process printing without newlines grows a single line forever, which
// eviction can't bound — force-split so no line exceeds MAX_LINE_CHARS.
// Each inserted break adds one separator to the joined length.
let lastIndex = session.outputLines.length - 1;
while (session.outputLines[lastIndex].length > MAX_LINE_CHARS) {
const overlong = session.outputLines[lastIndex];
session.outputLines[lastIndex] = overlong.slice(0, MAX_LINE_CHARS);
session.outputLines.push(overlong.slice(MAX_LINE_CHARS));
session.bufferedChars += 1;
lastIndex++;
}
// Enforce the per-session cap by evicting the oldest lines. Keeps the
// buffer far below V8's max string length so concatenation and join()
// can never throw "Invalid string length" and kill the server.
while (session.bufferedChars > MAX_BUFFERED_OUTPUT_CHARS && session.outputLines.length > 1) {
const dropped = session.outputLines.shift();
const droppedJoinedChars = dropped.length + 1; // +1 for its join separator
session.bufferedChars -= droppedJoinedChars;
session.evictedChars += droppedJoinedChars;
session.evictedLines++;
if (session.lastReadIndex > 0)
session.lastReadIndex--;
}
}
/**
* Read process output with pagination (like file reading)
* @param pid Process ID
* @param offset Line offset: 0=from lastReadIndex, positive=absolute, negative=tail
* @param length Max lines to return
* @param updateReadIndex Whether to update lastReadIndex (default: true for offset=0)
*/
readOutputPaginated(pid, offset = 0, length = 1000) {
// First check active sessions
const session = this.sessions.get(pid);
if (session) {
const result = this.readFromLineBuffer(session.outputLines, offset, length, session.lastReadIndex, (newIndex) => { session.lastReadIndex = newIndex; }, false, undefined);
result.evictedLines = session.evictedLines;
return result;
}
// Then check completed sessions
const completedSession = this.completedSessions.get(pid);
if (completedSession) {
const runtimeMs = completedSession.endTime.getTime() - completedSession.startTime.getTime();
const result = this.readFromLineBuffer(completedSession.outputLines, offset, length, 0, // Completed sessions don't track read position
() => { }, // No-op for completed sessions
true, completedSession.exitCode, runtimeMs);
result.evictedLines = completedSession.evictedLines;
return result;
}
return null;
}
/**
* Internal helper to read from a line buffer with offset/length
*/
readFromLineBuffer(lines, offset, length, lastReadIndex, updateLastRead, isComplete, exitCode, runtimeMs) {
const totalLines = lines.length;
let startIndex;
let linesToRead;
if (offset < 0) {
// Negative offset = start position from end, then read 'length' lines forward
// e.g., offset=-50, length=10 means: start 50 lines from end, read 10 lines
const fromEnd = Math.abs(offset);
startIndex = Math.max(0, totalLines - fromEnd);
linesToRead = lines.slice(startIndex, startIndex + length);
// Don't update lastReadIndex for tail reads
}
else if (offset === 0) {
// offset=0 means "from where I last read" (like getNewOutput)
startIndex = lastReadIndex;
linesToRead = lines.slice(startIndex, startIndex + length);
// Update lastReadIndex for "new output" behavior
updateLastRead(Math.min(startIndex + linesToRead.length, totalLines));
}
else {
// Positive offset = absolute position
startIndex = offset;
linesToRead = lines.slice(startIndex, startIndex + length);
// Don't update lastReadIndex for absolute position reads
}
const readCount = linesToRead.length;
const endIndex = startIndex + readCount;
const remaining = Math.max(0, totalLines - endIndex);
return {
lines: linesToRead,
totalLines,
readFrom: startIndex,
readCount,
remaining,
isComplete,
exitCode,
runtimeMs
};
}
/**
* Get total line count for a process
*/
getOutputLineCount(pid) {
const session = this.sessions.get(pid);
if (session) {
return session.outputLines.length;
}
const completedSession = this.completedSessions.get(pid);
if (completedSession) {
return completedSession.outputLines.length;
}
return null;
}
/**
* Legacy method for backward compatibility
* Returns all new output since last read
* @param maxLines Maximum lines to return (default: 1000 for context protection)
* @deprecated Use readOutputPaginated instead
*/
getNewOutput(pid, maxLines = 1000) {
const result = this.readOutputPaginated(pid, 0, maxLines);
if (!result)
return null;
const output = result.lines.join('\n').trim();
// For completed sessions, append completion info with runtime
if (result.isComplete) {
const runtimeStr = result.runtimeMs !== undefined
? `\nRuntime: ${(result.runtimeMs / 1000).toFixed(2)}s`
: '';
if (output) {
return `${output}\n\nProcess completed with exit code ${result.exitCode}${runtimeStr}`;
}
else {
return `Process completed with exit code ${result.exitCode}${runtimeStr}\n(No output produced)`;
}
}
// Add truncation warning if there's more output
if (result.remaining > 0) {
return `${output}\n\n[Output truncated: ${result.remaining} more lines available. Use read_process_output with offset/length for full output.]`;
}
return output || null;
}
/**
* Capture a snapshot of current output state for interaction tracking.
* Used by interactWithProcess to know what output existed before sending input.
*/
captureOutputSnapshot(pid) {
const session = this.sessions.get(pid);
if (session) {
const fullOutput = session.outputLines.join('\n');
return {
// Absolute since process start (includes evicted output), so the
// offset stays valid even if the cap evicts lines between
// snapshot and read.
totalChars: session.evictedChars + fullOutput.length,
lineCount: session.evictedLines + session.outputLines.length
};
}
return null;
}
/**
* Get output that appeared since a snapshot was taken.
* This handles the case where output is appended to the last line (REPL prompts).
* Also checks completed sessions in case process finished between snapshot and poll.
*/
getOutputSinceSnapshot(pid, snapshot) {
// Check active session first
const session = this.sessions.get(pid);
if (session) {
return TerminalManager.outputSinceSnapshot(session.outputLines, session.evictedChars, snapshot.totalChars);
}
// Fallback to completed sessions - process may have finished between snapshot and poll
const completedSession = this.completedSessions.get(pid);
if (completedSession) {
return TerminalManager.outputSinceSnapshot(completedSession.outputLines, completedSession.evictedChars, snapshot.totalChars);
}
return null;
}
/**
* New output since a snapshot, in absolute (since process start) offsets.
* If eviction dropped part of the unseen output, returns what the buffer
* still holds — the oldest unseen chars are lost to the cap.
*/
static outputSinceSnapshot(outputLines, evictedChars, snapshotTotalChars) {
const fullOutput = outputLines.join('\n');
const newChars = evictedChars + fullOutput.length - snapshotTotalChars;
if (newChars <= 0) {
return ''; // No new output
}
return fullOutput.substring(Math.max(0, fullOutput.length - newChars));
}
/**
* Get a session by PID
* @param pid Process ID
* @returns The session or undefined if not found
*/
getSession(pid) {
return this.sessions.get(pid);
}
forceTerminate(pid) {
const session = this.sessions.get(pid);
if (!session) {
return false;
}
try {
session.process.kill('SIGINT');
setTimeout(() => {
if (this.sessions.has(pid)) {
session.process.kill('SIGKILL');
}
}, 1000);
return true;
}
catch (error) {
// Convert error to string, handling both Error objects and other types
const errorMessage = error instanceof Error ? error.message : String(error);
capture('server_request_error', { error: errorMessage, message: `Failed to terminate process ${pid}:` });
return false;
}
}
listActiveSessions() {
const now = new Date();
return Array.from(this.sessions.values()).map(session => ({
pid: session.pid,
isBlocked: session.isBlocked,
runtime: now.getTime() - session.startTime.getTime()
}));
}
listCompletedSessions() {
return Array.from(this.completedSessions.values());
}
}
export const terminalManager = new TerminalManager();