Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
45.8 KB
Raw Blame
import { beforeEach, describe, expect, it, vi } from 'vitest'
import { TelegramAdapter } from '../../src/channels/telegram.js'
import {
  TELEGRAM_WORKFLOW_RESULT_CALLBACK_DATA,
  telegramWorkflowApprovalCallbackData,
  telegramWorkflowResultCallbackData,
} from '../../src/telegramCallbackData.js'

// vi.hoisted() runs before vi.mock() factories and before imports —
// variables declared here are safely accessible inside vi.mock() closures.

const grammy = vi.hoisted(() => ({
  constructorCalls: [] as Array<{ token: string; config?: unknown }>,
  instances: [] as Array<{
    on: ReturnType<typeof vi.fn>
    catch: ReturnType<typeof vi.fn>
    start: ReturnType<typeof vi.fn>
    stop: ReturnType<typeof vi.fn>
    api: {
      sendMessage: ReturnType<typeof vi.fn>
      sendDocument: ReturnType<typeof vi.fn>
    }
  }>,
}))

// Mutable config object — tests can modify properties to simulate different config states.
// Using vi.hoisted so it's accessible inside the vi.mock() factory below.
const mockCfg = vi.hoisted(
  () =>
    ({
      enableResponseAttachments: false,
      attachmentMaxCount: 3,
      attachmentMaxBytes: 52_428_800,
      telegramApiRoot: undefined as string | undefined,
      telegramStartupStabilityMs: 0,
      telegramShutdownGraceMs: 0,
    }) as {
      enableResponseAttachments: boolean
      attachmentMaxCount: number
      attachmentMaxBytes: number
      telegramApiRoot?: string
      telegramStartupStabilityMs: number
      telegramShutdownGraceMs: number
    }
)

const TEST_TOKEN = '123456:AAFtest'
const PROVIDER_TARGET = {
  hostRef: 'agent-a',
  communicationChannelNamespace: 'channels',
  communicationChannelName: 'agent-a-telegram',
}

function telegramOptions(
  telegramChatType: 'private' | 'group' | 'supergroup' = 'private',
  overrides: Record<string, unknown> = {}
) {
  return { telegramChatType, providerTarget: PROVIDER_TARGET, ...overrides }
}

vi.mock('grammy', () => ({
  // Must use `function` (not arrow) so `new Bot()` works as a constructor call.
  Bot: vi.fn().mockImplementation(function (token: string, botConfig?: unknown) {
    grammy.constructorCalls.push({ token, config: botConfig })
    const instance = {
      on: vi.fn(),
      catch: vi.fn(),
      // Simulate bot.start() calling onStart synchronously so connected = true
      start: vi.fn(function (opts?: {
        onStart?: (info: { username: string; id: number }) => void
      }) {
        opts?.onStart?.({ username: 'test_bot', id: 888001 })
        return Promise.resolve()
      }),
      stop: vi.fn().mockResolvedValue(undefined),
      api: {
        sendMessage: vi.fn().mockResolvedValue({ message_id: 1 }),
        sendDocument: vi.fn().mockResolvedValue({ message_id: 2 }),
      },
    }
    grammy.instances.push(instance)
    return instance
  }),
  InputFile: vi.fn(function (data: unknown, filename?: string) {
    return { _data: data, filename }
  }),
}))

// Use a getter so telegram.ts always reads the current mockCfg values
vi.mock('../../src/config', () => ({
  get config() {
    return mockCfg
  },
}))

beforeEach(() => {
  grammy.constructorCalls.length = 0
  grammy.instances.length = 0
  mockCfg.enableResponseAttachments = false
  mockCfg.telegramApiRoot = undefined
  mockCfg.telegramStartupStabilityMs = 0
  mockCfg.telegramShutdownGraceMs = 0
})

// ── Helpers ──

function getMessageHandler(bot: { on: ReturnType<typeof vi.fn> }) {
  const call = bot.on.mock.calls.find((c: unknown[]) => c[0] === 'message:text')
  if (!call) throw new Error('message:text handler not registered on bot')
  return call[1] as (ctx: unknown) => void
}

function getCallbackHandler(bot: { on: ReturnType<typeof vi.fn> }) {
  const call = bot.on.mock.calls.find((c: unknown[]) => c[0] === 'callback_query:data')
  if (!call) throw new Error('callback_query:data handler not registered on bot')
  return call[1] as (ctx: unknown) => Promise<void>
}

function makeCallbackCtx(opts: {
  senderId: string
  data: string
  chatId?: string
  callbackId?: string
  messageId?: number
  epochSeconds?: number
  chatType?: string
}) {
  return {
    from: { id: parseInt(opts.senderId, 10), username: 'testuser' },
    callbackQuery: {
      id: opts.callbackId ?? 'callback-1',
      data: opts.data,
      message: {
        message_id: opts.messageId ?? 77,
        date: opts.epochSeconds ?? Math.floor(Date.now() / 1000),
        chat: { id: parseInt(opts.chatId ?? '111222', 10), type: opts.chatType ?? 'private' },
      },
    },
    answerCallbackQuery: vi.fn().mockResolvedValue(undefined),
  }
}

