@hcu-lab.me/mcp-device 1.0.9 → 1.0.12

package/dist/device/core.js

@@ -0,0 +1,66 @@
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+function samePath(left, right) {
+    const normalize = (value) => {
+        const resolved = path.resolve(value);
+        return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+    };
+    return normalize(left) === normalize(right);
+}
+/**
+ * The transport-neutral execution owner shared by remote Device and server.
+ *
+ * No account enrollment, socket, self-MCP child, plugin, or Palace is created
+ * here. Authorization belongs to the caller's broker; file/process semantics
+ * remain owned by the existing Device handlers and GatewayToolAdapter.
+ *
+ * Existing native managers are process-scoped. A server must configure its
+ * isolated state root before importing them; silently changing a global root
+ * after import could write to the user's normal Device state.
+ */
+export async function createDeviceCore(options) {
+    if (!options.deviceId || typeof options.deviceId !== 'string' || !options.deviceId.trim()) {
+        throw Object.assign(new Error('Device Core requires a device identity'), { code: 'DEVICE_ID_REQUIRED' });
+    }
+    // This module intentionally has no eager imports of existing Device modules.
+    const { CONFIG_DIR } = await import('../config.js');
+    const stateRoot = path.resolve(options.stateRoot ?? CONFIG_DIR);
+    if (!samePath(stateRoot, CONFIG_DIR)) {
+        throw Object.assign(new Error('Device Core stateRoot must match MCP_DEVICE_CONFIG_DIR set before importing Device modules'), { code: 'CONFIG_ROOT_MISMATCH' });
+    }
+    const [{ GatewayToolAdapter, gatewayCapabilities }, { dispatchToolCall }] = await Promise.all([
+        import('./gateway-tool-adapter.js'),
+        import('../tool-dispatcher.js')
+    ]);
+    const adapter = new GatewayToolAdapter(undefined, {
+        allowedRoots: options.allowedRoots,
+        context: { deviceId: options.deviceId, stateRoot }
+    });
+    const runtimeInstanceId = `direct-in-process:${randomUUID()}`;
+    let closed = false;
+    const assertOpen = () => {
+        if (closed)
+            throw Object.assign(new Error('Device Core is closed'), { code: 'DEVICE_NOT_READY' });
+    };
+    return {
+        deviceId: options.deviceId,
+        stateRoot,
+        runtimeInstanceId,
+        get capabilities() {
+            return closed ? [] : gatewayCapabilities();
+        },
+        async invoke(tool, args = {}) {
+            assertOpen();
+            return adapter.call(tool, args);
+        },
+        async invokeNative(tool, args = {}) {
+            assertOpen();
+            return dispatchToolCall(tool, args, { isRemote: true });
+        },
+        async close() {
+            // The core owns no second runtime or socket. Its host owns process
+            // shutdown; existing native process session retention is unchanged.
+            closed = true;
+        }
+    };
+}

package/dist/device/device.d.ts

@@ -2,15 +2,20 @@
 import { type RuntimeOwnerStatus } from './runtime-owner.js';
 export declare class MCPDevice {
     private isShuttingDown;
+    private shutdownRequest?;
+    private core?;
+    private unsubscribeCapabilities?;
     private executionEngine;
     private gatewayChannel?;
     private gatewayProxyAgent?;
     private runtimeOwner?;
+    private stateLeases;
     constructor();
     private setupShutdownHandlers;
     start(options?: {
         confirmTakeover?: (existing: RuntimeOwnerStatus) => Promise<boolean> | boolean;
     }): Promise<void>;
     shutdown(): Promise<void>;
+    private performShutdown;
 }
 export declare function isModuleEntrypoint(moduleUrl: string, argvEntry?: string, pmExecPath?: string): boolean;

package/dist/device/device.js

@@ -9,8 +9,10 @@ import { GatewayDeviceIdentity } from './gateway-identity.js';
 import { pairGatewayDevice } from './gateway-pairing.js';
 import { bootstrapOfficialGatewayTrust } from './official-trust.js';
 import { GatewayDeviceStatusStore } from './device-status.js';
-import { GatewayToolAdapter } from './gateway-tool-adapter.js';
+import { createPlatformDeviceCore as createDeviceCore } from '../platform/device-runtime.js';
+import { resolveDevicePluginPolicy } from '../platform/plugin-policy.js';
 import { RuntimeOwner, acquireRuntimeOwner } from './runtime-owner.js';
