@nordbyte/nordrelay 0.5.0 → 0.5.2

package/.env.example

@@ -209,6 +209,8 @@ NORDRELAY_AUDIT_MAX_EVENTS=1000
 NORDRELAY_SESSION_LOCK_TTL_MS=1800000
 # NPM version cache TTL.
 NORDRELAY_VERSION_CACHE_TTL_MS=3600000
+# Installed agent CLI version cache TTL.
+NORDRELAY_CLI_VERSION_CACHE_TTL_MS=60000
 
 # Voice
 # Optional voice transcription settings.

package/README.md

@@ -37,6 +37,7 @@ Session control:
 - `/tasks` and `/progress` show the current turn status, queue length, active tool, elapsed time, and last error.
 - `/activity` shows a compact timeline of recent rollout events for the active thread, with filters and export.
 - `/diagnostics` reports redacted runtime, config, user/group authorization, Telegram rate-limit, mirror, voice, session, queue, and progress details.
+- `/support` exports a redacted diagnostics ZIP with config, health, versions, agent paths, recent logs, audit events, update jobs, state backend, and OS/Node/npm info.
 - `/lock`, `/unlock`, and `/locks` provide a team write-lock for shared sessions so one user can operate while others watch.
 - `/audit` shows recent prompt, queue, lock, command, authentication, permission-denied, user, group, Telegram-link, Telegram-chat, and web-session audit events for admins.
 
@@ -182,10 +183,10 @@ Authentication and safety:
 Operations:
 
 - Plugin command/skill starts, stops, restarts, and inspects the connector process.
-- Manual process commands support `start`, `stop`, `restart`, `status`, and `foreground`.
-- Telegram admin commands support `/logs`, `/diagnostics`, `/restart`, and `/update` for NordRelay and agent CLIs.
-- `/update` detects the install type: npm installs update with `npm install -g @nordbyte/nordrelay@latest`; source checkouts pull `origin/main`, install dependencies, run check, tests, and build, then restart.
-- `/update agents`, `/update <agent>`, `/update jobs`, `/update log <id>`, `/update cancel <id>`, and `/update input <id> <text>` manage Codex, Pi, Hermes, OpenClaw, and Claude Code updater jobs from Telegram.
+- Manual process commands support `start`, `stop`, `restart`, `status`, `update`, and `foreground`.
+- Telegram admin commands support `/logs`, `/diagnostics`, `/support`, `/restart`, and `/update` for NordRelay and agent CLIs.
+- `nordrelay update`, `/update`, and the WebUI update button detect the install type: npm installs update with `npm install -g @nordbyte/nordrelay@latest`; source checkouts pull `origin/main`, install dependencies, run check, tests, and build, then restart if the connector is running.
+- `/update agents`, `/update <agent>`, `/update install <agent>`, `/update jobs`, `/update log <id>`, `/update cancel <id>`, and `/update input <id> <text>` manage Codex, Pi, Hermes, OpenClaw, and Claude Code updater or installer jobs from Telegram.
 - `/logs` renders redacted connector, NordRelay update, and agent update logs with local-time timestamps, levels, file path, last-modified time, and highlighted warnings/errors.
 - Logs can be emitted as timestamped plain text or JSON records with `CONNECTOR_LOG_FORMAT`.
 - Telegram sends/edits/documents are routed through a rate-limit queue that honors Telegram retry-after responses.
@@ -195,12 +196,12 @@ Operations:
 - `nordrelay init` creates a private runtime config, `nordrelay doctor` validates host prerequisites, and `nordrelay web` starts the connector plus a full local WebUI dashboard.
 - The WebUI has responsive header/sidebar/footer navigation, live chat streaming, session controls, queue/artifact/log/diagnostic views, and settings management.
 - The WebUI supports light and dark themes, tabbed settings groups, paginated session browsing, and chat uploads for images, documents, and audio transcription.
-- The WebUI exposes REST and SSE endpoints for chat streaming, sessions, settings, queue, artifacts, logs, health, and diagnostics.
+- The WebUI exposes REST and SSE endpoints for chat streaming, sessions, settings, queue, artifacts, logs, health, diagnostics, and redacted diagnostics bundle export.
 - The dashboard can bind to `127.0.0.1` or `0.0.0.0`; user login and session cookies are mandatory in both modes.
 - Telegram can run with long polling or an HTTP webhook via `TELEGRAM_TRANSPORT=webhook`.