function makeCtx(opts: {
  senderId: string
  text?: string
  chatId?: string
  messageId?: number
  epochSeconds?: number
  chatType?: string
  entities?: Array<{ type: string; offset: number; length: number; user?: { id: number } }>
  replyToFromId?: number
}) {
  const message: Record<string, unknown> = {
    text: opts.text ?? 'hello world',
    message_id: opts.messageId ?? 42,
    date: opts.epochSeconds ?? Math.floor(Date.now() / 1000),
  }
  if (opts.entities) {
    message.entities = opts.entities
  }
  if (opts.replyToFromId != null) {
    message.reply_to_message = { from: { id: opts.replyToFromId } }
  }
  return {
    from: { id: parseInt(opts.senderId, 10), username: 'testuser' },
    message,
    chat: { id: parseInt(opts.chatId ?? '111222', 10), type: opts.chatType ?? 'private' },
  }
}

// ── connect() ──

describe('TelegramAdapter — connect()', () => {
  it('creates a Bot with the configured token', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    expect(grammy.instances).toHaveLength(1)
    expect(grammy.constructorCalls[0]).toEqual({ token: TEST_TOKEN, config: undefined })
    // Bot constructor was called, so instances array has one entry
    const bot = grammy.instances[0]!
    expect(bot.start).toHaveBeenCalledOnce()
  })

  it('uses the configured Telegram API root when provided', async () => {
    mockCfg.telegramApiRoot = 'http://telegram-api.channels.svc.cluster.local:443'

    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    expect(grammy.constructorCalls[0]).toEqual({
      token: TEST_TOKEN,
      config: {
        client: { apiRoot: 'http://telegram-api.channels.svc.cluster.local:443' },
      },
    })
  })

  it('registers a message:text handler on the bot', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[0]!
    expect(bot.on).toHaveBeenCalledWith('message:text', expect.any(Function))
  })

  it('registers a callback_query:data handler on the bot', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[0]!
    expect(bot.on).toHaveBeenCalledWith('callback_query:data', expect.any(Function))
  })

  it('calls bot.start() to begin polling', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[0]!
    expect(bot.start).toHaveBeenCalledOnce()
  })

  it('does nothing when telegramBotToken is not configured', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: undefined })

    // No Bot instance should be created
    expect(grammy.instances).toHaveLength(0)
  })
})

// ── disconnect() ──

describe('TelegramAdapter — disconnect()', () => {
  it('calls bot.stop() and nullifies internal bot reference', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[0]!
    await adapter.disconnect()

    expect(bot.stop).toHaveBeenCalledOnce()
  })

  it('is safe to call disconnect() without connect()', async () => {
    const adapter = new TelegramAdapter()
    await expect(adapter.disconnect()).resolves.toBeUndefined()
  })

  it('is safe to call disconnect() twice', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })
    await adapter.disconnect()
    await expect(adapter.disconnect()).resolves.toBeUndefined()
  })
})

// ── fetchMessages() ──

