@wonderwhy-er/desktop-commander 0.2.42 → 0.2.44

package/dist/bootstrap.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bootstrap.js

@@ -0,0 +1,22 @@
+/**
+ * Threadpool bootstrap. MUST be the first import in index.ts.
+ *
+ * Every fs operation (read_file, write_file, edit_block, config/history/log
+ * persistence) runs on libuv's threadpool, which defaults to only 4 threads.
+ * Under heavy parallel load — e.g. several agents reading/writing files on a
+ * slow or cloud-synced filesystem — 4 stalled operations exhaust the pool, and
+ * because a stalled syscall keeps its thread until the OS returns (a JS-level
+ * timeout does not cancel it), every subsequent fs op queues for minutes. That
+ * surfaced as multi-minute tool-call hangs under parallel `claude -p` load.
+ *
+ * Raising the pool size gives enough headroom that a burst of slow reads no
+ * longer starves the rest. libuv reads UV_THREADPOOL_SIZE only when the pool is
+ * first initialized (on first submitted work), so this assignment has to happen
+ * before ANY threadpool work — hence "first import". A user-provided value is
+ * always respected.
+ */
+const DEFAULT_THREADPOOL_SIZE = 16;
+if (!process.env.UV_THREADPOOL_SIZE) {
+    process.env.UV_THREADPOOL_SIZE = String(DEFAULT_THREADPOOL_SIZE);
+}
+export {};

package/dist/config-manager.d.ts

