@goodandready/dsh-messenger-gateway 0.1.0

package/lib/gateway.js

@@ -0,0 +1,321 @@
+import { readFile } from 'node:fs/promises'
+import { randomUUID } from 'node:crypto'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { installModelSelection } from '@deepseek-ai/dsh-agent'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import createAdapters from './adapters/index.js'
+import { transcribeVoice, speakText } from './integrations.js'
+import { attachInboundPhoto, photoOnlyHint } from './photos.js'
+import { formatInboundDocument, documentOnlyHint } from './documents.js'
+import { collectAssistantParts, buildOutboundFiles, stripImageUrls } from './outbound.js'
+import { assistantText, splitText } from './text.js'
+import { chatKey } from './topics.js'
+import { prepareTtsText, voiceReplyFile } from './tts.js'
+import {
+  makeAskToken, buildInlineKeyboard, indexCallbacks, releaseCallbacks,
+  parseCallbackData, targetMatchesAsk, rejectPendingAsk, REMOVE_KEYBOARD,
+} from './ask.js'
+
+const PLUGIN = 'dsh-messenger-gateway'
+
+export class Gateway {
+  constructor(ctx, config) {
+    this.ctx = ctx
+    this.config = config
+    this.chats = new Map()
+    this.pending = new Map()
+    this.pendingAsks = new Map()
+    this.adapters = new Map()
+    this.adapterList = []
+    this.disposeListener = undefined
+    this.idleTimer = undefined
+    this.callbackIndex = new Map()
+  }
+
+  baseUrl() {
+    const raw = String(this.config.internalBaseURL || '').trim()
+    return raw || 'http://127.0.0.1:3080'
+  }
+
+  async start() {
+    this.disposeListener = this.ctx.on('session/event', (session, event) => {
+      const collector = this.pending.get(session.id)
+      if (!collector) return
+      if (event.type === 'assistant/message') {
+        const msg = event.data.message
+        const text = assistantText(msg)
+        if (text) collector.parts.push(text)
+        const extra = collectAssistantParts(msg)
+        for (const img of extra.images) collector.images.push(img)
+      } else if (event.type === 'turn/end') {
+        collector.reason = event.data.reason
+      }
+    })
+    const adapters = createAdapters({
+      config: this.config,
+      onMessage: (input) => this.handleMessage(input),
+      onCallback: (cb) => this.handleCallback(cb),
+      logger: this.ctx.logger,
+    })
+    for (const adapter of adapters) {
+      try {
+        await adapter.start()
+        this.adapterList.push(adapter)
+        this.adapters.set(adapter.name, adapter)
+        this.ctx.logger?.info?.(`dsh-messenger-gateway: ${adapter.name} started`)
+      } catch (err) {
+        this.ctx.logger?.warn?.(`dsh-messenger-gateway: ${adapter.name}: ${err.message}`)
+      }
+    }
+    const idleMs = Number(this.config.agent?.idleTimeoutMs) || 0
+    if (idleMs > 0) {
+      this.idleTimer = setInterval(() => this.reapIdle(), Math.min(idleMs, 60_000))
+      this.idleTimer.unref?.()
+    }
+  }
+
+  stop() {
+    if (this.disposeListener) this.disposeListener()
+    if (this.idleTimer) clearInterval(this.idleTimer)
+    for (const a of this.adapterList) { try { a.stop() } catch {} }
+    this.adapterList = []
+    this.adapters.clear()
+    for (const chat of this.chats.values()) chat.dispose().catch(() => {})
+    this.chats.clear()
+    for (const pending of this.pendingAsks.values()) {
+      releaseCallbacks(this.callbackIndex, pending.callbackKeys)
+      rejectPendingAsk(pending, new Error('gateway stopped'))
+    }
+    this.pending.clear()
+    this.pendingAsks.clear()
+    this.callbackIndex.clear()
+  }
+
+  getAdapter(platform) {
+    return this.adapters.get(platform)
+  }
+
+  async messengerSend(target, payload) {
+    const adapter = this.getAdapter(target.platform)
+    if (!adapter?.sendTo) throw new Error(`adapter ${target.platform} unavailable`)
+    await adapter.sendTo(target.chatId, payload, { threadId: target.threadId })
+  }
+
+  async messengerAsk(target, payload, timeoutMs = 300_000) {
+    const adapter = this.getAdapter(target.platform)
+    if (!adapter) throw new Error(`adapter ${target.platform} unavailable`)
+    const token = makeAskToken()
+    const { replyMarkup, callbackKeys } = buildInlineKeyboard(token, payload.buttons || [])
+    indexCallbacks(this.callbackIndex, callbackKeys, token)
+    await adapter.sendTo(target.chatId, { text: payload.text, replyMarkup }, { threadId: target.threadId })
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        const pending = this.pendingAsks.get(token)
+        this.pendingAsks.delete(token)
+        releaseCallbacks(this.callbackIndex, callbackKeys)
+        reject(new Error('messenger.ask timed out'))
+      }, timeoutMs)
+      timer.unref?.()
+      this.pendingAsks.set(token, { resolve, reject, timer, target, callbackKeys })
+    })
+  }
+
+  async messengerProgress(target, payload) {
+    await this.messengerSend(target, { text: payload.text })
+  }
+
+  async handleCallback(cb) {
+    const indexed = this.callbackIndex.get(cb.data)
+    const { token, buttonId } = parseCallbackData(cb.data)
+    const askToken = indexed || token
+    if (askToken && this.pendingAsks.has(askToken)) {
+      const pending = this.pendingAsks.get(askToken)
+      if (!targetMatchesAsk(pending, cb)) {
+        await cb.answer('Кнопка для другого чата')
+        return
+      }
+      clearTimeout(pending.timer)
+      this.pendingAsks.delete(askToken)
+      releaseCallbacks(this.callbackIndex, pending.callbackKeys)
+      await cb.answer('OK')
+      try {
+        await cb.editMessage(cb.message?.text || 'Выбрано', REMOVE_KEYBOARD)
+      } catch {}
+      pending.resolve({ buttonId, data: cb.data })
+      return
+    }
+    await cb.answer()
+  }
+
+  async handleMessage(input) {
+    const { platform, chatId, userId, threadId = 0, text, attachments = [], replyText } = input
+    const key = chatKey(platform, chatId, threadId)
+    const body = String(text || '').trim()
+    const hasMedia = attachments.length > 0
+    if (!body && !hasMedia) return
+    if (body.startsWith('/')) { await this.handleCommand(key, body, input); return }
+    const chat = await this.getOrCreateChat(key)
+    if (chat.abort) chat.abort.abort()
+    chat.abort = new AbortController()
+    const run = chat.busy.then(() => this.runTurn(chat, input, chat.abort.signal))
+    chat.busy = run.catch(() => {})
+    await run
+  }
+
+  async handleCommand(key, text, input) {
+    const cmd = text.split(/\s+/)[0].toLowerCase()
+    const { reply, userId } = input
+    if (cmd === '/start') return reply('Шлюз подключён. Пишите сообщение агенту. /help — команды.')
+    if (cmd === '/help') return reply(['Команды:', '/help — справка', '/new — новая сессия', '/whoami — ваш id', '/stop — прервать текущий ответ'].join('\n'))
+    if (cmd === '/new') {
+      const chat = this.chats.get(key)
+      if (chat) { if (chat.abort) chat.abort.abort(); this.chats.delete(key); await chat.dispose(); return reply('Сессия сброшена.') }
+      return reply('Активной сессии нет.')
+    }
+    if (cmd === '/whoami') return reply(`Ваш id: ${userId}`)
+    if (cmd === '/stop') {
+      const chat = this.chats.get(key)
+      if (chat?.abort) { chat.abort.abort(); return reply('Прерывание отправлено.') }
+      return reply('Нечего прерывать.')
+    }
+    return reply(`Неизвестная команда ${cmd}. /help`)
+  }
+
+  async getOrCreateChat(key) {
+    let chat = this.chats.get(key)
+    if (!chat) { chat = await this.createChat(key); this.chats.set(key, chat) }
+    chat.lastUsed = Date.now()
+    return chat
+  }
+
+  async createChat(key) {
+    const selection = this.ctx.get('agentDefaultModel')?.currentSelection?.()
+    if (!selection) throw new Error('Выберите модель в Settings → Models')
+    const agentCfg = this.config.agent || {}
+    const provider = agentCfg.provider || selection.provider
+    const model = agentCfg.model || selection.model
+    const cwd = agentCfg.cwd || process.cwd()
+    const handle = await this.ctx.agents.create({
+      sessionId: SessionId(`msgw-${randomUUID()}`),
+      meta: { cwd },
+      agentOptions: { provider, model },
+      setup: (agentCtx) => installModelSelection(agentCtx, { current: { provider, model }, assembled: undefined }),
+    })
+    await handle.agent.whenIdle()
+    return { key, agent: handle.agent, dispose: handle.dispose, busy: Promise.resolve(), lastUsed: Date.now(), abort: undefined }
+  }
+
+  async buildUserContent(input, signal) {
+    const { text, attachments = [], replyText } = input
+    const parts = []
+    if (this.config.agent?.instructionPrefix) parts.push(String(this.config.agent.instructionPrefix))
+    if (replyText?.trim()) parts.push(`[Ответ на сообщение: ${replyText.trim()}]`)
+    const blocks = []
+    for (const att of attachments) {
+      if (att.kind === 'photo') {
+        try {
+          const { ref } = await attachInboundPhoto(this.ctx, att, {
+            signal,
+            maxBytes: Number(this.config.media?.maxImageBytes) || 20 * 1024 * 1024,
+          })
+          blocks.push({ type: 'image', attachment: ref })
+        } catch (err) {
+          if (signal?.aborted) throw err
+          const msg = err instanceof Error ? err.message : String(err)
+          parts.push(`[Не удалось приложить изображение: ${msg}]`)
+        }
+      } else if (att.kind === 'voice' || att.kind === 'audio') {
+        try {
+          const bytes = new Uint8Array(await readFile(att.path))
+          const transcript = await transcribeVoice(this.baseUrl(), bytes, att.mime || 'audio/ogg', 'message', signal)
+          parts.push(transcript ? `[Голосовое сообщение, расшифровка: ${transcript}]` : '[Голосовое сообщение (не удалось распознать)]')
+        } catch (err) {
+          if (signal?.aborted) throw err
+          const msg = err instanceof Error ? err.message : String(err)
+          this.ctx.logger?.warn?.(`voice: ${msg}`)
+          parts.push(`[Голосовое сообщение (dsh-voice недоступен: ${msg})]`)
+        }
+      } else if (att.kind === 'document' || att.kind === 'video') {
+        parts.push(formatInboundDocument(att))
+      } else {
+        parts.push(`[Файл: ${att.path}${att.name ? ` (${att.name})` : ''}]`)
+      }
+    }
+    const photoHint = photoOnlyHint(attachments, text)
+    if (photoHint) parts.push(photoHint)
+    if (text?.trim()) parts.push(text.trim())
+    const textBlock = parts.filter(Boolean).join('\n\n')
+    if (textBlock) blocks.unshift({ type: 'text', text: textBlock })
+    if (!blocks.length) blocks.push({ type: 'text', text: '(пустое сообщение)' })
+    return blocks
+  }
+
+  async runTurn(chat, input, signal) {
+    const { reply, typing } = input
+    const sessionId = chat.agent.session.id
+    const collector = { parts: [], images: [], reason: undefined }
+    this.pending.set(sessionId, collector)
+    try {
+      if (signal.aborted) return
+      if (typing) await typing()
+      const content = await this.buildUserContent(input, signal)
+      chat.agent.followup(createUserMessage({
+        content,
+        source: { kind: 'plugin', plugin: PLUGIN, form: 'relay' },
+      }))
+      await chat.agent.whenIdle()
+      if (signal.aborted) return
+      await this.ctx.sessions.flush(chat.agent.session)
+      const answer = stripImageUrls(collector.parts.join('\n\n'))
+      if (collector.reason?.kind === 'error') {
+        const err = collector.reason.error
+        return reply(`Ошибка агента: ${err?.code || 'error'}: ${err?.message || 'unknown'}`)
+      }
+      const files = await buildOutboundFiles(this.ctx, this.baseUrl(), collector, { signal, logger: this.ctx.logger })
+      if (!answer && !files.length) return reply('(нет ответа)')
+      const maxLen = Number(this.config.agent?.maxMessageLength) || 4000
+      const chunks = answer ? splitText(answer, maxLen) : ['']
+      for (let i = 0; i < chunks.length; i++) {
+        await reply({ text: chunks[i] || undefined, files: i === 0 ? files : [] })
+      }
+      if (this.config.tts?.enabled && !signal.aborted) {
+        const ttsText = prepareTtsText(answer, this.config.tts?.maxChars)
+        if (ttsText) {
+          try {
+            const spoken = await speakText(this.baseUrl(), ttsText, signal)
+            if (!signal.aborted) await reply({ files: [voiceReplyFile(spoken)] })
+          } catch (e) {
+            if (!signal?.aborted) this.ctx.logger?.warn?.(`tts: ${e.message}`)
+          }
+        }
+      }
+    } catch (err) {
+      if (!signal?.aborted) {
+        try { await reply(`Сбой: ${err.message}`) } catch {}
+      }
+    } finally {
+      this.pending.delete(sessionId)
+    }
+  }
+
+  reapIdle() {
+    const timeout = Number(this.config.agent?.idleTimeoutMs) || 0
+    if (timeout <= 0) return
+    const now = Date.now()
+    for (const [key, chat] of this.chats) {
+      if (now - chat.lastUsed > timeout) { this.chats.delete(key); chat.dispose().catch(() => {}) }
+    }
+  }
+
+  get messenger() {
+    return {
+      adapters: () => [...this.adapters.keys()],
+      activeChats: () => this.chats.size,
+      send: (target, payload) => this.messengerSend(target, payload),
+      ask: (target, payload, timeoutMs) => this.messengerAsk(target, payload, timeoutMs),
+      progress: (target, payload) => this.messengerProgress(target, payload),
+    }
+  }
+}

