@goodandready/dsh-messenger-gateway 0.1.0

package/lib/messenger-api.js

@@ -0,0 +1,225 @@
+import { normalizeThreadId } from './topics.js'
+
+const DEFAULT_ASK_TIMEOUT_MS = 300_000
+
+export const messengerApiSchema = {
+  version: 1,
+  service: 'messenger',
+  http: {
+    send: {
+      method: 'POST',
+      path: '/dsh-messenger-gateway/messenger/send',
+      body: {
+        target: { platform: 'telegram', chatId: 'number|string', threadId: 'optional number' },
+        text: 'optional string',
+        files: 'optional [{ dataBase64, mime, kind, name }]',
+        replyMarkup: 'optional Telegram inline_keyboard object',
+      },
+    },
+    ask: {
+      method: 'POST',
+      path: '/dsh-messenger-gateway/messenger/ask',
+      body: {
+        target: { platform: 'telegram', chatId: 'number|string' },
+        text: 'string (required)',
+        buttons: '[[{ id, text }]] (required, at least one button)',
+        timeoutMs: 'optional number (default 300000)',
+      },
+    },
+    progress: {
+      method: 'POST',
+      path: '/dsh-messenger-gateway/messenger/progress',
+      body: {
+        target: { platform: 'telegram', chatId: 'number|string' },
+        text: 'string (required)',
+      },
+    },
+  },
+}
+
+export function parseMessengerBody(raw) {
+  try {
+    return JSON.parse(String(raw || '{}') || '{}')
+  } catch {
+    const err = new Error('invalid json')
+    err.status = 400
+    throw err
+  }
+}
+
+export function validateTarget(target) {
+  if (!target || typeof target !== 'object') {
+    const err = new Error('target is required')
+    err.status = 400
+    throw err
+  }
+  const platform = String(target.platform || '').trim()
+  if (!platform) {
+    const err = new Error('target.platform is required')
+    err.status = 400
+    throw err
+  }
+  const chatId = target.chatId
+  if (chatId === undefined || chatId === null || String(chatId).trim() === '') {
+    const err = new Error('target.chatId is required')
+    err.status = 400
+    throw err
+  }
+  const out = { platform, chatId }
+  const threadId = normalizeThreadId(target.threadId)
+  if (threadId > 0) out.threadId = threadId
+  return out
+}
+
+export function normalizeButtons(buttons) {
+  if (buttons === undefined || buttons === null) return []
+  if (!Array.isArray(buttons)) {
+    const err = new Error('buttons must be a 2d array')
+    err.status = 400
+    throw err
+  }
+  return buttons.map((row, ri) => {
+    if (!Array.isArray(row)) {
+      const err = new Error(`buttons[${ri}] must be an array`)
+      err.status = 400
+      throw err
+    }
+    return row.map((btn, bi) => {
+      const id = String(btn?.id ?? btn?.buttonId ?? '').trim()
+      const text = String(btn?.text ?? '').trim()
+      if (!id || !text) {
+        const err = new Error(`buttons[${ri}][${bi}] requires id and text`)
+        err.status = 400
+        throw err
+      }
+      return { id, text }
+    })
+  })
+}
+
+export function normalizeFiles(files) {
+  if (!files) return []
+  if (!Array.isArray(files)) {
+    const err = new Error('files must be an array')
+    err.status = 400
+    throw err
+  }
+  return files.map((file, i) => {
+    if (!file || typeof file !== 'object') {
+      const err = new Error(`files[${i}] must be an object`)
+      err.status = 400
+      throw err
+    }
+    if (file.bytes) return file
+    if (typeof file.dataBase64 === 'string') {
+      return {
+        bytes: Buffer.from(file.dataBase64, 'base64'),
+        mime: file.mime || 'application/octet-stream',
+        kind: file.kind || 'document',
+        name: file.name || 'file',
+      }
+    }
+    const err = new Error(`files[${i}] needs bytes or dataBase64`)
+    err.status = 400
+    throw err
+  })
+}
+
+export function normalizeSendBody(payload) {
+  const text = typeof payload?.text === 'string' ? payload.text.trim() : ''
+  const files = normalizeFiles(payload?.files)
+  if (!text && !files.length) {
+    const err = new Error('text or files required')
+    err.status = 400
+    throw err
+  }
+  const body = {}
+  if (text) body.text = text
+  if (files.length) body.files = files
+  if (payload?.replyMarkup) body.replyMarkup = payload.replyMarkup
+  return body
+}
+
+export function normalizeAskBody(payload) {
+  const text = String(payload?.text || '').trim()
+  if (!text) {
+    const err = new Error('text is required for ask')
+    err.status = 400
+    throw err
+  }
+  const buttons = normalizeButtons(payload?.buttons)
+  if (!buttons.length || !buttons.some((row) => row.length > 0)) {
+    const err = new Error('ask requires at least one button')
+    err.status = 400
+    throw err
+  }
+  return { text, buttons }
+}
+
+export function normalizeProgressBody(payload) {
+  const text = String(payload?.text || '').trim()
+  if (!text) {
+    const err = new Error('text is required for progress')
+    err.status = 400
+    throw err
+  }
+  return { text }
+}
+
+export function resolveAskTimeoutMs(timeoutMs) {
+  const n = Number(timeoutMs)
+  if (!Number.isFinite(n) || n <= 0) return DEFAULT_ASK_TIMEOUT_MS
+  return Math.min(n, 3_600_000)
+}
+
+export function httpStatusForError(err) {
+  if (err?.status) return err.status
+  const msg = String(err?.message || '')
+  if (msg.includes('timed out')) return 504
+  if (msg.includes('not running') || msg.includes('unavailable')) return 503
+  return 502
+}
+
+export async function dispatchMessenger(gw, action, payload) {
+  if (!gw) {
+    const err = new Error('gateway not running')
+    err.status = 503
+    throw err
+  }
+  const target = validateTarget(payload?.target)
+  if (action === 'send') {
+    await gw.messenger.send(target, normalizeSendBody(payload))
+    return { ok: true }
+  }
+  if (action === 'progress') {
+    await gw.messenger.progress(target, normalizeProgressBody(payload))
+    return { ok: true }
+  }
+  if (action === 'ask') {
+    const result = await gw.messenger.ask(target, normalizeAskBody(payload), resolveAskTimeoutMs(payload?.timeoutMs))
+    return { ok: true, result }
+  }
+  const err = new Error(`unknown messenger action: ${action}`)
+  err.status = 400
+  throw err
+}
+
+export function createMessengerService(getGw) {
+  return {
+    adapters: () => getGw()?.messenger.adapters() ?? [],
+    activeChats: () => getGw()?.messenger.activeChats() ?? 0,
+    send: async (target, payload) => {
+      const gw = getGw()
+      await dispatchMessenger(gw, 'send', { target, ...payload })
+    },
+    progress: async (target, payload) => {
+      const gw = getGw()
+      await dispatchMessenger(gw, 'progress', { target, ...payload })
+    },
+    ask: async (target, payload, timeoutMs) => {
+      const gw = getGw()
+      const out = await dispatchMessenger(gw, 'ask', { target, ...payload, timeoutMs })
+      return out.result
+    },
+  }
+}

