unreal-engine-mcp-server 0.4.7 → 0.5.0

package/dist/automation/bridge.js

@@ -0,0 +1,452 @@
+import { EventEmitter } from 'node:events';
+import { WebSocket } from 'ws';
+import { Logger } from '../utils/logger.js';
+import { DEFAULT_AUTOMATION_HOST, DEFAULT_AUTOMATION_PORT, DEFAULT_NEGOTIATED_PROTOCOLS, DEFAULT_HEARTBEAT_INTERVAL_MS, DEFAULT_MAX_PENDING_REQUESTS } from '../constants.js';
+import { createRequire } from 'node:module';
+import { ConnectionManager } from './connection-manager.js';
+import { RequestTracker } from './request-tracker.js';
+import { HandshakeHandler } from './handshake.js';
+import { MessageHandler } from './message-handler.js';
+const require = createRequire(import.meta.url);
+const packageInfo = (() => {
+    try {
+        return require('../../package.json');
+    }
+    catch (error) {
+        const log = new Logger('AutomationBridge');
+        log.debug('Unable to read package.json for version info', error);
+        return {};
+    }
+})();
+export class AutomationBridge extends EventEmitter {
+    host;
+    port;
+    ports;
+    negotiatedProtocols;
+    capabilityToken;
+    enabled;
+    serverName;
+    serverVersion;
+    clientHost;
+    clientPort;
+    serverLegacyEnabled;
+    maxConcurrentConnections;
+    connectionManager;
+    requestTracker;
+    handshakeHandler;
+    messageHandler;
+    log = new Logger('AutomationBridge');
+    lastHandshakeAt;
+    lastHandshakeMetadata;
+    lastHandshakeAck;
+    lastHandshakeFailure;
+    lastDisconnect;
+    lastError;
+    requestQueue = [];
+    queuedRequestItems = [];
+    connectionPromise;
+    constructor(options = {}) {
+        super();
+        this.host = options.host ?? process.env.MCP_AUTOMATION_WS_HOST ?? DEFAULT_AUTOMATION_HOST;
+        const sanitizePort = (value) => {
+            if (typeof value === 'number' && Number.isInteger(value)) {
+                return value > 0 && value <= 65535 ? value : null;
+            }
+            if (typeof value === 'string' && value.trim().length > 0) {
+                const parsed = Number.parseInt(value.trim(), 10);
+                return Number.isInteger(parsed) && parsed > 0 && parsed <= 65535 ? parsed : null;
+            }
+            return null;
+        };
+        const defaultPort = sanitizePort(options.port ?? process.env.MCP_AUTOMATION_WS_PORT) ?? DEFAULT_AUTOMATION_PORT;
+        const configuredPortValues = options.ports
+            ? options.ports
+            : process.env.MCP_AUTOMATION_WS_PORTS
+                ?.split(',')
+                .map((token) => token.trim())
+                .filter((token) => token.length > 0);
+        const sanitizedPorts = Array.isArray(configuredPortValues)
+            ? configuredPortValues
+                .map((value) => sanitizePort(value))
+                .filter((port) => port !== null)
+            : [];
+        if (!sanitizedPorts.includes(defaultPort)) {
+            sanitizedPorts.unshift(defaultPort);
+        }
+        if (sanitizedPorts.length === 0) {
+            sanitizedPorts.push(DEFAULT_AUTOMATION_PORT);
+        }
+        this.ports = Array.from(new Set(sanitizedPorts));
+        const defaultProtocols = DEFAULT_NEGOTIATED_PROTOCOLS;
+        const userProtocols = Array.isArray(options.protocols)
+            ? options.protocols.filter((proto) => typeof proto === 'string' && proto.trim().length > 0)
+            : [];
+        const envProtocols = process.env.MCP_AUTOMATION_WS_PROTOCOLS
+            ? process.env.MCP_AUTOMATION_WS_PROTOCOLS.split(',')
+                .map((token) => token.trim())
+                .filter((token) => token.length > 0)
+            : [];
+        this.negotiatedProtocols = Array.from(new Set([...userProtocols, ...envProtocols, ...defaultProtocols]));
+        this.port = this.ports[0];
+        this.serverLegacyEnabled =
+            options.serverLegacyEnabled ?? process.env.MCP_AUTOMATION_SERVER_LEGACY !== 'false';
+        this.capabilityToken =
+            options.capabilityToken ?? process.env.MCP_AUTOMATION_CAPABILITY_TOKEN ?? undefined;
+        this.enabled = options.enabled ?? process.env.MCP_AUTOMATION_BRIDGE_ENABLED !== 'false';
+        this.serverName = options.serverName
+            ?? process.env.MCP_SERVER_NAME
+            ?? packageInfo.name
+            ?? 'unreal-engine-mcp';
+        this.serverVersion = options.serverVersion
+            ?? process.env.MCP_SERVER_VERSION
+            ?? packageInfo.version
+            ?? process.env.npm_package_version
+            ?? '0.0.0';
+        const heartbeatIntervalMs = (options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS) > 0
+            ? (options.heartbeatIntervalMs ?? DEFAULT_HEARTBEAT_INTERVAL_MS)
+            : 0;
+        const maxPendingRequests = Math.max(1, options.maxPendingRequests ?? DEFAULT_MAX_PENDING_REQUESTS);
+        const maxConcurrentConnections = Math.max(1, options.maxConcurrentConnections ?? 10);
+        this.clientHost = options.clientHost ?? process.env.MCP_AUTOMATION_CLIENT_HOST ?? DEFAULT_AUTOMATION_HOST;
+        this.clientPort = options.clientPort ?? sanitizePort(process.env.MCP_AUTOMATION_CLIENT_PORT) ?? DEFAULT_AUTOMATION_PORT;
+        this.maxConcurrentConnections = maxConcurrentConnections;
+        this.connectionManager = new ConnectionManager(heartbeatIntervalMs);
+        this.requestTracker = new RequestTracker(maxPendingRequests);
+        this.handshakeHandler = new HandshakeHandler(this.capabilityToken);
+        this.messageHandler = new MessageHandler(this.requestTracker);
+    }
+    on(event, listener) {
+        return super.on(event, listener);
+    }
+    once(event, listener) {
+        return super.once(event, listener);
+    }
+    off(event, listener) {
+        return super.off(event, listener);
+    }
+    start() {
+        if (!this.enabled) {
+            this.log.info('Automation bridge disabled by configuration.');
+            return;
+        }
+        this.log.info(`Automation bridge connecting to Unreal server at ws://${this.clientHost}:${this.clientPort}`);
+        this.startClient();
+    }
+    startClient() {
+        try {
+            const url = `ws://${this.clientHost}:${this.clientPort}`;
+            this.log.info(`Connecting to Unreal Engine automation server at ${url}`);
+            this.log.debug(`Negotiated protocols: ${JSON.stringify(this.negotiatedProtocols)}`);
+            const protocols = 'mcp-automation';
+            this.log.debug(`Using WebSocket protocols arg: ${JSON.stringify(protocols)}`);
+            const socket = new WebSocket(url, protocols, {
+                headers: this.capabilityToken ? { 'X-MCP-Capability': this.capabilityToken } : undefined,
+                perMessageDeflate: false
+            });
+            this.handleClientConnection(socket);
+        }
+        catch (error) {
+            const errorObj = error instanceof Error ? error : new Error(String(error));
+            this.lastError = { message: errorObj.message, at: new Date() };
+            this.log.error('Failed to create WebSocket client connection', errorObj);
+            const errorWithPort = Object.assign(errorObj, { port: this.clientPort });
+            this.emitAutomation('error', errorWithPort);
+        }
+    }
+    async handleClientConnection(socket) {
+        socket.on('open', async () => {
+            this.log.info('Automation bridge client connected, starting handshake');
+            try {
+                const metadata = await this.handshakeHandler.initiateHandshake(socket);
+                this.lastHandshakeAt = new Date();
+                this.lastHandshakeMetadata = metadata;
+                this.lastHandshakeFailure = undefined;
+                this.connectionManager.updateLastMessageTime();
+                const underlying = socket._socket || socket.socket;
+                const remoteAddr = underlying?.remoteAddress ?? undefined;
+                const remotePort = underlying?.remotePort ?? undefined;
+                this.connectionManager.registerSocket(socket, this.clientPort, metadata, remoteAddr, remotePort);
+                this.connectionManager.startHeartbeat();
+                this.flushQueue();
+                this.emitAutomation('connected', {
+                    socket,
+                    metadata,
+                    port: this.clientPort,
+                    protocol: socket.protocol || null
+                });
+                socket.on('message', (data) => {
+                    try {
+                        const text = typeof data === 'string' ? data : data.toString('utf8');
+                        this.log.debug(`[AutomationBridge Client] Received message: ${text.substring(0, 1000)}`);
+                        const parsed = JSON.parse(text);
+                        this.connectionManager.updateLastMessageTime();
+                        this.messageHandler.handleMessage(parsed);
+                        this.emitAutomation('message', parsed);
+                    }
+                    catch (error) {
+                        this.log.error('Error handling message', error);
+                    }
+                });
+            }
+            catch (error) {
+                const err = error instanceof Error ? error : new Error(String(error));
+                this.lastHandshakeFailure = { reason: err.message, at: new Date() };
+                this.emitAutomation('handshakeFailed', { reason: err.message, port: this.clientPort });
+            }
+        });
+        socket.on('error', (error) => {
+            this.log.error('Automation bridge client socket error', error);
+            const errObj = error instanceof Error ? error : new Error(String(error));
+            this.lastError = { message: errObj.message, at: new Date() };
+            const errWithPort = Object.assign(errObj, { port: this.clientPort });
+            this.emitAutomation('error', errWithPort);
+        });
+        socket.on('close', (code, reasonBuffer) => {
+            const reason = reasonBuffer.toString('utf8');
+            const socketInfo = this.connectionManager.removeSocket(socket);
+            if (socketInfo) {
+                this.lastDisconnect = { code, reason, at: new Date() };
+                this.emitAutomation('disconnected', {
+                    code,
+                    reason,
+                    port: socketInfo.port,
+                    protocol: socketInfo.protocol || null
+                });
+                this.log.info(`Automation bridge client socket closed (code=${code}, reason=${reason})`);
+                if (!this.connectionManager.isConnected()) {
+                    this.requestTracker.rejectAll(new Error(reason || 'Connection lost'));
+                }
+            }
+        });
+    }
+    stop() {
+        if (this.isConnected()) {
+            this.broadcast({
+                type: 'bridge_shutdown',
+                timestamp: new Date().toISOString(),
+                reason: 'Server shutting down'
+            });
+        }
+        this.connectionManager.closeAll(1001, 'Server shutdown');
+        this.lastHandshakeAck = undefined;
+        this.requestTracker.rejectAll(new Error('Automation bridge server stopped'));
+    }
+    isConnected() {
+        return this.connectionManager.isConnected();
+    }
+    getStatus() {
+        const connectionInfos = Array.from(this.connectionManager.getActiveSockets().entries()).map(([socket, info]) => ({
+            connectionId: info.connectionId,
+            sessionId: info.sessionId ?? null,
+            remoteAddress: info.remoteAddress ?? null,
+            remotePort: info.remotePort ?? null,
+            port: info.port,
+            connectedAt: info.connectedAt.toISOString(),
+            protocol: info.protocol || null,
+            readyState: socket.readyState,
+            isPrimary: socket === this.connectionManager.getPrimarySocket()
+        }));
+        return {
+            enabled: this.enabled,
+            host: this.host,
+            port: this.port,
+            configuredPorts: [...this.ports],
+            listeningPorts: [],
+            connected: this.isConnected(),
+            connectedAt: connectionInfos.length > 0 ? connectionInfos[0].connectedAt : null,
+            activePort: connectionInfos.length > 0 ? connectionInfos[0].port : null,
+            negotiatedProtocol: connectionInfos.length > 0 ? connectionInfos[0].protocol : null,
+            supportedProtocols: [...this.negotiatedProtocols],
+            supportedOpcodes: ['automation_request'],
+            expectedResponseOpcodes: ['automation_response'],
+            capabilityTokenRequired: Boolean(this.capabilityToken),
+            lastHandshakeAt: this.lastHandshakeAt?.toISOString() ?? null,
+            lastHandshakeMetadata: this.lastHandshakeMetadata ?? null,
+            lastHandshakeAck: this.lastHandshakeAck ?? null,
+            lastHandshakeFailure: this.lastHandshakeFailure
+                ? { reason: this.lastHandshakeFailure.reason, at: this.lastHandshakeFailure.at.toISOString() }
+                : null,
+            lastDisconnect: this.lastDisconnect
+                ? { code: this.lastDisconnect.code, reason: this.lastDisconnect.reason, at: this.lastDisconnect.at.toISOString() }
+                : null,
+            lastError: this.lastError
+                ? { message: this.lastError.message, at: this.lastError.at.toISOString() }
+                : null,
+            lastMessageAt: this.connectionManager.getLastMessageTime()?.toISOString() ?? null,
+            lastRequestSentAt: null,
+            pendingRequests: this.requestTracker.getPendingCount(),
+            pendingRequestDetails: this.requestTracker.getPendingDetails(),
+            connections: connectionInfos,
+            webSocketListening: false,
+            serverLegacyEnabled: this.serverLegacyEnabled,
+            serverName: this.serverName,
+            serverVersion: this.serverVersion,
+            maxConcurrentConnections: this.maxConcurrentConnections,
+            maxPendingRequests: 100,
+            heartbeatIntervalMs: 30000
+        };
+    }
+    async sendAutomationRequest(action, payload = {}, options = {}) {
+        if (!this.isConnected()) {
+            if (this.enabled) {
+                this.log.info('Automation bridge not connected, attempting lazy connection...');
+                if (!this.connectionPromise) {
+                    this.connectionPromise = new Promise((resolve, reject) => {
+                        const onConnect = () => {
+                            cleanup();
+                            resolve();
+                        };
+                        const onError = (err) => {
+                            cleanup();
+                            reject(err);
+                        };
+                        const onHandshakeFail = (err) => {
+                            cleanup();
+                            reject(new Error(`Handshake failed: ${err.reason}`));
+                        };
+                        const cleanup = () => {
+                            this.off('connected', onConnect);
+                            this.off('error', onError);
+                            this.off('handshakeFailed', onHandshakeFail);
+                            if (this.connectionPromise)
+                                this.connectionPromise = undefined;
+                        };
+                        this.once('connected', onConnect);
+                        this.once('error', onError);
+                        this.once('handshakeFailed', onHandshakeFail);
+                        try {
+                            this.startClient();
+                        }
+                        catch (e) {
+                            onError(e);
+                        }
+                    });
+                }
+                try {
+                    const connectTimeout = 5000;
+                    await Promise.race([
+                        this.connectionPromise,
+                        new Promise((_, reject) => setTimeout(() => reject(new Error('Lazy connection timeout')), connectTimeout))
+                    ]);
+                }
+                catch (err) {
+                    this.log.error('Lazy connection failed', err);
+                    throw new Error(`Failed to establish connection to Unreal Engine: ${err.message}`);
+                }
+            }
+            else {
+                throw new Error('Automation bridge disabled');
+            }
+        }
+        if (!this.isConnected()) {
+            throw new Error('Automation bridge not connected');
+        }
+        if (this.requestTracker.getPendingCount() >= this.requestTracker.maxPendingRequests) {
+            return new Promise((resolve, reject) => {
+                this.queuedRequestItems.push({
+                    resolve,
+                    reject,
+                    action,
+                    payload,
+                    options
+                });
+            });
+        }
+        return this.sendRequestInternal(action, payload, options);
+    }
+    async sendRequestInternal(action, payload, options) {
+        const timeoutMs = options.timeoutMs ?? 60000;
+        const coalesceKey = this.requestTracker.createCoalesceKey(action, payload);
+        if (coalesceKey) {
+            const existing = this.requestTracker.getCoalescedRequest(coalesceKey);
+            if (existing) {
+                return existing;
+            }
+        }
+        const { requestId, promise } = this.requestTracker.createRequest(action, payload, timeoutMs);
+        if (coalesceKey) {
+            this.requestTracker.setCoalescedRequest(coalesceKey, promise);
+        }
+        const message = {
+            type: 'automation_request',
+            requestId,
+            action,
+            payload
+        };
+        const resultPromise = promise;
+        resultPromise.finally(() => {
+            this.processRequestQueue();
+        }).catch(() => { });
+        if (this.send(message)) {
+            return resultPromise;
+        }
+        else {
+            this.requestTracker.rejectRequest(requestId, new Error('Failed to send request'));
+            throw new Error('Failed to send request');
+        }
+    }
+    processRequestQueue() {
+        if (this.queuedRequestItems.length === 0)
+            return;
+        while (this.queuedRequestItems.length > 0 &&
+            this.requestTracker.getPendingCount() < this.requestTracker.maxPendingRequests) {
+            const item = this.queuedRequestItems.shift();
+            if (item) {
+                this.sendRequestInternal(item.action, item.payload, item.options)
+                    .then(item.resolve)
+                    .catch(item.reject);
+            }
+        }
+    }
+    send(payload) {
+        const primarySocket = this.connectionManager.getPrimarySocket();
+        if (!primarySocket || primarySocket.readyState !== WebSocket.OPEN) {
+            this.log.warn('Attempted to send automation message without an active primary connection');
+            return false;
+        }
+        try {
+            primarySocket.send(JSON.stringify(payload));
+            return true;
+        }
+        catch (error) {
+            this.log.error('Failed to send automation message', error);
+            const errObj = error instanceof Error ? error : new Error(String(error));
+            const primaryInfo = this.connectionManager.getActiveSockets().get(primarySocket);
+            const errorWithPort = Object.assign(errObj, { port: primaryInfo?.port });
+            this.emitAutomation('error', errorWithPort);
+            return false;
+        }
+    }
+    broadcast(payload) {
+        const sockets = this.connectionManager.getActiveSockets();
+        if (sockets.size === 0) {
+            this.log.warn('Attempted to broadcast automation message without any active connections');
+            return false;
+        }
+        let sentCount = 0;
+        for (const [socket] of sockets) {
+            if (socket.readyState === WebSocket.OPEN) {
+                try {
+                    socket.send(JSON.stringify(payload));
+                    sentCount++;
+                }
+                catch (error) {
+                    this.log.error('Failed to broadcast automation message to socket', error);
+                }
+            }
+        }
+        return sentCount > 0;
+    }
+    flushQueue() {
+        if (this.requestQueue.length === 0)
+            return;
+        this.log.info(`Flushing ${this.requestQueue.length} queued automation requests`);
+        const queue = [...this.requestQueue];
+        this.requestQueue = [];
+        queue.forEach(fn => fn());
+    }
+    emitAutomation(event, ...args) {
+        this.emit(event, ...args);
+    }
+}
+//# sourceMappingURL=bridge.js.map

