@nordbyte/nordrelay 0.5.0 → 0.5.1

package/dist/bot.js

@@ -1,46 +1,49 @@
 import { randomUUID } from "node:crypto";
-import { readFile, unlink, writeFile } from "node:fs/promises";
-import { tmpdir } from "node:os";
+import { readFile, unlink } from "node:fs/promises";
 import path from "node:path";
 import { autoRetry } from "@grammyjs/auto-retry";
 import { Bot, InlineKeyboard, InputFile } from "grammy";
 import { ADMIN_GROUP_ID } from "./access-control.js";
 import { buildFileInstructions, outboxPath, stageFile, } from "./attachments.js";
-import { collectArtifactReport, collectRecentWorkspaceArtifacts, createArtifactZipBundle, ensureOutDir, formatArtifactSummary, getArtifactTurnReport, isTelegramImagePreview, listRecentArtifactReports, persistWorkspaceArtifactReport, pruneConnectorTurnDirs, removeArtifactTurn, telegramArtifactFilename, totalArtifactSize, } from "./artifacts.js";
-import { listAgentAdapterDescriptors } from "./agent-adapter.js";
+import { collectArtifactReport, collectRecentWorkspaceArtifacts, createArtifactZipBundle, ensureOutDir, formatArtifactSummary, isTelegramImagePreview, persistWorkspaceArtifactReport, pruneConnectorTurnDirs, telegramArtifactFilename, totalArtifactSize, } from "./artifacts.js";
 import { AgentUpdateManager } from "./agent-updates.js";
 import { AuditLogStore } from "./audit-log.js";
-import { formatSessionLabel, renderHelpMessage, renderWelcomeFirstTime, renderWelcomeReturning, } from "./bot-ui.js";
-import { BotPreferencesStore, formatQuietHours, isQuietNow, parseMirrorMode, parseNotifyMode, parseQuietHours, parseVoiceBackendPreference, } from "./bot-preferences.js";
-import { logTailRequests, parseLogsCommand, renderAgentUpdateJobAction, renderAgentsAction, renderArtifactReportsAction, renderChannelsAction, renderLogTailsAction, renderQueueListAction, renderQueuedPromptDetailAction, } from "./channel-actions.js";
-import { listChannelDescriptors } from "./channel-adapter.js";
+import { formatSessionLabel } from "./bot-ui.js";
+import { BotPreferencesStore, isQuietNow, } from "./bot-preferences.js";
+import { renderAgentUpdateJobAction } from "./channel-actions.js";
 import { deliverChannelAction } from "./channel-runtime.js";
 import { agentLabel, agentReasoningLabel, agentReasoningOptions, } from "./agent.js";
-import { getAgentActivityLog, getAgentDiagnostics, getExternalActivityForSession, getExternalSnapshotForSession, } from "./agent-activity.js";
-import { enabledAgents } from "./agent-factory.js";
+import { getExternalActivityForSession, getExternalSnapshotForSession, } from "./agent-activity.js";
 import { checkAuthStatus, clearAuthCache, startLogin as startCodexLogin, startLogout as startCodexLogout } from "./codex-auth.js";
 import { checkClaudeCodeAuthStatus, startClaudeCodeLogin, startClaudeCodeLogout } from "./claude-code-auth.js";
 import { formatLaunchProfileBehavior } from "./codex-launch.js";
 import { contextKeyFromCtx, isTelegramContextKey, isTopicContextKey, parseContextKey } from "./context-key.js";
 import { friendlyErrorText } from "./error-messages.js";
 import { escapeHTML } from "./format.js";
-import { getConnectorHealth, getVersionChecks, readConnectorState, readFormattedLogTail, spawnConnectorRestart, } from "./operations.js";
 import { PromptStore, toPromptEnvelope } from "./prompt-store.js";
 import { checkHermesAuthStatus, startHermesLogin, startHermesLogout } from "./hermes-auth.js";
 import { checkOpenClawAuthStatus } from "./openclaw-auth.js";
 import { checkPiAuthStatus } from "./pi-auth.js";
 import { configureRedaction, redactText } from "./redaction.js";
 import { canWriteWithLock, SessionLockStore } from "./session-locks.js";
-import { renderLaunchSummaryHTML, renderLaunchSummaryPlain, renderSessionInfoHTML, renderSessionInfoPlain, } from "./session-format.js";
+import { renderSessionInfoHTML, renderSessionInfoPlain, } from "./session-format.js";
 import { SessionRegistry } from "./session-registry.js";
-import { getAvailableBackends, transcribeAudio } from "./voice.js";
-import { getTelegramRateLimitMetrics, telegramRateLimiter } from "./telegram-rate-limit.js";
+import { transcribeAudio } from "./voice.js";
+import { telegramRateLimiter } from "./telegram-rate-limit.js";
 import { chatBucket, downloadTelegramFile, isMessageNotModifiedError, renderMarkdownChunkWithinLimit, safeEditMessage, safeEditReplyMarkup, safeReply, sendChatActionSafe, sendTextMessage, splitMarkdownForTelegram, } from "./telegram-output.js";
 import { NOOP_PAGE_CALLBACK_DATA, TelegramBotChannelRuntime, paginateKeyboard, telegramChannelContextFromCtx, } from "./telegram-channel-runtime.js";
 import { createTelegramAccessMiddleware } from "./telegram-access-middleware.js";
 import { registerTelegramAccessCommands } from "./telegram-access-commands.js";
+import { registerTelegramAgentCommands } from "./telegram-agent-commands.js";
+import { registerTelegramArtifactCommands } from "./telegram-artifact-commands.js";
+import { registerTelegramDiagnosticsCommands } from "./telegram-diagnostics-command.js";
+import { registerTelegramGeneralCommands } from "./telegram-general-commands.js";
+import { registerTelegramOperationalCommands } from "./telegram-operational-commands.js";
+import { registerTelegramPreferenceCommands } from "./telegram-preference-commands.js";
+import { createQueuedPromptCancelKeyboard, registerTelegramQueueCommands, } from "./telegram-queue-commands.js";
+import { registerTelegramSupportCommands } from "./telegram-support-command.js";
 import { registerTelegramUpdateCommands } from "./telegram-update-commands.js";
-import { appendWithCap, authHelpText, buildArtifactActionsKeyboard, buildStreamingPreview, capabilitiesOf, filterActivityEvents, filterArtifactReports, filterSessions, formatAgentLaunchProfileLabel, formatAgentSettingScope, formatCliPathHTML, formatCliPathPlain, formatDurationSeconds, formatError, formatLocalDateTime, formatLockOwner, formatModelButtonLabel, formatRelativeTime, formatTelegramName, formatToolSummaryLine, formatTurnUsageLine, getWorkspaceShortName, idOf, isEmptyArtifactReport, isPromptEnvelopeLike, isQueuedPromptLike, labelOf, orderPinnedSessions, parseActivityOptions, parseFastModeArgument, parseToggle, renderActivityTimeline, renderAgentDiagnostics, renderAuditEvents, renderDiagnosticsHTML, renderDiagnosticsPlain, renderExternalMirrorEvent, renderExternalMirrorStatus, renderHealthHTML, renderHealthPlain, renderPromptFailure, renderProgressHTML, renderProgressPlain, renderSessionLocks, renderTodoList, renderToolEndMessage, renderToolStartMessage, renderVersionCheckHTML, renderVersionCheckPlain, requiresTurnApproval, trimLine, } from "./bot-rendering.js";
+import { appendWithCap, authHelpText, buildStreamingPreview, capabilitiesOf, filterSessions, formatAgentLaunchProfileLabel, formatAgentSettingScope, formatDurationSeconds, formatError, formatLocalDateTime, formatLockOwner, formatModelButtonLabel, formatRelativeTime, formatTelegramName, formatToolSummaryLine, formatTurnUsageLine, getWorkspaceShortName, idOf, isEmptyArtifactReport, isPromptEnvelopeLike, isQueuedPromptLike, labelOf, orderPinnedSessions, parseFastModeArgument, renderExternalMirrorEvent, renderExternalMirrorStatus, renderPromptFailure, renderTodoList, renderToolEndMessage, renderToolStartMessage, requiresTurnApproval, trimLine, } from "./bot-rendering.js";
 import { UserStore } from "./user-management.js";
 import { evaluateWorkspacePolicy, filterAllowedWorkspaces, renderWorkspacePolicyLine, } from "./workspace-policy.js";
 export { formatToolSummaryLine, formatTurnUsageLine, summarizeToolName } from "./bot-rendering.js";