-- Version freshness checks are cached with `NORDRELAY_VERSION_CACHE_TTL_MS` to keep `/version` responsive.
-- CI includes typecheck, tests, package dry run, npm audit, and a separate secret-scan workflow.
-- `npm run dev`, `npm run build`, `npm run check`, `npm test`, `npm start`, `npm stop`, and `npm run status` are available.
+- Version freshness checks are cached with `NORDRELAY_VERSION_CACHE_TTL_MS`, and installed agent CLI version checks are cached with `NORDRELAY_CLI_VERSION_CACHE_TTL_MS`, to keep `/version` and adapter health responsive.
+- CI runs on Ubuntu, Windows, and macOS with typecheck, Vitest, Playwright WebUI browser tests, package dry run, npm audit, and a separate secret-scan workflow.
+- `npm run dev`, `npm run build`, `npm run check`, `npm test`, `npm run test:e2e`, `npm start`, `npm stop`, and `npm run status` are available.
 - Dockerfile and `docker-compose.yml` are included for containerized operation.
 - A `launchd/start.sh` helper is included for host-managed startup.
 
@@ -355,6 +356,7 @@ nordrelay init
 nordrelay doctor
 nordrelay start
 nordrelay status
+nordrelay update
 nordrelay restart
 nordrelay stop
 nordrelay foreground