+import { acquireServerLease } from '../platform/runtime-lease.js';
 import { assertDeviceStartupAllowedDuringUpdate, launchDeviceUpdateHelper, prepareDevicePackageUpdate, reconcileDeviceUpdateAfterStart, retireDeviceUpdateState, signalDeviceUpdateHandoff } from './self-update.js';
 import { captureRemote } from '../utils/capture.js';
 import { VERSION } from '../version.js';
@@ -18,43 +20,45 @@ export class MCPDevice {
     constructor() {
         this.isShuttingDown = false;
         this.executionEngine = new LocalExecutionEngine();
+        this.stateLeases = [];
         this.setupShutdownHandlers();
     }
     setupShutdownHandlers() {
         const handleShutdown = async (signal) => {
-            if (this.isShuttingDown) {
-                console.log(`\n${signal} received, but already shutting down...`);
-                process.exit(1);
-                return;
-            }
-            console.log(`\n${signal} received, initiating graceful shutdown...`);
-            const forceExit = setTimeout(() => {
-                console.error('\n⚠️ Graceful shutdown timed out, forcing exit...');
-                process.exit(1);
+            console.log(this.isShuttingDown
+                ? `\n${signal} received, waiting for owned resources to stop...`
+                : `\n${signal} received, initiating graceful shutdown...`);
+            const shutdownWarning = setTimeout(() => {
+                console.error('\n⚠️ Graceful shutdown is still waiting for owned resources; runtime ownership is retained.');
+                process.exitCode = 1;
             }, 5000);
             try {
                 await this.shutdown();
-                clearTimeout(forceExit);
                 process.exit(0);
             }
             catch (error) {
                 console.error('Error during shutdown:', error);
-                await captureRemote('remote_device_shutdown_handler_error', { error });
-                process.exit(1);
+                await captureRemote('remote_device_shutdown_handler_error', { error }).catch(() => { });
+                // Exiting here would make the PID lease stale while a plugin
+                // may still own its files. Keep the owner available for retry.
+                process.exitCode = 1;
+            }
+            finally {
+                clearTimeout(shutdownWarning);
             }
         };
         process.on('SIGINT', () => {
             handleShutdown('SIGINT').catch((error) => {
                 console.error('Fatal error during shutdown:', error);
                 captureRemote('remote_device_shutdown_handler_error', { error, signal: 'SIGINT' }).catch(() => { });
-                process.exit(1);
+                process.exitCode = 1;
             });
         });
         process.on('SIGTERM', () => {
             handleShutdown('SIGTERM').catch((error) => {
                 console.error('Fatal error during shutdown:', error);
                 captureRemote('remote_device_shutdown_handler_error', { error, signal: 'SIGTERM' }).catch(() => { });
-                process.exit(1);
+                process.exitCode = 1;
             });
         });
     }
@@ -73,9 +77,21 @@ export class MCPDevice {
                 : 'foreground';
             this.runtimeOwner = new RuntimeOwner({ mode, onStop: () => this.shutdown() });
             await acquireRuntimeOwner(this.runtimeOwner, { confirmTakeover: options.confirmTakeover });
+            const { CONFIG_DIR } = await import('../config.js');
+            // Child shell/CLI processes must resolve the same Device-only runtime.
+            process.env.MCP_DEVICE_CONFIG_DIR = CONFIG_DIR;
+            const stateRoots = new Map();
+            for (const root of [this.runtimeOwner.paths.root, CONFIG_DIR]) {
+                const absolute = path.resolve(root);
+                stateRoots.set(process.platform === 'win32' ? absolute.toLowerCase() : absolute, absolute);
+            }
+            for (const [, root] of [...stateRoots].sort(([a], [b]) => a.localeCompare(b))) {
+                this.stateLeases.push(await acquireServerLease(root, { allowDeviceOwnerPid: process.pid }));
+            }
             await this.runtimeOwner.bootstrap();
             await bootstrapOfficialGatewayTrust(new GatewayDeviceConfigStore());
-            await this.executionEngine.initialize();
+            // Remote mode uses direct in-process dispatch (tool-dispatcher.ts).
+            // Do not eagerly initialize LocalExecutionEngine, avoiding child dist/index.js process spawn.
             const gatewayStatus = new GatewayDeviceStatusStore();
             const storedGatewayStatus = await gatewayStatus.load();
             const gatewayConfig = await new GatewayDeviceConfigStore().load();
@@ -88,10 +104,16 @@ export class MCPDevice {
             const proxy = createGatewayProxyAgent(gatewayConfig);
             this.gatewayProxyAgent = proxy.agent;
             process.env.MCP_DEVICE_REMOTE = 'true';
-            console.log(`⏳ Connecting directly to MCP Gateway ${gatewayUrl}`);
+            console.log(`⏳ Connecting directly to MCP Device server ${gatewayUrl}`);
             const identity = new GatewayDeviceIdentity();
             const identityRecord = await identity.loadOrCreate();
             this.runtimeOwner.setDeviceId(identityRecord.deviceId);
+            // Local providers start before pairing; local indexing needs no account session.
+            this.core = await createDeviceCore({
+                deviceId: identityRecord.deviceId,
+                allowedRoots: gatewayConfig.allowedRoots,
+                pluginPolicy: resolveDevicePluginPolicy(process.argv)
+            });
             const enrollmentCredential = String(process.env.MCP_GATEWAY_ENROLLMENT_TOKEN || process.env.MCP_DEVICE_ENROLLMENT_TOKEN || '').trim() || undefined;
             let pairingGrant;
             if (!identityRecord.enrolled && !enrollmentCredential) {
@@ -115,9 +137,15 @@ export class MCPDevice {
                 proxyAgent: proxy.agent,
                 securityProtocolFloor: gatewayConfig.securityProtocolFloor,
                 appCaPem: gatewayConfig.appCaPem || undefined,
-                adapter: new GatewayToolAdapter(this.executionEngine, { allowedRoots: gatewayConfig.allowedRoots }),
-                runtimeState: () => this.executionEngine.getRuntimeState(),
-                agentVersion: process.env.npm_package_version,
+                adapter: { call: (tool, args) => this.core.invoke(tool, args) },
+                capabilities: () => this.core?.capabilities ?? [],
+                // In remote direct-dispatch mode, the daemon is ready once the gateway channel & dispatch are established.
+                runtimeState: () => ({
+                    runtime_ready: true,
+                    runtime_reason: null,
+                    execution_runtime_generation: this.core.runtimeInstanceId
+                }),
+                agentVersion: VERSION || process.env.npm_package_version || '1.0.12',
                 onUpdateRequest: async (targetVersion, { requestId }) => {
                     const record = await identity.loadOrCreate();
                     const prepared = await prepareDevicePackageUpdate({
@@ -169,6 +197,9 @@ export class MCPDevice {
                     });
                 }
             });
+            this.unsubscribeCapabilities = this.core.onCapabilitiesChanged?.(() => {
+                this.gatewayChannel?.updateCapabilities();
+            });
             await this.gatewayChannel.start();
             const updateReconciliation = await reconcileDeviceUpdateAfterStart(VERSION);
             if (updateReconciliation.action === 'success') {
@@ -209,32 +240,58 @@ export class MCPDevice {
             process.exit(1);
         }
     }
-    async shutdown() {
-        if (this.isShuttingDown)
-            return;
+    shutdown() {
+        if (this.shutdownRequest)
+            return this.shutdownRequest;
         this.isShuttingDown = true;
+        const request = this.performShutdown();
+        this.shutdownRequest = request;
+        // Concurrent callers share the same outcome. A rejected cleanup keeps
+        // ownership and resources available for a real retry; only success is cached.
+        void request.catch(() => {
+            if (this.shutdownRequest === request)
+                this.shutdownRequest = undefined;
+        });
+        return request;
+    }
+    async performShutdown() {
         console.log('\n🛑 Shutting down device...');
         try {
-            if (this.gatewayChannel) {
-                console.log('  → Closing direct Gateway channel...');
-                await this.gatewayChannel.stop();
-                this.gatewayChannel = undefined;
-            }
-            if (this.gatewayProxyAgent) {
-                this.gatewayProxyAgent.destroy();
-                this.gatewayProxyAgent = undefined;
+            try {
+                this.unsubscribeCapabilities?.();
+                this.unsubscribeCapabilities = undefined;
+                if (this.gatewayChannel) {
+                    console.log('  → Closing direct Gateway channel...');
+                    await this.gatewayChannel.stop();
+                    this.gatewayChannel = undefined;
+                }
+                if (this.gatewayProxyAgent) {
+                    this.gatewayProxyAgent.destroy();
+                    this.gatewayProxyAgent = undefined;
+                }
+                await new GatewayDeviceStatusStore().markOffline().catch(() => { });
             }
-            await new GatewayDeviceStatusStore().markOffline().catch(() => { });
-            await this.executionEngine.shutdown();
-            if (this.runtimeOwner) {
-                await this.runtimeOwner.release().catch(() => { });
-                this.runtimeOwner = undefined;
+            finally {
+                // Release shared state only after the same Core and its plugins
+                // have stopped, including failures partway through startup.
+                await this.core?.close();
+                this.core = undefined;
+                await this.executionEngine.shutdown();
+                while (this.stateLeases.length) {
+                    await this.stateLeases[this.stateLeases.length - 1]();
+                    this.stateLeases.pop();
+                }
+                if (this.runtimeOwner) {
+                    await this.runtimeOwner.release();
+                    this.runtimeOwner = undefined;
+                }
             }
             console.log('✓ Device shutdown complete');
         }
         catch (error) {
             console.error('Shutdown error:', error.message);
-            await captureRemote('remote_device_shutdown_error', { error });
+            await captureRemote('remote_device_shutdown_error', { error }).catch(() => { });
+            throw error;
         }
     }
 }

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

@@ -13,7 +13,9 @@ export interface GatewayChannelOptions {
     proxyAgent?: Agent;
     securityProtocolFloor?: number;
     appCaPem?: string;
-    adapter: GatewayToolAdapter;
+    adapter: Pick<GatewayToolAdapter, 'call'>;
+    /** Healthy current capabilities, including optional extensions. */
+    capabilities?: () => string[];
     runtimeState?: () => {
         runtime_ready: boolean;
         runtime_reason: string | null;
@@ -44,7 +46,12 @@ export declare class GatewayDeviceChannel {
     private secureSocket?;
     private authMode;
     private updateInFlight?;
+    private lastAdvertisedCapabilities?;
     constructor(options: GatewayChannelOptions);
+    private currentCapabilities;
+    private capabilityPayload;
+    /** Uses the existing authenticated v11 capability_sync frame. No reconnect. */
+    updateCapabilities(): boolean;
     private runtimePayload;
     start(): Promise<void>;
     private startV2Transport;

package/dist/device/gateway-channel.js

@@ -2,7 +2,7 @@ import os from 'os';
 import WebSocket from 'ws';
 import { GatewayDeviceIdentity } from './gateway-identity.js';
 import { DEVICE_INNER_TLS_SUBPROTOCOL, createClientInnerTls, createJsonFrameParser, encodeJsonFrame, exportDeviceAuthKeyingMaterial } from './gateway-secure-transport.js';
-import { GATEWAY_CAPABILITIES } from './gateway-tool-adapter.js';
+import { gatewayCapabilities } from './gateway-tool-adapter.js';
 import { gatewaySocketUrl } from './gateway-url-policy.js';
 import { VERSION } from '../version.js';
 const PROTOCOL_VERSION = 1;
@@ -19,6 +19,51 @@ export class GatewayDeviceChannel {
         this.authMode = 'reconnect';
         this.identity = options.identity || new GatewayDeviceIdentity();
     }
+    currentCapabilities() {
+        try {
+            const supplied = this.options.capabilities?.() ?? gatewayCapabilities();
+            return [...new Set(supplied.filter(value => typeof value === 'string' && value.length > 0 && value.length <= 128))];
+        }
+        catch {
+            // Extension metadata must not take ordinary Device execution offline.
+            return gatewayCapabilities();
+        }
+    }
+    capabilityPayload() {
+        const capabilities = this.currentCapabilities();
+        this.lastAdvertisedCapabilities = JSON.stringify(capabilities);
+        return { capabilities, context_version: capabilities.includes('local_status') ? 1 : undefined };
+    }
+    /** Uses the existing authenticated v11 capability_sync frame. No reconnect. */
+    updateCapabilities() {
+        if (!this.authenticatedDeviceId || this.connectionEpoch === undefined ||
+            !this.socket || this.socket.readyState !== WebSocket.OPEN)
+            return false;
+        const capabilities = this.currentCapabilities();
+        const serialized = JSON.stringify(capabilities);
+        if (serialized === this.lastAdvertisedCapabilities)
+            return false;
+        try {
+            this.send({
+                protocol_version: this.protocolVersion,
+                type: 'capability_sync',
+                device_id: this.authenticatedDeviceId,
+                connection_epoch: this.connectionEpoch,
+                timestamp: Date.now(),
+                payload: {
+                    capabilities,
+                    agent_version: this.options.agentVersion || 'mcp-device-1',
+                    package_version: VERSION
+                }
+            });
+            this.lastAdvertisedCapabilities = serialized;
+            return true;
+        }
+        catch {
+            // A reconnect will advertise the current getter in its normal hello.
+            return false;
+        }
+    }
     runtimePayload() {
         if (!this.options.runtimeState)
             return {};
@@ -35,6 +80,7 @@ export class GatewayDeviceChannel {
     async start() {
         this.authenticatedDeviceId = undefined;
         this.connectionEpoch = undefined;
+        this.lastAdvertisedCapabilities = undefined;
         this.messageQueue = Promise.resolve();
         const record = await this.identity.loadOrCreate();
         this.protocolVersion = Number(this.options.securityProtocolFloor || 1) >= 2 ? PROTOCOL_VERSION_V2 : PROTOCOL_VERSION;
@@ -162,7 +208,7 @@ export class GatewayDeviceChannel {
                 platform: process.platform,
                 arch: process.arch,
                 path_style: process.platform === 'win32' ? 'windows' : 'posix',
-                capabilities: [...GATEWAY_CAPABILITIES],
+                ...this.capabilityPayload(),
                 ...this.runtimePayload(),
                 ...(enrolling || pairing ? { public_key_pem: record.publicKeyPem } : {})
             }
@@ -186,7 +232,7 @@ export class GatewayDeviceChannel {
                 platform: process.platform,
                 arch: process.arch,
                 path_style: process.platform === 'win32' ? 'windows' : 'posix',
-                capabilities: [...GATEWAY_CAPABILITIES],
+                ...this.capabilityPayload(),
                 ...this.runtimePayload(),
                 ...(pairing || enrolling ? { public_key_pem: record.publicKeyPem, enrollment_grant: grant } : {})
             }
@@ -247,6 +293,7 @@ export class GatewayDeviceChannel {
             this.options.pairingGrant = undefined;
             if (this.options.onStatus && message.payload)
                 await this.options.onStatus(message.payload);
+            this.updateCapabilities();
             this.startHeartbeat();
             this.reconnectAttempt = 0;
             this.readyResolve?.();
@@ -456,6 +503,7 @@ export class GatewayDeviceChannel {
     startHeartbeat() {
         this.stopHeartbeat();
         this.heartbeat = setInterval(async () => {
+            this.updateCapabilities();
             const record = await this.identity.loadOrCreate();
             this.send({
                 protocol_version: this.protocolVersion,

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

@@ -1,17 +1,25 @@
-import { LocalExecutionEngine } from './execution-engine.js';
+import { type CanonicalObserver } from '../context/capture.js';
+import { type DeviceContextOptions } from '../context/device-adapter.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 declare function gatewayCapabilities(): string[];
 export interface GatewayToolAdapterOptions {
+    context?: DeviceContextOptions;
+    /** Trusted runtime supplies an owner/repository-bound observer, never tool arguments. */
+    observer?: CanonicalObserver;
     allowedRoots?: string[];
     pathValidator?: (requestedPath: string) => Promise<string>;
 }
 export declare class GatewayToolAdapter {
-    private engine;
     private allowedRoots;
     private pathValidator;
     private canonicalRoots?;
-    constructor(engine: LocalExecutionEngine, options?: GatewayToolAdapterOptions);
+    private readonly observer?;
+    private readonly context?;
+    constructor(_unusedEngine?: any, options?: GatewayToolAdapterOptions);
+    private parseSessionPid;
     private guardPath;
     private imagePreview;
     call(tool: string, args?: any): Promise<any>;
+    private executeCall;
     private editFile;
 }