Skip to content

Your team of AI agents, on your Mac, Windows or Linux. Agents that talk in channels, write code, review each other and use your tools, on the Claude Code, Codex, OpenCode or Pi you already have. Anything that touches the real world waits for your yes.

12.8 KB
Raw Blame
// The phone (spec §19): a Telegram bot of the user's own sends approvals with
// buttons, agents' questions (answered by replying to them) and what routines
// did. The app asks Telegram for updates (long polling), so nothing needs to
// reach this Mac. It answers only the chat paired with a code shown in the app.
import { randomInt } from 'node:crypto'
import { L } from '../shared/lang'
import { offline, UserError } from '../shared/errors'
import type { Approval, Message, TelegramInfo } from '../shared/types'
import type { Secrets } from './secrets'
import { questionsAsText, questionsOf } from '../shared/questions'

const API = 'https://api.telegram.org'
const TOKEN = 'telegram:token'
const CHAT = 'telegram:chat'
const POLL_SECONDS = 50
const RETRY_MS = 15_000
const MAX_TEXT = 3_500 // Telegram allows 4096 per message

// Telegram's refusal, in what to do: the token was revoked, or another app reads the same bot.
export const refused = (status: number, description?: string): UserError =>
  new UserError(
    status === 401
      ? L('O token do bot não vale mais. Cole um novo do @BotFather.', "The bot's token isn't valid anymore. Paste a new one from @BotFather.")
      : status === 409
        ? L('Outro app está lendo este bot (outro Tucano ou um webhook). Feche o outro ou troque o token.', 'Another app is reading this bot (another Tucano, or a webhook). Close the other one or change the token.')
        : L(`O Telegram recusou: ${description ?? status}.`, `Telegram refused: ${description ?? status}.`)
  )

type Fetch = typeof fetch
type Update = {
  update_id: number
  message?: { message_id: number; chat: { id: number; first_name?: string; username?: string; title?: string }; text?: string; reply_to_message?: { message_id: number } }
  callback_query?: { id: string; data?: string; message?: { message_id: number; chat: { id: number } } }
}

export interface TelegramDeps {
  secrets: Pick<Secrets, 'get' | 'set'>
  decide(approvalId: string, decision: 'approved' | 'refused', reason?: string): Promise<void>
  approval(id: string): Approval | undefined
  answer(conversationId: string, text: string, threadId?: string): void // a reply to a question, as if I wrote it in the app (in its thread)
  changed(): void // the bot or the pairing changed: settings show it
  fetch?: Fetch
}

export class Telegram {
  private bot?: string
  private chat?: { id: number; name: string }
  private code = String(randomInt(100_000, 1_000_000))
  private error?: string
  private loop?: AbortController
  private offset = 0
  private questions = new Map<number, { conversationId: string; threadId?: string }>() // Telegram message id → where it was asked

  constructor(private deps: TelegramDeps) {}

  private get f(): Fetch {
    return this.deps.fetch ?? fetch
  }

  info(): TelegramInfo {
    return { bot: this.bot, chat: this.chat?.name, code: this.bot && !this.chat ? this.code : undefined, error: this.error }
  }

  async start(): Promise<void> {
    const token = await this.deps.secrets.get(TOKEN)
    if (!token) return
    this.chat = (await this.deps.secrets.get(CHAT).then((s) => (s ? (JSON.parse(s) as { id: number; name: string }) : undefined))) ?? undefined
    try {
      this.bot = await this.me(token)
      this.error = undefined
    } catch (e) {
      this.error = e instanceof Error ? e.message : String(e)
    }
    this.deps.changed()
    this.listen(token)
  }

  stop(): void {
    this.loop?.abort()
    this.loop = undefined
  }

  // Checked with Telegram before it's saved; null forgets the bot and the pairing.
  async setToken(token: string | null): Promise<void> {
    const t = token?.trim()
    if (t) await this.me(t)
    this.stop()
    await this.deps.secrets.set(TOKEN, t || undefined)
    await this.deps.secrets.set(CHAT, undefined)
    this.bot = undefined
    this.chat = undefined
    this.error = undefined
    this.code = String(randomInt(100_000, 1_000_000))
    if (t) await this.start()
    else this.deps.changed()
  }

  async unpair(): Promise<void> {
    await this.deps.secrets.set(CHAT, undefined)
    this.chat = undefined
    this.code = String(randomInt(100_000, 1_000_000))
    this.deps.changed()
  }

