nexus-channel 1.6.5

package/dist/src/transport/ws-client.js

@@ -0,0 +1,249 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WSClient = void 0;
+const ws_1 = __importDefault(require("ws"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const frames_1 = require("./frames");
+const reconnect_1 = require("./reconnect");
+const resume_store_1 = require("./resume-store");
+class WSClient {
+    constructor(config) {
+        this.ws = null;
+        this.reconnectTimer = null;
+        this.config = config;
+        this.reconnectState = (0, reconnect_1.createReconnectState)();
+        this.state = { connected: false };
+    }
+    connect() {
+        const myConnId = (0, reconnect_1.incrementConnId)(this.reconnectState);
+        if (this.ws) {
+            try {
+                this.ws.close();
+            }
+            catch { }
+            this.ws = null;
+        }
+        console.log(`[nexus] WS connecting: ${this.config.hub2dUrl} rooms=${this.config.rooms.join(',')}`);
+        this.ws = new ws_1.default(this.config.hub2dUrl);
+        this.ws.on('open', () => {
+            this.sendConnectFrame();
+        });
+        this.ws.on('message', (data) => {
+            this.handleMessage(data);
+        });
+        this.ws.on('close', (code, reason) => {
+            this.handleClose(code, reason, myConnId);
+        });
+        this.ws.on('error', (error) => {
+            console.error(`[nexus] WS error: ${error.message}`);
+        });
+    }
+    sendConnectFrame() {
+        const frame = (0, frames_1.buildConnectFrame)({
+            node: this.config.agentName,
+            rooms: this.config.rooms,
+            resumeToken: (0, resume_store_1.getResumeTokens)(),
+            token: this.config.token,
+            openclawVersion: process.env.OPENCLAW_SERVICE_VERSION || process.env.OPENCLAW_VERSION || 'unknown',
+            pluginVersion: this.readPluginVersion(),
+        });
+        this.ws?.send(JSON.stringify(frame));
+        console.log('[nexus] WS open, connect frame sent');
+    }
+    readPluginVersion() {
+        try {
+            // Walk up from __dirname to find the plugin's package.json
+            // dist/src/transport -> dist/src -> dist -> <plugin-root>
+            let dir = path.resolve(__dirname, '..');
+            for (let i = 0; i < 5 && dir; i++) {
+                const pkgPath = path.join(dir, 'package.json');
+                if (fs.existsSync(pkgPath)) {
+                    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+                    if (pkg.name === 'nexus-channel' || pkg.name?.includes('nexus')) {
+                        return pkg.version || 'unknown';
+                    }
+                }
+                dir = path.dirname(dir);
+            }
+            return 'unknown';
+        }
+        catch {
+            return 'unknown';
+        }
+    }
+    handleMessage(data) {
+        let frame;
+        try {
+            frame = JSON.parse(typeof data === 'string' ? data : data.toString());
+        }
+        catch {
+            console.error('[nexus] WS bad JSON, ignoring');
+            return;
+        }
+        switch (frame.type) {
+            case 'connected': {
+                const connectedFrame = frame;
+                (0, reconnect_1.resetReconnectDelay)(this.reconnectState);
+                this.state.connected = true;
+                this.state.pendingApproval = false;
+                if (typeof connectedFrame.user_id === 'number') {
+                    this.state.userId = connectedFrame.user_id;
+                }
+                console.log(`[nexus] WS connected: user_id=${this.state.userId} backlog_count=${JSON.stringify(connectedFrame.backlog_count || {})}`);
+                this.config.onConnected?.(connectedFrame);
+                break;
+            }
+            case 'event':
+                this.config.onEvent?.(frame);
+                break;
+            case 'ping':
+                this.ws?.send(JSON.stringify({ type: 'pong', ts: Date.now() }));
+                break;
+            case 'error': {
+                const errorFrame = frame;
+                this.state.lastError = {
+                    code: errorFrame.code || 'UNKNOWN',
+                    message: errorFrame.message || JSON.stringify(frame),
+                    ts: Date.now(),
+                };
+                if (errorFrame.code === 'PENDING_APPROVAL') {
+                    this.state.pendingApproval = true;
+                    console.warn(`[nexus] Agent pending approval: node=${this.config.agentName}. ` +
+                        'An admin must approve this agent in the Nexus UI before connecting. ' +
+                        'Will retry with reduced frequency.');
+                }
+                console.error(`[nexus] Server error: code=${this.state.lastError.code} msg=${this.state.lastError.message}`);
+                this.config.onError?.(errorFrame);
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    handleClose(code, reason, myConnId) {
+        console.log(`[nexus] WS closed: code=${code} reason=${reason.toString() || 'none'} connId=${myConnId}/${this.reconnectState.connId}`);
+        this.state.connected = false;
+        (0, resume_store_1.flushResumeTokens)();
+        if (!(0, reconnect_1.isStaleConnection)(this.reconnectState, myConnId)) {
+            this.scheduleReconnect();
+        }
+        else {
+            console.log('[nexus] WS close from stale connection, skipping reconnect');
+        }
+        this.config.onClose?.();
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+        }
+        // If pending approval, use a longer delay (60s base, 5min max)
+        const PENDING_BASE_DELAY = 60000;
+        const PENDING_MAX_DELAY = 300000;
+        if (this.state.pendingApproval) {
+            const jitter = Math.floor(Math.random() * 5000);
+            const delay = Math.min(Math.max(this.reconnectState.currentDelay, PENDING_BASE_DELAY) + jitter, PENDING_MAX_DELAY);
+            this.reconnectTimer = setTimeout(() => { this.connect(); }, delay);
+            console.log(`[nexus] Reconnecting in ${Math.round(delay / 1000)}s (pending approval)`);
+        }
+        else {
+            const { delay, timer } = (0, reconnect_1.scheduleReconnect)(this.reconnectState, () => {
+                this.connect();
+            });
+            this.reconnectTimer = timer;
+            console.log(`[nexus] Reconnecting in ${delay}ms`);
+        }
+    }
+    sendAck(roomId, eventId) {
+        if (!this.ws || this.ws.readyState !== ws_1.default.OPEN)
+            return;
+        this.ws.send(JSON.stringify((0, frames_1.buildAckFrame)(roomId, eventId)));
+    }
+    sendReply(eventId, roomId, to, text, status) {
+        if (!this.ws || this.ws.readyState !== ws_1.default.OPEN) {
+            console.error(`[nexus] Cannot send reply, WS not open (event_id=${eventId})`);
+            return;
+        }
+        this.ws.send(JSON.stringify((0, frames_1.buildReplyFrame)({
+            eventId,
+            roomId,
+            from: this.config.agentName,
+            to,
+            text,
+            status,
+        })));
+    }
+    sendMessage(roomId, text, mentions, clientMsgId) {
+        if (!this.ws || this.ws.readyState !== ws_1.default.OPEN) {
+            console.error('[nexus] Cannot send message, WS not connected');
+            return;
+        }
+        this.ws.send(JSON.stringify((0, frames_1.buildSendFrame)({
+            roomId,
+            text,
+            mentions,
+            clientMsgId,
+        })));
+    }
+    getState() {
+        return { ...this.state };
+    }
+    isConnected() {
+        return this.state.connected;
+    }
+    getUserId() {
+        return this.state.userId;
+    }
+    close() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            try {
+                this.ws.close();
+            }
+            catch { }
+            this.ws = null;
+        }
+        (0, resume_store_1.flushResumeTokens)();
+        this.state.connected = false;
+    }
+}
+exports.WSClient = WSClient;

package/dist/tests/unit/config.resolve.test.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = __importDefault(require("node:test"));
+const strict_1 = __importDefault(require("node:assert/strict"));
+const resolve_config_1 = require("../../src/config/resolve-config");
+(0, node_test_1.default)('resolveNexusConfig reads channels.nexus path', () => {
+    const result = (0, resolve_config_1.resolveNexusConfig)({
+        channels: {
+            'nexus-channel': {
+                hub2dUrl: 'ws://127.0.0.1:3001',
+                roomId: 'general',
+                agentName: 'dot',
+            },
+        },
+    });
+    strict_1.default.equal(result.hub2dUrl, 'ws://127.0.0.1:3001');
+    strict_1.default.equal(result.roomId, 'general');
+    strict_1.default.equal(result.agentName, 'dot');
+    strict_1.default.equal(result.__nexusMeta.configured, true);
+    strict_1.default.equal(result.__nexusMeta.configSource, 'channels.nexus-channel');
+});
+(0, node_test_1.default)('validateNexusConfig reports missing required fields', () => {
+    const result = (0, resolve_config_1.validateNexusConfig)({});
+    strict_1.default.equal(result.valid, false);
+    strict_1.default.ok(result.errors.includes('hub2dUrl is required'));
+    strict_1.default.ok(result.errors.includes('roomId is required'));
+    strict_1.default.ok(result.errors.includes('agentName is required'));
+});

package/dist/tests/unit/runtime.event-handler.test.js

@@ -0,0 +1,23 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = __importDefault(require("node:test"));
+const strict_1 = __importDefault(require("node:assert/strict"));
+const event_handler_1 = require("../../src/runtime/event-handler");
+(0, node_test_1.default)('getEventTimestamp parses stream id prefix', () => {
+    strict_1.default.equal((0, event_handler_1.getEventTimestamp)('1710000000000-1'), 1710000000000);
+});
+(0, node_test_1.default)('getEventDecision skips own messages', () => {
+    const decision = (0, event_handler_1.getEventDecision)({
+        event: { event_id: '1710000000000-1', room_id: 'general', from: 'dot', text: 'hello' },
+        config: { agentName: 'dot' },
+        isRecent: () => false,
+    });
+    strict_1.default.equal(decision, 'skip-own');
+});
+(0, node_test_1.default)('buildEventPrompt prepends sender identity', () => {
+    const prompt = (0, event_handler_1.buildEventPrompt)({ event_id: '1-1', room_id: 'general', from: 'boss', text: 'hello' }, { longTextThreshold: 4000 });
+    strict_1.default.equal(prompt, '[from: boss] hello');
+});

package/dist/tests/unit/transport.frames.test.js

@@ -0,0 +1,31 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = __importDefault(require("node:test"));
+const strict_1 = __importDefault(require("node:assert/strict"));
+const frames_1 = require("../../src/transport/frames");
+(0, node_test_1.default)('buildConnectFrame fills required fields', () => {
+    const frame = (0, frames_1.buildConnectFrame)({ node: 'dot', rooms: ['general'] });
+    strict_1.default.equal(frame.type, 'connect');
+    strict_1.default.equal(frame.node, 'dot');
+    strict_1.default.deepEqual(frame.rooms, ['general']);
+    strict_1.default.deepEqual(frame.resume_token, {});
+});
+(0, node_test_1.default)('buildAckFrame returns ack shape', () => {
+    strict_1.default.deepEqual((0, frames_1.buildAckFrame)('general', '1-1'), {
+        type: 'ack',
+        room_id: 'general',
+        event_id: '1-1',
+    });
+});
+(0, node_test_1.default)('buildReplyFrame mirrors text to content', () => {
+    const frame = (0, frames_1.buildReplyFrame)({ eventId: '1-1', roomId: 'general', from: 'dot', to: 'boss', text: 'ok', status: 'done' });
+    strict_1.default.equal(frame.text, 'ok');
+    strict_1.default.equal(frame.content, 'ok');
+});
+(0, node_test_1.default)('buildSendFrame includes mentions when provided', () => {
+    const frame = (0, frames_1.buildSendFrame)({ roomId: 'general', text: 'hello', mentions: ['dot'] });
+    strict_1.default.deepEqual(frame.mentions, ['dot']);
+});

package/dist/tests/unit/transport.reconnect.test.js

@@ -0,0 +1,26 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const node_test_1 = __importDefault(require("node:test"));
+const strict_1 = __importDefault(require("node:assert/strict"));
+const reconnect_1 = require("../../src/transport/reconnect");
+(0, node_test_1.default)('reconnect state starts with defaults', () => {
+    const state = (0, reconnect_1.createReconnectState)();
+    strict_1.default.equal(state.currentDelay, 1000);
+    strict_1.default.equal(state.connId, 0);
+});
+(0, node_test_1.default)('incrementConnId advances connection id', () => {
+    const state = (0, reconnect_1.createReconnectState)();
+    strict_1.default.equal((0, reconnect_1.incrementConnId)(state), 1);
+    strict_1.default.equal((0, reconnect_1.incrementConnId)(state), 2);
+});
+(0, node_test_1.default)('isStaleConnection detects stale ids', () => {
+    const state = (0, reconnect_1.createReconnectState)();
+    (0, reconnect_1.incrementConnId)(state);
+    strict_1.default.equal((0, reconnect_1.isStaleConnection)(state, 1), false);
+    strict_1.default.equal((0, reconnect_1.isStaleConnection)(state, 0), true);
+    (0, reconnect_1.resetReconnectDelay)(state);
+    strict_1.default.equal(state.currentDelay, 1000);
+});

package/openclaw.plugin.json

@@ -0,0 +1,43 @@
+{
+  "id": "nexus",
+  "name": "Nexus Hub Channel",
+  "description": "Nexus Hub 2.0 channel plugin for multi-agent collaboration via WebSocket",
+  "kind": "channel",
+  "channels": ["nexus"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  },
+  "channelConfigs": {
+    "nexus-channel": {
+      "schema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "enabled": { "type": "boolean" },
+          "hub2dUrl": { "type": "string" },
+          "roomId": { "type": "string" },
+          "agentName": { "type": "string" },
+          "token": { "type": "string" },
+          "nexusApiKey": { "type": "string" },
+          "apiPort": { "type": "integer" },
+          "gatewayPort": { "type": "integer" },
+          "gatewayToken": { "type": "string" },
+          "gatewayTimeoutMs": { "type": "integer", "minimum": 5000 },
+          "longTextThreshold": { "type": "integer", "minimum": 500 },
+          "contextInjection": { "type": "string", "enum": ["P0", "L0", "L1", "L2", "OFF"] }
+        }
+      },
+      "uiHints": {
+        "hub2dUrl": { "label": "Hub2d WS URL", "placeholder": "wss://your-hub.example.com/ws" },
+        "roomId": { "label": "Room IDs (comma-sep)", "placeholder": "general,boss" },
+        "agentName": { "label": "Agent Name", "placeholder": "serina" },
+        "token": { "label": "Agent Token", "placeholder": "nagt_...", "sensitive": true },
+        "nexusApiKey": { "label": "Nexus API Key", "placeholder": "nxk-...", "sensitive": true },
+        "gatewayTimeoutMs": { "label": "Gateway Timeout (ms)", "placeholder": "120000" },
+        "contextInjection": { "label": "Context Inject Level", "placeholder": "P0" }
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "nexus-channel",
+  "version": "1.6.5",
+  "description": "Nexus Hub 2.0 channel plugin for OpenClaw — enables agents to connect to Nexus Hub as a channel, with A2A dispatch, room summary, and Control Plane management.",
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "files": [
+    "dist/",
+    "openclaw.plugin.json"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test dist/tests/unit/*.test.js",
+    "test:src": "npm run build && npm run test",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.11.0",
+    "@types/ws": "^8.5.12",
+    "typescript": "^5.3.3"
+  },
+  "peerDependencies": {
+    "openclaw": "*"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "setupEntry": "./dist/setup-entry.js",
+    "compat": {
+      "pluginApi": ">=2026.3.0",
+      "minGatewayVersion": "2026.3.0"
+    },
+    "build": {
+      "openclawVersion": "2026.3.0",
+      "pluginSdkVersion": "2026.3.0"
+    },
+    "channel": {
+      "id": "nexus-channel",
+      "label": "Nexus Hub 2.0",
+      "selectionLabel": "Nexus Hub (WebSocket)",
+      "detailLabel": "Nexus Hub 2.0 Channel",
+      "docsPath": "/channels/nexus-channel",
+      "docsLabel": "nexus-channel",
+      "blurb": "Connect to your Nexus Hub 2.0 workspace — A2A dispatch, room summaries, and shared agent memory across rooms.",
+      "systemImage": "network",
+      "markdownCapable": true
+    },
+    "install": {
+      "npmSpec": "nexus-channel",
+      "localPath": "extensions/nexus-channel",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.3.0"
+    },
+    "bundle": {
+      "stageRuntimeDependencies": false
+    },
+    "release": {
+      "publishToNpm": true
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "author": "Your Org <your@email.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/yourorg/openclaw-nexus.git"
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "nexus",
+    "nexus-hub",
+    "channel",
+    "multi-agent"
+  ]
+}