describe('TelegramAdapter — fetchMessages()', () => {
  it('returns empty array when no messages have arrived', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const messages = await adapter.fetchMessages('111222', new Set(['123456']), telegramOptions())
    expect(messages).toEqual([])
  })

  it('returns and clears pending messages from the buffer', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[0]!
    const handler = getMessageHandler(bot)

    // Set allowed senders first via a fetchMessages call
    await adapter.fetchMessages('111222', new Set(['123456']), telegramOptions())
    // Then simulate an incoming message
    handler(makeCtx({ senderId: '123456', text: 'Hi there', chatId: '111222' }))

    const messages = await adapter.fetchMessages('111222', new Set(['123456']), telegramOptions())
    expect(messages).toHaveLength(1)
    expect(messages[0]!.content).toBe('Hi there')
    expect(messages[0]!.channelType).toBe('telegram')
    expect(messages[0]!.sender).toBe('123456')

    // Second call should drain to empty — buffer was cleared
    const messages2 = await adapter.fetchMessages('111222', new Set(['123456']), telegramOptions())
    expect(messages2).toHaveLength(0)
  })

  it('ignores messages from unauthorized senders', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[0]!
    const handler = getMessageHandler(bot)

    // Set allowed senders to only "999999"
    await adapter.fetchMessages('111222', new Set(['999999']), telegramOptions())

    // Simulate a message from unauthorized sender "123456"
    handler(makeCtx({ senderId: '123456', text: 'I am not allowed' }))

    // The message should be dropped
    const messages = await adapter.fetchMessages('111222', new Set(['999999']), telegramOptions())
    expect(messages).toHaveLength(0)
  })

  it('updates allowed senders on each fetchMessages call', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[0]!
    const handler = getMessageHandler(bot)

    // First poll sets senders to only "999999"
    await adapter.fetchMessages('111222', new Set(['999999']), telegramOptions())

    // Message from allowed sender "999999" arrives
    handler(makeCtx({ senderId: '999999', text: 'Allowed' }))

    const messages = await adapter.fetchMessages('111222', new Set(['999999']), telegramOptions())
    expect(messages).toHaveLength(1)
    expect(messages[0]!.sender).toBe('999999')
  })

  it('accumulates multiple messages before draining', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[0]!
    const handler = getMessageHandler(bot)
    await adapter.fetchMessages('111222', new Set(['111', '222']), telegramOptions())

    handler(makeCtx({ senderId: '111', text: 'msg 1', messageId: 1 }))
    handler(makeCtx({ senderId: '222', text: 'msg 2', messageId: 2 }))
    handler(makeCtx({ senderId: '111', text: 'msg 3', messageId: 3 }))

    const messages = await adapter.fetchMessages(
      '111222',
      new Set(['111', '222']),
      telegramOptions()
    )
    expect(messages).toHaveLength(3)
    expect(messages.map(m => m.content)).toEqual(['msg 1', 'msg 2', 'msg 3'])
  })

  it('maps message fields correctly (channelId, messageId, timestamp)', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[0]!
    const handler = getMessageHandler(bot)
    const epochSeconds = 1_700_000_000

    await adapter.fetchMessages('111222', new Set(['123456']), telegramOptions())
    handler({
      from: { id: 123456, username: 'alice' },
      message: { text: 'timestamp test', message_id: 99, date: epochSeconds },
      chat: { id: 111222, type: 'private' },
    })

    const [msg] = await adapter.fetchMessages('111222', new Set(['123456']), telegramOptions())
    expect(msg!.channelId).toBe('111222')
    expect(msg!.messageId).toBe('99')
    expect(msg!.timestamp).toEqual(new Date(epochSeconds * 1000))
    expect(msg!.providerIdentity).toEqual({
      medium: 'telegram',
      providerUserId: '123456',
      providerWorkspaceId: null,
      providerChannelId: '111222',
      providerChannelType: 'private',
      providerEventId: 'telegram:111222:99',
      providerTarget: {
        ...PROVIDER_TARGET,
        providerBotId: '888001',
        providerBotUsername: 'test_bot',
      },
    })
  })

  it('with replyOnlyWhenMentioned, drops group messages without mention or reply', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[0]!
    const handler = getMessageHandler(bot)

    await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    handler(
      makeCtx({
        senderId: '123456',
        text: 'no mention',
        chatId: '111222',
        chatType: 'group',
      })
    )

    const messages = await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    expect(messages).toHaveLength(0)
  })

  it('with replyOnlyWhenMentioned, accepts @mention of bot in groups', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[0]!
    const handler = getMessageHandler(bot)
    const text = '@test_bot hello'
    await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    handler(
      makeCtx({
        senderId: '123456',
        text,
        chatId: '111222',
        chatType: 'group',
        entities: [{ type: 'mention', offset: 0, length: 9 }],
      })
    )

    const messages = await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    expect(messages).toHaveLength(1)
    expect(messages[0]!.content).toBe(text)
  })

  it('with replyOnlyWhenMentioned, accepts reply to bot in groups', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[0]!
    const handler = getMessageHandler(bot)
    await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    handler(
      makeCtx({
        senderId: '123456',
        text: 'thread reply',
        chatId: '111222',
        chatType: 'group',
        replyToFromId: 888001,
      })
    )

    const messages = await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    expect(messages).toHaveLength(1)
  })

  it('with replyOnlyWhenMentioned, private chats still accept messages without mention', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[0]!
    const handler = getMessageHandler(bot)
    await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('private', { replyOnlyWhenMentioned: true })
    )
    handler(makeCtx({ senderId: '123456', text: 'dm', chatId: '111222', chatType: 'private' }))

    const messages = await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('private', { replyOnlyWhenMentioned: true })
    )
    expect(messages).toHaveLength(1)
  })

  it('with replyOnlyWhenMentioned, /approve bypasses mention requirement', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[0]!
    const handler = getMessageHandler(bot)
    await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    handler(
      makeCtx({
        senderId: '123456',
        text: '/approve',
        chatId: '111222',
        chatType: 'group',
      })
    )

    const messages = await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    expect(messages).toHaveLength(1)
  })

  it('with replyOnlyWhenMentioned, drops group messages when bot id is not available', async () => {
    const { Bot } = await import('grammy')
    vi.mocked(Bot).mockImplementationOnce(function () {
      const instance = {
        on: vi.fn(),
        catch: vi.fn(),
        start: vi.fn(function (opts?: { onStart?: (info: { username: string }) => void }) {
          opts?.onStart?.({ username: 'test_bot' })
          return Promise.resolve()
        }),
        stop: vi.fn().mockResolvedValue(undefined),
        api: {
          sendMessage: vi.fn().mockResolvedValue({ message_id: 1 }),
          sendDocument: vi.fn().mockResolvedValue({ message_id: 2 }),
        },
      }
      grammy.instances.push(instance)
      return instance
    })

    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[grammy.instances.length - 1]!
    const handler = getMessageHandler(bot)
    await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    handler(
      makeCtx({
        senderId: '123456',
        text: '@test_bot hi',
        chatId: '111222',
        chatType: 'group',
        entities: [{ type: 'mention', offset: 0, length: 9 }],
      })
    )
    const messages = await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    expect(messages).toHaveLength(0)
  })

  it('with replyOnlyWhenMentioned, logs warn when dropping group message before bot id is ready', async () => {
    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
    const { Bot } = await import('grammy')
    vi.mocked(Bot).mockImplementationOnce(function () {
      const instance = {
        on: vi.fn(),
        catch: vi.fn(),
        start: vi.fn(function (opts?: { onStart?: (info: { username: string }) => void }) {
          opts?.onStart?.({ username: 'test_bot' })
          return Promise.resolve()
        }),
        stop: vi.fn().mockResolvedValue(undefined),
        api: {
          sendMessage: vi.fn().mockResolvedValue({ message_id: 1 }),
          sendDocument: vi.fn().mockResolvedValue({ message_id: 2 }),
        },
      }
      grammy.instances.push(instance)
      return instance
    })

    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })
    const bot = grammy.instances[grammy.instances.length - 1]!
    const handler = getMessageHandler(bot)
    await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    handler(makeCtx({ senderId: '123456', text: 'early', chatId: '111222', chatType: 'group' }))

    await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    expect(warnSpy.mock.calls.some(c => String(c[0]).includes('bot id not available yet'))).toBe(
      true
    )
    warnSpy.mockRestore()
  })

  it('warns once when replyOnlyWhenMentioned is set but the bot has no @username', async () => {
    const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {})
    const { Bot } = await import('grammy')
    vi.mocked(Bot).mockImplementationOnce(function () {
      const instance = {
        on: vi.fn(),
        catch: vi.fn(),
        start: vi.fn(function (opts?: {
          onStart?: (info: { username: string; id: number }) => void
        }) {
          opts?.onStart?.({ username: '', id: 888001 })
          return Promise.resolve()
        }),
        stop: vi.fn().mockResolvedValue(undefined),
        api: {
          sendMessage: vi.fn().mockResolvedValue({ message_id: 1 }),
          sendDocument: vi.fn().mockResolvedValue({ message_id: 2 }),
        },
      }
      grammy.instances.push(instance)
      return instance
    })

    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })
    await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )

    const noUsernameWarns = warnSpy.mock.calls.filter(c =>
      String(c[0]).includes('replyOnlyWhenMentioned is enabled but this bot has no @username')
    )
    expect(noUsernameWarns.length).toBe(1)
    warnSpy.mockRestore()
  })

  it('with replyOnlyWhenMentioned and no @username, accepts text_mention of bot id in groups', async () => {
    const { Bot } = await import('grammy')
    vi.mocked(Bot).mockImplementationOnce(function () {
      const instance = {
        on: vi.fn(),
        catch: vi.fn(),
        start: vi.fn(function (opts?: {
          onStart?: (info: { username: string; id: number }) => void
        }) {
          opts?.onStart?.({ username: '', id: 888001 })
          return Promise.resolve()
        }),
        stop: vi.fn().mockResolvedValue(undefined),
        api: {
          sendMessage: vi.fn().mockResolvedValue({ message_id: 1 }),
          sendDocument: vi.fn().mockResolvedValue({ message_id: 2 }),
        },
      }
      grammy.instances.push(instance)
      return instance
    })

    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })
    const bot = grammy.instances[grammy.instances.length - 1]!
    const handler = getMessageHandler(bot)
    await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    handler(
      makeCtx({
        senderId: '123456',
        text: 'hey',
        chatId: '111222',
        chatType: 'group',
        entities: [{ type: 'text_mention', offset: 0, length: 3, user: { id: 888001 } }],
      })
    )
    const messages = await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    expect(messages).toHaveLength(1)
  })

  it('with replyOnlyWhenMentioned, /approve always and /deny bypass in group', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })
    const bot = grammy.instances[0]!
    const handler = getMessageHandler(bot)
    await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )

    handler(
      makeCtx({
        senderId: '123456',
        text: '/approve always',
        chatId: '111222',
        chatType: 'group',
      })
    )
    let messages = await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    expect(messages).toHaveLength(1)
    expect(messages[0]!.content).toBe('/approve always')

    await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    handler(
      makeCtx({
        senderId: '123456',
        text: '/deny',
        messageId: 2,
        chatId: '111222',
        chatType: 'group',
      })
    )
    messages = await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    expect(messages).toHaveLength(1)
    expect(messages[0]!.content).toBe('/deny')
  })

  it('handles Telegram supergroups like configured groups for operational commands', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })
    const bot = grammy.instances[0]!
    const handler = getMessageHandler(bot)
    await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('supergroup', { replyOnlyWhenMentioned: true })
    )

    handler(
      makeCtx({
        senderId: '123456',
        text: '@test_bot in supergroup',
        chatId: '111222',
        chatType: 'supergroup',
        entities: [{ type: 'mention', offset: 0, length: 9 }],
      })
    )

    const messages = await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('supergroup', { replyOnlyWhenMentioned: true })
    )
    expect(messages).toHaveLength(1)
    expect(messages[0]!.providerIdentity?.providerChannelType).toBe('supergroup')
  })

  it('with replyOnlyWhenMentioned, channel chat type is ignored even when mentioned', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })
    const bot = grammy.instances[0]!
    const handler = getMessageHandler(bot)
    await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    handler(
      makeCtx({
        senderId: '123456',
        text: 'broadcast without mention',
        chatId: '111222',
        chatType: 'channel',
      })
    )
    let messages = await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    expect(messages).toHaveLength(0)

    await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    handler(
      makeCtx({
        senderId: '123456',
        text: '@test_bot in channel',
        chatId: '111222',
        chatType: 'channel',
        messageId: 3,
        entities: [{ type: 'mention', offset: 0, length: 9 }],
      })
    )
    messages = await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    expect(messages).toHaveLength(0)
  })

  it('with replyOnlyWhenMentioned and no @username, @mention entity alone does not qualify in groups', async () => {
    const { Bot } = await import('grammy')
    vi.mocked(Bot).mockImplementationOnce(function () {
      const instance = {
        on: vi.fn(),
        catch: vi.fn(),
        start: vi.fn(function (opts?: {
          onStart?: (info: { username: string; id: number }) => void
        }) {
          opts?.onStart?.({ username: '', id: 888001 })
          return Promise.resolve()
        }),
        stop: vi.fn().mockResolvedValue(undefined),
        api: {
          sendMessage: vi.fn().mockResolvedValue({ message_id: 1 }),
          sendDocument: vi.fn().mockResolvedValue({ message_id: 2 }),
        },
      }
      grammy.instances.push(instance)
      return instance
    })

    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })
    const bot = grammy.instances[grammy.instances.length - 1]!
    const handler = getMessageHandler(bot)
    await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    const text = '@other hi'
    handler(
      makeCtx({
        senderId: '123456',
        text,
        chatId: '111222',
        chatType: 'group',
        entities: [{ type: 'mention', offset: 0, length: 6 }],
      })
    )
    const messages = await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    expect(messages).toHaveLength(0)
  })

  it('accepts workflow approval button callbacks even when mentions are required', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[0]!
    const handler = getCallbackHandler(bot)
    const approvalRequestId = '00000000-0000-0000-0000-000000000222'
    await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )

    const ctx = makeCallbackCtx({
      senderId: '123456',
      data: telegramWorkflowApprovalCallbackData('approve', approvalRequestId),
      chatId: '111222',
      chatType: 'group',
      callbackId: 'callback-approve-1',
      messageId: 77,
    })
    await handler(ctx)

    const messages = await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    expect(messages).toHaveLength(1)
    expect(messages[0]!.content).toBe('/approve ' + approvalRequestId)
    expect(messages[0]!.messageId).toBe('77')
    expect(messages[0]!.rawData).toMatchObject({
      telegramCallbackApprovalRequestId: approvalRequestId,
      telegramCallbackDecision: 'approve',
    })
    expect(messages[0]!.providerIdentity).toMatchObject({
      providerUserId: '123456',
      providerChannelId: '111222',
      providerEventId: 'telegram:111222:callback:callback-approve-1',
    })
    expect(ctx.answerCallbackQuery).toHaveBeenCalledWith({
      text: 'Recording decision...',
      show_alert: false,
    })
  })

  it('accepts tool approval button callbacks even when mentions are required', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[0]!
    const handler = getCallbackHandler(bot)
    await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('supergroup', { replyOnlyWhenMentioned: true })
    )

    const ctx = makeCallbackCtx({
      senderId: '123456',
      data: 'tool:a:abcdefghijklmnop',
      chatId: '111222',
      chatType: 'supergroup',
      callbackId: 'callback-tool-approve-1',
      messageId: 77,
    })
    await handler(ctx)

    const messages = await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('supergroup', { replyOnlyWhenMentioned: true })
    )
    expect(messages).toHaveLength(1)
    expect(messages[0]).toMatchObject({
      content: 'tool:a:abcdefghijklmnop',
      messageId: '77',
      rawData: {
        telegramToolApprovalActionToken: 'abcdefghijklmnop',
        telegramToolApprovalDecision: 'approve',
      },
    })
    expect(ctx.answerCallbackQuery).toHaveBeenCalledWith({
      text: 'Recording decision...',
      show_alert: false,
    })
  })

  it('ignores repeated approval button callbacks from the same user for two seconds', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[0]!
    const handler = getCallbackHandler(bot)
    const approvalRequestId = '00000000-0000-0000-0000-000000000222'
    await adapter.fetchMessages('111222', new Set(['123456']), telegramOptions('group'))

    const approveCtx = makeCallbackCtx({
      senderId: '123456',
      data: telegramWorkflowApprovalCallbackData('approve', approvalRequestId),
      chatId: '111222',
      chatType: 'group',
      callbackId: 'callback-approve-1',
      messageId: 77,
    })
    await handler(approveCtx)

    const denyCtx = makeCallbackCtx({
      senderId: '123456',
      data: telegramWorkflowApprovalCallbackData('deny', approvalRequestId),
      chatId: '111222',
      chatType: 'group',
      callbackId: 'callback-deny-1',
      messageId: 77,
    })
    await handler(denyCtx)

    const messages = await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group')
    )
    expect(messages).toHaveLength(1)
    expect(messages[0]!.content).toBe('/approve ' + approvalRequestId)
    expect(approveCtx.answerCallbackQuery).toHaveBeenCalledWith({
      text: 'Recording decision...',
      show_alert: false,
    })
    expect(denyCtx.answerCallbackQuery).toHaveBeenCalledWith({
      text: 'Already recording decision.',
      show_alert: false,
    })
  })

  it('allows the same approval button after the debounce window so stale clicks are checked', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[0]!
    const handler = getCallbackHandler(bot)
    const approvalRequestId = '00000000-0000-0000-0000-000000000222'
    await adapter.fetchMessages('111222', new Set(['123456']), telegramOptions('group'))

    const dateNow = vi.spyOn(Date, 'now')
    try {
      dateNow.mockReturnValueOnce(1_000)
      await handler(
        makeCallbackCtx({
          senderId: '123456',
          data: telegramWorkflowApprovalCallbackData('approve', approvalRequestId),
          chatId: '111222',
          chatType: 'group',
          callbackId: 'callback-approve-1',
          messageId: 77,
          epochSeconds: 1,
        })
      )

      dateNow.mockReturnValueOnce(3_001)
      await handler(
        makeCallbackCtx({
          senderId: '123456',
          data: telegramWorkflowApprovalCallbackData('deny', approvalRequestId),
          chatId: '111222',
          chatType: 'group',
          callbackId: 'callback-deny-1',
          messageId: 77,
          epochSeconds: 3,
        })
      )
    } finally {
      dateNow.mockRestore()
    }

    const messages = await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group')
    )
    expect(messages.map(message => message.content)).toEqual([
      '/approve ' + approvalRequestId,
      '/deny ' + approvalRequestId,
    ])
  })

  it('ignores repeated workflow result button callbacks from the same user for two seconds', async () => {
    const workflowRunId = '11111111-2222-3333-4444-555555555555'
    const downloadWorkflowResultByRun = vi.fn(async () => ({
      success: true,
      status: 'completed' as const,
      response: 'Workflow result is ready.',
    }))
    const adapter = new TelegramAdapter({
      confirmTelegramChallenge: vi.fn(),
      downloadWorkflowResultByRun,
    })
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[0]!
    const handler = getCallbackHandler(bot)
    await adapter.fetchMessages('111222', new Set(['123456']), telegramOptions('group'))

    const firstCtx = makeCallbackCtx({
      senderId: '123456',
      data: telegramWorkflowResultCallbackData(workflowRunId)!,
      chatId: '111222',
      chatType: 'group',
      callbackId: 'callback-result-1',
      messageId: 78,
    })
    await handler(firstCtx)

    const secondCtx = makeCallbackCtx({
      senderId: '123456',
      data: telegramWorkflowResultCallbackData(workflowRunId)!,
      chatId: '111222',
      chatType: 'group',
      callbackId: 'callback-result-2',
      messageId: 78,
    })
    await handler(secondCtx)
    await Promise.resolve()

    expect(downloadWorkflowResultByRun).toHaveBeenCalledTimes(1)
    expect(firstCtx.answerCallbackQuery).toHaveBeenCalledWith({
      text: 'Fetching result...',
      show_alert: false,
    })
    expect(secondCtx.answerCallbackQuery).toHaveBeenCalledWith({
      text: 'Already fetching result.',
      show_alert: false,
    })
  })

  it('downloads workflow result button callbacks directly without enqueuing chat prompts', async () => {
    const workflowRunId = '11111111-2222-3333-4444-555555555555'
    const downloadWorkflowResultByRun = vi.fn(async () => ({
      success: true,
      status: 'completed' as const,
      response: 'Workflow result is ready.',
      attachments: [
        {
          id: 'artifact-1',
          kind: 'file' as const,
          mimeType: 'application/pdf',
          encoding: 'base64' as const,
          dataBase64: Buffer.from('%PDF artifact bytes').toString('base' + '64'),
          filename: 'due-diligence.pdf',
          caption: 'due-diligence.pdf (19 bytes)',
          sourceTool: 'workflow_result',
        },
      ],
    }))
    const adapter = new TelegramAdapter({
      confirmTelegramChallenge: vi.fn(),
      downloadWorkflowResultByRun,
    })
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[0]!
    const handler = getCallbackHandler(bot)
    await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )

    const ctx = makeCallbackCtx({
      senderId: '123456',
      data: telegramWorkflowResultCallbackData(workflowRunId)!,
      chatId: '111222',
      chatType: 'group',
      callbackId: 'callback-result-1',
      messageId: 78,
    })
    await handler(ctx)

    const messages = await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    expect(messages).toHaveLength(0)
    expect(downloadWorkflowResultByRun).toHaveBeenCalledWith(
      expect.objectContaining({
        channelType: 'telegram',
        channelId: '111222',
        sender: '123456',
        content: 'Download the completed workflow result',
        messageId: '78',
        providerIdentity: expect.objectContaining({
          providerUserId: '123456',
          providerChannelId: '111222',
          providerEventId: 'telegram:111222:callback:callback-result-1',
        }),
      }),
      workflowRunId
    )
    expect(ctx.answerCallbackQuery).toHaveBeenCalledWith({
      text: 'Fetching result...',
      show_alert: false,
    })
  })

  it('does not enqueue legacy workflow result callbacks without a workflow run', async () => {
    const downloadWorkflowResultByRun = vi.fn()
    const adapter = new TelegramAdapter({
      confirmTelegramChallenge: vi.fn(),
      downloadWorkflowResultByRun,
    })
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[0]!
    const handler = getCallbackHandler(bot)
    await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )

    const ctx = makeCallbackCtx({
      senderId: '123456',
      data: TELEGRAM_WORKFLOW_RESULT_CALLBACK_DATA,
      chatId: '111222',
      chatType: 'group',
      callbackId: 'callback-result-legacy',
      messageId: 79,
    })
    await handler(ctx)

    const messages = await adapter.fetchMessages(
      '111222',
      new Set(['123456']),
      telegramOptions('group', { replyOnlyWhenMentioned: true })
    )
    expect(messages).toHaveLength(0)
    expect(downloadWorkflowResultByRun).not.toHaveBeenCalled()
    expect(bot.api.sendMessage).toHaveBeenCalledWith(
      '111222',
      'This result button is missing its workflow run. Trigger the workflow again.',
      expect.objectContaining({ reply_to_message_id: 79 })
    )
    expect(ctx.answerCallbackQuery).toHaveBeenCalledWith({
      text: 'Fetching result...',
      show_alert: false,
    })
  })

  it('rejects button callbacks from unauthorized Telegram senders', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const bot = grammy.instances[0]!
    const handler = getCallbackHandler(bot)
    await adapter.fetchMessages('111222', new Set(['999999']), telegramOptions('group'))

    const ctx = makeCallbackCtx({
      senderId: '123456',
      data: TELEGRAM_WORKFLOW_RESULT_CALLBACK_DATA,
      chatId: '111222',
      chatType: 'group',
      callbackId: 'callback-denied-1',
    })
    await handler(ctx)

    const messages = await adapter.fetchMessages(
      '111222',
      new Set(['999999']),
      telegramOptions('group')
    )
    expect(messages).toHaveLength(0)
    expect(ctx.answerCallbackQuery).toHaveBeenCalledWith({
      text: 'You are not authorized to use this button.',
      show_alert: true,
    })
  })
})

