@nordbyte/nordrelay 0.6.0 → 0.7.0

package/.env.example

@@ -264,6 +264,23 @@ NORDRELAY_VERSION_CACHE_TTL_MS=3600000
 # Installed agent CLI version cache TTL.
 NORDRELAY_CLI_VERSION_CACHE_TTL_MS=60000
 
+# Peers
+# Optional NordRelay-to-NordRelay federation. Pairing is explicit, authenticated, scoped, and TLS-protected.
+# Expose the dedicated authenticated NordRelay peer API.
+NORDRELAY_PEER_ENABLED=false
+# Human-readable name shown to paired NordRelay instances.
+NORDRELAY_PEER_NAME=
+# Bind host for the peer API. Use 127.0.0.1 for local-only or a LAN/interface IP when explicitly exposing peers.
+NORDRELAY_PEER_HOST=127.0.0.1
+# Port for the peer API.
+NORDRELAY_PEER_PORT=31979
+# Optional public URL other instances should use for this node.
+NORDRELAY_PEER_PUBLIC_URL=
+# Serve the peer API over HTTPS with an automatically generated local certificate.
+NORDRELAY_PEER_TLS_ENABLED=true
+# Reject plaintext peer serving on non-loopback hosts.
+NORDRELAY_PEER_REQUIRE_TLS=true
+
 # Voice
 # Optional voice transcription settings.
 # Whisper fallback API key.

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 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.
+NordRelay is a remote control plane for coding agents across messaging channels and paired NordRelay instances. The current implementation connects Codex, Pi, Hermes, OpenClaw, and Claude Code coding-agent sessions to Telegram, Discord, the WebUI, and trusted peer nodes, keeps independent sessions per chat, thread, forum topic, DM, or remote target, streams replies and tool activity back to the active channel, supports files, photos, voice input, model controls, session browsing, retry/abort, CLI handback, and scoped multi-host control.
 
 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.
 
@@ -50,6 +50,17 @@ Adapter architecture:
 - `/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 channel-specific API calls.
 
+Peer federation:
+
+- Optional NordRelay-to-NordRelay pairing lets one instance operate agents on trusted Ubuntu, macOS, Windows, LAN, or remote hosts.
+- Peer serving is disabled by default and uses a dedicated API port separate from the dashboard.
+- Pairing requires an explicit one-time invitation code, Ed25519 node identity verification, a per-peer shared secret, request HMAC signatures, timestamp/nonce replay protection, and TLS fingerprint pinning.
+- Peer scopes restrict which remote WebUI/API actions are allowed, including read, prompt, queue, file, diagnostic, log, and session permissions.
+- Peer records can also restrict allowed agent ids, allowed workspace roots, and per-peer workspace aliases such as `app=/srv/app`.
+- The WebUI has a Peers page plus a local/remote target selector; dashboard pages, SSE streaming, queue actions, artifact downloads, health checks, and the global session browser proxy through the selected peer when allowed.
+- Telegram and Discord expose `/peers` and `/target` so a linked user can choose whether prompts run locally or on a paired NordRelay instance.
+- Remote prompts stream text, tool status, turn completion, and errors back to the originating Telegram or Discord context.
+
 Codex runtime:
 
 - Uses `@openai/codex-sdk` to start, resume, and stream Codex threads.
@@ -162,7 +173,7 @@ Telegram output:
 
 Discord input and output:
 
-- Enable Discord with `DISCORD_ENABLED=true` and `DISCORD_BOT_TOKEN`.
+- Enable Discord with `DISCORD_ENABLED=true` and `DISCORD_BOT_TOKEN`. If a requested chat adapter is missing its token, NordRelay disables that adapter and keeps running as long as another chat adapter is usable.
 - 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.
@@ -200,6 +211,7 @@ Operations:
 - Plugin command/skill starts, stops, restarts, and inspects the connector process.
 - 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 peer identity`, `list`, `invite`, `add`, `test`, and `revoke` manage secure peer federation from the CLI.
 - `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.
@@ -217,7 +229,7 @@ Operations:
 - 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 WebUI exposes REST and SSE endpoints for chat streaming, sessions, settings, queue, artifacts, logs, health, diagnostics, peers, 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`, and installed agent CLI version checks are cached with `NORDRELAY_CLI_VERSION_CACHE_TTL_MS`, to keep `/version` and adapter health responsive.
