polygram 0.8.0 → 0.9.0-rc.2

package/lib/handlers/poll.js

@@ -0,0 +1,140 @@
+/**
+ * Manual long-poll loop for Telegram updates + a watchdog for
+ * stalled poll loops.
+ *
+ * Why manual instead of grammy's built-in `bot.start()`: we need
+ * to (a) restore the polling offset from the DB on boot so a
+ * restart doesn't re-process the backlog Telegram accumulated
+ * during downtime, (b) persist the offset after each batch so a
+ * crash mid-batch only risks re-processing the unacked updates,
+ * (c) drive a stall watchdog that logs to events when the loop
+ * hasn't ticked in 2 minutes (network flap / Telegram 5xx).
+ *
+ * Long-poll discipline: Telegram holds the connection up to 25s
+ * waiting for updates. When something arrives it returns
+ * immediately; empty windows cost ~0 local CPU. Median inbound
+ * latency drops vs short-poll-every-1s.
+ *
+ * Allowed update types: message, edited_message, callback_query.
+ * Polygram doesn't process channel posts, polls, etc. — gating
+ * here trims server load + simplifies the dispatch.
+ */
+
+'use strict';
+
+const POLL_STALL_MS = 120_000;
+
+function createPollLoop({
+  db,
+  dbWrite,
+  config,
+  botName,
+  isWellFormedMessage,
+  getTopicName,
+  logger = console,
+} = {}) {
+  async function pollBot(bot) {
+    await bot.init();
+    bot._setBotUsername(bot.botInfo.username);
+    logger.log?.(`[${botName}] Bot @${bot.botInfo.username} ready`);
+
+    await bot.api.deleteWebhook();
+
+    // Restore polling offset from DB so a restart doesn't re-process
+    // the backlog Telegram accumulated while we were down.
+    let offset = 0;
+    try {
+      const saved = db?.getPollingOffset?.(botName);
+      if (saved && saved > 0) {
+        offset = saved + 1;
+        logger.log?.(`[${botName}] resuming polling from update_id ${saved}`);
+      }
+    } catch (err) {
+      logger.error?.(`[${botName}] getPollingOffset failed: ${err.message}`);
+    }
+    let running = true;
+    bot._lastPollTs = Date.now();
+    bot._stop = () => { running = false; };
+
+    while (running) {
+      try {
+        const updates = await bot.api.getUpdates({
+          offset,
+          timeout: 25,
+          allowed_updates: ['message', 'edited_message', 'callback_query'],
+        });
+        bot._lastPollTs = Date.now();
+
+        for (const update of updates) {
+          offset = update.update_id + 1;
+          if (update.message && isWellFormedMessage(update.message)) {
+            const m = update.message;
+            const chatId = m.chat.id.toString();
+            const chatConfig = config.chats[chatId];
+            const threadId = m.message_thread_id?.toString();
+            const topicName = threadId
+              ? (chatConfig ? getTopicName(chatConfig, threadId) : threadId)
+              : null;
+            const chatLabel = chatConfig?.name || chatId;
+            const label = topicName ? `${chatLabel}/${topicName}` : chatLabel;
+            logger.log?.(`[${botName}] ← ${label}: ${(m.text || m.caption || '(media)').slice(0, 60)}`);
+          }
+          try {
+            await bot.handleUpdate(update);
+          } catch (err) {
+            logger.error?.(`[${botName}] Handler error: ${err.message}`);
+          }
+        }
+        // Persist offset after batch dispatch — only on non-empty
+        // batches to avoid churning the row on every 25s idle poll.
+        if (updates.length > 0) {
+          dbWrite(() => db.savePollingOffset(botName, updates[updates.length - 1].update_id),
+            'save polling offset');
+        }
+        // No sleep on the success path: long-poll already blocks
+        // up to 25s when idle.
+      } catch (err) {
+        if (!running) break;
+        if (err.error_code === 409) {
+          logger.log?.(`[${botName}] 409, waiting 3s...`);
+          await new Promise((r) => setTimeout(r, 3000));
+        } else {
+          logger.error?.(`[${botName}] Poll error: ${err.message}`);
+          await new Promise((r) => setTimeout(r, 3000));
+        }
+      }
+    }
+  }
+
+  /**
+   * Watchdog: if the poll loop hasn't ticked in POLL_STALL_MS, log
+   * an event so external monitoring (or `events` queries) can see
+   * it. We don't exit here — launchd restarts the process on
+   * death, but a stalled poll is usually transient.
+   */
+  function startPollWatchdog(bot, { logEvent } = {}) {
+    let stalled = false;
+    return setInterval(() => {
+      const now = Date.now();
+      const age = now - (bot._lastPollTs || 0);
+      if (age > POLL_STALL_MS) {
+        if (!stalled) {
+          logger.error?.(`[${botName}] poll-stalled: no tick in ${Math.round(age / 1000)}s`);
+          if (logEvent) logEvent('poll-stalled', { bot: botName, stall_ms: age });
+          stalled = true;
+        }
+      } else if (stalled) {
+        logger.log?.(`[${botName}] poll-recovered after stall`);
+        if (logEvent) logEvent('poll-recovered', { bot: botName });
+        stalled = false;
+      }
+    }, 30_000);
+  }
+
+  return { pollBot, startPollWatchdog };
+}
+
+module.exports = {
+  createPollLoop,
+  POLL_STALL_MS,
+};

