refactor(telegram): cut comments down to what the code does
This commit is contained in:
1 parent
3500838ac1
commit
d5a1da1213
14 files changed
+123
-613
No files matched your search
@@ -17,14 +17,8 @@ import (
|
||||
// from dangerousCmdPrefix so the two approval systems never collide.
|
||||
const approvalCallbackPrefix = "approval:"
|
||||
|
||||
// telegramApprover implements gateway.ApprovalRequester by rendering an
|
||||
// inline-button prompt in the chat it was built for and blocking until the
|
||||
// human decides, the context is cancelled, or the approval window elapses.
|
||||
//
|
||||
// It generalises the dangerous-command approval machinery: instead of
|
||||
// carrying an onApprove callback that executes a fixed command, a tool
|
||||
// approval carries a result channel that the callback handler signals, and
|
||||
// the blocked RequestApproval caller observes the decision.
|
||||
// telegramApprover implements gateway.ApprovalRequester with an inline-button
|
||||
// prompt, blocking until the human decides, ctx ends or the window elapses.
|
||||
type telegramApprover struct {
|
||||
gw *Gateway
|
||||
bot *bot.Bot
|
||||
@@ -59,11 +53,7 @@ var (
|
||||
_ messaging.CapabilityReporter = (*telegramApprover)(nil)
|
||||
)
|
||||
|
||||
// Capabilities reports that this approver renders a native approval prompt.
|
||||
// It claims Approval only: clarify and picker have no native Telegram UI
|
||||
// wired yet, so claiming them would advertise an interaction this type
|
||||
// cannot carry. A caller that sees Clarify/Picker false uses the shared text
|
||||
// fallback instead of silently dropping the question.
|
||||
// Capabilities reports native approval only.
|
||||
func (a *telegramApprover) Capabilities() messaging.AdapterCapabilities {
|
||||
return messaging.AdapterCapabilities{Approval: true}
|
||||
}
|
||||
@@ -82,13 +72,8 @@ func (g *Gateway) NewApprover(b *bot.Bot, chatID int64, threadID int, recipient
|
||||
}
|
||||
}
|
||||
|
||||
// RequestApproval asks the recipient to approve or deny action.
|
||||
//
|
||||
// A current permanent approval for the action short-circuits the prompt and
|
||||
// returns ApprovalPermanentlyApproved. Otherwise the recipient is shown the
|
||||
// three-button inline keyboard and the call blocks until the human decides,
|
||||
// the context is cancelled, or the 2-minute approval window
|
||||
// (messaging.ToolApprovalTimeout) elapses.
|
||||
// RequestApproval asks the recipient to approve action. A current permanent
|
||||
// approval returns ApprovalPermanentlyApproved without prompting.
|
||||
func (a *telegramApprover) RequestApproval(ctx context.Context, action, description string) (messaging.ApprovalDecision, error) {
|
||||
// Compose the lookup key so a permanent approval is scoped to
|
||||
// the specific resource: "Approve Permanently" on "delete session
|
||||
|
||||
@@ -28,11 +28,7 @@ var gatewayCommandSpecs = []commandSpec{
|
||||
{Command: "spawn", Description: "Create a tracked task", Usage: "/spawn [identity=name] [repo=owner/name] [workflow=name] <title>"},
|
||||
{Command: "settings", Description: "Inspect or change runtime settings", Usage: "/settings [list|get <kind>|set <kind> <field>=<value> ...]"},
|
||||
{Command: "cancel", Description: "Cancel a queued or waiting task", Usage: "/cancel [identity=name] <task-id>"},
|
||||
// /approve and /deny are Telegram's own dangerous-command approval surface:
|
||||
// dangerous.go lists the pending commands and the inline buttons decide.
|
||||
// The shared command specs use /approve for task approval instead, and
|
||||
// Telegram's exact-match handler shadows that path, so /help must describe
|
||||
// the Telegram meaning.
|
||||
// On Telegram, /approve and /deny decide pending dangerous commands.
|
||||
{Command: "approve", Description: "Show pending dangerous commands to approve", Usage: "/approve"},
|
||||
{Command: "deny", Description: "Show pending dangerous commands to deny", Usage: "/deny"},
|
||||
{Command: "start", Description: "Confirm that Archie is running", Usage: "/start"},
|
||||
@@ -80,15 +76,8 @@ func gatewayHelpText() string {
|
||||
return strings.TrimSpace(help.String())
|
||||
}
|
||||
|
||||
// commandScopes are the scopes the menu is published to.
|
||||
//
|
||||
// Telegram resolves a chat's menu by scope specificity, not recency: a
|
||||
// list set on all_private_chats wins over the default scope in every DM.
|
||||
// Publishing only to the default scope therefore leaves the bot showing
|
||||
// whatever a previous owner of the token registered against the narrower
|
||||
// scopes -- state that lives on Telegram's side and survives redeploys,
|
||||
// rewrites and migrations. Writing every scope we care about overwrites
|
||||
// those leftovers instead of being shadowed by them.
|
||||
// commandScopes are the scopes the command menu is published to. Publishing
|
||||
// to every scope overwrites menus left on narrower scopes.
|
||||
var commandScopes = []models.BotCommandScope{
|
||||
&models.BotCommandScopeDefault{},
|
||||
&models.BotCommandScopeAllPrivateChats{},
|
||||
|
||||
@@ -274,11 +274,8 @@ func (g *Gateway) hasPermanentApproval(recipient int64, command string) bool {
|
||||
return found
|
||||
}
|
||||
|
||||
// hasPermanentApprovalExact is the exact-match variant used by the tool
|
||||
// approval path. Prefix matching is appropriate for slash commands
|
||||
// (/rollback covers /rollback 3); it is not for tool-approval keys
|
||||
// composed of action + resource, where "delete session abc" must not
|
||||
// grant on "delete session abc2".
|
||||
// hasPermanentApprovalExact is the exact-match approval check for tool
|
||||
// approvals.
|
||||
func (g *Gateway) hasPermanentApprovalExact(recipient int64, pattern string) bool {
|
||||
g.dangerousMu.Lock()
|
||||
defer g.dangerousMu.Unlock()
|
||||
@@ -411,13 +408,8 @@ func rollbackApprovalText(num int) string {
|
||||
|
||||
// ── /stop handler ──────────────────────────────────────────────
|
||||
|
||||
// stopCurrentTurn cancels whatever this conversation is currently doing.
|
||||
//
|
||||
// Cancellation propagates through the turn's context, so it reaches the
|
||||
// model stream and any tool running underneath it -- a shell command built
|
||||
// with exec.CommandContext is killed with the turn, which is the case that
|
||||
// matters. Whatever the reply had already streamed stays on screen: it is
|
||||
// the record of what Archie did before being stopped.
|
||||
// stopCurrentTurn cancels the conversation's running turn and any tool under
|
||||
// it. Streamed text stays.
|
||||
func (g *Gateway) stopCurrentTurn(ctx context.Context, b *bot.Bot, msg *models.Message, client messaging.ChatContract) {
|
||||
var cancelled bool
|
||||
var dropped int
|
||||
@@ -440,11 +432,7 @@ func (g *Gateway) stopCurrentTurn(ctx context.Context, b *bot.Bot, msg *models.M
|
||||
stopReport(cancelled, dropped, nil))
|
||||
}
|
||||
|
||||
// stopReport describes what a /stop actually stopped.
|
||||
//
|
||||
// It names the parts rather than saying "stopped" unconditionally.
|
||||
// Claiming success when nothing was running teaches the operator to
|
||||
// distrust the command at exactly the moment they need to believe it.
|
||||
// stopReport describes what a /stop stopped.
|
||||
func stopReport(cancelled bool, dropped int, tasks []int64) string {
|
||||
var parts []string
|
||||
if cancelled {
|
||||
@@ -479,15 +467,8 @@ func joinWithAnd(parts []string) string {
|
||||
}
|
||||
}
|
||||
|
||||
// stopHandler serves /stop.
|
||||
//
|
||||
// Bare /stop is the emergency brake: it cancels the conversation's running
|
||||
// turn immediately, with no approval step. Approval exists to protect
|
||||
// against destructive commands, and stopping is the opposite -- gating it
|
||||
// behind a confirmation round-trip would defeat the entire point.
|
||||
//
|
||||
// /stop <process-name> keeps the original behaviour of terminating a named
|
||||
// background process, which is destructive and still requires approval.
|
||||
// stopHandler serves /stop. Bare /stop cancels the running turn immediately;
|
||||
// /stop <process-name> terminates a background process after approval.
|
||||
func (g *Gateway) stopHandler(client messaging.ChatContract) bot.HandlerFunc {
|
||||
return func(ctx context.Context, b *bot.Bot, update *models.Update) {
|
||||
msg, ok := g.authorizedMessage(ctx, b, update)
|
||||
@@ -580,11 +561,8 @@ func parseDangerousCallback(data string) (decision, token string) {
|
||||
|
||||
// ── /approve and /deny handlers ─────────────────────────────────
|
||||
|
||||
// approveHandler serves /approve: list any pending dangerous commands,
|
||||
// or approve a specific one by token. When a pending command exists, the
|
||||
// user interacts via inline buttons rather than typing /approve directly;
|
||||
// this handler is for the edge case where a user types /approve without
|
||||
// a pending command context.
|
||||
// approveHandler serves /approve: lists pending dangerous commands or
|
||||
// approves one by token.
|
||||
func (g *Gateway) approveHandler() bot.HandlerFunc {
|
||||
return func(ctx context.Context, b *bot.Bot, update *models.Update) {
|
||||
msg, ok := g.authorizedMessage(ctx, b, update)
|
||||
|
||||
@@ -10,14 +10,7 @@ import (
|
||||
"github.com/samcharles93/archie-core/internal/domain/messaging"
|
||||
)
|
||||
|
||||
// telegramMessageDeleter removes messages the launch that built it sent,
|
||||
// through the Bot API's deleteMessage method.
|
||||
//
|
||||
// It captures the *bot.Bot at construction rather than reading a Gateway
|
||||
// field, matching telegramMediaSender and telegramApprover: a deleter belongs
|
||||
// to the launch that built it, so a /restart abandons in-flight retractions
|
||||
// with the outgoing bot instance instead of silently directing them through
|
||||
// the new one.
|
||||
// telegramMessageDeleter deletes messages through the bot it was built with.
|
||||
type telegramMessageDeleter struct {
|
||||
bot *bot.Bot
|
||||
chatID int64
|
||||
|
||||
@@ -15,12 +15,8 @@ import (
|
||||
// history next to the conversation it reported on.
|
||||
const statusNoticeTTL = 8 * time.Second
|
||||
|
||||
// sendEphemeral delivers text and retracts it after statusNoticeTTL.
|
||||
//
|
||||
// The retraction is best-effort by contract: a platform that cannot delete
|
||||
// leaves the notice in place (channels.EphemeralSender logs the degrade), and
|
||||
// a failed send is logged rather than returned, because a status notice must
|
||||
// never take the operation it narrates down with it.
|
||||
// sendEphemeral sends text and deletes it after statusNoticeTTL. Failures are
|
||||
// logged.
|
||||
func (g *Gateway) sendEphemeral(ctx context.Context, b *bot.Bot, chatID int64, messageThreadID int, text string) {
|
||||
sender := g.newEphemeralSender()
|
||||
_, err := sender.Send(ctx, g.NewMessageDeleter(b, chatID), messaging.EphemeralReply{
|
||||
@@ -45,11 +41,8 @@ func (g *Gateway) sendEphemeral(ctx context.Context, b *bot.Bot, chatID int64, m
|
||||
}
|
||||
}
|
||||
|
||||
// sendTextMessage delivers one message and returns its Bot API message ID.
|
||||
//
|
||||
// It returns 0 for text that must be split across messages: a retraction
|
||||
// addresses exactly one message, so a reply that does not fit in one is left
|
||||
// intact rather than half-deleted.
|
||||
// sendTextMessage sends one message and returns its ID, or 0 when the text
|
||||
// had to be split.
|
||||
func (g *Gateway) sendTextMessage(ctx context.Context, b *bot.Bot, chatID int64, messageThreadID int, text string) int {
|
||||
blocks := markdownToBlocks(text)
|
||||
if blockTextLen(blocks) > messageMaxLen {
|
||||
|
||||
@@ -111,11 +111,7 @@ func nilIfZero(v int64) *int64 {
|
||||
return &v
|
||||
}
|
||||
|
||||
// maxInboundDownloadBytes is the Bot API download ceiling: bots cannot
|
||||
// fetch files larger than 20 MB through getFile, so a larger attachment
|
||||
// must be refused with a clear notice rather than met with a Bot API 400
|
||||
// nobody reads. It is the messaging contract's inbound attachment ceiling,
|
||||
// so the value the Gateway must be able to receive stays in one place.
|
||||
// maxInboundDownloadBytes is the Bot API download limit.
|
||||
var maxInboundDownloadBytes int64 = messaging.MaxInboundAttachmentBytes
|
||||
|
||||
var errInboundMediaTooLarge = errors.New("file exceeds the bot download limit")
|
||||
@@ -157,11 +153,8 @@ func (g *Gateway) downloadMedia(ctx context.Context, b *bot.Bot, att messaging.M
|
||||
return data, nil
|
||||
}
|
||||
|
||||
// turnMessageText renders the text an inbound message's turn is built
|
||||
// from: plain text as received, or the attachment note plus caption when
|
||||
// the message carries a file. The note is what later turns read from
|
||||
// history, so a captioned photo whose caption alone would read as the
|
||||
// whole message ("what is this?") still names its attachment.
|
||||
// turnMessageText returns the message text, or the attachment note plus
|
||||
// caption for a message with a file.
|
||||
func turnMessageText(msg *models.Message, media inboundMedia, hasMedia bool) string {
|
||||
if !hasMedia {
|
||||
return msg.Text
|
||||
@@ -172,11 +165,8 @@ func turnMessageText(msg *models.Message, media inboundMedia, hasMedia bool) str
|
||||
return media.note + "\n" + msg.Caption
|
||||
}
|
||||
|
||||
// unsupportedMediaNotice returns the refusal for content kinds Archie
|
||||
// cannot read, and "" for update content that is not a message to answer
|
||||
// at all -- a group member change or pin must stay silent, while a
|
||||
// sticker the sender meant Archie to react to must not disappear into the
|
||||
// void.
|
||||
// unsupportedMediaNotice returns the refusal for unreadable content, or ""
|
||||
// for updates that need no reply.
|
||||
func unsupportedMediaNotice(msg *models.Message) string {
|
||||
switch {
|
||||
case msg.Sticker != nil:
|
||||
|
||||
@@ -40,12 +40,8 @@ type replyResult struct {
|
||||
err error
|
||||
}
|
||||
|
||||
// telegramInteractor carries clarify and picker interactions for one chat on
|
||||
// the channel's shared text fallback. Telegram renders no generic question or
|
||||
// single-choice widget in the agent-turn path, so both interactions appear as
|
||||
// text the human answers by replying; reporting the Clarify and Picker
|
||||
// capabilities is therefore honest, because the adapter can carry the
|
||||
// interaction even though it costs a typed answer.
|
||||
// telegramInteractor carries clarify and picker questions as plain text the
|
||||
// human replies to.
|
||||
type telegramInteractor struct {
|
||||
gw *Gateway
|
||||
bot *bot.Bot
|
||||
@@ -62,11 +58,7 @@ var (
|
||||
_ messaging.CapabilityReporter = (*telegramInteractor)(nil)
|
||||
)
|
||||
|
||||
// Capabilities reports that this adapter can carry a clarify question and a
|
||||
// single-choice picker. Both go through the shared text fallback rather than a
|
||||
// native widget, and the capability is about carrying the interaction, not
|
||||
// about the widget, so claiming them is what keeps a question from being
|
||||
// silently dropped.
|
||||
// Capabilities reports clarify and picker support.
|
||||
func (i *telegramInteractor) Capabilities() messaging.AdapterCapabilities {
|
||||
return messaging.AdapterCapabilities{Clarify: true, Picker: true}
|
||||
}
|
||||
|
||||
@@ -32,15 +32,8 @@ const (
|
||||
// not deliver an attachment inline, so the user still gets the asset.
|
||||
fallbackMediaLinePrefix = "📎 "
|
||||
|
||||
// liveBodyMaxRunes bounds one mid-turn frame. Telegram rejects a
|
||||
// message over its character limit outright, so an unbounded frame
|
||||
// means every edit past that point fails and the live message freezes
|
||||
// at the last frame that fit -- for the rest of the turn, since the
|
||||
// buffer only grows. The bound is in runes rather than bytes because
|
||||
// the limit Telegram applies is a character count, not a byte count.
|
||||
//
|
||||
// Only the live frame is bounded. finalize sends the whole reply,
|
||||
// split across as many messages as it needs.
|
||||
// liveBodyMaxRunes bounds one mid-turn frame below Telegram's message limit.
|
||||
// finalize sends the full reply.
|
||||
liveBodyMaxRunes = 3900
|
||||
|
||||
// Keep tool activity to a minority of a live frame so the answer remains
|
||||
@@ -49,32 +42,8 @@ const (
|
||||
liveToolMaxRunes = (liveBodyMaxRunes - 2) / 3
|
||||
)
|
||||
|
||||
// liveReply renders one chat turn into a single Telegram message as it is
|
||||
// generated, so the user watches the answer being written instead of waiting
|
||||
// on a silent "typing…" indicator.
|
||||
//
|
||||
// It keeps one canonical buffer and sends the whole of it on every update:
|
||||
// the first update creates the message, every later one edits that same
|
||||
// message. Editing has replace semantics, which is what makes a partial frame
|
||||
// impossible to append to the last one. (It previously streamed through
|
||||
// sendMessageDraft, whose drafts are ephemeral 30-second previews -- a tool
|
||||
// call longer than that outlived the preview, and successive frames were
|
||||
// observed concatenated, cursors and all.)
|
||||
//
|
||||
// Rendering is deliberately best-effort: it never blocks the generating
|
||||
// goroutine and never surfaces an error. The authoritative reply is the one
|
||||
// finalize writes when the turn completes -- if every live update failed,
|
||||
// the user simply sees the finished message appear the way it did before
|
||||
// streaming existed.
|
||||
//
|
||||
// A known, accepted trade-off of editing rather than sending: Telegram does
|
||||
// not change a message's date on edit, so the finished reply carries the
|
||||
// timestamp of the first streamed frame, not of finalize. A turn with a long
|
||||
// tool phase can therefore produce an answer timestamped before a user
|
||||
// message sent later, during that phase, and sort before the conversation
|
||||
// that produced it. Delete-and-resend on finalize would fix the ordering but
|
||||
// reintroduce the flicker/reorder streaming was built to avoid, so this is
|
||||
// left as-is rather than "fixed."
|
||||
// liveReply streams one chat turn into a single Telegram message, editing it
|
||||
// on each update. Rendering is best-effort; finalize writes the final reply.
|
||||
type liveReply struct {
|
||||
g *Gateway
|
||||
b *bot.Bot
|
||||
@@ -85,10 +54,6 @@ type liveReply struct {
|
||||
interval time.Duration
|
||||
|
||||
// newMediaSender builds the MediaSender Media delivers through.
|
||||
// Defaults to g.NewMediaSender; tests override it to inject a sender
|
||||
// with fixed Capabilities(), which the real Telegram one can't
|
||||
// express (it always reports Media: true) but a future channel or a
|
||||
// capability-limited deployment might.
|
||||
newMediaSender func(b *bot.Bot, chatID int64, threadID int) messaging.MediaSender
|
||||
|
||||
cancelRender context.CancelFunc
|
||||
@@ -96,12 +61,7 @@ type liveReply struct {
|
||||
renderDone chan struct{}
|
||||
|
||||
mu sync.Mutex
|
||||
// answerBuf is the assistant text streamed so far, in the order the
|
||||
// model produced it. Tool activity is not appended here: it is tracked
|
||||
// separately in toolLines so it can be kept whole and in front of the
|
||||
// answer at every rendering stage (mid-turn frame, abandon, finalize)
|
||||
// instead of scrolling out of the frame once the answer grows past the
|
||||
// live clamp.
|
||||
// answerBuf is the streamed answer text; tool activity is kept in toolLines.
|
||||
answerBuf strings.Builder
|
||||
// toolLines holds the tool activity for this turn, in call order, so
|
||||
// every rendering stage can lead with it rather than have it buried
|
||||
@@ -116,27 +76,11 @@ type liveReply struct {
|
||||
rendered string
|
||||
messageID int
|
||||
last time.Time
|
||||
// finalized is set once stopRendering returns, the single point every
|
||||
// finalize/abandon path funnels through to retire the renderer
|
||||
// goroutine. After that point requestRender is a silent no-op (a
|
||||
// non-blocking send into a channel nothing reads any more), so any
|
||||
// caller still trying to append to the live message after this point
|
||||
// -- Media's fire-and-forget delivery has its own 30s budget, far
|
||||
// longer than the turn's text usually takes -- must send its own
|
||||
// follow-up message instead of writing into a buffer nothing renders.
|
||||
// finalized is set once rendering stops; later writers must send their own
|
||||
// message.
|
||||
finalized bool
|
||||
|
||||
// terminal guards finalize and abandon so exactly one of them actually
|
||||
// runs its body. Without this, a turn finishing naturally (finalize)
|
||||
// and a concurrent Gateway.Stop (abandon, via abandonRestarted) can
|
||||
// both reach their own Telegram edit for the same message: both edits
|
||||
// go through, and whichever HTTP response Telegram processes last
|
||||
// decides what the user sees, nondeterministically -- including a
|
||||
// completed real answer getting silently overwritten by a restart
|
||||
// marker. The loser's call blocks until the winner's body returns
|
||||
// (sync.Once's own guarantee), then does nothing, so cleanup that must
|
||||
// happen exactly once (stopRendering, forgetLive) is never skipped or
|
||||
// duplicated regardless of which side wins.
|
||||
// terminal ensures only one of finalize and abandon runs.
|
||||
terminal sync.Once
|
||||
}
|
||||
|
||||
@@ -163,22 +107,15 @@ func (g *Gateway) newLiveReply(ctx context.Context, b *bot.Bot, chatID int64, me
|
||||
return live
|
||||
}
|
||||
|
||||
// resetLiveRegistry clears the previous launch's stopped mark. Called once
|
||||
// per launch, alongside rebuilding turns: a /restart's Stop marks the
|
||||
// registry stopped so nothing straggling from the outgoing bot instance
|
||||
// gets silently registered into it, but the incoming instance needs a live
|
||||
// registry of its own.
|
||||
// resetLiveRegistry clears the stopped mark at the start of a launch.
|
||||
func (g *Gateway) resetLiveRegistry() {
|
||||
g.liveMu.Lock()
|
||||
g.liveStopped = false
|
||||
g.liveMu.Unlock()
|
||||
}
|
||||
|
||||
// registerLive adds l to the set Stop drains on shutdown or restart. If a
|
||||
// drain already claimed the registry for this launch, l is abandoned
|
||||
// immediately instead of being registered: it arrived in the narrow window
|
||||
// between that claim and this call, and without this it would sit in no
|
||||
// registry, with nothing left to ever drain it.
|
||||
// registerLive adds l to the set Stop drains, or abandons it at once if the
|
||||
// registry is already stopped.
|
||||
func (g *Gateway) registerLive(ctx context.Context, l *liveReply) {
|
||||
g.liveMu.Lock()
|
||||
if g.liveStopped {
|
||||
@@ -193,36 +130,18 @@ func (g *Gateway) registerLive(ctx context.Context, l *liveReply) {
|
||||
g.liveMu.Unlock()
|
||||
}
|
||||
|
||||
// forgetLive removes l from the registry. Called at the top of doFinalize
|
||||
// and doAbandon -- reached through l.terminal, so by the time this runs the
|
||||
// caller has already exclusively won the right to decide this reply's
|
||||
// outcome (see the terminal field doc) -- so a reply that completed on its
|
||||
// own is never picked up a second time by a later Stop, and a reply Stop
|
||||
// has already claimed is never double-processed.
|
||||
// forgetLive removes l from the registry.
|
||||
func (g *Gateway) forgetLive(l *liveReply) {
|
||||
g.liveMu.Lock()
|
||||
defer g.liveMu.Unlock()
|
||||
delete(g.liveReplies, l)
|
||||
}
|
||||
|
||||
// abandonAllLiveTimeout bounds how long Stop waits for in-flight replies to
|
||||
// be marked before giving up and returning anyway. A single stalled
|
||||
// Telegram API call must not hang gateway (and therefore daemon) shutdown
|
||||
// indefinitely; entries still in flight past this deadline keep running in
|
||||
// the background and finish (or die with the process) on their own.
|
||||
// abandonAllLiveTimeout bounds how long Stop waits for in-flight replies.
|
||||
const abandonAllLiveTimeout = 5 * time.Second
|
||||
|
||||
// abandonAllLive drops the cursor, marked as interrupted, on every turn
|
||||
// still streaming when the gateway stops or restarts. It exists because
|
||||
// nothing else guarantees this happens: cancelling turnCtx does not
|
||||
// guarantee the goroutine that owns a liveReply ever runs again to notice
|
||||
// and clean up after itself, and a full daemon process exit gives it no
|
||||
// chance to run at all, so this must not wait on that goroutine and must not
|
||||
// skip a reply just because its owning turn is still technically running.
|
||||
//
|
||||
// Marking liveStopped and draining the registry happen together, under the
|
||||
// same lock, so registerLive can never observe "stopped" without also
|
||||
// observing an empty-of-this-entry registry, or vice versa.
|
||||
// abandonAllLive marks every still-streaming reply as interrupted on stop or
|
||||
// restart, and stops the registry under the same lock.
|
||||
func (g *Gateway) abandonAllLive(ctx context.Context) {
|
||||
g.liveMu.Lock()
|
||||
g.liveStopped = true
|
||||
@@ -319,18 +238,7 @@ func (l *liveReply) Delta(text string) {
|
||||
l.requestRender()
|
||||
}
|
||||
|
||||
// ToolCall appends one tool-activity line. It satisfies gateway.TurnStream.
|
||||
//
|
||||
// Tool activity is opt-in per deployment: without it the user cannot tell a
|
||||
// hallucinated action from a real one, but it also narrates every internal
|
||||
// step, which is noise in a conversation that is going fine.
|
||||
//
|
||||
// The name, parameters and summary all come from tool execution, not the
|
||||
// model's prose, and can carry raw Markdown metacharacters (a grep hit with
|
||||
// '*', a JSON parameter with '_' or backticks). They are escaped before
|
||||
// joining the line because the tool line and the model's reply share one
|
||||
// Markdown body (finalText): an unbalanced marker in the tool line breaks
|
||||
// parsing for the whole message, including the reply's own formatting.
|
||||
// ToolCall appends one escaped tool-activity line, when tool display is on.
|
||||
func (l *liveReply) ToolCall(event messaging.ToolCallEvent) {
|
||||
if !l.showToolCalls || event.Name == "" {
|
||||
return
|
||||
@@ -360,16 +268,7 @@ func (l *liveReply) ToolCall(event messaging.ToolCallEvent) {
|
||||
l.requestRender()
|
||||
}
|
||||
|
||||
// countedToolLine marks a collapsed entry with how many calls it stands for.
|
||||
// The count belongs to the status, not to the preview, so it is inserted
|
||||
// before the preview separator rather than appended: "grep — done ×14 · 2
|
||||
// matches" counts calls, while "· 2 matches ×14" reads as counting matches.
|
||||
// toolLineSeparator joins tool lines. It ends each one with CommonMark's
|
||||
// hard-break marker rather than a blank line: a bare "\n" is a soft break,
|
||||
// which the block parser space-joins into one run-on paragraph, while a blank
|
||||
// line would insert a spacer block between every pair. A hard break gives
|
||||
// each line its own block AND suppresses the spacer, so a turn's activity
|
||||
// reads as consecutive lines instead of a double-spaced list.
|
||||
// toolLineSeparator ends each tool line with a Markdown hard break.
|
||||
const toolLineSeparator = " \n"
|
||||
|
||||
func countedToolLine(line string, count int) string {
|
||||
@@ -383,26 +282,11 @@ func countedToolLine(line string, count int) string {
|
||||
return line + marker
|
||||
}
|
||||
|
||||
// mediaSendTimeout bounds one Media delivery. It is independent of the
|
||||
// render loop's own lifecycle (unlike answerBuf/toolLines, which a
|
||||
// /restart abandons via abandonAllLive): an upload in flight when the live
|
||||
// reply finalizes should still be allowed to land, since the asset is worth
|
||||
// delivering on its own even after the surrounding turn is done narrating.
|
||||
// mediaSendTimeout bounds one Media delivery, independent of the turn.
|
||||
const mediaSendTimeout = 30 * time.Second
|
||||
|
||||
// Media delivers the attachment through the media-specific Bot API, off the
|
||||
// generating goroutine: unlike Delta/ToolCall, this is a real network
|
||||
// upload, and TurnStream implementations must not block generation on one.
|
||||
// It satisfies gateway.TurnStream.
|
||||
//
|
||||
// An attachment carrying neither a URL to fetch nor a local Path to
|
||||
// upload is silently skipped: SendMedia would reject it as
|
||||
// invalid_message, there is nothing to fall back to, and Media has no
|
||||
// error return to report it through.
|
||||
//
|
||||
// This used to skip on a missing URL alone, which dropped every local
|
||||
// file before it reached the sender -- the guard, not just the sender,
|
||||
// was part of making a local path undeliverable.
|
||||
// Media uploads the attachment in the background. An attachment with no URL
|
||||
// or Path is skipped.
|
||||
func (l *liveReply) Media(ctx context.Context, event messaging.MediaEvent) {
|
||||
if event.Attachment.URL == "" && event.Attachment.Path == "" {
|
||||
return
|
||||
@@ -502,23 +386,9 @@ func (l *liveReply) markRendered(body string) {
|
||||
l.mu.Unlock()
|
||||
}
|
||||
|
||||
// finalize replaces the live message with the turn's authoritative reply,
|
||||
// led by the tool activity that produced it, and drops the cursor. When
|
||||
// nothing was ever streamed -- a non-streaming provider, or a reply served
|
||||
// from the turn ledger -- it sends the reply as a new message instead.
|
||||
//
|
||||
// ctx is stripped of cancellation before anything is sent: the reply is
|
||||
// already decided and persisted by the time finalize runs, so a /stop
|
||||
// landing mid-finalize must not abort delivery the way it aborts the turn
|
||||
// itself -- that would strand the live message on a frame with the cursor
|
||||
// still attached, forever. Doing this inside finalize rather than trusting
|
||||
// each caller to pass a live context is what keeps this fix from silently
|
||||
// regressing the next time a caller is added.
|
||||
//
|
||||
// The actual work runs inside l.terminal so a concurrent abandon (a gateway
|
||||
// shutdown abandoning every in-flight reply while this turn is finishing
|
||||
// naturally, see Gateway.abandonAllLive) cannot send its own conflicting
|
||||
// edit for the same message -- see the terminal field doc.
|
||||
// finalize replaces the live message with the tool activity and the final
|
||||
// reply, or sends a new message if nothing streamed. It ignores ctx
|
||||
// cancellation and runs at most once.
|
||||
func (l *liveReply) finalize(ctx context.Context, reply string) {
|
||||
ctx = context.WithoutCancel(ctx)
|
||||
l.terminal.Do(func() { l.doFinalize(ctx, reply) })
|
||||
@@ -546,11 +416,8 @@ func (l *liveReply) doFinalize(ctx context.Context, reply string) {
|
||||
return
|
||||
}
|
||||
|
||||
// The live message is one message, so an oversized reply keeps it as
|
||||
// the first part and sends the remainder after it. If the edit cannot
|
||||
// be delivered in either rich or plain form, send the complete reply
|
||||
// through the normal split path rather than losing the authoritative
|
||||
// answer behind a stale live frame.
|
||||
// Edit the first part into the live message and send the rest; if the edit
|
||||
// fails, send the whole reply.
|
||||
parts := splitBlocks(markdownToBlocks(content), messageMaxLen)
|
||||
if len(parts) == 0 {
|
||||
l.abandonStopped(ctx)
|
||||
@@ -572,17 +439,8 @@ func (l *liveReply) doFinalize(ctx context.Context, reply string) {
|
||||
// immutable, so nothing can correct that impression after the fact.
|
||||
const abandonMarker = "\n\n❌ _turn failed before finishing_"
|
||||
|
||||
// abandon leaves a stopped turn readable: the partial text stays, but the
|
||||
// cursor goes, so the message does not claim to still be writing. A /stop is
|
||||
// a deliberate, acknowledged interruption, not a fault, so the partial is
|
||||
// left clean rather than marked as a failure.
|
||||
//
|
||||
// Like finalize, it strips ctx of cancellation before sending: abandon runs
|
||||
// precisely when a /stop has cancelled turnCtx, so honouring that
|
||||
// cancellation in the very edit meant to drop the cursor would leave the
|
||||
// cursor blinking on a message nothing will ever finish. And like finalize,
|
||||
// the actual work runs inside l.terminal -- see the terminal field doc and
|
||||
// finalize's.
|
||||
// abandon leaves a stopped turn's partial text without the cursor. It ignores
|
||||
// ctx cancellation and runs at most once.
|
||||
func (l *liveReply) abandon(ctx context.Context) {
|
||||
ctx = context.WithoutCancel(ctx)
|
||||
l.terminal.Do(func() { l.doAbandon(ctx) })
|
||||
@@ -605,18 +463,10 @@ func (l *liveReply) abandonFailed(ctx context.Context) {
|
||||
l.abandon(ctx)
|
||||
}
|
||||
|
||||
// restartMarker distinguishes a gateway-restart abandon from both a clean
|
||||
// /stop (abandon) and a provider failure (abandonFailed): the turn was cut
|
||||
// off by an operational event rather than a fault in it or a deliberate
|
||||
// stop, and unlike either of those the user's message is still worth
|
||||
// resending once the gateway is back.
|
||||
// restartMarker marks a turn cut off by a gateway restart.
|
||||
const restartMarker = "\n\n⚠️ _archie restarted before finishing -- send your message again_"
|
||||
|
||||
// abandonRestarted leaves a turn interrupted by gateway shutdown or restart
|
||||
// readable and marked, for the same reason abandonFailed marks a provider
|
||||
// error: nothing will ever resume this turn, and an unmarked partial reads
|
||||
// as a finished answer either way. Called by Gateway.abandonAllLive, never
|
||||
// by the turn's own goroutine.
|
||||
// abandonRestarted marks a turn interrupted by a gateway stop or restart.
|
||||
func (l *liveReply) abandonRestarted(ctx context.Context) {
|
||||
l.mu.Lock()
|
||||
l.answerBuf.WriteString(restartMarker)
|
||||
@@ -676,27 +526,14 @@ func (l *liveReply) framedText(answer string) string {
|
||||
return block + "\n\n" + l.clampAnswer(answer, budget)
|
||||
}
|
||||
|
||||
// clampAnswer cuts the answer to its budget, retaining the newest text and
|
||||
// marking the cut with a leading ellipsis.
|
||||
//
|
||||
// The marker matters on every frame, including the opening one. A turn that
|
||||
// streams a large first chunk, or that never opens a reply at all (so
|
||||
// messageID stays 0), would otherwise render text that appears to begin
|
||||
// mid-sentence with nothing to say a cut was made -- and Telegram messages are
|
||||
// immutable, so it can never be corrected afterwards.
|
||||
// clampAnswer keeps the newest budget runes of answer, prefixed with an
|
||||
// ellipsis when cut.
|
||||
func (l *liveReply) clampAnswer(answer string, budget int) string {
|
||||
return clampToRunes(answer, budget)
|
||||
}
|
||||
|
||||
// toolBlock returns the most recent activity that fits its deliberately
|
||||
// smaller frame budget, prefixed with a count of what was left out.
|
||||
//
|
||||
// The search runs from the newest line backwards, widening the window while
|
||||
// the result still fits, so EVERY line that fits is kept: returning as soon as
|
||||
// the newest line alone fits would discard history that was never over budget
|
||||
// and report a "+N earlier" that is simply untrue.
|
||||
//
|
||||
// The caller holds the lock.
|
||||
// toolBlock returns the newest tool lines that fit the budget, prefixed with
|
||||
// a count of the rest. The caller holds the lock.
|
||||
func (l *liveReply) toolBlock() string {
|
||||
if len(l.toolLines) == 0 {
|
||||
return ""
|
||||
@@ -748,19 +585,8 @@ func clampToRunes(s string, maxRunes int) string {
|
||||
return "…" + string(runes[len(runes)-(maxRunes-1):])
|
||||
}
|
||||
|
||||
// finalText composes the finished message: the tool activity in the order it
|
||||
// happened, then the authoritative reply. The caller holds the lock.
|
||||
//
|
||||
// The reply is used rather than the streamed buffer because it is what the
|
||||
// turn actually returned and what was persisted to the conversation -- a
|
||||
// dropped or throttled frame cannot leave the visible message disagreeing
|
||||
// with the stored one.
|
||||
//
|
||||
// A turn that ran tools but produced no reply text still needs to say so:
|
||||
// the tool block alone reads as a completed answer that said nothing, and
|
||||
// Telegram messages are immutable, so nothing can correct it after the
|
||||
// fact. An empty reply with no tool activity either is left to the
|
||||
// content == "" path in finalize, which abandons instead of sending.
|
||||
// finalText returns the tool activity followed by reply, noting when tools
|
||||
// ran without a reply. The caller holds the lock.
|
||||
func (l *liveReply) finalText(reply string) string {
|
||||
reply = strings.TrimSpace(reply)
|
||||
if len(l.toolLines) == 0 {
|
||||
@@ -802,12 +628,8 @@ func (l *liveReply) open(ctx context.Context, blocks []models.InputRichBlock) {
|
||||
l.mu.Unlock()
|
||||
}
|
||||
|
||||
// edit replaces the live message's content.
|
||||
//
|
||||
// Rich messages are a recent Bot API addition, and text is only optional on
|
||||
// an edit that carries one, so a server that rejects the rich body rejects
|
||||
// the whole edit. As with send, that is treated as "unsupported" rather than
|
||||
// fatal: retry unformatted so the user still gets the reply.
|
||||
// edit replaces the live message's content, retrying as plain text if the
|
||||
// rich body is rejected.
|
||||
func (l *liveReply) edit(ctx context.Context, messageID int, blocks []models.InputRichBlock) error {
|
||||
_, richErr := l.b.EditMessageText(ctx, &bot.EditMessageTextParams{
|
||||
ChatID: l.chatID,
|
||||
|
||||
@@ -13,26 +13,9 @@ import (
|
||||
"github.com/samcharles93/archie-core/internal/domain/messaging"
|
||||
)
|
||||
|
||||
// telegramMediaSender delivers a MessageEvent's attachment through the
|
||||
// media-specific Bot API methods (sendVideo, sendPhoto, ...) rather than
|
||||
// sendMessage, which cannot carry a file at all.
|
||||
//
|
||||
// It captures the *bot.Bot at construction rather than reading the
|
||||
// Gateway's shared field, matching telegramApprover: a sender belongs to
|
||||
// the launch that built it, so a /restart abandons in-flight sends with
|
||||
// the outgoing bot instance instead of silently redirecting them through
|
||||
// the new one. That is the same lifetime rule the per-launch turns
|
||||
// registry documents.
|
||||
//
|
||||
// An attachment is delivered one of two ways, chosen by what it carries:
|
||||
// a URL is handed to Telegram to FETCH, while a Path is UPLOADED from this
|
||||
// host. Delivery used to be URL-only, which meant a locally produced file
|
||||
// was passed off as a URL Telegram could not fetch and the send did
|
||||
// nothing useful while reporting success.
|
||||
//
|
||||
// A MediaAttachment.FileID is still not accepted: it identifies a file on
|
||||
// the platform it was uploaded from and is meaningless as an outbound
|
||||
// handle here.
|
||||
// telegramMediaSender sends attachments through the media Bot API methods,
|
||||
// using the bot it was built with. A URL is fetched by Telegram; a Path is
|
||||
// uploaded. FileIDs are not accepted.
|
||||
type telegramMediaSender struct {
|
||||
bot *bot.Bot
|
||||
chatID int64
|
||||
@@ -118,19 +101,8 @@ var (
|
||||
errTooLarge = errors.New("file exceeds the Telegram upload limit")
|
||||
)
|
||||
|
||||
// source builds the Bot API file value for att, and a function to release
|
||||
// whatever it holds open.
|
||||
//
|
||||
// A URL becomes an InputFileString, which tells Telegram to fetch it. A
|
||||
// local path becomes an InputFileUpload carrying an open *os.File, which
|
||||
// the library streams as multipart form data -- the only way bytes that
|
||||
// exist solely on this host can reach a chat.
|
||||
//
|
||||
// The size check happens here rather than being left to Telegram: over the
|
||||
// limit the API answers a bad request whose text nobody reads, and the
|
||||
// operator sees an attachment that never arrived. The returned error is
|
||||
// classified invalid_message by the caller, so it is not retried -- a
|
||||
// file does not get smaller on a second attempt.
|
||||
// source returns the Bot API file for att and a release function. It refuses
|
||||
// a local file over the size limit.
|
||||
func (s *telegramMediaSender) source(att messaging.MediaAttachment) (models.InputFile, func(), error) {
|
||||
noop := func() {}
|
||||
if att.Path == "" {
|
||||
@@ -222,15 +194,8 @@ func invalidMedia(err error) (messaging.SendResult, error) {
|
||||
}, err
|
||||
}
|
||||
|
||||
// classifySendError maps a Bot API failure onto SendResult's error
|
||||
// vocabulary so a caller can decide on retry without inspecting
|
||||
// Telegram-specific errors.
|
||||
//
|
||||
// The library reports API failures as sentinel errors (bot.ErrorBadRequest
|
||||
// and friends), not as typed values, so these are errors.Is checks. A
|
||||
// failure matching no sentinel is a transport error or a 5xx, both of
|
||||
// which may yet succeed -- hence retryable, rather than defaulting to
|
||||
// permanent and silently dropping a deliverable asset.
|
||||
// classifySendError maps a Bot API error to a SendResult. Unrecognised errors
|
||||
// are retryable.
|
||||
func classifySendError(err error) messaging.SendResult {
|
||||
res := messaging.SendResult{Success: false, Error: err}
|
||||
|
||||
|
||||
@@ -8,12 +8,6 @@ import (
|
||||
)
|
||||
|
||||
// pipelineErrorHandler logs update-loop failures.
|
||||
//
|
||||
// go-telegram/bot v1.24.0 fixed getUpdates to honour retry_after on a 429
|
||||
// itself (https://github.com/go-telegram/bot/releases/tag/v1.24.0), instead
|
||||
// of retrying on its own 100ms-doubling-to-5s schedule regardless of what
|
||||
// Telegram asked for. This handler used to block for RetryAfter itself to
|
||||
// compensate; that workaround is gone now that the library does it.
|
||||
func (g *Gateway) pipelineErrorHandler(_ context.Context) func(error) {
|
||||
return func(err error) {
|
||||
if tooMany, ok := errors.AsType[*bot.TooManyRequestsError](err); ok {
|
||||
|
||||
@@ -14,13 +14,8 @@ type restartRequest struct {
|
||||
threadID int
|
||||
}
|
||||
|
||||
// restartHandler serves /restart: an operator escape hatch for reloading
|
||||
// config (notably the sender allowlist) or recovering a wedged adapter
|
||||
// without shell access to the host.
|
||||
//
|
||||
// Authorisation is inherited: authorizedMessage rejects anyone outside
|
||||
// AllowedUserIDs before this runs, so reaching it already implies an
|
||||
// allowlisted sender.
|
||||
// restartHandler serves /restart, relaunching the bot to reload config. Only
|
||||
// allowlisted senders reach it.
|
||||
func (g *Gateway) restartHandler() bot.HandlerFunc {
|
||||
return func(ctx context.Context, b *bot.Bot, update *models.Update) {
|
||||
msg, ok := g.authorizedMessage(ctx, b, update)
|
||||
@@ -28,11 +23,7 @@ func (g *Gateway) restartHandler() bot.HandlerFunc {
|
||||
return
|
||||
}
|
||||
|
||||
// Restarting tears down this process, and the update installer runs
|
||||
// as its child -- a restart mid-install kills the install outright
|
||||
// (signal: terminated) rather than letting it finish or fail
|
||||
// cleanly, leaving the daemon on its old binary with no clear error
|
||||
// surfaced to the operator.
|
||||
// Refuse to restart while an update is installing.
|
||||
g.updateMu.Lock()
|
||||
updating := g.updateInProgress
|
||||
g.updateMu.Unlock()
|
||||
|
||||
@@ -9,11 +9,8 @@ import (
|
||||
"github.com/go-telegram/bot/models"
|
||||
)
|
||||
|
||||
// Telegram's rich-message renderer has no ATX heading support and its
|
||||
// MarkdownV2 dialect needs escaping, so rather than translating Markdown into a
|
||||
// format it only partially implements we emit structured blocks the renderer
|
||||
// supports natively. Inline emphasis/code/links are reduced to plain text so no
|
||||
// Markdown marker can survive into the rendered message.
|
||||
// Markdown is rendered as Telegram rich blocks, with inline formatting
|
||||
// reduced to plain text.
|
||||
|
||||
var (
|
||||
inlineLinkHTML = regexp.MustCompile(`\[([^\]]*)\]\(([^)]+)\)`)
|
||||
@@ -114,11 +111,8 @@ func stripInlineMarkdown(s string) string {
|
||||
return codeBlockMark.ReplaceAllString(s, "$1")
|
||||
}
|
||||
|
||||
// stripEmphasis removes paired emphasis delimiters and keeps their content.
|
||||
// Pairing follows CommonMark's flanking rules, so a delimiter that cannot open
|
||||
// or close is ordinary text and stays put.
|
||||
// *sql.Tx all used to lose characters to a non-greedy `_(.+?)_` that paired
|
||||
// any two markers on a line.
|
||||
// stripEmphasis removes paired emphasis delimiters, keeping their content,
|
||||
// using CommonMark's flanking rules.
|
||||
func stripEmphasis(s, marker string) string {
|
||||
var b strings.Builder
|
||||
for i := 0; i < len(s); {
|
||||
@@ -181,13 +175,8 @@ func flanksOf(s string, i, j int) delimiterFlanks {
|
||||
}
|
||||
|
||||
// flanking reports whether the delimiter run s[i:j] may open or close
|
||||
// emphasis. The rules are CommonMark's, including the one that an underscore
|
||||
// may do neither inside a word.
|
||||
//
|
||||
// Single "*" carries one deliberate deviation: it may not open on
|
||||
// punctuation. CommonMark reads "*.go files in cmd/*" as emphasis, which in a
|
||||
// relay carrying shell globs and pointer types corrupts far more text than a
|
||||
// stray marker would. Emphasis opening on a word still works.
|
||||
// emphasis, per CommonMark, except that a single "*" may not open on
|
||||
// punctuation.
|
||||
func flanking(s string, i, j int, marker string) (canOpen, canClose bool) {
|
||||
f := flanksOf(s, i, j)
|
||||
switch marker {
|
||||
@@ -286,19 +275,8 @@ func (p *markdownBlockParser) handleLine(line string) {
|
||||
case trimmed == "":
|
||||
p.flush()
|
||||
default:
|
||||
// A normal line ends a list or quote block and continues a
|
||||
// paragraph. Joined with a space, not "\n": this is a CommonMark
|
||||
// soft line break, and Telegram's rich-block paragraph text does
|
||||
// not render an embedded "\n" as a break at all -- it renders
|
||||
// nothing, jamming the two lines together with no separator
|
||||
// whatsoever. A space is the correct soft-break rendering anyway
|
||||
// and survives regardless of how the client treats a literal "\n".
|
||||
//
|
||||
// A line that ended in a hard break is the exception: the producer
|
||||
// said it is a line, so it closes its own block and the next one
|
||||
// hugs it. Line-oriented reports (/status, /tasks) depend on this;
|
||||
// without it every one of their lines soft-joined into one run-on
|
||||
// paragraph.
|
||||
// A normal line ends a list or quote and continues the paragraph with a
|
||||
// space. A line ending in a hard break closes its own block.
|
||||
p.flushList()
|
||||
p.flushQuote()
|
||||
switch {
|
||||
@@ -412,14 +390,8 @@ func (p *markdownBlockParser) flush() {
|
||||
p.flushParagraph()
|
||||
}
|
||||
|
||||
// appendBlock adds block to the output. Telegram's rich-block renderer adds
|
||||
// no vertical gap between adjacent blocks on its own -- only a heading
|
||||
// carries its own margin -- so two blocks from source lines with no blank
|
||||
// line between them (an intro line immediately followed by a list, two
|
||||
// back-to-back paragraphs) render glued together with no visible break at
|
||||
// all. An empty paragraph spacer before any non-heading-following block
|
||||
// makes that gap explicit instead of relying on client-side spacing that
|
||||
// doesn't exist.
|
||||
// appendBlock adds block, preceded by an empty paragraph as a spacer unless
|
||||
// it follows a heading.
|
||||
func (p *markdownBlockParser) appendBlock(block models.InputRichBlock) {
|
||||
tight := p.tightNext
|
||||
p.tightNext = false
|
||||
|
||||
@@ -28,11 +28,8 @@ import (
|
||||
// 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 lists the sender IDs allowed to use the bot. Empty denies
|
||||
// everyone.
|
||||
AllowedUserIDs []int64
|
||||
// Reload re-reads configuration during /restart and applies it to g.
|
||||
// Supplied by the composition root, which owns config paths. Nil
|
||||
@@ -54,22 +51,12 @@ type Gateway struct {
|
||||
// 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 is where the update watchdog leaves an update's outcome,
|
||||
// relayed on each launch. 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 reports the version each component reports for itself, to
|
||||
// verify update reports. Nil leaves claims unverified.
|
||||
RunningVersions func() map[string]string
|
||||
|
||||
// Dangerous is the sandbox/process authority for /rollback and /stop.
|
||||
@@ -121,24 +108,14 @@ type Gateway struct {
|
||||
|
||||
// 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 tracks in-flight live replies so Stop can abandon them.
|
||||
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 is set when abandonAllLive claims the registry, and reset at
|
||||
// the next launch.
|
||||
liveStopped bool
|
||||
|
||||
log *slog.Logger
|
||||
@@ -218,12 +195,7 @@ func (g *Gateway) RequestRestart() error {
|
||||
}
|
||||
}
|
||||
|
||||
// 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.
|
||||
// Start runs the bot and relaunches it on restart requests until ctx ends.
|
||||
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")
|
||||
@@ -238,11 +210,7 @@ func (g *Gateway) Start(ctx context.Context, client messaging.ChatContract, life
|
||||
cancel()
|
||||
return err
|
||||
}
|
||||
// Confirm to whoever asked, now that the new instance can send.
|
||||
// It is a status notice, not a record: it retracts itself after a
|
||||
// short TTL so it does not sit in the chat as a stale "reloaded"
|
||||
// line. The pre-restart "Reloading…" message from the outgoing
|
||||
// instance stays as the durable acknowledgement.
|
||||
// Confirm the restart with a self-deleting notice.
|
||||
if req := g.pendingRestart; req != nil && req.chatID != 0 {
|
||||
g.sendEphemeral(runCtx, b, req.chatID, req.threadID, "✅ Archie reloaded.")
|
||||
}
|
||||
@@ -612,19 +580,8 @@ func (g *Gateway) handleCallback(ctx context.Context, b *bot.Bot, update *models
|
||||
}
|
||||
}
|
||||
|
||||
// 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.
|
||||
// turnInbound renders a Telegram message as the channel-neutral inbound a
|
||||
// chat turn is built from, with media attachments attached. ok is false
|
||||
// for messages with neither text nor media, which are not turns at all.
|
||||
// media/hasMedia are the caller's already-extracted attachment, so the
|
||||
// caller keeps the voice-note flag it needs without extracting twice.
|
||||
// turnInbound converts a Telegram message into an inbound turn. ok is false
|
||||
// for messages with no text or media.
|
||||
func turnInbound(msg *models.Message, media inboundMedia, hasMedia bool) (messaging.Inbound, bool) {
|
||||
if !hasMedia && msg.Text == "" {
|
||||
return messaging.Inbound{}, false
|
||||
@@ -632,11 +589,7 @@ func turnInbound(msg *models.Message, media inboundMedia, hasMedia bool) (messag
|
||||
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.
|
||||
// The message ID makes redelivery idempotent.
|
||||
SourceID: fmt.Sprintf("%d", msg.ID),
|
||||
ConversationID: conversationID(msg),
|
||||
Sender: msg.From.Username,
|
||||
@@ -704,26 +657,9 @@ func (g *Gateway) submitTurn(ctx context.Context, b *bot.Bot, msg *models.Messag
|
||||
})
|
||||
}
|
||||
|
||||
// drainTurnEvents consumes a streamed turn, rendering deltas, tool calls
|
||||
// and media as they arrive, and returns the final reply.
|
||||
//
|
||||
// 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.
|
||||
//
|
||||
// aborted means the turn was abandoned (as a stop or a failure) and its
|
||||
// reply must not be finalized.
|
||||
// drainTurnEvents renders a streamed turn's events and returns the final
|
||||
// reply. A cancelled turn is abandoned cleanly; a failed one is marked
|
||||
// failed. aborted means the reply must not be finalized.
|
||||
func (g *Gateway) drainTurnEvents(
|
||||
turnCtx context.Context, session string,
|
||||
live *liveReply, stopTyping func(), events <-chan messaging.ChatEvent,
|
||||
@@ -759,13 +695,8 @@ func (g *Gateway) drainTurnEvents(
|
||||
return reply, false
|
||||
}
|
||||
|
||||
// fetchTurnMedia downloads the turn's inbound attachment onto the lane,
|
||||
// where waiting for the Telegram API belongs: the update worker stays free
|
||||
// to serve other messages and a /stop while this download progresses. A
|
||||
// failed download is reported as a failed attachment without starting the
|
||||
// turn, so the answer does not pretend the media was read -- a later
|
||||
// turn's history only knows the note, not the picture, and the model must
|
||||
// not reason from what it never saw.
|
||||
// fetchTurnMedia downloads the turn's attachment. A failed download is
|
||||
// reported and the turn does not start.
|
||||
func (g *Gateway) fetchTurnMedia(ctx context.Context, b *bot.Bot, gm *messaging.Inbound, chatID int64, threadID int) bool {
|
||||
if len(gm.Media) == 0 || gm.Media[0].Data != nil {
|
||||
return true
|
||||
@@ -893,14 +824,8 @@ func (g *Gateway) sendMessage(ctx context.Context, b *bot.Bot, chatID int64, mes
|
||||
}
|
||||
}
|
||||
|
||||
// sendBlocks delivers one message as a Telegram rich message built from
|
||||
// structured blocks and returns the Bot API message ID, or 0 when nothing was
|
||||
// delivered. The ID is what an EphemeralReply's retraction addresses; callers
|
||||
// that only send ignore it.
|
||||
//
|
||||
// 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.
|
||||
// sendBlocks sends one rich message and returns its ID, or 0. A rejected rich
|
||||
// message is resent as plain text.
|
||||
func (g *Gateway) sendBlocks(ctx context.Context, b *bot.Bot, chatID int64, messageThreadID int, blocks []models.InputRichBlock, errMsg string) int {
|
||||
rich := &bot.SendRichMessageParams{
|
||||
ChatID: chatID,
|
||||
@@ -1040,24 +965,8 @@ func (g *Gateway) ValidateConfig(cfg map[string]any) error {
|
||||
// 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.
|
||||
// dropPendingUpdates discards queued updates before long polling starts,
|
||||
// via deleteWebhook. Best-effort.
|
||||
func (g *Gateway) dropPendingUpdates(ctx context.Context, b *bot.Bot) {
|
||||
ctx, cancel := context.WithTimeout(ctx, 10*time.Second)
|
||||
defer cancel()
|
||||
|
||||
@@ -147,12 +147,7 @@ func (g *Gateway) dispatchUpdateAction(ctx context.Context, b *bot.Bot, query *m
|
||||
}
|
||||
g.answerModelCallback(ctx, b, query.ID, "Starting update…", false)
|
||||
g.editUpdateMessage(ctx, b, query, "Update approved. Starting now…")
|
||||
// The callback context belongs to Telegram's short-lived update
|
||||
// handler and is cancelled as soon as this handler returns. The
|
||||
// installer may build an image for several minutes, so detach only
|
||||
// the install operation from that request lifetime. Progress and
|
||||
// final-message edits still use ctx and may harmlessly fail when the
|
||||
// callback request is gone.
|
||||
// Install outside the callback's short-lived context.
|
||||
go g.installUpdate(ctx, b, query, fresh)
|
||||
default:
|
||||
g.answerModelCallback(ctx, b, query.ID, "That update action is no longer valid.", true)
|
||||
@@ -169,14 +164,8 @@ func (g *Gateway) beginUpdate() bool {
|
||||
return true
|
||||
}
|
||||
|
||||
// installUpdate runs the synchronous phase of an update (build/install) and
|
||||
// reports it live. It deliberately never claims the update itself
|
||||
// succeeded: the reference installer queues the daemon restart through a
|
||||
// detached unit precisely so restarting archied.service doesn't kill this
|
||||
// call before it can report a clean exit, which means the restart -- and
|
||||
// whether the new version actually comes up healthy -- happens after this
|
||||
// function returns. That outcome is reported separately, by whichever
|
||||
// archied process boots next, via SendPendingReport.
|
||||
// installUpdate runs and reports an update's install phase. The restart
|
||||
// outcome is reported by the next boot via SendPendingReport.
|
||||
func (g *Gateway) installUpdate(ctx context.Context, b *bot.Bot, query *models.CallbackQuery, snapshot releaseupdate.Snapshot) {
|
||||
defer func() {
|
||||
g.updateMu.Lock()
|
||||
@@ -270,22 +259,8 @@ func formatVersionChanges(result releaseupdate.Result) string {
|
||||
return strings.Join(parts, ", ")
|
||||
}
|
||||
|
||||
// formatPendingReport describes the phase-2 outcome. There are five distinct
|
||||
// cases, not two: the daemon came back up and confirms it is running what was
|
||||
// installed; it came back up but reports running something else; it came back
|
||||
// up and nothing could be checked either way; it didn't come up, and was
|
||||
// rolled back; or it didn't, and there was no backup to roll back to.
|
||||
//
|
||||
// Two of those are easy to collapse into a neighbour and must not be. A
|
||||
// no-backup failure worded like a rollback tells the operator to stand down
|
||||
// while the daemon may still be running the broken version, or not running
|
||||
// at all. An unverified success worded like a confirmed one re-asserts
|
||||
// exactly the claim that went unchecked in the incident this verification
|
||||
// was added for.
|
||||
//
|
||||
// running maps component ID to the version that component reports for
|
||||
// itself; see Report.Verify for why a passed health check is not on its own
|
||||
// evidence that the install took effect.
|
||||
// formatPendingReport describes an update's outcome: confirmed, version
|
||||
// drift, unverified, rolled back, or failed with no backup.
|
||||
func formatPendingReport(report releaseupdate.Report, running map[string]string) string {
|
||||
if !report.RolledBack && report.HealthCheck == "passed" {
|
||||
return formatHealthyReport(report, report.Verify(running))
|
||||
@@ -318,11 +293,7 @@ func formatHealthyReport(report releaseupdate.Report, verification releaseupdate
|
||||
}
|
||||
changes := formatVersionChanges(releaseupdate.Result{Previous: report.Previous, Installed: report.Installed})
|
||||
if len(verification.Confirmed) == 0 {
|
||||
// Nothing self-reported a version we could check the claim against,
|
||||
// so a passed health probe is all we have -- and it only ever
|
||||
// proved that *something* answered. Calling this "Update complete"
|
||||
// would assert the exact thing that went unverified in the incident
|
||||
// this check was added for.
|
||||
// No version could be checked.
|
||||
text := "Update install finished"
|
||||
if changes != "" {
|
||||
text += " (" + changes + ")"
|
||||
@@ -335,30 +306,14 @@ func formatHealthyReport(report releaseupdate.Report, verification releaseupdate
|
||||
}
|
||||
text += ". Health check passed — archie-core is healthy on the new version."
|
||||
if len(verification.Unverified) > 0 {
|
||||
// Something WAS confirmed, so the headline is earned -- but the
|
||||
// version change printed above covers every component the
|
||||
// installer claimed, including ones nothing checked. Naming them
|
||||
// keeps the confirmed part from silently vouching for the rest.
|
||||
// This is the ordinary case, not an edge one: only the daemon can
|
||||
// self-report today, so the agent lands here on every successful
|
||||
// update.
|
||||
// Name the components that were not checked.
|
||||
text += " Not independently checked: " + strings.Join(verification.Unverified, ", ") + "."
|
||||
}
|
||||
return text
|
||||
}
|
||||
|
||||
// formatVersionDrift words the case where the installer reported success and
|
||||
// the health check passed, but a component reports it is running something
|
||||
// other than what was installed.
|
||||
//
|
||||
// "still the version this update meant to replace" is attached PER COMPONENT
|
||||
// rather than stated once for the whole message, because a single sentence
|
||||
// cannot be true of a mixed set: one component can be sitting on the version
|
||||
// the update meant to replace while another is on some third version the
|
||||
// report never mentions. Asserting one cause for both would invent a fact
|
||||
// about at least one of them -- the same defect as the false success this
|
||||
// whole check exists to catch. The trailing sentence is therefore worded to
|
||||
// hold either way, and says only what a passed probe actually establishes.
|
||||
// formatVersionDrift lists components running a version other than the one
|
||||
// installed.
|
||||
func formatVersionDrift(drift []releaseupdate.VersionDrift) string {
|
||||
parts := make([]string, 0, len(drift))
|
||||
for _, d := range drift {
|
||||
@@ -375,15 +330,8 @@ func formatVersionDrift(drift []releaseupdate.VersionDrift) string {
|
||||
"Investigate before retrying — otherwise /update will report success again."
|
||||
}
|
||||
|
||||
// reportPendingUpdate checks for a phase-2 outcome left by the update
|
||||
// watchdog and relays it, exactly like announceRelease -- called on every
|
||||
// gateway launch so it fires whether this is a fresh process boot (the
|
||||
// common case after an update restart) or a later /restart. A report is
|
||||
// cleared as soon as it's handled -- relayed, or found unreadable -- so a
|
||||
// later launch never retries it. An unreadable report is discarded rather
|
||||
// than left in place: without clearing it, every future launch would fail
|
||||
// the same decode and the chat that approved the update would never learn
|
||||
// any outcome at all.
|
||||
// reportPendingUpdate relays and clears a pending update report on launch.
|
||||
// An unreadable report is discarded.
|
||||
func (g *Gateway) reportPendingUpdate(ctx context.Context, b *bot.Bot) {
|
||||
g.updateReportMu.Lock()
|
||||
defer g.updateReportMu.Unlock()
|
||||
@@ -407,23 +355,12 @@ func (g *Gateway) reportPendingUpdate(ctx context.Context, b *bot.Bot) {
|
||||
}
|
||||
}
|
||||
|
||||
// SendPendingReport relays the phase-2 outcome of an update -- whether the
|
||||
// restarted daemon came up healthy, or was rolled back -- to the chat that
|
||||
// originally approved it. Called once, on startup, by whichever archied
|
||||
// process finds a pending report left by the previous boot's install; see
|
||||
// releaseupdate.ReadPendingReport.
|
||||
// SendPendingReport relays an update's outcome to the chat that approved it.
|
||||
func (g *Gateway) SendPendingReport(ctx context.Context, b *bot.Bot, report releaseupdate.Report) {
|
||||
g.sendMessage(ctx, b, report.ChatID, report.ThreadID, formatPendingReport(report, g.runningVersions()))
|
||||
}
|
||||
|
||||
// runningVersions returns the versions components report for themselves, or
|
||||
// nil when the composition root wired none.
|
||||
//
|
||||
// Nil is not a no-op: with nothing to check against, every claim is
|
||||
// Unverified, so the relayed message says the versions could not be
|
||||
// confirmed rather than repeating the pre-verification "healthy on the new
|
||||
// version". That is deliberate -- an unwired gateway should read as
|
||||
// unchecked, not as verified.
|
||||
// runningVersions returns self-reported component versions, or nil.
|
||||
func (g *Gateway) runningVersions() map[string]string {
|
||||
if g.RunningVersions == nil {
|
||||
return nil
|
||||
|
||||
Reference in new issue
Block a user