@@ -318,6 +330,33 @@ User and chat access management:
 - 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.
 
+Peer setup:
+
+1. On each host that should accept peer connections, set `NORDRELAY_PEER_ENABLED=true` in `~/.nordrelay/nordrelay.env`.
+2. Keep `NORDRELAY_PEER_TLS_ENABLED=true` and `NORDRELAY_PEER_REQUIRE_TLS=true` for LAN or internet use.
+3. Use `NORDRELAY_PEER_HOST=127.0.0.1` for local-only testing, a LAN/interface IP for trusted local networks, or keep the peer API behind a TLS reverse proxy/VPN for internet access.
+4. Set `NORDRELAY_PEER_PUBLIC_URL=https://host.example:31979` when other hosts cannot reach the bind address directly.
+5. Restart NordRelay on the accepting host and create an invitation:
+
+```bash
+nordrelay peer invite --name workstation --scopes inspect,sessions.read,sessions.write,prompt.send,prompt.abort,queue.read,queue.write,files.read,files.write,diagnostics.read,logs.read
+```
+
+6. On the controlling host, run the printed command:
+
+```bash
+nordrelay peer add https://workstation.example:31979 --code one-time-code
+```
+
+7. Confirm the connection:
+
+```bash
+nordrelay peer list
+nordrelay peer test <peer-id>
+```
+
+Use `--workspace-aliases app=/srv/app,demo=/home/me/demo` on invites when a controller should be able to start remote sessions with short workspace names. Use the WebUI Peers page for the same invite, pair, enable/disable, test, alias, global-session, and revoke workflow. Use `/peers` from Telegram or Discord to inspect paired nodes and `/target <peer-id>` or `/target local` to choose where subsequent prompts run.
+
 Codex authentication:
 
 - Preferred local setup: run `codex login` on the host before starting the connector.
@@ -403,6 +442,9 @@ nordrelay restart
 nordrelay stop
 nordrelay foreground
 nordrelay web
+nordrelay peer list
+nordrelay peer invite
+nordrelay peer add https://peer.example:31979 --code one-time-code
 ```
 
 Source checkout process commands:
@@ -417,6 +459,7 @@ node plugins/nordrelay/scripts/nordrelay.mjs foreground
 node plugins/nordrelay/scripts/nordrelay.mjs user list
 node plugins/nordrelay/scripts/nordrelay.mjs doctor
 node plugins/nordrelay/scripts/nordrelay.mjs web
+node plugins/nordrelay/scripts/nordrelay.mjs peer list
 ```
 
 NPM shortcuts:
@@ -472,6 +515,7 @@ The dashboard is a second NordRelay client next to Telegram. It can:
 - 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 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.
+- Pair, test, enable/disable, and revoke NordRelay peers, then switch the dashboard target between the local instance and paired remote instances.
 
 Dashboard API endpoints are served under `/api/*`. Streaming uses `GET /api/events`.
 
@@ -504,6 +548,8 @@ Run NordRelay behind your reverse proxy so the public URL forwards to `http://12
 - `/channels` shows available and planned messaging adapters.
 - `/agents` shows available and planned coding-agent adapters.
 - `/agent` selects the active agent for this Telegram context.
+- `/peers` shows configured NordRelay peer instances.
+- `/target local|<peer-id>` selects whether prompts for this chat run locally or on a paired peer.
 - `/link <code>` links the Telegram account to a NordRelay user.
 - `/whoami` shows the linked NordRelay user, groups, and permissions.
 - `/register_chat` enables the current Telegram group or forum chat for NordRelay when the linked user has user-management permission.
@@ -575,6 +621,7 @@ Discord supports slash commands and `/command` text messages for the shared comm
 - `/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.