package/lib/handlers/record-inbound.js

@@ -0,0 +1,88 @@
+/**
+ * Record an inbound Telegram message + its attachments to SQLite.
+ *
+ * Atomic: message + N-attachment writes wrapped in
+ * `db.raw.transaction` so a crash mid-write can't leave a message
+ * row with zero (or partial) attachment rows that boot-replay
+ * would silently treat as "no media."
+ *
+ * Edit-safe: Telegram fires recordInbound again for edited_message
+ * events (same chat_id + msg_id). If attachments already exist,
+ * we skip the attachment-insert pass — re-inserting would duplicate
+ * rows AND reset download_status back to 'pending', losing the
+ * local_path we already fetched.
+ *
+ * Best-effort: dbWrite swallows errors; recordInbound never
+ * throws. Late-arriving inbounds during shutdown (after db.raw.close())
+ * are explicitly short-circuited at the top.
+ */
+
+'use strict';
+
+function createRecordInbound({
+  db,
+  dbWrite,
+  config,
+  botName,
+  extractAttachments,
+} = {}) {
+  return function recordInbound(msg) {
+    if (!db) return;
+    const chatId = msg.chat.id.toString();
+    const threadId = msg.message_thread_id?.toString() || null;
+    const user = msg.from?.first_name || msg.from?.username || null;
+    const attachments = extractAttachments(msg);
+    const chatConfig = config.chats[chatId];
+    const ts = (msg.date || Math.floor(Date.now() / 1000)) * 1000;
+
+    // Atomic message + attachments write. db.raw.transaction
+    // collapses N+1 fsyncs into one commit — perf win for media
+    // groups (7-attachment album: 8 sync writes → 1).
+    const writeInbound = db.raw.transaction(() => {
+      db.insertMessage({
+        chat_id: chatId,
+        thread_id: threadId,
+        msg_id: msg.message_id,
+        user,
+        user_id: msg.from?.id || null,
+        text: msg.text || msg.caption || '',
+        reply_to_id: msg.reply_to_message?.message_id || null,
+        direction: 'in',
+        source: 'polygram',
+        bot_name: botName,
+        model: chatConfig?.model || null,
+        effort: chatConfig?.effort || null,
+        ts,
+      });
+
+      if (!attachments.length) return;
+      // Look up the just-inserted message row id so attachments
+      // can FK to it. lastInsertRowid is unreliable across the
+      // upsert path; explicit lookup is cheap and always correct.
+      const messageId = db.getInboundMessageId({ chat_id: chatId, msg_id: msg.message_id });
+      if (!messageId) return;
+      // Edit-safety: skip if attachments already persisted.
+      if (db.getAttachmentsByMessage(messageId).length > 0) return;
+      for (const att of attachments) {
+        db.insertAttachment({
+          message_id: messageId,
+          chat_id: chatId,
+          msg_id: msg.message_id,
+          thread_id: threadId,
+          bot_name: botName,
+          file_id: att.file_id,
+          file_unique_id: att.file_unique_id,
+          kind: att.kind,
+          name: att.name,
+          mime_type: att.mime_type,
+          size_bytes: att.size,
+          ts,
+        });
+      }
+    });
+
+    dbWrite(() => writeInbound(), `insert inbound ${chatId}/${msg.message_id}`);
+  };
+}
+
+module.exports = { createRecordInbound };