package/dist/automation/connection-manager.d.ts

@@ -0,0 +1,23 @@
+import { WebSocket } from 'ws';
+import { SocketInfo } from './types.js';
+import { EventEmitter } from 'node:events';
+export declare class ConnectionManager extends EventEmitter {
+    private heartbeatIntervalMs;
+    private activeSockets;
+    private primarySocket?;
+    private heartbeatTimer?;
+    private lastMessageAt?;
+    private log;
+    constructor(heartbeatIntervalMs: number);
+    registerSocket(socket: WebSocket, port: number, metadata?: Record<string, unknown>, remoteAddress?: string, remotePort?: number): void;
+    removeSocket(socket: WebSocket): SocketInfo | undefined;
+    getActiveSockets(): Map<WebSocket, SocketInfo>;
+    getPrimarySocket(): WebSocket | undefined;
+    isConnected(): boolean;
+    startHeartbeat(): void;
+    stopHeartbeat(): void;
+    updateLastMessageTime(): void;
+    getLastMessageTime(): Date | undefined;
+    closeAll(code?: number, reason?: string): void;
+}
+//# sourceMappingURL=connection-manager.d.ts.map

package/dist/automation/connection-manager.js

@@ -0,0 +1,107 @@
+import { WebSocket } from 'ws';
+import { Logger } from '../utils/logger.js';
+import { randomUUID } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+export class ConnectionManager extends EventEmitter {
+    heartbeatIntervalMs;
+    activeSockets = new Map();
+    primarySocket;
+    heartbeatTimer;
+    lastMessageAt;
+    log = new Logger('ConnectionManager');
+    constructor(heartbeatIntervalMs) {
+        super();
+        this.heartbeatIntervalMs = heartbeatIntervalMs;
+    }
+    registerSocket(socket, port, metadata, remoteAddress, remotePort) {
+        const connectionId = randomUUID();
+        const sessionId = metadata && typeof metadata.sessionId === 'string' ? metadata.sessionId : undefined;
+        const socketInfo = {
+            connectionId,
+            port,
+            connectedAt: new Date(),
+            protocol: socket.protocol || undefined,
+            sessionId,
+            remoteAddress: remoteAddress ?? undefined,
+            remotePort: typeof remotePort === 'number' ? remotePort : undefined
+        };
+        this.activeSockets.set(socket, socketInfo);
+        if (!this.primarySocket) {
+            this.primarySocket = socket;
+        }
+        socket.on('pong', () => {
+            this.lastMessageAt = new Date();
+        });
+    }
+    removeSocket(socket) {
+        const info = this.activeSockets.get(socket);
+        if (info) {
+            this.activeSockets.delete(socket);
+            if (socket === this.primarySocket) {
+                this.primarySocket = this.activeSockets.size > 0 ? this.activeSockets.keys().next().value : undefined;
+                if (this.activeSockets.size === 0) {
+                    this.stopHeartbeat();
+                }
+            }
+        }
+        return info;
+    }
+    getActiveSockets() {
+        return this.activeSockets;
+    }
+    getPrimarySocket() {
+        return this.primarySocket;
+    }
+    isConnected() {
+        return this.activeSockets.size > 0;
+    }
+    startHeartbeat() {
+        if (this.heartbeatIntervalMs <= 0)
+            return;
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = setInterval(() => {
+            if (this.activeSockets.size === 0) {
+                this.stopHeartbeat();
+                return;
+            }
+            const pingPayload = JSON.stringify({
+                type: 'bridge_ping',
+                timestamp: new Date().toISOString()
+            });
+            for (const [socket] of this.activeSockets) {
+                if (socket.readyState === WebSocket.OPEN) {
+                    try {
+                        socket.ping();
+                        socket.send(pingPayload);
+                    }
+                    catch (error) {
+                        this.log.error('Failed to send heartbeat', error);
+                    }
+                }
+            }
+        }, this.heartbeatIntervalMs);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = undefined;
+        }
+    }
+    updateLastMessageTime() {
+        this.lastMessageAt = new Date();
+    }
+    getLastMessageTime() {
+        return this.lastMessageAt;
+    }
+    closeAll(code, reason) {
+        this.stopHeartbeat();
+        for (const [socket] of this.activeSockets) {
+            socket.removeAllListeners();
+            socket.close(code, reason);
+        }
+        this.activeSockets.clear();
+        this.primarySocket = undefined;
+    }
+}
+//# sourceMappingURL=connection-manager.js.map

