@nordbyte/nordrelay 0.5.1 → 0.6.0

package/.env.example

@@ -1,9 +1,11 @@
 # NordRelay runtime config example.
-# Access is managed with NordRelay users, groups, linked Telegram identities, and enabled Telegram group chats.
+# Access is managed with NordRelay users, groups, linked chat identities, and enabled group/guild channels.
 # Create the first admin with `nordrelay init` or `nordrelay user create-admin`.
 
 # Telegram
-# Required Telegram bot and transport settings.
+# Telegram bot and transport settings.
+# Start the Telegram bot adapter.
+TELEGRAM_ENABLED=true
 # BotFather token.
 TELEGRAM_BOT_TOKEN=123456789:replace-me
 # polling or webhook.
@@ -20,6 +22,40 @@ TELEGRAM_WEBHOOK_PATH=/telegram/webhook
 # Optional Telegram webhook secret token.
 TELEGRAM_WEBHOOK_SECRET=
 
+# Discord
+# Discord bot settings. Discord is opt-in and uses the same NordRelay users, groups, and permissions as Telegram.
+# Start the Discord bot adapter.
+DISCORD_ENABLED=false
+# Discord bot token.
+DISCORD_BOT_TOKEN=
+# Discord application/client id used for slash command registration.
+DISCORD_CLIENT_ID=
+# Comma-separated guild ids for instant guild slash-command registration.
+DISCORD_GUILD_IDS=
+# Optional comma-separated guild allow-list.
+DISCORD_ALLOWED_GUILD_IDS=
+# Optional comma-separated channel allow-list before user/group checks.
+DISCORD_ALLOWED_CHANNEL_IDS=
+# Read regular Discord text messages as prompts. Requires enabling the privileged intent in Discord.
+DISCORD_MESSAGE_CONTENT_ENABLED=true
+# slash, message, or both.
+# Options: slash, message, both
+DISCORD_COMMAND_MODE=both
+# Register Discord slash commands on startup when client id is configured.
+DISCORD_AUTO_REGISTER_COMMANDS=true
+# Optional Discord override for CLI mirror mode. Uses the NordRelay default when unset.
+# Options: off, status, final, full
+DISCORD_CLI_MIRROR_MODE=
+# Optional Discord override for mirrored edit interval.
+DISCORD_CLI_MIRROR_MIN_UPDATE_MS=
+# Optional Discord override for completion notifications.
+# Options: off, minimal, all
+DISCORD_NOTIFY_MODE=
+# Optional Discord quiet hours override. Use HH-HH, off, or leave blank for default.
+DISCORD_QUIET_HOURS=
+# Optional Discord override for automatic artifact summaries/uploads.
+DISCORD_AUTO_SEND_ARTIFACTS=
+
 # Agents
 # Agent access. Codex is enabled by default; Pi, Hermes, OpenClaw, and Claude Code are opt-in.
 # Allow Codex sessions.
@@ -161,15 +197,27 @@ ENABLE_TELEGRAM_REACTIONS=false
 TELEGRAM_RATE_LIMIT_MIN_INTERVAL_MS=80
 # Minimum edit interval.
 TELEGRAM_EDIT_MIN_INTERVAL_MS=1200
-# off, status, final, or full.
+# Default mirror mode for chat adapters: off, status, final, or full.
+# Options: off, status, final, full
+NORDRELAY_CLI_MIRROR_MODE=status
+# Default minimum mirrored edit interval.
+NORDRELAY_CLI_MIRROR_MIN_UPDATE_MS=4000
+# Default completion notifications: off, minimal, or all.
+# Options: off, minimal, all
+NORDRELAY_NOTIFY_MODE=minimal
+# Default quiet hours. Use HH-HH, off, or leave blank.
+NORDRELAY_QUIET_HOURS=
+# Default automatic artifact summaries/uploads for chat adapters.
+NORDRELAY_AUTO_SEND_ARTIFACTS=false
+# Optional Telegram override for CLI mirror mode. Uses the NordRelay default when unset.
 # Options: off, status, final, full
-TELEGRAM_CLI_MIRROR_MODE=status
-# Minimum mirrored edit interval.
-TELEGRAM_CLI_MIRROR_MIN_UPDATE_MS=4000
-# off, minimal, or all.
+TELEGRAM_CLI_MIRROR_MODE=
+# Optional Telegram override for mirrored edit interval.
+TELEGRAM_CLI_MIRROR_MIN_UPDATE_MS=
+# Optional Telegram override for completion notifications.
 # Options: off, minimal, all
-TELEGRAM_NOTIFY_MODE=minimal
-# HH-HH or blank.
+TELEGRAM_NOTIFY_MODE=
+# Optional Telegram quiet hours override. Use HH-HH, off, or leave blank for default.
 TELEGRAM_QUIET_HOURS=
 # Additional comma-separated regex patterns.
 TELEGRAM_REDACT_PATTERNS=