package/lib/handlers/slash-commands.js

@@ -0,0 +1,319 @@
+/**
+ * Slash command dispatcher.
+ *
+ * Polygram supports these chat commands (gated on
+ * config.bot.allowConfigCommands except /pair which is its own auth):
+ *
+ *   /context         — on-demand SDK context-usage report
+ *   /compact [hint]  — manual SDK compaction with optional preserve hint
+ *   /reload          — close+respawn Query, preserves session_id
+ *   /new, /reset     — fresh session (resetSession clears session_id)
+ *   /model X         — switch model (X ∈ opus|sonnet|haiku)
+ *   /effort X        — switch effort (X ∈ low|medium|high|xhigh|max)
+ *   /pair-code …     — admin: issue a pairing code
+ *   /pairings        — admin: list active pairings
+ *   /unpair <user>   — admin: revoke pairings for a user
+ *   /pair <code>     — claim a pairing code (open, code is the auth)
+ *
+ * Returns true when the message was a recognized command (caller
+ * short-circuits handleMessage); false otherwise.
+ *
+ * Why a single factory: each handler shares the same runtime
+ * context (config, db, dbWrite, pm, pairings, sendReply, logEvent,
+ * etc.) and they're naturally co-located by command-style anyway.
+ * Splitting into one-file-per-command would 5× the wiring without
+ * gain.
+ */
+
+'use strict';
+
+function createSlashCommands({
+  config,
+  db,
+  dbWrite,
+  pm,
+  pairings,
+  parsePairingTtl,
+  contextHintShown,
+  formatContextReply,
+  getClaudeSessionId,
+  getOrSpawnForChat,
+  parsePairCodeArgs,
+  modelVersionsDesc,
+  botName,
+  logEvent,
+  logger = console,
+} = {}) {
+
+  return async function dispatchSlashCommand(ctx) {
+    const {
+      text, sessionKey, chatId, threadIdStr, chatConfig,
+      cmdUser, cmdUserId, label, sendReply,
+    } = ctx;
+    const botAllowsCommands = !!config.bot?.allowConfigCommands;
+
+    // /context
+    if (botAllowsCommands && text === '/context') {
+      const entry = pm.get(sessionKey);
+      const q = entry?.query;
+      if (!q || typeof q.getContextUsage !== 'function') {
+        await sendReply('📚 No active session yet — send a message first, then /context.');
+        return true;
+      }
+      try {
+        const u = await q.getContextUsage();
+        await sendReply(formatContextReply(u));
+      } catch (err) {
+        logger.error?.(`[${label}] /context failed: ${err.message}`);
+        await sendReply(`📚 Couldn't fetch context info: ${err.message}`);
+      }
+      return true;
+    }
+
+    // /compact [hint] — manual SDK compaction. Push the literal
+    // "/compact ..." into the input controller; SDK parses leading
+    // "/" as a slash command and triggers compaction. If session
+    // was LRU-evicted but DB has a saved session_id, auto-spawn
+    // with --resume so /compact has something to work with.
+    if (botAllowsCommands && text.startsWith('/compact')) {
+      let entry = pm.get(sessionKey);
+      if (!entry) {
+        const savedSessionId = getClaudeSessionId(db, sessionKey);
+        if (!savedSessionId) {
+          await sendReply('🗜️ No conversation to compact yet. Send a message first, then /compact.');
+          return true;
+        }
+        try {
+          entry = await getOrSpawnForChat(sessionKey);
+        } catch (err) {
+          logger.error?.(`[${label}] /compact spawn-resume: ${err.message}`);
+          await sendReply(`🗜️ Couldn't load session for compaction: ${err.message}`);
+          return true;
+        }
+        if (!entry) {
+          await sendReply('🗜️ Session not loadable (config missing).');
+          return true;
+        }
+        logEvent('compact-spawn-resumed', {
+          chat_id: chatId, thread_id: threadIdStr, session_key: sessionKey,
+          resumed_session_id: savedSessionId,
+        });
+      }
+      if (!entry?.inputController?.push) {
+        await sendReply('🗜️ Session not ready for /compact (no input controller).');
+        return true;
+      }
+      try {
+        entry.inputController.push({
+          type: 'user',
+          message: { role: 'user', content: text },
+          parent_tool_use_id: null,
+        });
+        logEvent('compact-command', {
+          chat_id: chatId, thread_id: threadIdStr, session_key: sessionKey,
+          text_len: text.length,
+          // rc.65: store full text so boot-time orphan recovery can
+          // silently re-push after a deploy interrupted compaction.
+          text,
+          user: cmdUser, user_id: cmdUserId,
+        });
+        const hasHint = text.length > '/compact'.length + 1;
+        await sendReply(hasHint ? '🗜️ Compacting with your hint…' : '🗜️ Compacting…');
+      } catch (err) {
+        logger.error?.(`[${label}] /compact push: ${err.message}`);
+        await sendReply(`🗜️ Couldn't trigger compact: ${err.message}`);
+      }
+      return true;
+    }
+
+    // /reload — close+respawn Query while PRESERVING session_id.
+    // Difference vs /new:
+    //   /new    → resetSession clears session_id → fresh conversation
+    //   /reload → kill closes Query, session_id preserved → same
+    //              conversation continues with fresh agent/skill code
+    if (botAllowsCommands && text === '/reload') {
+      if (pm.has(sessionKey)) {
+        try { await pm.kill(sessionKey); }
+        catch (err) { logger.error?.(`[${label}] kill on /reload: ${err.message}`); }
+      }
+      logEvent('session-reload-command', {
+        chat_id: chatId, command: text,
+        user: cmdUser, user_id: cmdUserId,
+      });
+      await sendReply('🔄 Reloaded. Next message picks up the conversation with fresh skills/agents.');
+      return true;
+    }
+
+    // /new + /reset — fresh session
+    if (botAllowsCommands && (text === '/new' || text === '/reset')) {
+      let drained = 0;
+      try {
+        const r = await pm.resetSession(sessionKey, { reason: text.slice(1) });
+        drained = r?.drainedPendings ?? 0;
+      } catch (err) {
+        logger.error?.(`[${label}] resetSession ${text}: ${err.message}`);
+      }
+      contextHintShown.delete(sessionKey);
+      logEvent('session-reset-command', {
+        chat_id: chatId, command: text, drained_pendings: drained,
+        user: cmdUser, user_id: cmdUserId,
+      });
+      await sendReply('✨ Started a fresh session.');
+      return true;
+    }
+
+    // SDK pm applies model/effort changes live via setModel /
+    // applyFlagSettings — no respawn. Returns whether there was a
+    // live session to push the change into; chatConfig is updated
+    // either way (next cold spawn picks it up).
+    const applyConfigChange = async (setting, value) => {
+      let applied = false;
+      if (setting === 'effort') {
+        applied = await pm.applyFlagSettings(sessionKey, { effortLevel: value });
+      } else if (setting === 'model') {
+        applied = await pm.setModel(sessionKey, value);
+      }
+      return { anyActive: !applied };
+    };
+
+    // /model X
+    if (botAllowsCommands && text.startsWith('/model ')) {
+      const newModel = text.slice(7).trim();
+      if (['opus', 'sonnet', 'haiku'].includes(newModel)) {
+        const oldModel = chatConfig.model;
+        chatConfig.model = newModel;
+        dbWrite(() => db.logConfigChange({
+          chat_id: chatId, thread_id: threadIdStr, field: 'model',
+          old_value: oldModel, new_value: newModel,
+          user: cmdUser, user_id: cmdUserId, source: 'command',
+        }), 'log model change');
+        const { anyActive } = await applyConfigChange('model', newModel);
+        const ver = (modelVersionsDesc && modelVersionsDesc[newModel]) || newModel;
+        const suffix = anyActive ? ` — I'll switch when I finish` : '';
+        await sendReply(`Model → ${newModel} (${ver})${suffix}`);
+      } else {
+        await sendReply(`Unknown model. Use: opus, sonnet, haiku`);
+      }
+      return true;
+    }
+
+    // /effort X
+    if (botAllowsCommands && text.startsWith('/effort ')) {
+      const newEffort = text.slice(8).trim();
+      if (['low', 'medium', 'high', 'xhigh', 'max'].includes(newEffort)) {
+        const oldEffort = chatConfig.effort;
+        chatConfig.effort = newEffort;
+        dbWrite(() => db.logConfigChange({
+          chat_id: chatId, thread_id: threadIdStr, field: 'effort',
+          old_value: oldEffort, new_value: newEffort,
+          user: cmdUser, user_id: cmdUserId, source: 'command',
+        }), 'log effort change');
+        const { anyActive } = await applyConfigChange('effort', newEffort);
+        const suffix = anyActive ? ` — I'll switch when I finish` : '';
+        await sendReply(`Effort → ${newEffort}${suffix}`);
+      } else {
+        await sendReply(`Unknown effort. Use: low, medium, high, xhigh, max`);
+      }
+      return true;
+    }
+
+    // Admin-only pairing commands — chat must match config.bot.adminChatId.
+    // allowConfigCommands alone is NOT sufficient: that flag gates
+    // /model and /effort which only affect the current chat. Pairing
+    // issues cross-chat trust and must be narrowed further.
+    const adminChatId = config.bot?.adminChatId ? String(config.bot.adminChatId) : null;
+    const isAdminChat = adminChatId && String(chatId) === adminChatId;
+
+    if (botAllowsCommands && text.startsWith('/pair-code')) {
+      if (!isAdminChat) { await sendReply('Pairing commands are admin-only; run from the admin chat.'); return true; }
+      const issuerId = cmdUserId;
+      if (!issuerId) { await sendReply('No user id on request'); return true; }
+      const args = parsePairCodeArgs(text);
+      try {
+        const out = pairings.issueCode({
+          bot_name: botName,
+          chat_id: args.chat || null,
+          scope: args.scope || 'user',
+          issued_by_user_id: issuerId,
+          ttlMs: args.ttl ? parsePairingTtl(args.ttl) : undefined,
+          note: args.note || null,
+        });
+        logEvent('pair-code-issued', {
+          bot: botName, by: issuerId, scope: out.scope,
+          chat_id: out.chat_id, note: out.note,
+        });
+        const ttlLabel = args.ttl || '10m';
+        const chatLabel = out.chat_id ? `chat ${out.chat_id}` : 'any chat';
+        await sendReply(
+          `Code: ${out.code}\nexpires: ${ttlLabel}\nscope: ${out.scope} (${chatLabel})${out.note ? `\nnote: ${out.note}` : ''}\n\nShare with user:\n/pair ${out.code}`,
+        );
+      } catch (err) {
+        await sendReply(`Could not issue code: ${err.message}`);
+      }
+      return true;
+    }
+
+    if (botAllowsCommands && text.startsWith('/pairings')) {
+      if (!isAdminChat) { await sendReply('Pairing commands are admin-only; run from the admin chat.'); return true; }
+      const rows = pairings.listActive(botName);
+      if (!rows.length) { await sendReply('No active pairings.'); return true; }
+      const lines = rows.map((r) => {
+        const chat = r.chat_id ? `chat ${r.chat_id}` : 'any chat';
+        const granted = new Date(r.granted_ts).toISOString().slice(0, 16).replace('T', ' ');
+        const note = r.note ? ` — ${r.note}` : '';
+        return `• user ${r.user_id} — ${chat} — ${granted}${note}`;
+      });
+      await sendReply(`Active pairings (${rows.length}):\n${lines.join('\n')}`);
+      return true;
+    }
+
+    if (botAllowsCommands && text.startsWith('/unpair ')) {
+      if (!isAdminChat) { await sendReply('Pairing commands are admin-only; run from the admin chat.'); return true; }
+      const arg = text.slice(8).trim();
+      const targetId = parseInt(arg, 10);
+      if (!Number.isFinite(targetId)) {
+        await sendReply('Usage: /unpair <user_id>');
+        return true;
+      }
+      const n = pairings.revokeByUser({ bot_name: botName, user_id: targetId });
+      logEvent('pair-revoked', {
+        bot: botName, user_id: targetId, by: cmdUserId, count: n,
+      });
+      await sendReply(n
+        ? `Revoked ${n} pairing(s) for user ${targetId}.`
+        : `No active pairings for user ${targetId}.`);
+      return true;
+    }
+
+    // /pair <CODE> — open to anyone, no admin gate (the code IS the auth).
+    if (text.startsWith('/pair ') && !text.startsWith('/pair-code') && !text.startsWith('/pairings')) {
+      if (!cmdUserId) { await sendReply('No user id on request'); return true; }
+      const code = text.slice(6).trim();
+      const res = pairings.claimCode({
+        code, claimer_user_id: cmdUserId,
+        chat_id: chatId, bot_name: botName,
+      });
+      logEvent('pair-claim-attempt', {
+        bot: botName, user_id: cmdUserId, chat_id: chatId,
+        ok: res.ok, reason: res.reason,
+      });
+      if (res.ok) {
+        const chatLabel = res.chat_id ? `chat ${res.chat_id}` : `every chat ${botName} is in`;
+        await sendReply(`Paired. You can use me in ${chatLabel}.${res.note ? `\n(${res.note})` : ''}`);
+        return true;
+      }
+      // Collapse failure reasons into "invalid or expired" to
+      // prevent enumeration. The pair-claim-attempt event above
+      // logs the precise reason for operator audit.
+      const userMsg = res.reason === 'rate-limited'
+        ? 'Too many attempts. Try again later.'
+        : 'That code is invalid or expired.';
+      await sendReply(userMsg);
+      return true;
+    }
+
+    return false;
+  };
+}
+
+module.exports = { createSlashCommands };