@@ -366,6 +368,7 @@ Source checkout process commands:
 ```bash
 node plugins/nordrelay/scripts/nordrelay.mjs start
 node plugins/nordrelay/scripts/nordrelay.mjs status
+node plugins/nordrelay/scripts/nordrelay.mjs update
 node plugins/nordrelay/scripts/nordrelay.mjs restart
 node plugins/nordrelay/scripts/nordrelay.mjs stop
 node plugins/nordrelay/scripts/nordrelay.mjs foreground
@@ -424,7 +427,7 @@ The dashboard is a second NordRelay client next to Telegram. It can:
 - Edit all supported runtime settings from tabbed Settings groups with option selects, validation feedback, and restart actions.
 - View filtered connector/update/agent-update logs, structured diagnostics, enabled channels, and agent adapters.
 - Inspect a per-agent capability matrix showing model, reasoning, launch, fast mode, attachments, activity, usage, auth, login/logout, and handback support.
-- Check NordRelay and agent CLI versions, then start Codex, Pi, Hermes, OpenClaw, or Claude Code updates from outdated version rows with live output, cancel, delete-log, and stdin response controls for interactive updaters.
+- Check NordRelay and agent CLI versions, then start Codex, Pi, Hermes, OpenClaw, or Claude Code updates from outdated rows or installs from not-installed rows with live output, cancel, delete-log, and stdin response controls.
 - Build dashboard CSS and client JavaScript from modular source assets through esbuild, then serve them as authenticated static assets instead of inline HTML.
 
 Dashboard API endpoints are served under `/api/*`. Streaming uses `GET /api/events`.
@@ -515,10 +518,11 @@ Run NordRelay behind your reverse proxy so the public URL forwards to `http://12
 - `/logs update [lines]` shows the self-update log. Requires `logs.read`.
 - `/logs agent [lines]` shows the aggregate agent updater log. Requires `logs.read`.
 - `/logs all [lines]` shows connector, self-update, and agent update logs together. Requires `logs.read`.
-- `/diagnostics` shows redacted connector diagnostics. Requires `logs.read`.
+- `/diagnostics` shows redacted connector diagnostics. Requires `diagnostics.read`.
+- `/support` exports a redacted diagnostics ZIP. Requires `diagnostics.read`.
 - `/restart` restarts the connector process. Requires `system.restart`.
 - `/update` updates through npm or git depending on the detected install type, then restarts only on success. Requires `updates.run`.
-- `/update agents`, `/update <agent>`, `/update jobs`, `/update log <id>`, `/update cancel <id>`, and `/update input <id> <text>` manage agent CLI update jobs. Requires `updates.run`.
+- `/update agents`, `/update <agent>`, `/update install <agent>`, `/update jobs`, `/update log <id>`, `/update cancel <id>`, and `/update input <id> <text>` manage agent CLI update and install jobs. Requires `updates.run`.
 
 ## Command Examples
 
@@ -735,6 +739,7 @@ Agent selection:
 - `NORDRELAY_AUDIT_MAX_EVENTS`: maximum audit events retained. Defaults to `1000`.
 - `NORDRELAY_SESSION_LOCK_TTL_MS`: session write-lock TTL. Defaults to `1800000`.
 - `NORDRELAY_VERSION_CACHE_TTL_MS`: npm version freshness cache TTL. Defaults to `3600000`; set `0` to disable.
+- `NORDRELAY_CLI_VERSION_CACHE_TTL_MS`: installed agent CLI version cache TTL. Defaults to `60000`; set `0` to disable.
 
 Dashboard:
 
@@ -835,8 +840,8 @@ NordRelay wrapper:
 
 - `NORDRELAY_HOME`: config/state/log directory override. Defaults to `~/.nordrelay`.
 - `NORDRELAY_SOURCE_ROOT`: runtime source root override. Useful when the plugin is launched from Codex cache.
-- `NORDRELAY_UPDATE_METHOD`: optional `auto`, `npm`, or `git` self-update method override. Auto uses git when the runtime root has a `.git` directory and npm otherwise.
-- Agent updates from the dashboard and Telegram use each agent's native updater where possible: `codex update`, `pi update pi`, `hermes update --yes`, `openclaw update --yes`, and `claude update`.
+- `NORDRELAY_UPDATE_METHOD`: optional `auto`, `npm`, or `git` self-update method override used by `nordrelay update`, `/update`, and the WebUI update button. Auto uses git when the runtime root has a `.git` directory and npm otherwise.
+- Agent updates from the dashboard and Telegram use each agent's native updater where possible: `codex update`, `pi update pi`, `hermes update --yes`, `openclaw update --yes`, and `claude update`. Not-installed agents can be installed from the dashboard or with `/update install <agent>` using npm global installs.
 - `NORDRELAY_KEEP_PENDING_UPDATES`: set true to avoid dropping pending Telegram updates on start.
 - `NORDRELAY_FORWARD_TOOL_OUTPUT`: backward-compatible alias that sets `TOOL_VERBOSITY=all` when `TOOL_VERBOSITY` is unset.
 - `NORDRELAY_STATE_FILE`: internal state-file path passed by the wrapper.
@@ -1041,9 +1046,13 @@ npm run build
 - `plugins/nordrelay/scripts/nordrelay.mjs`: process manager for `start`, `stop`, `restart`, `status`, and `foreground`.
 - `src/index.ts`: runtime entrypoint, config load, auth check, state-file writes, polling lifecycle, shutdown.
 - `src/bot.ts`: Telegram prompt/session runtime, streaming, file/photo/voice handling, artifacts, and error handling.
-- `src/telegram-access-commands.ts`, `src/telegram-update-commands.ts`, and `src/telegram-command-menu.ts`: focused Telegram command groups for access linking, update jobs, and command menu registration.
+- `src/telegram-general-commands.ts`, `src/telegram-agent-commands.ts`, `src/telegram-preference-commands.ts`, `src/telegram-access-commands.ts`, `src/telegram-diagnostics-command.ts`, `src/telegram-update-commands.ts`, `src/telegram-support-command.ts`, and `src/telegram-command-menu.ts`: focused Telegram command groups for start/help/adapters, agent/auth controls, per-chat preferences, access linking, diagnostics/log/version commands, update jobs, diagnostics bundle export, and command menu registration.
 - `src/channel-adapter.ts`, `src/channel-runtime.ts`, and `src/channel-actions.ts`: channel descriptors, generic command routing, outbound delivery contracts, and channel-neutral command responses.
 - `src/config-metadata.ts`: shared setting metadata used by the WebUI settings page and generated `.env.example`.
+- `src/support-bundle.ts` and `src/zip-writer.ts`: redacted diagnostics bundle creation with a dependency-free ZIP writer.
+- `src/relay-queue-service.ts`, `src/relay-artifact-service.ts`, and `src/relay-external-activity-monitor.ts`: Web runtime queue operations, artifact preview/export/persistence, and external CLI activity mirroring.
+- `src/relay-runtime-types.ts`: shared Runtime/WebUI DTO types used by runtime, API contracts, and dashboard code.
+- `src/web-dashboard-http.ts`, `src/web-dashboard-pages.ts`, and `src/web-dashboard-runtime-routes.ts`: dashboard HTTP helpers, HTML shell rendering, and operational runtime API routes.
 - `src/webui/`: focused WebUI source assets for core runtime state/API helpers, overview rendering, live events, chat/session workflows, admin pages, and CSS sections.
 - `src/bot-preferences.ts`: per-context mirror, notification, quiet-hour, and voice preference persistence.
 - `src/telegram-rate-limit.ts`: centralized Telegram API send/edit/document rate limiting and retry-after tracking.

package/dist/access-control.js

@@ -79,6 +79,8 @@ const COMMAND_PERMISSIONS = new Map([
     ["voice", "inspect"],
     ["whoami", "inspect"],
     ["diagnostics", "diagnostics.read"],
+    ["support", "diagnostics.read"],
+    ["diagnostics_bundle", "diagnostics.read"],
     ["logs", "logs.read"],
     ["audit", "audit.read"],
     ["restart", "system.restart"],

package/dist/agent-updates.js

@@ -7,9 +7,16 @@ import { resolveClaudeCodeCli } from "./claude-code-cli.js";
 import { resolveCodexCli } from "./codex-cli.js";
 import { resolveHermesCli } from "./hermes-cli.js";
 import { resolveOpenClawCli } from "./openclaw-cli.js";
-import { getAgentUpdateLogPath, getConnectorHome } from "./operations.js";
+import { getAgentUpdateLogPath, getConnectorHome, resolveNpmSpawnCommand } from "./operations.js";
 import { resolvePiCli } from "./pi-cli.js";
 import { redactText } from "./redaction.js";
+const AGENT_INSTALL_PACKAGES = {
+    codex: "@openai/codex",
+    pi: "@earendil-works/pi-coding-agent",
+    hermes: "hermes-agent",
+    openclaw: "openclaw",
+    "claude-code": "@anthropic-ai/claude-code",
+};
 export class AgentUpdateManager {
     options;
     jobs = new Map();
@@ -58,12 +65,12 @@ export class AgentUpdateManager {
         this.persistJobs();
         return snapshot;
     }
-    start(agentId, context = {}) {
+    start(agentId, context = {}, operation = "update") {
         const running = [...this.jobs.values()].find((job) => job.agentId === agentId && job.status === "running");
         if (running) {
-            throw new Error(`${agentLabel(agentId)} update is already running.`);
+            throw new Error(`${agentLabel(agentId)} update/install job is already running.`);
         }
-        const plan = resolveAgentUpdatePlan(agentId, { ...context, env: context.env ?? this.options.env });
+        const plan = resolveAgentUpdatePlan(agentId, { ...context, env: context.env ?? this.options.env }, operation);
         const now = new Date().toISOString();
         const id = `${agentId.replace(/[^a-z0-9]/gi, "")}-${Date.now().toString(36)}`;
         const logPath = path.join(this.home, "updates", `${id}.log`);
@@ -72,6 +79,7 @@ export class AgentUpdateManager {
             id,
             agentId,
             agentLabel: plan.agentLabel,
+            operation,
             status: "running",
             method: plan.method,
             command: plan.command,
@@ -91,16 +99,17 @@ export class AgentUpdateManager {
         this.jobs.set(id, job);
         this.persistJobs();
         this.append(job, [
-            `[${now}] Starting ${job.agentLabel} update`,
+            `[${now}] Starting ${job.agentLabel} ${job.operation}`,
             `Method: ${job.method}`,
             `Command: ${[job.command, ...job.args].join(" ")}`,
             `Working directory: ${job.cwd}`,
             "",
         ].join("\n"));
-        const child = spawn(plan.command, plan.args, {
+        const useShell = process.platform === "win32";
+        const child = spawn(useShell ? formatShellCommand(plan.command, plan.args) : plan.command, useShell ? [] : plan.args, {
             cwd: plan.cwd,
             env: { ...process.env, ...(this.options.env ?? {}), ...(context.env ?? {}) },
-            shell: process.platform === "win32",
+            shell: useShell,
             windowsHide: true,
             stdio: "pipe",
         });
@@ -115,7 +124,7 @@ export class AgentUpdateManager {
             if (job.status !== "running") {
                 return;
             }
-            this.finish(job, code === 0 ? "completed" : "failed", code, signal, code === 0 ? undefined : `Update exited with code ${code ?? "unknown"}`);
+            this.finish(job, code === 0 ? "completed" : "failed", code, signal, code === 0 ? undefined : `${capitalize(job.operation)} exited with code ${code ?? "unknown"}`);
         });
         this.emit(job);
         return this.snapshot(job);
@@ -178,7 +187,7 @@ export class AgentUpdateManager {
         job.finishedAt = new Date().toISOString();
         job.updatedAt = job.finishedAt;
         job.child = undefined;
-        this.append(job, `\n[${job.finishedAt}] ${job.agentLabel} update ${status}${error ? `: ${job.error}` : ""}\n`);
+        this.append(job, `\n[${job.finishedAt}] ${job.agentLabel} ${job.operation} ${status}${error ? `: ${job.error}` : ""}\n`);
     }
     emit(job) {
         this.options.onUpdate?.(this.snapshot(job));
@@ -205,6 +214,7 @@ export class AgentUpdateManager {
                 }
                 const job = {
                     ...snapshot,
+                    operation: snapshot.operation ?? "update",
                     status: staleRunning ? "failed" : snapshot.status,
                     canInput: false,
                     needsInput: false,
@@ -254,7 +264,10 @@ function isProcessRunning(pid) {
         return false;
     }
 }
-export function resolveAgentUpdatePlan(agentId, context = {}) {
+export function resolveAgentUpdatePlan(agentId, context = {}, operation = "update") {
+    if (operation === "install") {
+        return resolveAgentInstallPlan(agentId, context);
+    }
     const env = context.env ?? process.env;
     switch (agentId) {
         case "codex": {
@@ -294,10 +307,30 @@ export function resolveAgentUpdatePlan(agentId, context = {}) {
         }
     }
 }
+function resolveAgentInstallPlan(agentId, context = {}) {
+    const env = context.env ?? process.env;
+    const npm = resolveNpmSpawnCommand(env);
+    if (!npm) {
+        throw new Error(`Cannot install ${agentLabel(agentId)} because npm was not found on PATH.`);
+    }
+    const packageName = AGENT_INSTALL_PACKAGES[agentId];
+    return {
+        agentId,
+        agentLabel: agentLabel(agentId),
+        operation: "install",
+        method: `npm install -g ${packageName}@latest`,
+        command: npm.command,
+        args: [...npm.argsPrefix, "install", "-g", `${packageName}@latest`],
+        cwd: env.HOME || os.homedir(),
+        summary: `Installs the latest ${agentLabel(agentId)} CLI with npm. Restart NordRelay after installation if the agent was previously unavailable.`,
+        interactive: true,
+    };
+}
 function plan(agentId, method, command, args, summary, env) {
     return {
         agentId,
         agentLabel: agentLabel(agentId),
+        operation: "update",
         method,
         command,
         args,
@@ -310,3 +343,21 @@ function looksLikePrompt(text) {
     const tail = text.split(/\r?\n/).slice(-4).join("\n");
     return /\b(y\/n|yes\/no|continue|proceed|confirm|password|passphrase|token|api key|enter|select)\b|[?>]\s*$/i.test(tail);
 }
+function formatShellCommand(command, args) {
+    return [command, ...args].map(quoteWindowsCmdArg).join(" ");
+}
+function quoteWindowsCmdArg(value) {
+    if (value.length === 0) {
+        return "\"\"";
+    }
+    if (!/[\s"&|<>()^%]/.test(value)) {
+        return value;
+    }
+    return `"${value
+        .replace(/%/g, "%%")
+        .replace(/(\\*)"/g, '$1$1\\"')
+        .replace(/(\\+)$/g, "$1$1")}"`;
+}
+function capitalize(value) {
+    return value.charAt(0).toUpperCase() + value.slice(1);
+}

package/dist/bot-ui.js

@@ -67,6 +67,7 @@ export function renderHelpMessage() {
             commands: [
                 ["/logs", "Show connector log tail"],
                 ["/diagnostics", "Connector diagnostics"],
+                ["/support", "Export diagnostics bundle"],
                 ["/lock", "Lock session writes to you"],
                 ["/unlock", "Release session write lock"],
                 ["/locks", "List active write locks"],