@goodandready/dsh-messenger-gateway 0.4.0 → 0.4.1

package/lib/alerts.js

@@ -1,105 +1,105 @@
-import { escapeHtml } from './telegram-format.js'
-import { normalizeThreadId } from './topics.js'
-import { t } from './locales/index.js'
-
-export function formatAlertMessage(type, payload = {}) {
-  const timestamp = new Date().toLocaleTimeString()
-
-  if (type === 'pairing') {
-    const { userId, username, code } = payload
-    const userStr = username ? `@${username} (id: <code>${userId}</code>)` : `id: <code>${userId}</code>`
-    return [
-      `🔐 <b>[Pairing Request]</b> <i>(${timestamp})</i>`,
-      '',
-      `User: ${userStr}`,
-      `Pairing Code: <code>${code}</code>`,
-      '',
-      `To approve, send to bot:`,
-      `<code>/pair ${code}</code>`,
-    ].join('\n')
-  }
-
-  if (type === 'error') {
-    const { message, code, sessionId, chatId, threadId } = payload
-    const location = chatId ? `Chat: <code>${chatId}</code>${threadId ? ` / thread <code>${threadId}</code>` : ''}` : ''
-    const sess = sessionId ? `Session: <code>${sessionId}</code>` : ''
-    const meta = [location, sess].filter(Boolean).join('\n')
-
-    return [
-      `🚨 <b>[Gateway Error]</b> <i>(${timestamp})</i>`,
-      meta ? `\n${meta}` : '',
-      `Error code: <b>${escapeHtml(String(code || 'error'))}</b>`,
-      `<code>${escapeHtml(String(message || 'unknown error'))}</code>`,
-    ].filter(Boolean).join('\n')
-  }
-
-  if (type === 'status') {
-    const { title, details } = payload
-    return [
-      `⚡ <b>[Gateway: ${escapeHtml(title || 'Status')}]</b> <i>(${timestamp})</i>`,
-      details ? `\n${escapeHtml(details)}` : '',
-    ].filter(Boolean).join('\n')
-  }
-
-  return `🔔 <b>[Alert: ${type}]</b> <i>(${timestamp})</i>\n${escapeHtml(JSON.stringify(payload))}`
-}
-
-export function resolveAlertTarget(gateway) {
-  const alertsCfg = gateway?.config?.telegram?.alerts
-  if (!alertsCfg || alertsCfg.enabled === false) return null
-
-  // If a named home is specified
-  if (alertsCfg.home) {
-    const home = gateway.resolveHomeTarget('telegram', alertsCfg.home)
-    if (home) return home
-  }
-
-  const chatId = alertsCfg.chatId
-  if (!chatId) return null
-
-  return {
-    platform: 'telegram',
-    chatId,
-    threadId: normalizeThreadId(alertsCfg.threadId),
-  }
-}
-
-export async function handleSetAlertCommand(gw, input, locale) {
-  const { reply, userId, chatId, threadId = 0 } = input
-  if (!gw.isUserAllowed(userId)) return reply(t('msg.not_allowed', {}, locale))
-  const nextTg = {
-    ...gw.tg(),
-    alerts: {
-      ...(gw.tg().alerts || {}),
-      enabled: true,
-      chatId,
-      threadId: threadId || 0,
-    },
-  }
-  gw.config.telegram = nextTg
-  try { await gw.hooks?.persistHomes?.(nextTg) } catch (err) { gw.logger?.warn?.('persistHomes error:', err?.message || err) }
-  return reply(`🔔 This chat assigned as alert channel (chat: ${chatId}${threadId ? `, topic: ${threadId}` : ''}).`)
-}
-
-export async function handleAlertCommand(gw, input, parts) {
-  const { reply, userId } = input
-  const sub = parts[1]?.toLowerCase()
-  if (sub === 'test') {
-    const target = resolveAlertTarget(gw)
-    if (!target) return reply('Alert channel not configured. Configure: /setalert')
-    await gw.sendAlert('status', { title: 'Test Alert', details: `Sent by user ID ${userId}` })
-    return reply('Test alert sent to alert channel.')
-  }
-  const target = resolveAlertTarget(gw)
-  const alertsCfg = gw.tg().alerts || {}
-  return reply([
-    '🔔 <b>Alert Channel:</b>',
-    `Status: ${alertsCfg.enabled ? 'enabled' : 'disabled'}`,
-    `Chat: ${target ? `${target.chatId}${target.threadId ? ` (topic: ${target.threadId})` : ''}` : '(not assigned)'}`,
-    `Events: ${(alertsCfg.events || ['error', 'pairing']).join(', ')}`,
-    '',
-    'Commands:',
-    '/setalert — assign current chat as alert channel',
-    '/alert test — send test alert',
-  ].join('\n'))
-}
+import { escapeHtml } from './telegram-format.js'
+import { normalizeThreadId } from './topics.js'
+import { t } from './locales/index.js'
+
+export function formatAlertMessage(type, payload = {}) {
+  const timestamp = new Date().toLocaleTimeString()
+
+  if (type === 'pairing') {
+    const { userId, username, code } = payload
+    const userStr = username ? `@${username} (id: <code>${userId}</code>)` : `id: <code>${userId}</code>`
+    return [
+      `🔐 <b>[Pairing Request]</b> <i>(${timestamp})</i>`,
+      '',
+      `User: ${userStr}`,
+      `Pairing Code: <code>${code}</code>`,
+      '',
+      `To approve, send to bot:`,
+      `<code>/pair ${code}</code>`,
+    ].join('\n')
+  }
+
+  if (type === 'error') {
+    const { message, code, sessionId, chatId, threadId } = payload
+    const location = chatId ? `Chat: <code>${chatId}</code>${threadId ? ` / thread <code>${threadId}</code>` : ''}` : ''
+    const sess = sessionId ? `Session: <code>${sessionId}</code>` : ''
+    const meta = [location, sess].filter(Boolean).join('\n')
+
+    return [
+      `🚨 <b>[Gateway Error]</b> <i>(${timestamp})</i>`,
+      meta ? `\n${meta}` : '',
+      `Error code: <b>${escapeHtml(String(code || 'error'))}</b>`,
+      `<code>${escapeHtml(String(message || 'unknown error'))}</code>`,
+    ].filter(Boolean).join('\n')
+  }
+
+  if (type === 'status') {
+    const { title, details } = payload
+    return [
+      `⚡ <b>[Gateway: ${escapeHtml(title || 'Status')}]</b> <i>(${timestamp})</i>`,
+      details ? `\n${escapeHtml(details)}` : '',
+    ].filter(Boolean).join('\n')
+  }
+
+  return `🔔 <b>[Alert: ${type}]</b> <i>(${timestamp})</i>\n${escapeHtml(JSON.stringify(payload))}`
+}
+
+export function resolveAlertTarget(gateway) {
+  const alertsCfg = gateway?.config?.telegram?.alerts
+  if (!alertsCfg || alertsCfg.enabled === false) return null
+
+  // If a named home is specified
+  if (alertsCfg.home) {
+    const home = gateway.resolveHomeTarget('telegram', alertsCfg.home)
+    if (home) return home
+  }
+
+  const chatId = alertsCfg.chatId
+  if (!chatId) return null
+
+  return {
+    platform: 'telegram',
+    chatId,
+    threadId: normalizeThreadId(alertsCfg.threadId),
+  }
+}
+
+export async function handleSetAlertCommand(gw, input, locale) {
+  const { reply, userId, chatId, threadId = 0 } = input
+  if (!gw.isUserAllowed(userId)) return reply(t('msg.not_allowed', {}, locale))
+  const nextTg = {
+    ...gw.tg(),
+    alerts: {
+      ...(gw.tg().alerts || {}),
+      enabled: true,
+      chatId,
+      threadId: threadId || 0,
+    },
+  }
+  gw.config.telegram = nextTg
+  try { await gw.hooks?.persistHomes?.(nextTg) } catch (err) { gw.logger?.warn?.('persistHomes error:', err?.message || err) }
+  return reply(`🔔 This chat assigned as alert channel (chat: ${chatId}${threadId ? `, topic: ${threadId}` : ''}).`)
+}
+
+export async function handleAlertCommand(gw, input, parts) {
+  const { reply, userId } = input
+  const sub = parts[1]?.toLowerCase()
+  if (sub === 'test') {
+    const target = resolveAlertTarget(gw)
+    if (!target) return reply('Alert channel not configured. Configure: /setalert')
+    await gw.sendAlert('status', { title: 'Test Alert', details: `Sent by user ID ${userId}` })
+    return reply('Test alert sent to alert channel.')
+  }
+  const target = resolveAlertTarget(gw)
+  const alertsCfg = gw.tg().alerts || {}
+  return reply([
+    '🔔 <b>Alert Channel:</b>',
+    `Status: ${alertsCfg.enabled ? 'enabled' : 'disabled'}`,
+    `Chat: ${target ? `${target.chatId}${target.threadId ? ` (topic: ${target.threadId})` : ''}` : '(not assigned)'}`,
+    `Events: ${(alertsCfg.events || ['error', 'pairing']).join(', ')}`,
+    '',
+    'Commands:',
+    '/setalert — assign current chat as alert channel',
+    '/alert test — send test alert',
+  ].join('\n'))
+}