package/lib/handlers/voice.js

@@ -0,0 +1,107 @@
+/**
+ * Voice attachment transcription handler.
+ *
+ * Per-message Telegram voice/audio attachments get transcribed via
+ * the configured provider (OpenAI Whisper today). The transcript is
+ * persisted both per-attachment (JSON in attachments.transcription)
+ * AND combined into messages.text so chat-search picks up "what
+ * Maria said" via the normal text path.
+ *
+ * Also fires a one-time 👂 reaction so the user knows the voice was
+ * heard before transcription completes; the caller is told to
+ * suppress the QUEUED 👀 (otherwise both flash visibly).
+ *
+ * Factory pattern: polygram.js wires the runtime deps (config, db,
+ * dbWrite, tg, logEvent, transcribeVoice impl, isVoiceAttachment)
+ * once and the returned function does the per-call work.
+ */
+
+'use strict';
+
+function createTranscribeVoiceAttachments({
+  config,
+  db,
+  dbWrite,
+  tg,
+  logEvent,
+  transcribeVoice,
+  isVoiceAttachment,
+  botName,
+  logger = console,
+} = {}) {
+
+  return async function transcribeVoiceAttachments(downloaded, { chatId, msgId, label, botApi /* , threadId */ }) {
+    const voiceCfg = config.bot?.voice || config.voice;
+    if (!voiceCfg?.enabled) return { ackEmitted: false };
+    const provider = voiceCfg.provider || 'openai';
+    const providerCfg = voiceCfg[provider] || {};
+    const targets = downloaded.filter((a) => isVoiceAttachment(a) && a.path);
+    if (!targets.length) return { ackEmitted: false };
+
+    // Acknowledge receipt with a reaction so the user knows we heard
+    // them. Cheap, robust (no state), and survives transcription
+    // failure. ackEmitted=true tells the caller to skip the reactor's
+    // QUEUED → 👀 transition (otherwise 👂 + 👀 flash visibly).
+    const ack = voiceCfg.ackReaction || '👂';
+    let ackEmitted = false;
+    if (ack && botApi) {
+      ackEmitted = true;
+      tg(botApi, 'setMessageReaction', {
+        chat_id: chatId, message_id: msgId,
+        reaction: [{ type: 'emoji', emoji: ack }],
+      }, { source: 'voice-ack', botName }).catch((err) => {
+        logger.error?.(`[${label}] voice ack reaction failed: ${err.message}`);
+      });
+    }
+
+    await Promise.all(targets.map(async (a) => {
+      try {
+        const opts = {
+          provider,
+          ...providerCfg,
+          language: voiceCfg.language || 'auto',
+          maxDurationSec: voiceCfg.maxDurationSec,
+          maxDurationBytesPerSec: voiceCfg.maxDurationBytesPerSec,
+        };
+        const r = await transcribeVoice(a.path, opts);
+        a.transcription = r;
+        logger.log?.(`[${label}] transcribed ${a.kind} (${r.duration_sec?.toFixed?.(1) || '?'}s, ${r.text.length} chars)`);
+        logEvent('voice-transcribed', {
+          chat_id: chatId, msg_id: msgId,
+          provider: r.provider, language: r.language,
+          duration_sec: r.duration_sec, chars: r.text.length,
+          cost_usd: r.cost_usd,
+        });
+      } catch (err) {
+        logger.error?.(`[${label}] transcribe failed for ${a.name}: ${err.message}`);
+        logEvent('voice-transcribe-failed', {
+          chat_id: chatId, msg_id: msgId, name: a.name, error: err.message,
+        });
+      }
+    }));
+
+    // Persist transcription:
+    //   - Per-attachment: setAttachmentTranscription stores the
+    //     full object (text + language + duration + provider) as
+    //     JSON in attachments.transcription. buildVoiceTags
+    //     parses it back when building the prompt.
+    //   - Message-level: setMessageText updates messages.text with
+    //     the combined transcript so FTS finds "what Maria said"
+    //     via the normal chat search path.
+    const successful = targets.filter((a) => a.transcription?.text);
+    if (!successful.length) return { ackEmitted };
+    for (const a of successful) {
+      if (a.id != null) {
+        dbWrite(() => db.setAttachmentTranscription(a.id, JSON.stringify(a.transcription)),
+          `setAttachmentTranscription ${a.id}`);
+      }
+    }
+    const combinedText = successful.map((a) => a.transcription.text).join(' ').trim();
+    dbWrite(() => db.setMessageText({
+      chat_id: chatId, msg_id: msgId, text: combinedText,
+    }), 'persist voice transcription');
+    return { ackEmitted };
+  };
+}
+
+module.exports = { createTranscribeVoiceAttachments };