@sstar/embedlink_agent 0.1.0

package/dist/server/web.js

@@ -0,0 +1,2284 @@
+import express from 'express';
+import http from 'http';
+import { WebSocketServer } from 'ws';
+import fs from 'node:fs/promises';
+import fsSync from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import YAML from 'yaml';
+import { boardUartWrite } from '../board_uart/index.js';
+import { closeSession, listBoardUartSessions, openManualSession, startRecording, stopRecording, setDefaultBoardUartHint, buildSessionId, } from '../board_uart/sessions.js';
+import { getBoardUartHistoryLines, setBoardUartHistoryMaxLines } from '../board_uart/history.js';
+import { gatherSshCandidates } from '../ssh/candidates.js';
+import { SshTunnel } from '../ssh/tunnel.js';
+import { SSHAdapter } from '../ssh/adapter.js';
+import { readPasswordFromEnv } from '../secrets/index.js';
+import { loadConfig } from '../config/index.js';
+import { downloadFromExternalTftp, getTftpServerStats, startTftpServer, stopTftpServer, uploadToExternalTftp, listTftpEntries, } from '../tftp/index.js';
+import { ubootBreak, ubootRunCommand } from '../uboot/index.js';
+import { ErrorCodes, DefaultTimeouts } from '../core/errors.js';
+import { saveBoardNotes } from '../board/notes.js';
+import { readDoc, writeDoc, resetDoc } from '../board/docs.js';
+import { getBoardUartResourceManager } from '../board_uart/resource.js';
+import { deleteMacroScript, getMacroScript, listMacroScripts, upsertMacroScript, } from '../macro/index.js';
+import { getCurrentRun, runMacroScript, stopCurrentRun } from '../macro/runner.js';
+import { getAgentLogger, LogLevel } from '../logger.js';
+import { firmwarePrepareImages } from '../firmware/prepare_images.js';
+import { firmwareBurnRecover } from '../firmware/burn_recover.js';
+import { listFiles } from '../files/index.js';
+import { nfsList } from '../nfs/index.js';
+import { getGrpcLastActivity } from '../core/activity.js';
+import { getPlatformInfo } from '../utils/platform.js';
+import { getNetworkInfo } from '../utils/network.js';
+import { getLogSnapshot, subscribeLogs } from '../core/log_stream.js';
+export async function startWebServer(cfg) {
+    // 初始化Agent日志系统
+    const logger = getAgentLogger();
+    // 记录服务器启动信息
+    logger.write(LogLevel.INFO, 'server.starting', {
+        agentId: cfg.agentId,
+        version: cfg.version,
+        port: cfg.port,
+        grpcPort: cfg.grpcPort,
+        pid: process.pid,
+    });
+    const app = express();
+    app.use(express.json());
+    app.get('/health', (_req, res) => res.json({ status: 'ok', pid: process.pid, uptime: process.uptime() }));
+    app.get('/api/status', async (_req, res) => {
+        try {
+            const mod = await import('../board_uart/index.js');
+            const st = await (mod.boardUartStatus?.() || {});
+            const tools = [...(st.attachedTools || [])];
+            const lastGrpc = getGrpcLastActivity();
+            if (Date.now() - lastGrpc < 15000) {
+                if (!tools.includes('mcp-host')) {
+                    tools.push('mcp-host');
+                }
+            }
+            res.json({
+                id: cfg.agentId,
+                version: cfg.version,
+                uptime: process.uptime(),
+                attachedTools: tools,
+            });
+        }
+        catch (e) {
+            res.status(500).json({ error: e?.message || String(e) });
+        }
+    });
+    app.get('/api/network/interfaces', async (_req, res) => {
+        try {
+            const interfaces = await getNetworkInfo();
+            res.json({ interfaces });
+        }
+        catch (e) {
+            res.status(500).json({ error: e?.message || String(e) });
+        }
+    });
+    if (cfg.staticDir) {
+        const pagesDir = path.join(cfg.staticDir, 'pages');
+        if (fsSync.existsSync(pagesDir)) {
+            // 直接将 dist/pages 挂载到根，确保 / 与 /xxx.html 可用
+            app.use(express.static(pagesDir));
+            app.use('/pages', express.static(pagesDir));
+        }
+        app.use(express.static(cfg.staticDir));
+        const assetsDir = path.join(cfg.staticDir, 'assets');
+        app.use('/assets', express.static(assetsDir));
+    }
+    // Board UART ports listing
+    app.get('/api/board_uart/ports', async (_req, res) => {
+        try {
+            // 尝试返回更详细的状态（有模块/被禁用/端口列表）
+            const mod = await import('../board_uart/index.js');
+            const st = await (mod.boardUartStatus?.() || {
+                disabled: false,
+                hasModule: false,
+                ports: [],
+            });
+            let reason;
+            if (st.disabled)
+                reason = 'disabled-by-env';
+            else if (!st.hasModule)
+                reason = 'module-missing';
+            else if (!st.ports?.length)
+                reason = 'no-device';
+            res.json({ ports: st.ports || [], reason });
+        }
+        catch (e) {
+            // 兜底：即使发生异常也不要抛 500
+            res.json({ ports: [], reason: 'unknown' });
+        }
+    });
+    app.get('/api/board_uart/default', async (_req, res) => {
+        try {
+            const conf = await ensureConfigLoaded();
+            res.json({ port: conf.boardUart.port || '', baud: conf.boardUart.baud || 115200 });
+        }
+        catch (e) {
+            res.status(500).json({ error: e?.message || String(e) });
+        }
+    });
+    // Board UART write (base64 data)
+    app.post('/api/board_uart/write', async (req, res) => {
+        try {
+            const { port, baud, data } = req.body || {};
+            if (!port || !baud || !data)
+                return res.status(400).json({ error: 'missing params' });
+            const bytes = await boardUartWrite({
+                port,
+                baud: Number(baud),
+                data: Buffer.from(String(data), 'base64'),
+                mock: false, // 明确禁用 mock
+            });
+            res.json({ ok: true, bytesWritten: bytes });
+        }
+        catch (e) {
+            res.status(500).json({ error: e?.message || String(e), code: e?.code });
+        }
+    });
+    // Board UART open test (no data, just open/close)
+    app.post('/api/board_uart/open', async (req, res) => {
+        try {
+            const { port, baud } = req.body || {};
+            if (!port || !baud)
+                return res.status(400).json({ error: 'missing params' });
+            await boardUartWrite({
+                port,
+                baud: Number(baud),
+                data: Buffer.alloc(0),
+                mock: false,
+            });
+            res.json({ ok: true });
+        }
+        catch (e) {
+            res.status(500).json({ error: e?.message || String(e), code: e?.code });
+        }
+    });
+    app.get('/api/board_uart/sessions', async (_req, res) => {
+        try {
+            const sessions = await listBoardUartSessions();
+            res.json({ sessions });
+        }
+        catch (e) {
+            res.status(500).json({ error: e?.message || String(e), code: e?.code });
+        }
+    });
+    app.post('/api/board_uart/session/open', async (req, res) => {
+        try {
+            const { port, baud } = req.body || {};
+            const session = await openManualSession({ port, baud: Number(baud) });
+            res.json({ session });
+        }
+        catch (e) {
+            res.status(500).json({ error: e?.message || String(e), code: e?.code });
+        }
+    });
+    app.post('/api/board_uart/session/close', async (req, res) => {
+        try {
+            const { sessionId } = req.body || {};
+            const closed = await closeSession(String(sessionId || ''));
+            res.json({ closed });
+        }
+        catch (e) {
+            res.status(500).json({ error: e?.message || String(e), code: e?.code });
+        }
+    });
+    // SSH candidates from ssh config + netstat
+    app.get('/api/ssh/candidates', async (_req, res) => {
+        const hosts = await gatherSshCandidates();
+        res.json({ hosts });
+    });
+    // SSH defaults (username / key path)
+    app.get('/api/ssh/defaults', async (_req, res) => {
+        try {
+            const c = await loadConfig();
+            const keyPath = c.ssh?.defaultKeyPath;
+            let keyExists = false;
+            if (keyPath) {
+                try {
+                    const st = await fs.stat(keyPath);
+                    keyExists =
+                        typeof st.isFile === 'function' ? st.isFile() : !st.isDirectory();
+                }
+                catch {
+                    keyExists = false;
+                }
+            }
+            const user = cfg.originUser || os.userInfo().username || 'user';
+            res.json({
+                user,
+                defaultKeyPath: keyPath,
+                keyExists,
+                enablePasswordFallback: !!c.ssh?.enablePasswordFallback,
+            });
+        }
+        catch (e) {
+            res.status(500).json({ error: e?.message || String(e) });
+        }
+    });
+    // File listing for Custom Browser
+    app.post('/api/files/list', async (req, res) => {
+        try {
+            const { path } = req.body || {};
+            const result = await listFiles(path);
+            res.json(result);
+        }
+        catch (e) {
+            res.status(500).json({ ok: false, error: e?.message || String(e) });
+        }
+    });
+    // Path check for TFTP dir
+    app.get('/api/path/exists', async (req, res) => {
+        const dir = String(req.query.dir || '');
+        try {
+            const st = await fs.stat(dir);
+            res.json({ ok: st.isDirectory() });
+        }
+        catch {
+            res.json({ ok: false });
+        }
+    });
+    // Open directory in system file manager
+    app.post('/api/path/open', async (req, res) => {
+        const dir = String(req.body?.dir || '');
+        if (!dir)
+            return res.status(400).json({ error: 'missing dir' });
+        try {
+            await fs.mkdir(dir, { recursive: true });
+            const platform = process.platform;
+            let cmd;
+            let args;
+            if (platform === 'win32') {
+                cmd = 'cmd';
+                args = ['/c', 'start', '', dir];
+            }
+            else if (platform === 'darwin') {
+                cmd = 'open';
+                args = [dir];
+            }
+            else {
+                cmd = 'xdg-open';
+                args = [dir];
+            }
+            try {
+                const child = spawn(cmd, args, { detached: true, stdio: 'ignore' });
+                child.unref();
+            }
+            catch {
+                // 打开失败不影响 HTTP 返回
+            }
+            res.json({ ok: true, dir });
+        }
+        catch (e) {
+            res.status(500).json({ error: e?.message || String(e) });
+        }
+    });
+    async function pickDirectoryDialog() {
+        const platform = process.platform;
+        if (platform === 'win32') {
+            const script = '$ErrorActionPreference = "Stop";' +
+                'Add-Type -AssemblyName System.Windows.Forms;' +
+                '$f = New-Object System.Windows.Forms.FolderBrowserDialog;' +
+                '$f.Description = "选择目录";' +
+                '$f.ShowNewFolderButton = $true;' +
+                'if ($f.ShowDialog() -eq [System.Windows.Forms.DialogResult]::OK) { Write-Output $f.SelectedPath }';
+            return await new Promise((resolve, reject) => {
+                const child = spawn('powershell', ['-NoProfile', '-Command', script], {
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                });
+                let out = '';
+                let err = '';
+                child.stdout.on('data', (d) => (out += d.toString()));
+                child.stderr.on('data', (d) => (err += d.toString()));
+                child.on('error', (e) => reject(e));
+                child.on('close', (code) => {
+                    if (code === 0 && out.trim())
+                        return resolve(out.trim());
+                    if (code === 0)
+                        return resolve(null);
+                    reject(new Error(err.trim() || `powershell exited with code ${code}`));
+                });
+            });
+        }
+        if (platform === 'darwin') {
+            return await new Promise((resolve, reject) => {
+                const script = 'try\n' +
+                    '  set theFolder to choose folder with prompt "选择目录"\n' +
+                    '  POSIX path of theFolder\n' +
+                    'on error number -128\n' +
+                    '  return ""\n' +
+                    'end try';
+                const child = spawn('osascript', ['-e', script], {
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                });
+                let out = '';
+                let err = '';
+                child.stdout.on('data', (d) => (out += d.toString()));
+                child.stderr.on('data', (d) => (err += d.toString()));
+                child.on('error', (e) => reject(e));
+                child.on('close', (code) => {
+                    if (code === 0) {
+                        const p = out.trim();
+                        return resolve(p || null);
+                    }
+                    reject(new Error(err.trim() || `osascript exited with code ${code}`));
+                });
+            });
+        }
+        // Linux / 其他 Unix：尝试使用 zenity
+        return await new Promise((resolve, reject) => {
+            const child = spawn('zenity', ['--file-selection', '--directory', '--title=选择目录'], {
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            let out = '';
+            let err = '';
+            child.stdout.on('data', (d) => (out += d.toString()));
+            child.stderr.on('data', (d) => (err += d.toString()));
+            child.on('error', (e) => reject(e));
+            child.on('close', (code) => {
+                if (code === 0) {
+                    const p = out.trim();
+                    return resolve(p || null);
+                }
+                if (code === 1) {
+                    // 用户取消
+                    return resolve(null);
+                }
+                reject(new Error(err.trim() || `zenity exited with code ${code}`));
+            });
+        });
+    }
+    // Pick directory via native dialog
+    app.post('/api/path/pick', async (req, res) => {
+        try {
+            const dir = await pickDirectoryDialog();
+            if (!dir) {
+                return res.json({ ok: false, cancelled: true });
+            }
+            const st = await fs.stat(dir).catch(() => null);
+            if (!st || !st.isDirectory()) {
+                return res.status(400).json({ ok: false, error: 'selected path is not a directory' });
+            }
+            res.json({ ok: true, path: dir });
+        }
+        catch (e) {
+            res.status(500).json({ ok: false, error: e?.message || String(e) });
+        }
+    });
+    // Accept uploaded private key (base64)
+    let uploadedKeyMem;
+    app.post('/api/ssh/key', async (req, res) => {
+        const { keyBase64 } = req.body || {};
+        if (!keyBase64)
+            return res.status(400).json({ error: 'missing keyBase64' });
+        uploadedKeyMem = Buffer.from(String(keyBase64), 'base64');
+        res.json({ ok: true, size: uploadedKeyMem.byteLength });
+    });
+    // Accept private key from local path
+    app.post('/api/ssh/key/path', async (req, res) => {
+        const { keyPath } = req.body || {};
+        if (!keyPath)
+            return res.status(400).json({ error: 'missing keyPath' });
+        try {
+            const buf = await fs.readFile(String(keyPath));
+            uploadedKeyMem = buf;
+            res.json({ ok: true, size: uploadedKeyMem.byteLength });
+        }
+        catch (e) {
+            res.status(500).json({ error: e?.message || String(e) });
+        }
+    });
+    // SSH tunnel management (reverse proxy: Host端监听 → 连接回 Agent gRPC)
+    let tunnel;
+    let lastRemotePort;
+    let lastError;
+    let lastErrorCode;
+    let lastSuggestions;
+    let lastDiscoveryPath;
+    let lastParams;
+    let autoReconnect = true;
+    // 监听器管理：防止重复注册导致的内存泄漏
+    const tunnelCleanupListeners = new Set();
+    function addTunnelCleanupListener(cleanupFn) {
+        // 先移除旧的监听器（如果存在）
+        removeTunnelCleanupListeners();
+        tunnelCleanupListeners.add(cleanupFn);
+        server.once('close', cleanupFn);
+        logInfo('tunnel.cleanup_listener_added', {
+            listenerCount: tunnelCleanupListeners.size,
+            maxListeners: server.getMaxListeners(),
+            currentListeners: server.listenerCount('close'),
+        });
+    }
+    function removeTunnelCleanupListeners() {
+        for (const cleanupFn of tunnelCleanupListeners) {
+            server.off('close', cleanupFn);
+        }
+        tunnelCleanupListeners.clear();
+        logInfo('tunnel.cleanup_listeners_removed');
+    }
+    async function cleanupTunnel(reason, additionalCleanup) {
+        logInfo('tunnel.cleanup_start', { reason, hasTunnel: !!tunnel });
+        try {
+            if (tunnel) {
+                await tunnel.stop();
+                tunnel = undefined;
+                lastRemotePort = undefined;
+                // 添加延迟确保端口完全释放
+                await new Promise((resolve) => setTimeout(resolve, 100));
+                logInfo('tunnel.stopped', { reason });
+            }
+            // 执行额外的清理逻辑
+            if (additionalCleanup) {
+                await additionalCleanup();
+            }
+        }
+        catch (e) {
+            logError('tunnel.cleanup_failed', {
+                reason,
+                error: e?.message || String(e),
+            });
+            // 即使失败也要清理引用
+            tunnel = undefined;
+            lastRemotePort = undefined;
+        }
+        // 移除所有相关的清理监听器
+        removeTunnelCleanupListeners();
+        logInfo('tunnel.cleanup_complete', { reason });
+    }
+    // 口令管理：从环境变量读取默认 SSH 密码，仅在内存中持有
+    const sshPasswordSecret = readPasswordFromEnv();
+    function hashPort(username) {
+        const base = 23745;
+        const span = 25745 - 23745 + 1; // inclusive
+        let h = 0;
+        for (let i = 0; i < username.length; i++) {
+            h = (h * 131 + username.charCodeAt(i)) >>> 0;
+        }
+        return base + (h % span);
+    }
+    app.get('/api/ssh/tunnel/status', async (_req, res) => {
+        res.json({
+            connected: !!(tunnel && tunnel.isConnected()),
+            remotePort: lastRemotePort,
+            lastError,
+            code: lastErrorCode,
+            suggestions: lastSuggestions,
+            discoveryPath: lastDiscoveryPath,
+        });
+    });
+    app.post('/api/ssh/tunnel/start', async (req, res) => {
+        const { host, port = 22, user, password, remotePort, bindAddr = '127.0.0.1', keySource = 'default', } = req.body || {};
+        if (!host || !user)
+            return res.status(400).json({
+                error: 'missing host/user',
+                code: 'EL_INVALID_PARAMS',
+                suggestions: ['请填写 SSH 主机与用户名'],
+            });
+        if (!cfg.grpcPort)
+            return res.status(500).json({ error: 'grpcPort unavailable' });
+        try {
+            // 若已存在同一 host/user/port 的隧道，则视为幂等重复调用，直接复用
+            if (tunnel &&
+                tunnel.isConnected() &&
+                lastParams &&
+                lastParams.host === host &&
+                lastParams.user === user &&
+                lastParams.port === Number(port)) {
+                lastError = undefined;
+                lastErrorCode = undefined;
+                lastSuggestions = undefined;
+                return res.json({
+                    connected: true,
+                    remotePort: lastRemotePort,
+                    discoveryPath: lastDiscoveryPath,
+                    reused: true,
+                });
+            }
+            // Probe existing mapping for this user+agent on remote; if active, refuse
+            const agentId = cfg.agentId || 'agent';
+            const probe = await probeRemoteExistingTunnel({
+                host,
+                sshPort: Number(port),
+                user,
+                password,
+                agentId,
+            });
+            if (probe.active && probe.port) {
+                lastError = `existing tunnel active on remote port ${probe.port}`;
+                lastErrorCode = 'EL_SSH_TUNNEL_BROKEN';
+                lastSuggestions = ['复用已存在端口', '停止其他 Agent 隧道后再试'];
+                lastDiscoveryPath = probe.path;
+                return res.status(409).json({
+                    error: lastError,
+                    code: lastErrorCode,
+                    suggestions: lastSuggestions,
+                    remotePort: probe.port,
+                    discoveryPath: lastDiscoveryPath,
+                });
+            }
+            await cleanupTunnel('probe_existing_tunnel');
+            // 确保私钥已正确加载
+            let privateKey = uploadedKeyMem;
+            if (keySource === 'default' && !privateKey) {
+                try {
+                    const c = await loadConfig();
+                    if (c.ssh?.defaultKeyPath) {
+                        privateKey = await fs.readFile(c.ssh.defaultKeyPath);
+                    }
+                }
+                catch (e) {
+                    console.debug('Failed to read default SSH key:', e?.message || String(e));
+                }
+            }
+            // First try requested port, else fallback to username-hash mapping
+            const userName = os.userInfo().username || 'user';
+            const basePort = remotePort ? Number(remotePort) : hashPort(user);
+            // Build a list of ports to try (base port + 10 alternatives)
+            const tryPorts = [];
+            for (let i = 0; i <= 10; i++) {
+                tryPorts.push(basePort + i);
+            }
+            let bound;
+            let portBindingError;
+            for (const p of tryPorts) {
+                try {
+                    // Ensure previous tunnel is fully stopped before creating new one
+                    await cleanupTunnel(`port_binding_failed_${p}`);
+                    tunnel = new SshTunnel();
+                    const r = await tunnel.start({
+                        host,
+                        port: Number(port),
+                        user,
+                        password: password || sshPasswordSecret.value,
+                        privateKey,
+                        bindAddr,
+                        bindPort: Number(p),
+                        dstHost: '127.0.0.1',
+                        dstPort: Number(cfg.grpcPort),
+                    });
+                    bound = r.bindPort;
+                    portBindingError = undefined;
+                    break;
+                }
+                catch (e) {
+                    portBindingError = e?.message || String(e);
+                    console.warn(`Failed to bind port ${p}:`, portBindingError);
+                    // Clean up failed tunnel properly
+                    await cleanupTunnel(`port_binding_cleanup_${p}`);
+                }
+            }
+            if (!bound)
+                throw new Error(portBindingError || 'bind failed');
+            lastRemotePort = bound;
+            lastParams = { host, port: Number(port), user, password, bindAddr, keySource };
+            // 添加清理监听器：在Server关闭时自动清理隧道
+            addTunnelCleanupListener(async () => {
+                await cleanupTunnel('server_shutdown');
+            });
+            // 验证SSH隧道连通性后再写入agent.json
+            // 此时tunnel一定存在，因为bound不是undefined意味着隧道建立成功
+            const isTunnelReady = await tunnel.verifyConnectivity(5000);
+            if (!isTunnelReady) {
+                throw new Error('SSH tunnel established but connectivity verification failed');
+            }
+            try {
+                const originHost = os.hostname();
+                const originUser = cfg.originUser || os.userInfo().username || 'user';
+                const pairCode = cfg.pairCode;
+                const startupTime = cfg.startupTime;
+                lastDiscoveryPath = await writeRemoteAgentJson(tunnel, {
+                    port: bound,
+                    agentId,
+                    user,
+                    originHost,
+                    originUser,
+                    pairCode,
+                    version: '0.1.0',
+                    startupTime,
+                    sshHost: host,
+                    sshPort: Number(port),
+                });
+            }
+            catch { }
+            lastError = undefined;
+            lastErrorCode = undefined;
+            lastSuggestions = undefined;
+            res.json({ connected: true, remotePort: bound, discoveryPath: lastDiscoveryPath });
+        }
+        catch (e) {
+            const fe = friendlyError(e);
+            lastError = fe.message;
+            lastErrorCode = fe.code;
+            lastSuggestions = fe.suggestions;
+            res.status(500).json({ error: fe.message, code: fe.code, suggestions: fe.suggestions });
+        }
+    });
+    app.post('/api/ssh/tunnel/stop', async (_req, res) => {
+        try {
+            await cleanupTunnel('manual_stop_api');
+            res.json({ stopped: true });
+        }
+        catch (e) {
+            // Always clear the tunnel reference even if stop fails
+            tunnel = undefined;
+            lastRemotePort = undefined;
+            res.status(500).json({ error: e?.message || String(e) });
+        }
+    });
+    // Test SSH connectivity (no tunnel)
+    app.post('/api/ssh/test', async (req, res) => {
+        const { host, port = 22, user, password, keySource = 'default', } = req.body || {};
+        if (!host || !user) {
+            return res.status(400).json({
+                ok: false,
+                error: 'missing host/user',
+                code: 'EL_INVALID_PARAMS',
+                suggestions: ['请填写 SSH 主机和用户名'],
+            });
+        }
+        // 加载默认私钥（如果使用默认私钥选项）
+        if (keySource === 'default') {
+            try {
+                const c = await loadConfig();
+                if (c.ssh?.defaultKeyPath) {
+                    uploadedKeyMem = await fs.readFile(c.ssh.defaultKeyPath);
+                }
+            }
+            catch (e) {
+                // 私钥读取失败时，uploadedKeyMem 保持原状
+                // SSH连接会返回相应的错误信息
+                console.debug('Failed to read default SSH key:', e?.message || String(e));
+            }
+        }
+        try {
+            const ssh2 = await import('ssh2');
+            const ClientCtor = ssh2.Client;
+            const client = new ClientCtor();
+            await new Promise((resolve, reject) => {
+                client
+                    .on('ready', () => {
+                    try {
+                        client.end();
+                    }
+                    catch { }
+                    resolve();
+                })
+                    .on('error', (e) => {
+                    try {
+                        client.end();
+                    }
+                    catch { }
+                    reject(e);
+                })
+                    .connect({
+                    host,
+                    port: Number(port),
+                    username: user,
+                    password: password || sshPasswordSecret.value,
+                    privateKey: uploadedKeyMem,
+                    tryKeyboard: false,
+                });
+            });
+            res.json({ ok: true });
+        }
+        catch (e) {
+            const fe = friendlyError(e);
+            res
+                .status(500)
+                .json({ ok: false, error: fe.message, code: fe.code, suggestions: fe.suggestions });
+        }
+    });
+    // Auto-reconnect loop (simple fixed interval)
+    setInterval(async () => {
+        if (!autoReconnect)
+            return;
+        if (!lastParams)
+            return;
+        if (tunnel && tunnel.isConnected())
+            return;
+        try {
+            // Ensure previous tunnel is fully stopped before creating new one
+            await cleanupTunnel('auto_reconnect_start');
+            // 确保私钥已正确加载（自动重连场景）
+            let privateKey = uploadedKeyMem;
+            if (lastParams.keySource === 'default' && !privateKey) {
+                try {
+                    const c = await loadConfig();
+                    if (c.ssh?.defaultKeyPath) {
+                        privateKey = await fs.readFile(c.ssh.defaultKeyPath);
+                    }
+                }
+                catch (e) {
+                    console.debug('Failed to read default SSH key for auto-reconnect:', e?.message || String(e));
+                }
+            }
+            const userName = os.userInfo().username || 'user';
+            const basePort = lastRemotePort || hashPort(userName) || 23745;
+            // Try multiple ports for auto-reconnect as well
+            const tryPorts = [];
+            for (let i = 0; i <= 10; i++) {
+                tryPorts.push(basePort + i);
+            }
+            let connected = false;
+            for (const p of tryPorts) {
+                try {
+                    tunnel = new SshTunnel();
+                    const r = await tunnel.start({
+                        host: lastParams.host,
+                        port: lastParams.port,
+                        user: lastParams.user,
+                        password: lastParams.password,
+                        privateKey,
+                        bindAddr: lastParams.bindAddr,
+                        bindPort: p,
+                        dstHost: '127.0.0.1',
+                        dstPort: Number(cfg.grpcPort),
+                    });
+                    lastRemotePort = r.bindPort;
+                    connected = true;
+                    // 为自动重连的隧道添加清理监听器
+                    addTunnelCleanupListener(async () => {
+                        await cleanupTunnel('auto_reconnect_server_shutdown');
+                    });
+                    break;
+                }
+                catch (e) {
+                    console.warn(`Auto-reconnect failed for port ${p}:`, e?.message || String(e));
+                    await cleanupTunnel(`auto_reconnect_port_failed_${p}`);
+                }
+            }
+            if (!connected) {
+                throw new Error('All auto-reconnect attempts failed');
+            }
+            // 验证SSH隧道连通性后再写入agent.json
+            const isTunnelReady = await tunnel.verifyConnectivity(5000);
+            if (!isTunnelReady) {
+                // 在自动重连中，如果验证失败，清理隧道并跳过本次写入
+                await cleanupTunnel('auto_reconnect_connectivity_failed');
+                return;
+            }
+            try {
+                const originHost = cfg.originHost || os.hostname();
+                const originUser = cfg.originUser || os.userInfo().username || 'user';
+                const pairCode = cfg.pairCode;
+                const startupTime = cfg.startupTime;
+                lastDiscoveryPath = await writeRemoteAgentJson(tunnel, {
+                    port: lastRemotePort,
+                    agentId: cfg.agentId || 'agent',
+                    user: lastParams.user,
+                    originHost,
+                    originUser,
+                    pairCode,
+                    version: '0.1.0',
+                    startupTime,
+                    sshHost: lastParams.host,
+                    sshPort: lastParams.port,
+                });
+            }
+            catch { }
+            lastError = undefined;
+            lastErrorCode = undefined;
+            lastSuggestions = undefined;
+        }
+        catch (e) {
+            const fe = friendlyError(e);
+            lastError = fe.message;
+            lastErrorCode = fe.code;
+            lastSuggestions = fe.suggestions;
+            // Ensure tunnel is cleaned up on failure
+            await cleanupTunnel('auto_reconnect_exception');
+        }
+    }, 5000);
+    // 定期监控监听器数量，防止内存泄漏
+    setInterval(() => {
+        const closeListenerCount = server.listenerCount('close');
+        const maxListeners = server.getMaxListeners();
+        // 监控常见事件的监听器数量
+        const commonEvents = ['close', 'error', 'listening', 'request', 'connection'];
+        const totalListeners = commonEvents.reduce((sum, eventName) => {
+            return sum + server.listenerCount(eventName);
+        }, 0);
+        if (closeListenerCount > maxListeners * 0.8) {
+            // 超过80%时警告
+            logInfo('server.listeners_warning', {
+                closeListeners: closeListenerCount,
+                maxListeners,
+                totalListeners,
+                tunnelCleanupListeners: tunnelCleanupListeners.size,
+                utilization: `${Math.round((closeListenerCount / maxListeners) * 100)}%`,
+            });
+        }
+        // 定期记录监听器状态（每分钟一次）
+        if (Math.random() < 0.2) {
+            // 20% 概率，避免日志过多
+            logInfo('server.listeners_status', {
+                closeListeners: closeListenerCount,
+                maxListeners,
+                totalListeners,
+                tunnelCleanupListeners: tunnelCleanupListeners.size,
+                commonEventCounts: commonEvents.map((event) => ({
+                    event,
+                    count: server.listenerCount(event),
+                })),
+            });
+        }
+    }, 60000); // 每分钟检查一次
+    // Auto-reconnect toggle
+    app.get('/api/ssh/tunnel/auto', (_req, res) => res.json({ enable: autoReconnect }));
+    app.post('/api/ssh/tunnel/auto', (req, res) => {
+        autoReconnect = !!req.body?.enable;
+        res.json({ enable: autoReconnect });
+    });
+    // Config read/write
+    let currentConfig = cfg.agentConfig ?? null;
+    const configPathCandidates = [
+        path.join(os.homedir(), '.config', 'embed_link', 'config.json'),
+        path.join(process.cwd(), 'agent.config.yaml'),
+        path.join(process.cwd(), 'agent.config.yml'),
+        path.join(process.cwd(), 'agent.config.json'),
+    ];
+    async function ensureConfigLoaded() {
+        if (currentConfig) {
+            return currentConfig;
+        }
+        currentConfig = await loadConfig();
+        return currentConfig;
+    }
+    function resolveConfigPath() {
+        // 始终优先使用用户主目录下的配置文件路径
+        return configPathCandidates[0];
+    }
+    app.get('/api/config', async (_req, res) => {
+        try {
+            const c = await ensureConfigLoaded();
+            res.json({
+                config: c,
+                pairCode: cfg.pairCode,
+                agentId: cfg.agentId,
+                startupTime: cfg.startupTime,
+            });
+        }
+        catch (e) {
+            res.status(500).json({ error: e?.message || String(e) });
+        }
+    });
+    app.put('/api/config', async (req, res) => {
+        try {
+            const incoming = req.body?.config || {};
+            const apply = !!req.body?.apply;
+            const base = await ensureConfigLoaded();
+            const merged = { ...base, ...incoming };
+            const tftpConfigChanged = JSON.stringify(base.tftp?.server) !== JSON.stringify(merged.tftp?.server);
+            // 落盘
+            const target = resolveConfigPath();
+            const out = target.endsWith('.json') || target.endsWith('.json5')
+                ? JSON.stringify(merged, null, 2)
+                : YAML.stringify(merged);
+            await fs.mkdir(path.dirname(target), { recursive: true });
+            await fs.writeFile(target, out, 'utf8');
+            if (apply) {
+                Object.assign(base, merged);
+                if (tftpConfigChanged) {
+                    const serverConfig = merged.tftp?.server;
+                    if (serverConfig?.enabled && serverConfig.mode !== 'disabled') {
+                        await startTftpServer(merged);
+                        logInfo('tftp.started', { config: serverConfig });
+                    }
+                    else {
+                        await stopTftpServer();
+                        logInfo('tftp.stopped', { reason: 'config_disabled' });
+                    }
+                }
+            }
+            setDefaultBoardUartHint(merged.boardUart.port, merged.boardUart.baud);
+            logInfo('config.saved', { path: target });
+            res.json({ ok: true, path: target });
+        }
+        catch (e) {
+            logError('config.save_failed', { error: e?.message || String(e) });
+            res.status(500).json({ error: e?.message || String(e) });
+        }
+    });
+    async function selftestExternalTftp(host, port) {
+        const id = randomUUID();
+        const remoteSubpath = `__embedlink_test/${id}.bin`;
+        const payload = Buffer.from(`embedlink-tftp-selfcheck-${id}`, 'utf8');
+        const start = Date.now();
+        await uploadToExternalTftp(host, port, remoteSubpath, payload);
+        const r = await downloadFromExternalTftp(host, port, remoteSubpath);
+        const ok = r.size === payload.length && r.content.equals(payload);
+        const cost = Date.now() - start;
+        if (ok) {
+            return {
+                ok: true,
+                message: `ok, host=${host}:${port}, rtt=${cost}ms`,
+            };
+        }
+        return {
+            ok: false,
+            message: `content mismatch from ${host}:${port}`,
+        };
+    }
+    function normalizePosixSubpath(subpath) {
+        if (!subpath)
+            return '';
+        const replaced = subpath.replace(/\\/g, '/');
+        const parts = replaced.split('/').filter((p) => p && p !== '.' && p !== '..');
+        return parts.join('/');
+    }
+    // TFTP files listing
+    app.get('/api/tftp/files', async (req, res) => {
+        try {
+            const c = await ensureConfigLoaded();
+            const subpath = String(req.query.path || '').trim();
+            const result = await listTftpEntries(c.tftp.dir, subpath || undefined, 1);
+            // listTftpEntries 会把起始目录本身也作为一条 entry 返回，
+            // Web UI 只关心"当前目录的子项"，这里过滤掉这条"自身"记录
+            const baseRel = normalizePosixSubpath(subpath || undefined);
+            const files = result.entries
+                .filter((entry) => !entry.isDirectory)
+                .map((entry) => {
+                const tftpEntry = entry;
+                return {
+                    name: entry.path.split('/').pop() || entry.path,
+                    path: entry.path,
+                    size: tftpEntry.sizeBytes,
+                };
+            });
+            const directories = result.entries
+                .filter((entry) => entry.isDirectory && entry.path !== baseRel)
+                .map((entry) => ({
+                name: entry.path.split('/').pop() || entry.path,
+                path: entry.path,
+            }));
+            res.json({ files, directories });
+        }
+        catch (e) {
+            res.status(500).json({ error: e?.message || String(e) });
+        }
+    });
+    // NFS files listing
+    app.get('/api/nfs/files', async (req, res) => {
+        try {
+            const c = await ensureConfigLoaded();
+            if (!c.nfs?.enabled || !c.nfs?.localPath) {
+                return res.status(400).json({ error: 'NFS is not configured or disabled' });
+            }
+            const subpath = String(req.query.path || '').trim();
+            const result = await nfsList(c.nfs.localPath, subpath || undefined, 'detailed');
+            const baseRel = normalizePosixSubpath(subpath || undefined);
+            const files = result.entries
+                .filter((entry) => !entry.isDirectory)
+                .map((entry) => {
+                const detailedEntry = entry;
+                return {
+                    name: entry.name, // 直接使用name字段
+                    size: detailedEntry.sizeBytes,
+                };
+            });
+            const directories = result.entries
+                .filter((entry) => entry.isDirectory)
+                .map((entry) => ({
+                name: entry.name, // 直接使用name字段
+            }));
+            res.json({ files, directories });
+        }
+        catch (e) {
+            res.status(500).json({ error: e?.message || String(e) });
+        }
+    });
+    // External TFTP quick self-test
+    app.get('/api/tftp/external/selftest', async (req, res) => {
+        try {
+            const c = await ensureConfigLoaded();
+            const mode = c.tftp?.server?.mode || 'builtin';
+            if (mode !== 'external') {
+                return res.status(400).json({ ok: false, error: 'tftp server mode is not external' });
+            }
+            const hostParam = String(req.query.host || '').trim();
+            const portParam = Number(req.query.port || 0);
+            const host = hostParam || c.tftp?.server?.externalHost || '';
+            const port = portParam || c.tftp?.server?.externalPort || 69;
+            if (!host || !host.trim()) {
+                return res.status(400).json({ ok: false, error: 'externalHost not set for TFTP' });
+            }
+            const r = await selftestExternalTftp(host, port);
+            res.json({ ok: r.ok, message: r.message, host, port });
+        }
+        catch (e) {
+            res.status(500).json({ ok: false, error: e?.message || String(e) });
+        }
+    });
+    // TFTP server control endpoints
+    app.get('/api/tftp/status', async (_req, res) => {
+        try {
+            const stats = await getTftpServerStats();
+            res.json(stats);
+        }
+        catch (e) {
+            res.status(500).json({ error: e?.message || String(e) });
+        }
+    });
+    app.post('/api/tftp/start', async (req, res) => {
+        try {
+            const config = await ensureConfigLoaded();
+            await startTftpServer(config);
+            const stats = await getTftpServerStats();
+            logInfo('tftp.manually_started', { mode: stats.mode, host: stats.host, port: stats.port });
+            res.json({ success: true, stats });
+        }
+        catch (e) {
+            logError('tftp.start_failed', { error: e?.message || String(e) });
+            res.status(500).json({ error: e?.message || String(e) });
+        }
+    });
+    app.post('/api/tftp/stop', async (_req, res) => {
+        try {
+            await stopTftpServer();
+            const stats = await getTftpServerStats();
+            logInfo('tftp.manually_stopped', { reason: 'manual_request' });
+            res.json({ success: true, stats });
+        }
+        catch (e) {
+            logError('tftp.stop_failed', { error: e?.message || String(e) });
+            res.status(500).json({ error: e?.message || String(e) });
+        }
+    });
+    // Self-check
+    app.get('/api/selfcheck', async (_req, res) => {
+        const results = [];
+        try {
+            results.push({ step: 'health', ok: true, message: 'ok' });
+            // PairCheck 由上游调用，这里仅回显配对码存在
+            if (cfg.pairCode) {
+                results.push({ step: 'pairCode', ok: true, message: 'pairCode present' });
+            }
+            else {
+                results.push({ step: 'pairCode', ok: false, message: 'pairCode missing' });
+            }
+            try {
+                const c = await ensureConfigLoaded();
+                if (c.boardUart.port) {
+                    await boardUartWrite({
+                        port: c.boardUart.port,
+                        baud: c.boardUart.baud ?? DefaultTimeouts.boardUart.write,
+                        data: Buffer.alloc(0),
+                        mock: false,
+                    });
+                    results.push({ step: 'boardUart', ok: true, message: `${c.boardUart.port}` });
+                }
+                else {
+                    results.push({ step: 'boardUart', ok: false, message: 'boardUart.port not set' });
+                }
+            }
+            catch (e) {
+                results.push({ step: 'boardUart', ok: false, message: e?.message || String(e) });
+            }
+            try {
+                const c = await ensureConfigLoaded();
+                const mode = c.tftp.server?.mode || 'builtin';
+                const enabled = c.tftp.server?.enabled !== false && mode !== 'disabled';
+                if (!enabled) {
+                    results.push({ step: 'tftp', ok: false, message: 'disabled' });
+                }
+                else if (mode === 'external') {
+                    const host = c.tftp.server?.externalHost;
+                    const port = c.tftp.server?.externalPort || 69;
+                    if (!host || !host.trim()) {
+                        results.push({
+                            step: 'tftp.external',
+                            ok: false,
+                            message: 'externalHost not set',
+                        });
+                    }
+                    else {
+                        try {
+                            const r = await selftestExternalTftp(host, port);
+                            results.push({ step: 'tftp.external', ok: r.ok, message: r.message });
+                        }
+                        catch (e) {
+                            results.push({
+                                step: 'tftp.external',
+                                ok: false,
+                                message: e?.message || String(e),
+                            });
+                        }
+                    }
+                }
+                else {
+                    // builtin 模式：检查目录与服务器状态
+                    const dir = c.tftp.dir;
+                    let dirOk = false;
+                    try {
+                        const st = await fs.stat(dir);
+                        dirOk = st.isDirectory();
+                    }
+                    catch {
+                        dirOk = false;
+                    }
+                    const stats = await getTftpServerStats();
+                    const ok = dirOk && stats.enabled && stats.isRunning;
+                    const parts = [];
+                    parts.push(`dir=${dirOk ? dir : 'missing'}`);
+                    if (stats.mode === 'builtin') {
+                        const host = stats.host || '0.0.0.0';
+                        const port = stats.port || 69;
+                        parts.push(`server=${stats.isRunning ? 'running' : 'stopped'}@${host}:${port}`);
+                    }
+                    else {
+                        parts.push(`serverMode=${stats.mode}`);
+                    }
+                    if (stats.lastError)
+                        parts.push(`error=${stats.lastError}`);
+                    results.push({ step: 'tftp', ok, message: parts.join(', ') });
+                }
+            }
+            catch (e) {
+                results.push({ step: 'tftp', ok: false, message: e?.message || String(e) });
+            }
+            try {
+                const c = await ensureConfigLoaded();
+                results.push({
+                    step: 'nfs',
+                    ok: !!(c.nfs?.enabled && c.nfs?.localPath),
+                    message: c.nfs?.localPath || 'not set',
+                });
+            }
+            catch (e) {
+                results.push({ step: 'nfs', ok: false, message: e?.message || String(e) });
+            }
+            try {
+                const c = await ensureConfigLoaded();
+                const binaryPath = c.firmware?.flashtool?.binaryPath;
+                if (!binaryPath || !binaryPath.trim()) {
+                    results.push({
+                        step: 'flashtool',
+                        ok: false,
+                        message: 'firmware.flashtool.binaryPath not set',
+                    });
+                }
+                else {
+                    try {
+                        const stIsp = await fs.stat(binaryPath);
+                        const ok = typeof stIsp.isFile === 'function'
+                            ? stIsp.isFile()
+                            : !stIsp.isDirectory();
+                        results.push({
+                            step: 'flashtool',
+                            ok,
+                            message: ok ? binaryPath : `not a regular file: ${binaryPath}`,
+                        });
+                    }
+                    catch (e) {
+                        results.push({
+                            step: 'flashtool',
+                            ok: false,
+                            message: e?.message || `binaryPath not accessible: ${binaryPath}`,
+                        });
+                    }
+                }
+            }
+            catch (e) {
+                results.push({ step: 'flashtool', ok: false, message: e?.message || String(e) });
+            }
+            logInfo('selfcheck.done', { results });
+            res.json({ ok: true, results });
+        }
+        catch (e) {
+            res.status(500).json({ ok: false, error: e?.message || String(e), results });
+        }
+    });
+    // Docs read/write
+    app.get('/api/docs/:kind', async (req, res) => {
+        const kind = String(req.params.kind || '');
+        try {
+            const validKinds = ['board-interaction', 'tftp-transfer', 'nfs-mount', 'firmware-upgrade'];
+            if (!validKinds.includes(kind))
+                return res.status(400).json({ error: 'invalid kind' });
+            const { content, path: p } = await readDoc(kind);
+            res.json({ content, format: 'markdown', path: p });
+        }
+        catch (e) {
+            res.status(500).json({ error: e?.message || String(e) });
+        }
+    });
+    app.put('/api/docs/:kind', async (req, res) => {
+        const kind = String(req.params.kind || '');
+        try {
+            const validKinds = ['board-interaction', 'tftp-transfer', 'nfs-mount', 'firmware-upgrade'];
+            if (!validKinds.includes(kind))
+                return res.status(400).json({ error: 'invalid kind' });
+            const content = String(req.body?.content || '');
+            const path = await writeDoc(kind, content);
+            if (kind === 'board-interaction') {
+                await saveBoardNotes(content);
+            }
+            logInfo('docs.saved', { kind, path });
+            res.json({ ok: true, path });
+        }
+        catch (e) {
+            logError('docs.save_failed', { kind, error: e?.message || String(e) });
+            res.status(500).json({ error: e?.message || String(e) });
+        }
+    });
+    app.post('/api/docs/:kind/reset', async (req, res) => {
+        const kind = String(req.params.kind || '');
+        try {
+            const validKinds = ['board-interaction', 'tftp-transfer', 'nfs-mount', 'firmware-upgrade'];
+            if (!validKinds.includes(kind))
+                return res.status(400).json({ error: 'invalid kind' });
+            const p = await resetDoc(kind);
+            if (kind === 'board-interaction') {
+                const { content } = await readDoc(kind);
+                await saveBoardNotes(content);
+            }
+            logInfo('docs.reset', { kind, path: p });
+            res.json({ ok: true, path: p });
+        }
+        catch (e) {
+            logError('docs.reset_failed', { kind, error: e?.message || String(e) });
+            res.status(500).json({ error: e?.message || String(e) });
+        }
+    });
+    // Flash / U-Boot / Reboot helpers
+    app.post('/api/uboot/break', async (req, res) => {
+        try {
+            const { port, baud, timeoutMs } = req.body || {};
+            const sessionId = port && baud ? buildSessionId(port, Number(baud)) : undefined;
+            const r = await ubootBreak({
+                sessionId,
+                timeoutMs: timeoutMs || DefaultTimeouts.uboot.break,
+                mock: false,
+            });
+            res.json(r);
+        }
+        catch (e) {
+            res.status(500).json({ error: e?.message || String(e), code: e?.code });
+        }
+    });
+    app.post('/api/uboot/run', async (req, res) => {
+        try {
+            const { port, baud, command, timeoutMs } = req.body || {};
+            const sessionId = port && baud ? buildSessionId(port, Number(baud)) : undefined;
+            const r = await ubootRunCommand({
+                sessionId,
+                command,
+                timeoutMs: timeoutMs || DefaultTimeouts.uboot.cmd,
+                mock: false,
+            });
+            res.json(r);
+        }
+        catch (e) {
+            res.status(500).json({ error: e?.message || String(e), code: e?.code });
+        }
+    });
+    // Firmware helper endpoints (bridge to firmware.prepare_images / firmware.burn_recover)
+    app.post('/api/firmware/prepare', async (req, res) => {
+        try {
+            const imagesRoot = String(req.body?.imagesRoot || '').trim();
+            if (!imagesRoot) {
+                return res.status(400).json({ error: 'imagesRoot is required' });
+            }
+            const meta = await firmwarePrepareImages({
+                cfg: await ensureConfigLoaded(),
+                imagesRoot,
+            });
+            res.json({ meta }); // 只返回纯字符串
+        }
+        catch (e) {
+            res.status(500).json({ error: e?.message || String(e) });
+        }
+    });
+    app.post('/api/firmware/burn', async (req, res) => {
+        try {
+            const { imagesRoot, args, timeoutMs, force } = req.body || {};
+            if (!Array.isArray(args) || args.length === 0) {
+                return res.status(400).json({ error: 'args must be a non-empty string array' });
+            }
+            const r = await firmwareBurnRecover({
+                cfg: await ensureConfigLoaded(),
+                imagesRoot: typeof imagesRoot === 'string' ? imagesRoot : '',
+                args,
+                timeoutMs: typeof timeoutMs === 'number' ? timeoutMs : 0,
+                force: !!force,
+            });
+            res.json(r);
+        }
+        catch (e) {
+            res.status(500).json({ error: e?.message || String(e) });
+        }
+    });
+    // WebSocket server and broadcast helpers
+    const server = http.createServer(app);
+    // 增加监听器数量限制，防止内存泄漏警告
+    server.setMaxListeners(20);
+    const wss = new WebSocketServer({ server, path: '/ws' });
+    function broadcast(obj) {
+        const str = JSON.stringify(obj);
+        wss.clients.forEach((c) => c.readyState === 1 && c.send(str));
+    }
+    // Stream internal log buffers to subscribed WS clients.
+    // Clients MUST subscribe via `logs.subscribe` for each source they want.
+    //
+    // Optimization goal (per user request):
+    // - Do not JSON.stringify if nobody subscribed.
+    // - Do not iterate all WS clients; keep per-source subscriber sets.
+    const wsLogSubs = new Map();
+    // Optional host-side filtering by hostInstanceId.
+    const wsHostIdSubs = new Map();
+    const wsLogTargets = {
+        agent: new Set(),
+        host: new Set(),
+    };
+    function ensureSubs(ws) {
+        let s = wsLogSubs.get(ws);
+        if (!s) {
+            s = new Set();
+            wsLogSubs.set(ws, s);
+        }
+        return s;
+    }
+    function addAgentSub(ws) {
+        const s = ensureSubs(ws);
+        if (s.has('agent'))
+            return;
+        s.add('agent');
+        wsLogTargets.agent.add(ws);
+    }
+    function removeAgentSub(ws) {
+        const s = ensureSubs(ws);
+        if (!s.has('agent'))
+            return;
+        s.delete('agent');
+        wsLogTargets.agent.delete(ws);
+    }
+    function addHostSub(ws, hostInstanceId) {
+        const s = ensureSubs(ws);
+        if (!s.has('host'))
+            s.add('host');
+        wsLogTargets.host.add(ws);
+        if (hostInstanceId) {
+            wsHostIdSubs.set(ws, hostInstanceId);
+        }
+        else {
+            wsHostIdSubs.delete(ws);
+        }
+    }
+    function removeHostSub(ws) {
+        const s = ensureSubs(ws);
+        if (!s.has('host'))
+            return;
+        s.delete('host');
+        wsLogTargets.host.delete(ws);
+        wsHostIdSubs.delete(ws);
+    }
+    function clearSubs(ws) {
+        const s = wsLogSubs.get(ws);
+        if (!s)
+            return;
+        if (s.has('agent'))
+            wsLogTargets.agent.delete(ws);
+        if (s.has('host'))
+            wsLogTargets.host.delete(ws);
+        wsHostIdSubs.delete(ws);
+        wsLogSubs.delete(ws);
+    }
+    subscribeLogs((source, entry) => {
+        if (source === 'agent') {
+            const targets = wsLogTargets.agent;
+            if (targets.size === 0)
+                return;
+            const str = JSON.stringify({ type: 'agent.log', ...entry });
+            for (const sock of targets) {
+                if (sock.readyState !== 1) {
+                    clearSubs(sock);
+                    continue;
+                }
+                try {
+                    sock.send(str);
+                }
+                catch {
+                    clearSubs(sock);
+                }
+            }
+            return;
+        }
+        // host: filter by per-WS hostInstanceId if set.
+        const targets = wsLogTargets.host;
+        if (targets.size === 0)
+            return;
+        const entryHostId = String(entry.hostInstanceId || '');
+        const str = JSON.stringify({ type: 'host.log', ...entry });
+        for (const sock of targets) {
+            if (sock.readyState !== 1) {
+                clearSubs(sock);
+                continue;
+            }
+            const wantId = wsHostIdSubs.get(sock);
+            if (wantId && wantId !== entryHostId)
+                continue;
+            try {
+                sock.send(str);
+            }
+            catch {
+                clearSubs(sock);
+            }
+        }
+    });
+    function logInfo(event, data) {
+        // 纯文件日志，不再进行WebSocket广播
+        if (logger) {
+            logger.write(LogLevel.INFO, event, data);
+        }
+    }
+    function logError(event, data) {
+        // 纯文件日志，不再进行WebSocket广播
+        if (logger) {
+            logger.write(LogLevel.ERROR, event, data);
+        }
+    }
+    function sendStatus(ws) {
+        try {
+            const platformInfo = getPlatformInfo();
+            ws.send(JSON.stringify({
+                type: 'agent.status',
+                health: 'ok',
+                agentId: cfg.agentId,
+                version: cfg.version,
+                startupTime: cfg.startupTime,
+                originHost: cfg.originHost,
+                originUser: cfg.originUser,
+                pairCode: cfg.pairCode ? `${cfg.pairCode.slice(0, 4)}****` : '',
+                platform: platformInfo.platform,
+                arch: platformInfo.arch,
+                ts: Date.now(),
+            }));
+        }
+        catch { }
+    }
+    wss.on('connection', (ws) => {
+        const boardUartAttachIds = new Set();
+        // default: no log subscriptions until client asks
+        ensureSubs(ws);
+        ws.on('close', () => {
+            clearSubs(ws);
+        });
+        sendStatus(ws);
+        ws.send(JSON.stringify({ type: 'hello', now: Date.now() }));
+        ws.on('message', async (raw) => {
+            let msg;
+            try {
+                msg = JSON.parse(raw.toString('utf8'));
+            }
+            catch {
+                return;
+            }
+            if (!msg || typeof msg !== 'object')
+                return;
+            const mgr = getBoardUartResourceManager();
+            const DEFAULT_EXPECT_TIMEOUT_MS = 5000;
+            const sendMacroError = (err) => {
+                try {
+                    ws.send(JSON.stringify({
+                        type: 'macro.error',
+                        error: err?.message || String(err),
+                    }));
+                }
+                catch { }
+            };
+            const broadcastScripts = async () => {
+                const scripts = await listMacroScripts();
+                broadcast({ type: 'macro.scripts', scripts });
+            };
+            if (msg.type === 'macro.list') {
+                try {
+                    const scripts = await listMacroScripts();
+                    ws.send(JSON.stringify({ type: 'macro.scripts', scripts, running: getCurrentRun() }));
+                }
+                catch (e) {
+                    sendMacroError(e);
+                }
+            }
+            else if (msg.type === 'macro.get') {
+                try {
+                    const id = String(msg.id || '').trim();
+                    if (!id)
+                        throw new Error('missing id');
+                    const script = await getMacroScript(id);
+                    if (!script)
+                        throw new Error('script not found');
+                    ws.send(JSON.stringify({ type: 'macro.script', script }));
+                }
+                catch (e) {
+                    sendMacroError(e);
+                }
+            }
+            else if (msg.type === 'macro.upsert') {
+                try {
+                    const input = msg.script || msg;
+                    const script = await upsertMacroScript({
+                        id: input.id,
+                        name: input.name,
+                        order: input.order,
+                        steps: input.steps,
+                    });
+                    ws.send(JSON.stringify({ type: 'macro.upserted', script }));
+                    await broadcastScripts();
+                }
+                catch (e) {
+                    sendMacroError(e);
+                }
+            }
+            else if (msg.type === 'macro.delete') {
+                try {
+                    const id = String(msg.id || '').trim();
+                    if (!id)
+                        throw new Error('missing id');
+                    const ok = await deleteMacroScript(id);
+                    ws.send(JSON.stringify({ type: 'macro.deleted', id, ok }));
+                    await broadcastScripts();
+                }
+                catch (e) {
+                    sendMacroError(e);
+                }
+            }
+            else if (msg.type === 'macro.run') {
+                try {
+                    const cur = getCurrentRun();
+                    if (cur && cur.status === 'running') {
+                        ws.send(JSON.stringify({ type: 'macro.run_ack', status: 'busy', running: cur }));
+                        return;
+                    }
+                    const scriptId = String(msg.scriptId || '').trim();
+                    if (!scriptId)
+                        throw new Error('missing scriptId');
+                    const script = await getMacroScript(scriptId);
+                    if (!script)
+                        throw new Error('script not found');
+                    const runId = randomUUID();
+                    const sessionId = msg.sessionId ? String(msg.sessionId) : undefined;
+                    ws.send(JSON.stringify({ type: 'macro.run_ack', status: 'running', runId, scriptId }));
+                    void runMacroScript({
+                        runId,
+                        script,
+                        sessionId,
+                        defaultExpectTimeoutMs: DEFAULT_EXPECT_TIMEOUT_MS,
+                        onUpdate: (u) => broadcast({ type: 'macro.run_update', ...u }),
+                    });
+                }
+                catch (e) {
+                    sendMacroError(e);
+                }
+            }
+            else if (msg.type === 'macro.stop') {
+                try {
+                    const ok = stopCurrentRun();
+                    ws.send(JSON.stringify({ type: 'macro.stopped', ok }));
+                    const cur = getCurrentRun();
+                    if (cur)
+                        broadcast({ type: 'macro.run_update', ...cur, message: 'stop requested' });
+                }
+                catch (e) {
+                    sendMacroError(e);
+                }
+            }
+            else if (msg.type === 'macro.status') {
+                try {
+                    ws.send(JSON.stringify({ type: 'macro.status', running: getCurrentRun() }));
+                }
+                catch (e) {
+                    sendMacroError(e);
+                }
+            }
+            else if (msg.type === 'board_uart.status_query') {
+                try {
+                    const st = await mgr.getStatus();
+                    ws.send(JSON.stringify({
+                        type: 'board_uart.status',
+                        status: st.status,
+                        disabled: st.disabled,
+                        hasModule: st.hasModule,
+                        port: st.port,
+                        baud: st.baud,
+                        sessions: st.sessions,
+                        attachedTools: (st.attachedTools || []).map((t) => ({
+                            ...t,
+                            source: t.source || '',
+                            attachedAtMs: t.attachedAt,
+                        })),
+                        suspended: st.suspended,
+                        suspendOwner: st.suspendOwner,
+                        suspendedSinceMs: st.suspendedSinceMs,
+                        maxSuspendMs: st.maxSuspendMs,
+                        autoResumed: st.autoResumed,
+                    }));
+                }
+                catch (e) {
+                    try {
+                        ws.send(JSON.stringify({
+                            type: 'board_uart.error',
+                            error: e?.message || String(e),
+                            code: e?.code,
+                        }));
+                    }
+                    catch { }
+                }
+            }
+            else if (msg.type === 'logs.subscribe') {
+                const src = String(msg.source || '');
+                const hostInstanceId = typeof msg.hostInstanceId === 'string' ? msg.hostInstanceId.trim() : '';
+                if (src === 'agent') {
+                    addAgentSub(ws);
+                }
+                else if (src === 'host') {
+                    addHostSub(ws, hostInstanceId || undefined);
+                }
+                else if (src === 'all') {
+                    addAgentSub(ws);
+                    addHostSub(ws);
+                }
+                try {
+                    ws.send(JSON.stringify({
+                        type: 'logs.subscribed',
+                        source: src || 'all',
+                        hostInstanceId: hostInstanceId || '',
+                    }));
+                }
+                catch { }
+            }
+            else if (msg.type === 'logs.unsubscribe') {
+                const src = String(msg.source || '');
+                if (src === 'agent') {
+                    removeAgentSub(ws);
+                }
+                else if (src === 'host') {
+                    removeHostSub(ws);
+                }
+                else if (src === 'all') {
+                    clearSubs(ws);
+                    ensureSubs(ws);
+                }
+                try {
+                    ws.send(JSON.stringify({ type: 'logs.unsubscribed', source: src || 'all' }));
+                }
+                catch { }
+            }
+            else if (msg.type === 'logs.snapshot_query') {
+                const src = String(msg.source || 'agent');
+                const source = src === 'host' ? 'host' : 'agent';
+                const hostInstanceId = typeof msg.hostInstanceId === 'string' ? msg.hostInstanceId.trim() : '';
+                try {
+                    let entries = getLogSnapshot(source);
+                    if (source === 'host' && hostInstanceId) {
+                        entries = entries.filter((e) => String(e?.hostInstanceId || '') === hostInstanceId);
+                    }
+                    ws.send(JSON.stringify({ type: 'logs.snapshot', source, hostInstanceId, entries }));
+                }
+                catch { }
+            }
+            else if (msg.type === 'board_uart.tools_query') {
+                try {
+                    const st = await mgr.getStatus();
+                    ws.send(JSON.stringify({
+                        type: 'board_uart.tools',
+                        tools: st.attachedTools,
+                    }));
+                }
+                catch { }
+            }
+            else if (msg.type === 'board_uart.start_recording') {
+                const { sessionId } = msg;
+                if (sessionId) {
+                    const root = cfg.agentConfig?.files?.rootDir || cfg.agentConfig?.tftp?.dir || './files';
+                    const logDir = path.join(root, 'logs');
+                    try {
+                        const p = await startRecording(sessionId, logDir);
+                        ws.send(JSON.stringify({ type: 'board_uart.recording_started', sessionId, path: p }));
+                    }
+                    catch (e) {
+                        ws.send(JSON.stringify({ type: 'board_uart.error', error: e?.message || String(e) }));
+                    }
+                }
+            }
+            else if (msg.type === 'board_uart.stop_recording') {
+                const { sessionId } = msg;
+                if (sessionId) {
+                    try {
+                        await stopRecording(sessionId);
+                        ws.send(JSON.stringify({ type: 'board_uart.recording_stopped', sessionId }));
+                    }
+                    catch (e) {
+                        ws.send(JSON.stringify({ type: 'board_uart.error', error: e?.message || String(e) }));
+                    }
+                }
+            }
+            else if (msg.type === 'board_uart.force_close') {
+                try {
+                    await mgr.setHardwareDisabled(true);
+                    logInfo('board_uart.hardware_disabled', { ts: Date.now() });
+                    ws.send(JSON.stringify({ type: 'board_uart.force_closed' }));
+                    const st = await mgr.getStatus();
+                    const payload = JSON.stringify({
+                        type: 'board_uart.status',
+                        status: st.status,
+                        disabled: st.disabled,
+                        hasModule: st.hasModule,
+                        port: st.port,
+                        baud: st.baud,
+                        sessions: st.sessions,
+                        attachedTools: (st.attachedTools || []).map((t) => ({
+                            ...t,
+                            source: t.source || '',
+                            attachedAtMs: t.attachedAt,
+                        })),
+                        suspended: st.suspended,
+                        suspendOwner: st.suspendOwner,
+                        suspendedSinceMs: st.suspendedSinceMs,
+                        maxSuspendMs: st.maxSuspendMs,
+                        autoResumed: st.autoResumed,
+                    });
+                    wss.clients.forEach((c) => c.readyState === 1 && c.send(payload));
+                }
+                catch (e) {
+                    try {
+                        ws.send(JSON.stringify({
+                            type: 'board_uart.error',
+                            error: e?.message || String(e),
+                            code: e?.code,
+                        }));
+                    }
+                    catch { }
+                }
+            }
+            else if (msg.type === 'board_uart.open_manual') {
+                try {
+                    const port = String(msg.port || '');
+                    const baud = Number(msg.baud || 0);
+                    if (!port || !baud) {
+                        ws.send(JSON.stringify({
+                            type: 'board_uart.error',
+                            error: 'missing port/baud',
+                            code: ErrorCodes.EL_INVALID_PARAMS,
+                        }));
+                        return;
+                    }
+                    await mgr.setHardwareDisabled(false);
+                    const session = await openManualSession({ port, baud });
+                    logInfo('board_uart.hardware_enabled', {
+                        ts: Date.now(),
+                        port,
+                        baud,
+                        sessionId: session.id,
+                    });
+                    ws.send(JSON.stringify({ type: 'board_uart.opened_manual', session }));
+                    const st = await mgr.getStatus();
+                    const payload = JSON.stringify({
+                        type: 'board_uart.status',
+                        status: st.status,
+                        disabled: st.disabled,
+                        hasModule: st.hasModule,
+                        port: st.port,
+                        baud: st.baud,
+                        sessions: st.sessions,
+                        attachedTools: (st.attachedTools || []).map((t) => ({
+                            ...t,
+                            source: t.source || '',
+                            attachedAtMs: t.attachedAt,
+                        })),
+                        suspended: st.suspended,
+                        suspendOwner: st.suspendOwner,
+                        suspendedSinceMs: st.suspendedSinceMs,
+                        maxSuspendMs: st.maxSuspendMs,
+                        autoResumed: st.autoResumed,
+                    });
+                    wss.clients.forEach((c) => c.readyState === 1 && c.send(payload));
+                }
+                catch (e) {
+                    try {
+                        ws.send(JSON.stringify({
+                            type: 'board_uart.error',
+                            error: e?.message || String(e),
+                            code: e?.code,
+                        }));
+                    }
+                    catch { }
+                }
+            }
+            else if (msg.type === 'board_uart.listen') {
+                const sessionId = msg.sessionId ? String(msg.sessionId) : undefined;
+                const port = msg.port ? String(msg.port) : undefined;
+                const baud = msg.baud ? Number(msg.baud) : undefined;
+                const clientSessionId = msg.clientSessionId ? String(msg.clientSessionId) : undefined;
+                const historyLinesRaw = msg.historyLines;
+                const historyLines = typeof historyLinesRaw === 'number' && Number.isFinite(historyLinesRaw)
+                    ? Math.floor(historyLinesRaw)
+                    : 0;
+                let meta = null;
+                let seq = 0;
+                let replayingHistory = false;
+                const bufferedLive = [];
+                let bufferedBytes = 0;
+                const MAX_BUFFERED_LIVE_BYTES = 1024 * 1024;
+                const sendLiveChunk = (chunk, receivedAtMs) => {
+                    if (!meta)
+                        return;
+                    try {
+                        ws.send(JSON.stringify({
+                            type: 'board_uart.data',
+                            port: meta.port,
+                            baud: meta.baud,
+                            id: meta.id,
+                            sessionId: meta.sessionId,
+                            clientSessionId: meta.clientSessionId,
+                            receivedAtMs,
+                            seq: seq++,
+                            dataBase64: chunk.toString('base64'),
+                        }));
+                    }
+                    catch { }
+                };
+                const listener = {
+                    source: msg.source || 'web-monitor',
+                    onData(chunk) {
+                        if (!meta)
+                            return;
+                        const receivedAtMs = Date.now();
+                        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                        if (replayingHistory) {
+                            bufferedLive.push({ chunk: buf, receivedAtMs });
+                            bufferedBytes += buf.length;
+                            while (bufferedBytes > MAX_BUFFERED_LIVE_BYTES && bufferedLive.length > 0) {
+                                const old = bufferedLive.shift();
+                                if (!old)
+                                    break;
+                                bufferedBytes -= old.chunk.length;
+                            }
+                            return;
+                        }
+                        sendLiveChunk(buf, receivedAtMs);
+                    },
+                    onError(e) {
+                        if (!meta)
+                            return;
+                        try {
+                            ws.send(JSON.stringify({
+                                type: 'board_uart.error',
+                                port: meta.port,
+                                baud: meta.baud,
+                                id: meta.id,
+                                sessionId: meta.sessionId,
+                                clientSessionId: meta.clientSessionId,
+                                error: e?.message || String(e),
+                                code: e?.code,
+                            }));
+                        }
+                        catch { }
+                    },
+                };
+                try {
+                    if (historyLines > 0) {
+                        const targetSessionId = sessionId || (port && baud ? buildSessionId(String(port), Number(baud)) : undefined);
+                        if (targetSessionId) {
+                            setBoardUartHistoryMaxLines(targetSessionId, historyLines);
+                        }
+                    }
+                    const attached = await mgr.attachResource({
+                        listener,
+                        sessionId,
+                        port,
+                        baud,
+                        source: msg.source || 'web-monitor',
+                    });
+                    meta = {
+                        id: attached.id,
+                        sessionId: attached.sessionId,
+                        port: attached.port,
+                        baud: attached.baud,
+                        clientSessionId,
+                    };
+                    boardUartAttachIds.add(attached.id);
+                    replayingHistory = historyLines > 0;
+                    ws.send(JSON.stringify({
+                        type: 'board_uart.listening',
+                        id: attached.id,
+                        attachId: attached.id,
+                        sessionId: attached.sessionId,
+                        port: attached.port,
+                        baud: attached.baud,
+                        clientSessionId,
+                    }));
+                    if (historyLines > 0) {
+                        const HISTORY_CHUNK_LINES = 200;
+                        const lines = getBoardUartHistoryLines(attached.sessionId, historyLines);
+                        for (let i = 0; i < lines.length; i += HISTORY_CHUNK_LINES) {
+                            const items = lines.slice(i, i + HISTORY_CHUNK_LINES).map((it) => ({
+                                receivedAtMs: it.receivedAtMs,
+                                dataBase64: Buffer.from(it.text + '\n', 'utf8').toString('base64'),
+                            }));
+                            try {
+                                ws.send(JSON.stringify({
+                                    type: 'board_uart.history',
+                                    id: attached.id,
+                                    attachId: attached.id,
+                                    sessionId: attached.sessionId,
+                                    clientSessionId,
+                                    items,
+                                }));
+                            }
+                            catch { }
+                        }
+                        try {
+                            ws.send(JSON.stringify({
+                                type: 'board_uart.history_end',
+                                id: attached.id,
+                                attachId: attached.id,
+                                sessionId: attached.sessionId,
+                                clientSessionId,
+                            }));
+                        }
+                        catch { }
+                        while (bufferedLive.length > 0) {
+                            const item = bufferedLive.shift();
+                            if (!item)
+                                break;
+                            bufferedBytes -= item.chunk.length;
+                            sendLiveChunk(item.chunk, item.receivedAtMs);
+                        }
+                        replayingHistory = false;
+                    }
+                    logInfo('board_uart.listening', {
+                        port: attached.port,
+                        baud: attached.baud,
+                        id: attached.id,
+                        sessionId: attached.sessionId,
+                        clientSessionId,
+                        historyLines,
+                    });
+                }
+                catch (e) {
+                    try {
+                        ws.send(JSON.stringify({
+                            type: 'board_uart.error',
+                            port,
+                            baud,
+                            clientSessionId,
+                            error: e?.message || String(e),
+                            code: e?.code,
+                        }));
+                    }
+                    catch { }
+                }
+            }
+            else if (msg.type === 'board_uart.send') {
+                const dataBase64 = String(msg.dataBase64 || '');
+                if (!dataBase64) {
+                    try {
+                        ws.send(JSON.stringify({
+                            type: 'board_uart.error',
+                            error: 'missing dataBase64',
+                            code: 'EL_INVALID_PARAMS',
+                        }));
+                    }
+                    catch { }
+                    return;
+                }
+                let data;
+                try {
+                    data = Buffer.from(dataBase64, 'base64');
+                }
+                catch {
+                    try {
+                        ws.send(JSON.stringify({
+                            type: 'board_uart.error',
+                            error: 'invalid dataBase64',
+                            code: 'EL_INVALID_PARAMS',
+                        }));
+                    }
+                    catch { }
+                    return;
+                }
+                const sessionId = msg.sessionId ? String(msg.sessionId) : undefined;
+                try {
+                    await mgr.write({ data, sessionId });
+                    ws.send(JSON.stringify({
+                        type: 'board_uart.sent',
+                        sessionId: sessionId || null,
+                        bytes: data.byteLength,
+                    }));
+                }
+                catch (e) {
+                    try {
+                        ws.send(JSON.stringify({
+                            type: 'board_uart.error',
+                            sessionId: sessionId || null,
+                            error: e?.message || String(e),
+                            code: e?.code,
+                        }));
+                    }
+                    catch { }
+                }
+            }
+            else if (msg.type === 'board_uart.stop') {
+                const id = String(msg.id || msg.attachId || '');
+                if (!id)
+                    return;
+                try {
+                    mgr.detachResource(id);
+                }
+                catch { }
+                boardUartAttachIds.delete(id);
+                try {
+                    ws.send(JSON.stringify({ type: 'board_uart.stopped', id }));
+                }
+                catch { }
+            }
+        });
+        ws.on('close', () => {
+            const mgr = getBoardUartResourceManager();
+            for (const id of boardUartAttachIds.values()) {
+                try {
+                    mgr.detachResource(id);
+                }
+                catch { }
+            }
+            boardUartAttachIds.clear();
+        });
+    });
+    // broadcast BoardUart status periodically + status heartbeat
+    setInterval(async () => {
+        try {
+            const mgr = getBoardUartResourceManager();
+            const st = await mgr.getStatus();
+            const msg = JSON.stringify({
+                type: 'board_uart.status',
+                status: st.status,
+                disabled: st.disabled,
+                hasModule: st.hasModule,
+                port: st.port,
+                baud: st.baud,
+                sessions: st.sessions,
+                attachedTools: (st.attachedTools || []).map((t) => ({
+                    ...t,
+                    source: t.source || '',
+                    attachedAtMs: t.attachedAt,
+                })),
+                suspended: st.suspended,
+                suspendOwner: st.suspendOwner,
+                suspendedSinceMs: st.suspendedSinceMs,
+                maxSuspendMs: st.maxSuspendMs,
+                autoResumed: st.autoResumed,
+            });
+            wss.clients.forEach((c) => c.readyState === 1 && c.send(msg));
+        }
+        catch { }
+        const platformInfo = getPlatformInfo();
+        broadcast({
+            type: 'agent.status',
+            health: 'ok',
+            ts: Date.now(),
+            agentId: cfg.agentId,
+            platform: platformInfo.platform,
+            arch: platformInfo.arch,
+        });
+    }, 3000);
+    await new Promise((resolve) => server.listen(cfg.port, cfg.host || '127.0.0.1', resolve));
+    // 记录服务器启���成功
+    logger.write(LogLevel.INFO, 'server.started', {
+        agentId: cfg.agentId,
+        port: cfg.port,
+        host: cfg.host || '127.0.0.1',
+        grpcPort: cfg.grpcPort,
+        pid: process.pid,
+    });
+    // 应用关闭时的最终清理
+    const gracefulShutdown = async () => {
+        logInfo('server.graceful_shutdown_start');
+        try {
+            // 清理所有隧道
+            await cleanupTunnel('application_shutdown');
+            // 关闭WebSocket服务器
+            wss.close();
+            // 关闭HTTP服务器
+            server.close();
+            logInfo('server.graceful_shutdown_complete');
+        }
+        catch (e) {
+            logError('server.graceful_shutdown_failed', {
+                error: e?.message || String(e),
+            });
+        }
+    };
+    // 监听进程退出信号
+    process.on('SIGINT', gracefulShutdown);
+    process.on('SIGTERM', gracefulShutdown);
+    process.on('beforeExit', gracefulShutdown);
+    return { app, server, wss };
+}
+const EMBED_LINK_HEAD = '=========EMBED_LINK=========';
+export function execRemoteRaw(client, cmd) {
+    return new Promise((resolve, reject) => {
+        // 首先发送HEAD命令来吸收横幅并提供分隔标识
+        const headCmd = `echo '${EMBED_LINK_HEAD}'`;
+        const fullCmd = `${headCmd} && ${cmd}`;
+        client.exec(fullCmd, (err, stream) => {
+            if (err)
+                return reject(err);
+            let out = '';
+            let errout = '';
+            stream.on('data', (d) => (out += d.toString()));
+            stream.stderr.on('data', (d) => (errout += d.toString()));
+            stream.on('close', (code) => {
+                if (code === 0) {
+                    const output = out || errout || '';
+                    // 查找HEAD标记，提取HEAD之后的内容
+                    const headIndex = output.indexOf(EMBED_LINK_HEAD);
+                    if (headIndex !== -1) {
+                        const cleanOutput = output.substring(headIndex + EMBED_LINK_HEAD.length).trim();
+                        resolve(cleanOutput);
+                    }
+                    else {
+                        // 如果没有找到HEAD，可能是HEAD命令本身就失败了，返回原始输出
+                        resolve(output);
+                    }
+                }
+                else {
+                    reject(new Error(errout || out));
+                }
+            });
+        });
+    });
+}
+function friendlyError(e) {
+    const msg = (e?.message || String(e || '')).toString();
+    const lower = msg.toLowerCase();
+    if (lower.includes('permission denied') ||
+        lower.includes('authentication') ||
+        lower.includes('auth')) {
+        return {
+            code: 'EL_SSH_CONNECT_FAILED',
+            message: msg,
+            suggestions: ['检查用户名/密码/私钥是否正确', '确认 SSH 服务器允许该账号登录'],
+        };
+    }
+    if (lower.includes('cannot bind') ||
+        lower.includes('address already in use') ||
+        lower.includes('eaddrinuse')) {
+        return {
+            code: 'EL_SSH_TUNNEL_BROKEN',
+            message: msg,
+            suggestions: [
+                '端口被占用，复用已存在端口或停止其他隧道',
+                '确认 SSH 服务器允许远端端口转发 (AllowTcpForwarding)',
+            ],
+        };
+    }
+    if (lower.includes('sftp')) {
+        return {
+            code: 'EL_SSH_CONNECT_FAILED',
+            message: 'SFTP 不可用（仅用于写入发现文件，可忽略）',
+            suggestions: ['继续使用隧道功能', '检查服务器 SFTP 配置（可选）'],
+        };
+    }
+    return {
+        code: 'EL_SSH_CONNECT_FAILED',
+        message: msg,
+        suggestions: ['检查网络连通性和凭据', '查看 Agent 日志获取更多细节'],
+    };
+}
+async function writeRemoteAgentJson(tunnel, info) {
+    const client = tunnel.getClient();
+    if (!client)
+        return undefined;
+    try {
+        const adapter = new SSHAdapter(client);
+        await adapter.init();
+        const agentData = {
+            schemaVersion: 1,
+            agent: {
+                id: info.agentId,
+                version: info.version,
+                pairCode: info.pairCode,
+                startupTime: info.startupTime,
+                originHost: info.originHost,
+                originUser: info.originUser,
+                hostGrpcPort: info.port,
+            },
+            endpoint: {
+                grpc: {
+                    host: '127.0.0.1',
+                    port: info.port,
+                    scheme: 'grpc',
+                },
+            },
+            transport: {
+                mode: 'reverse-ssh',
+                reverseSsh: {
+                    sshHost: info.sshHost,
+                    sshPort: info.sshPort,
+                    sshUser: info.user,
+                    originHost: info.originHost,
+                    forwardPort: info.port,
+                },
+            },
+        };
+        await adapter.writeAgentJson(agentData);
+        return adapter.getAgentJsonPath();
+    }
+    catch (e) {
+        console.warn('Failed to write agent.json:', e);
+        return undefined;
+    }
+}
+async function probeRemoteExistingTunnel(params) {
+    const { host, sshPort, user, password } = params;
+    const ssh2 = await import('ssh2');
+    const client = new ssh2.Client();
+    return await new Promise(async (resolve) => {
+        const adapter = new SSHAdapter(client);
+        const finish = (result) => {
+            try {
+                client.end();
+            }
+            catch { }
+            resolve(result);
+        };
+        client
+            .on('ready', async () => {
+            try {
+                // 一次初始化，全程使用
+                await adapter.init();
+                // 读取agent.json
+                const agentData = await adapter.readAgentJson();
+                if (!agentData) {
+                    const agentJsonPath = adapter.getAgentJsonPath();
+                    return finish({ active: false, path: agentJsonPath });
+                }
+                const port = Number(agentData?.agent?.hostGrpcPort || agentData?.endpoint?.grpc?.port);
+                if (!port) {
+                    return finish({ active: false });
+                }
+                // 检查端口是否在监听
+                const isListening = await adapter.isPortListening(port);
+                if (isListening) {
+                    const agentJsonPath = adapter.getAgentJsonPath();
+                    return finish({ active: true, port, path: agentJsonPath });
+                }
+                return finish({ active: false });
+            }
+            catch (e) {
+                console.warn('Failed to probe remote agent.json:', e);
+                return finish({ active: false });
+            }
+        })
+            .on('error', (err) => {
+            console.warn('Failed to probe remote agent.json:', err?.message || String(err));
+            return finish({ active: false });
+        })
+            .connect({ host, port: sshPort, username: user, password });
+    });
+}