@nordbyte/nordrelay 0.3.1 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nordbyte/nordrelay",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Remote control plane for coding agents across messaging channels.",
   "type": "module",
   "author": "Ricardo",
@@ -18,6 +18,10 @@
     "remote-control",
     "codex",
     "pi",
+    "hermes",
+    "openclaw",
+    "claude-code",
+    "claude",
     "telegram",
     "bot",
     "automation"
@@ -30,7 +34,6 @@
     "dist/",
     "plugins/",
     "launchd/",
-    "CHANGELOG.md",
     ".env.example",
     "Dockerfile",
     "docker-compose.yml"
@@ -50,9 +53,11 @@
     "test": "vitest run"
   },
   "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "^0.2.140",
     "@grammyjs/auto-retry": "^2.0.2",
     "@openai/codex-sdk": "^0.130.0",
-    "grammy": "^1.41.1"
+    "grammy": "^1.41.1",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.0",

package/plugins/nordrelay/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "nordrelay",
-  "version": "0.3.0",
-  "description": "Run a remote-control bridge for coding agents. The current adapter connects Codex sessions to Telegram with streaming replies, multi-session controls, attachments, voice input, model selection, thread browsing, and handback.",
+  "version": "0.3.1",
+  "description": "Run a remote-control bridge for coding agents. Current adapters connect Codex, Pi, Hermes, and OpenClaw sessions to Telegram with streaming replies, multi-session controls, attachments, voice input, model selection, thread browsing, and handback.",
   "author": {
     "name": "Ricardo",
     "url": "https://github.com/nordbyte"
@@ -14,6 +14,9 @@
     "messaging",
     "remote-control",
     "codex",
+    "pi",
+    "hermes",
+    "openclaw",
     "telegram",
     "bot",
     "app-server"
@@ -22,7 +25,7 @@
   "interface": {
     "displayName": "NordRelay",
     "shortDescription": "Remote-control bridge for coding agents",
-    "longDescription": "Starts NordRelay, a messaging bridge for coding agents. The current runtime connects Codex and Pi sessions to Telegram: messages become agent turns, replies and tool activity stream back to Telegram, each chat or forum topic has its own session, and commands provide thread browsing, model and reasoning controls, launch profiles, attachments, voice transcription, artifacts, login, abort, retry, and CLI handback.",
+    "longDescription": "Starts NordRelay, a messaging bridge for coding agents. The current runtime connects Codex, Pi, Hermes, and OpenClaw sessions to Telegram: messages become agent turns, replies and tool activity stream back to Telegram, each chat or forum topic has its own session, and commands provide thread browsing, model and reasoning controls, launch profiles, attachments, voice transcription, artifacts, login, abort, retry, and CLI handback.",
     "developerName": "Ricardo",
     "category": "Productivity",
     "capabilities": [
@@ -38,7 +41,7 @@
       "Show NordRelay status",
       "Stop NordRelay",
       "Show Telegram session browser",
-      "Select Codex model"
+      "Select agent model"
     ],
     "brandColor": "#229ED9",
     "composerIcon": "./assets/nordrelay.svg",

package/plugins/nordrelay/commands/remote.md

@@ -21,7 +21,7 @@ Codex plugin commands are namespaced by the plugin id in current plugin-aware co
 ## Workflow
 
 1. Locate the plugin root containing `.codex-plugin/plugin.json` with `"name": "nordrelay"`. In a source checkout this is usually `<repo>/plugins/nordrelay`.
-2. Check whether `TELEGRAM_BOT_TOKEN` and either `TELEGRAM_ALLOWED_USER_IDS`, `TELEGRAM_ALLOWED_CHAT_IDS`, or `TELEGRAM_ALLOW_ANY_CHAT=1` are available from the environment or from `.env`.
+2. Check whether `TELEGRAM_BOT_TOKEN` and `TELEGRAM_ADMIN_USER_IDS` are available from the environment or from the NordRelay env file.
 3. Run the connector command from the plugin root:
 
 ```bash
@@ -29,5 +29,5 @@ node scripts/nordrelay.mjs ${ARGUMENTS:-start}
 ```
 
 4. If `${ARGUMENTS}` is empty, use `start`.
-5. After `start` or `restart`, run `node scripts/nordrelay.mjs status` and report the PID, selected Codex thread id, and log file.
+5. After `start` or `restart`, run `node scripts/nordrelay.mjs status` and report the PID, selected thread id if visible, and log file.
 6. If startup fails because dependencies are missing, run `npm install` and `npm run build` in the repository root.

package/plugins/nordrelay/scripts/nordrelay.mjs

@@ -9,22 +9,36 @@ import readline from "node:readline/promises";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 
-const VERSION = "0.3.0";
+const FALLBACK_VERSION = "0.3.1";
 const require = createRequire(import.meta.url);
 const APP_NAME = "nordrelay";
 const SCRIPT_PATH = fileURLToPath(import.meta.url);
 const PLUGIN_ROOT = path.resolve(path.dirname(SCRIPT_PATH), "..");
 const DEFAULT_MARKETPLACE_ROOT = path.resolve(PLUGIN_ROOT, "../..");
 const RUNTIME_ROOT = findRuntimeRoot();
+const VERSION = readRuntimePackageVersion() || FALLBACK_VERSION;
 const DEFAULT_HOME = path.join(os.homedir(), ".nordrelay");
 
 function nowIso() {
   return new Date().toISOString();
 }
 
+function readRuntimePackageVersion() {
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(RUNTIME_ROOT, "package.json"), "utf8"));
+    return typeof pkg.version === "string" && pkg.version.trim() ? pkg.version.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
 function parseArgs(argv) {
   const copy = [...argv];
   let command = "foreground";
+  if (copy[0] === "--version" || copy[0] === "-v") {
+    command = "version";
+    copy.shift();
+  }
   if (copy[0] && !copy[0].startsWith("-")) {
     command = copy.shift();
   }
@@ -50,6 +64,9 @@ function parseArgs(argv) {
     else if (arg === "--admin-id") options.telegramAdminUserIds = requireValue(copy, ++i, arg);
     else if (arg === "--state-backend") options.stateBackend = requireValue(copy, ++i, arg);
     else if (arg === "--enable-pi") options.enablePi = true;
+    else if (arg === "--enable-hermes") options.enableHermes = true;
+    else if (arg === "--enable-openclaw") options.enableOpenClaw = true;
+    else if (arg === "--enable-claude-code") options.enableClaudeCode = true;
     else if (arg === "--disable-codex") options.disableCodex = true;
   }
 
@@ -250,6 +267,7 @@ async function commandStop(options) {
 }
 
 async function commandStatus(options) {
+  loadEnvFiles(options.home);
   const pid = await readPid(options.pidFile);
   const state = await readJson(options.stateFile, {});
   const running = isProcessRunning(pid);
@@ -259,6 +277,11 @@ async function commandStatus(options) {
   console.log(`Mode: ${state.sessionMode || "per Telegram context"}`);
   console.log(`Auth: ${state.authenticated === undefined ? "-" : state.authenticated ? "yes" : "no"}`);
   console.log(`Codex CLI: ${state.codexCli || "-"}`);
+  console.log(`Pi CLI: ${state.piCli || "-"}`);
+  console.log(`Hermes CLI: ${state.hermesCli || "-"}`);
+  console.log(`OpenClaw CLI: ${state.openClawCli || "-"}`);
+  console.log(`Claude Code CLI: ${state.claudeCodeCli || "-"}`);
+  console.log(`OpenClaw Gateway: ${state.openClawGateway || process.env.OPENCLAW_GATEWAY_URL || "-"}`);
   console.log(`Log: ${options.logFile}`);
   if (state.error) console.log(`Error: ${state.error}`);
 }
@@ -284,11 +307,23 @@ async function commandInit(options) {
       await ask(rl, "Telegram admin user id", "");
     const enableCodex = options.disableCodex ? "false" : await askChoice(rl, "Enable Codex", "true");
     const enablePi = options.enablePi ? "true" : await askChoice(rl, "Enable Pi", "false");
+    const enableHermes = options.enableHermes ? "true" : await askChoice(rl, "Enable Hermes", "false");
+    const enableOpenClaw = options.enableOpenClaw ? "true" : await askChoice(rl, "Enable OpenClaw", "false");
+    const enableClaudeCode = options.enableClaudeCode ? "true" : await askChoice(rl, "Enable Claude Code", "false");
     const stateBackend = options.stateBackend || await askChoice(rl, "State backend (json/sqlite)", "json");
 
     if (!telegramBotToken) throw new Error("Telegram bot token is required.");
     if (!telegramAdminUserIds) throw new Error("Telegram admin user id is required.");
-    if (enableCodex !== "true" && enablePi !== "true") throw new Error("At least one agent must be enabled.");
+    if (enableCodex !== "true" && enablePi !== "true" && enableHermes !== "true" && enableOpenClaw !== "true" && enableClaudeCode !== "true") throw new Error("At least one agent must be enabled.");
+    const defaultAgent = enableCodex === "true"
+      ? "codex"
+      : enablePi === "true"
+        ? "pi"
+        : enableHermes === "true"
+          ? "hermes"
+          : enableOpenClaw === "true"
+            ? "openclaw"
+            : "claude-code";
 
     const lines = [
       "# NordRelay local runtime config.",
@@ -298,7 +333,18 @@ async function commandInit(options) {
       "TELEGRAM_ALLOW_ANY_CHAT=false",
       `NORDRELAY_CODEX_ENABLED=${enableCodex}`,
       `NORDRELAY_PI_ENABLED=${enablePi}`,
-      `NORDRELAY_DEFAULT_AGENT=${enableCodex === "true" ? "codex" : "pi"}`,
+      `NORDRELAY_HERMES_ENABLED=${enableHermes}`,
+      `NORDRELAY_OPENCLAW_ENABLED=${enableOpenClaw}`,
+      `NORDRELAY_CLAUDE_CODE_ENABLED=${enableClaudeCode}`,
+      `NORDRELAY_DEFAULT_AGENT=${defaultAgent}`,
+      "PI_DEFAULT_PROFILE=default",
+      "HERMES_API_BASE_URL=http://127.0.0.1:8642",
+      "HERMES_DEFAULT_PROFILE=default",
+      "OPENCLAW_GATEWAY_URL=ws://127.0.0.1:18789",
+      "OPENCLAW_AGENT_ID=main",
+      "OPENCLAW_DEFAULT_PROFILE=default",
+      "CLAUDE_CODE_DEFAULT_PROFILE=default",
+      "CLAUDE_CODE_MAX_TURNS=100",
       `NORDRELAY_STATE_BACKEND=${stateBackend === "sqlite" ? "sqlite" : "json"}`,
       "TELEGRAM_TRANSPORT=polling",
       "TELEGRAM_AUTO_SEND_ARTIFACTS=false",
@@ -324,8 +370,18 @@ async function commandDoctor(options) {
   checks.push(check("Private by default", process.env.TELEGRAM_ALLOW_ANY_CHAT !== "true", "TELEGRAM_ALLOW_ANY_CHAT is not true"));
   checks.push(check("Codex enabled flag", process.env.NORDRELAY_CODEX_ENABLED !== "false", `NORDRELAY_CODEX_ENABLED=${process.env.NORDRELAY_CODEX_ENABLED ?? "true"}`));
   checks.push(check("Pi enabled flag", process.env.NORDRELAY_PI_ENABLED === "true" || process.env.NORDRELAY_PI_ENABLED === undefined, `NORDRELAY_PI_ENABLED=${process.env.NORDRELAY_PI_ENABLED ?? "false"}`, process.env.NORDRELAY_PI_ENABLED === "true" ? "pass" : "warn"));
+  checks.push(check("Hermes enabled flag", process.env.NORDRELAY_HERMES_ENABLED === "true", `NORDRELAY_HERMES_ENABLED=${process.env.NORDRELAY_HERMES_ENABLED ?? "false"}`, process.env.NORDRELAY_HERMES_ENABLED === "true" ? "pass" : "warn"));
+  checks.push(check("OpenClaw enabled flag", process.env.NORDRELAY_OPENCLAW_ENABLED === "true", `NORDRELAY_OPENCLAW_ENABLED=${process.env.NORDRELAY_OPENCLAW_ENABLED ?? "false"}`, process.env.NORDRELAY_OPENCLAW_ENABLED === "true" ? "pass" : "warn"));
+  checks.push(check("Claude Code enabled flag", process.env.NORDRELAY_CLAUDE_CODE_ENABLED === "true", `NORDRELAY_CLAUDE_CODE_ENABLED=${process.env.NORDRELAY_CLAUDE_CODE_ENABLED ?? "false"}`, process.env.NORDRELAY_CLAUDE_CODE_ENABLED === "true" ? "pass" : "warn"));
   checks.push(check("Codex CLI", Boolean(findExecutable(process.env.CODEX_CLI_PATH || "codex")), process.env.CODEX_CLI_PATH || findExecutable("codex") || "not found", process.env.NORDRELAY_CODEX_ENABLED === "false" ? "warn" : "fail"));
   checks.push(check("Pi CLI", Boolean(findExecutable(process.env.PI_CLI_PATH || "pi")), process.env.PI_CLI_PATH || findExecutable("pi") || "not found", process.env.NORDRELAY_PI_ENABLED === "true" ? "fail" : "warn"));
+  checks.push(check("Hermes CLI", Boolean(findExecutable(process.env.HERMES_CLI_PATH || "hermes")), process.env.HERMES_CLI_PATH || findExecutable("hermes") || "not found", process.env.NORDRELAY_HERMES_ENABLED === "true" ? "fail" : "warn"));
+  checks.push(check("OpenClaw CLI", Boolean(findExecutable(process.env.OPENCLAW_CLI_PATH || "openclaw")), process.env.OPENCLAW_CLI_PATH || findExecutable("openclaw") || "not found", process.env.NORDRELAY_OPENCLAW_ENABLED === "true" ? "fail" : "warn"));
+  checks.push(check("Claude Code CLI", Boolean(findExecutable(process.env.CLAUDE_CODE_CLI_PATH || "claude")), process.env.CLAUDE_CODE_CLI_PATH || findExecutable("claude") || "SDK bundled runtime", "warn"));
+  const hermesApiCheck = await checkHermesApiServer();
+  checks.push(check("Hermes API Server", hermesApiCheck.ok, hermesApiCheck.detail, process.env.NORDRELAY_HERMES_ENABLED === "true" ? "fail" : "warn"));
+  const openClawGatewayCheck = await checkOpenClawGateway();
+  checks.push(check("OpenClaw Gateway", openClawGatewayCheck.ok, openClawGatewayCheck.detail, process.env.NORDRELAY_OPENCLAW_ENABLED === "true" ? "fail" : "warn"));
   checks.push(check("ffmpeg", Boolean(findExecutable("ffmpeg")), findExecutable("ffmpeg") || "not found", "warn"));
   const stateBackendCheck = validateStateBackend();
   checks.push(check("State backend", stateBackendCheck.ok, stateBackendCheck.detail));
@@ -341,6 +397,78 @@ async function commandDoctor(options) {
   if (failed.length > 0) process.exitCode = 1;
 }
 
+async function checkHermesApiServer() {
+  const baseUrl = (process.env.HERMES_API_BASE_URL || "http://127.0.0.1:8642").replace(/\/+$/, "");
+  const headers = process.env.HERMES_API_KEY ? { authorization: `Bearer ${process.env.HERMES_API_KEY}` } : {};
+  try {
+    const response = await fetch(`${baseUrl}/health`, { headers, signal: AbortSignal.timeout(2000) });
+    return {
+      ok: response.ok,
+      detail: response.ok ? `${baseUrl}/health ok` : `${baseUrl}/health HTTP ${response.status}`,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      detail: `${baseUrl}/health failed: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
+
+async function checkOpenClawGateway() {
+  const gatewayUrl = process.env.OPENCLAW_GATEWAY_URL || "ws://127.0.0.1:18789";
+  const WebSocketClass = globalThis.WebSocket;
+  if (!WebSocketClass) {
+    return { ok: false, detail: "Node.js WebSocket runtime is unavailable" };
+  }
+
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      try {
+        socket.close();
+      } catch {
+        // Ignore close errors during diagnostics.
+      }
+      resolve(value);
+    };
+    const timeout = setTimeout(() => {
+      finish({ ok: false, detail: `${gatewayUrl} timed out` });
+    }, 2000);
+    timeout.unref?.();
+
+    let socket;
+    try {
+      socket = new WebSocketClass(gatewayUrl);
+    } catch (error) {
+      clearTimeout(timeout);
+      resolve({ ok: false, detail: `${gatewayUrl} failed: ${error instanceof Error ? error.message : String(error)}` });
+      return;
+    }
+
+    socket.addEventListener("open", () => {
+      const auth = {};
+      if (process.env.OPENCLAW_GATEWAY_TOKEN) auth.token = process.env.OPENCLAW_GATEWAY_TOKEN;
+      if (process.env.OPENCLAW_GATEWAY_PASSWORD) auth.password = process.env.OPENCLAW_GATEWAY_PASSWORD;
+      const params = {
+        client: { name: "NordRelay doctor", deviceFamily: "nordrelay" },
+        role: "operator",
+        subscribe: ["health"],
+      };
+      if (Object.keys(auth).length > 0) params.auth = auth;
+      socket.send(JSON.stringify({ type: "connect", id: "doctor", params }));
+    }, { once: true });
+    socket.addEventListener("message", () => {
+      finish({ ok: true, detail: `${gatewayUrl} reachable` });
+    }, { once: true });
+    socket.addEventListener("error", () => {
+      finish({ ok: false, detail: `${gatewayUrl} failed` });
+    }, { once: true });
+  });
+}
+
 async function commandWeb(options) {
   await mkdirp(options.home);
   loadEnvFiles(options.home);

package/plugins/nordrelay/skills/telegram-remote/SKILL.md

@@ -5,7 +5,7 @@ description: Use when the user wants to start, inspect, stop, or troubleshoot th
 
 # Telegram Remote
 
-After the bot process is running, Telegram provides the actual controls (`/new`, `/sessions`, `/sync`, `/pinned`, `/pin`, `/unpin`, `/attach`, `/handback`, `/model`, `/reasoning`, `/fast`, `/launch_profiles`, `/retry`, `/queue`, `/cancel`, `/clearqueue`, `/artifacts`, `/abort`, `/stop`, `/tasks`, `/progress`, `/status`, `/health`, `/version`, `/logs`, `/diagnostics`, `/restart`, `/update`, voice, photos, documents, media groups, artifacts, login). The Codex-side command is only a process manager.
+After the bot process is running, Telegram provides the actual controls (`/agent`, `/new`, `/sessions`, `/sync`, `/pinned`, `/pin`, `/unpin`, `/attach`, `/handback`, `/model`, `/reasoning`, `/fast`, `/launch_profiles`, `/retry`, `/queue`, `/cancel`, `/clearqueue`, `/artifacts`, `/abort`, `/stop`, `/tasks`, `/progress`, `/status`, `/health`, `/version`, `/logs`, `/diagnostics`, `/restart`, `/update`, voice, photos, documents, media groups, artifacts, login). The Codex-side command is only a process manager.
 
 Use the local connector script in the plugin root. In a source checkout, the plugin root is usually:
 
@@ -21,6 +21,6 @@ node scripts/nordrelay.mjs status
 node scripts/nordrelay.mjs stop
 ```
 
-The bridge needs `TELEGRAM_BOT_TOKEN` and either `TELEGRAM_ALLOWED_USER_IDS`, `TELEGRAM_ALLOWED_CHAT_IDS`, or `TELEGRAM_ALLOW_ANY_CHAT=1`.
+The bridge needs `TELEGRAM_BOT_TOKEN` and `TELEGRAM_ADMIN_USER_IDS` by default. Optional non-admin operators can be added with `TELEGRAM_ALLOWED_USER_IDS` or trusted group/topic access can be added with `TELEGRAM_ALLOWED_CHAT_IDS`.
 
 Prefer `start` for normal use. Use `foreground` only when debugging connection problems, because it keeps the current command running. If the runtime is missing, run `npm install` and `npm run build` in the repository root.

package/CHANGELOG.md

@@ -1,26 +0,0 @@
-# Changelog
-
-## v0.3.1 - 2026-05-12
-
-Commits since `v0.3.0`:
-
-- Move runtime home to .nordrelay.
-- Improve dashboard live status handling.
-- Separate dashboard contexts from Telegram sessions.
-- Expand dashboard controls and activity views.
-
-## v0.3.0 - 2026-05-12
-
-Commits since `v0.2.1`:
-
-- Prepare v0.3.0 release with copyable WebUI thread IDs and aligned session controls.
-- Improve dashboard usability and uploads.
-- Expand WebUI dashboard.
-- Keep dashboard server running.
-- Expand NordRelay platform features.
-- Hide missing timestamp marker in logs.
-- Show CLI paths directly in version output.
-- Add version freshness checks.
-- Render log messages as normal text.
-- Improve version and log display.
-- Improve logs and self-update behavior.