+- `/peers` and `/target local|<peer-id>` use the same paired-instance target selection as Telegram.
 - `/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.
@@ -760,7 +807,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_BOT_TOKEN`: BotFather token. Required for the Telegram adapter to start.
 - `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`.
 - `TELEGRAM_TRANSPORT`: `polling` or `webhook`. Defaults to `polling`.
@@ -780,7 +827,7 @@ Telegram:
 Discord:
 
 - `DISCORD_ENABLED`: starts the Discord adapter. Defaults to `false`.
-- `DISCORD_BOT_TOKEN`: required Discord bot token when Discord is enabled.
+- `DISCORD_BOT_TOKEN`: Discord bot token. Required for the Discord adapter to start.
 - `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.
@@ -795,9 +842,21 @@ User management:
 - 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`.
+- 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`, `audit.read`, `peers.read`, `peers.write`, and `peers.connect`.
 - Custom groups can also restrict access to specific agent ids, workspace roots, Telegram chat ids, and Discord channel ids.
 
+Peers:
+
+- `NORDRELAY_PEER_ENABLED`: starts the dedicated peer API. Defaults to `false`.
+- `NORDRELAY_PEER_NAME`: optional human-readable node name shown to paired instances.
+- `NORDRELAY_PEER_HOST`: peer API bind host. Defaults to `127.0.0.1`.
+- `NORDRELAY_PEER_PORT`: peer API port. Defaults to `31979`.
+- `NORDRELAY_PEER_PUBLIC_URL`: optional URL other instances should use to reach this node.
+- `NORDRELAY_PEER_TLS_ENABLED`: serves the peer API over HTTPS with an automatically generated local certificate. Defaults to `true`.
+- `NORDRELAY_PEER_REQUIRE_TLS`: refuses plaintext peer serving on non-loopback hosts. Defaults to `true`.
+- Peer identity, TLS certificate, peers, and invitations are stored under `~/.nordrelay/identity.json`, `~/.nordrelay/tls/`, and `~/.nordrelay/peers.json`.
+- Peer invitations expire after at most 24 hours even if a longer lifetime is requested.
+
 Agent selection:
 
 - `NORDRELAY_CODEX_ENABLED`: enables Codex contexts. Defaults to `true`.
@@ -956,12 +1015,14 @@ Unsafe profiles are intentionally gated. Telegram asks for confirmation before a
 - Link Telegram accounts only to active NordRelay users that should control agents remotely.
 - Enable Telegram group/forum chats only when the whole chat context is trusted for the permissions granted to linked users.
 - Review group permissions before granting `prompt.send`, `prompt.abort`, `files.write`, `settings.write`, `updates.run`, `system.restart`, or `users.write`.
+- Review peer scopes before granting `peers.write`, `peers.connect`, broad `prompt.send`, or unrestricted workspace roots to a paired instance.
 - Treat `danger-full-access` as equivalent to shell access on the host.
 - Treat uploaded files as untrusted input. They are staged inside the active workspace so the selected sandbox policy still matters.
 - Keep `CODEX_API_KEY`, `HERMES_API_KEY`, `OPENCLAW_GATEWAY_TOKEN`, `OPENCLAW_GATEWAY_PASSWORD`, and `OPENAI_API_KEY` in `~/.nordrelay/nordrelay.env` or host secret management.
 - In group chats, remember that any linked user with prompt permissions can prompt the selected agent in that chat context.
 - Use `TOOL_VERBOSITY=summary` or `errors-only` when command output may include sensitive data.
 - Review and unsafe launch profiles add a Telegram approve/deny gate before each turn starts.
+- Keep the peer API disabled unless needed. For internet use, expose it only through a firewall, VPN, or hardened reverse proxy; keep TLS enabled and revoke unused peers with `nordrelay peer revoke <peer-id>`.
 
 ## Troubleshooting
 

package/dist/access-control.js

@@ -20,6 +20,9 @@ export const ALL_PERMISSIONS = [
     "users.read",
     "users.write",
     "audit.read",
+    "peers.read",
+    "peers.write",
+    "peers.connect",
 ];
 export const ADMIN_GROUP_ID = "admin";
 export const USER_GROUP_ID = "user";
@@ -71,6 +74,8 @@ const COMMAND_PERMISSIONS = new Map([
     ["health", "inspect"],
     ["version", "inspect"],
     ["channels", "inspect"],
+    ["peers", "peers.read"],
+    ["target", "peers.connect"],
     ["agents", "inspect"],
     ["tasks", "inspect"],
     ["progress", "inspect"],
@@ -148,7 +153,7 @@ export function permissionForCallbackData(callbackData) {
     if (callbackData.startsWith("approval_") || callbackData.startsWith("codex_abort:") || callbackData.startsWith("agent_abort:")) {
         return "prompt.abort";
     }
-    if (callbackData.startsWith("queue_")) {
+    if (callbackData.startsWith("queue_") || callbackData.startsWith("peer_queue_")) {
         return "queue.write";
     }
     if (callbackData.startsWith("artifact_delete")) {

package/dist/activity-events.js

@@ -11,7 +11,7 @@ export function activityCategoryForType(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))
+    if (/^(user_|group_|telegram_chat_|telegram_link|discord_channel_|discord_link|peer_|permission_|access_|lock_)/.test(type))
         return "security";
     if (/^(tool_|cli_tool)/.test(type))
         return "tool";
@@ -32,7 +32,7 @@ export function auditCategoryForAction(action) {
         return "security";
     if (/^auth_/.test(action))
         return "auth";
-    if (/^(permission_|user_|group_|telegram_|discord_)/.test(action))
+    if (/^(permission_|user_|group_|telegram_|discord_|peer_)/.test(action))
         return "security";
     if (/^(artifact|file)/.test(action))
         return "artifact";

package/dist/bot-preferences.js

@@ -117,6 +117,7 @@ function normalizePreferences(value) {
         voiceBackend: isVoiceBackendPreference(candidate.voiceBackend) ? candidate.voiceBackend : undefined,
         voiceLanguage: typeof candidate.voiceLanguage === "string" ? candidate.voiceLanguage : candidate.voiceLanguage === null ? null : undefined,
         voiceTranscribeOnly: typeof candidate.voiceTranscribeOnly === "boolean" ? candidate.voiceTranscribeOnly : undefined,
+        targetPeerId: typeof candidate.targetPeerId === "string" ? candidate.targetPeerId : candidate.targetPeerId === null ? null : undefined,
     });
 }
 function pruneEmptyPreferences(preferences) {

package/dist/bot.js

@@ -12,6 +12,7 @@ import { formatSessionLabel } from "./bot-ui.js";
 import { BotPreferencesStore, isQuietNow, } from "./bot-preferences.js";
 import { renderAgentUpdateJobAction } from "./channel-actions.js";
 import { ChannelCommandService } from "./channel-command-service.js";
+import { runChannelPeerPrompt } from "./channel-peer-prompt.js";
 import { deliverChannelAction } from "./channel-runtime.js";
 import { agentLabel, agentReasoningLabel, agentReasoningOptions, } from "./agent.js";
 import { getExternalActivityForSession, getExternalSnapshotForSession, } from "./agent-activity.js";
@@ -24,6 +25,7 @@ import { escapeHTML } from "./format.js";
 import { PromptStore, toPromptEnvelope } from "./prompt-store.js";
 import { checkHermesAuthStatus, startHermesLogin, startHermesLogout } from "./hermes-auth.js";
 import { checkOpenClawAuthStatus } from "./openclaw-auth.js";
+import { RemoteRelayClient } from "./peer-client.js";
 import { checkPiAuthStatus } from "./pi-auth.js";
 import { configureRedaction, redactText } from "./redaction.js";
 import { canWriteWithLock, SessionLockStore } from "./session-locks.js";
@@ -984,6 +986,76 @@ export function createBot(config, registry) {
         ].join("\n");
         await safeReply(ctx, html, { fallbackText: plain, replyMarkup: keyboard });
     };
+    const remoteClient = new RemoteRelayClient();
+    const handleRemoteUserPrompt = async (ctx, contextKey, chatId, prompt) => {
+        const targetPeerId = preferencesStore.get(contextKey).targetPeerId ?? undefined;
+        const parsed = parseContextKey(contextKey);
+        const messageThreadId = parsed.messageThreadId;
+        return runChannelPeerPrompt({
+            targetPeerId,
+            contextKey,
+            prompt,
+            remoteClient,
+            editMinIntervalMs: config.telegramEditMinIntervalMs,
+            typingIntervalMs: TYPING_INTERVAL_MS,
+            sendTyping: () => sendChatActionSafe(ctx.api, chatId, "typing", messageThreadId),
+            sendResponse: async (text) => {
+                const message = await sendTextMessage(ctx.api, chatId, escapeHTML(text), {
+                    fallbackText: text,
+                    messageThreadId,
+                });
+                return message.message_id;
+            },
+            editResponse: (messageId, text) => safeEditMessage(bot, chatId, messageId, escapeHTML(text), {
+                fallbackText: text,
+            }),
+            sendTurnStart: (remotePrompt) => safeReply(ctx, `<b>Remote peer working on:</b>\n${escapeHTML(remotePrompt)}`, {
+                fallbackText: `Remote peer working on:\n${remotePrompt}`,
+            }),
+            sendToolStart: (toolName) => safeReply(ctx, `<b>Remote tool:</b> <code>${escapeHTML(toolName)}</code>`, {
+                fallbackText: `Remote tool: ${toolName}`,
+            }),
+            sendQueued: async (queueId) => {
+                const keyboard = queueId ? new InlineKeyboard().text("Cancel queued message", `peer_queue_cancel:${targetPeerId}:${queueId}`) : undefined;
+                await safeReply(ctx, escapeHTML(`Remote prompt queued${queueId ? `: ${queueId}` : ""}.`), {
+                    fallbackText: `Remote prompt queued${queueId ? `: ${queueId}` : ""}.`,
+                    replyMarkup: keyboard,
+                });
+            },
+            sendCompleted: () => safeReply(ctx, escapeHTML("Remote turn completed."), { fallbackText: "Remote turn completed." }),
+            sendFailure: (message) => safeReply(ctx, escapeHTML(`Remote peer failed: ${message}`), {
+                fallbackText: `Remote peer failed: ${message}`,
+            }),
+        });
+    };
+    bot.callbackQuery(/^peer_queue_cancel:([^:]+):([a-z0-9]+)$/, async (ctx) => {
+        const targetPeerId = ctx.match?.[1];
+        const queueId = ctx.match?.[2];
+        const contextKey = contextKeyFromCtx(ctx);
+        if (!targetPeerId || !queueId || !contextKey) {
+            await ctx.answerCallbackQuery();
+            return;
+        }
+        try {
+            await remoteClient.webProxy(targetPeerId, {
+                method: "POST",
+                path: "/api/queue",
+                body: { action: "cancel", id: queueId },
+                contextKey,
+            }, telegramActivityActor(ctx), contextKey);
+            await ctx.answerCallbackQuery({ text: `Cancelled remote queued prompt ${queueId}.` });
+            const chatId = ctx.chat?.id;
+            const messageId = ctx.callbackQuery.message?.message_id;
+            if (chatId && messageId) {
+                await safeEditMessage(bot, chatId, messageId, escapeHTML(`Cancelled remote queued prompt ${queueId}.`), {
+                    fallbackText: `Cancelled remote queued prompt ${queueId}.`,
+                });
+            }
+        }
+        catch (error) {
+            await ctx.answerCallbackQuery({ text: friendlyErrorText(error), show_alert: true });
+        }
+    });
     const handleUserPrompt = async (ctx, contextKey, chatId, session, prompt, options = {}) => {
         if (!canSendSystemMessagesToContext(contextKey)) {
             return;
@@ -995,6 +1067,9 @@ export function createBot(config, registry) {
             ...rawEnvelope,
             activityActor: rawEnvelope.activityActor ?? telegramActivityActor(ctx),
         };
+        if (!options.fromQueue && await handleRemoteUserPrompt(ctx, contextKey, chatId, envelope)) {
+            return;
+        }
         if (!options.fromQueue && await denyIfLocked(ctx, contextKey, session)) {
             return;
         }
@@ -1887,6 +1962,7 @@ export function createBot(config, registry) {
         isTopicContext,
         replyChannelAction,
         commandService,
+        preferencesStore,
     });
     registerTelegramAgentCommands({
         bot,
@@ -1914,14 +1990,9 @@ export function createBot(config, registry) {
     registerTelegramPreferenceCommands({
         bot,
         config,
+        commandService,
         preferencesStore,
         getContextSession,
-        getEffectiveMirrorMode,
-        getEffectiveNotifyMode,
-        getEffectiveQuietHours,
-        getEffectiveVoiceBackend,
-        getEffectiveVoiceLanguage,
-        isVoiceTranscribeOnly,
     });
     registerTelegramDiagnosticsCommands({
         bot,

package/dist/channel-adapter.js

@@ -45,7 +45,8 @@ export class TelegramChannelAdapter {
     label = "Telegram";
     capabilities = new Set(TELEGRAM_CAPABILITIES);
     describe() {
-        const enabled = process.env.TELEGRAM_ENABLED !== "false";
+        const requested = process.env.TELEGRAM_ENABLED !== "false";
+        const enabled = requested && Boolean(process.env.TELEGRAM_BOT_TOKEN);
         return {
             id: this.id,
             label: this.label,
@@ -53,8 +54,10 @@ export class TelegramChannelAdapter {
             status: "available",
             enabled,
             notes: enabled
-                ? "Telegram bot runtime is enabled by default."
-                : "Telegram bot runtime is disabled.",
+                ? "Telegram bot runtime is enabled."
+                : requested
+                    ? "Telegram bot runtime is disabled because TELEGRAM_BOT_TOKEN is missing."
+                    : "Telegram bot runtime is disabled.",
         };
     }
 }
@@ -63,7 +66,8 @@ export class DiscordChannelAdapter {
     label = "Discord";
     capabilities = new Set(DISCORD_CAPABILITIES);
     describe() {
-        const enabled = process.env.DISCORD_ENABLED === "true";
+        const requested = process.env.DISCORD_ENABLED === "true";
+        const enabled = requested && Boolean(process.env.DISCORD_BOT_TOKEN);
         return {
             id: this.id,
             label: this.label,
@@ -72,7 +76,9 @@ export class DiscordChannelAdapter {
             enabled,
             notes: enabled
                 ? "Discord bot runtime is enabled."
-                : "Enable with DISCORD_ENABLED=true and DISCORD_BOT_TOKEN.",
+                : requested
+                    ? "Discord bot runtime is disabled because DISCORD_BOT_TOKEN is missing."
+                    : "Enable with DISCORD_ENABLED=true and DISCORD_BOT_TOKEN.",
         };
     }
 }

package/dist/channel-command-catalog.js

@@ -0,0 +1,88 @@
+const textOption = (name = "value", description = "Value", required = false) => ({
+    type: 3,
+    name,
+    description,
+    required,
+});
+export const CHANNEL_COMMANDS = [
+    { name: "start", description: "Welcome and status", discordDescription: "Start or inspect the current NordRelay context" },
+    { name: "help", description: "Command reference", discordDescription: "Show Discord adapter help" },
+    { name: "prompt", description: "Send a prompt to the selected agent", telegram: false, discordOptions: [textOption("text", "Prompt text", true)] },
+    { name: "link", description: "Link account to NordRelay user", telegramDescription: "Link Telegram to NordRelay user", discordDescription: "Link this Discord account with a NordRelay code", discordOptions: [textOption("value", "Link code", true)] },
+    { name: "whoami", description: "Show your NordRelay user", discordDescription: "Show linked NordRelay user" },
+    { name: "register_chat", description: "Admin: enable this group chat", discord: false },
+    { name: "register_channel", description: "Enable this Discord channel for NordRelay", telegram: false },
+    { name: "channels", description: "Messaging adapter status", discordDescription: "Show channel adapters" },
+    { name: "peers", description: "NordRelay peer status", discordDescription: "Show paired NordRelay instances" },
+    { name: "target", description: "Select local or peer target", discordDescription: "Select local or peer target", discordOptions: [textOption("value", "local or peer id")] },
+    { name: "agents", description: "Agent adapter status", discordDescription: "Show agent adapters" },
+    { name: "agent", description: "Select agent", discordDescription: "Select or show the active agent", discordOptions: [textOption("value", "Agent id")] },
+    { name: "new", description: "Start a new thread", discordDescription: "Create a new session", discordOptions: [textOption("value", "Workspace path")] },
+    { name: "session", description: "Current thread details", discordDescription: "Show the active session" },
+    { name: "sessions", description: "Browse and switch threads", discordDescription: "Browse recent sessions", discordOptions: [textOption("query", "Search query")] },
+    { name: "switch", description: "Switch to a thread by ID", discordDescription: "Switch to a session", discordOptions: [textOption("thread_id", "Thread id", true)] },
+    { name: "attach", description: "Bind a session to this topic", discordDescription: "Attach a session", discordOptions: [textOption("thread_id", "Thread id", true)] },
+    { name: "handback", description: "Hand session back to CLI", discordDescription: "Hand the active session back to the native CLI" },
+    { name: "sync", description: "Sync active session from CLI state", discordDescription: "Sync from local agent state" },
+    { name: "pinned", description: "Show pinned threads" },
+    { name: "pin", description: "Pin current or given thread", discordOptions: [textOption("value", "Thread id")] },
+    { name: "unpin", description: "Unpin current or given thread", discordOptions: [textOption("value", "Thread id")] },
+    { name: "retry", description: "Resend the last prompt", discordDescription: "Retry the last prompt" },
+    { name: "queue", description: "Show queued prompts", discordDescription: "Show or manage queue", discordOptions: [textOption("action", "pause/resume/clear/run/cancel/top/up/down"), textOption("id", "Queue id")] },
+    { name: "cancel", description: "Cancel a queued prompt", discordOptions: [textOption("value", "Queue id", true)] },
+    { name: "clearqueue", description: "Clear queued prompts", discordDescription: "Clear queue" },
+    { name: "artifacts", description: "List or resend generated files", discordDescription: "List or send artifacts", discordOptions: [textOption("value", "zip <turn-id>")] },
+    { name: "workspaces", description: "List allowed workspaces" },
+    { name: "abort", description: "Cancel current operation", discordDescription: "Abort the active task" },
+    { name: "stop", description: "Cancel current operation", discordDescription: "Abort the active task" },
+    { name: "launch", description: "Select launch profile", discordOptions: [textOption("value", "Launch profile id")] },
+    { name: "launch_profiles", description: "Select launch profile", discordOptions: [textOption("value", "Launch profile id")] },
+    { name: "fast", description: "Toggle fast mode", discordOptions: [textOption("value", "on/off")] },
+    { name: "model", description: "View and change model", discordDescription: "Select or show models", discordOptions: [textOption("value", "Model id")] },
+    { name: "effort", description: "Set reasoning effort", discordDescription: "Select reasoning effort", discordOptions: [textOption("value", "Reasoning value")] },
+    { name: "reasoning", description: "Set reasoning effort", discordDescription: "Select reasoning effort", discordOptions: [textOption("value", "Reasoning value")] },
+    { name: "mirror", description: "Control CLI mirroring", discordDescription: "Set mirror mode", discordOptions: [textOption("value", "off/status/final/full")] },
+    { name: "notify", description: "Control notifications", discordDescription: "Set notification mode", discordOptions: [textOption("value", "off/minimal/all")] },
+    { name: "auth", description: "Check auth status", discordDescription: "Show selected agent auth status" },
+    { name: "login", description: "Start authentication", discordDescription: "Start selected agent login" },
+    { name: "logout", description: "Sign out", discordDescription: "Sign out of the selected agent" },
+    { name: "voice", description: "Voice transcription status", discordDescription: "Show or change voice settings", discordOptions: [textOption("value", "transcribe-only on/off")] },
+    { name: "tasks", description: "Current turn progress", discordDescription: "Show recent tasks", discordOptions: [textOption("value", "Limit")] },
+    { name: "progress", description: "Current turn progress", discordDescription: "Show current turn progress" },
+    { name: "activity", description: "Thread activity timeline", discordDescription: "Show recent activity", discordOptions: [textOption("value", "Limit")] },
+    { name: "audit", description: "Admin: recent audit events", discordDescription: "Show recent audit events", discordOptions: [textOption("value", "Limit")] },
+    { name: "status", description: "Connector runtime status", discordDescription: "Show status" },
+    { name: "health", description: "Connector health report", discordDescription: "Show health" },
+    { name: "version", description: "Connector version", discordDescription: "Show versions" },
+    { name: "logs", description: "Admin: show connector logs", discordDescription: "Show logs", discordOptions: [textOption("value", "Target and line count")] },
+    { name: "diagnostics", description: "Admin: connector diagnostics", discordDescription: "Show diagnostics" },
+    { name: "support", description: "Admin: export diagnostics bundle", discordDescription: "Show support diagnostics" },
+    { name: "lock", description: "Lock session writes to you", discordDescription: "Lock this context" },
+    { name: "unlock", description: "Release session write lock", discordDescription: "Unlock this context" },
+    { name: "locks", description: "List session write locks", discordDescription: "List locks" },
+    { name: "restart", description: "Admin: restart connector", discordDescription: "Restart NordRelay" },
+    { name: "update", description: "Admin: update connector or agents", discordDescription: "Update NordRelay or agents", discordOptions: [textOption("target", "jobs, install, log, cancel, input, or agent id"), textOption("agent", "Agent id or job id"), textOption("input", "Text for update input")] },
+];
+export function telegramCommandCatalog() {
+    return CHANNEL_COMMANDS
+        .filter((entry) => entry.telegram !== false)
+        .map((entry) => ({
+        command: entry.name,
+        description: entry.telegramDescription ?? entry.description,
+    }));
+}
+export function discordCommandCatalog() {
+    return CHANNEL_COMMANDS
+        .filter((entry) => entry.discord !== false)
+        .map((entry) => ({
+        name: entry.name,
+        description: entry.discordDescription ?? entry.description,
+        options: entry.discordOptions ?? [],
+    }));
+}
+export function discordHelpCommandList() {
+    return discordCommandCatalog()
+        .filter((entry) => !["start", "help", "prompt"].includes(entry.name))
+        .map((entry) => `/${entry.name}`)
+        .join(", ");
+}