@goodandready/dsh-messenger-gateway 0.1.0 → 0.3.0

package/README.md

@@ -1,26 +1,24 @@
 # @goodandready/dsh-messenger-gateway
 
-Messenger transport for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).
+Telegram messenger bridge for [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness).
 
-## 0.1.0 scope (Telegram)
+Talk to your Harness agent from Telegram: text, voice, photos, documents, inline buttons, named homes, and optional spoken replies.
 
-- Long-poll Telegram bot
-- Text, voice (`dsh-voice`), photos (`attachments` + `dsh-vision-bridge`), documents
-- Outbound images from tool results
-- `messenger` service: HTTP `/messenger/send`, `/ask`, `/progress` and `ctx.provide('messenger')`
-- Forum topics = separate agent sessions (`message_thread_id`)
-- Optional spoken replies (`dsh-tts`)
-- Commands: `/start` `/help` `/new` `/whoami` `/stop`
+## Features
 
-Discord adapter is a stub; full Discord support comes after 0.1.0.
+- Long-poll or webhook Telegram bot
+- Allowlist + pairing codes
+- Per-user or per-chat sessions (`sessionScope`)
+- Forum topics as separate sessions
+- 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
 
-## Profile dependencies
-
-Install these plugins in the same Harness profile (they are not npm dependencies):
-
-- `dsh-voice` — inbound voice transcription
-- `dsh-tts` — optional spoken replies
-- `dsh-vision-bridge` — inbound photo understanding
+Discord is listed in settings as a placeholder only — the Discord adapter is not implemented yet.
 
 ## Install
 
@@ -28,8 +26,59 @@ Install these plugins in the same Harness profile (they are not npm dependencies
 dsh plugin --profile web add @goodandready/dsh-messenger-gateway
 ```
 
-Settings → **Messenger gateway** → enable Telegram, paste bot token, set allowed user IDs.
+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` `/status` | Model / gateway status |
+| `/voice on\|off` | Per-user spoken replies |
+| `/sethome [name]` | Bind current chat/topic as a named home |
+| `/home` | List homes |
+
+## 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
+
+## 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`
 
-See `docs/deployment/0.1.0-install.md` for staging smoke and prod swap vs legacy hub-media.
+## License
 
 MIT

package/lib/adapters/index.js

@@ -1,7 +1,7 @@
 import { TelegramAdapter } from './telegram.js'
 
 export default function createAdapters(deps) {
-  const { config, onMessage, onCallback, logger } = deps
+  const { config, onMessage, onCallback, onUnauthorized, isUserAllowed, logger } = deps
   const list = []
   const tg = config.telegram || {}
   if (config.enabled !== false && tg.enabled && String(tg.botToken || '').trim()) {
@@ -10,9 +10,22 @@ export default function createAdapters(deps) {
       allowedUserIds: tg.allowedUserIds,
       timeoutSeconds: tg.pollTimeoutSeconds,
       pollIntervalMs: tg.pollIntervalMs,
+      commands: tg.commands,
+      textFormat: tg.textFormat,
+      groupsEnabled: tg.groupsEnabled,
+      groupRequireMention: tg.groupRequireMention,
+      reactionsEnabled: tg.reactionsEnabled,
+      statusIndicator: tg.statusIndicator,
+      statusOnline: tg.statusOnline,
+      statusOffline: tg.statusOffline,
+      transport: tg.transport,
+      webhookUrl: tg.webhookUrl,
+      webhookSecret: tg.webhookSecret,
       media: config.media,
       onMessage,
       onCallback,
+      onUnauthorized,
+      isUserAllowed,
       logger,
     }))
   }
@@ -21,4 +34,4 @@ export default function createAdapters(deps) {
     logger?.warn?.('dsh-messenger-gateway: discord adapter is not implemented yet')
   }
   return list
-}
+}