@hcu-lab.me/mcp-device 1.0.5 → 1.0.7

package/dist/device/execution-engine.js

@@ -1,135 +1,116 @@
-import { spawn } from 'child_process';
+import { randomUUID } from 'crypto';
 import path from 'path';
 import fs from 'fs/promises';
 import { Client } from '@modelcontextprotocol/sdk/client/index.js';
 import { StdioClientTransport, getDefaultEnvironment } from '@modelcontextprotocol/sdk/client/stdio.js';
 import { fileURLToPath } from 'url';
 import { captureRemote } from '../utils/capture.js';
+import { deviceStatePaths } from './device-state.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-export class DesktopCommanderIntegration {
+export class LocalExecutionEngine {
     constructor() {
         this.mcpClient = null;
         this.mcpTransport = null;
         this.isReady = false;
+        this.runtimeReason = 'LOCAL_EXECUTION_ENGINE_UNAVAILABLE';
+        this.runtimeGeneration = null;
+    }
+    markUnavailable(client) {
+        if (client && this.mcpClient !== client)
+            return;
+        this.isReady = false;
+        this.runtimeReason = 'LOCAL_EXECUTION_ENGINE_UNAVAILABLE';
+        this.runtimeGeneration = null;
     }
     async initialize() {
-        console.debug('[DEBUG] DesktopCommanderIntegration.initialize() called');
-        const config = await this.resolveMcpConfig();
-        if (!config) {
-            console.debug('[DEBUG] No MCP config found');
-            throw new Error('Desktop Commander MCP not found. Please install it globally via `npm install -g @wonderwhy-er/desktop-commander` or build the local project.');
-        }
-        console.log(` - ⏳ Connecting to Local Desktop Commander MCP using: ${config.command} ${config.args.join(' ')}`);
-        console.debug('[DEBUG] MCP config:', JSON.stringify(config, null, 2));
+        console.debug('[DEBUG] LocalExecutionEngine.initialize() called');
+        this.markUnavailable();
         try {
-            console.debug('[DEBUG] Creating StdioClientTransport');
-            // MCP_DEVICE_REMOTE 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({
+            const config = await this.resolveMcpConfig();
+            if (!config)
+                throw new Error('Bundled local execution engine is unavailable. Reinstall MCP Device.');
+            const transport = new StdioClientTransport({
                 ...config,
                 env: {
                     ...getDefaultEnvironment(),
                     ...config.env,
-                    MCP_DEVICE_REMOTE: 'true',
-                    DESKTOP_COMMANDER_DISABLE_TELEMETRY: 'true'
+                    MCP_DEVICE_REMOTE: 'true'
                 }
             });
-            // Create MCP client
-            console.debug('[DEBUG] Creating MCP Client');
-            this.mcpClient = new Client({
-                name: "desktop-commander-client",
-                version: "1.0.0"
-            }, {
-                capabilities: {}
-            });
-            // Connect to Desktop Commander
-            console.debug('[DEBUG] Connecting MCP client to transport');
-            await this.mcpClient.connect(this.mcpTransport);
+            const client = new Client({ name: 'mcp-device-local-engine', version: '1.0.0' }, { capabilities: {} });
+            this.mcpTransport = transport;
+            this.mcpClient = client;
+            client.onclose = () => this.markUnavailable(client);
+            await client.connect(transport);
+            if (this.mcpClient !== client || this.mcpTransport !== transport || transport.pid === null) {
+                throw new Error('Local execution engine closed during startup.');
+            }
+            this.runtimeGeneration = randomUUID();
             this.isReady = true;
-            console.log(' - 🔌 Connected to Desktop Commander MCP');
-            console.debug('[DEBUG] Desktop Commander MCP connection successful');
+            this.runtimeReason = null;
+            console.log(' - Local execution engine ready');
         }
         catch (error) {
-            console.error(' - ❌ Failed to connect to Desktop Commander MCP:', error);
-            console.debug('[DEBUG] MCP connection error:', error);
-            await captureRemote('desktop_integration_init_failed', { error });
-            throw error;
+            console.error(' - Failed to start local execution engine:', error);
+            await captureRemote('local_engine_init_failed', { error });
+            try {
+                await this.mcpClient?.close();
+            }
+            catch { }
+            try {
+                await this.mcpTransport?.close();
+            }
+            catch { }
+            this.mcpClient = null;
+            this.mcpTransport = null;
+            this.markUnavailable();
         }
     }
     async resolveMcpConfig() {
-        console.debug('[DEBUG] Resolving MCP config...');
-        // Option 1: Development/Local Build
-        // Adjusting path resolution since we are now in src/device and dist is in root/dist
-        // Original: path.resolve(__dirname, '../../dist/index.js')
-        const devPath = path.resolve(__dirname, '../../dist/index.js');
-        console.debug('[DEBUG] Checking local dev path:', devPath);
+        const localEngine = path.resolve(__dirname, '../../dist/index.js');
         try {
-            await fs.access(devPath);
-            console.debug(' - 🔍 Found local MCP server at:', devPath);
-            return {
-                command: process.execPath, // Use the current node executable
-                args: [devPath],
-                cwd: path.dirname(devPath)
-            };
+            await fs.access(localEngine);
         }
         catch {
-            console.debug('[DEBUG] Local dev path not found, trying global installation');
-            // Local file not found, continue...
+            return null;
         }
-        // Option 2: Global Installation
-        const commandName = 'desktop-commander';
-        console.debug('[DEBUG] Checking for global command:', commandName);
-        try {
-            await new Promise((resolve, reject) => {
-                // Use platform-appropriate command to check if the command exists in PATH
-                // We can't run it directly as it's an stdio MCP server that waits for input
-                const whichCommand = process.platform === 'win32' ? 'where' : 'which';
-                console.debug('[DEBUG] Using platform command:', whichCommand, 'on platform:', process.platform);
-                const check = spawn(whichCommand, [commandName], { windowsHide: true }); // Prevent visible console windows on Windows
-                check.on('error', (err) => {
-                    console.debug('[DEBUG] Spawn error for', whichCommand, ':', err.message);
-                    reject(err);
-                });
-                check.on('close', (code) => {
-                    console.debug('[DEBUG]', whichCommand, 'exited with code:', code);
-                    return code === 0 ? resolve() : reject(new Error('Command not found'));
-                });
-            });
-            console.debug(' - Found global desktop-commander CLI');
-            return {
-                command: commandName,
-                args: []
-            };
-        }
-        catch (err) {
-            console.debug('[DEBUG] Global command not found:', err);
-            // Global command not found
-        }
-        console.debug('[DEBUG] No MCP config resolved');
-        return null;
+        const runtimeDir = deviceStatePaths().runtime;
+        await fs.mkdir(runtimeDir, { recursive: true, mode: 0o700 });
+        return {
+            command: process.execPath,
+            args: [localEngine],
+            cwd: runtimeDir
+        };
+    }
+    getChildPid() {
+        return this.mcpTransport?.pid ?? null;
+    }
+    getRuntimeState() {
+        return {
+            runtime_ready: this.isReady,
+            runtime_reason: this.isReady ? null : this.runtimeReason,
+            execution_runtime_generation: this.isReady ? this.runtimeGeneration : null
+        };
+    }
+    assertReady() {
+        if (this.isReady && this.mcpClient)
+            return;
+        const error = new Error('Local execution engine is unavailable.');
+        error.code = 'DEVICE_NOT_READY';
+        throw error;
     }
     async callClientTool(toolName, args, metadata) {
-        if (!this.isReady || !this.mcpClient) {
-            console.debug('[DEBUG] callClientTool() failed - not ready or no client');
-            throw new Error('DesktopIntegration not initialized');
-        }
-        // Proxy other tools to MCP server
+        this.assertReady();
         try {
-            console.debug('[DEBUG] Calling MCP tool:', toolName, 'args:', JSON.stringify(args).substring(0, 100));
-            const result = await this.mcpClient.callTool({
+            return await this.mcpClient.callTool({
                 name: toolName,
                 arguments: args,
                 _meta: { remote: true, ...metadata || {} }
             });
-            console.debug('[DEBUG] Tool call successful:', toolName);
-            return result;
         }
         catch (error) {
-            console.error(`Error executing tool ${toolName}:`, error);
-            console.debug('[DEBUG] Tool call error details:', error);
-            await captureRemote('desktop_integration_tool_call_failed', { error, toolName });
+            await captureRemote('local_engine_tool_call_failed', { error, toolName });
             throw error;
         }
     }
@@ -137,59 +118,37 @@ export class DesktopCommanderIntegration {
         if (!this.mcpClient)
             return { tools: [] };
         try {
-            // List tools from MCP server
             const mcpTools = await this.mcpClient.listTools();
-            // Merge tools
-            return {
-                tools: mcpTools.tools || []
-            };
+            return { tools: mcpTools.tools || [] };
         }
         catch (error) {
-            console.error('Error fetching capabilities:', error);
-            await captureRemote('desktop_integration_list_tools_failed', { error });
-            // Fallback to local tools
-            return {
-                tools: []
-            };
+            await captureRemote('local_engine_list_tools_failed', { error });
+            return { tools: [] };
         }
     }
     async shutdown() {
-        console.debug('[DEBUG] DesktopCommanderIntegration.shutdown() called');
-        const closeWithTimeout = async (operation, name, timeoutMs = 3000) => {
-            return Promise.race([
-                operation(),
-                new Promise((_, reject) => setTimeout(() => reject(new Error(`${name} timeout after ${timeoutMs}ms`)), timeoutMs))
-            ]);
-        };
+        const closeWithTimeout = async (operation, name, timeoutMs = 3000) => Promise.race([
+            operation(),
+            new Promise((_, reject) => setTimeout(() => reject(new Error(`${name} timeout after ${timeoutMs}ms`)), timeoutMs))
+        ]);
         if (this.mcpClient) {
             try {
-                console.log('  → Closing MCP client...');
-                console.debug('[DEBUG] Calling mcpClient.close() with timeout');
                 await closeWithTimeout(() => this.mcpClient.close(), 'MCP client close');
-                console.log('  ✓ MCP client closed');
             }
-            catch (e) {
-                console.warn('  ⚠️  MCP client close timeout or error:', e.message);
-                console.debug('[DEBUG] MCP client close error:', e);
-                await captureRemote('desktop_integration_shutdown_error', { error: e, component: 'client' });
+            catch (error) {
+                await captureRemote('local_engine_shutdown_error', { error, component: 'client' });
             }
             this.mcpClient = null;
         }
         if (this.mcpTransport) {
             try {
-                console.log('  → Closing MCP transport...');
-                console.debug('[DEBUG] Calling mcpTransport.close() with timeout');
                 await closeWithTimeout(() => this.mcpTransport.close(), 'MCP transport close');
-                console.log('  ✓ MCP transport closed');
             }
-            catch (e) {
-                console.warn('  ⚠️  MCP transport close timeout or error:', e.message);
-                console.debug('[DEBUG] MCP transport close error:', e);
-                await captureRemote('desktop_integration_shutdown_error', { error: e, component: 'transport' });
+            catch (error) {
+                await captureRemote('local_engine_shutdown_error', { error, component: 'transport' });
             }
             this.mcpTransport = null;
         }
-        this.isReady = false;
-        console.debug('[DEBUG] Desktop Commander integration shutdown complete');
+        this.markUnavailable();
     }
 }

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

@@ -1,6 +1,10 @@
 import type { Agent } from 'http';
 import { GatewayDeviceIdentity } from './gateway-identity.js';
 import { GatewayToolAdapter } from './gateway-tool-adapter.js';
+export type GatewayUpdateRequestOutcome = {
+    mode: 'detached';
+    handoff: () => Promise<void>;
+};
 export interface GatewayChannelOptions {
     gatewayUrl: string;
     enrollmentToken?: string;
@@ -10,9 +14,16 @@ export interface GatewayChannelOptions {
     securityProtocolFloor?: number;
     appCaPem?: string;
     adapter: GatewayToolAdapter;
+    runtimeState?: () => {
+        runtime_ready: boolean;
+        runtime_reason: string | null;
+        execution_runtime_generation: string | null;
+    };
     agentVersion?: string;
     onStatus?: (payload: any) => void | Promise<void>;
-    onUpdateRequest?: (targetVersion: string) => void | Promise<void>;
+    onUpdateRequest?: (targetVersion: string, context: {
+        requestId: string;
+    }) => GatewayUpdateRequestOutcome | Promise<GatewayUpdateRequestOutcome>;
 }
 export declare class GatewayDeviceChannel {
     private options;
@@ -32,7 +43,9 @@ export declare class GatewayDeviceChannel {
     private protocolVersion;
     private secureSocket?;
     private authMode;
+    private updateInFlight?;
     constructor(options: GatewayChannelOptions);
+    private runtimePayload;
     start(): Promise<void>;
     private startV2Transport;
     stop(): Promise<void>;
@@ -40,11 +53,16 @@ export declare class GatewayDeviceChannel {
     private sendHelloV2;
     private handleMessage;
     logoutAccount(timeoutMs?: number): Promise<any>;
+    private updateStatusMessage;
+    private sendUpdateStatus;
+    private sendUpdateStatusFlushed;
+    reportUpdateFailure(requestId: string, targetVersion: string, code: string, message: string): Promise<void>;
     private handleUpdateRequest;
     private handleToolCall;
     private scheduleReconnect;
     private startHeartbeat;
     private stopHeartbeat;
     private send;
+    private sendFlushed;
     private fail;
 }

package/dist/device/gateway-channel.js

@@ -19,6 +19,19 @@ export class GatewayDeviceChannel {
         this.authMode = 'reconnect';
         this.identity = options.identity || new GatewayDeviceIdentity();
     }
+    runtimePayload() {
+        if (!this.options.runtimeState)
+            return {};
+        const state = this.options.runtimeState();
+        const ready = state?.runtime_ready === true;
+        const reason = ready ? null : String(state?.runtime_reason || 'LOCAL_EXECUTION_ENGINE_UNAVAILABLE').slice(0, 96);
+        const generation = String(state?.execution_runtime_generation || '').trim().slice(0, 128) || null;
+        return {
+            runtime_ready: ready,
+            runtime_reason: reason,
+            execution_runtime_generation: generation
+        };
+    }
     async start() {
         this.authenticatedDeviceId = undefined;
         this.connectionEpoch = undefined;
@@ -55,10 +68,15 @@ export class GatewayDeviceChannel {
         socket.once('error', error => this.fail(error));
         socket.once('close', (code, reason) => {
             this.stopHeartbeat();
+            const reasonText = reason.toString();
+            const forgotten = code === 4003 && /(?:unknown or revoked device|revoked device|device revoked)/i.test(reasonText);
+            const error = new Error(`Gateway connection closed (${code}): ${reasonText}`);
+            if (forgotten)
+                error.code = 'DEVICE_FORGOTTEN';
             if (!this.shuttingDown && this.readyReject) {
-                this.fail(new Error(`Gateway connection closed (${code}): ${reason.toString()}`));
+                this.fail(error);
             }
-            else if (!this.shuttingDown) {
+            else if (!this.shuttingDown && !forgotten) {
                 this.scheduleReconnect();
             }
         });
@@ -145,6 +163,7 @@ export class GatewayDeviceChannel {
                 arch: process.arch,
                 path_style: process.platform === 'win32' ? 'windows' : 'posix',
                 capabilities: [...GATEWAY_CAPABILITIES],
+                ...this.runtimePayload(),
                 ...(enrolling || pairing ? { public_key_pem: record.publicKeyPem } : {})
             }
         });
@@ -168,6 +187,7 @@ export class GatewayDeviceChannel {
                 arch: process.arch,
                 path_style: process.platform === 'win32' ? 'windows' : 'posix',
                 capabilities: [...GATEWAY_CAPABILITIES],
+                ...this.runtimePayload(),
                 ...(pairing || enrolling ? { public_key_pem: record.publicKeyPem, enrollment_grant: grant } : {})
             }
         });
@@ -297,40 +317,83 @@ export class GatewayDeviceChannel {
             clearTimeout(timer);
         }
     }
+    updateStatusMessage(requestId, targetVersion, state, extra = {}) {
+        if (this.connectionEpoch === undefined || !this.authenticatedDeviceId) {
+            throw new Error('Gateway update status cannot be sent before authentication.');
+        }
+        return {
+            protocol_version: this.protocolVersion,
+            type: 'device_update_status',
+            request_id: requestId,
+            device_id: this.authenticatedDeviceId,
+            connection_epoch: this.connectionEpoch,
+            timestamp: Date.now(),
+            payload: { state, target_version: targetVersion, package_version: VERSION, ...extra }
+        };
+    }
+    sendUpdateStatus(requestId, targetVersion, state, extra = {}) {
+        try {
+            this.send(this.updateStatusMessage(requestId, targetVersion, state, extra));
+        }
+        catch {
+            // Best-effort path used only when the socket may already be closing.
+        }
+    }
+    async sendUpdateStatusFlushed(requestId, targetVersion, state, extra = {}) {
+        await this.sendFlushed(this.updateStatusMessage(requestId, targetVersion, state, extra));
+    }
+    async reportUpdateFailure(requestId, targetVersion, code, message) {
+        // Failed update state is retired only after this awaited send succeeds.
+        await this.sendUpdateStatusFlushed(requestId, targetVersion, 'failed', {
+            code: String(code || 'DEVICE_UPDATE_FAILED').slice(0, 64),
+            message: String(message || 'Device update failed.').slice(0, 240)
+        });
+    }
     async handleUpdateRequest(message) {
         if (this.connectionEpoch === undefined || !this.authenticatedDeviceId)
             return;
         const requestId = String(message.request_id || '').trim();
         const targetVersion = String(message.payload?.target_version || '').trim();
-        const sendStatus = (state, extra = {}) => {
-            try {
-                this.send({
-                    protocol_version: this.protocolVersion,
-                    type: 'device_update_status',
-                    request_id: requestId,
-                    device_id: this.authenticatedDeviceId,
-                    connection_epoch: this.connectionEpoch,
-                    timestamp: Date.now(),
-                    payload: { state, target_version: targetVersion, package_version: VERSION, ...extra }
+        if (!requestId || !/^\d+\.\d+\.\d+$/.test(targetVersion) || typeof this.options.onUpdateRequest !== 'function') {
+            this.sendUpdateStatus(requestId, targetVersion, 'failed', {
+                code: 'DEVICE_UPDATE_UNSUPPORTED',
+                message: 'Device update request is unsupported or invalid.'
+            });
+            return;
+        }
+        if (this.updateInFlight) {
+            if (this.updateInFlight !== requestId) {
+                this.sendUpdateStatus(requestId, targetVersion, 'failed', {
+                    code: 'DEVICE_UPDATE_IN_PROGRESS',
+                    message: 'Another MCP Device update is already in progress.'
                 });
             }
-            catch { /* reconnect state will make the final version authoritative */ }
-        };
-        if (!requestId || !/^\d+\.\d+\.\d+$/.test(targetVersion) || typeof this.options.onUpdateRequest !== 'function') {
-            sendStatus('failed', { code: 'DEVICE_UPDATE_UNSUPPORTED', message: 'Device update request is unsupported or invalid.' });
             return;
         }
-        sendStatus('accepted');
+        this.updateInFlight = requestId;
         try {
-            await this.options.onUpdateRequest(targetVersion);
-            sendStatus('installed');
+            // Pre-stage and verify the target before acknowledging the update.
+            // If this throws, the currently running device stays healthy.
+            const outcome = await this.options.onUpdateRequest(targetVersion, { requestId });
+            if (!outcome || outcome.mode !== 'detached') {
+                throw Object.assign(new Error('Device update handler did not provide a detached handoff.'), { code: 'DEVICE_UPDATE_INVALID_HANDOFF' });
+            }
+            // Do not tear down the socket until the gateway has accepted
+            // the frame into the transport write path.
+            await this.sendUpdateStatusFlushed(requestId, targetVersion, 'accepted');
+            await outcome.handoff();
+            return;
         }
         catch (error) {
-            sendStatus('failed', {
+            this.sendUpdateStatus(requestId, targetVersion, 'failed', {
                 code: String(error?.code || 'DEVICE_UPDATE_FAILED').slice(0, 64),
                 message: String(error?.message || error).slice(0, 240)
             });
         }
+        finally {
+            if (this.updateInFlight === requestId)
+                this.updateInFlight = undefined;
+        }
     }
     async handleToolCall(message) {
         if (this.connectionEpoch === undefined || !this.authenticatedDeviceId)
@@ -384,7 +447,7 @@ export class GatewayDeviceChannel {
                 type: 'heartbeat',
                 device_id: record.deviceId,
                 timestamp: Date.now(),
-                payload: {}
+                payload: this.runtimePayload()
             });
         }, HEARTBEAT_MS);
         this.heartbeat.unref?.();
@@ -411,6 +474,29 @@ export class GatewayDeviceChannel {
         }
         this.socket.send(encoded);
     }
+    async sendFlushed(message) {
+        if (!this.socket || this.socket.readyState !== WebSocket.OPEN)
+            throw new Error('Gateway socket is not open');
+        const encoded = JSON.stringify(message);
+        if (Buffer.byteLength(encoded, 'utf8') > MAX_OUTBOUND_MESSAGE_BYTES) {
+            const error = new Error('Gateway device response exceeds the outbound message limit');
+            error.code = 'DEVICE_OUTPUT_TOO_LARGE';
+            throw error;
+        }
+        if (this.protocolVersion === PROTOCOL_VERSION_V2) {
+            if (!this.secureSocket || this.secureSocket.destroyed)
+                throw new Error('Gateway v2 inner TLS socket is not open');
+            const secureSocket = this.secureSocket;
+            await new Promise((resolve, reject) => {
+                secureSocket.write(encodeJsonFrame(message), error => error ? reject(error) : resolve());
+            });
+            return;
+        }
+        const socket = this.socket;
+        await new Promise((resolve, reject) => {
+            socket.send(encoded, error => error ? reject(error) : resolve());
+        });
+    }
     fail(error) {
         const reject = this.readyReject;
         this.readyResolve = undefined;

package/dist/device/gateway-identity.d.ts

@@ -13,6 +13,7 @@ export declare class GatewayDeviceIdentity {
     });
     loadOrCreate(): Promise<GatewayIdentityRecord>;
     markEnrolled(): Promise<void>;
+    forget(): Promise<void>;
     signChallenge(nonce: string): Promise<string>;
     signChallengeV2(options: {
         mode: 'reconnect' | 'enroll' | 'pair';

package/dist/device/gateway-identity.js

@@ -82,6 +82,10 @@ export class GatewayDeviceIdentity {
         this.record = { ...current, enrolled: true };
         await this.persist();
     }
+    async forget() {
+        this.record = undefined;
+        await fs.rm(this.identityPath, { force: true });
+    }
     async signChallenge(nonce) {
         const current = await this.loadOrCreate();
         const challenge = Buffer.from(`mcp-device-auth-v1\n${current.deviceId}\n${nonce}`, 'utf8');

package/dist/device/gateway-tool-adapter.d.ts

@@ -1,15 +1,15 @@
-import { DesktopCommanderIntegration } from './execution-engine.js';
+import { LocalExecutionEngine } from './execution-engine.js';
 export declare const GATEWAY_CAPABILITIES: readonly ["read_text_file", "write_file", "edit_file", "shell_execute", "start_process", "read_process_output", "interact_with_process", "terminate_process", "image_preview", "project_inspect"];
 export interface GatewayToolAdapterOptions {
     allowedRoots?: string[];
     pathValidator?: (requestedPath: string) => Promise<string>;
 }
 export declare class GatewayToolAdapter {
-    private desktop;
+    private engine;
     private allowedRoots;
     private pathValidator;
     private canonicalRoots?;
-    constructor(desktop: DesktopCommanderIntegration, options?: GatewayToolAdapterOptions);
+    constructor(engine: LocalExecutionEngine, options?: GatewayToolAdapterOptions);
     private guardPath;
     private imagePreview;
     call(tool: string, args?: any): Promise<any>;