@datafrog-io/n2n-nexus 0.3.0 → 0.3.2

package/README.md

@@ -102,36 +102,22 @@
 
 Add to your MCP config file (e.g., `claude_desktop_config.json` or Cursor MCP settings):
 
-#### Leader AI
 ```json
 {
   "mcpServers": {
     "n2n-nexus": {
       "command": "npx",
-      "args": [
-        "-y",
-        "@datafrog-io/n2n-nexus",
-        "--root", "D:/DevSpace/Nexus_Storage"
-      ]
+      "args": ["-y", "@datafrog-io/n2n-nexus"]
     }
   }
 }
 ```
 
-#### Collaborator AI
+> **Zero-Config**: No `--id` or `--host` needed. Just run and collaborate!
+
+**Optional**: Use `--root` to specify a custom storage path:
 ```json
-{
-  "mcpServers": {
-    "n2n-nexus": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@datafrog-io/n2n-nexus",
-        "--root", "D:/DevSpace/Nexus_Storage"
-      ]
-    }
-  }
-}
+"args": ["-y", "@datafrog-io/n2n-nexus", "--root", "/path/to/storage"]
 ```
 
 ### CLI Arguments
@@ -174,9 +160,11 @@ The following files demonstrate a real orchestration session where **4 AI agents
 
 ## ⭐ Support This Project
 
-If **n2ns Nexus** helps you build better AI workflows, consider giving it a star! Your support helps us improve and motivates continued development.
+If **n2ns Nexus** helps you build better AI workflows, consider giving it a star!
 
-[![Star on GitHub](https://img.shields.io/github/stars/n2ns/n2n-nexus?style=social)](https://github.com/n2ns/n2n-nexus)
+<a href="https://github.com/n2ns/n2n-nexus">
+  <img src="https://img.shields.io/github/stars/n2ns/n2n-nexus?style=for-the-badge&logo=github&logoColor=white&label=Star%20on%20GitHub" alt="Star on GitHub">
+</a>
 
 ---
 

package/build/config.js

@@ -106,56 +106,72 @@ async function probeHost(port) {
  */
 async function isHostAutoElection(root) {
     const startPort = 5688;
-    const endPort = 5700;
-    // Phase 1: Probe-First - Check if any Host already exists
-    for (let port = startPort; port <= endPort; port++) {
-        const probe = await probeHost(port);
-        if (probe.isNexus) {
-            return { isHost: false, port, rootStorage: probe.rootStorage };
+    const endPort = 5800;
+    let retryCount = 0;
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+        // Phase 1: Probe-First - Check if any Host already exists (Concurrent Batch Scan)
+        const BATCH_SIZE = 20;
+        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 })));
+            }
+            const results = await Promise.all(promises);
+            const found = results.find(r => r.isNexus);
+            if (found) {
+                return { isHost: false, port: found.port, rootStorage: found.rootStorage };
+            }
         }
-    }
-    // Phase 2: No Host found, attempt to become Host
-    for (let port = startPort; port <= endPort; port++) {
-        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
-                    }));
-                    return;
-                }
-                res.writeHead(404);
-                res.end();
-            });
-            server.on("error", (err) => {
-                if (err.code === "EADDRINUSE") {
-                    resolve({ isHost: false });
-                }
-                else {
-                    resolve({ isHost: false });
-                }
-            });
-            server.listen(port, "127.0.0.1", () => {
-                resolve({ isHost: true, server });
+        // Phase 2: No Host found, attempt to become Host
+        for (let port = startPort; port <= endPort; port++) {
+            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
+                        }));
+                        return;
+                    }
+                    res.writeHead(404);
+                    res.end();
+                });
+                server.on("error", (err) => {
+                    if (err.code === "EADDRINUSE") {
+                        resolve({ isHost: false });
+                    }
+                    else {
+                        resolve({ isHost: false });
+                    }
+                });
+                server.listen(port, "127.0.0.1", () => {
+                    resolve({ isHost: true, server });
+                });
             });