package/lib/http.js

@@ -0,0 +1,18 @@
+export async function readBody(req) {
+  const chunks = []
+  for await (const chunk of req) chunks.push(chunk)
+  return Buffer.concat(chunks)
+}
+
+export function writeJson(res, status, body) {
+  res.statusCode = status
+  res.setHeader('Content-Type', 'application/json; charset=utf-8')
+  res.end(JSON.stringify(body))
+}
+
+export function isTrustedSettingsRequest(req) {
+  const origin = String(req.headers?.origin || '')
+  const host = String(req.headers?.host || '')
+  if (!origin || !host) return false
+  try { return new URL(origin).host === host } catch { return false }
+}

package/lib/index.js

@@ -0,0 +1,174 @@
+import z from '@deepseek-ai/schemastery'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
+import { Gateway } from './gateway.js'
+import { readBody, writeJson, isTrustedSettingsRequest } from './http.js'
+import {
+  createMessengerService, dispatchMessenger, httpStatusForError,
+  messengerApiSchema, parseMessengerBody,
+} from './messenger-api.js'
+
+export const name = 'dsh-messenger-gateway'
+export const inject = ['agentDefaultModel', 'agents', 'sessions', 'loader', 'settings', 'webServer', 'attachments']
+
+export const SETTINGS_NAMESPACE = settingsNamespace('dsh-messenger-gateway')
+
+export const Config = z.object({
+  enabled: z.boolean().default(true),
+  internalBaseURL: z.string().default('http://127.0.0.1:3080'),
+  telegram: z.object({
+    enabled: z.boolean().default(false),
+    botToken: z.string().role('secret').default(''),
+    allowedUserIds: z.array(z.number()).default([]),
+    pollTimeoutSeconds: z.number().default(50),
+    pollIntervalMs: z.number().default(500),
+  }),
+  discord: z.object({
+    enabled: z.boolean().default(false),
+    botToken: z.string().role('secret').default(''),
+  }),
+  media: z.object({
+    cacheDir: z.string().default(''),
+    maxDocBytes: z.number().default(20 * 1024 * 1024),
+    maxTextInjectBytes: z.number().default(100 * 1024),
+    maxImageBytes: z.number().default(20 * 1024 * 1024),
+  }),
+  tts: z.object({
+    enabled: z.boolean().default(false),
+    maxChars: z.number().default(4000),
+  }),
+  agent: z.object({
+    provider: z.string().default(''),
+    model: z.string().default(''),
+    cwd: z.string().default(''),
+    instructionPrefix: z.string().default(''),
+    maxMessageLength: z.number().default(4000),
+    idleTimeoutMs: z.number().default(3_600_000),
+  }),
+})
+
+function resolveConfig(raw) {
+  const cfg = Config(raw)
+  const home = process.env.DSH_HOME || join(homedir(), '.dsh')
+  if (!cfg.media.cacheDir) {
+    cfg.media = { ...cfg.media, cacheDir: join(home, 'messenger-gateway', 'cache') }
+  }
+  return cfg
+}
+
+function publicConfig(cfg) {
+  return {
+    enabled: cfg.enabled,
+    internalBaseURL: cfg.internalBaseURL,
+    telegram: {
+      enabled: cfg.telegram.enabled,
+      allowedUserIds: cfg.telegram.allowedUserIds,
+      pollTimeoutSeconds: cfg.telegram.pollTimeoutSeconds,
+      pollIntervalMs: cfg.telegram.pollIntervalMs,
+      botTokenConfigured: Boolean(String(cfg.telegram.botToken || '').trim()),
+    },
+    discord: { enabled: cfg.discord.enabled, botTokenConfigured: Boolean(String(cfg.discord.botToken || '').trim()) },
+    media: { maxDocBytes: cfg.media.maxDocBytes, maxTextInjectBytes: cfg.media.maxTextInjectBytes, maxImageBytes: cfg.media.maxImageBytes },
+    tts: cfg.tts,
+    agent: cfg.agent,
+  }
+}
+
+function registerMessengerRoute(ctx, getGw, path, action) {
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact', path,
+    handler: async (req, res) => {
+      if (req.method !== 'POST') return writeJson(res, 405, { ok: false, error: 'POST only' })
+      let payload
+      try {
+        payload = parseMessengerBody((await readBody(req)).toString('utf8'))
+      } catch (err) {
+        return writeJson(res, httpStatusForError(err), { ok: false, error: err.message })
+      }
+      try {
+        const out = await dispatchMessenger(getGw(), action, payload)
+        writeJson(res, 200, out)
+      } catch (err) {
+        writeJson(res, httpStatusForError(err), { ok: false, error: err.message })
+      }
+    },
+  }), `dsh-messenger-gateway: ${action}`)
+}
+
+export function apply(ctx, config) {
+  const entry = resolveConfig(structuredClone(config || {}))
+  let gateway
+  let source = () => entry
+  let settingsApi
+
+  const sync = () => {
+    if (gateway) { gateway.stop(); gateway = undefined }
+    const effective = source()
+    if (effective.enabled === false) return
+    gateway = new Gateway(ctx, effective)
+    gateway.start().catch((err) => ctx.logger?.warn?.(`dsh-messenger-gateway: ${err.message}`))
+  }
+
+  if (ctx.settings?.register) {
+    settingsApi = ctx.settings.register(SETTINGS_NAMESPACE, Config, { base: config || {} })
+    source = () => resolveConfig(settingsApi.get() ?? config ?? {})
+    ctx.effect(() => settingsApi.watch(sync), 'dsh-messenger-gateway: settings')
+  }
+
+  const getGw = () => gateway
+
+  ctx.effect(() => ctx.provide('messenger', createMessengerService(getGw)), 'dsh-messenger-gateway: messenger service')
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact', path: '/dsh-messenger-gateway/status',
+    handler: async (req, res) => {
+      if (req.method !== 'GET') return writeJson(res, 405, { ok: false, error: 'GET only' })
+      const gw = getGw()
+      writeJson(res, 200, {
+        ok: true,
+        running: Boolean(gw),
+        adapters: gw?.messenger.adapters() || [],
+        activeChats: gw?.messenger.activeChats() || 0,
+        ttsEnabled: Boolean(source().tts?.enabled),
+        messengerService: 'messenger',
+        config: publicConfig(source()),
+      })
+    },
+  }), 'dsh-messenger-gateway: status')
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact', path: '/dsh-messenger-gateway/messenger',
+    handler: async (req, res) => {
+      if (req.method !== 'GET') return writeJson(res, 405, { ok: false, error: 'GET only' })
+      writeJson(res, 200, { ok: true, schema: messengerApiSchema })
+    },
+  }), 'dsh-messenger-gateway: messenger schema')
+
+  ctx.effect(() => ctx.webServer.register({
+    kind: 'exact', path: '/dsh-messenger-gateway/config',
+    handler: async (req, res) => {
+      if (req.method === 'GET') return writeJson(res, 200, { ok: true, config: publicConfig(source()) })
+      if (req.method !== 'PUT') return writeJson(res, 405, { ok: false, error: 'GET or PUT' })
+      if (!isTrustedSettingsRequest(req)) return writeJson(res, 403, { ok: false, error: 'forbidden' })
+      if (!settingsApi) return writeJson(res, 503, { ok: false, error: 'settings not ready' })
+      let payload
+      try { payload = JSON.parse((await readBody(req)).toString('utf8') || '{}') } catch { return writeJson(res, 400, { ok: false, error: 'invalid json' }) }
+      if (payload && typeof payload.config === 'object') payload = payload.config
+      try {
+        await settingsApi.replace(Config({ ...source(), ...payload }))
+        sync()
+        writeJson(res, 200, { ok: true, config: publicConfig(source()) })
+      } catch (err) {
+        writeJson(res, 400, { ok: false, error: err.message })
+      }
+    },
+  }), 'dsh-messenger-gateway: config')
+
+  registerMessengerRoute(ctx, getGw, '/dsh-messenger-gateway/messenger/send', 'send')
+  registerMessengerRoute(ctx, getGw, '/dsh-messenger-gateway/messenger/progress', 'progress')
+  registerMessengerRoute(ctx, getGw, '/dsh-messenger-gateway/messenger/ask', 'ask')
+
+  ctx.on('dispose', () => { if (gateway) gateway.stop() })
+  sync()
+}

