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

package/dist/device/gateway-tool-adapter.js

@@ -63,7 +63,7 @@ function parsePid(result) {
     const match = textFromResult(result).match(/PID\s+(-?\d+)/i);
     const pid = Number(match?.[1]);
     if (!Number.isInteger(pid))
-        throw new Error('Desktop Commander did not return a process PID');
+        throw new Error('Local execution engine did not return a process PID');
     return pid;
 }
 async function runShell(args) {
@@ -120,8 +120,8 @@ async function runShell(args) {
     }
 }
 export class GatewayToolAdapter {
-    constructor(desktop, options = {}) {
-        this.desktop = desktop;
+    constructor(engine, options = {}) {
+        this.engine = engine;
         this.allowedRoots = options.allowedRoots ?? configuredGatewayRoots();
         this.pathValidator = options.pathValidator ?? validatePath;
     }
@@ -188,6 +188,7 @@ export class GatewayToolAdapter {
         throw new Error(`REMOTE_IMAGE_TOO_LARGE: unable to fit preview within ${MAX_REMOTE_IMAGE_PREVIEW_BYTES} bytes`);
     }
     async call(tool, args = {}) {
+        this.engine.assertReady();
         if (tool === 'read_text_file') {
             if (args.head !== undefined && args.tail !== undefined)
                 throw new Error('Use either head or tail, not both');
@@ -199,10 +200,10 @@ export class GatewayToolAdapter {
             else if (args.tail !== undefined) {
                 mapped.offset = -Number(args.tail);
             }
-            return assertSuccess(await this.desktop.callClientTool('read_file', mapped), 'read_file');
+            return assertSuccess(await this.engine.callClientTool('read_file', mapped), 'read_file');
         }
         if (tool === 'write_file') {
-            return assertSuccess(await this.desktop.callClientTool('write_file', {
+            return assertSuccess(await this.engine.callClientTool('write_file', {
                 path: await this.guardPath(args.path),
                 content: args.content,
                 mode: 'rewrite'
@@ -214,7 +215,7 @@ export class GatewayToolAdapter {
             return await runShell({ ...args, working_directory: await this.guardPath(args.working_directory) });
         if (tool === 'start_process') {
             const workingDirectory = await this.guardPath(args.working_directory);
-            const result = assertSuccess(await this.desktop.callClientTool('start_process', {
+            const result = assertSuccess(await this.engine.callClientTool('start_process', {
                 command: args.command,
                 timeout_ms: Number(args.timeout_ms || 10000),
                 working_directory: workingDirectory
@@ -222,7 +223,7 @@ export class GatewayToolAdapter {
             return { ...result, pid: parsePid(result), session_id: String(parsePid(result)) };
         }
         if (tool === 'read_process_output') {
-            return assertSuccess(await this.desktop.callClientTool('read_process_output', {
+            return assertSuccess(await this.engine.callClientTool('read_process_output', {
                 pid: Number(args.session_id),
                 offset: args.offset,
                 length: args.length,
@@ -230,14 +231,14 @@ export class GatewayToolAdapter {
             }), 'read_process_output');
         }
         if (tool === 'interact_with_process') {
-            return assertSuccess(await this.desktop.callClientTool('interact_with_process', {
+            return assertSuccess(await this.engine.callClientTool('interact_with_process', {
                 pid: Number(args.session_id),
                 input: String(args.input ?? ''),
                 timeout_ms: Number(args.timeout_ms || 8000)
             }), 'interact_with_process');
         }
         if (tool === 'terminate_process') {
-            return assertSuccess(await this.desktop.callClientTool('force_terminate', {
+            return assertSuccess(await this.engine.callClientTool('force_terminate', {
                 pid: Number(args.session_id)
             }), 'force_terminate');
         }
@@ -258,7 +259,7 @@ export class GatewayToolAdapter {
             throw new Error('expected_replacements must be a positive integer');
         }
         if (args.dry_run === true) {
-            const read = assertSuccess(await this.desktop.callClientTool('read_file', {
+            const read = assertSuccess(await this.engine.callClientTool('read_file', {
                 path: args.path,
                 offset: 0,
                 length: 100000
@@ -274,7 +275,7 @@ export class GatewayToolAdapter {
                         }) }]
             };
         }
-        return assertSuccess(await this.desktop.callClientTool('edit_block', {
+        return assertSuccess(await this.engine.callClientTool('edit_block', {
             file_path: args.path,
             old_string: args.old_text,
             new_string: args.new_text,

package/dist/device/linux-service.d.ts

@@ -1,3 +1,5 @@
+export declare const SYSTEMD_UNIT = "mcp-device.service";
+export declare const PM2_NAME = "mcp-device";
 type ExecFileResult = {
     stdout: string;
     stderr: string;
@@ -20,6 +22,7 @@ export declare class SystemdUserDeviceService {
     private nodePath;
     private entrypoint;
     private pathValue;
+    private runtimeDir;
     constructor(options?: {
         platform?: NodeJS.Platform | string;
         execFile?: ExecFileFn;
@@ -27,6 +30,7 @@ export declare class SystemdUserDeviceService {
         nodePath?: string;
         entrypoint?: string;
         pathValue?: string;
+        runtimeDir?: string;
     });
     private assertLinux;
     private unitExists;
@@ -45,6 +49,7 @@ export declare class Pm2DeviceService {
     private entrypoint;
     private user;
     private pm2Home;
+    private runtimeDir;
     constructor(options?: {
         platform?: NodeJS.Platform | string;
         execFile?: ExecFileFn;
@@ -53,6 +58,7 @@ export declare class Pm2DeviceService {
         entrypoint?: string;
         user?: string;
         pm2Home?: string;
+        runtimeDir?: string;
     });
     private assertLinux;
     private processRow;

package/dist/device/linux-service.js

@@ -4,10 +4,11 @@ import os from 'os';
 import path from 'path';
 import readline from 'readline/promises';
 import { promisify } from 'util';
+import { deviceStatePaths } from './device-state.js';
 const execFileAsync = promisify(execFileCallback);
-const SYSTEMD_UNIT = 'mcp-device.service';
+export const SYSTEMD_UNIT = 'mcp-device.service';
 const SYSTEMD_OWNER_MARKER = '# Managed by MCP Device';
-const PM2_NAME = 'mcp-device';
+export const PM2_NAME = 'mcp-device';
 async function defaultExecFile(file, args) {
     const result = await execFileAsync(file, args, { windowsHide: true, encoding: 'utf8' });
     return { stdout: String(result.stdout || ''), stderr: String(result.stderr || '') };
@@ -55,6 +56,7 @@ export class SystemdUserDeviceService {
         this.nodePath = options.platform === 'linux' && options.nodePath ? String(options.nodePath) : path.resolve(options.nodePath || process.execPath);
         this.entrypoint = options.platform === 'linux' && options.entrypoint ? String(options.entrypoint) : path.resolve(options.entrypoint || process.argv[1]);
         this.pathValue = String(options.pathValue ?? process.env.PATH ?? '/usr/local/bin:/usr/bin:/bin');
+        this.runtimeDir = options.platform === 'linux' && options.runtimeDir ? String(options.runtimeDir) : path.resolve(options.runtimeDir || deviceStatePaths().runtime);
     }
     assertLinux() {
         if (this.platform !== 'linux')
@@ -89,6 +91,7 @@ export class SystemdUserDeviceService {
             '[Service]',
             'Type=simple',
             `Environment="PATH=${this.pathValue.replace(/["\\]/g, match => `\\${match}`)}"`,
+            `WorkingDirectory=${quoteSystemdArg(this.runtimeDir)}`,
             `ExecStart=${quoteSystemdArg(this.nodePath)} ${quoteSystemdArg(this.entrypoint)} --service --manager=systemd`,
             'Restart=on-failure',
             'RestartSec=3',
@@ -102,6 +105,7 @@ export class SystemdUserDeviceService {
         this.assertLinux();
         await this.assertOwnedUnitIfPresent();
         await this.execFile('systemctl', ['--user', 'show-environment']);
+        await fs.mkdir(this.runtimeDir, { recursive: true, mode: 0o700 });
         await fs.mkdir(path.dirname(this.unitPath), { recursive: true });
         await fs.writeFile(this.unitPath, this.unitText(), { mode: 0o600 });
         await this.execFile('systemctl', ['--user', 'daemon-reload']);
@@ -152,6 +156,7 @@ export class Pm2DeviceService {
         this.entrypoint = options.platform === 'linux' && options.entrypoint ? String(options.entrypoint) : path.resolve(options.entrypoint || process.argv[1]);
         this.user = String(options.user || process.env.USER || process.env.LOGNAME || os.userInfo().username);
         this.pm2Home = options.platform === 'linux' && options.pm2Home ? String(options.pm2Home) : path.resolve(options.pm2Home || process.env.PM2_HOME || path.join(os.homedir(), '.pm2'));
+        this.runtimeDir = options.platform === 'linux' && options.runtimeDir ? String(options.runtimeDir) : path.resolve(options.runtimeDir || deviceStatePaths().runtime);
     }
     assertLinux() {
         if (this.platform !== 'linux')
@@ -209,13 +214,15 @@ export class Pm2DeviceService {
     }
     async install() {
         await this.proveStartup();
+        await fs.mkdir(this.runtimeDir, { recursive: true, mode: 0o700 });
         const existing = await this.processRow();
         this.assertOwnedProcess(existing);
         if (!existing) {
-            await this.execFile(this.pm2Path, ['start', this.entrypoint, '--name', PM2_NAME, '--interpreter', this.nodePath, '--', '--service', '--manager=pm2']);
+            await this.execFile(this.pm2Path, ['start', this.entrypoint, '--name', PM2_NAME, '--interpreter', this.nodePath, '--cwd', this.runtimeDir, '--', '--service', '--manager=pm2']);
         }
-        else if (String(existing?.pm2_env?.status || '').toLowerCase() !== 'online') {
-            await this.execFile(this.pm2Path, ['restart', PM2_NAME]);
+        else if (String(existing?.pm2_env?.status || '').toLowerCase() !== 'online' ||
+            String(existing?.pm2_env?.pm_cwd || '') !== this.runtimeDir) {
+            await this.execFile(this.pm2Path, ['restart', PM2_NAME, '--cwd', this.runtimeDir]);
         }
         await this.execFile(this.pm2Path, ['save']);
         const status = await this.status();

package/dist/device/runtime-owner.d.ts

@@ -9,6 +9,7 @@ export interface RuntimeOwnerStatus {
     entrypoint: string;
     deviceId: string | null;
 }
+export declare function runtimeOwnerControlFileFor(paths: DeviceStatePaths): string;
 export declare function probeRuntimeOwner(paths?: DeviceStatePaths, platform?: NodeJS.Platform | string): Promise<RuntimeOwnerStatus | null>;
 export declare class RuntimeOwner {
     readonly paths: DeviceStatePaths;

package/dist/device/runtime-owner.js

@@ -2,14 +2,14 @@ import crypto from 'crypto';
 import fs from 'fs/promises';
 import net from 'net';
 import path from 'path';
-import { deviceStatePaths, migrateLegacyDeviceState } from './device-state.js';
+import { deviceStatePaths } from './device-state.js';
 function endpointFor(paths, platform = process.platform) {
     const digest = crypto.createHash('sha256').update(paths.root, 'utf8').digest('hex').slice(0, 24);
     if (platform === 'win32')
         return `\\\\.\\pipe\\mcp-device-${digest}`;
     return path.join(paths.root, `runtime-${digest}.sock`);
 }
-function controlFileFor(paths) {
+export function runtimeOwnerControlFileFor(paths) {
     return path.join(paths.root, 'runtime-control.json');
 }
 async function request(endpoint, message, timeoutMs = 800) {
@@ -103,10 +103,10 @@ export class RuntimeOwner {
             this.server.once('error', reject);
             this.server.listen(this.endpoint, resolve);
         });
-        await fs.writeFile(controlFileFor(this.paths), JSON.stringify({ endpoint: this.endpoint, nonce: this.nonce }, null, 2), { mode: 0o600 });
+        await fs.writeFile(runtimeOwnerControlFileFor(this.paths), JSON.stringify({ endpoint: this.endpoint, nonce: this.nonce }, null, 2), { mode: 0o600 });
     }
     async bootstrap() {
-        await migrateLegacyDeviceState(this.paths);
+        await fs.mkdir(this.paths.root, { recursive: true, mode: 0o700 });
     }
     setDeviceId(deviceId) {
         this.status.deviceId = String(deviceId || '').trim() || null;
@@ -118,7 +118,7 @@ export class RuntimeOwner {
             await new Promise(resolve => server.close(() => resolve()));
         }
         try {
-            await fs.unlink(controlFileFor(this.paths));
+            await fs.unlink(runtimeOwnerControlFileFor(this.paths));
         }
         catch (error) {
             if (error?.code !== 'ENOENT')
@@ -138,7 +138,7 @@ export class RuntimeOwner {
 export async function stopRuntimeOwner(paths = deviceStatePaths(), platform = process.platform) {
     let control;
     try {
-        control = JSON.parse(await fs.readFile(controlFileFor(paths), 'utf8'));
+        control = JSON.parse(await fs.readFile(runtimeOwnerControlFileFor(paths), 'utf8'));
     }
     catch (error) {
         if (error?.code === 'ENOENT')

package/dist/device/self-update.d.ts

@@ -1,20 +1,115 @@
 import { spawn as spawnCallback } from 'child_process';
+import { type DeviceStatePaths } from './device-state.js';
 export declare const MCP_DEVICE_PACKAGE = "@hcu-lab.me/mcp-device";
+export type DeviceUpdateManagerKind = 'windows-task' | 'windows-run' | 'windows-manual' | 'systemd' | 'pm2';
+export type DeviceUpdatePhase = 'prepared' | 'helper_started' | 'handoff_ready' | 'quiescing' | 'installing' | 'installed_waiting_reconnect' | 'rollback' | 'failed';
+export interface DeviceUpdateState {
+    schema: number;
+    requestId: string;
+    fromVersion: string;
+    targetVersion: string;
+    state: DeviceUpdatePhase;
+    startedAt: number;
+    updatedAt?: number;
+    completedAt: number | null;
+    errorCode: string | null;
+    message: string | null;
+    deviceId: string;
+    managerKind: DeviceUpdateManagerKind;
+    parentPid: number;
+    childPid: number | null;
+    packageRoot: string;
+    globalPrefix: string;
+    nodePath: string;
+    npmCliPath: string;
+    targetTarball: string;
+    cacheDir: string;
+    rollbackSnapshot: string;
+    rollbackPath: string;
+    helperPath: string;
+    handoffPath: string;
+    runtimeOwnerControlPath: string;
+    windowsRunnerPath?: string;
+    windowsTaskName?: string;
+    windowsUpdateTaskName?: string;
+    powershellPath?: string;
+    schtasksPath?: string;
+    systemctlPath?: string;
+    systemdRunPath?: string;
+    systemdUnit?: string;
+    systemdUpdateUnit?: string;
+    pm2Path?: string;
+    pm2Name?: string;
+}
+export interface PreparedDeviceUpdate {
+    state: DeviceUpdateState;
+    statePath: string;
+    helperRunnerPath?: string;
+}
+type ExecFileFn = (file: string, args: string[]) => Promise<{
+    stdout?: string;
+    stderr?: string;
+}>;
+export interface DeviceUpdateManagerOverride {
+    managerKind: DeviceUpdateManagerKind;
+    windowsRunnerPath?: string;
+    windowsTaskName?: string;
+    powershellPath?: string;
+    schtasksPath?: string;
+    systemctlPath?: string;
+    systemdRunPath?: string;
+    systemdUnit?: string;
+    pm2Path?: string;
+    pm2Name?: string;
+}
 export declare function normalizeUpdateVersion(value: string): string;
-export declare function installDevicePackageUpdate(targetVersion: string, options?: {
+export declare function readDeviceUpdateState(paths?: DeviceStatePaths): Promise<DeviceUpdateState | null>;
+export declare function assertDeviceStartupAllowedDuringUpdate(currentVersion?: string, paths?: DeviceStatePaths): Promise<void>;
+export declare function resolveNpmCliPath(options?: {
     platform?: NodeJS.Platform | string;
-    execFile?: (file: string, args: string[]) => Promise<{
-        stdout?: string;
-        stderr?: string;
-    }>;
-    npmPath?: string;
+    execFile?: ExecFileFn;
+    nodePath?: string;
+    npmExecPath?: string;
 }): Promise<string>;
-export declare function buildWindowsRestartHelper(deviceId: string, currentPid?: number): string;
-export declare function scheduleDeviceRuntimeRestart(options: {
+export declare function findCurrentPackageRoot(entrypoint?: string): Promise<string>;
+export declare function prepareDevicePackageUpdate(options: {
+    targetVersion: string;
+    requestId: string;
     deviceId: string;
-    platform?: NodeJS.Platform | string;
+    childPid?: number | null;
+    fromVersion?: string;
     argv?: string[];
-    delayMs?: number;
+    platform?: NodeJS.Platform | string;
+    execFile?: ExecFileFn;
+    paths?: DeviceStatePaths;
+    entrypoint?: string;
+    nodePath?: string;
+    packageRoot?: string;
+    npmCliPath?: string;
+    globalPrefix?: string;
+    globalRoot?: string;
+    managerOverride?: DeviceUpdateManagerOverride;
+    helperSourcePath?: string;
+}): Promise<PreparedDeviceUpdate>;
+export declare function launchDeviceUpdateHelper(prepared: PreparedDeviceUpdate, options?: {
+    execFile?: ExecFileFn;
     spawn?: typeof spawnCallback;
-    exit?: (code?: number) => never | void;
-}): void;
+    platform?: NodeJS.Platform | string;
+    paths?: DeviceStatePaths;
+}): Promise<void>;
+export declare function signalDeviceUpdateHandoff(handoff?: {
+    childPid?: number | null;
+}, paths?: DeviceStatePaths): Promise<void>;
+export declare function markPreparedUpdateFailed(code: string, message: string, paths?: DeviceStatePaths): Promise<void>;
+export type UpdateReconciliation = {
+    action: 'none';
+} | {
+    action: 'success';
+    state: DeviceUpdateState;
+} | {
+    action: 'report-failed';
+    state: DeviceUpdateState;
+};
+export declare function reconcileDeviceUpdateAfterStart(currentVersion?: string, paths?: DeviceStatePaths): Promise<UpdateReconciliation>;
+export declare function retireDeviceUpdateState(state: DeviceUpdateState, paths?: DeviceStatePaths): Promise<void>;
+export {};