@@ -222,9 +225,9 @@ export function createBot(config, registry) {
         openClawCliPath: config.openClawCliPath,
         claudeCodeCliPath: config.claudeCodeCliPath,
     });
-    const startTelegramAgentUpdate = async (ctx, agentId) => {
+    const startTelegramAgentUpdate = async (ctx, agentId, operation = "update") => {
         try {
-            const job = agentUpdates.start(agentId, agentUpdateContext());
+            const job = agentUpdates.start(agentId, agentUpdateContext(), operation);
             const contextKey = contextKeyFromCtx(ctx);
             if (contextKey) {
                 audit({
@@ -232,7 +235,7 @@ export function createBot(config, registry) {
                     status: "ok",
                     contextKey,
                     agentId,
-                    description: `update ${agentId}`,
+                    description: `${operation} ${agentId}`,
                     detail: job.summary,
                 });
             }
@@ -240,8 +243,9 @@ export function createBot(config, registry) {
             await replyChannelAction(ctx, rendered);
         }
         catch (error) {
-            const message = `Failed to start ${agentLabel(agentId)} update: ${friendlyErrorText(error)}`;
-            await safeReply(ctx, `<b>Update failed:</b> ${escapeHTML(message)}`, { fallbackText: message });
+            const message = `Failed to start ${agentLabel(agentId)} ${operation}: ${friendlyErrorText(error)}`;
+            const label = operation === "install" ? "Install" : "Update";
+            await safeReply(ctx, `<b>${label} failed:</b> ${escapeHTML(message)}`, { fallbackText: message });
         }
     };
     const startAgentLogin = (info) => {
@@ -344,28 +348,6 @@ export function createBot(config, registry) {
             fallbackText: "Still working on previous message...",
         });
     };
-    const queueCancelCallbackData = (action, contextKey, queueId) => `queue_${action}:${contextKey}:${queueId}`;
-    const createQueuedPromptCancelKeyboard = (contextKey, queueId, label = "Cancel queued message") => new InlineKeyboard().text(label, queueCancelCallbackData("cancel", contextKey, queueId));
-    const renderQueueList = (contextKey, queue) => {
-        const paused = promptStore.isPaused(contextKey);
-        const rendered = renderQueueListAction(queue, paused);
-        if (queue.length === 0) {
-            return rendered;
-        }
-        const keyboard = new InlineKeyboard();
-        queue.forEach((item, index) => {
-            keyboard
-                .text(`Run ${index + 1}`, queueCancelCallbackData("run", contextKey, item.id))
-                .text("Top", queueCancelCallbackData("top", contextKey, item.id))
-                .text("Cancel", queueCancelCallbackData("remove", contextKey, item.id))
-                .row();
-            keyboard
-                .text("Up", queueCancelCallbackData("up", contextKey, item.id))
-                .text("Down", queueCancelCallbackData("down", contextKey, item.id))
-                .row();
-        });
-        return { ...rendered, keyboard };
-    };
     const createSystemContext = (contextKey) => {
         const parsed = parseContextKey(contextKey);
         return {
@@ -1603,616 +1585,78 @@ export function createBot(config, registry) {
     };
     bot.use(createTelegramAccessMiddleware({ userStore, contextUsers, audit }));
     registerTelegramAccessCommands({ bot, userStore, contextUsers, linkAttempts, audit, getUserRole });
-    bot.command("start", async (ctx) => {
-        const contextSession = await getContextSession(ctx, { deferThreadStart: true });
-        if (!contextSession) {
-            return;
-        }
-        const { contextKey, session } = contextSession;
-        const info = session.getInfo();
-        const authStatus = capabilitiesOf(info).auth ? await checkAgentAuthStatus(info) : null;
-        const authWarning = authStatus && !authStatus.authenticated
-            ? [`${labelOf(info)} is not authenticated.`, authStatus.detail, authHelpText(info)].filter(Boolean).join(" ")
-            : undefined;
-        const isReturning = registry.hasMetadata(contextKey);
-        if (isReturning) {
-            const welcome = renderWelcomeReturning(renderSessionInfoHTML(info), renderSessionInfoPlain(info), isTopicContext(contextKey), authWarning);
-            await safeReply(ctx, welcome.html, { fallbackText: welcome.plain });
-        }
-        else {
-            const welcome = renderWelcomeFirstTime(authWarning);
-            await safeReply(ctx, [welcome.html, "", renderLaunchSummaryHTML(info)].join("\n"), {
-                fallbackText: [welcome.plain, "", renderLaunchSummaryPlain(info)].join("\n"),
-            });
-        }
-    });
-    bot.command("help", async (ctx) => {
-        const help = renderHelpMessage();
-        await safeReply(ctx, help.html, { fallbackText: help.plain });
-    });
-    bot.command("channels", async (ctx) => {
-        const rendered = renderChannelsAction(listChannelDescriptors());
-        await replyChannelAction(ctx, rendered);
-    });
-    bot.command("agents", async (ctx) => {
-        const rendered = renderAgentsAction(listAgentAdapterDescriptors(), enabledAgents(config));
-        await replyChannelAction(ctx, rendered);
-    });
-    bot.command("agent", async (ctx) => {
-        const contextSession = await getContextSession(ctx, { deferThreadStart: true });
-        if (!contextSession) {
-            return;
-        }
-        const { contextKey, session } = contextSession;
-        if (isBusy(contextKey)) {
-            await safeReply(ctx, escapeHTML("Cannot switch agent while a prompt is running."), {
-                fallbackText: "Cannot switch agent while a prompt is running.",
-            });
-            return;
-        }
-        const availableAgents = enabledAgents(config);
-        const currentAgent = idOf(session.getInfo());
-        if (availableAgents.length <= 1) {
-            const only = agentLabel(availableAgents[0] ?? currentAgent);
-            await safeReply(ctx, `<b>Current agent:</b> <code>${escapeHTML(only)}</code>\nNo other agents are enabled.`, {
-                fallbackText: `Current agent: ${only}\nNo other agents are enabled.`,
-            });
-            return;
-        }
-        pendingAgentPicks.set(contextKey, availableAgents);
-        const keyboard = new InlineKeyboard();
-        for (const availableAgent of availableAgents) {
-            keyboard.text(`${agentLabel(availableAgent)}${availableAgent === currentAgent ? " ✓" : ""}`, `agent_${availableAgent}`).row();
-        }
-        await safeReply(ctx, `<b>Current agent:</b> <code>${escapeHTML(agentLabel(currentAgent))}</code>\nSelect agent for this Telegram context:`, {
-            fallbackText: `Current agent: ${agentLabel(currentAgent)}\nSelect agent for this Telegram context:`,
-            replyMarkup: keyboard,
-        });
-    });
-    bot.command("auth", async (ctx) => {
-        if (!ctx.chat) {
-            return;
-        }
-        const contextSession = await getContextSession(ctx, { deferThreadStart: true });
-        const info = contextSession?.session.getInfo();
-        if (info && !capabilitiesOf(info).auth) {
-            const text = `${labelOf(info)} uses its local CLI authentication. Run its login flow on the host if needed.`;
-            await safeReply(ctx, escapeHTML(text), { fallbackText: text });
-            return;
-        }
-        const authStatus = info ? await checkAgentAuthStatus(info) : await checkAuthStatus(config.codexApiKey);
-        const icon = authStatus.authenticated ? "✅" : "❌";
-        const html = [
-            `<b>${icon} Auth status:</b> ${authStatus.authenticated ? "authenticated" : "not authenticated"}`,
-            `<b>Method:</b> <code>${escapeHTML(authStatus.method)}</code>`,
-            `<b>Detail:</b> <code>${escapeHTML(authStatus.detail)}</code>`,
-        ].join("\n");
-        const plain = [
-            `${icon} Auth status: ${authStatus.authenticated ? "authenticated" : "not authenticated"}`,
-            `Method: ${authStatus.method}`,
-            `Detail: ${authStatus.detail}`,
-        ].join("\n");
-        await safeReply(ctx, html, { fallbackText: plain });
-    });
-    bot.command("login", async (ctx) => {
-        if (!ctx.chat) {
-            return;
-        }
-        const contextSession = await getContextSession(ctx, { deferThreadStart: true });
-        const info = contextSession?.session.getInfo();
-        if (info && !capabilitiesOf(info).login) {
-            const text = `${labelOf(info)} login is not managed by NordRelay. Run the CLI login flow on the host.`;
-            await safeReply(ctx, escapeHTML(text), { fallbackText: text });
-            return;
-        }
-        const authStatus = await checkLoginAuthStatus(info);
-        if (agentIdForAuth(info) !== "hermes" && authStatus.authenticated) {
-            await safeReply(ctx, `<b>✅ Already authenticated</b> via <code>${escapeHTML(authStatus.method)}</code>.`, {
-                fallbackText: `✅ Already authenticated via ${authStatus.method}.`,
-            });
-            return;
-        }
-        if (!config.enableTelegramLogin) {
-            await safeReply(ctx, [
-                "<b>Telegram-initiated login is disabled.</b>",
-                "",
-                `Run <code>${escapeHTML(hostLoginCommand(info))}</code> on the host.`,
-            ].join("\n"), {
-                fallbackText: [
-                    "Telegram-initiated login is disabled.",
-                    "",
-                    `Run '${hostLoginCommand(info)}' on the host.`,
-                ].join("\n"),
-            });
-            return;
-        }
-        const result = await startAgentLogin(info);
-        if (result.success) {
-            await safeReply(ctx, `<b>🔑 Login initiated.</b>\n\n<code>${escapeHTML(result.message)}</code>`, {
-                fallbackText: `🔑 Login initiated.\n\n${result.message}`,
-            });
-            return;
-        }
-        await safeReply(ctx, `<b>❌ Login failed.</b>\n\n<code>${escapeHTML(result.message)}</code>`, {
-            fallbackText: `❌ Login failed.\n\n${result.message}`,
-        });
-    });
-    bot.command("logout", async (ctx) => {
-        if (!ctx.chat) {
-            return;
-        }
-        const contextSession = await getContextSession(ctx, { deferThreadStart: true });
-        const info = contextSession?.session.getInfo();
-        if (info && !capabilitiesOf(info).logout) {
-            const text = `${labelOf(info)} logout is not managed by NordRelay. Run the CLI logout flow on the host.`;
-            await safeReply(ctx, escapeHTML(text), { fallbackText: text });
-            return;
-        }
-        const authStatus = await checkLoginAuthStatus(info);
-        if (authStatus.method === "api-key") {
-            await safeReply(ctx, [
-                `<b>Cannot logout via Telegram when ${escapeHTML(labelForAuth(info))} uses API-key authentication.</b>`,
-                "",
-                "Remove the API key from .env to use CLI-based auth instead.",
-            ].join("\n"), {
-                fallbackText: [
-                    `Cannot logout via Telegram when ${labelForAuth(info)} uses API-key authentication.`,
-                    "",
-                    "Remove the API key from .env to use CLI-based auth instead.",
-                ].join("\n"),
-            });
-            return;
-        }
-        if (!config.enableTelegramLogin) {
-            await safeReply(ctx, [
-                "<b>Telegram-initiated auth management is disabled.</b>",
-                "",
-                `Run <code>${escapeHTML(hostLogoutCommand(info))}</code> on the host.`,
-            ].join("\n"), {
-                fallbackText: [
-                    "Telegram-initiated auth management is disabled.",
-                    "",
-                    `Run '${hostLogoutCommand(info)}' on the host.`,
-                ].join("\n"),
-            });
-            return;
-        }
-        if (agentIdForAuth(info) !== "hermes" && !authStatus.authenticated) {
-            await safeReply(ctx, escapeHTML("Not currently authenticated."), {
-                fallbackText: "Not currently authenticated.",
-            });
-            return;
-        }
-        const result = await startAgentLogout(info);
-        if (result.success) {
-            await safeReply(ctx, `<b>🔓 Logged out.</b>\n\n${escapeHTML(result.message)}`, {
-                fallbackText: `🔓 Logged out.\n\n${result.message}`,
-            });
-            return;
-        }
-        await safeReply(ctx, `<b>❌ Logout failed.</b>\n\n<code>${escapeHTML(result.message)}</code>`, {
-            fallbackText: `❌ Logout failed.\n\n${result.message}`,
-        });
-    });
-    bot.command("mirror", async (ctx) => {
-        const contextSession = await getContextSession(ctx, { deferThreadStart: true });
-        if (!contextSession) {
-            return;
-        }
-        const { contextKey, session } = contextSession;
-        if (!capabilitiesOf(session.getInfo()).cliMirror) {
-            const text = `CLI mirroring is not supported for ${labelOf(session.getInfo())} yet.`;
-            await safeReply(ctx, escapeHTML(text), { fallbackText: text });
-            return;
-        }
-        const argument = (ctx.message?.text ?? "").replace(/^\/mirror(?:@\w+)?\s*/i, "").trim();
-        if (argument) {
-            const mode = parseMirrorMode(argument, getEffectiveMirrorMode(contextKey));
-            if (!["off", "status", "final", "full"].includes(argument.toLowerCase())) {
-                await safeReply(ctx, escapeHTML("Usage: /mirror [off|status|final|full]"), {
-                    fallbackText: "Usage: /mirror [off|status|final|full]",
-                });
-                return;
-            }
-            preferencesStore.update(contextKey, { mirrorMode: mode });
-        }
-        const mode = getEffectiveMirrorMode(contextKey);
-        const plain = [
-            `CLI mirroring: ${mode}`,
-            `Minimum update interval: ${config.telegramMirrorMinUpdateMs} ms`,
-            "Modes: off, status, final, full",
-        ].join("\n");
-        const html = [
-            `<b>CLI mirroring:</b> <code>${escapeHTML(mode)}</code>`,
-            `<b>Minimum update interval:</b> <code>${config.telegramMirrorMinUpdateMs} ms</code>`,
-            "<b>Modes:</b> <code>off</code>, <code>status</code>, <code>final</code>, <code>full</code>",
-        ].join("\n");
-        await safeReply(ctx, html, { fallbackText: plain });
-    });
-    bot.command("notify", async (ctx) => {
-        const contextSession = await getContextSession(ctx, { deferThreadStart: true });
-        if (!contextSession) {
-            return;
-        }
-        const { contextKey } = contextSession;
-        const argument = (ctx.message?.text ?? "").replace(/^\/notify(?:@\w+)?\s*/i, "").trim();
-        if (argument) {
-            const quietMatch = argument.match(/^quiet\s+(.+)$/i);
-            if (quietMatch) {
-                let quietHours;
-                try {
-                    quietHours = quietMatch[1].toLowerCase() === "off" ? null : parseQuietHours(quietMatch[1]);
-                }
-                catch (error) {
-                    await safeReply(ctx, escapeHTML(`Invalid quiet hours: ${friendlyErrorText(error)}`), {
-                        fallbackText: `Invalid quiet hours: ${friendlyErrorText(error)}`,
-                    });
-                    return;
-                }
-                preferencesStore.update(contextKey, { quietHours });
-            }
-            else {
-                const mode = parseNotifyMode(argument, getEffectiveNotifyMode(contextKey));
-                if (!["off", "minimal", "all"].includes(argument.toLowerCase())) {
-                    await safeReply(ctx, escapeHTML("Usage: /notify [off|minimal|all] or /notify quiet HH-HH"), {
-                        fallbackText: "Usage: /notify [off|minimal|all] or /notify quiet HH-HH",
-                    });
-                    return;
-                }
-                preferencesStore.update(contextKey, { notifyMode: mode });
-            }
-        }
-        const mode = getEffectiveNotifyMode(contextKey);
-        const quietHours = getEffectiveQuietHours(contextKey);
-        const plain = [
-            `Notifications: ${mode}`,
-            `Quiet hours: ${formatQuietHours(quietHours)}`,
-            `Currently quiet: ${isQuietNow(quietHours) ? "yes" : "no"}`,
-        ].join("\n");
-        const html = [
-            `<b>Notifications:</b> <code>${escapeHTML(mode)}</code>`,
-            `<b>Quiet hours:</b> <code>${escapeHTML(formatQuietHours(quietHours))}</code>`,
-            `<b>Currently quiet:</b> <code>${isQuietNow(quietHours) ? "yes" : "no"}</code>`,
-        ].join("\n");
-        await safeReply(ctx, html, { fallbackText: plain });
+    registerTelegramGeneralCommands({
+        bot,
+        config,
+        registry,
+        getContextSession,
+        checkAgentAuthStatus,
+        isTopicContext,
+        replyChannelAction,
     });
-    bot.command("workspaces", async (ctx) => {
-        const contextSession = await getContextSession(ctx, { deferThreadStart: true });
-        if (!contextSession) {
-            return;
-        }
-        const { session } = contextSession;
-        const agentName = labelOf(session.getInfo());
-        const workspaces = filterAllowedWorkspaces(session.listWorkspaces(), config);
-        const currentWorkspace = session.getInfo().workspace;
-        const lines = workspaces.slice(0, 20).map((workspace, index) => {
-            const prefix = workspace === currentWorkspace ? "*" : `${index + 1}.`;
-            const policy = renderWorkspacePolicyLine(workspace, config);
-            return `${prefix} ${workspace}${policy ? ` (${policy})` : ""}`;
-        });
-        const currentPolicy = evaluateWorkspacePolicy(currentWorkspace, config);
-        const header = [
-            "Workspaces:",
-            `Current: ${currentWorkspace}`,
-            currentPolicy.warning ? `Current warning: ${currentPolicy.warning}` : undefined,
-            config.workspaceAllowedRoots.length > 0 ? `Allowed roots: ${config.workspaceAllowedRoots.join(", ")}` : "Allowed roots: unrestricted",
-            "",
-        ].filter((line) => Boolean(line));
-        const plain = [...header, ...(lines.length > 0 ? lines : [`No workspaces found in ${agentName} state.`])].join("\n");
-        const html = [
-            "<b>Workspaces:</b>",
-            `<b>Current:</b> <code>${escapeHTML(currentWorkspace)}</code>`,
-            currentPolicy.warning ? `<b>Current warning:</b> <code>${escapeHTML(currentPolicy.warning)}</code>` : undefined,
-            `<b>Allowed roots:</b> <code>${escapeHTML(config.workspaceAllowedRoots.length > 0 ? config.workspaceAllowedRoots.join(", ") : "unrestricted")}</code>`,
-            "",
-            ...(lines.length > 0 ? lines.map((line) => `<code>${escapeHTML(line)}</code>`) : [`<code>No workspaces found in ${escapeHTML(agentName)} state.</code>`]),
-        ].filter((line) => Boolean(line)).join("\n");
-        await safeReply(ctx, html, { fallbackText: plain });
+    registerTelegramAgentCommands({
+        bot,
+        config,
+        registry,
+        pendingAgentPicks,
+        getContextSession,
+        isBusy,
+        checkAgentAuthStatus,
+        checkLoginAuthStatus,
+        agentIdForAuth,
+        labelForAuth,
+        startAgentLogin,
+        startAgentLogout,
+        hostLoginCommand,
+        hostLogoutCommand,
     });
-    bot.command("voice", async (ctx) => {
-        if (!ctx.chat) {
-            return;
-        }
-        const contextSession = await getContextSession(ctx, { deferThreadStart: true });
-        if (!contextSession) {
-            return;
-        }
-        const { contextKey } = contextSession;
-        const argument = (ctx.message?.text ?? "").replace(/^\/voice(?:@\w+)?\s*/i, "").trim();
-        if (argument) {
-            const parts = argument.split(/\s+/);
-            const key = parts[0]?.toLowerCase();
-            const value = parts.slice(1).join(" ").trim();
-            if (key === "backend" && value) {
-                preferencesStore.update(contextKey, { voiceBackend: parseVoiceBackendPreference(value) });
-            }
-            else if (key === "language") {
-                preferencesStore.update(contextKey, { voiceLanguage: value && value.toLowerCase() !== "auto" ? value : null });
-            }
-            else if (key === "transcribe_only" || key === "transcribe-only") {
-                const enabled = parseToggle(value);
-                if (enabled === undefined) {
-                    await safeReply(ctx, escapeHTML("Usage: /voice transcribe_only on|off"), {
-                        fallbackText: "Usage: /voice transcribe_only on|off",
-                    });
-                    return;
-                }
-                preferencesStore.update(contextKey, { voiceTranscribeOnly: enabled });
-            }
-            else {
-                await safeReply(ctx, escapeHTML("Usage: /voice, /voice backend auto|parakeet|faster-whisper|openai, /voice language auto|<code>, /voice transcribe_only on|off"), {
-                    fallbackText: "Usage: /voice, /voice backend auto|parakeet|faster-whisper|openai, /voice language auto|<code>, /voice transcribe_only on|off",
-                });
-                return;
-            }
-        }
-        const backends = await getAvailableBackends().catch(() => []);
-        if (backends.length === 0) {
-            await safeReply(ctx, [
-                "<b>Voice transcription is not available.</b>",
-                "",
-                "Install <code>faster-whisper</code> + ffmpeg, install <code>parakeet-coreml</code> on macOS Apple Silicon, or set <code>OPENAI_API_KEY</code>.",
-                "<i>Cloud transcription uses OPENAI_API_KEY, not CODEX_API_KEY.</i>",
-            ].join("\n"), {
-                fallbackText: [
-                    "Voice transcription is not available.",
-                    "",
-                    "Install faster-whisper + ffmpeg, install parakeet-coreml on macOS Apple Silicon, or set OPENAI_API_KEY.",
-                    "Cloud transcription uses OPENAI_API_KEY, not CODEX_API_KEY.",
-                ].join("\n"),
-            });
-            return;
-        }
-        const joined = backends.join(" + ");
-        const backendPreference = getEffectiveVoiceBackend(contextKey);
-        const language = getEffectiveVoiceLanguage(contextKey);
-        const transcribeOnly = isVoiceTranscribeOnly(contextKey);
-        const plain = [
-            `Voice backends: ${joined}`,
-            `Preferred backend: ${backendPreference}`,
-            `Language: ${language ?? "auto"}`,
-            `Transcribe only: ${transcribeOnly ? "on" : "off"}`,
-        ].join("\n");
-        const html = [
-            `<b>Voice backends:</b> <code>${escapeHTML(joined)}</code>`,
-            `<b>Preferred backend:</b> <code>${escapeHTML(backendPreference)}</code>`,
-            `<b>Language:</b> <code>${escapeHTML(language ?? "auto")}</code>`,
-            `<b>Transcribe only:</b> <code>${transcribeOnly ? "on" : "off"}</code>`,
-        ].join("\n");
-        await safeReply(ctx, html, {
-            fallbackText: plain,
-        });
+    registerTelegramPreferenceCommands({
+        bot,
+        config,
+        preferencesStore,
+        getContextSession,
+        getEffectiveMirrorMode,
+        getEffectiveNotifyMode,
+        getEffectiveQuietHours,
+        getEffectiveVoiceBackend,
+        getEffectiveVoiceLanguage,
+        isVoiceTranscribeOnly,
     });
-    bot.command(["status", "health"], async (ctx) => {
-        const health = await getConnectorHealth({ piCliPath: config.piCliPath, hermesCliPath: config.hermesCliPath, openClawCliPath: config.openClawCliPath, claudeCodeCliPath: config.claudeCodeCliPath });
-        const contextSession = await getContextSession(ctx, { deferThreadStart: true });
-        const authStatus = contextSession
-            ? await checkAgentAuthStatus(contextSession.session.getInfo())
-            : await checkAuthStatus(config.codexApiKey);
-        const html = renderHealthHTML(health, authStatus.authenticated, getUserRole(ctx));
-        const plain = renderHealthPlain(health, authStatus.authenticated, getUserRole(ctx));
-        await safeReply(ctx, html, { fallbackText: plain });
+    registerTelegramDiagnosticsCommands({
+        bot,
+        config,
+        registry,
+        promptStore,
+        turnProgress,
+        externalMirrors,
+        externalQueueTimers,
+        queueStatusMessages,
+        getContextSession,
+        checkAgentAuthStatus,
+        getUserRole,
+        getEffectiveMirrorMode,
+        getEffectiveNotifyMode,
+        getEffectiveQuietHours,
+        getEffectiveVoiceBackend,
+        getEffectiveVoiceLanguage,
+        isVoiceTranscribeOnly,
+        replyChannelAction,
     });
-    bot.command("version", async (ctx) => {
-        const health = await getConnectorHealth({ piCliPath: config.piCliPath, hermesCliPath: config.hermesCliPath, openClawCliPath: config.openClawCliPath, claudeCodeCliPath: config.claudeCodeCliPath });
-        const state = await readConnectorState();
-        const versions = await getVersionChecks({ piCliPath: config.piCliPath, hermesCliPath: config.hermesCliPath, openClawCliPath: config.openClawCliPath, claudeCodeCliPath: config.claudeCodeCliPath });
-        const plain = [
-            renderVersionCheckPlain(versions.nordrelay),
-            `Runtime status: ${state.status ?? "unknown"}`,
-            formatCliPathPlain("Codex CLI", health.codexCliPath, health.codexCli),
-            renderVersionCheckPlain(versions.codex),
-            formatCliPathPlain("Pi CLI", health.piCliPath, health.piCli),
-            renderVersionCheckPlain(versions.pi),
-            formatCliPathPlain("Hermes CLI", health.hermesCliPath, health.hermesCli),
-            renderVersionCheckPlain(versions.hermes),
-            formatCliPathPlain("OpenClaw CLI", health.openClawCliPath, health.openClawCli),
-            renderVersionCheckPlain(versions.openclaw),
-            formatCliPathPlain("Claude Code CLI", health.claudeCodeCliPath, health.claudeCodeCli),
-            renderVersionCheckPlain(versions.claudeCode),
-        ].join("\n");
-        const html = [
-            renderVersionCheckHTML(versions.nordrelay),
-            `<b>Runtime status:</b> <code>${escapeHTML(state.status ?? "unknown")}</code>`,
-            formatCliPathHTML("Codex CLI", health.codexCliPath, health.codexCli),
-            renderVersionCheckHTML(versions.codex),
-            formatCliPathHTML("Pi CLI", health.piCliPath, health.piCli),
-            renderVersionCheckHTML(versions.pi),
-            formatCliPathHTML("Hermes CLI", health.hermesCliPath, health.hermesCli),
-            renderVersionCheckHTML(versions.hermes),
-            formatCliPathHTML("OpenClaw CLI", health.openClawCliPath, health.openClawCli),
-            renderVersionCheckHTML(versions.openclaw),
-            formatCliPathHTML("Claude Code CLI", health.claudeCodeCliPath, health.claudeCodeCli),
-            renderVersionCheckHTML(versions.claudeCode),
-        ].join("\n");
-        await safeReply(ctx, html, { fallbackText: plain });
-    });
-    bot.command(["tasks", "progress"], async (ctx) => {
-        const contextSession = await getContextSession(ctx, { deferThreadStart: true });
-        if (!contextSession) {
-            return;
-        }
-        const progress = turnProgress.get(contextSession.contextKey);
-        const queue = promptStore.list(contextSession.contextKey);
-        const externalActivity = getExternalActivity(contextSession.session);
-        const busyState = {
-            ...getBusyState(contextSession.contextKey),
-            external: Boolean(externalActivity?.active),
-        };
-        const info = contextSession.session.getInfo();
-        const plain = renderProgressPlain(progress, queue.length, busyState, info);
-        const html = renderProgressHTML(progress, queue.length, busyState, info);
-        await safeReply(ctx, html, { fallbackText: plain });
-    });
-    bot.command("activity", async (ctx) => {
-        const contextSession = await getContextSession(ctx, { deferThreadStart: true });
-        if (!contextSession) {
-            return;
-        }
-        const info = contextSession.session.getInfo();
-        if (!capabilitiesOf(info).activityLog) {
-            const text = `${labelOf(info)} activity timelines are not available yet.`;
-            await safeReply(ctx, escapeHTML(text), { fallbackText: text });
-            return;
-        }
-        const threadId = contextSession.session.getActiveThreadId();
-        if (!threadId) {
-            await safeReply(ctx, escapeHTML("No active thread yet."), { fallbackText: "No active thread yet." });
-            return;
-        }
-        const options = parseActivityOptions((ctx.message?.text ?? "").replace(/^\/activity(?:@\w+)?\s*/i, "").trim());
-        const events = filterActivityEvents(getAgentActivityLog(contextSession.session, config, options.exportFile ? 200 : options.limit), options);
-        const rendered = renderActivityTimeline(threadId, events, options);
-        if (options.exportFile && ctx.chat) {
-            const exportPath = path.join(tmpdir(), `nordrelay-activity-${threadId}-${randomUUID().slice(0, 8)}.txt`);
-            await writeFile(exportPath, rendered.plain, "utf8");
-            try {
-                await telegramRateLimiter.run(chatBucket(ctx.chat.id), "sendDocument", () => ctx.api.sendDocument(ctx.chat.id, new InputFile(exportPath, path.basename(exportPath)), {
-                    ...(ctx.message?.message_thread_id ? { message_thread_id: ctx.message.message_thread_id } : {}),
-                }));
-            }
-            finally {
-                await unlink(exportPath).catch(() => { });
-            }
-            return;
-        }
-        await safeReply(ctx, rendered.html, { fallbackText: rendered.plain });
-    });
-    bot.command("audit", async (ctx) => {
-        const rawText = ctx.message?.text ?? "";
-        const limitArg = rawText.replace(/^\/audit(?:@\w+)?\s*/i, "").trim();
-        const limit = /^\d+$/.test(limitArg) ? Number(limitArg) : 20;
-        const events = auditLog.list(limit);
-        const rendered = renderAuditEvents(events);
-        await safeReply(ctx, rendered.html, { fallbackText: rendered.plain });
-    });
-    bot.command("lock", async (ctx) => {
-        const contextSession = await getContextSession(ctx, { deferThreadStart: true });
-        if (!contextSession || !ctx.from) {
-            return;
-        }
-        const { contextKey, session } = contextSession;
-        const existing = lockStore.get(contextKey);
-        if (existing && existing.ownerId !== ctx.from.id && !isAdminUser(ctx)) {
-            const text = `Session is already locked by ${formatLockOwner(existing)}.`;
-            await safeReply(ctx, escapeHTML(text), { fallbackText: text });
-            return;
-        }
-        const lock = lockStore.set(contextKey, ctx.from.id, formatTelegramName(ctx), config.sessionLockTtlMs);
-        auditContext(ctx, contextKey, session, {
-            action: "lock_updated",
-            status: "ok",
-            detail: `locked by ${lock.ownerId}`,
-        });
-        const text = `Session locked by ${formatLockOwner(lock)}${lock.expiresAt ? ` until ${formatLocalDateTime(new Date(lock.expiresAt))}` : ""}.`;
-        await safeReply(ctx, escapeHTML(text), { fallbackText: text });
-    });
-    bot.command("unlock", async (ctx) => {
-        const contextSession = await getContextSession(ctx, { deferThreadStart: true });
-        if (!contextSession) {
-            return;
-        }
-        const { contextKey, session } = contextSession;
-        const lock = lockStore.get(contextKey);
-        if (lock && lock.ownerId !== ctx.from?.id && !isAdminUser(ctx)) {
-            const text = `Only ${formatLockOwner(lock)} or an admin can unlock this session.`;
-            await safeReply(ctx, escapeHTML(text), { fallbackText: text });
-            return;
-        }
-        const removed = lockStore.clear(contextKey);
-        auditContext(ctx, contextKey, session, {
-            action: "lock_updated",
-            status: "ok",
-            detail: removed ? "unlocked" : "no lock",
-        });
-        const text = removed ? "Session lock released." : "No active lock for this session.";
-        await safeReply(ctx, escapeHTML(text), { fallbackText: text });
-    });
-    bot.command("locks", async (ctx) => {
-        const locks = lockStore.list();
-        const rendered = renderSessionLocks(locks);
-        await safeReply(ctx, rendered.html, { fallbackText: rendered.plain });
-    });
-    bot.command("diagnostics", async (ctx) => {
-        const health = await getConnectorHealth({ piCliPath: config.piCliPath, hermesCliPath: config.hermesCliPath, openClawCliPath: config.openClawCliPath, claudeCodeCliPath: config.claudeCodeCliPath });
-        const contextKey = contextKeyFromCtx(ctx);
-        const queueLength = contextKey ? promptStore.list(contextKey).length : 0;
-        const progress = contextKey ? turnProgress.get(contextKey) : undefined;
-        const contextSession = contextKey ? await getContextSession(ctx, { deferThreadStart: true }) : null;
-        const authStatus = contextSession
-            ? await checkAgentAuthStatus(contextSession.session.getInfo())
-            : await checkAuthStatus(config.codexApiKey);
-        const agentDiagnostics = contextSession
-            ? renderAgentDiagnostics(getAgentDiagnostics(contextSession.session, config))
-            : { plain: "Agent state: no context", html: "<b>Agent state:</b> <code>no context</code>" };
-        const runtime = {
-            rateLimit: getTelegramRateLimitMetrics(),
-            externalMirrors: externalMirrors.size,
-            externalQueueTimers: externalQueueTimers.size,
-            queueStatusMessages: queueStatusMessages.size,
-            mirrorMode: contextKey ? getEffectiveMirrorMode(contextKey) : config.telegramMirrorMode,
-            notifyMode: contextKey ? getEffectiveNotifyMode(contextKey) : config.telegramNotifyMode,
-            quietHours: formatQuietHours(contextKey ? getEffectiveQuietHours(contextKey) : config.telegramQuietHours),
-            voiceBackend: contextKey ? getEffectiveVoiceBackend(contextKey) : config.voicePreferredBackend,
-            voiceLanguage: contextKey ? getEffectiveVoiceLanguage(contextKey) ?? "auto" : config.voiceDefaultLanguage ?? "auto",
-            voiceTranscribeOnly: contextKey ? isVoiceTranscribeOnly(contextKey) : config.voiceTranscribeOnly,
-        };
-        const plain = `${renderDiagnosticsPlain(config, registry, health, authStatus.authenticated, getUserRole(ctx), queueLength, progress, runtime)}\n${agentDiagnostics.plain}`;
-        const html = `${renderDiagnosticsHTML(config, registry, health, authStatus.authenticated, getUserRole(ctx), queueLength, progress, runtime)}\n${agentDiagnostics.html}`;
-        await safeReply(ctx, html, { fallbackText: plain });
-    });
-    bot.command("sync", async (ctx) => {
-        const contextSession = await getContextSession(ctx, { deferThreadStart: true });
-        if (!contextSession) {
-            return;
-        }
-        const sessionInfo = contextSession.session.getInfo();
-        if (!capabilitiesOf(sessionInfo).externalActivity) {
-            const plain = [`${labelOf(sessionInfo)} has no external CLI state watcher to sync.`, "", renderSessionInfoPlain(sessionInfo)].join("\n");
-            const html = [`<b>${escapeHTML(labelOf(sessionInfo))} has no external CLI state watcher to sync.</b>`, "", renderSessionInfoHTML(sessionInfo)].join("\n");
-            await safeReply(ctx, html, { fallbackText: plain });
-            return;
-        }
-        const result = contextSession.session.syncFromAgentState({ reattach: true });
-        if (result.changed) {
-            updateSessionMetadata(contextSession.contextKey, contextSession.session);
-        }
-        const fields = result.changedFields.length > 0 ? result.changedFields.join(", ") : "none";
-        const plain = [
-            result.changed ? `Synced from ${labelOf(sessionInfo)} state.` : "Already in sync.",
-            `Changed: ${fields}`,
-            `Reattached: ${result.reattached ? "yes" : "no"}`,
-            "",
-            renderSessionInfoPlain(result.info),
-        ].join("\n");
-        const html = [
-            result.changed ? `<b>Synced from ${escapeHTML(labelOf(sessionInfo))} state.</b>` : "<b>Already in sync.</b>",
-            `<b>Changed:</b> <code>${escapeHTML(fields)}</code>`,
-            `<b>Reattached:</b> <code>${result.reattached ? "yes" : "no"}</code>`,
-            "",
-            renderSessionInfoHTML(result.info),
-        ].join("\n");
-        await safeReply(ctx, html, { fallbackText: plain });
-    });
-    bot.command("logs", async (ctx) => {
-        const rawText = ctx.message?.text ?? "";
-        const argument = rawText.replace(/^\/logs(?:@\w+)?\s*/i, "").trim();
-        const logRequest = parseLogsCommand(argument);
-        const logs = await Promise.all(logTailRequests(logRequest.target).map(async (request) => ({
-            title: request.title,
-            tail: await readFormattedLogTail(logRequest.lines, request.path),
-        })));
-        const rendered = renderLogTailsAction(logs);
-        await replyChannelAction(ctx, rendered);
-    });
-    bot.command("restart", async (ctx) => {
-        await safeReply(ctx, escapeHTML("Restarting connector..."), {
-            fallbackText: "Restarting connector...",
-        });
-        setTimeout(() => {
-            spawnConnectorRestart();
-        }, 300);
+    registerTelegramOperationalCommands({
+        bot,
+        config,
+        promptStore,
+        auditLog,
+        lockStore,
+        turnProgress,
+        getContextSession,
+        getBusyState,
+        getExternalActivity,
+        isAdminUser,
+        auditContext,
+        updateSessionMetadata,
     });
+    registerTelegramSupportCommands({ bot, config, auditLog, agentUpdates, getUserRole, audit });
     registerTelegramUpdateCommands({ bot, agentUpdates, replyChannelAction, startTelegramAgentUpdate });
     bot.command("new", async (ctx) => {
         const chatId = ctx.chat?.id;
@@ -2322,233 +1766,24 @@ export function createBot(config, registry) {
             await clearReaction(ctx);
         }
     });
-    bot.command("queue", async (ctx) => {
-        const contextSession = await getContextSession(ctx, { deferThreadStart: true });
-        if (!contextSession) {
-            return;
-        }
-        const chatId = ctx.chat?.id;
-        const { contextKey, session } = contextSession;
-        const rawText = ctx.message?.text ?? "";
-        const argument = rawText.replace(/^\/queue(?:@\w+)?\s*/i, "").trim();
-        const laterMatch = argument.match(/^later\s+(\d+)(?:m|min|minutes?)?\s+([\s\S]+)$/i);
-        if (laterMatch) {
-            const minutes = Math.min(7 * 24 * 60, Math.max(1, Number(laterMatch[1])));
-            const text = laterMatch[2].trim();
-            const notBefore = Date.now() + minutes * 60 * 1000;
-            const item = promptStore.enqueue(contextKey, toPromptEnvelope(text), { notBefore });
-            const message = `Queued prompt ${item.id} for ${formatLocalDateTime(new Date(notBefore))}.`;
-            await safeReply(ctx, escapeHTML(message), {
-                fallbackText: message,
-                replyMarkup: createQueuedPromptCancelKeyboard(contextKey, item.id),
-            });
-            auditContext(ctx, contextKey, session, {
-                action: "prompt_queued",
-                status: "ok",
-                promptId: item.id,
-                description: item.description,
-                detail: "scheduled",
-            });
-            return;
-        }
-        const inspectMatch = argument.match(/^inspect\s+([a-z0-9]+)$/i);
-        if (inspectMatch) {
-            const item = promptStore.get(contextKey, inspectMatch[1]);
-            if (!item) {
-                await safeReply(ctx, escapeHTML(`No queued prompt found with id ${inspectMatch[1]}.`), {
-                    fallbackText: `No queued prompt found with id ${inspectMatch[1]}.`,
-                });
-                return;
-            }
-            const rendered = renderQueuedPromptDetailAction(item);
-            await safeReply(ctx, rendered.html, { fallbackText: rendered.plain });
-            return;
-        }
-        if (/^pause$/i.test(argument)) {
-            promptStore.pause(contextKey);
-            const message = `Queue paused. ${promptStore.list(contextKey).length} queued.`;
-            await safeReply(ctx, escapeHTML(message), { fallbackText: message });
-            await updateQueueStatusMessage(contextKey, message);
-            return;
-        }
-        if (/^resume$/i.test(argument)) {
-            promptStore.resume(contextKey);
-            const message = `Queue resumed. ${promptStore.list(contextKey).length} queued.`;
-            await safeReply(ctx, escapeHTML(message), { fallbackText: message });
-            if (chatId) {
-                void drainQueuedPrompts(ctx, contextKey, chatId, session).catch((error) => {
-                    console.error("Failed to drain queue after resume:", error);
-                });
-            }
-            return;
-        }
-        const moveMatch = argument.match(/^move\s+([a-z0-9]+)\s+(top|up|down)$/i);
-        if (moveMatch) {
-            const direction = moveMatch[2].toLowerCase();
-            const item = direction === "top"
-                ? promptStore.moveToTop(contextKey, moveMatch[1])
-                : direction === "up"
-                    ? promptStore.moveUp(contextKey, moveMatch[1])
-                    : promptStore.moveDown(contextKey, moveMatch[1]);
-            if (!item) {
-                await safeReply(ctx, escapeHTML(`No queued prompt found with id ${moveMatch[1]}.`), {
-                    fallbackText: `No queued prompt found with id ${moveMatch[1]}.`,
-                });
-                return;
-            }
-            const message = `Moved queued prompt ${item.id} ${direction}.`;
-            await safeReply(ctx, escapeHTML(message), { fallbackText: message });
-            return;
-        }
-        const runMatch = argument.match(/^run\s+([a-z0-9]+)$/i);
-        if (runMatch) {
-            const item = promptStore.remove(contextKey, runMatch[1]);
-            if (!item) {
-                await safeReply(ctx, escapeHTML(`No queued prompt found with id ${runMatch[1]}.`), {
-                    fallbackText: `No queued prompt found with id ${runMatch[1]}.`,
-                });
-                return;
-            }
-            promptStore.enqueueFront(contextKey, item);
-            promptStore.resume(contextKey);
-            if (!chatId) {
-                return;
-            }
-            const busy = getBusyReason(contextKey);
-            if (busy.busy) {
-                const message = `Queued prompt ${item.id} moved to top and will run when the current task finishes.`;
-                await safeReply(ctx, escapeHTML(message), { fallbackText: message });
-                if (busy.kind === "external") {
-                    scheduleExternalQueueDrain(ctx, contextKey, chatId, session);
-                }
-                return;
-            }
-            const next = promptStore.dequeue(contextKey);
-            if (next) {
-                await handleUserPrompt(ctx, contextKey, chatId, session, next, { fromQueue: true });
-            }
-            return;
-        }
-        if (argument) {
-            await safeReply(ctx, escapeHTML("Usage: /queue, /queue pause, /queue resume, /queue later <minutes> <prompt>, /queue inspect <id>, /queue move <id> top|up|down, /queue run <id>"), {
-                fallbackText: "Usage: /queue, /queue pause, /queue resume, /queue later <minutes> <prompt>, /queue inspect <id>, /queue move <id> top|up|down, /queue run <id>",
-            });
-            return;
-        }
-        const queue = promptStore.list(contextKey);
-        if (queue.length === 0) {
-            const rendered = renderQueueList(contextKey, queue);
-            await safeReply(ctx, rendered.html, { fallbackText: rendered.plain });
-            return;
-        }
-        const rendered = renderQueueList(contextKey, queue);
-        await safeReply(ctx, rendered.html, {
-            fallbackText: rendered.plain,
-            replyMarkup: rendered.keyboard,
-        });
+    registerTelegramQueueCommands({
+        bot,
+        promptStore,
+        getContextSession,
+        getBusyReason,
+        getSession: (contextKey) => registry.get(contextKey),
+        updateQueueStatusMessage,
+        scheduleExternalQueueDrain,
+        drainQueuedPrompts,
+        handleUserPrompt,
+        auditContext,
     });
-    bot.command("clearqueue", async (ctx) => {
-        const contextSession = await getContextSession(ctx, { deferThreadStart: true });
-        if (!contextSession) {
-            return;
-        }
-        const count = promptStore.clear(contextSession.contextKey);
-        const message = `Cleared ${count} queued prompt${count === 1 ? "" : "s"}.`;
-        await safeReply(ctx, escapeHTML(message), { fallbackText: message });
-    });
-    bot.command("cancel", async (ctx) => {
-        const contextSession = await getContextSession(ctx, { deferThreadStart: true });
-        if (!contextSession) {
-            return;
-        }
-        const rawText = ctx.message?.text ?? "";
-        const id = rawText.replace(/^\/cancel(?:@\w+)?\s*/i, "").trim();
-        if (!id) {
-            await safeReply(ctx, escapeHTML("Usage: /cancel <queue-id>"), {
-                fallbackText: "Usage: /cancel <queue-id>",
-            });
-            return;
-        }
-        const removed = promptStore.remove(contextSession.contextKey, id);
-        if (!removed) {
-            await safeReply(ctx, escapeHTML(`No queued prompt found with id ${id}.`), {
-                fallbackText: `No queued prompt found with id ${id}.`,
-            });
-            return;
-        }
-        await safeReply(ctx, escapeHTML(`Cancelled queued prompt ${removed.id}.`), {
-            fallbackText: `Cancelled queued prompt ${removed.id}.`,
-        });
-    });
-    bot.command("artifacts", async (ctx) => {
-        const contextSession = await getContextSession(ctx, { deferThreadStart: true });
-        if (!contextSession || !ctx.chat) {
-            return;
-        }
-        const workspace = contextSession.session.getInfo().workspace;
-        const rawText = ctx.message?.text ?? "";
-        const argument = rawText.replace(/^\/artifacts(?:@\w+)?\s*/i, "").trim();
-        const reports = await listRecentArtifactReports(workspace, 10, config.maxFileSize);
-        if (reports.length === 0) {
-            await safeReply(ctx, escapeHTML("No generated artifacts found for this workspace."), {
-                fallbackText: "No generated artifacts found for this workspace.",
-            });
-            return;
-        }
-        if (argument) {
-            const parts = argument.split(/\s+/).filter(Boolean);
-            if (parts[0]?.toLowerCase() === "delete" && parts[1]) {
-                const selected = reports.find((report) => report.turnId === parts[1] || report.turnId.startsWith(parts[1]));
-                if (!selected) {
-                    await safeReply(ctx, escapeHTML(`No artifact turn found for "${parts[1]}".`), {
-                        fallbackText: `No artifact turn found for "${parts[1]}".`,
-                    });
-                    return;
-                }
-                const removed = await removeArtifactTurn(workspace, selected.turnId);
-                const text = removed ? `Deleted artifact turn: ${selected.turnId}` : `Artifact turn not found: ${selected.turnId}`;
-                await safeReply(ctx, escapeHTML(text), { fallbackText: text });
-                return;
-            }
-            const filtered = filterArtifactReports(reports, argument);
-            if (filtered) {
-                if (filtered.length === 0) {
-                    await safeReply(ctx, escapeHTML(`No artifacts matched "${argument}".`), {
-                        fallbackText: `No artifacts matched "${argument}".`,
-                    });
-                    return;
-                }
-                const rendered = renderArtifactReportsAction(filtered);
-                await safeReply(ctx, rendered.html, {
-                    fallbackText: rendered.plain,
-                    replyMarkup: buildArtifactActionsKeyboard(filtered),
-                });
-                return;
-            }
-            const shouldZip = parts[0]?.toLowerCase() === "zip";
-            const requestedTurn = shouldZip ? parts[1] : parts[0];
-            const selected = !requestedTurn || requestedTurn.toLowerCase() === "latest"
-                ? reports[0]
-                : reports.find((report) => report.turnId === requestedTurn || report.turnId.startsWith(requestedTurn));
-            if (!selected) {
-                await safeReply(ctx, escapeHTML(`No artifact turn found for "${argument}".`), {
-                    fallbackText: `No artifact turn found for "${argument}".`,
-                });
-                return;
-            }
-            if (shouldZip) {
-                await deliverArtifactReportZip(ctx, ctx.chat.id, selected, ctx.message?.message_thread_id);
-            }
-            else {
-                await deliverArtifactReport(ctx, ctx.chat.id, selected, ctx.message?.message_thread_id);
-            }
-            return;
-        }
-        const { html, plain } = renderArtifactReportsAction(reports);
-        await safeReply(ctx, html, {
-            fallbackText: plain,
-            replyMarkup: buildArtifactActionsKeyboard(reports),
-        });
+    registerTelegramArtifactCommands({
+        bot,
+        config,
+        getContextSession,
+        deliverArtifactReport,
+        deliverArtifactReportZip,
     });
     bot.command("session", async (ctx) => {
         const contextSession = await getContextSession(ctx, { deferThreadStart: true });
@@ -3065,49 +2300,6 @@ export function createBot(config, registry) {
         });
     };
     bot.command(["effort", "reasoning"], openReasoningPicker);
-    bot.callbackQuery(/^agent_(codex|pi|hermes|openclaw|claude-code)$/, async (ctx) => {
-        const chatId = ctx.chat?.id;
-        const messageId = ctx.callbackQuery.message?.message_id;
-        const selectedAgent = ctx.match?.[1];
-        const contextKey = contextKeyFromCtx(ctx);
-        if (!chatId || !contextKey || !selectedAgent) {
-            await ctx.answerCallbackQuery();
-            return;
-        }
-        const picks = pendingAgentPicks.get(contextKey);
-        if (!picks?.includes(selectedAgent)) {
-            await ctx.answerCallbackQuery({ text: "Expired, run /agent again" });
-            return;
-        }
-        if (isBusy(contextKey)) {
-            await ctx.answerCallbackQuery({ text: "Wait for the current prompt to finish" });
-            return;
-        }
-        await ctx.answerCallbackQuery({ text: `Switching to ${agentLabel(selectedAgent)}...` });
-        pendingAgentPicks.delete(contextKey);
-        try {
-            const session = await registry.switchAgent(contextKey, selectedAgent);
-            const info = session.getInfo();
-            const html = [`<b>Agent switched to ${escapeHTML(labelOf(info))}.</b>`, "", renderSessionInfoHTML(info)].join("\n");
-            const plain = [`Agent switched to ${labelOf(info)}.`, "", renderSessionInfoPlain(info)].join("\n");
-            if (messageId) {
-                await safeEditMessage(bot, chatId, messageId, html, { fallbackText: plain });
-            }
-            else {
-                await safeReply(ctx, html, { fallbackText: plain });
-            }
-        }
-        catch (error) {
-            const html = `<b>Failed:</b> ${escapeHTML(friendlyErrorText(error))}`;
-            const plain = `Failed: ${friendlyErrorText(error)}`;
-            if (messageId) {
-                await safeEditMessage(bot, chatId, messageId, html, { fallbackText: plain });
-            }
-            else {
-                await safeReply(ctx, html, { fallbackText: plain });
-            }
-        }
-    });
     bot.callbackQuery(NOOP_PAGE_CALLBACK_DATA, async (ctx) => {
         await ctx.answerCallbackQuery();
     });
@@ -3130,94 +2322,6 @@ export function createBot(config, registry) {
         await ctx.answerCallbackQuery({ text: "Aborting..." });
         await session.abort();
     });
-    bot.callbackQuery(/^queue_(cancel|remove|top|up|down|run):(-?\d+(?::\d+)?):([a-z0-9]+)$/, async (ctx) => {
-        const action = ctx.match?.[1];
-        const contextKey = ctx.match?.[2];
-        const queueId = ctx.match?.[3];
-        if (!action || !contextKey || !queueId) {
-            await ctx.answerCallbackQuery();
-            return;
-        }
-        const currentContextKey = contextKeyFromCtx(ctx);
-        if (currentContextKey && currentContextKey !== contextKey) {
-            await ctx.answerCallbackQuery({ text: "This queue button belongs to another chat or topic." });
-            return;
-        }
-        const chatId = ctx.chat?.id;
-        const messageId = ctx.callbackQuery.message?.message_id;
-        if (action === "top" || action === "up" || action === "down") {
-            const item = action === "top"
-                ? promptStore.moveToTop(contextKey, queueId)
-                : action === "up"
-                    ? promptStore.moveUp(contextKey, queueId)
-                    : promptStore.moveDown(contextKey, queueId);
-            await ctx.answerCallbackQuery({ text: item ? `Moved ${queueId} ${action}.` : "Queued prompt not found." });
-            if (chatId && messageId) {
-                const rendered = renderQueueList(contextKey, promptStore.list(contextKey));
-                await safeEditMessage(bot, chatId, messageId, rendered.html, {
-                    fallbackText: rendered.plain,
-                    replyMarkup: rendered.keyboard,
-                });
-            }
-            return;
-        }
-        if (action === "run") {
-            const item = promptStore.remove(contextKey, queueId);
-            if (!item) {
-                await ctx.answerCallbackQuery({ text: "Queued prompt already started or was cancelled." });
-                return;
-            }
-            promptStore.enqueueFront(contextKey, item);
-            promptStore.resume(contextKey);
-            await ctx.answerCallbackQuery({ text: `Queued prompt ${queueId} moved to next.` });
-            if (chatId && messageId) {
-                const rendered = renderQueueList(contextKey, promptStore.list(contextKey));
-                await safeEditMessage(bot, chatId, messageId, rendered.html, {
-                    fallbackText: rendered.plain,
-                    replyMarkup: rendered.keyboard,
-                });
-            }
-            const session = registry.get(contextKey);
-            if (chatId && session && !getBusyReason(contextKey).busy) {
-                void drainQueuedPrompts(ctx, contextKey, chatId, session).catch((error) => {
-                    console.error("Failed to drain queue after run-now callback:", error);
-                });
-            }
-            return;
-        }
-        const removed = promptStore.remove(contextKey, queueId);
-        if (!removed) {
-            await ctx.answerCallbackQuery({ text: "Queued prompt already started or was cancelled." });
-            if (chatId && messageId) {
-                if (action === "remove") {
-                    const rendered = renderQueueList(contextKey, promptStore.list(contextKey));
-                    await safeEditMessage(bot, chatId, messageId, rendered.html, {
-                        fallbackText: rendered.plain,
-                        replyMarkup: rendered.keyboard,
-                    });
-                }
-                else {
-                    const message = `Queued prompt ${queueId} is no longer queued.`;
-                    await safeEditMessage(bot, chatId, messageId, escapeHTML(message), { fallbackText: message });
-                }
-            }
-            return;
-        }
-        const message = `Cancelled queued prompt ${removed.id}.`;
-        await ctx.answerCallbackQuery({ text: message });
-        if (!chatId || !messageId) {
-            return;
-        }
-        if (action === "remove") {
-            const rendered = renderQueueList(contextKey, promptStore.list(contextKey));
-            await safeEditMessage(bot, chatId, messageId, rendered.html, {
-                fallbackText: rendered.plain,
-                replyMarkup: rendered.keyboard,
-            });
-            return;
-        }
-        await safeEditMessage(bot, chatId, messageId, escapeHTML(message), { fallbackText: message });
-    });
     bot.callbackQuery(/^approval_(yes|no):([a-z0-9]+)$/, async (ctx) => {
         const action = ctx.match?.[1];
         const approvalId = ctx.match?.[2];
@@ -3627,65 +2731,6 @@ export function createBot(config, registry) {
             fallbackText: `⚡ ${label} set to ${effort} — ${scope}.`,
         });
     });
-    bot.callbackQuery(/^artifact_(send|zip|delete|delete_confirm):([a-zA-Z0-9._-]+)$/, async (ctx) => {
-        const action = ctx.match?.[1];
-        const turnId = ctx.match?.[2];
-        const chatId = ctx.chat?.id;
-        const messageId = ctx.callbackQuery.message?.message_id;
-        if (!action || !turnId || !chatId) {
-            await ctx.answerCallbackQuery();
-            return;
-        }
-        const contextSession = await getContextSession(ctx, { deferThreadStart: true });
-        if (!contextSession) {
-            await ctx.answerCallbackQuery({ text: "No context" });
-            return;
-        }
-        const workspace = contextSession.session.getInfo().workspace;
-        if (action === "delete") {
-            await ctx.answerCallbackQuery({ text: "Confirm deletion" });
-            const keyboard = new InlineKeyboard()
-                .text("Delete artifacts", `artifact_delete_confirm:${turnId}`)
-                .row()
-                .text("Cancel", NOOP_PAGE_CALLBACK_DATA);
-            const html = `<b>Delete artifact turn?</b>\n<code>${escapeHTML(turnId)}</code>`;
-            const plain = `Delete artifact turn?\n${turnId}`;
-            if (messageId) {
-                await safeEditMessage(bot, chatId, messageId, html, { fallbackText: plain, replyMarkup: keyboard });
-            }
-            else {
-                await safeReply(ctx, html, { fallbackText: plain, replyMarkup: keyboard });
-            }
-            return;
-        }
-        if (action === "delete_confirm") {
-            const removed = await removeArtifactTurn(workspace, turnId);
-            await ctx.answerCallbackQuery({ text: removed ? "Deleted" : "Already gone" });
-            const html = removed
-                ? `<b>Deleted artifact turn:</b> <code>${escapeHTML(turnId)}</code>`
-                : `<b>Artifact turn not found:</b> <code>${escapeHTML(turnId)}</code>`;
-            const plain = removed ? `Deleted artifact turn: ${turnId}` : `Artifact turn not found: ${turnId}`;
-            if (messageId) {
-                await safeEditMessage(bot, chatId, messageId, html, { fallbackText: plain });
-            }
-            else {
-                await safeReply(ctx, html, { fallbackText: plain });
-            }
-            return;
-        }
-        const report = await getArtifactTurnReport(workspace, turnId, config.maxFileSize);
-        if (!report) {
-            await ctx.answerCallbackQuery({ text: "Artifact turn not found" });
-            return;
-        }
-        await ctx.answerCallbackQuery({ text: action === "zip" ? "Sending ZIP..." : "Sending artifacts..." });
-        if (action === "zip") {
-            await deliverArtifactReportZip(ctx, chatId, report, ctx.callbackQuery.message?.message_thread_id);
-        }
-        else {
-            await deliverArtifactReport(ctx, chatId, report, ctx.callbackQuery.message?.message_thread_id);
-        }
-    });
     bot.on("message:text", async (ctx) => {
         const contextSession = await getContextSession(ctx);
         if (!contextSession) {