@@ -191,8 +239,8 @@ ARTIFACT_MAX_INBOX_DIRS=30
 ARTIFACT_IGNORE_DIRS=
 # Extra ignored glob patterns.
 ARTIFACT_IGNORE_GLOBS=
-# Automatically send artifact files.
-TELEGRAM_AUTO_SEND_ARTIFACTS=false
+# Optional Telegram override for automatic artifact summaries/uploads.
+TELEGRAM_AUTO_SEND_ARTIFACTS=
 
 # Workspace
 # State and workspace guardrails.
@@ -207,8 +255,14 @@ NORDRELAY_STATE_BACKEND=json
 NORDRELAY_AUDIT_MAX_EVENTS=1000
 # Write-lock TTL.
 NORDRELAY_SESSION_LOCK_TTL_MS=1800000
+# Stale-while-refresh TTL for expensive dashboard API snapshots.
+NORDRELAY_DASHBOARD_CACHE_TTL_MS=10000
+# Maximum persisted unified jobs retained for the WebUI jobs view.
+NORDRELAY_UNIFIED_JOB_MAX_ITEMS=1000
 # 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

@@ -1,6 +1,6 @@
 # NordRelay
 
-NordRelay is a remote control plane for coding agents across messaging channels. The current implementation connects Codex, Pi, Hermes, OpenClaw, and Claude Code coding-agent sessions to Telegram, keeps independent sessions per chat or forum topic, streams replies and tool activity back to Telegram, supports files, photos, voice input, model controls, session browsing, retry/abort, and CLI handback.
+NordRelay is a remote control plane for coding agents across messaging channels. The current implementation connects Codex, Pi, Hermes, OpenClaw, and Claude Code coding-agent sessions to Telegram and Discord, keeps independent sessions per chat, thread, forum topic, or DM, streams replies and tool activity back to the active channel, supports files, photos, voice input, model controls, session browsing, retry/abort, and CLI handback.
 
 The repo is both a local Codex marketplace and a standalone Node app. The plugin lives in `plugins/nordrelay/`; the full bot runtime lives in `src/` and uses `@openai/codex-sdk` for Codex, Pi RPC mode for Pi, the Hermes API Server for Hermes, the OpenClaw Gateway WebSocket RPC surface for OpenClaw, and the Claude Agent SDK for Claude Code.
 
@@ -43,11 +43,12 @@ Session control:
 
 Adapter architecture:
 
-- Telegram is implemented as the first channel adapter with text, typing, streaming edits, inline buttons, files, photos, voice, topics, and webhook capability metadata.
-- `/channels` shows available and planned messaging adapters for Discord, WhatsApp, Slack, and Matrix.
+- Telegram supports text, typing, streaming edits, inline buttons, files, photos, voice, forum topics, and polling/webhook transport.
+- Discord supports text, typing, streaming edits, buttons, files, photos, voice/audio transcription, guild channels, threads, DMs, message commands, and slash commands.
+- `/channels` shows available and planned messaging adapters for Telegram, Discord, WhatsApp, Slack, and Matrix.
 - Codex, Pi, Hermes, OpenClaw, and Claude Code are implemented as agent adapters.
 - `/agents` shows available/planned agent adapters and whether Codex, Pi, Hermes, OpenClaw, and Claude Code are enabled.
-- Shared command-action renderers and a channel runtime contract keep inbound commands, outbound messages, typing, files, inline actions, and streaming-ready delivery separate from Telegram-specific API calls.
+- Shared command-action renderers and a channel runtime contract keep inbound commands, outbound messages, typing, files, inline actions, and streaming-ready delivery separate from channel-specific API calls.
 
 Codex runtime:
 
@@ -159,19 +160,33 @@ Telegram output:
 - Old artifact and inbox turn directories are pruned automatically with configurable retention.
 - Optional Telegram message reactions can acknowledge work start and completion with `ENABLE_TELEGRAM_REACTIONS=true`.
 
+Discord input and output:
+
+- Enable Discord with `DISCORD_ENABLED=true` and `DISCORD_BOT_TOKEN`.
+- Set `DISCORD_CLIENT_ID` to let NordRelay register slash commands automatically.
+- `DISCORD_COMMAND_MODE=both` supports slash commands and `/command` text messages. Set it to `slash` if the bot should not read message commands.
+- `DISCORD_MESSAGE_CONTENT_ENABLED=true` lets regular Discord messages become prompts. The matching privileged intent must also be enabled in the Discord Developer Portal.
+- Discord DMs, guild channels, and threads get independent NordRelay contexts.
+- Discord attachments are staged like Telegram uploads; images are passed as image inputs and audio files are transcribed before prompting.
+- Discord buttons cover session picks, model/reasoning/launch picks, queue actions, artifact actions, update jobs, and abort where Discord component limits allow.
+- Discord slash commands mirror the Telegram command surface where Discord supports it: `/agent`, `/auth`, `/login`, `/logout`, `/session`, `/sessions`, `/new`, `/switch`, `/attach`, `/handback`, `/workspaces`, `/pin`, `/unpin`, `/pinned`, `/model`, `/reasoning`, `/fast`, `/launch`, `/launch_profiles`, `/queue`, `/stop`, `/retry`, `/sync`, `/progress`, `/activity`, `/audit`, `/artifacts`, `/logs`, `/version`, `/diagnostics`, `/restart`, `/update`, `/lock`, `/unlock`, `/mirror`, `/notify`, `/voice`, `/link`, `/whoami`, and `/register_channel`.
+
 Authentication and safety:
 
 - WebUI login is required for every dashboard page, API route, SSE stream, artifact download, and health endpoint.
