@hcu-lab.me/mcp-device 1.0.0

package/dist/device/execution-engine.js

@@ -0,0 +1,195 @@
+import { spawn } from 'child_process';
+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';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+export class DesktopCommanderIntegration {
+    constructor() {
+        this.mcpClient = null;
+        this.mcpTransport = null;
+        this.isReady = false;
+    }
+    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));
+        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({
+                ...config,
+                env: {
+                    ...getDefaultEnvironment(),
+                    ...config.env,
+                    MCP_DEVICE_REMOTE: 'true',
+                    DESKTOP_COMMANDER_DISABLE_TELEMETRY: '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);
+            this.isReady = true;
+            console.log(' - 🔌 Connected to Desktop Commander MCP');
+            console.debug('[DEBUG] Desktop Commander MCP connection successful');
+        }
+        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;
+        }
+    }
+    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);
+        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)
+            };
+        }
+        catch {
+            console.debug('[DEBUG] Local dev path not found, trying global installation');
+            // Local file not found, continue...
+        }
+        // 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;
+    }
+    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
+        try {
+            console.debug('[DEBUG] Calling MCP tool:', toolName, 'args:', JSON.stringify(args).substring(0, 100));
+            const result = 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 });
+            throw error;
+        }
+    }
+    async listClientTools() {
+        if (!this.mcpClient)
+            return { tools: [] };
+        try {
+            // List tools from MCP server
+            const mcpTools = await this.mcpClient.listTools();
+            // Merge 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: []
+            };
+        }
+    }
+    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))
+            ]);
+        };
+        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' });
+            }
+            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' });
+            }
+            this.mcpTransport = null;
+        }
+        this.isReady = false;
+        console.debug('[DEBUG] Desktop Commander integration shutdown complete');
+    }
+}

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

@@ -0,0 +1,48 @@
+import type { Agent } from 'http';
+import { GatewayDeviceIdentity } from './gateway-identity.js';
+import { GatewayToolAdapter } from './gateway-tool-adapter.js';
+export interface GatewayChannelOptions {
+    gatewayUrl: string;
+    enrollmentToken?: string;
+    pairingGrant?: string;
+    identity?: GatewayDeviceIdentity;
+    proxyAgent?: Agent;
+    securityProtocolFloor?: number;
+    appCaPem?: string;
+    adapter: GatewayToolAdapter;
+    agentVersion?: string;
+    onStatus?: (payload: any) => void | Promise<void>;
+}
+export declare class GatewayDeviceChannel {
+    private options;
+    private socket?;
+    private heartbeat?;
+    private shuttingDown;
+    private identity;
+    private readyResolve?;
+    private readyReject?;
+    private reconnectTimer?;
+    private reconnectAttempt;
+    private authenticatedDeviceId?;
+    private connectionEpoch?;
+    private accountLogoutResolve?;
+    private accountLogoutReject?;
+    private messageQueue;
+    private protocolVersion;
+    private secureSocket?;
+    private authMode;
+    constructor(options: GatewayChannelOptions);
+    start(): Promise<void>;
+    private startV2Transport;
+    stop(): Promise<void>;
+    private sendHello;
+    private sendHelloV2;
+    private handleMessage;
+    logoutAccount(timeoutMs?: number): Promise<any>;
+    private handleToolCall;
+    private scheduleReconnect;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private send;
+    private fail;
+}

package/dist/device/gateway-channel.js