@@ -23,6 +23,8 @@ declare class ConfigManager {
     private config;
     private initialized;
     private _isFirstRun;
+    private writeChain;
+    private saveScheduled;
     constructor();
     /**
      * Initialize configuration - load from disk or create default
@@ -37,9 +39,26 @@ declare class ConfigManager {
      */
     private getDefaultConfig;
     /**
-     * Save config to disk
+     * Write the current in-memory config to disk. All writes funnel through
+     * writeChain (see saveConfig / scheduleSave) so overlapping saves can never
+     * interleave and corrupt the file. Previously every tool call could fire its
+     * own independent fs.writeFile of the same path.
+     */
+    private writeConfigToDisk;
+    /**
+     * Awaitable save, serialized on writeChain. Use for explicit, user-driven
+     * config changes where the caller wants on-disk confirmation.
      */
     private saveConfig;
+    /**
+     * Non-blocking, coalesced save. Returns immediately; the write runs in the
+     * background. A burst of calls collapses to at most one queued write behind
+     * the in-flight one, so a storm of tool calls can't storm the disk — and,
+     * critically, can't pile up behind a saturated libuv threadpool and gate the
+     * tool-call response path. Used for high-frequency, non-critical persistence
+     * such as usage stats.
+     */
+    scheduleSave(): void;
     /**
      * Get the entire config
      */
@@ -52,6 +71,16 @@ declare class ConfigManager {
      * Set a specific configuration value
      */
     setValue(key: string, value: any): Promise<void>;
+    /**
+     * Update a value in memory and persist it WITHOUT blocking the caller.
+     * The tool-call response path must never wait on a disk write: when the libuv
+     * threadpool is saturated (e.g. many parallel reads stalled on a slow/cloud
+     * filesystem) an awaited write can't get a thread and would hang the response
+     * of even pure-memory tools. The in-memory value is updated synchronously so
+     * subsequent reads see it immediately; the write is coalesced in the
+     * background. Callers needing on-disk confirmation should use setValue.
+     */
+    setValueNonBlocking(key: string, value: any): Promise<void>;
     /**
      * Update multiple configuration values at once
      */

package/dist/config-manager.js

@@ -29,6 +29,10 @@ class ConfigManager {
         this.config = {};
         this.initialized = false;
         this._isFirstRun = false; // Track if this is the first run (config was just created)
+        // Serializes all disk writes so concurrent saves can't corrupt config.json.
+        this.writeChain = Promise.resolve();
+        // True while a coalesced background write is already queued (see scheduleSave).
+        this.saveScheduled = false;
         // Get user's home directory
         // Define config directory and file paths
         this.configPath = CONFIG_FILE;
@@ -140,16 +144,45 @@ class ConfigManager {
         };
     }
     /**
-     * Save config to disk
+     * Write the current in-memory config to disk. All writes funnel through
+     * writeChain (see saveConfig / scheduleSave) so overlapping saves can never
+     * interleave and corrupt the file. Previously every tool call could fire its
+     * own independent fs.writeFile of the same path.
+     */
+    async writeConfigToDisk() {
+        await fs.writeFile(this.configPath, JSON.stringify(this.config, null, 2), 'utf8');
+    }
+    /**
+     * Awaitable save, serialized on writeChain. Use for explicit, user-driven
+     * config changes where the caller wants on-disk confirmation.
      */
     async saveConfig() {
-        try {
-            await fs.writeFile(this.configPath, JSON.stringify(this.config, null, 2), 'utf8');
-        }
-        catch (error) {
-            console.error('Failed to save config:', error);
-            throw error;
-        }
+        const write = this.writeChain.then(() => this.writeConfigToDisk());
+        // Keep the chain alive even if this write rejects, so later writes still run.
+        this.writeChain = write.catch(() => { });
+        return write;
+    }
+    /**
+     * Non-blocking, coalesced save. Returns immediately; the write runs in the
+     * background. A burst of calls collapses to at most one queued write behind
+     * the in-flight one, so a storm of tool calls can't storm the disk — and,
+     * critically, can't pile up behind a saturated libuv threadpool and gate the
+     * tool-call response path. Used for high-frequency, non-critical persistence
+     * such as usage stats.
+     */
+    scheduleSave() {
+        if (this.saveScheduled)
+            return; // a queued write will capture the latest config
+        this.saveScheduled = true;
+        this.writeChain = this.writeChain.then(async () => {
+            this.saveScheduled = false; // let the next burst queue a fresh write
+            try {
+                await this.writeConfigToDisk();
+            }
+            catch (error) {
+                console.error('Failed to save config (background):', error);
+            }
+        });
     }
     /**
      * Get the entire config
@@ -194,6 +227,20 @@ class ConfigManager {
         this.config[key] = value;
         await this.saveConfig();
     }
+    /**
+     * Update a value in memory and persist it WITHOUT blocking the caller.
+     * The tool-call response path must never wait on a disk write: when the libuv
+     * threadpool is saturated (e.g. many parallel reads stalled on a slow/cloud
+     * filesystem) an awaited write can't get a thread and would hang the response
+     * of even pure-memory tools. The in-memory value is updated synchronously so
+     * subsequent reads see it immediately; the write is coalesced in the
+     * background. Callers needing on-disk confirmation should use setValue.
+     */
+    async setValueNonBlocking(key, value) {
+        await this.init();
+        this.config[key] = value;
+        this.scheduleSave();
+    }
     /**
      * Update multiple configuration values at once
      */

package/dist/handlers/filesystem-handlers.js

@@ -41,7 +41,12 @@ function getErrorFromPath(path) {
  * Handle read_file command
  */
 export async function handleReadFile(args) {
-    const HANDLER_TIMEOUT = 60000; // 60 seconds total operation timeout
+    // Backstop for the whole handler operation. The real control is the
+    // 3-minute cancellable read timeout inside readFileFromDisk; this sits just
+    // above it (so that one fires first, with cleanup + a useful error) but
+    // still below the MCP client's ~4-minute hard cap, so we never leave the
+    // client hanging on an opaque timeout.
+    const HANDLER_TIMEOUT = 3.5 * 60 * 1000; // 3m30s
     // Add input validation
     if (args === null || args === undefined) {
         return createErrorResponse('No arguments provided for read_file command');
@@ -95,28 +100,47 @@ export async function handleReadFile(args) {
                     },
                     ...pdfContent
                 ],
-                structuredContent: {
-                    fileName: path.basename(resolvedFilePath),
-                    filePath: resolvedFilePath,
-                    fileType: 'unsupported',
-                    sourceTool: 'read_file',
-                    ...await getDefaultEditorMetadata(resolvedFilePath),
-                    content: pdfContent
-                        .filter((item) => item.type === "text")
-                        .map((item) => item.text)
-                        .join("\n"),
-                },
+                ...(parsed.origin === 'ui' ? {
+                    structuredContent: {
+                        fileName: path.basename(resolvedFilePath),
+                        filePath: resolvedFilePath,
+                        fileType: 'unsupported',
+                        ...await getDefaultEditorMetadata(resolvedFilePath),
+                    },
+                } : {}),
             };
         }
         // Handle image files
         if (fileResult.metadata?.isImage) {
             // Return the image bytes in the MCP content array so the host model can
-            // actually see the image. structuredContent additionally carries the bytes
-            // for the preview widget to render.
+            // actually see the image. The preview widget gets its copy from its own
+            // origin:'ui' read — structuredContent stays metadata-only.
             const imageData = typeof fileResult.content === 'string'
                 ? fileResult.content
                 : fileResult.content.toString('base64');
             const imageSummary = `Image file: ${parsed.path} (${fileResult.mimeType})\n`;
+            const imageStructuredContent = {
+                fileName: path.basename(resolvedFilePath),
+                filePath: resolvedFilePath,
+                fileType: 'image',
+                ...await getDefaultEditorMetadata(resolvedFilePath),
+                mimeType: fileResult.mimeType,
+            };
+            // Widget pull (origin: 'ui'): return the base64 in a TEXT block, never
+            // an image block. An image content block makes the host inline-vision-
+            // render the result, which preempts delivery of this RPC response to
+            // the widget — leaving the preview stuck on "Preparing preview…" for
+            // exactly the host-rendered types (png/jpeg/gif/webp). Text-only lets
+            // the RPC response through so the widget can draw the <img>.
+            if (parsed.origin === 'ui') {
+                return {
+                    content: [{ type: "text", text: imageData }],
+                    structuredContent: imageStructuredContent,
+                };
+            }
+            // Model-facing read: keep the image block so the host/model sees it.
+            // No structuredContent — the widget renders from its own origin:'ui'
+            // read, and nothing else consumes it.
             return {
                 content: [
                     {
@@ -129,36 +153,32 @@ export async function handleReadFile(args) {
                         mimeType: fileResult.mimeType
                     }
                 ],
-                structuredContent: {
-                    fileName: path.basename(resolvedFilePath),
-                    filePath: resolvedFilePath,
-                    fileType: 'image',
-                    sourceTool: 'read_file',
-                    ...await getDefaultEditorMetadata(resolvedFilePath),
-                    content: imageData,
-                    imageData,
-                    mimeType: fileResult.mimeType
-                }
             };
         }
         else {
             // For all other files, return as text.
             // structuredContent carries only file metadata (no content duplication);
-            // the widget reads text from the MCP content array.
-            const textContent = typeof fileResult.content === 'string'
+            // the widget reads text from the MCP content array (over the RPC read).
+            let textContent = typeof fileResult.content === 'string'
                 ? fileResult.content
                 : fileResult.content.toString('utf8');
             const fileType = fileResult.metadata?.isDirectory ? 'directory' : resolvePreviewFileType(resolvedFilePath);
+            // The directory fallback prefixes a "use list_directory instead" hint
+            // for the LLM. The widget's own read (a list_directory preview pulls
+            // read_file on the dir path) would render that hint as a notice — strip it.
+            if (parsed.origin === 'ui' && fileType === 'directory') {
+                textContent = textContent.replace(/^This is a directory, not a file\.[^\n]*\n+/, '');
+            }
             return {
                 content: [{ type: "text", text: textContent }],
-                structuredContent: {
-                    fileName: path.basename(resolvedFilePath),
-                    filePath: resolvedFilePath,
-                    fileType,
-                    sourceTool: 'read_file',
-                    ...await getDefaultEditorMetadata(resolvedFilePath),
-                    content: textContent,
-                },
+                ...(parsed.origin === 'ui' ? {
+                    structuredContent: {
+                        fileName: path.basename(resolvedFilePath),
+                        filePath: resolvedFilePath,
+                        fileType,
+                        ...await getDefaultEditorMetadata(resolvedFilePath),
+                    },
+                } : {}),
             };
         }
     };
@@ -237,7 +257,30 @@ export async function handleReadMultipleFiles(args) {
  */
 export async function handleWriteFile(args) {
     try {
+        const modeProvided = !!(args && typeof args === 'object' && 'mode' in args);
         const parsed = WriteFileArgsSchema.parse(args);
+        // An omitted `mode` falls back to 'rewrite', which silently destroys
+        // the target's existing content. The common failure is an LLM caller
+        // intending to append but dropping the optional param (issue #541), so
+        // require explicit intent when the target already has content;
+        // new/empty files keep the zero-friction default.
+        if (!modeProvided) {
+            let existing = null;
+            try {
+                existing = await getFileInfo(parsed.path);
+            }
+            catch {
+                // Missing file or invalid path — nothing to protect; the write
+                // itself will surface any real path error.
+            }
+            if (existing?.isFile && existing.size > 0) {
+                return createErrorResponse(`Write rejected to prevent accidental data loss: ${parsed.path} already exists ` +
+                    `with content (${existing.size} bytes), and no 'mode' was specified — the default ` +
+                    `mode 'rewrite' would REPLACE the entire file. Retry with an explicit mode: ` +
+                    `'append' to add your content to the end of the existing file, or 'rewrite' ` +
+                    `to replace all existing content.`);
+            }
+        }
         // Get the line limit from configuration
         const config = await configManager.getConfig();
         const MAX_LINES = config.fileWriteLineLimit ?? 50; // Default to 50 if not set
@@ -254,19 +297,13 @@ export async function handleWriteFile(args) {
         await writeFile(parsed.path, parsed.content, parsed.mode);
         // Provide more informative message based on mode
         const modeMessage = parsed.mode === 'append' ? 'appended to' : 'wrote to';
-        const resolvedWritePath = resolveAbsolutePath(parsed.path);
+        // No structuredContent: nothing in the UI calls write_file (the widget
+        // previews the write via its own read_file pull at tool-result time).
         return {
             content: [{
                     type: "text",
                     text: `Successfully ${modeMessage} ${parsed.path} (${lineCount} lines) ${errorMessage}`
                 }],
-            structuredContent: {
-                fileName: path.basename(resolvedWritePath),
-                filePath: resolvedWritePath,
-                fileType: resolvePreviewFileType(resolvedWritePath),
-                sourceTool: 'write_file',
-                ...await getDefaultEditorMetadata(resolvedWritePath),
-            },
         };
     }
     catch (error) {
@@ -303,16 +340,13 @@ export async function handleListDirectory(args) {
         const resolvedPath = resolveAbsolutePath(parsed.path);
         return {
             content: [{ type: "text", text: resultText }],
-            structuredContent: {
-                fileName: path.basename(resolvedPath),
-                filePath: resolvedPath,
-                fileType: 'directory',
-                sourceTool: 'list_directory',
-                // Carry the listing in structuredContent too. Chat reads the text
-                // content array, but structuredContent-only consumers (e.g. Cowork)
-                // render from here and would otherwise show an empty directory.
-                content: resultText,
-            },
+            ...(parsed.origin === 'ui' ? {
+                structuredContent: {
+                    fileName: path.basename(resolvedPath),
+                    filePath: resolvedPath,
+                    fileType: 'directory',
+                },
+            } : {}),
         };
     }
     catch (error) {

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 #!/usr/bin/env node
-export {};
+import './bootstrap.js';

package/dist/index.js

@@ -1,4 +1,7 @@
 #!/usr/bin/env node
+// MUST be first: raises the libuv threadpool size before any fs work is
+// submitted. See src/bootstrap.ts for why import order matters.
+import './bootstrap.js';
 import { FilteredStdioServerTransport } from './custom-stdio.js';
 import { server, flushDeferredMessages } from './server.js';
 import { configManager } from './config-manager.js';

package/dist/remote-device/desktop-commander-integration.js

@@ -2,7 +2,7 @@ import { spawn } from 'child_process';
 import path from 'path';
 import fs from 'fs/promises';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
-import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { fileURLToPath } from 'url';
 import { captureRemote } from '../utils/capture.js';
 const __filename = fileURLToPath(import.meta.url);
@@ -24,7 +24,13 @@ export class DesktopCommanderIntegration {
         console.debug('[DEBUG] MCP config:', JSON.stringify(config, null, 2));
         try {
             console.debug('[DEBUG] Creating StdioClientTransport');
-            this.mcpTransport = new StdioClientTransport(config);
+            // DC_REMOTE_DEVICE tells the spawned server it is serving remote
+            // services, so it suppresses local-only behavior like opening the
+            // welcome page in a browser the remote user would never see.
+            this.mcpTransport = new StdioClientTransport({
+                ...config,
+                env: { ...getDefaultEnvironment(), ...config.env, DC_REMOTE_DEVICE: 'true' }
+            });
             // Create MCP client
             console.debug('[DEBUG] Creating MCP Client');
             this.mcpClient = new Client({

package/dist/remote-device/remote-channel.d.ts

@@ -20,6 +20,9 @@ export declare class RemoteChannel {
     private onToolCall;
     private lastDeviceStatus;
     private lastChannelState;
+    private reconnectAttempt;
+    private isRecreatingChannel;
+    private joiningSince;
     private _user;
     get user(): User | null;
     initialize(url: string, key: string): void;
@@ -50,10 +53,22 @@ export declare class RemoteChannel {
      * This is used for both initial subscription and recreation after socket reconnects.
      */
     private createChannel;
+    /**
+     * Compact connection state for logs — e.g. "socket=open(1) ch=errored attempt=3".
+     * readyState 1=OPEN (a 1 while joins keep failing = a half-open socket being reused),
+     * 3=CLOSED, '-'=no socket. Reads realtime-js internals defensively; never throws.
+     */
+    private connState;
     /**
      * Check if channel is connected, recreate if not.
      */
     private checkConnectionHealth;
+    /**
+     * Run an async op but reject if it doesn't settle within `ms`, so a hung await
+     * can't leave isRecreatingChannel stuck true and disable the watchdog. Mirrors
+     * closeWithTimeout() in desktop-commander-integration.ts.
+     */
+    private withTimeout;
     /**
      * Recreate the channel by destroying old one and creating fresh instance.
      */