-- Access is managed through NordRelay users, groups, permissions, web sessions, and linked Telegram identities.
-- Built-in groups are `Admin`, `User`, and `Read Only`; custom groups can be created in the WebUI and can restrict allowed agents, workspace roots, and Telegram chats.
+- Access is managed through NordRelay users, groups, permissions, web sessions, linked Telegram identities, and linked Discord identities.
+- Built-in groups are `Admin`, `User`, and `Read Only`; custom groups can be created in the WebUI and can restrict allowed agents, workspace roots, Telegram chats, and Discord channels.
 - The last active admin cannot be disabled or demoted, and web sessions are revoked when passwords or group memberships change.
 - Admins can review and revoke active WebUI sessions from the Users page.
 - Telegram private chats require a linked active NordRelay user.
 - Telegram group and forum chats must be registered before use; admins can run `/register_chat` in the chat or enable chats in the WebUI.
+- Discord DMs require a linked active NordRelay user.
+- Discord guild channels and threads must be registered before use; admins can run `/register_channel` in the channel or enable channels in the WebUI.
 - `/whoami` shows the linked NordRelay account and groups.
 - `/link <code>` links a Telegram account to a NordRelay user after a link code is created in the WebUI or with `nordrelay user link-code`.
-- WebUI login and Telegram link attempts are rate-limited to reduce brute-force risk.
-- User, group, Telegram-link, Telegram-chat, web-session, login, and permission-denied events are written to the audit log.
+- `/link <code>` also links a Discord account when the code was created as a Discord link code.
+- WebUI login and chat-account link attempts are rate-limited to reduce brute-force risk.
+- User, group, Telegram-link, Telegram-chat, Discord-link, Discord-channel, web-session, login, and permission-denied events are written to the audit log.
 - `/auth` reports Codex authentication, Pi provider environment health, Hermes API Server reachability, OpenClaw Gateway reachability, or Claude Code CLI auth for the selected agent.
 - `/login` starts Telegram-managed CLI auth for Codex, Hermes, or Claude Code when enabled.
 - `/logout` signs out of CLI auth for Codex, Hermes, or Claude Code; Codex logout is disabled while `CODEX_API_KEY` is in use.
@@ -183,23 +198,29 @@ 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`.
+- 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.
-- `/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.
+- `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.
+- Mirror, notification, quiet-hour, and automatic artifact-delivery defaults are configured through channel-neutral `NORDRELAY_*` settings, with Telegram and Discord override keys when a channel should differ.
+- The WebUI Tasks page includes a unified Jobs view for active WebUI turns, external CLI turns, queued prompts, agent update/install jobs, self-updates, and diagnostics bundle exports, with log, cancel, and retry actions where supported.
+- Unified Jobs are persisted across restarts and retain recent prompt, queue, update, connector-update, and support-bundle history for WebUI inspection.
+- The WebUI Metrics page reports queue state, active/completed/failed turns, job counts, average prompt duration, and Telegram/Discord rate-limit counters.
+- Expensive dashboard views such as version checks, adapter health, and diagnostics use a short stale-while-refresh server cache so the UI can render recent data while fresh checks run in the background.
 - Context metadata, queues, and preferences are written atomically with backup recovery.
 - Context metadata, queues, preferences, audit events, and locks can use JSON files or the optional SQLite state backend with `NORDRELAY_STATE_BACKEND=sqlite`.
 - Runtime config, state, and logs are written under `~/.nordrelay/`.
 - `nordrelay init` creates a private runtime config, `nordrelay doctor` validates host prerequisites, and `nordrelay web` starts the connector plus a full local WebUI dashboard.
+- On first WebUI startup without an admin account, NordRelay shows a setup wizard for creating the first admin; remote setup requires the one-time token printed in the server console.
 - 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, 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.
+- 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.
@@ -218,12 +239,16 @@ nordrelay start
 ```
 
 npm is the fastest install path and is the recommended default for normal use. `nordrelay init` writes the private runtime config to `~/.nordrelay/nordrelay.env`.
