feat(telegram): Telegram versions of inbox-buddy, joke-bot, spotify-releases, hn-monitor

Merged
KH
4mo ago
+1747-11

Adds Telegram-transport siblings of the personal-use agents, so you can run them over Telegram instead of (or alongside) Slack. Each is a separate deployable persona that reuses its base agent's transport-agnostic logic and swaps the Slack transport for a shared Telegram transport — every deploy needs only ONE chat surface.

What's here

  • shared/telegram.ts — shared transport over @relayfile/relay-helpers telegramClient() (the generic providerClient; there's no ergonomic telegram client yet — see relayfile-adapters#222). Provides message parsing, bareChatId (__title suffix strip), conversation keying, bot-loop / wrong-chat / empty guards, and a send() / replyToMessage() wrapper that threads natively via reply_to_message_id. (tsconfig now includes shared/.)
  • inbox-buddy-telegram — reuses ../inbox-buddy/lib/{gmail,prompt,conversation}; Gmail Q&A over Telegram. Trigger telegram: message; scope /telegram/chats/**.
  • joke-bot-telegram — conversational jokes + daily joke-of-the-day; sandbox:false (HTTP writeback, no Daytona box).
  • spotify-releases-telegram — daily new-releases message to a Telegram chat.
  • hn-monitor-telegram — threaded digest (count header + reply_to_message_id) + Q&A over recent posts; claims "seen" before posting and never throws once the header lands (no duplicate header on retry).
  • tests/telegram-agents.test.mjs — transport + one-or-more path per agent. Full suite 156/156 green, typecheck clean, all four personas compile.

Auth / deploy

Telegram auth is a Nango bot-token connection (@BotFather). The trigger/scope catalog cutover to formally recognize telegram is tracked in relayfile-adapters#222 and workforce#249 — authoring works today via persona-kit's provider index-signature fallback, and personas compile; the deploy target must have the telegram adapter registered.

Approach (separate Telegram persona per agent, reusing the transport-agnostic lib) was chosen with the requester.

🤖 Generated with Claude Code

Summary by cubic

Adds Telegram-transport siblings for inbox-buddy, joke-bot, spotify-releases, and hn-monitor using a shared Telegram transport with native threading. Now uses telegramClient().sendMessage() from @relayfile/relay-helpers@0.4.2 for simple, idempotent writeback; added READMEs and graphics for each persona.

  • New Features

    • shared/telegram.ts: wrapper over telegramClient().sendMessage() with parsing, bareChatId, conversation keys, loop/wrong-chat/empty guards, and send()/replyToMessage() (threads via reply_to_message_id and forum threadId).
    • Agents:
      • inbox-buddy-telegram: Gmail Q&A; reuses ../inbox-buddy/lib/{gmail,prompt,conversation}; trigger telegram: message; optional TELEGRAM_CHAT.
      • joke-bot-telegram: conversational jokes + daily cron; per-conversation memory; sandbox:false (HTTP writeback).
      • spotify-releases-telegram: daily new releases to TELEGRAM_CHAT; requires SPOTIFY_TOKEN; no model.
      • hn-monitor-telegram: cron digest + Q&A; posts a count header then threads the digest; claims “seen” before posting; retries pending bodies without duplicating the header.
    • Docs & assets: READMEs with launch badges and avatars/banners/cards for each Telegram persona.
    • Tests: tests/telegram-agents.test.mjs cover transport and key flows; tsconfig.json includes shared/*.ts.

  • Migration

    • Auth: Telegram via a Nango bot token (@BotFather). Ensure the deploy target registers the Telegram adapter (relayfile-adapters#222, workforce#249).
    • Scope Telegram to /telegram/chats/** so the writeback path mounts.
    • Inputs: TELEGRAM_CHAT for delivery; SPOTIFY_TOKEN required for spotify-releases.