@@ -0,0 +1,384 @@
+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 { gatewaySocketUrl } from './gateway-url-policy.js';
+const PROTOCOL_VERSION = 1;
+const PROTOCOL_VERSION_V2 = 2;
+const HEARTBEAT_MS = 20000;
+const MAX_OUTBOUND_MESSAGE_BYTES = 56 * 1024;
+export class GatewayDeviceChannel {
+    constructor(options) {
+        this.options = options;
+        this.shuttingDown = false;
+        this.reconnectAttempt = 0;
+        this.messageQueue = Promise.resolve();
+        this.protocolVersion = PROTOCOL_VERSION;
+        this.authMode = 'reconnect';
+        this.identity = options.identity || new GatewayDeviceIdentity();
+    }
+    async start() {
+        this.authenticatedDeviceId = undefined;
+        this.connectionEpoch = undefined;
+        this.messageQueue = Promise.resolve();
+        const record = await this.identity.loadOrCreate();
+        this.protocolVersion = Number(this.options.securityProtocolFloor || 1) >= 2 ? PROTOCOL_VERSION_V2 : PROTOCOL_VERSION;
+        if (this.protocolVersion === PROTOCOL_VERSION_V2 && !String(this.options.appCaPem || '').trim()) {
+            throw new Error('Protocol v2 requires a provisioned gateway application CA.');
+        }
+        const credential = this.options.pairingGrant || (!record.enrolled ? this.options.enrollmentToken : undefined);
+        const webSocketOptions = this.options.proxyAgent ? { agent: this.options.proxyAgent } : {};
+        const socket = this.protocolVersion === PROTOCOL_VERSION_V2
+            ? new WebSocket(gatewaySocketUrl(this.options.gatewayUrl), DEVICE_INNER_TLS_SUBPROTOCOL, webSocketOptions)
+            : new WebSocket(gatewaySocketUrl(this.options.gatewayUrl), {
+                ...(credential ? { headers: { authorization: `Bearer ${credential}` } } : {}),
+                ...webSocketOptions
+            });
+        this.socket = socket;
+        const ready = new Promise((resolve, reject) => {
+            this.readyResolve = resolve;
+            this.readyReject = reject;
+        });
+        if (this.protocolVersion === PROTOCOL_VERSION_V2) {
+            socket.once('open', () => this.startV2Transport().catch(error => this.fail(error)));
+        }
+        else {
+            socket.once('open', () => this.sendHello().catch(error => this.fail(error)));
+            socket.on('message', raw => {
+                this.messageQueue = this.messageQueue
+                    .then(() => this.handleMessage(raw.toString()))
+                    .catch(error => this.fail(error));
+            });
+        }
+        socket.once('error', error => this.fail(error));
+        socket.once('close', (code, reason) => {
+            this.stopHeartbeat();
+            if (!this.shuttingDown && this.readyReject) {
+                this.fail(new Error(`Gateway connection closed (${code}): ${reason.toString()}`));
+            }
+            else if (!this.shuttingDown) {
+                this.scheduleReconnect();
+            }
+        });
+        await ready;
+    }
+    async startV2Transport() {
+        const socket = this.socket;
+        if (!socket || socket.readyState !== WebSocket.OPEN)
+            throw new Error('Gateway socket is not open');
+        if (socket.protocol !== DEVICE_INNER_TLS_SUBPROTOCOL) {
+            throw new Error('Gateway did not negotiate the required v2 inner TLS subprotocol.');
+        }
+        const url = new URL(gatewaySocketUrl(this.options.gatewayUrl));
+        const secure = createClientInnerTls(socket, {
+            ca: String(this.options.appCaPem || ''),
+            servername: url.hostname
+        });
+        this.secureSocket = secure;
+        const parser = createJsonFrameParser({
+            onMessage: message => {
+                this.messageQueue = this.messageQueue
+                    .then(() => this.handleMessage(message))
+                    .catch(error => this.fail(error));
+            }
+        });
+        secure.on('data', chunk => {
+            try {
+                parser.push(chunk);
+            }
+            catch (error) {
+                this.fail(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+        secure.once('error', error => this.fail(error));
+        await new Promise((resolve, reject) => {
+            secure.once('secureConnect', resolve);
+            secure.once('error', reject);
+        });
+        await this.sendHelloV2();
+    }
+    async stop() {
+        this.shuttingDown = true;
+        this.stopHeartbeat();
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = undefined;
+        const secure = this.secureSocket;
+        this.secureSocket = undefined;
+        if (secure && !secure.destroyed)
+            secure.destroy();
+        const socket = this.socket;
+        this.socket = undefined;
+        if (!socket || socket.readyState === WebSocket.CLOSED)
+            return;
+        await new Promise(resolve => {
+            const timer = setTimeout(() => {
+                try {
+                    socket.terminate();
+                }
+                catch { }
+                resolve();
+            }, 1500);
+            socket.once('close', () => {
+                clearTimeout(timer);
+                resolve();
+            });
+            socket.close(1000, 'device shutdown');
+        });
+    }
+    async sendHello() {
+        const record = await this.identity.loadOrCreate();
+        const pairing = record.enrolled && Boolean(this.options.pairingGrant);
+        const enrolling = !record.enrolled && Boolean(this.options.pairingGrant || this.options.enrollmentToken);
+        this.send({
+            protocol_version: PROTOCOL_VERSION,
+            type: pairing ? 'pair_hello' : enrolling ? 'enroll_hello' : 'auth_hello',
+            device_id: record.deviceId,
+            timestamp: Date.now(),
+            payload: {
+                agent_version: this.options.agentVersion || 'mcp-device-1',
+                hostname: os.hostname(),
+                platform: process.platform,
+                arch: process.arch,
+                path_style: process.platform === 'win32' ? 'windows' : 'posix',
+                capabilities: [...GATEWAY_CAPABILITIES],
+                ...(enrolling || pairing ? { public_key_pem: record.publicKeyPem } : {})
+            }
+        });
+    }
+    async sendHelloV2() {
+        const record = await this.identity.loadOrCreate();
+        const pairing = record.enrolled && Boolean(this.options.pairingGrant);
+        const enrolling = !record.enrolled && Boolean(this.options.pairingGrant || this.options.enrollmentToken);
+        this.authMode = pairing ? 'pair' : enrolling ? 'enroll' : 'reconnect';
+        const grant = pairing || enrolling ? String(this.options.pairingGrant || this.options.enrollmentToken || '') : '';
+        this.send({
+            protocol_version: PROTOCOL_VERSION_V2,
+            type: pairing ? 'pair_hello' : enrolling ? 'enroll_hello' : 'auth_hello',
+            device_id: record.deviceId,
+            timestamp: Date.now(),
+            payload: {
+                agent_version: this.options.agentVersion || 'mcp-device-1',
+                hostname: os.hostname(),
+                platform: process.platform,
+                arch: process.arch,
+                path_style: process.platform === 'win32' ? 'windows' : 'posix',
+                capabilities: [...GATEWAY_CAPABILITIES],
+                ...(pairing || enrolling ? { public_key_pem: record.publicKeyPem, enrollment_grant: grant } : {})
+            }
+        });
+    }
+    async handleMessage(raw) {
+        const message = typeof raw === 'string' ? JSON.parse(raw) : raw;
+        if (message?.protocol_version !== this.protocolVersion)
+            throw new Error('Unsupported gateway protocol version');
+        if (['auth_challenge', 'auth_ok', 'tool_call'].includes(String(message?.type || ''))) {
+            const record = await this.identity.loadOrCreate();
+            if (String(message?.device_id || '') !== record.deviceId)
+                throw new Error('Gateway message device_id mismatch');
+        }
+        if (message.type === 'auth_challenge') {
+            const nonce = String(message.payload?.nonce || '');
+            if (!nonce)
+                throw new Error('Gateway authentication challenge is missing a nonce');
+            const record = await this.identity.loadOrCreate();
+            if (this.protocolVersion === PROTOCOL_VERSION_V2) {
+                const mode = String(message.payload?.mode || '');
+                if (mode !== this.authMode)
+                    throw new Error('Gateway authentication challenge mode mismatch');
+                const nonceBytes = Buffer.from(nonce, 'base64url');
+                if (nonceBytes.length !== 32)
+                    throw new Error('Gateway v2 authentication challenge nonce must be exactly 32 bytes');
+                if (!this.secureSocket)
+                    throw new Error('Gateway v2 inner TLS socket is unavailable');
+                const exporter = exportDeviceAuthKeyingMaterial(this.secureSocket, record.deviceId, this.authMode);
+                const grant = this.authMode === 'reconnect' ? null : String(this.options.pairingGrant || this.options.enrollmentToken || '');
+                this.send({
+                    protocol_version: PROTOCOL_VERSION_V2,
+                    type: 'auth_response',
+                    device_id: record.deviceId,
+                    timestamp: Date.now(),
+                    payload: {
+                        signature: await this.identity.signChallengeV2({ mode: this.authMode, nonce: nonceBytes, exporter, grant })
+                    }
+                });
+                return;
+            }
+            this.send({
+                protocol_version: PROTOCOL_VERSION,
+                type: 'auth_response',
+                device_id: record.deviceId,
+                timestamp: Date.now(),
+                payload: { signature: await this.identity.signChallenge(nonce) }
+            });
+            return;
+        }
+        if (message.type === 'auth_ok') {
+            if (message.connection_epoch === undefined || message.connection_epoch === null || String(message.connection_epoch).trim() === '')
+                throw new Error('Gateway auth_ok is missing connection_epoch');
+            const record = await this.identity.loadOrCreate();
+            this.authenticatedDeviceId = record.deviceId;
+            this.connectionEpoch = message.connection_epoch;
+            await this.identity.markEnrolled();
+            this.options.pairingGrant = undefined;
+            if (this.options.onStatus && message.payload)
+                await this.options.onStatus(message.payload);
+            this.startHeartbeat();
+            this.reconnectAttempt = 0;
+            this.readyResolve?.();
+            this.readyResolve = undefined;
+            this.readyReject = undefined;
+            return;
+        }
+        if (message.type === 'status_snapshot') {
+            if (this.connectionEpoch === undefined || this.authenticatedDeviceId === undefined)
+                return;
+            if (String(message.connection_epoch) !== String(this.connectionEpoch))
+                return;
+            if (this.options.onStatus && message.payload)
+                await this.options.onStatus(message.payload);
+            if (message.payload?.account?.connected === false && this.accountLogoutResolve) {
+                this.accountLogoutResolve(message.payload);
+                this.accountLogoutResolve = undefined;
+                this.accountLogoutReject = undefined;
+            }
+            return;
+        }
+        if (message.type !== 'tool_call')
+            return;
+        if (this.connectionEpoch === undefined || this.authenticatedDeviceId === undefined)
+            throw new Error('Gateway tool_call arrived before authentication');
+        if (String(message.connection_epoch) !== String(this.connectionEpoch))
+            throw new Error('Gateway tool_call connection_epoch mismatch');
+        await this.handleToolCall(message);
+    }
+    async logoutAccount(timeoutMs = 5000) {
+        if (!this.socket || this.socket.readyState !== WebSocket.OPEN || this.connectionEpoch === undefined || !this.authenticatedDeviceId) {
+            throw new Error('Gateway device is not authenticated.');
+        }
+        if (this.accountLogoutResolve)
+            throw new Error('Account logout is already pending.');
+        const result = new Promise((resolve, reject) => {
+            this.accountLogoutResolve = resolve;
+            this.accountLogoutReject = reject;
+        });
+        this.send({
+            protocol_version: this.protocolVersion,
+            type: 'account_logout',
+            device_id: this.authenticatedDeviceId,
+            connection_epoch: this.connectionEpoch,
+            timestamp: Date.now(),
+            payload: {}
+        });
+        const timer = setTimeout(() => {
+            if (!this.accountLogoutReject)
+                return;
+            const reject = this.accountLogoutReject;
+            this.accountLogoutResolve = undefined;
+            this.accountLogoutReject = undefined;
+            reject(new Error('Timed out waiting for account logout status.'));
+        }, timeoutMs);
+        try {
+            return await result;
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    async handleToolCall(message) {
+        if (this.connectionEpoch === undefined || !this.authenticatedDeviceId)
+            throw new Error('Gateway tool_call arrived before authentication');
+        const requestId = String(message.request_id || '');
+        const tool = String(message.payload?.tool || '');
+        try {
+            const result = await this.options.adapter.call(tool, message.payload?.arguments || {});
+            this.send({
+                protocol_version: this.protocolVersion,
+                type: 'tool_result',
+                request_id: requestId,
+                device_id: this.authenticatedDeviceId,
+                connection_epoch: this.connectionEpoch,
+                timestamp: Date.now(),
+                payload: result
+            });
+        }
+        catch (error) {
+            this.send({
+                protocol_version: this.protocolVersion,
+                type: 'tool_error',
+                request_id: requestId,
+                device_id: this.authenticatedDeviceId,
+                connection_epoch: this.connectionEpoch,
+                timestamp: Date.now(),
+                payload: {
+                    message: String(error?.message || error),
+                    code: String(error?.code || 'REMOTE_DEVICE_ERROR').slice(0, 64)
+                }
+            });
+        }
+    }
+    scheduleReconnect() {
+        if (this.shuttingDown || this.reconnectTimer)
+            return;
+        const delay = Math.min(30000, 1000 * 2 ** Math.min(this.reconnectAttempt, 5));
+        this.reconnectAttempt += 1;
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = undefined;
+            this.start().catch(() => this.scheduleReconnect());
+        }, delay);
+        this.reconnectTimer.unref?.();
+    }
+    startHeartbeat() {
+        this.stopHeartbeat();
+        this.heartbeat = setInterval(async () => {
+            const record = await this.identity.loadOrCreate();
+            this.send({
+                protocol_version: this.protocolVersion,
+                type: 'heartbeat',
+                device_id: record.deviceId,
+                timestamp: Date.now(),
+                payload: {}
+            });
+        }, HEARTBEAT_MS);
+        this.heartbeat.unref?.();
+    }
+    stopHeartbeat() {
+        if (this.heartbeat)
+            clearInterval(this.heartbeat);
+        this.heartbeat = undefined;
+    }
+    send(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');
+            this.secureSocket.write(encodeJsonFrame(message));
+            return;
+        }
+        this.socket.send(encoded);
+    }
+    fail(error) {
+        const reject = this.readyReject;
+        this.readyResolve = undefined;
+        this.readyReject = undefined;
+        if (reject) {
+            reject(error);
+            return;
+        }
+        const socket = this.socket;
+        if (socket && socket.readyState !== WebSocket.CLOSED) {
+            try {
+                socket.terminate();
+            }
+            catch { }
+        }
+    }
+}

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

@@ -0,0 +1,40 @@
+import { ProxyAgent } from 'proxy-agent';
+export interface GatewayProxyConfig {
+    mode: 'direct' | 'configured';
+    url: string | null;
+}
+export interface GatewayDeviceConfig {
+    version: 1;
+    gatewayUrl: string | null;
+    allowedRoots: string[];
+    proxy: GatewayProxyConfig;
+    appCaPem: string | null;
+    securityProtocolFloor: number;
+}
+type SecretProtect = (value: Buffer) => Promise<string>;
+type SecretUnprotect = (value: string) => Promise<Buffer>;
+export declare class GatewayDeviceConfigStore {
+    readonly configPath: string;
+    private platform;
+    private protectSecret;
+    private unprotectSecret;
+    constructor(configPath?: string, options?: {
+        platform?: NodeJS.Platform | string;
+        protectSecret?: SecretProtect;
+        unprotectSecret?: SecretUnprotect;
+    });
+    load(): Promise<GatewayDeviceConfig>;
+    update(patch: Partial<GatewayDeviceConfig>): Promise<GatewayDeviceConfig>;
+    private persist;
+}
+export declare function resolveProxyDecisionFromEnvironment(gatewayUrl: string): {
+    explicit: boolean;
+    proxyUrl: string | null;
+};
+export declare function captureGatewayConfigFromEnvironment(store: GatewayDeviceConfigStore, options?: {
+    fallbackGatewayUrl?: string | null;
+}): Promise<GatewayDeviceConfig>;
+export declare function createGatewayProxyAgent(config: GatewayDeviceConfig): {
+    agent: ProxyAgent;
+};
+export {};