package/lib/outbound.js

@@ -0,0 +1,112 @@
+const IMAGE_URL_RE = /(\/(?:dsh-[\w-]+)\/image\?[^\s)]+)/g
+
+export function extractImageUrls(text) {
+  const urls = []
+  for (const m of String(text || '').matchAll(IMAGE_URL_RE)) urls.push(m[1])
+  return urls
+}
+
+/** Remove harness image URLs from reply text before sending to messenger. */
+export function stripImageUrls(text) {
+  return String(text || '')
+    .replace(IMAGE_URL_RE, '')
+    .replace(/[ \t]+\n/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim()
+}
+
+/** Collect image attachment refs from assistant content (incl. nested tool blocks). */
+export function collectImagesDeep(content) {
+  const images = []
+  const walk = (blocks) => {
+    if (!Array.isArray(blocks)) return
+    for (const block of blocks) {
+      if (!block || typeof block !== 'object') continue
+      if (block.type === 'image' && block.attachment) images.push(block.attachment)
+      if (Array.isArray(block.content)) walk(block.content)
+    }
+  }
+  walk(content)
+  return images
+}
+
+export function collectAssistantParts(message) {
+  const texts = []
+  for (const block of message?.content || []) {
+    if (block.type === 'text' && block.text) texts.push(block.text)
+  }
+  return { text: texts.join('\n\n').trim(), images: collectImagesDeep(message?.content) }
+}
+
+export function dedupeAttachmentRefs(refs) {
+  const seen = new Set()
+  const out = []
+  for (const ref of refs || []) {
+    const id = ref?.attachmentId ?? ref?.id
+    const key = id !== undefined ? String(id) : JSON.stringify(ref)
+    if (seen.has(key)) continue
+    seen.add(key)
+    out.push(ref)
+  }
+  return out
+}
+
+export function fileNameForRef(ref) {
+  const name = String(ref?.name || '').trim()
+  if (name) return name.replace(/[^\w.\- ]/g, '_').slice(0, 120) || 'image.png'
+  const mt = String(ref?.mediaType || '').toLowerCase()
+  if (mt === 'image/jpeg' || mt === 'image/jpg') return 'image.jpg'
+  if (mt === 'image/webp') return 'image.webp'
+  if (mt === 'image/gif') return 'image.gif'
+  return 'image.png'
+}
+
+export async function readAttachmentBytes(ctx, ref) {
+  const stored = await ctx.attachments.readImage(ref)
+  return {
+    bytes: stored.data,
+    mime: ref.mediaType || stored.ref?.mediaType || 'image/png',
+    kind: 'photo',
+    name: fileNameForRef(ref),
+  }
+}
+
+export async function fetchInternalImage(baseUrl, path, signal) {
+  const url = new URL(path, baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`)
+  const res = await fetch(url, { signal })
+  if (!res.ok) throw new Error(`image fetch HTTP ${res.status}`)
+  const bytes = new Uint8Array(await res.arrayBuffer())
+  const mime = res.headers.get('content-type') || 'image/png'
+  const fromQuery = url.searchParams.get('id') || url.searchParams.get('name')
+  const name = fromQuery ? `image-${fromQuery.slice(0, 32)}.png` : 'image.png'
+  return { bytes, mime, kind: 'photo', name }
+}
+
+const DEFAULT_MAX_OUTBOUND_FILES = 10
+
+/** Build Telegram-ready files from assistant image blocks and inline plugin URLs. */
+export async function buildOutboundFiles(ctx, baseUrl, collector, opts = {}) {
+  const { signal, logger, maxFiles = DEFAULT_MAX_OUTBOUND_FILES } = opts
+  const files = []
+  const refs = dedupeAttachmentRefs(collector.images)
+  for (const ref of refs) {
+    if (files.length >= maxFiles) break
+    if (signal?.aborted) break
+    try {
+      files.push(await readAttachmentBytes(ctx, ref))
+    } catch (e) {
+      logger?.warn?.(`outbound image: ${e.message}`)
+    }
+  }
+  const urls = [...new Set(extractImageUrls(collector.parts.join('\n')))]
+  for (const path of urls) {
+    if (files.length >= maxFiles) break
+    if (signal?.aborted) break
+    try {
+      files.push(await fetchInternalImage(baseUrl, path, signal))
+    } catch (e) {
+      logger?.warn?.(`outbound url image: ${e.message}`)
+    }
+  }
+  return files
+}

package/lib/photos.js

@@ -0,0 +1,30 @@
+import { readFile } from 'node:fs/promises'
+
+/**
+ * Persist an inbound photo for the agent. dsh-vision-bridge rewrites image blocks
+ * for text-only models at agent/pre-step and llm/stream.
+ */
+export async function attachInboundPhoto(ctx, att, opts = {}) {
+  const { signal, maxBytes = 20 * 1024 * 1024 } = opts
+  if (signal?.aborted) throw new DOMException('Aborted', 'AbortError')
+  const bytes = new Uint8Array(await readFile(att.path))
+  if (signal?.aborted) throw new DOMException('Aborted', 'AbortError')
+  if (maxBytes > 0 && bytes.length > maxBytes) {
+    throw new Error(`image too large (${bytes.length} bytes, max ${maxBytes})`)
+  }
+  const ref = await ctx.attachments.saveImage({
+    data: bytes,
+    mediaType: att.mime || 'image/jpeg',
+    ...(att.name ? { name: att.name } : {}),
+  })
+  return { ref, byteLength: bytes.length }
+}
+
+/** Text hint when the user sent photo(s) without a caption. */
+export function photoOnlyHint(attachments, userText) {
+  if (String(userText || '').trim()) return ''
+  const photos = attachments.filter((a) => a.kind === 'photo')
+  if (!photos.length) return ''
+  if (photos.length === 1) return '[Пользователь отправил фото]'
+  return `[Пользователь отправил ${photos.length} фото]`
+}

package/lib/text.js

@@ -0,0 +1,22 @@
+export function splitText(text, maxLen) {
+  const raw = String(text ?? '')
+  if (raw.length <= maxLen) return [raw]
+  const chunks = []
+  let rest = raw
+  while (rest.length > maxLen) {
+    let cut = rest.lastIndexOf('\n', maxLen)
+    if (cut < maxLen / 2) cut = rest.lastIndexOf(' ', maxLen)
+    if (cut < maxLen / 2) cut = maxLen
+    chunks.push(rest.slice(0, cut).trim())
+    rest = rest.slice(cut).trimStart()
+  }
+  if (rest.length > 0) chunks.push(rest)
+  return chunks
+}
+
+export function assistantText(message) {
+  return (message?.content || [])
+    .filter((block) => block.type === 'text')
+    .map((block) => block.text)
+    .join('')
+}

package/lib/topics.js

@@ -0,0 +1,27 @@
+/** Forum topic / thread helpers (Telegram message_thread_id). */
+
+export function normalizeThreadId(threadId) {
+  const n = Number(threadId)
+  if (!Number.isFinite(n) || n <= 0) return 0
+  return Math.trunc(n)
+}
+
+/** Stable session key: one agent per platform+chat+topic. */
+export function chatKey(platform, chatId, threadId = 0) {
+  return `${platform}:${chatId}:${normalizeThreadId(threadId)}`
+}
+
+export function parseChatKey(key) {
+  const parts = String(key || '').split(':')
+  if (parts.length < 2) return null
+  const platform = parts[0]
+  const chatId = parts[1]
+  const threadId = parts.length >= 3 ? normalizeThreadId(parts[2]) : 0
+  return { platform, chatId, threadId }
+}
+
+/** Extra Telegram API fields for forum topic replies. */
+export function telegramThreadParams(threadId) {
+  const tid = normalizeThreadId(threadId)
+  return tid > 0 ? { message_thread_id: tid } : {}
+}

package/lib/tts.js

@@ -0,0 +1,40 @@
+/** Prepare agent text for dsh-tts and map audio to Telegram voice messages. */
+
+export const DEFAULT_TTS_MAX_CHARS = 4000
+
+export function stripMarkdownForSpeech(text) {
+  return String(text || '')
+    .replace(/```[\s\S]*?```/g, ' ')
+    .replace(/`[^`]+`/g, ' ')
+    .replace(/!\[[^\]]*\]\([^)]+\)/g, ' ')
+    .replace(/\[([^\]]+)\]\([^)]+\)/g, '$1')
+    .replace(/https?:\/\/\S+/g, ' ')
+    .replace(/[#*_~]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim()
+}
+
+export function prepareTtsText(answer, maxChars = DEFAULT_TTS_MAX_CHARS) {
+  const stripped = stripMarkdownForSpeech(answer)
+  if (!stripped || stripped.length < 2) return ''
+  const limit = Math.max(1, Number(maxChars) || DEFAULT_TTS_MAX_CHARS)
+  return stripped.slice(0, limit)
+}
+
+export function voiceFileNameForMime(mime) {
+  const m = String(mime || '').toLowerCase()
+  if (m.includes('ogg') || m.includes('opus')) return 'reply.ogg'
+  if (m.includes('mpeg') || m.includes('mp3')) return 'reply.mp3'
+  if (m.includes('wav')) return 'reply.wav'
+  return 'reply.dat'
+}
+
+export function voiceReplyFile(spoken) {
+  const mime = spoken?.mime || 'audio/mpeg'
+  return {
+    bytes: spoken.audio,
+    mime,
+    kind: 'voice',
+    name: voiceFileNameForMime(mime),
+  }
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@goodandready/dsh-messenger-gateway",
+  "version": "0.1.0",
+  "description": "Messenger gateway for DeepSeek Harness: Telegram transport (0.1.0 scope). Discord planned.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./package.json": "./package.json",
+    "./cordis.patch.yml": "./cordis.patch.yml"
+  },
+  "files": [
+    "lib/",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE",
+    "docs/"
+  ],
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "telegram",
+    "discord",
+    "messenger",
+    "deepseek-harness"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GooDAnDReaDY/dsh-messenger-gateway.git"
+  },
+  "homepage": "https://github.com/GooDAnDReaDY/dsh-messenger-gateway",
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale",
+        "@deepseek-ai/dsh-client-ui-slots",
+        "@deepseek-ai/dsh-client-ui-settings"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-llm": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-session": "^0.1.0-rc.6",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}