@nordbyte/nordrelay 0.3.0 → 0.4.0

package/dist/web-state.js

@@ -0,0 +1,131 @@
+import { randomUUID } from "node:crypto";
+import { createDocumentStore } from "./state-backend.js";
+const DEFAULT_CHAT_LIMIT = 300;
+const DEFAULT_ACTIVITY_LIMIT = 1000;
+export class WebChatStore {
+    store;
+    maxMessages;
+    constructor(workspace, backend = "json", maxMessages = DEFAULT_CHAT_LIMIT) {
+        this.store = createDocumentStore({
+            workspace,
+            fileName: "web-chat.json",
+            sqliteKey: "web-chat",
+            backend,
+        });
+        this.maxMessages = maxMessages;
+    }
+    append(input) {
+        const payload = this.readPayload();
+        const threadId = input.threadId || "pending";
+        const messages = payload.messagesByThread[threadId] ?? [];
+        const message = {
+            id: randomId(),
+            timestamp: input.timestamp ?? new Date().toISOString(),
+            ...input,
+            threadId,
+        };
+        messages.push(message);
+        if (messages.length > this.maxMessages) {
+            messages.splice(0, messages.length - this.maxMessages);
+        }
+        payload.messagesByThread[threadId] = messages;
+        this.store.write(payload);
+        return message;
+    }
+    list(threadId, limit = 200) {
+        const messages = this.readPayload().messagesByThread[threadId || "pending"] ?? [];
+        return messages.slice(-Math.max(1, Math.min(this.maxMessages, limit)));
+    }
+    clear(threadId) {
+        const payload = this.readPayload();
+        const key = threadId || "pending";
+        const count = payload.messagesByThread[key]?.length ?? 0;
+        delete payload.messagesByThread[key];
+        this.store.write(payload);
+        return count;
+    }
+    readPayload() {
+        const payload = this.store.read();
+        if (!payload || payload.version !== 1 || !payload.messagesByThread || typeof payload.messagesByThread !== "object") {
+            return { version: 1, messagesByThread: {} };
+        }
+        const messagesByThread = {};
+        for (const [threadId, messages] of Object.entries(payload.messagesByThread)) {
+            if (Array.isArray(messages)) {
+                messagesByThread[threadId] = messages.filter(isWebChatMessage).slice(-this.maxMessages);
+            }
+        }
+        return { version: 1, messagesByThread };
+    }
+}
+export class WebActivityStore {
+    store;
+    maxEvents;
+    constructor(workspace, backend = "json", maxEvents = DEFAULT_ACTIVITY_LIMIT) {
+        this.store = createDocumentStore({
+            workspace,
+            fileName: "web-activity.json",
+            sqliteKey: "web-activity",
+            backend,
+        });
+        this.maxEvents = maxEvents;
+    }
+    append(input) {
+        const payload = this.readPayload();
+        const event = {
+            id: randomId(),
+            timestamp: input.timestamp ?? new Date().toISOString(),
+            ...input,
+        };
+        payload.events.push(event);
+        if (payload.events.length > this.maxEvents) {
+            payload.events.splice(0, payload.events.length - this.maxEvents);
+        }
+        this.store.write(payload);
+        return event;
+    }
+    list(options = {}) {
+        const limit = Math.max(1, Math.min(500, options.limit ?? 100));
+        return this.readPayload().events
+            .filter((event) => !options.source || options.source === "all" || event.source === options.source)
+            .filter((event) => !options.status || options.status === "all" || event.status === options.status)
+            .slice(-limit)
+            .reverse();
+    }
+    readPayload() {
+        const payload = this.store.read();
+        if (!payload || payload.version !== 1 || !Array.isArray(payload.events)) {
+            return { version: 1, events: [] };
+        }
+        return {
+            version: 1,
+            events: payload.events.filter(isWebActivityEvent).slice(-this.maxEvents),
+        };
+    }
+}
+function isWebChatMessage(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const candidate = value;
+    return typeof candidate.id === "string" &&
+        typeof candidate.threadId === "string" &&
+        typeof candidate.text === "string" &&
+        typeof candidate.timestamp === "string" &&
+        ["user", "agent", "system", "tool"].includes(candidate.role) &&
+        ["web", "cli"].includes(candidate.source);
+}
+function isWebActivityEvent(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const candidate = value;
+    return typeof candidate.id === "string" &&
+        typeof candidate.timestamp === "string" &&
+        typeof candidate.type === "string" &&
+        ["web", "cli"].includes(candidate.source) &&
+        ["queued", "running", "completed", "failed", "aborted", "info"].includes(candidate.status);
+}
+function randomId() {
+    return randomUUID().replace(/-/g, "").slice(0, 12);
+}

package/docker-compose.yml

@@ -3,7 +3,7 @@ services:
     build: .
     env_file: .env
     volumes:
