switchroom 0.18.31 → 0.18.33

package/telegram-plugin/gateway/photo-message-handler.ts

@@ -0,0 +1,80 @@
+/**
+ * Photo inbound handler (switchroom#2996 P6 cluster D).
+ *
+ * `message:photo` is the one attachment type whose gateway handling is not a
+ * pure metadata render: it downloads the largest photo size from the Telegram
+ * CDN (bounded 15s fetch), writes it into the per-agent inbox with 0600 perms,
+ * and hands the on-disk path to the coalescing inbound pipeline as the image
+ * download. Split out of the cluster-C metadata handlers precisely because it
+ * carries side-effecting IO + bot-token handling.
+ *
+ * The registration line stays in gateway.ts (order is a load-bearing invariant
+ * pinned by gateway-handler-registration-wiring.test.ts) and delegates here.
+ * The bot token is read lazily via `getToken()` — it is materialized after
+ * this deps object is constructed — and never exposed in logs (redacted on the
+ * error path). Path-safety helpers are imported directly.
+ */
+
+import { mkdirSync, writeFileSync } from 'node:fs'
+import type { Context, Filter } from 'grammy'
+import { buildAttachmentPath, assertInsideInbox } from '../attachment-path.js'
+
+export interface PhotoHandlerDeps {
+  handleInboundCoalesced: (
+    ctx: Context,
+    text: string,
+    downloadImage: (() => Promise<string | undefined>) | undefined,
+  ) => Promise<void>
+  /** Lazily read the materialized bot token (set after deps construction). */
+  getToken: () => string
+  /** Per-agent inbox directory (0700). */
+  inboxDir: string
+  /** stderr log sink. */
+  log: (line: string) => void
+}
+
+export async function handlePhotoMessage(
+  ctx: Filter<Context, 'message:photo'>,
+  deps: PhotoHandlerDeps,
+): Promise<void> {
+  const caption = ctx.message.caption ?? '(photo)'
+  await deps.handleInboundCoalesced(ctx, caption, async () => {
+    const photos = ctx.message.photo
+    const best = photos[photos.length - 1]
+    try {
+      const file = await ctx.api.getFile(best.file_id)
+      if (!file.file_path) return undefined
+      // Build download URL — token is embedded in the URL but never exposed
+      // in error messages or logs (caught and sanitized below).
+      //
+      // Bounded fetch: a stalled Telegram CDN connection without a
+      // timeout would hang the entire inbound handler, blocking the
+      // user's photo from ever being acked or seen by the agent.
+      // 15s is generous for normal photos (typical 100ms-2s) and
+      // tight enough to surface a real outage.
+      const token = deps.getToken()
+      const downloadUrl = `https://api.telegram.org/file/bot${token}/${file.file_path}`
+      const res = await fetch(downloadUrl, { signal: AbortSignal.timeout(15_000) })
+      if (!res.ok) {
+        deps.log(`telegram gateway: photo download failed: HTTP ${res.status}\n`)
+        return undefined
+      }
+      const buf = Buffer.from(await res.arrayBuffer())
+      const dlPath = buildAttachmentPath({
+        inboxDir: deps.inboxDir,
+        telegramFilePath: file.file_path,
+        fileUniqueId: best.file_unique_id,
+        now: Date.now(),
+      })
+      mkdirSync(deps.inboxDir, { recursive: true, mode: 0o700 })
+      assertInsideInbox(deps.inboxDir, dlPath)
+      writeFileSync(dlPath, buf, { mode: 0o600 })
+      return dlPath
+    } catch (err) {
+      // Sanitize error to avoid leaking bot token in logs
+      const msg = err instanceof Error ? err.message : 'unknown error'
+      deps.log(`telegram gateway: photo download failed: ${msg.replace(deps.getToken(), '<REDACTED>')}\n`)
+      return undefined
+    }
+  })
+}

package/telegram-plugin/gateway/pinned-message-handler.ts