package/lib/api-health.js

@@ -1,38 +1,38 @@
-export class ApiHealthTracker {
-  constructor(options = {}) {
-    this.logger = options.logger || console
-    this.degradedThreshold = Number(options.degradedThreshold) || 3
-    this.warnThreshold = Number(options.warnThreshold) || 5
-    this.consecutiveFailures = 0
-    this.lastError = null
-  }
-
-  recordFailure(op, err) {
-    this.consecutiveFailures++
-    this.lastError = {
-      op,
-      message: err?.message || String(err),
-      time: Date.now(),
-    }
-    this.logger?.debug?.(`dsh-messenger-gateway: Telegram API ${op} failed (${this.consecutiveFailures} consecutive):`, err?.message || err)
-    if (this.consecutiveFailures >= this.warnThreshold && this.consecutiveFailures % this.warnThreshold === 0) {
-      this.logger?.warn?.(`dsh-messenger-gateway: Telegram API experiencing repeated failures (${this.consecutiveFailures} in a row). Last op: ${op}, error: ${err?.message || err}`)
-    }
-  }
-
-  recordSuccess() {
-    this.consecutiveFailures = 0
-  }
-
-  isDegraded() {
-    return this.consecutiveFailures >= this.degradedThreshold
-  }
-
-  getSnapshot() {
-    return {
-      degraded: this.isDegraded(),
-      consecutiveFailures: this.consecutiveFailures,
-      lastError: this.lastError,
-    }
-  }
-}
+export class ApiHealthTracker {
+  constructor(options = {}) {
+    this.logger = options.logger || console
+    this.degradedThreshold = Number(options.degradedThreshold) || 3
+    this.warnThreshold = Number(options.warnThreshold) || 5
+    this.consecutiveFailures = 0
+    this.lastError = null
+  }
+
+  recordFailure(op, err) {
+    this.consecutiveFailures++
+    this.lastError = {
+      op,
+      message: err?.message || String(err),
+      time: Date.now(),
+    }
+    this.logger?.debug?.(`dsh-messenger-gateway: Telegram API ${op} failed (${this.consecutiveFailures} consecutive):`, err?.message || err)
+    if (this.consecutiveFailures >= this.warnThreshold && this.consecutiveFailures % this.warnThreshold === 0) {
+      this.logger?.warn?.(`dsh-messenger-gateway: Telegram API experiencing repeated failures (${this.consecutiveFailures} in a row). Last op: ${op}, error: ${err?.message || err}`)
+    }
+  }
+
+  recordSuccess() {
+    this.consecutiveFailures = 0
+  }
+
+  isDegraded() {
+    return this.consecutiveFailures >= this.degradedThreshold
+  }
+
+  getSnapshot() {
+    return {
+      degraded: this.isDegraded(),
+      consecutiveFailures: this.consecutiveFailures,
+      lastError: this.lastError,
+    }
+  }
+}