+If you start `nordrelay web` before creating an admin, the dashboard opens a first-run setup wizard. Remote setup requires the one-time setup token printed in the NordRelay console.
 
 Non-interactive setup is also supported:
 
 ```bash
 nordrelay init \
   --token 123456789:replace-me \
+  --enable-discord \
+  --discord-token "discord-bot-token" \
+  --discord-client-id "discord-client-id" \
   --admin-email you@example.com \
   --admin-name "Your Name" \
   --admin-password "replace-with-a-long-password" \
@@ -231,6 +256,7 @@ nordrelay init \
 ```
 
 `--telegram-user-id` is optional, but linking the first admin during setup is the fastest way to use Telegram immediately.
+Use `--discord-user-id <id>` with `nordrelay user create-admin` or `nordrelay user link-discord` to link Discord directly.
 
 Source checkout setup:
 
@@ -253,10 +279,23 @@ Create the Telegram bot:
 5. Create the first admin user with `nordrelay init` or `nordrelay user create-admin`.
 6. Link Telegram from the WebUI, with `nordrelay user link-telegram`, or by creating a link code and sending `/link <code>` to the bot.
 
+Create the Discord bot:
+
+1. Open the Discord Developer Portal and create an application.
+2. Add a bot user and copy the bot token into `DISCORD_BOT_TOKEN`.
+3. Copy the application client ID into `DISCORD_CLIENT_ID`.
+4. Enable the Message Content intent if you want regular Discord messages to become prompts.
+5. Invite the bot with application-command, message-send, message-read, attachment, and thread permissions.
+6. Link Discord from the WebUI, with `nordrelay user link-discord`, or by creating a Discord link code and sending `/link <code>` to the bot.
+7. In guild channels, run `/register_channel` once from an admin-linked Discord account.
+
 Minimal private-bot `~/.nordrelay/nordrelay.env`:
 
 ```dotenv
 TELEGRAM_BOT_TOKEN=123456789:replace-me
+DISCORD_ENABLED=false
+DISCORD_BOT_TOKEN=
+DISCORD_CLIENT_ID=
 NORDRELAY_CODEX_ENABLED=true
 NORDRELAY_PI_ENABLED=false
 NORDRELAY_HERMES_ENABLED=false
@@ -267,14 +306,17 @@ CODEX_SANDBOX_MODE=workspace-write
 CODEX_APPROVAL_POLICY=never
 ```
 
-User and Telegram access management:
+User and chat access management:
 
 - `nordrelay init` creates the first admin user and writes `~/.nordrelay/users.json`.
 - `nordrelay user create-admin --email you@example.com --name "Your Name"` creates another admin.
 - `nordrelay user create --email dev@example.com --name "Dev" --group user` creates a normal user.
 - `nordrelay user link-telegram --email you@example.com --telegram-user-id 123456789` links a Telegram account directly.
-- `nordrelay user link-code --email you@example.com` creates a short-lived code that the user sends as `/link <code>` to the bot.
-- Group chats are disabled until an admin enables them from the WebUI or runs `/register_chat` inside the group.
+- `nordrelay user link-discord --email you@example.com --discord-user-id 123456789012345678` links a Discord account directly.
+- `nordrelay user link-code --email you@example.com` creates a short-lived Telegram code that the user sends as `/link <code>` to the Telegram bot.
+- `nordrelay user discord-link-code --email you@example.com` creates a short-lived Discord code that the user sends as `/link <code>` to the Discord bot.
+- Telegram group chats are disabled until an admin enables them from the WebUI or runs `/register_chat` inside the group.
+- Discord guild channels are disabled until an admin enables them from the WebUI or runs `/register_channel` inside the channel.
 
 Codex authentication:
 
@@ -356,6 +398,7 @@ nordrelay init
 nordrelay doctor
 nordrelay start
 nordrelay status
+nordrelay update
 nordrelay restart
 nordrelay stop
 nordrelay foreground
@@ -367,6 +410,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
@@ -420,6 +464,7 @@ The dashboard is a second NordRelay client next to Telegram. It can:
 - Control the active session model, reasoning/thinking, fast mode, and launch profile directly from the chat view.
 - Abort turns, hand sessions back to the native CLI, and inspect the active session.
 - Manage queued prompts with pause/resume, run, cancel, reorder buttons, and drag-and-drop prioritization.
+- Inspect unified jobs across queued prompts, active turns, mirrored CLI work, agent updates, self-updates, and support-bundle exports.
 - Browse, preview, download, ZIP, and delete artifacts.
 - Inspect the activity timeline for WebUI and mirrored CLI turns.
 - Edit all supported runtime settings from tabbed Settings groups with option selects, validation feedback, and restart actions.