@@ -0,0 +1,86 @@
+/**
+ * `message:pinned_message` service-message cleanup (switchroom#2996 P6 cluster F).
+ *
+ * Suppresses the "pinned a message" service message Telegram inserts when OUR
+ * silent status-pin fires. The pin call passes `disable_notification: true`,
+ * which kills the PUSH notification but NOT the in-chat service message — so we
+ * delete that service message as it lands, but ONLY for pins we own (tracked in
+ * `statusPinState`). Manual/operator pins are never silent and are never
+ * touched. Only silent status pins reach here as an OUR-pin match, so the
+ * ownership check is the guard.
+ *
+ * The registration line stays in gateway.ts (order is a load-bearing invariant
+ * pinned by gateway-handler-registration-wiring.test.ts) and delegates here.
+ *
+ * DI note (check-bot-api-wrapping): the actual `lockedBot.api.deleteMessage`
+ * call is NOT made here — it is injected as `deleteServiceMessage`, bound in
+ * gateway.ts inside a `robustApiCall(...)` wrapper. This keeps the raw
+ * `lockedBot.api.*` callsite in gateway.ts (already inside the retry policy)
+ * and leaves this module with no raw Bot API site to allowlist.
+ */
+
+import type { Context, Filter } from 'grammy'
+import { pinnedMessageIsOurs, type TrackedStatusPin } from './status-pin-store.js'
+import type { PinState } from '../status-pin.js'
+
+export interface PinnedMessageHandlerDeps {
+  /** Live pinKey→PinState registry of pins we own. */
+  statusPinState: ReadonlyMap<string, PinState>
+  /** Companion pinKey→chatId registry (chat-scoped ownership). */
+  statusPinChatIds: ReadonlyMap<string, string>
+  /**
+   * Delete the pin service message. Bound in gateway.ts through
+   * `robustApiCall(() => lockedBot.api.deleteMessage(...))` so the raw Bot API
+   * call stays inside the retry policy. Rethrows on failure (the caller logs).
+   */
+  deleteServiceMessage: (chatId: string, messageId: number) => Promise<void>
+  /** stderr log sink. */
+  log: (line: string) => void
+}
+
+export async function handlePinnedMessage(
+  ctx: Filter<Context, 'message:pinned_message'>,
+  deps: PinnedMessageHandlerDeps,
+): Promise<void> {
+  const pinnedId = ctx.msg.pinned_message?.message_id
+  if (pinnedId == null) return
+  const chatId = String(ctx.chat.id)
+  const serviceMsgId = ctx.msg.message_id
+
+  // Chat-scoped ownership (see pinnedMessageIsOurs): the match requires BOTH
+  // the messageId AND that the tracked entry lives in THIS chat, so a pin id
+  // colliding across chats can't delete a foreign (e.g. operator-manual) pin
+  // notice. statusPinChatIds is the companion pinKey→chatId map written on
+  // every desired-pinned reconcile.
+  const trackedPins = (): TrackedStatusPin[] => {
+    const out: TrackedStatusPin[] = []
+    for (const [pinKey, state] of deps.statusPinState) {
+      const c = deps.statusPinChatIds.get(pinKey)
+      if (c != null) out.push({ chatId: c, messageId: state.messageId })
+    }
+    return out
+  }
+  const isOurs = () => pinnedMessageIsOurs(trackedPins(), chatId, pinnedId)
+
+  if (!isOurs()) {
+    // Tolerate the reconcile-store race: wait briefly, then re-check once.
+    await new Promise(resolve => setTimeout(resolve, 250))
+    if (!isOurs()) return
+  }
+
+  try {
+    await deps.deleteServiceMessage(chatId, serviceMsgId)
+  } catch (err) {
+    // Best-effort: a failure to delete the service message is cosmetic only —
+    // the "pinned a message" line just stays. The most likely cause in a
+    // supergroup/forum is the bot lacking can_delete_messages admin right, so
+    // surface a concise one-liner (robustApiCall rethrows this case without
+    // logging a reason) rather than swallowing silently — an operator sees WHY.
+    const msg = err instanceof Error ? err.message : String(err)
+    deps.log(
+      `telegram gateway: status-pin: could not delete pin service message ` +
+        `(chat=${chatId} msg=${serviceMsgId}) — likely missing can_delete_messages ` +
+        `admin right in this chat: ${msg}\n`,
+    )
+  }
+}

