dsh-messenger-gateway

📦 @goodandready/dsh-messenger-gateway

---

⚡ 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