// ── sendMessage() ──

describe('TelegramAdapter — sendMessage()', () => {
  it('sends a text message via bot.api.sendMessage', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    await adapter.sendMessage('111222', 'Hello from Clerum')

    const bot = grammy.instances[0]!
    // channelId is passed as-is (string), 3rd arg is the options object
    expect(bot.api.sendMessage).toHaveBeenCalledWith(
      '111222',
      'Hello from Clerum',
      expect.objectContaining({})
    )
  })

  it('sends inline keyboard buttons as Telegram reply markup', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    await adapter.sendMessage('111222', 'Approval needed', undefined, undefined, {
      telegramInlineKeyboard: [
        [
          {
            text: 'Approve',
            callbackData: telegramWorkflowApprovalCallbackData(
              'approve',
              '00000000-0000-0000-0000-000000000222'
            ),
          },
        ],
      ],
    })

    const bot = grammy.instances[0]!
    expect(bot.api.sendMessage).toHaveBeenCalledWith(
      '111222',
      'Approval needed',
      expect.objectContaining({
        reply_markup: {
          inline_keyboard: [
            [
              {
                text: 'Approve',
                callback_data: 'wf:a:00000000-0000-0000-0000-000000000222',
              },
            ],
          ],
        },
      })
    )
  })

  it('updates tool approval keyboards and clears them from progress messages', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })
    const bot = grammy.instances[0]!
    const editMessageText = vi.fn().mockResolvedValue({ message_id: 1 })
    ;(bot.api as typeof bot.api & { editMessageText: typeof editMessageText }).editMessageText =
      editMessageText

    await adapter.editMessage('111222', '77', 'Approval needed', {
      telegramInlineKeyboard: [
        [
          { text: 'Approve', callbackData: 'tool:a:abcdefghijklmnop' },
          { text: 'Deny', callbackData: 'tool:d:abcdefghijklmnop' },
        ],
      ],
    })
    await adapter.editMessage('111222', '77', 'Approved. Processing...')

    expect(editMessageText).toHaveBeenNthCalledWith(1, '111222', 77, 'Approval needed', {
      reply_markup: {
        inline_keyboard: [
          [
            { text: 'Approve', callback_data: 'tool:a:abcdefghijklmnop' },
            { text: 'Deny', callback_data: 'tool:d:abcdefghijklmnop' },
          ],
        ],
      },
    })
    expect(editMessageText).toHaveBeenNthCalledWith(2, '111222', 77, 'Approved. Processing...', {
      reply_markup: { inline_keyboard: [] },
    })
  })

  it('does nothing when bot is not connected (no prior connect())', async () => {
    const adapter = new TelegramAdapter()

    await expect(adapter.sendMessage('111222', 'Should not send')).resolves.toBeUndefined()
    expect(grammy.instances).toHaveLength(0)
  })

  it('splits long messages (>4096 chars) into multiple api calls', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    const longText = 'A'.repeat(8200)
    await adapter.sendMessage('111222', longText)

    const bot = grammy.instances[0]!
    expect(bot.api.sendMessage.mock.calls.length).toBeGreaterThan(1)
  })

  it('passes replyToMessageId as reply_to_message_id', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    await adapter.sendMessage('111222', 'Reply!', '42')

    const bot = grammy.instances[0]!
    const callArgs = bot.api.sendMessage.mock.calls[0]
    // telegram.ts uses the legacy reply_to_message_id field (not reply_parameters)
    expect(callArgs[2]).toMatchObject({ reply_to_message_id: 42 })
  })

  it('sends workflow artifact documents without a separate text message when content is empty', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    await adapter.sendMessage('111222', '', '42', [
      {
        id: 'artifact-1',
        kind: 'file',
        mimeType: 'application/pdf',
        encoding: 'base64',
        dataBase64: Buffer.from('%PDF artifact bytes').toString('base' + '64'),
        filename: 'due-diligence.pdf',
        caption: 'due-diligence.pdf (19 bytes)',
        sourceTool: 'workflow_result',
      },
    ])

    const bot = grammy.instances[0]!
    expect(bot.api.sendMessage).not.toHaveBeenCalled()
    expect(bot.api.sendDocument).toHaveBeenCalledTimes(1)
    const [, inputFile, options] = bot.api.sendDocument.mock.calls[0]
    expect(inputFile).toMatchObject({ filename: 'due-diligence.pdf' })
    expect(options).toMatchObject({
      caption: 'due-diligence.pdf (19 bytes)',
      reply_to_message_id: 42,
    })
  })

  it('does not send unsupported workflow artifact document types', async () => {
    const adapter = new TelegramAdapter()
    await adapter.connect({ telegramBotToken: TEST_TOKEN })

    await adapter.sendMessage('111222', 'Workflow result is ready', undefined, [
      {
        id: 'artifact-zip',
        kind: 'file',
        mimeType: 'application/zip',
        encoding: 'base64',
        dataBase64: Buffer.from('zip bytes').toString('base' + '64'),
        filename: 'archive.zip',
        sourceTool: 'workflow_result',
      },
    ])

    const bot = grammy.instances[0]!
    expect(bot.api.sendDocument).not.toHaveBeenCalled()
    expect(bot.api.sendMessage).toHaveBeenCalledWith(
      '111222',
      'Workflow result is ready',
      expect.objectContaining({})
    )
  })
})

// ── channelType ──

describe('TelegramAdapter — channelType', () => {
  it('reports channelType as telegram', () => {
    const adapter = new TelegramAdapter()
    expect(adapter.channelType).toBe('telegram')
  })
})