The menu and /help were generated from a hand-maintained spec list that had drifted from the executable surface: /approve and /deny are real handlers but were published nowhere, while /rollback and /stop are Telegram-only. Registration now reads a single handler table, and a regression test derives the executable set from messaging.LocalCommands() plus that table, failing when the published specs and the executable surface disagree in either direction. /approve and /deny are published with their Telegram meaning, the dangerous-command approval list, not the shared task-approval copy; that split is archie-core-ho86. The two tests that pinned them as hidden commands are updated to the published decision. /help now also asserts it carries every published command's description, not only its usage.
972 lines
36 KiB
Go
972 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 may be supplied either directly as token_env (an
|
|
// environment variable name) or as token (a secret reference object with
|
|
// engine/key); token takes precedence when both are set, matching
|
|
// resolveTelegramToken's own precedence.
|
|
func (g *Gateway) ConfigSchema() json.RawMessage {
|
|
return json.RawMessage(`{
|
|
"type": "object",
|
|
"anyOf": [
|
|
{ "required": ["token_env"] },
|
|
{ "required": ["token"] }
|
|
],
|
|
"properties": {
|
|
"token_env": {
|
|
"type": "string",
|
|
"description": "Environment variable holding the Telegram bot token from @BotFather"
|
|
},
|
|
"token": {
|
|
"type": "object",
|
|
"description": "Secret reference for the bot token, resolved through the configured secret engine. Takes precedence over token_env.",
|
|
"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 is
|
|
// required, supplied either as token (a secret reference) or token_env
|
|
// (an environment variable name) -- either credential source is valid,
|
|
// matching resolveTelegramToken's precedence in the daemon's boot path.
|
|
func (g *Gateway) ValidateConfig(cfg map[string]any) error {
|
|
if cfg == nil {
|
|
return fmt.Errorf("telegram config is required")
|
|
}
|
|
tokenEnv, _ := cfg["token_env"].(string)
|
|
_, hasTokenRef := cfg["token"]
|
|
if tokenEnv == "" && !hasTokenRef {
|
|
return fmt.Errorf("telegram.token or telegram.token_env 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)
|
|
}
|
|
}
|