package/lib/client.js

@@ -12,6 +12,10 @@ window.__ModuleLoader__.load({
 
     const NS = 'dsh-messenger-gateway'
     const ROUTE_PREFIX = '/dsh-messenger-gateway'
+    // Plugins page row seat: key = '<package name>#<row id>', row id as cordis.patch.yml declares it.
+    const PKG = '@goodandready/dsh-messenger-gateway'
+    const ROW_ID = 'dsh-messenger-gateway'
+    const ROW_CONFIG_KEY = PKG + '#' + ROW_ID
 
     const en = {
       title: 'Messenger gateway',
@@ -335,6 +339,7 @@ window.__ModuleLoader__.load({
       style.dataset.dshPlugin = NS
       style.textContent = `
 .msgw-page{display:flex;flex-direction:column;gap:16px;color:var(--dsw-alias-label-primary);font-family:inherit}
+.msgw-page-seat{padding:0}
 .msgw-header{display:flex;flex-direction:column;gap:4px;padding-bottom:12px;border-bottom:1px solid var(--dsw-alias-border-l2)}
 .msgw-page-title{font-size:18px;font-weight:700;display:flex;align-items:center;gap:10px;flex-wrap:wrap;color:var(--dsw-alias-label-primary)}
 .msgw-page-sub{font-size:13px;color:var(--dsw-alias-label-secondary);line-height:1.4}
@@ -1512,6 +1517,23 @@ window.__ModuleLoader__.load({
         ensureCss()
       }, [])
 
+      // Plugins page row seat ('plugins.row.config'): the host page draws the title,
+      // icon and crumb and provides its own padding, so view 'page' renders the form
+      // bare (no card chrome, which would double the border and clip the left edge)
+      // and view 'summary' renders the one-line state under the row title.
+      if (props && props.view === 'summary') {
+        return React.createElement('div', { className: 'msgw-sub' }, t('description'))
+      }
+      if (props && props.view === 'page') {
+        return React.createElement(
+          'div',
+          { className: 'msgw-page-seat' },
+          React.createElement(ErrorBoundary, null,
+            React.createElement(SettingsPage, { ...props, ctx: (props && props.ctx) || ctx, t })
+          )
+        )
+      }
+
       return React.createElement(
         'li',
         { className: 'msgw-card msgw-section-card', style: { listStyle: 'none', marginBottom: '12px' } },
@@ -1640,6 +1662,22 @@ window.__ModuleLoader__.load({
         }
       }
 
+      // Row seat on the Plugins page (current core): the plugin's row gains a
+      // configure control whose page is the settings form. Registered first; the
+      // legacy seats below stay as fallbacks so settings never become unreachable.
+      registerSlotWhenReady('plugins.row.config', () => {
+        const slots = ctx?.get?.('slots') || ctx?.slots
+        return slots.register(
+          {
+            name: 'plugins.row.config',
+            key: ROW_CONFIG_KEY,
+            locale: NS,
+            inject: () => ({ ctx }),
+          },
+          (props) => React.createElement(ErrorBoundary, null, React.createElement(PluginCard, { ...props, ctx: (props && props.ctx) || ctx }))
+        )
+      })
+
       registerSlotWhenReady('settings.plugin.item', () => {
         const slots = ctx?.get?.('slots') || ctx?.slots
         return slots.register(

package/lib/commands.js

@@ -1,126 +1,126 @@
-export const DEFAULT_TELEGRAM_COMMANDS = [
-  { command: 'start', description: 'Connect and show greeting' },
-  { command: 'help', description: 'Show commands help' },
-  { command: 'new', description: 'Start a new agent session' },
-  { command: 'whoami', description: 'Show your messenger user ID' },
-  { command: 'stop', description: 'Interrupt current turn' },
-  { command: 'pair', description: 'Approve pairing code: /pair CODE' },
-  { command: 'sethome', description: 'Set home: /sethome [name]' },
-  { command: 'home', description: 'List registered home channels' },
-  { command: 'model', description: 'Interactive model selector' },
-  { command: 'top', description: 'System resources: CPU, RAM, uptime' },
-  { command: 'topic', description: 'Create forum topic: /topic <name>' },
-  { command: 'status', description: 'Gateway and bot status' },
-  { command: 'setalert', description: 'Designate channel for alerts' },
-  { command: 'alert', description: 'Alert channel status: /alert [test]' },
-  { command: 'keyboard', description: 'Toggle quick actions: /keyboard on|off' },
-  { command: 'role', description: 'Switch persona: /role [name]' },
-  { command: 'bind', description: 'Bind preset/persona to forum topic: /bind <name>' },
-  { command: 'preset', description: 'Show or switch agent preset: /preset [name]' },
-  { command: 'cron', description: 'Manage recurring reports: /cron' },
-  { command: 'skills', description: 'List active tools & skills' },
-  { command: 'tools', description: 'List active tools' },
-  { command: 'fork', description: 'Fork session into new branch' },
-  { command: 'export', description: 'Export history to Markdown' },
-  { command: 'rewind', description: 'Rewind turns: /rewind [N]' },
-  { command: 'files', description: 'Workspace file explorer: /files [dir]' },
-  { command: 'get', description: 'Download file to messenger: /get <path>' },
-  { command: 'remind', description: 'Set reminder: /remind <time> <text>' },
-  { command: 'voice', description: 'Voice reply mode: /voice on|off|status' },
-  { command: 'tts', description: 'Speech in this chat: /tts on|off|status' },
-  { command: 'mute', description: 'Mute notifications in this chat' },
-  { command: 'unmute', description: 'Unmute notifications in this chat' },
-  { command: 'update', description: 'Check or install plugin update: /update [now]' },
-]
-
-export function normalizeTelegramCommands(commands) {
-  const source = Array.isArray(commands) && commands.length ? commands : DEFAULT_TELEGRAM_COMMANDS
-  const out = []
-  const seen = new Set()
-  for (const raw of source) {
-    if (!raw || typeof raw !== 'object') continue
-    let command = String(raw.command || '').trim().replace(/^\//, '')
-    const description = String(raw.description || '').trim()
-    if (!command || !description) continue
-    command = command.slice(0, 32).toLowerCase()
-    if (seen.has(command)) continue
-    seen.add(command)
-    out.push({ command, description: description.slice(0, 256) })
-  }
-  return out.length ? out : [...DEFAULT_TELEGRAM_COMMANDS]
-}
-
-export function mergeDynamicCommands(baseCommands = DEFAULT_TELEGRAM_COMMANDS, dynamicCommands = [], maxTotal = 100) {
-  const normalizedBase = normalizeTelegramCommands(baseCommands)
-  const out = [...normalizedBase]
-  const seen = new Set(out.map((c) => c.command))
-
-  for (const item of dynamicCommands || []) {
-    if (out.length >= maxTotal) break
-    if (!item || typeof item !== 'object') continue
-    let command = String(item.command || item.name || '').trim().replace(/^\//, '').toLowerCase()
-    // Telegram format: lowercase alphanumeric and underscore only, 1-32 chars
-    command = command.replace(/[^a-z0-9_]/g, '_').slice(0, 32)
-    if (!command || seen.has(command)) continue
-    let description = String(item.description || item.title || `Skill ${command}`).trim()
-    if (!description) description = `Skill ${command}`
-    description = description.slice(0, 256)
-    seen.add(command)
-    out.push({ command, description })
-  }
-
-  return out.slice(0, maxTotal)
-}
-
-export function buildQuickActionsKeyboard() {
-  return {
-    keyboard: [
-      [{ text: '🔄 /new' }, { text: '🛑 /stop' }],
-      [{ text: '🎙️ /voice' }, { text: '📊 /status' }],
-    ],
-    resize_keyboard: true,
-  }
-}
-
-export const REMOVE_REPLY_KEYBOARD = { remove_keyboard: true }
-
-export const HELP_TEXT = [
-  '📖 <b>Messenger Gateway Help:</b>',
-  '',
-  '💬 <b>Session & Chat:</b>',
-  '• /help — show this command reference',
-  '• /new — start fresh session',
-  '• /stop — interrupt current response',
-  '• /model — interactive model selector (/model list)',
-  '• /role [name] — switch persona or role (/role list)',
-  '• /bind [role] — bind persona to topic / chat',
-  '• /preset [name] — bind preset to topic / chat',
-  '• /lang [en|zh] — switch user language',
-  '• /rewind [N] — rewind last N turns',
-  '• /fork — fork session into new branch',
-  '• /export — export history to Markdown',
-  '',
-  '🛠️ <b>Tools, Files & Cron:</b>',
-  '• /skills / /tools — list active tools & skills',
-  '• /files [dir] — workspace file explorer',
-  '• /get <path> — download file from workspace',
-  '• /remind <time> <text> — set reminder (/remind 10m check deploy)',
-  '• /cron <interval> <prompt> — recurring autonomous task',
-  '',
-  '⚙️ <b>Settings & Stats:</b>',
-  '• /status — gateway and active model status',
-  '• /top — system resource usage (RAM, uptime)',
-  '• /keyboard on|off — quick action keyboard',
-  '• /voice on|off|status — voice replies preference',
-  '• /tts on|off|status — speech synthesis in this chat',
-  '• /mute / /unmute — mute notifications in this chat',
-  '',
-  '🔒 <b>Access & Channels:</b>',
-  '• /whoami — your messenger user ID',
-  '• /pair CODE — approve pairing code',
-  '• /sethome [name] — set home notification channel',
-  '• /setalert — set alert channel',
-].join('\n')
-
-
-
+export const DEFAULT_TELEGRAM_COMMANDS = [
+  { command: 'start', description: 'Connect and show greeting' },
+  { command: 'help', description: 'Show commands help' },
+  { command: 'new', description: 'Start a new agent session' },
+  { command: 'whoami', description: 'Show your messenger user ID' },
+  { command: 'stop', description: 'Interrupt current turn' },
+  { command: 'pair', description: 'Approve pairing code: /pair CODE' },
+  { command: 'sethome', description: 'Set home: /sethome [name]' },
+  { command: 'home', description: 'List registered home channels' },
+  { command: 'model', description: 'Interactive model selector' },
+  { command: 'top', description: 'System resources: CPU, RAM, uptime' },
+  { command: 'topic', description: 'Create forum topic: /topic <name>' },
+  { command: 'status', description: 'Gateway and bot status' },
+  { command: 'setalert', description: 'Designate channel for alerts' },
+  { command: 'alert', description: 'Alert channel status: /alert [test]' },
+  { command: 'keyboard', description: 'Toggle quick actions: /keyboard on|off' },
+  { command: 'role', description: 'Switch persona: /role [name]' },
+  { command: 'bind', description: 'Bind preset/persona to forum topic: /bind <name>' },
+  { command: 'preset', description: 'Show or switch agent preset: /preset [name]' },
+  { command: 'cron', description: 'Manage recurring reports: /cron' },
+  { command: 'skills', description: 'List active tools & skills' },
+  { command: 'tools', description: 'List active tools' },
+  { command: 'fork', description: 'Fork session into new branch' },
+  { command: 'export', description: 'Export history to Markdown' },
+  { command: 'rewind', description: 'Rewind turns: /rewind [N]' },
+  { command: 'files', description: 'Workspace file explorer: /files [dir]' },
+  { command: 'get', description: 'Download file to messenger: /get <path>' },
+  { command: 'remind', description: 'Set reminder: /remind <time> <text>' },
+  { command: 'voice', description: 'Voice reply mode: /voice on|off|status' },
+  { command: 'tts', description: 'Speech in this chat: /tts on|off|status' },
+  { command: 'mute', description: 'Mute notifications in this chat' },
+  { command: 'unmute', description: 'Unmute notifications in this chat' },
+  { command: 'update', description: 'Check or install plugin update: /update [now]' },
+]
+
+export function normalizeTelegramCommands(commands) {
+  const source = Array.isArray(commands) && commands.length ? commands : DEFAULT_TELEGRAM_COMMANDS
+  const out = []
+  const seen = new Set()
+  for (const raw of source) {
+    if (!raw || typeof raw !== 'object') continue
+    let command = String(raw.command || '').trim().replace(/^\//, '')
+    const description = String(raw.description || '').trim()
+    if (!command || !description) continue
+    command = command.slice(0, 32).toLowerCase()
+    if (seen.has(command)) continue
+    seen.add(command)
+    out.push({ command, description: description.slice(0, 256) })
+  }
+  return out.length ? out : [...DEFAULT_TELEGRAM_COMMANDS]
+}
+
+export function mergeDynamicCommands(baseCommands = DEFAULT_TELEGRAM_COMMANDS, dynamicCommands = [], maxTotal = 100) {
+  const normalizedBase = normalizeTelegramCommands(baseCommands)
+  const out = [...normalizedBase]
+  const seen = new Set(out.map((c) => c.command))
+
+  for (const item of dynamicCommands || []) {
+    if (out.length >= maxTotal) break
+    if (!item || typeof item !== 'object') continue
+    let command = String(item.command || item.name || '').trim().replace(/^\//, '').toLowerCase()
+    // Telegram format: lowercase alphanumeric and underscore only, 1-32 chars
+    command = command.replace(/[^a-z0-9_]/g, '_').slice(0, 32)
+    if (!command || seen.has(command)) continue
+    let description = String(item.description || item.title || `Skill ${command}`).trim()
+    if (!description) description = `Skill ${command}`
+    description = description.slice(0, 256)
+    seen.add(command)
+    out.push({ command, description })
+  }
+
+  return out.slice(0, maxTotal)
+}
+
+export function buildQuickActionsKeyboard() {
+  return {
+    keyboard: [
+      [{ text: '🔄 /new' }, { text: '🛑 /stop' }],
+      [{ text: '🎙️ /voice' }, { text: '📊 /status' }],
+    ],
+    resize_keyboard: true,
+  }
+}
+
+export const REMOVE_REPLY_KEYBOARD = { remove_keyboard: true }
+
+export const HELP_TEXT = [
+  '📖 <b>Messenger Gateway Help:</b>',
+  '',
+  '💬 <b>Session & Chat:</b>',
+  '• /help — show this command reference',
+  '• /new — start fresh session',
+  '• /stop — interrupt current response',
+  '• /model — interactive model selector (/model list)',
+  '• /role [name] — switch persona or role (/role list)',
+  '• /bind [role] — bind persona to topic / chat',
+  '• /preset [name] — bind preset to topic / chat',
+  '• /lang [en|zh] — switch user language',
+  '• /rewind [N] — rewind last N turns',
+  '• /fork — fork session into new branch',
+  '• /export — export history to Markdown',
+  '',
+  '🛠️ <b>Tools, Files & Cron:</b>',
+  '• /skills / /tools — list active tools & skills',
+  '• /files [dir] — workspace file explorer',
+  '• /get <path> — download file from workspace',
+  '• /remind <time> <text> — set reminder (/remind 10m check deploy)',
+  '• /cron <interval> <prompt> — recurring autonomous task',
+  '',
+  '⚙️ <b>Settings & Stats:</b>',
+  '• /status — gateway and active model status',
+  '• /top — system resource usage (RAM, uptime)',
+  '• /keyboard on|off — quick action keyboard',
+  '• /voice on|off|status — voice replies preference',
+  '• /tts on|off|status — speech synthesis in this chat',
+  '• /mute / /unmute — mute notifications in this chat',
+  '',
+  '🔒 <b>Access & Channels:</b>',
+  '• /whoami — your messenger user ID',
+  '• /pair CODE — approve pairing code',
+  '• /sethome [name] — set home notification channel',
+  '• /setalert — set alert channel',
+].join('\n')
+
+
+