package/telegram-plugin/gateway/secret-request-card.test.ts

@@ -0,0 +1,46 @@
+import { describe, it, expect } from 'vitest'
+import {
+  renderSecretRequestCard,
+  buildSecretRequestKeyboard,
+} from './secret-request-card.js'
+
+describe('secret-request-card (#2996 P5 extraction — verbatim from gateway.ts)', () => {
+  describe('renderSecretRequestCard', () => {
+    it('renders the title, key, reason, and the provide-securely instruction', () => {
+      const out = renderSecretRequestCard({
+        agent: 'worker',
+        key: 'openai/api_key',
+        reason: 'need it to call the API',
+      })
+      expect(out).toContain('🔒 **worker** needs a secret:')
+      expect(out).toContain('`openai/api_key`')
+      expect(out).toContain('_need it to call the API_')
+      expect(out).toContain('Tap **Provide securely**')
+    })
+
+    it('omits the reason line when none is given', () => {
+      const out = renderSecretRequestCard({ agent: 'worker', key: 'openai/api_key' })
+      // The reason line is the only `_…_` emphasis block; absent when no reason.
+      expect(out).not.toMatch(/\n_.*_$/m)
+    })
+
+    it('does NOT harden card breaks (prose body, preserved from the inline version)', () => {
+      // The inline renderer joined lines plainly (no hardenCardBreaks); this
+      // pins that difference from the vault-save card so the move stays verbatim.
+      const out = renderSecretRequestCard({ agent: 'worker', key: 'k/v' })
+      expect(out.split('\n')[0]).toBe('🔒 **worker** needs a secret:')
+    })
+  })
+
+  describe('buildSecretRequestKeyboard', () => {
+    it('carries the vsp:* callback_data contract', () => {
+      const kb = buildSecretRequestKeyboard('abcd1234')
+      const flat = kb.inline_keyboard.flat()
+      expect(flat.map((b) => b.callback_data)).toEqual([
+        'vsp:provide:abcd1234',
+        'vsp:decline:abcd1234',
+      ])
+      expect(flat.map((b) => b.text)).toEqual(['🔐 Provide securely', '🚫 Decline'])
+    })
+  })
+})

package/telegram-plugin/gateway/secret-request-card.ts

@@ -0,0 +1,45 @@
+/**
+ * Pure renderer + inline-keyboard builder for the agent-initiated
+ * `request_secret` card (#2045 — the agent does NOT have a value and asks the
+ * operator to PROVIDE one securely). Callback prefix `vsp:`
+ * (vault-secret-provide), handled by handleSecretRequestCallback in
+ * callback-query-handlers.ts.
+ *
+ * Extracted verbatim from gateway.ts (#2996 P5); the render body is unchanged.
+ * Unlike the vault-save card this renderer does NOT call hardenCardBreaks — the
+ * body is a short prose block, not labelled field lines — so the move preserves
+ * that difference exactly.
+ */
+
+import { escapeHtmlForTg } from '../shared/bot-runtime.js'
+
+/** Minimal shape the card needs — a subset of PendingSecretRequest. */
+export interface SecretRequestCardInput {
+  agent: string
+  key: string
+  reason?: string
+}
+
+export function renderSecretRequestCard(req: SecretRequestCardInput): string {
+  const lines: string[] = [
+    `🔒 **${escapeHtmlForTg(req.agent)}** needs a secret:`,
+    `\`${req.key}\``,
+  ]
+  if (req.reason) lines.push(`_${escapeHtmlForTg(req.reason)}_`)
+  lines.push(
+    '',
+    'Tap **Provide securely**, then send the value as your next message. I’ll delete it instantly and store it in the vault — it is never shown in chat or to the agent.',
+  )
+  return lines.join('\n')
+}
+
+export function buildSecretRequestKeyboard(stageId: string): { inline_keyboard: Array<Array<{ text: string; callback_data: string }>> } {
+  return {
+    inline_keyboard: [
+      [
+        { text: '🔐 Provide securely', callback_data: `vsp:provide:${stageId}` },
+        { text: '🚫 Decline', callback_data: `vsp:decline:${stageId}` },
+      ],
+    ],
+  }
+}