📦 @goodandready/dsh-messenger-gateway

<div align="center"><h3>Telegram Messenger Bridge with Interactive Buttons, Forum Topics & Voice Notes for DeepSeek Harness</h3><p align="center"> <a href="https://www.npmjs.com/package/@goodandready/dsh-messenger-gateway"><img src="https://img.shields.io/npm/v/@goodandready/dsh-messenger-gateway.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a> <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-10b981.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a> <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a> <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a> </p><p align="center"> <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/All_Author_Projects-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="All Author Projects"></a> </p><p align="center"> <a href="README.md"><b>🇬🇧 English</b></a> • <a href="README.ru.md"><b>🇷🇺 Русский</b></a> • <a href="README.zh.md"><b>🇨🇳 中文说明</b></a> </p><table align="center"> <tr> <td align="center"> ⭐ <strong>If you like this plugin, please star it on GitHub</strong> — it shows me that the plugin is useful to you and motivates me to keep developing it. <br><br> 🐛 <strong>If you find a bug or would like to request a feature</strong>, open a GitHub issue in any language — I will review your proposal and implement useful suggestions in a future plugin version. </td> </tr> </table></div>

---

⚡ Overview

dsh-messenger-gateway provides an enterprise-grade, multi-transport messaging gateway for DeepSeek Harness agents. Talk to your Harness agent directly from Telegram: interactive keyboard buttons, forum topic sessions, private user workspaces, pairing codes, and optional spoken voice replies.

Talk to your Harness agent from Telegram: text, voice, photos, documents, inline buttons, named homes, and optional spoken replies.

Features

• Long-poll or webhook Telegram bot
• Multi-transport support: Telegram, Discord (Webhooks & Bot API), and Slack (Webhooks & Bot API)
• Allowlist + pairing codes
• Per-user or per-chat sessions (sessionScope)
• Forum topics as separate sessions
• Quick actions reply keyboard (/keyboard on|off)
• Multi-select interactive ask forms with checkboxes and pagination (messenger_ask)
• Artifact & Mermaid diagram rendering (SVG cards) and monospace table formatting
• Agent roles & personas (/role coder, /role architect, @role tags in group chats)
• Agent tools & skills inspection (/skills, /tools)
• Session management: dialogue history export to Markdown (/export), turn rewind (/rewind), session branching (/fork)
• Workspace file manager (/files [dir]) and file download (/get <path>) with directory traversal protection
• Admin alert channel for pairing requests, model errors and monitoring (/setalert, /alert)
• Persistent scheduled reminders (/remind <time> <text>, /remind list, /remind cancel)
• Inbound webhook event dispatcher (POST /dsh-messenger-gateway/events) for CI/CD and external alerts
• Steer: follow-up messages while the agent is busy (instead of aborting)
• /stop, /new, /model, /status, /voice, /sethome, /home
• Agent tool messenger_ask (inline keyboard answers return to the agent)
• Named homes for outbound notify / messenger.send
• Optional notify bridge: web session events → Telegram home (excludes messenger sessions)
• Inbound voice → STT (dsh-voice), photos → vision (dsh-vision-bridge)
• Optional TTS replies (dsh-tts); mp3 is converted to OGG/Opus via ffmpeg for Telegram voice notes

Discord and Slack adapters are available as outbound transports (Webhooks or Bot REST APIs).

Install

dsh plugin --profile web add @goodandready/dsh-messenger-gateway

Then open Settings → Plugins → Messenger gateway:

1. Enable Telegram
2. Paste the BotFather token (write-only; leave blank to keep the current token)
3. Set allowed Telegram user IDs (or use pairing)

Optional companion plugins (same profile)

Plugin	Role
@goodandready/dsh-voice	Transcribe inbound voice messages
@goodandready/dsh-tts	Speak agent replies
@goodandready/dsh-vision-bridge	Describe inbound photos

They are not npm dependencies of this package — install them separately if you want those features.

Voice notes

Spoken replies use Telegram sendVoice. If TTS returns MP3 (or other non-Opus audio), the gateway runs ffmpeg (libopus) to produce OGG. If ffmpeg is missing or conversion fails, the audio is sent as a regular audio file instead of a voice note.

Commands (Telegram)

Command	Description
/start /help	Help
/whoami	Your Telegram user id
/new	New agent session
/stop	Abort the current turn
/model	Interactive 2-step model picker (providers → models) or /model <prov> <mod>
/status	Gateway status and session counters
/top	Live server resources: RSS/Heap memory, uptime, active chats, reminders
/topic <name>	Create a new Telegram forum topic in supergroups and start an isolated session
/role [name]	Switch agent persona (coder, architect, reviewer, writer, translator, concise)
/skills /tools	List active agent tools and capabilities
/fork	Fork current session into a new independent session
/export	Export session dialogue history to Markdown
/rewind [N]	Rewind last N conversation turns
/files [dir]	Workspace file manager
/get <path>	Download file from workspace
/remind <time> <text>	Set a reminder (e.g. /remind 15m Call client)
/setalert /alert	Configure admin alert channel and send test alert
/keyboard on|off	Toggle quick actions reply keyboard
/voice on|off	Per-user spoken replies
/tts on|off|status	Per-chat spoken replies
/sethome [name]	Bind current chat/topic as a named home
/home	List homes

Multi-Transport Support (Discord & Slack)

In addition to Telegram, outbound messages can be dispatched to Discord and Slack via Webhooks or Bot APIs:

• Discord: set discord.enabled: true, provide either webhookUrl or botToken. Target channels via chatId: "<channel_id>".
• Slack: set slack.enabled: true, provide either webhookUrl or botToken. Target channels via chatId: "<channel_id>" or threads via threadId: "<thread_ts>".

Agent tools & HTTP

• Tool: messenger_ask — ask the user with inline buttons; choice is fed back into the turn
• HTTP (when enabled): /messenger/send, /messenger/ask, /messenger/progress
• Cordis service: ctx.messenger for other plugins

Configuration notes

• sessionScope: user (default) or chat — how group chats isolate sessions
• voiceMode: mirror / always / off — when to speak replies (also /voice)
• tts.enabled / tts.maxChars — TTS gate and length cap
• notifyBridge — forward non-messenger web session events to a home
• Bot token is a DSH secret field — never commit it

Client UI & Settings Card

• Mounted into settings.plugin.item on the Plugins tab (key: dsh-messenger-gateway).
• Configuration is managed reactively via settingsScope.bind({ namespace: 'dsh-messenger-gateway' }) with snapshot status checking (loading, unavailable, ready).
• Protected dictionary registration: duplicate registration attempts on page reload are safely caught with non-fatal warnings, ensuring the settings card never fails to mount.

Requirements

• DeepSeek Harness web (or compatible) profile
• Node.js matching your Harness install
• For voice notes from non-Opus TTS: ffmpeg on the host PATH

License

MIT