-        });
-        if (result.isHost) {
-            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 };
+            if (result.isHost) {
+                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 };
+            }
+            // If still not Nexus, try next port (occupied by non-Nexus service)
         }
-        // If still not Nexus, try next port (occupied by non-Nexus service)
+        // 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}...`);
+        await new Promise(r => setTimeout(r, waitTime));
+        retryCount++;
     }
-    // Fallback: become Host on startPort (should rarely happen)
-    return { isHost: true, port: startPort };
 }
 /**
  * Automatic Project Name Detection

package/build/index.js

@@ -196,21 +196,28 @@ class NexusServer {
         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);
+                }
+                retryCount++;
                 // Clear any stale stdin listeners before starting
                 process.stdin.removeAllListeners("data");
-                console.error(`[Nexus:${guestId}] Global Hub detected at ${CONFIG.port}. Joining...`);
+                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. Triggering re-election...");
+                        console.error("[Nexus Guest] Host stale. Reconnecting...");
                         cleanup();
-                        // Random delay to prevent all guests from racing for the port
-                        setTimeout(() => this.run(), randomDelay());
+                        // Use setImmediate to break call stack, then delay
+                        setImmediate(() => setTimeout(startProxy, randomDelay()));
                     }
                 }, 10000);
                 const cleanup = () => {
@@ -224,7 +231,7 @@ class NexusServer {
                         const req = http.request({
                             hostname: "127.0.0.1",
                             port: CONFIG.port,
-                            path: `/mcp?sessionId=${sessionId}&id=${guestId}`,
+                            path: `/mcp?sessionId=${sessionId}&id=${encodeURIComponent(guestId)}`,
                             method: "POST",
                             headers: { "Content-Type": "application/json" }
                         });
@@ -236,7 +243,8 @@ class NexusServer {
                     catch { /* suppress */ }
                 };
                 process.stdin.on("data", stdioHandler);
-                http.get(`http://127.0.0.1:${CONFIG.port}/mcp?id=${guestId}`, (res) => {
+                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();
@@ -259,15 +267,15 @@ class NexusServer {
                         }
                     });
                     res.on("end", () => {
-                        console.error("[Nexus Guest] Lost connection to Host. Re-electing...");
+                        console.error("[Nexus Guest] Lost connection to Host. Reconnecting...");
                         cleanup();
-                        // Random delay for re-election
-                        setTimeout(() => this.run(), randomDelay());
+                        // Use setImmediate to break call stack
+                        setImmediate(() => setTimeout(startProxy, randomDelay()));
                     });
                 }).on("error", () => {
-                    console.error("[Nexus Guest] Proxy Receive Error. Retry with random delay...");
+                    console.error("[Nexus Guest] Proxy Receive Error. Retrying...");
                     cleanup();
-                    setTimeout(() => this.run(), 1000 + randomDelay());
+                    setImmediate(() => setTimeout(startProxy, 1000 + randomDelay()));
                 });
             };
             startProxy();

package/docs/ASSISTANT_GUIDE.md

@@ -1,6 +1,6 @@
-# Nexus 助手协作指令 (v0.2.1)
+# Nexus 助手协作指令 (v0.3.0)
 
-你现在是 **n2ns Nexus** 协作网络的一员。该系统集成了实时通信、结构化资产管理以及 **异步任务流 (Task Primitives)**，所有操作均落地在本地文件系统。
+你现在是 **n2ns Nexus** 协作网络的一员。该系统集成了实时通信、结构化资产管理、**异步任务流 (Task Primitives)** 以及 **全局 Hub 架构 (v0.3.0)**，所有操作均落地在本地文件系统。
 
 ## 🚦 核心原则：渐进式发现，增量读取
 

package/docs/README_zh.md

@@ -102,36 +102,22 @@
 
 在你的 MCP 配置文件中（如 `claude_desktop_config.json` 或 Cursor MCP 设置）添加：
 
