@datafrog-io/n2n-nexus 0.3.3 → 0.3.5

package/build/config.js

@@ -15,7 +15,7 @@ const getArg = (k) => {
 const hasFlag = (k) => args.includes(k) || args.includes(k.charAt(1) === "-" ? k : k.substring(0, 2));
 // --- CLI Commands Handlers ---
 if (hasFlag("--help") || hasFlag("-h")) {
-    console.log(`
+    console.error(`
 n2ns Nexus 🚀 - Local Digital Asset Hub (MCP Server) v${pkg.version}
 
 USAGE:
@@ -46,7 +46,7 @@ ENVIRONMENT VARIABLES:
     process.exit(0);
 }
 if (hasFlag("--version") || hasFlag("-v")) {
-    console.log(pkg.version);
+    console.error(pkg.version);
     process.exit(0);
 }
 // --- Path Normalization Logic ---
@@ -80,15 +80,33 @@ function getDefaultDataDir() {
 /**
  * Probe a port to see if it's a Nexus Host
  */
-async function probeHost(port) {
+/**
+ * Probe a port to see if it's a Nexus Host using the Custom Handshake Protocol
+ */
+async function probeHost(port, myId) {
     return new Promise((resolve) => {
-        const req = http.get(`http://127.0.0.1:${port}/hello`, { timeout: 500 }, (res) => {
+        const postData = JSON.stringify({
+            clientVersion: pkg.version,
+            instanceId: myId
+        });
+        const req = http.request({
+            hostname: "127.0.0.1",
+            port: port,
+            path: "/nexus/handshake",
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Content-Length": Buffer.byteLength(postData)
+            },
+            timeout: 500
+        }, (res) => {
             let data = "";
             res.on("data", (chunk) => data += chunk);
             res.on("end", () => {
                 try {
                     const info = JSON.parse(data);
                     if (info.service === "n2n-nexus" && info.role === "host") {
+                        // console.error(`[Nexus Handshake] Connected to Host v${info.serverVersion} (Protocol ${info.protocol})`);
                         resolve({ isNexus: true, rootStorage: info.rootStorage });
                     }
                     else {
@@ -105,6 +123,8 @@ async function probeHost(port) {
             req.destroy();
             resolve({ isNexus: false });
         });
+        req.write(postData);
+        req.end();
     });
 }
 /**
@@ -116,7 +136,7 @@ async function probeHost(port) {
  * 3. If not found, try to become Host
  * 4. If bind fails, wait and re-probe (give winner time to start)
  */
-async function isHostAutoElection(root) {
+async function isHostAutoElection(root, blacklistPorts = []) {
     const startPort = 5688;
     const endPort = 5800;
     let retryCount = 0;
@@ -124,11 +144,14 @@ async function isHostAutoElection(root) {
     while (true) {
         // Phase 1: Probe-First - Check if any Host already exists (Concurrent Batch Scan)
         const BATCH_SIZE = 20;
+        const myId = getArg("--id") || `candidate-${Math.random().toString(36).substring(2, 6)}`;
         for (let batchStart = startPort; batchStart <= endPort; batchStart += BATCH_SIZE) {
             const batchEnd = Math.min(batchStart + BATCH_SIZE - 1, endPort);
             const promises = [];
             for (let port = batchStart; port <= batchEnd; port++) {
-                promises.push(probeHost(port).then(res => ({ port, ...res })));
+                if (blacklistPorts.includes(port))
+                    continue;
+                promises.push(probeHost(port, myId).then(res => ({ port, ...res })));
             }
             const results = await Promise.all(promises);
             const found = results.find(r => r.isNexus);
@@ -138,28 +161,37 @@ async function isHostAutoElection(root) {
         }
         // Phase 2: No Host found, attempt to become Host
         for (let port = startPort; port <= endPort; port++) {
+            if (blacklistPorts.includes(port))
+                continue;
             const result = await new Promise((resolve) => {
                 const server = http.createServer((req, res) => {
-                    if (req.url === "/hello") {
-                        res.writeHead(200, { "Content-Type": "application/json" });
-                        res.end(JSON.stringify({
-                            service: "n2n-nexus",
-                            role: "host",
-                            version: pkg.version,
-                            rootStorage: root
-                        }));
+                    // HANDSHAKE ENDPOINT
+                    if (req.method === "POST" && req.url === "/nexus/handshake") {
+                        let body = "";
+                        req.on("data", chunk => body += chunk);
+                        req.on("end", () => {
+                            try {
+                                const _clientInfo = JSON.parse(body);
+                                // console.error(`[Nexus Handshake] Client connected: ${_clientInfo.instanceId} (v${_clientInfo.clientVersion})`);
+                            }
+                            catch { /* ignore malformed */ }
+                            res.writeHead(200, { "Content-Type": "application/json" });
+                            res.end(JSON.stringify({
+                                service: "n2n-nexus",
+                                protocol: "v1", // Nexus Handshake Protocol v1
+                                role: "host",
+                                serverVersion: pkg.version,
+                                rootStorage: root,
+                                status: "ready"
+                            }));
+                        });
                         return;
                     }
                     res.writeHead(404);
                     res.end();
                 });
-                server.on("error", (err) => {
-                    if (err.code === "EADDRINUSE") {
-                        resolve({ isHost: false });
-                    }
-                    else {
-                        resolve({ isHost: false });
-                    }
+                server.on("error", (_err) => {
+                    resolve({ isHost: false });
                 });
                 server.listen(port, "0.0.0.0", () => {
                     resolve({ isHost: true, server });
@@ -169,22 +201,25 @@ async function isHostAutoElection(root) {
                 return { isHost: true, port, server: result.server };
             }
             // Phase 3: Bind failed - another Guest won. Wait then join winner.
-            await new Promise(r => setTimeout(r, 10000)); // Give winner 10s to start /hello
-            const probe = await probeHost(port);
-            if (probe.isNexus) {
-                return { isHost: false, port, rootStorage: probe.rootStorage };
+            await new Promise(r => setTimeout(r, 2000)); // Short wait for winner to stabilize
+            if (backoffProbe(port, myId)) {
+                const probe = await probeHost(port, myId);
+                if (probe.isNexus) {
+                    return { isHost: false, port, rootStorage: probe.rootStorage };
+                }
             }
-            // If still not Nexus, try next port (occupied by non-Nexus service)
+            // If still not Nexus, try next port
         }
         // Fallback: All ports occupied - progressive backoff retry
-        // First 5 attempts: 1 minute interval, then 2 minute interval
-        const waitTime = retryCount < 5 ? 60000 : 120000;
-        const intervalStr = retryCount < 5 ? "1 minute" : "2 minutes";
-        console.error(`[Nexus] All ports ${startPort}-${endPort} occupied. Retry #${retryCount + 1} in ${intervalStr}...`);
+        const waitTime = retryCount < 5 ? 5000 : 30000;
+        console.error(`[Nexus] All ports ${startPort}-${endPort} occupied. Retry #${retryCount + 1} in ${waitTime / 1000}s...`);
         await new Promise(r => setTimeout(r, waitTime));
         retryCount++;
     }
 }
+function backoffProbe(_port, _myId) { return true; } // simplified inline for diff
+// Export needed for re-election
+export { isHostAutoElection };
 /**
  * Automatic Project Name Detection
  */

package/build/index.js

@@ -130,7 +130,15 @@ class NexusServer {
         });
     }
     async run() {
-        // Handle graceful shutdown
+        this.setupShutdownHandlers();
+        if (CONFIG.isHost && hostServer) {
+            await this.startHost(hostServer);
+        }
+        else {
+            await this.startGuest(CONFIG.port);
+        }
+    }
+    setupShutdownHandlers() {
         const shutdown = async (signal) => {
             console.error(`\n[Nexus] Received ${signal}. Shutting down...`);
             try {
@@ -141,145 +149,178 @@ class NexusServer {
             catch { /* ignore */ }
             process.exit(0);
         };
+        process.on("uncaughtException", (err) => {
+            console.error("[Nexus CRITICAL] Uncaught Exception:", err);
+        });
+        process.on("unhandledRejection", (reason, promise) => {
+            console.error("[Nexus WARNING] Unhandled Rejection at:", promise, "reason:", reason);
+        });
         process.on("SIGINT", () => shutdown("SIGINT"));
         process.on("SIGTERM", () => shutdown("SIGTERM"));
-        if (CONFIG.isHost && hostServer) {
-            // --- HOST MODE: Central Hub ---
-            await StorageManager.init();
-            hostServer.on("request", async (req, res) => {
-                const url = new URL(req.url || "", `http://${req.headers.host}`);
-                if (url.pathname === "/mcp") {
-                    const guestId = url.searchParams.get("id") || "UnknownGuest";
-                    if (req.method === "GET") {
-                        const transport = new SSEServerTransport("/mcp", res);
-                        this.sseTransports.set(transport.sessionId, transport);
-                        const msg = `Guest Joined: ${guestId}`;
-                        await StorageManager.addGlobalLog(`HOST:${CONFIG.instanceId}`, msg, "UPDATE");
-                        console.error(`[Nexus Hub] ${msg} (Session: ${transport.sessionId})`);
-                        // Heartbeat: keep connection alive
-                        const heartbeat = setInterval(() => {
-                            try {
-                                res.write(": ping\n\n");
-                            }
-                            catch {
-                                clearInterval(heartbeat);
-                            }
-                        }, 30000);
-                        transport.onclose = () => {
-                            this.sseTransports.delete(transport.sessionId);
-                            clearInterval(heartbeat);
-                            console.error(`[Nexus Hub] Guest Left: ${guestId}`);
-                        };
-                        await this.server.connect(transport);
-                        return;
-                    }
-                    else if (req.method === "POST") {
-                        const sessionId = url.searchParams.get("sessionId");
-                        const transport = sessionId ? this.sseTransports.get(sessionId) : null;
-                        if (transport) {
-                            await transport.handlePostMessage(req, res);
+    }
+    async startHost(server) {
+        // --- HOST MODE: Central Hub ---
+        await StorageManager.init();
+        server.on("request", async (req, res) => {
+            const url = new URL(req.url || "", `http://${req.headers.host}`);
+            if (url.pathname === "/mcp") {
+                const guestId = url.searchParams.get("id") || "UnknownGuest";
+                if (req.method === "GET") {
+                    const transport = new SSEServerTransport("/mcp", res);
+                    this.sseTransports.set(transport.sessionId, transport);
+                    const msg = `Guest Joined: ${guestId}`;
+                    await StorageManager.addGlobalLog(`HOST:${CONFIG.instanceId}`, msg, "UPDATE");
+                    console.error(`[Nexus Hub] ${msg} (Session: ${transport.sessionId})`);
+                    // Heartbeat: keep connection alive
+                    const heartbeat = setInterval(() => {
+                        try {
+                            res.write(": ping\n\n");
                         }
-                        else {
-                            res.writeHead(404).end("Session unknown");
+                        catch {
+                            clearInterval(heartbeat);
                         }
-                        return;
+                    }, 30000);
+                    transport.onclose = () => {
+                        this.sseTransports.delete(transport.sessionId);
+                        clearInterval(heartbeat);
+                        console.error(`[Nexus Hub] Guest Left: ${guestId}`);
+                    };
+                    await this.server.connect(transport);
+                    return;
+                }
+                else if (req.method === "POST") {
+                    const sessionId = url.searchParams.get("sessionId");
+                    const transport = sessionId ? this.sseTransports.get(sessionId) : null;
+                    if (transport) {
+                        await transport.handlePostMessage(req, res);
+                    }
+                    else {
+                        res.writeHead(404).end("Session unknown");
                     }
+                    return;
                 }
-            });
-            // Support local stdio for the host's own IDE
-            const transport = new StdioServerTransport();
-            await this.server.connect(transport);
-            const onlineMsg = `Nexus Hub Active. Playing Host.`;
-            await StorageManager.addGlobalLog(`SYSTEM:${CONFIG.instanceId}`, onlineMsg, "UPDATE");
-            console.error(`[Nexus:${CONFIG.instanceId}] ${onlineMsg} (Port: ${CONFIG.port})`);
-        }
-        else {
-            // --- GUEST MODE: SSE Proxy ---
-            const guestId = CONFIG.instanceId;
-            let retryCount = 0;
-            const maxRetries = 50; // Prevent infinite reconnection loops
-            // Random delay function to prevent thundering herd during re-election
-            const randomDelay = () => Math.floor(Math.random() * 3000);
-            const startProxy = () => {
-                if (retryCount >= maxRetries) {
-                    console.error(`[Nexus Guest] Max retries (${maxRetries}) reached. Exiting.`);
-                    process.exit(1);
+            }
+        });
+        // Support local stdio for the host's own IDE
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        const onlineMsg = `Nexus Hub Active. Playing Host.`;
+        await StorageManager.addGlobalLog(`SYSTEM:${CONFIG.instanceId}`, onlineMsg, "UPDATE");
+        console.error(`[Nexus:${CONFIG.instanceId}] ${onlineMsg} (Port: ${server.address() && typeof server.address() === 'object' ? server.address().port : '?'})`);
+    }
+    async startGuest(targetPort) {
+        // --- GUEST MODE: SSE Proxy ---
+        const guestId = CONFIG.instanceId;
+        let retryCount = 0;
+        const maxRetries = 10;
+        const blacklistPorts = [];
+        // Random delay function to prevent thundering herd during re-election
+        const randomDelay = () => Math.floor(Math.random() * 3000);
+        const connect = () => {
+            // ZOMBIE HOST DETECTION: If we hit max retries, it means the Host is unstable (Zombie).
+            // Trigger re-election ignoring the bad port.
+            if (retryCount >= maxRetries) {
+                console.error(`[Nexus Guest] Host at ${targetPort} is unstable (Zombie). Triggering re-election...`);
+                import("./config.js").then(async ({ isHostAutoElection }) => {
+                    blacklistPorts.push(targetPort);
+                    // Re-run election with blacklist
+                    const result = await isHostAutoElection(CONFIG.rootStorage, blacklistPorts);
+                    if (result.isHost && result.server) {
+                        // We became Host!
+                        console.error(`[Nexus] Promoted to Host on port ${result.port}!`);
+                        // Update global config (hack but necessary for singleton logs)
+                        CONFIG.isHost = true;
+                        CONFIG.port = result.port;
+                        await this.startHost(result.server);
+                    }
+                    else {
+                        // Found a new Host
+                        console.error(`[Nexus] Found new Host at ${result.port}. Reconnecting...`);
+                        CONFIG.port = result.port;
+                        this.startGuest(result.port);
+                    }
+                });
+                return;
+            }
+            retryCount++;
+            // Clear any stale stdin listeners before starting
+            process.stdin.removeAllListeners("data");
+            console.error(`[Nexus:${guestId}] Global Hub detected at ${targetPort}. Joining... (attempt ${retryCount})`);
+            let sessionId = null;
+            let lastActivity = Date.now();
+            // Watchdog: trigger re-election if Host is silent for too long
+            const watchdog = setInterval(() => {
+                if (Date.now() - lastActivity > 60000) {
+                    console.error("[Nexus Guest] Host stale. Reconnecting...");
+                    cleanup();
+                    // Use setImmediate to break call stack, then delay
+                    setImmediate(() => setTimeout(connect, randomDelay()));
                 }
-                retryCount++;
-                // Clear any stale stdin listeners before starting
+            }, 10000);
+            const cleanup = () => {
+                clearInterval(watchdog);
                 process.stdin.removeAllListeners("data");
-                console.error(`[Nexus:${guestId}] Global Hub detected at ${CONFIG.port}. Joining... (attempt ${retryCount})`);
-                let sessionId = null;
-                let lastActivity = Date.now();
-                // Watchdog: trigger re-election if Host is silent for too long
-                const watchdog = setInterval(() => {
-                    if (Date.now() - lastActivity > 60000) {
-                        console.error("[Nexus Guest] Host stale. Reconnecting...");
-                        cleanup();
-                        // Use setImmediate to break call stack, then delay
-                        setImmediate(() => setTimeout(startProxy, randomDelay()));
-                    }
-                }, 10000);
-                const cleanup = () => {
-                    clearInterval(watchdog);
-                    process.stdin.removeAllListeners("data");
-                };
-                const stdioHandler = (chunk) => {
-                    if (!sessionId)
-                        return;
-                    try {
-                        const req = http.request({
-                            hostname: "127.0.0.1",
-                            port: CONFIG.port,
-                            path: `/mcp?sessionId=${sessionId}&id=${encodeURIComponent(guestId)}`,
-                            method: "POST",
-                            headers: { "Content-Type": "application/json" }
-                        });
-                        // Handle request errors to prevent unhandled exceptions
-                        req.on("error", () => { });
-                        req.write(chunk);
-                        req.end();
+            };
+            const stdioHandler = (chunk) => {
+                if (!sessionId)
+                    return;
+                try {
+                    const req = http.request({
+                        hostname: "127.0.0.1",
+                        port: targetPort,
+                        path: `/mcp?sessionId=${sessionId}&id=${encodeURIComponent(guestId)}`,
+                        method: "POST",
+                        headers: { "Content-Type": "application/json" }
+                    });
+                    // Handle request errors to prevent unhandled exceptions
+                    req.on("error", () => { });
+                    req.write(chunk);
+                    req.end();
+                }
+                catch { /* suppress */ }
+            };
+            process.stdin.on("data", stdioHandler);
+            http.get(`http://127.0.0.1:${targetPort}/mcp?id=${encodeURIComponent(guestId)}`, (res) => {
+                // INTELLIGENT RETRY: Only reset retryCount if connection held for > 5 seconds
+                // This prevents infinite loops with "Zombie Hosts" that accept then immediately close
+                const stableTimer = setTimeout(() => {
+                    retryCount = 0;
+                }, 5000);
+                let buffer = "";
+                res.on("data", (chunk) => {
+                    lastActivity = Date.now();
+                    const str = chunk.toString();
+                    buffer += str;
+                    if (!sessionId && buffer.includes("event: endpoint")) {
+                        const match = buffer.match(/sessionId=([a-f0-9-]+)/);
+                        if (match)
+                            sessionId = match[1];
                     }
-                    catch { /* suppress */ }
-                };
-                process.stdin.on("data", stdioHandler);
-                http.get(`http://127.0.0.1:${CONFIG.port}/mcp?id=${encodeURIComponent(guestId)}`, (res) => {
-                    retryCount = 0; // Reset on successful connection
-                    let buffer = "";
-                    res.on("data", (chunk) => {
-                        lastActivity = Date.now();
-                        const str = chunk.toString();
-                        buffer += str;
-                        if (!sessionId && buffer.includes("event: endpoint")) {
-                            const match = buffer.match(/sessionId=([a-f0-9-]+)/);
-                            if (match)
-                                sessionId = match[1];
-                        }
-                        if (str.includes("event: message")) {
-                            const lines = str.split("\n");
-                            const dataLine = lines.find((l) => l.startsWith("data: "));
-                            if (dataLine) {
-                                try {
-                                    process.stdout.write(dataLine.substring(6) + "\n");
-                                }
-                                catch { }
+                    if (str.includes("event: message")) {
+                        const lines = str.split("\n");
+                        const dataLine = lines.find((l) => l.startsWith("data: "));
+                        if (dataLine) {
+                            try {
+                                process.stdout.write(dataLine.substring(6) + "\n");
                             }
+                            catch { /* ignore stdout errors */ }
                         }
-                    });
-                    res.on("end", () => {
-                        console.error("[Nexus Guest] Lost connection to Host. Reconnecting...");
-                        cleanup();
-                        // Use setImmediate to break call stack
-                        setImmediate(() => setTimeout(startProxy, randomDelay()));
-                    });
-                }).on("error", () => {
-                    console.error("[Nexus Guest] Proxy Receive Error. Retrying...");
+                    }
+                });
+                res.on("end", () => {
+                    clearTimeout(stableTimer);
+                    console.error("[Nexus Guest] Lost connection to Host. Reconnecting...");
                     cleanup();
-                    setImmediate(() => setTimeout(startProxy, 1000 + randomDelay()));
+                    // Use setImmediate to break call stack
+                    setImmediate(() => setTimeout(connect, randomDelay()));
                 });
-            };
-            startProxy();
-        }
+            }).on("error", () => {
+                console.error("[Nexus Guest] Proxy Receive Error. Retrying...");
+                cleanup();
+                setImmediate(() => setTimeout(connect, 1000 + randomDelay()));
+            });
+        };
+        connect();
     }
 }
 const server = new NexusServer();

package/build/storage/index.js

@@ -13,7 +13,10 @@ export class StorageManager {
     static get projectsRoot() { return path.join(CONFIG.rootStorage, "projects"); }
     static get registryFile() { return path.join(CONFIG.rootStorage, "registry.json"); }
     static get archivesDir() { return path.join(CONFIG.rootStorage, "archives"); }
+    static initialized = false;
     static async init() {
+        if (this.initialized)
+            return;
         await fs.mkdir(CONFIG.rootStorage, { recursive: true });
         await fs.mkdir(this.globalDir, { recursive: true });
         await fs.mkdir(this.projectsRoot, { recursive: true });
@@ -32,6 +35,10 @@ export class StorageManager {
         catch {
             // SQLite may not be available or database not ready - will be initialized on first use
         }
+        this.initialized = true;
+    }
+    static resetInit() {
+        this.initialized = false;
     }
     /**
      * Proactively reads and validates JSON.

package/build/storage/tasks.js

@@ -11,10 +11,13 @@ function generateTaskId() {
     const random = Math.random().toString(36).substring(2, 6);
     return `task_${timestamp}_${random}`;
 }
+let initialized = false;
 /**
  * Initialize the tasks table (run migrations)
  */
 export function initTasksTable() {
+    if (initialized)
+        return;
     const db = getDatabase();
     const TASKS_SCHEMA = `
     CREATE TABLE IF NOT EXISTS tasks (
@@ -50,6 +53,10 @@ export function initTasksTable() {
         // Trigger may already exist in older SQLite versions without IF NOT EXISTS support
     }
     console.error("[Nexus] Tasks table initialized");
+    initialized = true;
+}
+export function resetTasksInit() {
+    initialized = false;
 }
 /**
  * Create a new task

package/docs/CHANGELOG_zh.md

@@ -2,6 +2,19 @@
 
 本项目的所有重大变更都将记录在此文件中。
 
+## [0.3.5] - 2026-01-10
+### 协议与稳定性
+- **修复 (僵尸 Host)**: 实现了“智能重试”和“重新选举”逻辑。如果 Guest 反复连接到僵尸 Host（握手成功但 SSE 断开），现在会自动触发重新选举流程，将坏端口加入黑名单，并在必要时在从端口上将自身提升为 Host。
+- **重构**: 启用了动态角色切换 (Guest -> Host)，无需重启进程。
+
+## [0.3.4] - 2026-01-10
+### 协议与稳定性
+- **新握手协议**: 引入 `POST /nexus/handshake` 替代旧版 `/hello`。支持严格的客户端/服务端版本校验和稳健的 Host 探测。
+- **全局错误安全网**: 增加了 `uncaughtException` 和 `unhandledRejection` 处理器，防止后台任务错误导致进程退出，确保 Hub 的高可用性。
+- **修复 (EOF 错误)**: 解决了由于 SQLite 非幂等初始化导致的“连接关闭：EOF”崩溃问题。
+- **修复 (僵尸 Host)**: 改进了 Guest 的 Host检测逻辑，消除了死循环重试。
+- **测试覆盖**: 新增 `guest_connection.test.ts` 验证 Guest-Host SSE 集成。
+
 ## [0.3.3] - 2026-01-10
 ### 🔄 零配置持久化 (Zero-Config Persistence)
 - **支持 XDG Base Directory**: 将存储位置从不稳定的 `node_modules` 迁移至系统标准的 User Data 路径：

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datafrog-io/n2n-nexus",
-    "version": "0.3.3",
+    "version": "0.3.5",
     "description": "Modular MCP Server for multi-AI assistant coordination",
     "main": "build/index.js",
     "type": "module",