@@ -522,6 +567,18 @@ Run NordRelay behind your reverse proxy so the public URL forwards to `http://12
 - `/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 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`.
 
+## Discord Commands
+
+Discord supports slash commands and `/command` text messages for the shared command set. The primary differences from Telegram are:
+
+- `/register_channel` replaces `/register_chat` for guild channels and threads.
+- `/prompt <text>` is available for slash-command-only deployments where regular message content is disabled.
+- `/link <code>` consumes Discord link codes created in the WebUI or with `nordrelay user discord-link-code`.
+- `/queue`, `/sessions`, `/agent`, `/model`, `/reasoning`, `/launch`, `/artifacts`, `/update`, and `/stop` use Discord buttons where component limits allow.
+- `/artifacts latest`, `/artifacts zip latest`, `/artifacts images`, `/artifacts docs`, `/artifacts search <text>`, and `/artifacts delete <turn-id>` are available in Discord.
+- Unsafe launch profiles require explicit confirmation with `/launch <profile-id> confirm`.
+- Discord does not support Telegram reactions or Telegram webhook transport; typing, message edits, attachments, files, DMs, guild channels, and threads are supported.
+
 ## Command Examples
 
 Switching to an existing thread:
@@ -702,6 +759,7 @@ Voice transcription uses `OPENAI_API_KEY`, not `CODEX_API_KEY`.
 
 Telegram:
 
+- `TELEGRAM_ENABLED`: starts the Telegram adapter. Defaults to `true`.
 - `TELEGRAM_BOT_TOKEN`: required BotFather token.
 - `TELEGRAM_RATE_LIMIT_MIN_INTERVAL_MS`: minimum interval for normal Telegram API sends. Defaults to `80`.
 - `TELEGRAM_EDIT_MIN_INTERVAL_MS`: minimum interval for Telegram message edits. Defaults to `1200`.
@@ -711,19 +769,34 @@ Telegram:
 - `TELEGRAM_WEBHOOK_PORT`: local bind port for webhook mode. Defaults to `8080`.
 - `TELEGRAM_WEBHOOK_PATH`: webhook request path. Defaults to `/telegram/webhook`.
 - `TELEGRAM_WEBHOOK_SECRET`: optional Telegram webhook secret token.
-- `TELEGRAM_CLI_MIRROR_MODE`: default CLI mirror mode: `off`, `status`, `final`, or `full`. Defaults to `status`.
-- `TELEGRAM_CLI_MIRROR_MIN_UPDATE_MS`: minimum interval for mirrored CLI status edits. Defaults to `4000`.
-- `TELEGRAM_NOTIFY_MODE`: default notification mode: `off`, `minimal`, or `all`. Defaults to `minimal`.
-- `TELEGRAM_QUIET_HOURS`: optional quiet-hour range in `HH-HH` format, for example `22-7`.
+- `NORDRELAY_CLI_MIRROR_MODE`: default CLI mirror mode for chat adapters: `off`, `status`, `final`, or `full`. Defaults to `status`.
+- `NORDRELAY_CLI_MIRROR_MIN_UPDATE_MS`: default minimum interval for mirrored CLI status edits. Defaults to `4000`.
+- `NORDRELAY_NOTIFY_MODE`: default notification mode for chat adapters: `off`, `minimal`, or `all`. Defaults to `minimal`.
+- `NORDRELAY_QUIET_HOURS`: optional default quiet-hour range in `HH-HH` format, for example `22-7`; use `off` in a channel override to disable inherited quiet hours.
+- `NORDRELAY_AUTO_SEND_ARTIFACTS`: default automatic artifact summaries/uploads for chat adapters. Defaults to `false`.
+- `TELEGRAM_CLI_MIRROR_MODE`, `TELEGRAM_CLI_MIRROR_MIN_UPDATE_MS`, `TELEGRAM_NOTIFY_MODE`, `TELEGRAM_QUIET_HOURS`, and `TELEGRAM_AUTO_SEND_ARTIFACTS`: optional Telegram-specific overrides.
 - `TELEGRAM_REDACT_PATTERNS`: comma-separated regular expressions for additional Telegram/log redaction.
 
+Discord:
+
+- `DISCORD_ENABLED`: starts the Discord adapter. Defaults to `false`.
+- `DISCORD_BOT_TOKEN`: required Discord bot token when Discord is enabled.
+- `DISCORD_CLIENT_ID`: Discord application/client id used for slash-command registration.
+- `DISCORD_GUILD_IDS`: optional comma-separated guild ids for instant guild slash-command registration.
+- `DISCORD_ALLOWED_GUILD_IDS`: optional guild allow-list before user/group permissions are checked.
+- `DISCORD_ALLOWED_CHANNEL_IDS`: optional channel allow-list before user/group permissions are checked.
+- `DISCORD_MESSAGE_CONTENT_ENABLED`: reads regular Discord text messages as prompts. Defaults to `true`.
+- `DISCORD_COMMAND_MODE`: `slash`, `message`, or `both`. Defaults to `both`.
+- `DISCORD_AUTO_REGISTER_COMMANDS`: registers slash commands on startup when `DISCORD_CLIENT_ID` is set. Defaults to `true`.
+- `DISCORD_CLI_MIRROR_MODE`, `DISCORD_CLI_MIRROR_MIN_UPDATE_MS`, `DISCORD_NOTIFY_MODE`, `DISCORD_QUIET_HOURS`, and `DISCORD_AUTO_SEND_ARTIFACTS`: optional Discord-specific overrides for the channel-neutral defaults.
+
 User management:
 
-- Users, groups, Telegram identities, Telegram group-chat access, and web sessions are stored in `~/.nordrelay/users.json`.
-- Manage users in the WebUI Users page or with `nordrelay user list`, `create-admin`, `create`, `reset-password`, `link-telegram`, and `link-code`.
+- Users, groups, Telegram identities, Telegram group-chat access, Discord identities, Discord channel access, and web sessions are stored in `~/.nordrelay/users.json`.
+- Manage users in the WebUI Users page or with `nordrelay user list`, `create-admin`, `create`, `reset-password`, `link-telegram`, `link-discord`, `link-code`, and `discord-link-code`.
 - Built-in groups are `admin`, `user`, and `readonly`.
 - Group permissions include `inspect`, `sessions.read`, `sessions.write`, `prompt.send`, `prompt.abort`, `files.read`, `files.write`, `settings.read`, `settings.write`, `auth.manage`, `diagnostics.read`, `logs.read`, `logs.clear`, `queue.read`, `queue.write`, `updates.run`, `system.restart`, `users.read`, `users.write`, and `audit.read`.
-- Custom groups can also restrict access to specific agent ids, workspace roots, and Telegram chat ids.
+- Custom groups can also restrict access to specific agent ids, workspace roots, Telegram chat ids, and Discord channel ids.
 
 Agent selection:
 
@@ -732,11 +805,12 @@ Agent selection:
 - `NORDRELAY_HERMES_ENABLED`: enables Hermes contexts through the Hermes API Server. Defaults to `false`.
 - `NORDRELAY_OPENCLAW_ENABLED`: enables OpenClaw contexts through the OpenClaw Gateway. Defaults to `false`.
 - `NORDRELAY_CLAUDE_CODE_ENABLED`: enables Claude Code contexts through the Claude Agent SDK. Defaults to `false`.
-- `NORDRELAY_DEFAULT_AGENT`: `codex`, `pi`, `hermes`, `openclaw`, or `claude-code`, used for new Telegram contexts. Defaults to the first enabled agent.
+- `NORDRELAY_DEFAULT_AGENT`: `codex`, `pi`, `hermes`, `openclaw`, or `claude-code`, used for new chat contexts. Defaults to the first enabled agent.
 - `NORDRELAY_STATE_BACKEND`: `json` or `sqlite`. JSON is the default; SQLite requires `better-sqlite3`.
 - `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:
 
