Files
archie/internal/channels/telegram/telegram.go
T
sam e5105280ad chore(config): remove token_env aliases for forge, artifacts and telegram
Each credential is now only a {engine, key} secret reference. A stale
token_env in a file is reported at startup as an unrecognised key.
nats.token_env stays (no secret-ref form), and providers.api_key_env stays:
it is the carrier the resolver writes each resolved key's env name into.
2026-09-24 23:58:26 +10:00

958 lines
36 KiB
Go

// Package telegram implements gateway.Gateway using the Telegram Bot API
// via go-telegram/bot. Ported from GopherClaw's telegram.go and adapted
// for archie-core's gateway architecture.
package telegram
import (
"context"
"encoding/json"
"errors"
"fmt"
"log/slog"
"net/http"
"runtime/debug"
"slices"
"strings"
"sync"
"sync/atomic"
"time"
"github.com/go-telegram/bot"
"github.com/go-telegram/bot/models"
"github.com/samcharles93/archie-core/internal/channels"
"github.com/samcharles93/archie-core/internal/domain/messaging"
"github.com/samcharles93/archie-core/internal/releaseupdate"
)
// Gateway is a Telegram gateway.Gateway backed by go-telegram/bot.
type Gateway struct {
Token string
// AllowedUserIDs lists the Telegram user IDs allowed to use the bot,
// matched against the sender rather than the chat so the bot cannot be
// reached by adding it to a group. Empty denies everyone: a bot handle
// is public, and chat tools run with the daemon's authority, so failing
// open would expose those tools to any stranger who finds the bot.
AllowedUserIDs []int64
// Reload re-reads configuration during /restart and applies it to g.
// Supplied by the composition root, which owns config paths. Nil
// restarts with the settings already in memory.
Reload func(*Gateway) error
// ReleaseAnnouncements sends one-time upgrade notes to authorized users.
// It is supplied by the composition root because version, changelog, and
// persistence paths are deployment concerns.
ReleaseAnnouncements ReleaseAnnouncer
// Version reports installed component versions. The composition root owns
// build metadata; Telegram only renders it for authorized users.
Version func() string
// Updates is injected by the composition root. It owns release discovery,
// deferral persistence, and installation; Telegram only presents it.
Updates UpdateService
// Settings executes control-plane commands in this authenticated adapter.
Settings *messaging.SettingsCommand
// ResolveActor maps a channel-native sender to an authenticated Archie
// identity. Nil deliberately permits reads but makes writes fail closed.
ResolveActor func(int64) (string, bool)
// UpdateReportPath is where the update watchdog (see
// scripts/archie-update-watchdog) leaves the phase-2 outcome of an
// update -- whether the restarted daemon came up healthy or was rolled
// back. Checked and relayed on every gateway launch (process boot and
// /restart alike), same as ReleaseAnnouncements. Empty disables it.
UpdateReportPath string
// RunningVersions reports, per component ID (see
// releaseupdate.ComponentDaemon), the version that component reports for
// itself rather than the version an installer claimed to install. It is
// what turns a pending update report from a self-reported claim into a
// checked one: the daemon's own compiled-in build version cannot be
// talked out of being what is actually running. Only components that can
// genuinely self-report belong here -- a guess would re-introduce
// exactly the false success this check exists to catch. Nil leaves every
// claim unverified.
RunningVersions func() map[string]string
// Dangerous is the sandbox/process authority for /rollback and /stop.
// When nil, those commands return "not configured". The composition
// root supplies this; Telegram only renders approval UX.
Dangerous DangerousCommandAuthority
// showToolCalls controls whether new live replies render completed tool
// calls. Each reply snapshots it so reloads affect only later turns.
showToolCalls atomic.Bool
// restartCh carries /restart requests from a bot handler to the
// supervisor loop in Start. Buffered so a handler never blocks.
restartCh chan restartRequest
pendingRestart *restartRequest
modelMu sync.RWMutex
modelCallbacks map[string]string
modelPages map[string]modelPage
providerMu sync.RWMutex
providerCallbacks map[string]string
updateMu sync.Mutex
updateInProgress bool
updateActions map[string]updateAction
updateReportMu sync.Mutex
// dangerous command approval state
dangerousMu sync.Mutex
dangerousActions map[string]dangerousAction
permanentApprovals []permanentApproval
// tool approval state (gateway.ApprovalRequester). Kept separate from
// the dangerous-command state above: tool approvals deliver the human's
// decision on a channel to the blocked RequestApproval call rather than
// executing through an onApprove callback.
approvalMu sync.Mutex
pendingApprovals map[string]*pendingApproval
// turns serialises chat turns per session off the update worker and
// makes the running one cancellable by /stop. Rebuilt on every launch
// so a restart abandons in-flight turns with the old bot instance.
turns *messaging.Turns
// liveMu guards liveReplies and liveStopped.
liveMu sync.Mutex
// liveReplies tracks every liveReply currently mid-turn. Cancelling
// turnCtx (a /restart, a daemon shutdown) does not guarantee the
// goroutine that owns a liveReply ever runs again to notice and clean
// up after itself -- a full process exit gives it no chance at all --
// so Stop drains this registry directly rather than waiting on that
// goroutine. See abandonAllLive. The map itself survives a /restart
// (only turns above is rebuilt per launch); liveStopped is what scopes
// draining to one launch's lifecycle.
liveReplies map[*liveReply]struct{}
// liveDrainTimeout bounds abandonAllLive's wait for in-flight replies to
// be marked. Zero uses abandonAllLiveTimeout; tests shrink it so a
// deliberately-hung reply doesn't make the suite slow.
liveDrainTimeout time.Duration
// liveStopped is set the instant abandonAllLive claims the registry, so
// a newLiveReply that arrives in the narrow window between that claim
// and its caller actually registering is abandoned immediately instead
// of being added to a registry nothing will ever drain again. Reset to
// false at the start of the next launch.
liveStopped bool
log *slog.Logger
bot *bot.Bot
running bool
// serverURL redirects the Bot API at a test server. Empty in production,
// where the library's default endpoint is used. It exists so launch's
// wiring can be tested without reaching api.telegram.org.
serverURL string
}
type UpdateService interface {
Check(context.Context, int64) (releaseupdate.Snapshot, error)
Defer(context.Context, int64, releaseupdate.Snapshot) error
Install(context.Context, releaseupdate.Snapshot, releaseupdate.InstallMeta, func(string)) (releaseupdate.Result, error)
CanInstall() bool
}
type ReleaseAnnouncer interface {
Announce(
ctx context.Context,
recipients []int64,
send func(context.Context, int64, string) error,
) error
}
// New returns an unstarted Gateway. Call Start to begin long-polling.
func New(token string, allowedUserIDs []int64, log *slog.Logger) *Gateway {
return &Gateway{
Token: token,
AllowedUserIDs: allowedUserIDs,
restartCh: make(chan restartRequest, 1),
modelCallbacks: make(map[string]string),
modelPages: make(map[string]modelPage),
providerCallbacks: make(map[string]string),
updateActions: make(map[string]updateAction),
dangerousActions: make(map[string]dangerousAction),
permanentApprovals: nil,
pendingApprovals: make(map[string]*pendingApproval),
log: log.With("component", "gateway-telegram"),
}
}
func (g *Gateway) Name() string { return "telegram" }
// SetShowToolCalls controls tool visibility for replies created after the call.
func (g *Gateway) SetShowToolCalls(show bool) {
g.showToolCalls.Store(show)
}
// ShowToolCalls reports the visibility setting that a new reply must snapshot.
func (g *Gateway) ShowToolCalls() bool {
return g.showToolCalls.Load()
}
// RequestRestart asks the gateway supervisor to reload this adapter. It is
// safe for callers outside Telegram (such as the local Web UI) and never
// blocks when a restart is already queued.
func (g *Gateway) RequestRestart() error {
select {
case g.restartCh <- restartRequest{}:
return nil
default:
return errors.New("telegram gateway restart already in progress")
}
}
// Start supervises the bot: it launches an instance and relaunches it
// whenever a restart is requested, blocking until ctx is cancelled.
//
// Restarts are scoped to this gateway. The daemon keeps running, so
// in-flight agent tasks are untouched -- the whole point of the escape
// hatch is to recover chat without disturbing work in progress.
func (g *Gateway) Start(ctx context.Context, client messaging.ChatContract, lifecycle channels.Lifecycle) error {
if g.Token == "" {
return fmt.Errorf("telegram bot token is required")
}
g.log.Info("starting telegram gateway")
for {
lifecycle.ReportStarting()
runCtx, cancel := context.WithCancel(ctx)
b, err := g.launch(runCtx, client, lifecycle)
if err != nil {
cancel()
return err
}
// Confirm to whoever asked, now that the new instance can send.
if req := g.pendingRestart; req != nil && req.chatID != 0 {
g.sendMessage(runCtx, b, req.chatID, req.threadID, "✅ Archie reloaded.")
}
if g.pendingRestart != nil {
g.pendingRestart = nil
}
select {
case <-ctx.Done():
cancel()
return g.Stop(context.WithoutCancel(ctx))
case req := <-g.restartCh:
g.log.Info("restarting telegram gateway", "requested_by", req.chatID)
cancel()
if err := g.Stop(context.WithoutCancel(ctx)); err != nil {
g.log.Warn("stop during restart failed", "error", err)
}
if g.Reload != nil {
if err := g.Reload(g); err != nil {
// Keep the previous settings rather than dying: a bad
// config edit must not take the gateway down for good.
g.log.Error("config reload failed, restarting with previous settings", "error", err)
}
}
g.pendingRestart = &req
}
}
}
// telegramTextHandler is one text command the Telegram adapter answers itself,
// before the shared router sees it.
type telegramTextHandler struct {
command string
match bot.MatchType
build func(*Gateway, messaging.ChatContract) bot.HandlerFunc
}
// telegramTextHandlers is the single source for the commands Telegram answers
// locally. Registration reads it, and so does
// TestPublishedCommandsMatchExecutableSurface, which proves the published menu
// covers the executable surface: a handler added here without a spec in
// gatewayCommandSpecs fails that test, so a command cannot become typeable
// without becoming discoverable.
var telegramTextHandlers = []telegramTextHandler{
{"/status", bot.MatchTypeExact, func(g *Gateway, c messaging.ChatContract) bot.HandlerFunc { return g.statusHandler(c) }},
{"/whoami", bot.MatchTypeExact, func(g *Gateway, c messaging.ChatContract) bot.HandlerFunc { return g.whoamiHandler(c) }},
{"/profile", bot.MatchTypeExact, func(g *Gateway, c messaging.ChatContract) bot.HandlerFunc { return g.profileHandler(c) }},
{"/sessions", bot.MatchTypeExact, func(g *Gateway, c messaging.ChatContract) bot.HandlerFunc { return g.sessionsHandler(c) }},
{"/resume", bot.MatchTypeExact, func(g *Gateway, c messaging.ChatContract) bot.HandlerFunc { return g.resumeHandler(c) }},
{"/agents", bot.MatchTypeExact, func(g *Gateway, c messaging.ChatContract) bot.HandlerFunc { return g.agentsHandler(c) }},
{"/version", bot.MatchTypeExact, func(g *Gateway, _ messaging.ChatContract) bot.HandlerFunc { return g.versionHandler() }},
{"/update", bot.MatchTypeExact, func(g *Gateway, _ messaging.ChatContract) bot.HandlerFunc { return g.updateHandler() }},
{"/settings", bot.MatchTypePrefix, func(g *Gateway, _ messaging.ChatContract) bot.HandlerFunc { return g.settingsHandler() }},
{"/start", bot.MatchTypeExact, func(g *Gateway, _ messaging.ChatContract) bot.HandlerFunc { return g.startHandler() }},
{"/help", bot.MatchTypeExact, func(g *Gateway, _ messaging.ChatContract) bot.HandlerFunc { return g.helpHandler() }},
{"/restart", bot.MatchTypeExact, func(g *Gateway, _ messaging.ChatContract) bot.HandlerFunc { return g.restartHandler() }},
{"/rollback", bot.MatchTypePrefix, func(g *Gateway, _ messaging.ChatContract) bot.HandlerFunc { return g.rollbackHandler() }},
{"/stop", bot.MatchTypePrefix, func(g *Gateway, c messaging.ChatContract) bot.HandlerFunc { return g.stopHandler(c) }},
{"/approve", bot.MatchTypeExact, func(g *Gateway, _ messaging.ChatContract) bot.HandlerFunc { return g.approveHandler() }},
{"/deny", bot.MatchTypeExact, func(g *Gateway, _ messaging.ChatContract) bot.HandlerFunc { return g.denyHandler() }},
}
func (g *Gateway) registerCommandHandlers(b *bot.Bot, client messaging.ChatContract) {
for _, handler := range telegramTextHandlers {
b.RegisterHandler(bot.HandlerTypeMessageText, handler.command, handler.match, handler.build(g, client))
}
}
func (g *Gateway) startListening(ctx context.Context, b *bot.Bot, _ channels.Lifecycle) error {
g.dropPendingUpdates(ctx, b)
g.running = true
go b.Start(ctx)
return nil
}
// launch builds one bot instance, registers handlers and starts its
// long-poll delivery worker. Readiness is reported by pollReadinessClient
// after the first successful getUpdates response.
func (g *Gateway) launch(ctx context.Context, client messaging.ChatContract, lifecycle channels.Lifecycle) (*bot.Bot, error) {
// Turns are per-launch. Each queued turn carries the update handler's
// context, which is this launch's, so a /restart cancels everything
// still running under the outgoing bot instance.
g.turns = messaging.NewTurns(g.log)
g.resetLiveRegistry()
opts := []bot.Option{
bot.WithErrorsHandler(g.pipelineErrorHandler(ctx)),
bot.WithDebugHandler(func(format string, args ...any) {
g.log.Debug("telegram debug", "message", fmt.Sprintf(format, args...))
}),
bot.WithDefaultHandler(g.defaultHandler(client)),
bot.WithMiddlewares(g.panicRecoveryMiddleware(), g.updateLoggingMiddleware()),
bot.WithHTTPClient(telegramPollTimeout, &pollReadinessClient{
client: &http.Client{Timeout: telegramPollTimeout},
onRunning: lifecycle.ReportRunning,
}),
}
if g.serverURL != "" {
opts = append(opts, bot.WithServerURL(g.serverURL), bot.WithSkipGetMe())
}
b, err := bot.New(g.Token, opts...)
if err != nil {
return nil, fmt.Errorf("create bot: %w", err)
}
g.bot = b
g.registerCommandHandlers(b, client)
// Publish the command list so Telegram renders a menu. Without this
// the commands are undiscoverable and the LLM, having no idea they
// exist, tells users there are none.
g.registerCommands(ctx, b)
g.notifyLaunch(ctx, b)
if err := g.startListening(ctx, b, lifecycle); err != nil {
return nil, err
}
return b, nil
}
// notifyLaunch sends the one-time notifications that belong to every
// gateway launch, not just a process boot: a newly installed release's
// changelog, and the phase-2 outcome of an update the watchdog finished
// while this gateway was down.
func (g *Gateway) notifyLaunch(ctx context.Context, b *bot.Bot) {
g.announceRelease(ctx, b)
g.reportPendingUpdate(ctx, b)
go g.watchPendingUpdate(ctx, b)
}
// watchPendingUpdate closes the watchdog/startup race: the watchdog writes
// the health result only after this process answers its health probe, so the
// launch-time read can miss the report for the boot it describes.
func (g *Gateway) watchPendingUpdate(ctx context.Context, b *bot.Bot) {
ticker := time.NewTicker(2 * time.Second)
defer ticker.Stop()
for {
select {
case <-ctx.Done():
return
case <-ticker.C:
g.reportPendingUpdate(ctx, b)
}
}
}
func (g *Gateway) announceRelease(ctx context.Context, b *bot.Bot) {
if g.ReleaseAnnouncements == nil {
return
}
err := g.ReleaseAnnouncements.Announce(
ctx,
slices.Clone(g.AllowedUserIDs),
func(ctx context.Context, recipient int64, message string) error {
_, err := b.SendMessage(ctx, &bot.SendMessageParams{
ChatID: recipient,
Text: message,
})
return err
},
)
if err != nil {
// Notifications are ancillary to chat availability. Keep the gateway
// running and let the announcer retry unrecorded recipients next time.
g.log.Warn("release announcement failed", "error", err)
}
}
// Stop gracefully shuts down the bot.
func (g *Gateway) Stop(ctx context.Context) error {
if !g.running {
return nil
}
g.log.Info("stopping telegram gateway")
g.running = false
g.abandonAllLive(ctx)
return nil
}
// ── command handlers (gateway-local -- no LLM) ────────────────
func (g *Gateway) statusHandler(client messaging.ChatContract) bot.HandlerFunc {
return g.routeCmdHandler(client, "/status")
}
func (g *Gateway) whoamiHandler(client messaging.ChatContract) bot.HandlerFunc {
return g.routeCmdHandler(client, "/whoami")
}
func (g *Gateway) profileHandler(client messaging.ChatContract) bot.HandlerFunc {
return g.routeCmdHandler(client, "/profile")
}
func (g *Gateway) sessionsHandler(client messaging.ChatContract) bot.HandlerFunc {
return g.routeCmdHandler(client, "/sessions")
}
func (g *Gateway) agentsHandler(client messaging.ChatContract) bot.HandlerFunc {
return g.routeCmdHandler(client, "/agents")
}
func (g *Gateway) resumeHandler(client messaging.ChatContract) bot.HandlerFunc {
return func(ctx context.Context, b *bot.Bot, update *models.Update) {
msg, ok := g.authorizedMessage(ctx, b, update)
if !ok {
return
}
reply, err := client.Route(ctx, messaging.Inbound{Platform: "telegram", Message: messaging.Message{
ConversationID: conversationID(msg),
Sender: msg.From.Username,
Role: messaging.RoleUser,
Text: msg.Text,
}})
if err != nil {
g.log.Error("resume handler failed", "error", err)
return
}
g.sendMessage(ctx, b, msg.Chat.ID, msg.MessageThreadID, reply.Text)
}
}
// routeCmdHandler builds a handler that routes a fixed command through the
// messaging.ChatContract and sends the reply.
func (g *Gateway) routeCmdHandler(client messaging.ChatContract, cmd string) bot.HandlerFunc {
return func(ctx context.Context, b *bot.Bot, update *models.Update) {
msg, ok := g.authorizedMessage(ctx, b, update)
if !ok {
return
}
reply, err := client.Route(ctx, messaging.Inbound{Platform: "telegram", Message: messaging.Message{
ConversationID: conversationID(msg),
Sender: msg.From.Username,
Role: messaging.RoleUser,
Text: cmd,
}})
if err != nil {
g.log.Error("command handler failed", "command", cmd, "error", err)
return
}
g.sendMessage(ctx, b, msg.Chat.ID, msg.MessageThreadID, reply.Text)
}
}
func (g *Gateway) settingsHandler() bot.HandlerFunc {
return func(ctx context.Context, b *bot.Bot, update *models.Update) {
msg, ok := g.authorizedMessage(ctx, b, update)
if !ok {
return
}
actor := ""
if g.ResolveActor != nil {
actor, _ = g.ResolveActor(msg.From.ID)
}
input := strings.TrimSpace(strings.TrimPrefix(msg.Text, "/settings"))
reply := g.Settings.Execute(ctx, actor, input)
g.sendMessage(ctx, b, msg.Chat.ID, msg.MessageThreadID, reply)
}
}
func (g *Gateway) versionHandler() bot.HandlerFunc {
return func(ctx context.Context, b *bot.Bot, update *models.Update) {
msg, ok := g.authorizedMessage(ctx, b, update)
if !ok {
return
}
if g.Version == nil {
g.sendMessage(ctx, b, msg.Chat.ID, msg.MessageThreadID, "Version information is not configured.")
return
}
g.sendMessage(ctx, b, msg.Chat.ID, msg.MessageThreadID, g.Version())
}
}
func (g *Gateway) helpHandler() bot.HandlerFunc {
return func(ctx context.Context, b *bot.Bot, update *models.Update) {
msg, ok := g.authorizedMessage(ctx, b, update)
if !ok {
return
}
g.sendMessage(ctx, b, msg.Chat.ID, msg.MessageThreadID, gatewayHelpText())
}
}
func (g *Gateway) startHandler() bot.HandlerFunc {
return func(ctx context.Context, b *bot.Bot, update *models.Update) {
msg, ok := g.authorizedMessage(ctx, b, update)
if !ok {
return
}
g.sendMessage(ctx, b, msg.Chat.ID, msg.MessageThreadID,
"Archie is running. Send a message to chat, or type /help for available commands.")
}
}
// ── default handler (non-command text → router) ─────────────
func (g *Gateway) defaultHandler(client messaging.ChatContract) bot.HandlerFunc {
return func(ctx context.Context, b *bot.Bot, update *models.Update) {
if update.CallbackQuery != nil {
g.handleCallback(ctx, b, update, client)
return
}
msg, ok := g.authorizedMessage(ctx, b, update)
if !ok || msg.Text == "" {
return
}
if isModelSelectorRequest(msg.Text) {
g.sendProviderSelector(ctx, b, msg, client)
return
}
if isModelCommand(msg.Text) {
g.handleModelCommand(ctx, b, msg, client)
return
}
if isPersonalityRequest(msg.Text) {
g.handlePersonalityCommand(ctx, b, msg, client)
return
}
g.submitTurn(ctx, b, msg, client)
}
}
// handleCallback dispatches an inline-button callback query to the handler
// for its prefix. Callback prefixes are mutually exclusive; an unknown
// callback is ignored.
func (g *Gateway) handleCallback(ctx context.Context, b *bot.Bot, update *models.Update, client messaging.ChatContract) {
switch {
case strings.HasPrefix(update.CallbackQuery.Data, approvalCallbackPrefix):
g.handleApprovalCallback(ctx, b, update)
case strings.HasPrefix(update.CallbackQuery.Data, dangerousCmdPrefix):
g.handleDangerousCallback(ctx, b, update)
case strings.HasPrefix(update.CallbackQuery.Data, providerCallbackPrefix):
g.handleProviderCallback(ctx, b, update, client)
case strings.HasPrefix(update.CallbackQuery.Data, modelCallbackPrefix):
g.handleModelCallback(ctx, b, update, client)
case strings.HasPrefix(update.CallbackQuery.Data, modelPageCallbackPrefix):
g.handleModelPageCallback(ctx, b, update, client)
case update.CallbackQuery.Data == modelBackCallback:
g.handleModelBackCallback(ctx, b, update, client)
case update.CallbackQuery.Data == modelCancelCallback:
g.handleModelCancelCallback(ctx, b, update)
case update.CallbackQuery.Data == modelNoopCallback:
g.handleModelNoopCallback(ctx, b, update)
case strings.HasPrefix(update.CallbackQuery.Data, personalityCallbackPrefix):
g.handlePersonalityCallback(ctx, b, update, client)
case strings.HasPrefix(update.CallbackQuery.Data, updateCallbackPrefix):
g.handleUpdateCallback(ctx, b, update)
}
}
// submitTurn hands the message to its session's turn lane and returns at
// once, leaving the bot's single update worker free.
//
// The turn must not run on the caller's goroutine. go-telegram/bot serves
// updates from one worker that invokes handlers synchronously, so a turn
// running here would block delivery of every later update -- including the
// /stop meant to cancel it, which would sit unread until the turn it was
// aimed at had already finished.
func (g *Gateway) submitTurn(ctx context.Context, b *bot.Bot, msg *models.Message, client messaging.ChatContract) {
gm := messaging.Inbound{Platform: "telegram", Message: messaging.Message{
// Telegram's message ID makes persistence idempotent: the store
// derives a canonical ID from it, so a redelivered update is a
// no-op rather than appending a duplicate or overwriting the
// stored record, which must stay immutable. Date is the sender's
// clock reading and is what history should be ordered by.
SourceID: fmt.Sprintf("%d", msg.ID),
ConversationID: conversationID(msg),
Sender: msg.From.Username,
SenderID: fmt.Sprintf("%d", msg.From.ID),
Role: messaging.RoleUser,
Text: msg.Text,
At: time.Unix(int64(msg.Date), 0).UTC(),
}}
// The lane key must be the session, so that /stop -- which resolves
// the same key -- reaches the turn the sender is actually watching.
session := conversationID(msg).String()
chatID, threadID := msg.Chat.ID, msg.MessageThreadID
g.turns.Submit(ctx, session, func(turnCtx context.Context) {
// If the turn invokes a tool that requires human approval,
// the dispatch layer blocks on this approver. Nil is fine
// — most turns need no gating.
approver := g.NewApprover(b, chatID, threadID, msg.From.ID)
turnCtx = messaging.WithApprovalRequester(turnCtx, approver)
// reply appears as it is written; the typing indicator covers the
// gap before the first token and any non-streaming path.
stopTyping := g.startTyping(turnCtx, b, chatID, threadID)
live := g.newLiveReply(turnCtx, b, chatID, threadID, g.ShowToolCalls())
events, err := client.Stream(turnCtx, gm)
if err != nil {
stopTyping()
if errors.Is(err, context.Canceled) || errors.Is(turnCtx.Err(), context.Canceled) {
g.log.Info("chat turn stopped", "session", session)
live.abandon(turnCtx)
} else {
g.log.Error("stream failed", "error", err)
live.abandonFailed(turnCtx)
}
return
}
var reply string
var streamErr error
for ev := range events {
switch ev.Kind {
case "delta":
live.Delta(ev.Text)
case "tool":
live.ToolCall(ev.Tool)
case "media":
live.Media(turnCtx, ev.Media)
case "done":
reply = ev.Text
case "error":
streamErr = errors.New(ev.Text)
}
}
stopTyping()
// A cancelled turn is a /stop, not a fault. The stop handler has
// already acknowledged it, and turnCtx is dead, so there is
// nothing useful left to send from here -- but whatever was
// already streamed stays, minus the cursor that would otherwise
// claim the answer is still being written. abandon strips turnCtx's
// own cancellation before it edits, so the cursor-drop is not itself
// aborted by the /stop that triggered it.
//
// errors.Is(err, context.Canceled) reliably separates a /stop from a
// fault; either way turnCtx is dead by the time we get here. A
// genuine fault is marked as failed rather than left as a clean
// partial: /stop is an acknowledged interruption, a provider error
// is not, and an unmarked partial reads as a finished answer either
// way.
if streamErr != nil || turnCtx.Err() != nil {
if errors.Is(turnCtx.Err(), context.Canceled) || (streamErr != nil && errors.Is(streamErr, context.Canceled)) {
g.log.Info("chat turn stopped", "session", session)
live.abandon(turnCtx)
} else {
g.log.Error("stream turn failed", "error", streamErr)
live.abandonFailed(turnCtx)
}
return
}
live.finalize(turnCtx, reply)
})
}
// ── helpers ──────────────────────────────────────────────────
// conversationID addresses the chat a Telegram message arrived in: the
// chat ID, and the topic thread within it for supergroups.
func conversationID(msg *models.Message) messaging.ConversationID {
return messaging.ConversationID{
ChannelID: fmt.Sprintf("%d", msg.Chat.ID),
ThreadID: threadIDString(msg.MessageThreadID),
}
}
// threadIDString converts a Telegram message_thread_id to a string suitable
// for messaging.ConversationID.ThreadID and SessionSource.ThreadID. A zero
// value (no topic thread, or the General topic) maps to empty string so that
// flat-chat routing continues to work without changes.
func threadIDString(id int) string {
if id == 0 {
return ""
}
return fmt.Sprintf("%d", id)
}
func (g *Gateway) authorizedMessage(ctx context.Context, b *bot.Bot, update *models.Update) (*models.Message, bool) {
if update.Message == nil || update.Message.From == nil {
return nil, false
}
if g.isSenderAllowed(update.Message.From.ID) {
return update.Message, true
}
g.log.Warn(
"message from unauthorized sender",
"user_id", update.Message.From.ID,
"username", update.Message.From.Username,
"chat_id", update.Message.Chat.ID,
)
// Reply so an authorised user who is simply missing from the list can
// tell the bot is alive and misconfigured, rather than dead.
g.sendMessage(ctx, b, update.Message.Chat.ID, update.Message.MessageThreadID,
"⛔ You are not authorised to use this bot.")
return nil, false
}
// typingRefresh is how often the typing action is re-sent. Telegram clears
// the indicator after ~5s, so it must be refreshed to stay visible for the
// length of an LLM turn.
const typingRefresh = 4 * time.Second
// startTyping shows the "typing…" indicator and keeps it alive until the
// returned stop function is called. Errors are logged at debug level only:
// a missing typing indicator must never block or fail the actual reply.
func (g *Gateway) startTyping(ctx context.Context, b *bot.Bot, chatID int64, messageThreadID int) (stop func()) {
send := func() {
params := &bot.SendChatActionParams{
ChatID: chatID,
Action: models.ChatActionTyping,
}
if messageThreadID != 0 {
params.MessageThreadID = messageThreadID
}
if _, err := b.SendChatAction(ctx, params); err != nil {
g.log.Debug("send chat action failed", "error", err)
}
}
typingCtx, cancel := context.WithCancel(ctx)
send()
go func() {
ticker := time.NewTicker(typingRefresh)
defer ticker.Stop()
for {
select {
case <-typingCtx.Done():
return
case <-ticker.C:
send()
}
}
}()
return cancel
}
// isSenderAllowed reports whether a message's sender may use the bot.
// An empty allowlist denies everyone (see Gateway.AllowedUserIDs).
func (g *Gateway) isSenderAllowed(userID int64) bool {
return slices.Contains(g.AllowedUserIDs, userID)
}
// messageMaxLen keeps a single message under Telegram's 4096 character
// limit, with room for the continuation marker split adds.
const messageMaxLen = 4000
// telegramRenderVersion identifies the renderer applied to outgoing Telegram
// messages. It is included in the per-send log line so an old deployment
// cannot be mistaken for the current code when diagnosing rendering
// differences.
const telegramRenderVersion = "rich-markdown-v2"
func (g *Gateway) sendMessage(ctx context.Context, b *bot.Bot, chatID int64, messageThreadID int, text string) {
blocks := markdownToBlocks(text)
if total := blockTextLen(blocks); total <= messageMaxLen {
g.sendBlocks(ctx, b, chatID, messageThreadID, blocks, "send message failed")
return
}
parts := splitBlocks(blocks, messageMaxLen)
for i, part := range parts {
if i < len(parts)-1 {
part = append(part, paragraphBlock("_(continued...)_"))
}
g.sendBlocks(ctx, b, chatID, messageThreadID, part, "send message part failed")
}
}
// sendBlocks delivers one message as a Telegram rich message built from
// structured blocks.
//
// Rich messages are a recent Bot API addition, so a rejection here is treated
// as "unsupported" rather than fatal: fall back to sending the blocks as plain
// text so the user still receives the reply, unformatted, instead of silence.
func (g *Gateway) sendBlocks(ctx context.Context, b *bot.Bot, chatID int64, messageThreadID int, blocks []models.InputRichBlock, errMsg string) {
rich := &bot.SendRichMessageParams{
ChatID: chatID,
RichMessage: models.InputRichMessage{Blocks: blocks},
}
if messageThreadID != 0 {
rich.MessageThreadID = messageThreadID
}
if _, err := b.SendRichMessage(ctx, rich); err == nil {
g.log.Debug("telegram message sent", "renderer", telegramRenderVersion, "mode", "rich")
return
} else {
g.log.Warn("rich send failed, retrying unformatted", "error", err)
}
plain := &bot.SendMessageParams{ChatID: chatID, Text: strings.Join(blocksToPlainText(blocks), "\n\n")}
if messageThreadID != 0 {
plain.MessageThreadID = messageThreadID
}
if _, err := b.SendMessage(ctx, plain); err != nil {
g.log.Error(errMsg, "error", err)
} else {
g.log.Warn("telegram message sent via plain fallback", "renderer", telegramRenderVersion, "mode", "plain")
}
}
// blockTextLen is the rune length of a block slice as rendered plain text.
func blockTextLen(blocks []models.InputRichBlock) int {
return len([]rune(strings.Join(blocksToPlainText(blocks), "\n")))
}
// ── middlewares ──────────────────────────────────────────────
func (g *Gateway) panicRecoveryMiddleware() bot.Middleware {
return func(next bot.HandlerFunc) bot.HandlerFunc {
return func(ctx context.Context, b *bot.Bot, update *models.Update) {
defer func() {
if r := recover(); r != nil {
kind, chatID, hasChat := updateMetadata(update)
attrs := []any{
"panic", r,
"update_kind", kind,
"update_id", update.ID,
"stack", string(debug.Stack()),
}
if hasChat {
attrs = append(attrs, "chat_id", chatID)
}
g.log.Error("panic in telegram middleware", attrs...)
}
}()
next(ctx, b, update)
}
}
}
func (g *Gateway) updateLoggingMiddleware() bot.Middleware {
return func(next bot.HandlerFunc) bot.HandlerFunc {
return func(ctx context.Context, b *bot.Bot, update *models.Update) {
kind, chatID, hasChat := updateMetadata(update)
attrs := []any{"update_kind", kind, "update_id", update.ID}
if hasChat {
attrs = append(attrs, "chat_id", chatID)
}
if threadID := updateThreadID(update); threadID != 0 {
attrs = append(attrs, "thread_id", threadID)
}
g.log.Debug("telegram update", attrs...)
next(ctx, b, update)
}
}
}
func updateMetadata(update *models.Update) (kind string, chatID int64, hasChat bool) {
switch {
case update == nil:
return "unknown", 0, false
case update.Message != nil:
return "message", update.Message.Chat.ID, true
case update.CallbackQuery != nil:
if update.CallbackQuery.Message.Message != nil {
return "callback_query", update.CallbackQuery.Message.Message.Chat.ID, true
}
return "callback_query", 0, false
default:
return "other", 0, false
}
}
// updateThreadID extracts the message_thread_id from an update for logging
// and session routing. Returns 0 for flat chats / non-message updates.
func updateThreadID(update *models.Update) int {
if update == nil || update.Message == nil {
return 0
}
return update.Message.MessageThreadID
}
// ConfigSchema returns the JSON Schema for the Telegram channel config.
// The bot token is a secret reference object with engine/key.
func (g *Gateway) ConfigSchema() json.RawMessage {
return json.RawMessage(`{
"type": "object",
"required": ["token"],
"properties": {
"token": {
"type": "object",
"description": "Secret reference for the Telegram bot token from @BotFather, resolved through the configured secret engine.",
"properties": {
"engine": { "type": "string" },
"key": { "type": "string" }
}
},
"allowed_user_ids": {
"type": "array",
"items": { "type": "integer" },
"description": "Restrict bot access to specific Telegram user ids"
}
}
}`)
}
// ValidateConfig checks the Telegram channel configuration. A token
// secret reference is required.
func (g *Gateway) ValidateConfig(cfg map[string]any) error {
if cfg == nil {
return fmt.Errorf("telegram config is required")
}
if _, ok := cfg["token"]; !ok {
return fmt.Errorf("telegram.token is required")
}
return nil
}
// Compile-time guard.
var _ channels.Channel = (*Gateway)(nil)
// dropPendingUpdates clears Telegram's queue of undelivered updates before
// long polling starts.
//
// Telegram holds updates for 24h and replays them on the first getUpdates,
// so without this a daemon that was down overnight boots and answers every
// message sent while it was gone -- one LLM turn each, in a burst. The
// webhook path already passes DropPendingUpdates when it registers; polling
// has no equivalent, so it has to be asked for explicitly. deleteWebhook is
// the call that carries the flag, and it doubles as a guard against a stale
// webhook registration, which would make getUpdates fail with 409.
//
// This also runs on /restart, so a message sent during the restart window is
// discarded rather than answered late. That matches the webhook branch, which
// passes the same flag on every launch.
//
// Best-effort: a failure here is logged, not fatal. Chat availability matters
// more than a clean queue, and the deadline keeps an unreachable Telegram
// from holding up gateway startup.
func (g *Gateway) dropPendingUpdates(ctx context.Context, b *bot.Bot) {
ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
defer cancel()
if _, err := b.DeleteWebhook(ctx, &bot.DeleteWebhookParams{DropPendingUpdates: true}); err != nil {
g.log.Warn("could not drop pending telegram updates, backlog may be replayed", "error", err)
}
}