-      - ${HOME}/.codex:/home/nordrelay/.codex:rw
+      - ${HOME}/.nordrelay:/home/nordrelay/.nordrelay:rw
       - ./workspace:/workspace:rw
     cap_drop:
       - ALL

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nordbyte/nordrelay",
-  "version": "0.3.0",
+  "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 DEFAULT_HOME = path.join(os.homedir(), ".codex", "nordrelay");
+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;
   }
 
@@ -77,16 +94,11 @@ async function mkdirp(dir) {
 }
 
 function loadEnvFiles(home) {
-  const files = [
-    path.join(process.cwd(), ".env"),
-    path.join(RUNTIME_ROOT, ".env"),
-    path.join(PLUGIN_ROOT, ".env"),
-    path.join(home, "nordrelay.env"),
-  ];
+  const envPath = process.env.NORDRELAY_ENV_FILE
+    ? path.resolve(process.env.NORDRELAY_ENV_FILE)
+    : path.join(home, "nordrelay.env");
 
-  for (const envPath of files) {
-    loadEnvFile(envPath);
-  }
+  loadEnvFile(envPath);
 
   normalizeEnvAliases();
 }
@@ -207,7 +219,7 @@ async function commandStart(options) {
       await fsp.rm(options.pidFile, { force: true });
     }
     console.log(`Startup failed. Log: ${options.logFile}`);
-    console.log(state.error || "Unknown error");
+    console.log(state.error || await readStartupError(options.logFile) || "Unknown error");
     process.exitCode = 1;
     return;
   }
@@ -255,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);
@@ -264,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}`);
 }
@@ -289,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.",
@@ -303,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",
@@ -329,10 +370,21 @@ 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"));
-  checks.push(check("State backend", validateStateBackend(), `NORDRELAY_STATE_BACKEND=${process.env.NORDRELAY_STATE_BACKEND ?? "json"}`));
+  const stateBackendCheck = validateStateBackend();
+  checks.push(check("State backend", stateBackendCheck.ok, stateBackendCheck.detail));
   checks.push(check("Runtime entry", Boolean(await resolveRuntimeEntry()), RUNTIME_ROOT));
 
   for (const item of checks) {
@@ -345,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);
@@ -439,12 +563,14 @@ async function commandForeground(options) {
     child.once("exit", (code, signal) => resolve({ code, signal }));
   });
 
+  const previousState = await readJson(options.stateFile, {});
   await writeJsonAtomic(options.stateFile, {
     status: exit.code === 0 ? "stopped" : "error",
     pid: process.pid,
     updatedAt: nowIso(),
     exitCode: exit.code,
     signal: exit.signal,
+    error: exit.code === 0 ? undefined : previousState.error,
     logFile: options.logFile,
   });
 
@@ -550,13 +676,40 @@ function findExecutable(command) {
 
 function validateStateBackend() {
   const backend = process.env.NORDRELAY_STATE_BACKEND || "json";
-  if (backend === "json") return true;
-  if (backend !== "sqlite") return false;
+  if (backend === "json") return { ok: true, detail: "NORDRELAY_STATE_BACKEND=json" };
+  if (backend !== "sqlite") return { ok: false, detail: `Invalid NORDRELAY_STATE_BACKEND=${backend}` };
   try {
-    require("better-sqlite3");
-    return true;
+    const Database = require("better-sqlite3");
+    const filePath = path.join(process.cwd(), ".nordrelay", "state.sqlite");
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const db = new Database(filePath);
+    db.exec([
+      "CREATE TABLE IF NOT EXISTS documents (",
+      "key TEXT PRIMARY KEY,",
+      "json TEXT NOT NULL,",
+      "updated_at TEXT NOT NULL",
+      ")",
+    ].join(" "));
+    db.close?.();
+    return { ok: true, detail: `NORDRELAY_STATE_BACKEND=sqlite (${filePath})` };
+  } catch (error) {
+    return {
+      ok: false,
+      detail: `NORDRELAY_STATE_BACKEND=sqlite failed: ${error instanceof Error ? error.message : String(error)}`,
+    };
+  }
+}
+
+async function readStartupError(logFile) {
+  try {
+    const lines = (await fsp.readFile(logFile, "utf8")).split(/\r?\n/).filter(Boolean).slice(-80).reverse();
+    const startupLine = lines.find((line) => line.includes("Failed to start NordRelay:"));
+    if (startupLine) return startupLine.replace(/^.*Failed to start NordRelay:\s*/, "");
+    const errorLine = lines.find((line) => /\bERROR\b/i.test(line));
+    if (errorLine) return errorLine;
+    return lines[0] || null;
   } catch {
-    return false;
+    return null;
   }
 }
 

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,17 +0,0 @@
-# Changelog
-
-## 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.