  private async me(token: string): Promise<string> {
    let res: Response
    try {
      res = await this.f(`${API}/bot${token}/getMe`, { signal: AbortSignal.timeout(10_000) })
    } catch {
      throw new Error(L('Não consegui falar com o Telegram. Confira a internet.', "I couldn't reach Telegram. Check the internet."))
    }
    const body = (await res.json().catch(() => null)) as { ok?: boolean; result?: { username?: string } } | null
    if (!res.ok || !body?.ok) throw new Error(L('O Telegram recusou esse token. Copie de novo do @BotFather.', 'Telegram refused that token. Copy it again from @BotFather.'))
    return `@${body.result?.username ?? 'bot'}`
  }

  private async api(method: string, params: Record<string, unknown>, signal?: AbortSignal): Promise<unknown> {
    const token = await this.deps.secrets.get(TOKEN)
    if (!token) return undefined
    const res = await this.f(`${API}/bot${token}/${method}`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(params),
      signal: signal ?? AbortSignal.timeout(15_000)
    })
    const body = (await res.json().catch(() => null)) as { ok?: boolean; result?: unknown; description?: string } | null
    if (!body?.ok) throw refused(res.status, body?.description)
    return body.result
  }

  private listen(token: string): void {
    this.stop()
    const ctl = new AbortController()
    this.loop = ctl
    void (async () => {
      while (!ctl.signal.aborted) {
        try {
          const res = await this.f(`${API}/bot${token}/getUpdates?timeout=${POLL_SECONDS}&offset=${this.offset}&allowed_updates=${encodeURIComponent('["message","callback_query"]')}`, {
            signal: AbortSignal.any([ctl.signal, AbortSignal.timeout((POLL_SECONDS + 10) * 1000)])
          })
          const body = (await res.json()) as { ok: boolean; result?: Update[]; description?: string }
          if (!body.ok) throw refused(res.status, body.description)
          for (const u of body.result ?? []) {
            this.offset = u.update_id + 1
            await this.handle(u).catch((e: unknown) => console.error('[telegram]', e))
          }
          if (this.error) {
            this.error = undefined
            this.deps.changed()
          }
        } catch (e) {
          if (ctl.signal.aborted) return
          // Telegram said no (and why), or it didn't answer at all: the loop asks again in a moment.
          const why =
            e instanceof UserError
              ? e.message
              : offline(e)
                ? L('Sem internet; tento de novo sozinho.', 'No internet; I’ll try again on my own.')
                : L('O Telegram não respondeu direito; tento de novo sozinho.', 'Telegram didn’t answer properly; I’ll try again on my own.')
          if (why !== this.error) {
            this.error = why
            this.deps.changed()
          }
          await new Promise((r) => setTimeout(r, RETRY_MS))
        }
      }
    })()
  }

  private async handle(u: Update): Promise<void> {
    const m = u.message
    if (m?.text !== undefined) {
      if (!this.chat) {
        // Pairing: only someone who sees the code in the app can take the bot.
        if (m.text.replace('/start', '').trim() !== this.code) return
        this.chat = { id: m.chat.id, name: m.chat.title ?? m.chat.first_name ?? m.chat.username ?? 'Telegram' }
        await this.deps.secrets.set(CHAT, JSON.stringify(this.chat))
        this.deps.changed()
        await this.send(
          L(
            'Pronto: este chat recebe as aprovações, as perguntas dos agentes e o fim das rotinas. Pra responder a uma pergunta, responda à mensagem dela.',
            "Done: this chat gets the approvals, the agents' questions and the end of routines. To answer a question, reply to its message."
          )
        )
        return
      }
      if (m.chat.id !== this.chat.id) return
      const asked = m.reply_to_message && this.questions.get(m.reply_to_message.message_id)
      if (asked) {
        this.deps.answer(asked.conversationId, m.text, asked.threadId)
        await this.send(L('Mandei a sua resposta.', 'I sent your answer.'), { reply_to_message_id: m.message_id })
      } else {
        await this.send(L('Pra responder a um agente, responda à mensagem da pergunta (deslize pro lado). Aprovações têm botões.', "To answer an agent, reply to the question's message (swipe it sideways). Approvals have buttons."))
      }
      return
    }

    const q = u.callback_query
    if (!q?.data || !this.chat || q.message?.chat.id !== this.chat.id) return
    const [kind, id, action] = q.data.split(':')
    const ap = kind === 'ap' && id ? this.deps.approval(id) : undefined
    const edit = (text: string, buttons?: unknown): Promise<unknown> =>
      this.api('editMessageText', { chat_id: this.chat!.id, message_id: q.message!.message_id, text, ...(buttons ? { reply_markup: buttons } : {}) })
    if (!ap || ap.state !== 'pending') {
      await this.api('answerCallbackQuery', { callback_query_id: q.id, text: L('Esse pedido já foi decidido.', 'That request was already decided.') })
      if (ap) await edit(`${approvalText(ap)}\n\n${ap.state === 'approved' ? L('✅ Aprovado', '✅ Approved') : ap.state === 'refused' ? L('❌ Recusado', '❌ Refused') : L('Expirou', 'Expired')}`).catch(() => {})
      return
    }
    if (action === 'ok' && ap.highRisk) {
      // In the app this needs a long press; here, a second tap.
      await this.api('answerCallbackQuery', { callback_query_id: q.id })
      await edit(`${approvalText(ap)}\n\n${L('⚠️ Alto risco. Tem certeza?', '⚠️ High risk. Are you sure?')}`, {
        inline_keyboard: [[{ text: L('Sim, executar', 'Yes, run it'), callback_data: `ap:${ap.id}:sure` }, { text: L('Recusar', 'Refuse'), callback_data: `ap:${ap.id}:no` }]]
      })
      return
    }
    const approve = action === 'ok' || action === 'sure'
    await this.api('answerCallbackQuery', { callback_query_id: q.id, text: approve ? L('Aprovado', 'Approved') : L('Recusado', 'Refused') })
    await edit(`${approvalText(ap)}\n\n${approve ? L('✅ Aprovado pelo Telegram', '✅ Approved from Telegram') : L('❌ Recusado pelo Telegram', '❌ Refused from Telegram')}`)
    await this.deps.decide(ap.id, approve ? 'approved' : 'refused', approve ? undefined : L('Recusado pelo Telegram', 'Refused from Telegram'))
  }

  private async send(text: string, extra: Record<string, unknown> = {}): Promise<number | undefined> {
    if (!this.chat) return undefined
    const r = (await this.api('sendMessage', { chat_id: this.chat.id, text: clip(text), ...extra }).catch((e: unknown) => console.error('[telegram]', e))) as { message_id?: number } | undefined
    return r?.message_id
  }

  // ---------- what goes to the phone ----------

  async approvalAsked(ap: Approval, agentName: string): Promise<void> {
    await this.send(`${L(`${agentName} pede aprovação`, `${agentName} asks for approval`)}\n\n${approvalText(ap)}`, {
      reply_markup: { inline_keyboard: [[{ text: L('Aprovar', 'Approve'), callback_data: `ap:${ap.id}:ok` }, { text: L('Recusar', 'Refuse'), callback_data: `ap:${ap.id}:no` }]] }
    })
  }

  async questionAsked(msg: Message, agentName: string, where: string): Promise<void> {
    const questions = questionsOf(msg.run)
    if (!questions.length) return
    const text = questionsAsText(questions)
    const id = await this.send(
      L(`${agentName} pergunta (${where}):\n\n${text}\n\nResponda a esta mensagem.`, `${agentName} asks (${where}):\n\n${text}\n\nReply to this message.`),
      { reply_markup: { force_reply: true, input_field_placeholder: L('Sua resposta', 'Your answer') } }
    )
    if (id) this.questions.set(id, { conversationId: msg.conversationId, ...(msg.threadId ? { threadId: msg.threadId } : {}) })
  }

  async notice(title: string, body: string): Promise<void> {
    for (const chunk of splitIntoChunks(`${title}\n\n${body}`, MAX_TEXT)) await this.send(chunk)
  }
}

function approvalText(ap: Approval): string {
  const args = JSON.stringify(ap.args, null, 1)
  return `${ap.connectorName} · ${ap.tool}${ap.why ? `\n${L('Motivo', 'Reason')}: ${ap.why}` : ''}\n\n${args.length > 1500 ? `${args.slice(0, 1500)}…` : args}`
}

const clip = (s: string): string => (s.length > MAX_TEXT ? `${s.slice(0, MAX_TEXT)}…` : s)

// Cuts at the last line break that fits, and drops it; a line longer than maxLength is cut at maxLength.
export function splitIntoChunks(text: string, maxLength: number): string[] {
  const chunks: string[] = []
  let remaining = text

  while (remaining.length > maxLength) {
    const lineBreak = remaining.lastIndexOf('\n', maxLength)
    const endsAtLineBreak = lineBreak > 0
    const end = endsAtLineBreak ? lineBreak : maxLength

    chunks.push(remaining.slice(0, end))
    remaining = remaining.slice(endsAtLineBreak ? end + 1 : end)
  }

  chunks.push(remaining)
  return chunks
}