-#### 主导 AI
 ```json
 {
   "mcpServers": {
     "n2n-nexus": {
       "command": "npx",
-      "args": [
-        "-y",
-        "@datafrog-io/n2n-nexus",
-        "--root", "D:/DevSpace/Nexus_Storage"
-      ]
+      "args": ["-y", "@datafrog-io/n2n-nexus"]
     }
   }
 }
 ```
 
-#### 协同 AI (Guest)
+> **零配置**: 无需 `--id` 或 `--host`。直接运行即可协作！
+
+**可选**: 使用 `--root` 指定自定义存储路径：
 ```json
-{
-  "mcpServers": {
-    "n2n-nexus": {
-      "command": "npx",
-      "args": [
-        "-y",
-        "@datafrog-io/n2n-nexus",
-        "--root", "D:/DevSpace/Nexus_Storage"
-      ]
-    }
-  }
-}
+"args": ["-y", "@datafrog-io/n2n-nexus", "--root", "/path/to/storage"]
 ```
 
 ### 命令行参数
@@ -173,9 +159,11 @@ npm start -- --root ./my-storage
 
 ## ⭐ 支持本项目
 
-如果 **n2ns Nexus** 帮助您构建了更好的 AI 工作流，考虑给我们一个 Star 吧！您的支持是我们持续改进的动力。
+如果 **n2ns Nexus** 帮助您构建了更好的 AI 工作流，考虑给我们一个 Star 吧！
 
-[![Star on GitHub](https://img.shields.io/github/stars/n2ns/n2n-nexus?style=social)](https://github.com/n2ns/n2n-nexus)
+<a href="https://github.com/n2ns/n2n-nexus">
+  <img src="https://img.shields.io/github/stars/n2ns/n2n-nexus?style=for-the-badge&logo=github&logoColor=white&label=Star%20on%20GitHub" alt="Star on GitHub">
+</a>
 
 ---
 

package/docs/TODO_zh.md

@@ -69,3 +69,29 @@
 
 ---
 *最后更新日期: 2025-12-31 由 Nexus AI 助手更新。*
+
+---
+
+## 📅 2026-01-08: 全局 Hub 架构 (v0.3.0)
+
+**目标**: 实现自动 Host 选举和零配置多 IDE 协作。
+
+### 全局 Hub 实现 (已完成)
+- [x] **自动 Host 选举**: 基于端口 (5688-5700) 的选举，采用探测优先策略
+- [x] **SSE 通讯**: Guest 实例的 Stdio-to-SSE 代理
+- [x] **心跳与看门狗**: 30 秒 Host 心跳，60 秒 Guest 看门狗实现自动故障转移
+- [x] **存储路径继承**: Guest 从 Host 继承 `rootStorage` 实现无缝故障转移
+- [x] **术语重构**: 所有代码、测试和文档中 Moderator → Host
+
+### 文档更新 (已完成)
+- [x] **README**: 添加全局 Hub 架构章节（含 ASCII 架构图）
+- [x] **CHANGELOG**: 添加 v0.3.0 发布说明
+- [x] **ASSISTANT_GUIDE**: 更新至 v0.3.0，包含全局 Hub 上下文
+- [x] **零配置示例**: 简化 MCP 配置为单一 JSON 块
+
+### 测试覆盖 (已完成)
+- [x] **election.test.ts**: 9 个测试用例，覆盖探测、绑定和竞争场景
+- [x] **全部测试通过**: 55/55
+
+---
+*最后更新: 2026-01-08 由 Antigravity AI 更新。*

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@datafrog-io/n2n-nexus",
-    "version": "0.3.0",
-    "description": "Unified Project Asset & Collaboration Hub (MCP Server) designed for AI agent coordination, featuring structured metadata, real-time messaging, and dependency topology.",
+    "version": "0.3.2",
+    "description": "Modular MCP Server for multi-AI assistant coordination",
     "main": "build/index.js",
     "type": "module",
     "bin": {