package/dist/automation/handshake.d.ts

@@ -0,0 +1,11 @@
+import { WebSocket } from 'ws';
+import { EventEmitter } from 'node:events';
+export declare class HandshakeHandler extends EventEmitter {
+    private capabilityToken?;
+    private log;
+    private readonly DEFAULT_HANDSHAKE_TIMEOUT_MS;
+    constructor(capabilityToken?: string | undefined);
+    initiateHandshake(socket: WebSocket, timeoutMs?: number): Promise<Record<string, unknown>>;
+    private sanitizeHandshakeMetadata;
+}
+//# sourceMappingURL=handshake.d.ts.map

package/dist/automation/handshake.js

@@ -0,0 +1,89 @@
+import { WebSocket } from 'ws';
+import { Logger } from '../utils/logger.js';
+import { EventEmitter } from 'node:events';
+export class HandshakeHandler extends EventEmitter {
+    capabilityToken;
+    log = new Logger('HandshakeHandler');
+    DEFAULT_HANDSHAKE_TIMEOUT_MS = 5000;
+    constructor(capabilityToken) {
+        super();
+        this.capabilityToken = capabilityToken;
+    }
+    initiateHandshake(socket, timeoutMs = this.DEFAULT_HANDSHAKE_TIMEOUT_MS) {
+        return new Promise((resolve, reject) => {
+            let handshakeComplete = false;
+            const timeout = setTimeout(() => {
+                if (!handshakeComplete) {
+                    this.log.warn('Automation bridge client handshake timed out');
+                    socket.close(4002, 'Handshake timeout');
+                    reject(new Error('Handshake timeout'));
+                }
+            }, timeoutMs);
+            const onMessage = (data) => {
+                let parsed;
+                const text = typeof data === 'string' ? data : data.toString('utf8');
+                try {
+                    parsed = JSON.parse(text);
+                }
+                catch (error) {
+                    this.log.error('Received non-JSON automation message during handshake', error);
+                    socket.close(4003, 'Invalid JSON payload');
+                    cleanup();
+                    reject(new Error('Invalid JSON payload'));
+                    return;
+                }
+                if (parsed.type === 'bridge_ack') {
+                    handshakeComplete = true;
+                    cleanup();
+                    const metadata = this.sanitizeHandshakeMetadata(parsed);
+                    resolve(metadata);
+                }
+                else {
+                    this.log.warn(`Expected bridge_ack handshake, received ${parsed.type}`);
+                    socket.close(4004, 'Handshake expected bridge_ack');
+                    cleanup();
+                    reject(new Error(`Handshake expected bridge_ack, got ${parsed.type}`));
+                }
+            };
+            const onError = (error) => {
+                cleanup();
+                reject(error);
+            };
+            const onClose = () => {
+                cleanup();
+                reject(new Error('Socket closed during handshake'));
+            };
+            const cleanup = () => {
+                clearTimeout(timeout);
+                socket.off('message', onMessage);
+                socket.off('error', onError);
+                socket.off('close', onClose);
+            };
+            socket.on('message', onMessage);
+            socket.on('error', onError);
+            socket.on('close', onClose);
+            setTimeout(() => {
+                if (socket.readyState === WebSocket.OPEN) {
+                    const helloPayload = {
+                        type: 'bridge_hello',
+                        capabilityToken: this.capabilityToken || undefined
+                    };
+                    this.log.debug(`Sending bridge_hello (delayed): ${JSON.stringify(helloPayload)}`);
+                    socket.send(JSON.stringify(helloPayload));
+                }
+                else {
+                    this.log.warn('Socket closed before bridge_hello could be sent');
+                }
+            }, 500);
+        });
+    }
+    sanitizeHandshakeMetadata(payload) {
+        const sanitized = { ...payload };
+        delete sanitized.type;
+        if ('capabilityToken' in sanitized) {
+            sanitized.capabilityToken = 'REDACTED';
+        }
+        return sanitized;
+    }
+}
+//# sourceMappingURL=handshake.js.map

package/dist/automation/index.d.ts

@@ -0,0 +1,3 @@
+export { AutomationBridge } from './bridge.js';
+export * from './types.js';
+//# sourceMappingURL=index.d.ts.map