@@ -837,7 +911,7 @@ 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.
+- `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.

package/dist/access-control.js

@@ -119,6 +119,7 @@ const COMMAND_PERMISSIONS = new Map([
     ["abort", "prompt.abort"],
     ["stop", "prompt.abort"],
     ["register_chat", "users.write"],
+    ["register_channel", "users.write"],
     ["chat_access", "users.write"],
     ["link", "inspect"],
 ]);

package/dist/activity-events.js

@@ -0,0 +1,44 @@
+export function activityCategoryForType(type) {
+    if (/^(prompt|cli_turn|voice|upload|attachment)/.test(type))
+        return "prompt";
+    if (/^(session|agent_switch|handback|model_|reasoning_|fast_|launch_)/.test(type))
+        return "session";
+    if (/^queue_/.test(type))
+        return "queue";
+    if (/^agent_(install|update)/.test(type))
+        return "agent-update";
+    if (/^(artifact|artifacts)/.test(type))
+        return "artifact";
+    if (/^(auth|login|logout)/.test(type))
+        return "auth";
+    if (/^(user_|group_|telegram_chat_|telegram_link|discord_channel_|discord_link|permission_|access_|lock_)/.test(type))
+        return "security";
+    if (/^(tool_|cli_tool)/.test(type))
+        return "tool";
+    return "system";
+}
+export function activityActorLabel(actor) {
+    if (!actor) {
+        return "system";
+    }
+    return actor.label || actor.username || actor.id || actor.channelUserId || actor.channel;
+}
+export function auditCategoryForAction(action) {
+    if (/^prompt_/.test(action))
+        return "prompt";
+    if (/^queue_/.test(action))
+        return "queue";
+    if (/^lock_/.test(action))
+        return "security";
+    if (/^auth_/.test(action))
+        return "auth";
+    if (/^(permission_|user_|group_|telegram_|discord_)/.test(action))
+        return "security";
+    if (/^(artifact|file)/.test(action))
+        return "artifact";
+    if (/^(model_|reasoning_|fast_|launch_|session_|handback)/.test(action))
+        return "session";
+    if (/^(tool_)/.test(action))
+        return "tool";
+    return "system";
+}

package/dist/agent-updates.js

@@ -105,10 +105,11 @@ export class AgentUpdateManager {
             `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",
         });