package/lib/integrations.js

@@ -0,0 +1,40 @@
+export function formatApiError(data, status) {
+  const err = data?.error
+  const msg = typeof err === 'string' ? err
+    : (err?.message || err?.code || JSON.stringify(data).slice(0, 200))
+  return `${msg} (HTTP ${status})`
+}
+
+export async function postJson(baseUrl, path, body, signal) {
+  const url = new URL(path, baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`)
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+    signal,
+  })
+  const data = await res.json().catch(() => ({}))
+  if (!res.ok || data.ok === false) {
+    throw new Error(`${path} failed: ${formatApiError(data, res.status)}`)
+  }
+  return data
+}
+
+/** Transcribe audio via dsh-voice message chain (Telegram voice/audio). */
+export async function transcribeVoice(baseUrl, bytes, mimeType, mode = 'message', signal) {
+  const data = await postJson(baseUrl, '/dsh-voice/transcribe', {
+    dataBase64: Buffer.from(bytes).toString('base64'),
+    mimeType: mimeType || 'audio/ogg',
+    mode,
+  }, signal)
+  return String(data.text || '').trim()
+}
+
+export async function speakText(baseUrl, text, signal) {
+  const data = await postJson(baseUrl, '/dsh-tts/speak', { text }, signal)
+  return {
+    audio: Buffer.from(data.audioBase64, 'base64'),
+    mime: data.mime || 'audio/mpeg',
+    provider: data.provider,
+  }
+}

package/lib/media.js

@@ -0,0 +1,68 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import { basename, extname, join } from 'node:path'
+
+export const TELEGRAM_MAX_DOC_BYTES = 20 * 1024 * 1024
+
+export const SUPPORTED_DOCUMENT_TYPES = {
+  '.pdf': 'application/pdf', '.md': 'text/markdown', '.txt': 'text/plain', '.csv': 'text/csv',
+  '.log': 'text/plain', '.json': 'application/json', '.xml': 'application/xml',
+  '.yaml': 'application/yaml', '.yml': 'application/yaml', '.toml': 'application/toml',
+  '.ini': 'text/plain', '.cfg': 'text/plain', '.zip': 'application/zip',
+  '.doc': 'application/msword',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.xls': 'application/vnd.ms-excel',
+  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+  '.ppt': 'application/vnd.ms-powerpoint',
+  '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  '.ts': 'text/plain', '.py': 'text/plain', '.sh': 'text/plain',
+}
+
+export const IMAGE_EXT_TO_MIME = {
+  '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png', '.webp': 'image/webp', '.gif': 'image/gif',
+}
+
+export const VIDEO_EXT_TO_MIME = {
+  '.mp4': 'video/mp4', '.mov': 'video/quicktime', '.webm': 'video/webm',
+}
+
+export function extOf(name, mime) {
+  let ext = name ? extname(name).toLowerCase() : ''
+  const m = String(mime || '').toLowerCase()
+  if (!ext && m) ext = Object.entries(IMAGE_EXT_TO_MIME).find(([, v]) => v === m)?.[0] || ''
+  return ext
+}
+
+export function classifyDocument(ext, mime) {
+  const m = String(mime || '').toLowerCase()
+  if (IMAGE_EXT_TO_MIME[ext] || m.startsWith('image/')) return 'image'
+  if (VIDEO_EXT_TO_MIME[ext] || Object.values(VIDEO_EXT_TO_MIME).includes(m)) return 'video'
+  if (SUPPORTED_DOCUMENT_TYPES[ext]) return 'doc'
+  return 'unsupported'
+}
+
+export function mediaKindOf(path) {
+  const ext = extname(path).toLowerCase()
+  if (IMAGE_EXT_TO_MIME[ext]) return 'photo'
+  if (['.ogg', '.opus', '.oga'].includes(ext)) return 'voice'
+  if (['.mp3', '.m4a', '.wav', '.flac'].includes(ext)) return 'audio'
+  return 'document'
+}
+
+export function safeName(name) {
+  return String(name || 'file').replace(/[^\w.\- ]/g, '_').slice(0, 120) || 'file'
+}
+
+export function saveToCache(cacheDir, name, bytes) {
+  mkdirSync(cacheDir, { recursive: true })
+  const path = join(cacheDir, name)
+  writeFileSync(path, bytes)
+  return path
+}
+
+export function cacheName(prefix, ext, name) {
+  const base = `${prefix}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`
+  const display = name ? safeName(name) : ''
+  return display ? `${base}-${display}${ext || ''}` : `${base}${ext || ''}`
+}
+
+export { basename }