@@ -342,6 +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/audit-log.js

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { auditCategoryForAction, } from "./activity-events.js";
 import { createDocumentStore } from "./state-backend.js";
 export class AuditLogStore {
     store;
@@ -18,6 +19,7 @@ export class AuditLogStore {
             id: randomUUID().replace(/-/g, "").slice(0, 12),
             timestamp: new Date().toISOString(),
             ...event,
+            category: event.category ?? auditCategoryForAction(event.action),
             channelId: event.channelId ?? "telegram",
         };
         payload.events.push(next);
@@ -27,8 +29,22 @@ export class AuditLogStore {
         this.store.write(payload);
         return next;
     }
-    list(limit = 20) {
-        return this.readPayload().events.slice(-Math.max(1, Math.min(200, limit))).reverse();
+    list(options = 20) {
+        const resolved = typeof options === "number" ? { limit: options } : options;
+        const limit = Math.max(1, Math.min(500, resolved.limit ?? 20));
+        const since = normalizeSince(resolved.since);
+        return this.readPayload().events
+            .filter((event) => !resolved.channelId || resolved.channelId === "all" || event.channelId === resolved.channelId)
+            .filter((event) => !resolved.status || resolved.status === "all" || event.status === resolved.status)
+            .filter((event) => !resolved.action || resolved.action === "all" || event.action === resolved.action)
+            .filter((event) => !resolved.category || resolved.category === "all" || (event.category ?? auditCategoryForAction(event.action)) === resolved.category)
+            .filter((event) => !resolved.agentId || resolved.agentId === "all" || event.agentId === resolved.agentId)
+            .filter((event) => !resolved.threadId || event.threadId === resolved.threadId)
+            .filter((event) => !resolved.workspace || event.workspace === resolved.workspace)
+            .filter((event) => !resolved.actor || auditActorMatches(event, resolved.actor))
+            .filter((event) => !since || Date.parse(event.timestamp) >= since)
+            .slice(-limit)
+            .reverse();
     }
     readPayload() {
         const payload = this.store.read();
@@ -41,6 +57,28 @@ export class AuditLogStore {
         };
     }
 }
+function normalizeSince(value) {
+    if (value === undefined || value === null || value === "") {
+        return null;
+    }
+    const time = typeof value === "number" ? value : Date.parse(value);
+    return Number.isFinite(time) ? time : null;
+}
+function auditActorMatches(event, query) {
+    const needle = query.trim().toLowerCase();
+    if (!needle) {
+        return true;
+    }
+    return [
+        event.actor?.id,
+        event.actor?.label,
+        event.actor?.username,
+        event.actor?.channelUserId,
+        event.actor?.channel,
+        event.actorId,
+        event.actorRole,
+    ].some((value) => String(value ?? "").toLowerCase().includes(needle));
+}
 function isAuditEvent(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {
         return false;

package/dist/bot-rendering.js

@@ -61,11 +61,12 @@ export function renderAuditEvents(events) {
     }
     const lines = events.map((event) => {
         const time = formatLocalDateTime(new Date(event.timestamp));
-        const actor = event.actorId ? `user ${event.actorId}` : "system";
+        const actor = event.actor?.label || event.actor?.username || event.actor?.id || (event.actorId ? `user ${event.actorId}` : "system");
         const prompt = event.promptId ? ` · ${event.promptId}` : "";
         const detail = event.detail ? ` · ${trimLine(event.detail, 90)}` : "";
         const description = event.description ? ` · ${trimLine(event.description, 90)}` : "";
-        return `${time} · ${event.status.toUpperCase()} · ${event.action} · ${actor}${prompt}${description}${detail}`;
+        const category = event.category ? ` · ${event.category}` : "";
+        return `${time} · ${event.status.toUpperCase()} · ${event.action}${category} · ${actor}${prompt}${description}${detail}`;
     });
     return {
         plain: ["Audit:", ...lines].join("\n"),
@@ -95,7 +96,9 @@ export function formatLockOwner(lock) {
     if (!lock) {
         return "nobody";
     }
-    return lock.ownerName ? `${lock.ownerName} (${lock.ownerId})` : `user ${lock.ownerId}`;
+    const label = lock.ownerLabel || lock.ownerUserId;
+    const channel = lock.ownerChannel ? ` via ${lock.ownerChannel}` : "";
+    return `${label} (${lock.ownerUserId})${channel}`;
 }
 export function formatTelegramName(ctx) {
     const firstName = ctx.from?.first_name?.trim();
@@ -420,13 +423,13 @@ export function renderDiagnosticsPlain(config, registry, health, authenticated,
         `Tool verbosity: ${config.toolVerbosity}`,
         `Telegram rate limit queued/running/retries/429: ${runtime.rateLimit.queued}/${runtime.rateLimit.running}/${runtime.rateLimit.retries}/${runtime.rateLimit.rateLimitHits}`,
         `Telegram last retry_after: ${runtime.rateLimit.lastRetryAfterSeconds ?? "-"}s`,
-        `CLI mirror mode/update: ${runtime.mirrorMode} / ${config.telegramMirrorMinUpdateMs} ms`,
+        `CLI mirror mode/update: ${runtime.mirrorMode} / ${config.telegramMirrorMinUpdateMs} ms (default ${config.mirrorMode} / ${config.mirrorMinUpdateMs} ms)`,
         `Notify/quiet: ${runtime.notifyMode} / ${runtime.quietHours}`,
         `Voice: ${runtime.voiceBackend} / ${runtime.voiceLanguage} / transcribe-only ${runtime.voiceTranscribeOnly ? "on" : "off"}`,
         `Sync interval: ${config.codexSyncIntervalMs} ms`,
         `External busy check/stale: ${config.codexExternalBusyCheckMs} ms / ${config.codexExternalBusyStaleMs} ms`,
         `External mirrors/timers/status messages: ${runtime.externalMirrors}/${runtime.externalQueueTimers}/${runtime.queueStatusMessages}`,
-        `Auto-send artifacts: ${config.telegramAutoSendArtifacts ? "yes" : "no"}`,
+        `Auto-send artifacts: ${config.telegramAutoSendArtifacts ? "yes" : "no"} (default ${config.autoSendArtifacts ? "yes" : "no"})`,
         `Artifact ignore dirs/globs: ${config.artifactIgnoreDirs.length}/${config.artifactIgnoreGlobs.length}`,
         `Artifact retention: ${config.artifactRetentionDays}d / ${config.artifactMaxTurnDirs} turns / ${config.artifactMaxInboxDirs} inbox dirs`,
         `Workspace allowed/warn roots: ${config.workspaceAllowedRoots.length}/${config.workspaceWarnRoots.length}`,
@@ -465,13 +468,13 @@ export function renderDiagnosticsHTML(config, registry, health, authenticated, r
         `<b>Tool verbosity:</b> <code>${escapeHTML(config.toolVerbosity)}</code>`,
         `<b>Telegram rate limit queued/running/retries/429:</b> <code>${runtime.rateLimit.queued}/${runtime.rateLimit.running}/${runtime.rateLimit.retries}/${runtime.rateLimit.rateLimitHits}</code>`,
         `<b>Telegram last retry_after:</b> <code>${escapeHTML(String(runtime.rateLimit.lastRetryAfterSeconds ?? "-"))}s</code>`,
-        `<b>CLI mirror mode/update:</b> <code>${escapeHTML(runtime.mirrorMode)} / ${config.telegramMirrorMinUpdateMs} ms</code>`,
+        `<b>CLI mirror mode/update:</b> <code>${escapeHTML(runtime.mirrorMode)} / ${config.telegramMirrorMinUpdateMs} ms (default ${config.mirrorMode} / ${config.mirrorMinUpdateMs} ms)</code>`,
         `<b>Notify/quiet:</b> <code>${escapeHTML(runtime.notifyMode)} / ${escapeHTML(runtime.quietHours)}</code>`,
         `<b>Voice:</b> <code>${escapeHTML(runtime.voiceBackend)} / ${escapeHTML(runtime.voiceLanguage)} / transcribe-only ${runtime.voiceTranscribeOnly ? "on" : "off"}</code>`,
         `<b>Sync interval:</b> <code>${config.codexSyncIntervalMs} ms</code>`,
         `<b>External busy check/stale:</b> <code>${config.codexExternalBusyCheckMs} ms / ${config.codexExternalBusyStaleMs} ms</code>`,
         `<b>External mirrors/timers/status messages:</b> <code>${runtime.externalMirrors}/${runtime.externalQueueTimers}/${runtime.queueStatusMessages}</code>`,
-        `<b>Auto-send artifacts:</b> <code>${config.telegramAutoSendArtifacts ? "yes" : "no"}</code>`,
+        `<b>Auto-send artifacts:</b> <code>${config.telegramAutoSendArtifacts ? "yes" : "no"} (default ${config.autoSendArtifacts ? "yes" : "no"})</code>`,
         `<b>Artifact ignore dirs/globs:</b> <code>${config.artifactIgnoreDirs.length}/${config.artifactIgnoreGlobs.length}</code>`,
         `<b>Artifact retention:</b> <code>${config.artifactRetentionDays}d / ${config.artifactMaxTurnDirs} turns / ${config.artifactMaxInboxDirs} inbox dirs</code>`,
         `<b>Workspace allowed/warn roots:</b> <code>${config.workspaceAllowedRoots.length}/${config.workspaceWarnRoots.length}</code>`,