Satisfy linter

README.md

@@ -52,114 +52,6 @@ A scalable, multi-bot solution for Telegram using Go, GORM, and the Anthropic AP
    go build -o telegram-bot
    ```
 
-## Trying Out New Behavior Safely
-
-Want to experiment with a different personality, tone, or set of instructions without disturbing the bot your users already talk to? Run a second, separate bot just for testing.
-
-Each bot profile is its own config file with its own Telegram token, and bots are fully independent — separate identity, separate chat history, separate settings. So a "test twin" is quick to set up:
-
-1. Create a new bot with [@BotFather](https://t.me/BotFather) and copy its token.
-2. Copy your existing config to a new file, e.g. `cp config/mybot.json config/mybot-test.json`.
-3. In the new file, paste the new token, give it a different `id`, and edit `system_prompts` to try your changes.
-4. Start it alongside your main bot. Chat with the test bot, tweak its prompt, and restart the test bot to try again — your real users never see the experiments.
-5. Happy with the result? Copy the same change into your main bot's config and restart it.
-
-> [!NOTE]
-> A test bot always needs its **own** token. Telegram only lets one running bot listen on a given token, so you can't point a second copy at your live bot — give the twin its own @BotFather bot instead.
-
-## Configuration
-
-Each bot is one JSON file in `config/` (see `config/default.json` for the template). Keys of note:
-
-| Key                | Type   | Default     | Description |
-| ------------------ | ------ | ----------- | ----------- |
-| `max_tokens`       | number | `1000`      | Maximum output tokens per reply. **Thinking tokens count toward this limit** — raise it (e.g. `4000`+) whenever `thinking` is `"adaptive"`, or a turn can spend the whole budget on reasoning and produce no text. |
-| `thinking`         | string | *(omitted)* | Reasoning mode: `"adaptive"` (the model decides when and how much to think) or `"disabled"`. Omit the key entirely to use the model's own API default. If the configured model doesn't support the chosen mode, the API rejects the request with a 400 — owners/admins see the raw error, regular users get the generic fallback. Check [Anthropic's model docs](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking) for per-model support. |
-| `thinking_display` | string | *(omitted)* | `"summarized"` or `"omitted"`. Only valid together with `"thinking": "adaptive"`. Controls whether the API returns a readable summary of the reasoning (logged, never sent to chat). Thinking is billed the same either way; when omitted, the API's per-model default applies. |
-| `debounce_ms`      | number | *(omitted)* | Quiet window, in milliseconds, for coalescing rapid follow-up messages into a single turn. Omit or set `0` to disable. See [Coalescing rapid messages](#coalescing-rapid-messages) below. |
-| `cache_history`    | bool   | `true`      | Places a prompt-cache breakpoint on the trailing conversation block, so each turn reads the prior history from cache instead of reprocessing it at full price. Set `false` to cache only the system prompt. |
-| `web_search`       | object | *(omitted)* | Enables Anthropic's server-side web search (and, optionally, web fetch), sandboxed to a domain allowlist. Omit the key entirely to leave both tools off — an absent block sends byte-identical requests to before. See [Web search / fetch](#web-search--fetch) below. |
-
-Every reply logs one accounting line — `[usage] model=... in=... out=... thinking=... cache_read=... cache_write=... stop=...` — so thinking spend (billed even when its text is omitted) stays visible in `journalctl`/`docker compose logs`. A `stop=max_tokens` line is accompanied by an error-level warning that the reply was truncated.
-
-> [!TIP]
-> Watch `cache_read`/`cache_write` after changing prompts or models. A cache breakpoint below the model's minimum cacheable prefix fails **silently** — no error, just `cache_write=0` forever. The minimum is model-specific and not monotonic across generations (Haiku 4.5 needs 4096 tokens; Sonnet 4.6 needs 1024), so a short system prompt that caches fine on one model may never cache on another. Note also that chat memory is a sliding window: once it is full, each turn evicts the oldest message and changes the prefix, so `cache_read` on long-running chats will be lower than on fresh ones.
-
-### Coalescing rapid messages
-
-A user who sends "how do I do X", then "sorry typo", then "lmao" in five seconds would otherwise get three separate replies — the bot starts a full turn per message, because each Telegram update independently drives one. `debounce_ms` holds text messages in a per-chat buffer and resets the window on every new message, dispatching a single turn once the user stops typing.
-
-```json
-"debounce_ms": 2500
-```
-
-Reasonable windows are 1500–3000ms for ordinary chat and up to 8000ms for Telegram Business, where a person writing to a business account tends to send longer bursts. The maximum is 30000ms.
-
-Nothing is discarded while buffering. Each message is still persisted and added to chat memory the moment it arrives, so the single coalesced turn sees all of them — the buffer only decides *when* to answer, never *what* the model reads. Reply metadata (language, premium status, business connection) follows the most recent message in the batch.
-
-What deliberately does **not** wait:
-
-- **Commands** (`/stats`, `/clear`, …) dispatch immediately.
-- **Photos, albums, voice, and stickers** dispatch immediately and cancel any pending text window. The buffered text is not lost — it is already in memory, so the media turn answers it too.
-- **`/clear` and `/clear_hard`** cancel the buffer outright. Without this, the window would fire seconds after the wipe and replay the just-deleted messages back into memory.
-
-While a turn is running the bot shows Telegram's "typing…" indicator (or "recording audio" while synthesising a voice reply), refreshed every 4 seconds because Telegram expires the status after 5. Without it, a debounce window reads as the bot ignoring you — which is what prompts users to send more messages in the first place.
-
-> [!NOTE]
-> Debouncing is the cheap fix and the reason there is no "cancel the in-flight request" mode. Anthropic bills input tokens plus any output already generated when a turn stops partway, and any web searches it already ran are billed and re-billed on the retry. A message that never dispatched costs nothing.
-
-### Web search / fetch
-
-The `web_search` block wires in Anthropic's server-side `web_search` (and optionally `web_fetch`) tools, mirroring how `mcp_servers` wires in MCP toolsets: the engine provides the generic mechanism, and the per-bot config carries the policy. **No domains are hardcoded in the engine** — each profile declares its own allowlist. When the model decides a question needs current information, it runs a search server-side; results and any fetch targets are confined to the domains you list.
-
-```json
-"web_search": {
-  "allowed_domains": [
-    "example.com/help",
-    "docs.example.com"
-  ],
-  "max_uses": 3,
-  "fetch": true,
-  "max_content_tokens": 50000
-}
-```
-
-| Field                  | Type     | Description |
-| ---------------------- | -------- | ----------- |
-| `allowed_domains`      | string[] | Restricts **`web_search`** results (and, by default, `web_fetch` targets) to these. Each entry is a **domain with an optional path prefix and no scheme** — `example.com` or `example.com/help`. Mutually exclusive with `blocked_domains`. **The path only scopes `web_search`** — see the asymmetry note below. |
-| `blocked_domains`      | string[] | Excludes these domains instead of allowlisting. Mutually exclusive with `allowed_domains` (setting both fails validation at boot, since the API 400s). |
-| `fetch_allowed_domains`| string[] | **Host-only** allowlist for `web_fetch`, independent of the search list. Omit it and `web_fetch` reuses the *hosts* of `allowed_domains`. Set it to fetch a **narrower** set than you search — e.g. to keep a shared host (a social platform) search-only. Only meaningful with `fetch: true`. |
-| `max_uses`             | number   | Caps how many searches the model may run per turn. Omit for no cap. |
-| `fetch`                | bool     | Also enable `web_fetch`, which pulls full page content for URLs already surfaced by a search or pasted by the user (it cannot fetch model-invented URLs). Citations are always on when fetch is enabled, so fetched passages are sourceable. |
-| `max_content_tokens`   | number   | Caps the tokens a single `web_fetch` may pull into context. Only meaningful with `fetch: true`. |
-
-**Search/fetch path asymmetry (important).** Anthropic filters the two tools differently: `web_search` honors a path prefix (`example.com/help` matches only `example.com/help/...`), but **`web_fetch` matches on the host only — an entry that includes a path never matches any fetch URL**. The engine bridges this: `web_search` gets your entries verbatim, while `web_fetch` gets the host portion of each entry (path stripped, deduped). So a path-scoped `allowed_domains` still permits fetching across the whole host. If that host isn't wholly trusted, list the fetchable hosts explicitly in `fetch_allowed_domains` instead.
-
-**Search-only pattern for shared hosts (e.g. social).** To let the model *search* a single account on a shared platform without ever *fetching* the wider platform, put the account path in `allowed_domains` and leave its host out of `fetch_allowed_domains`:
-
-```json
-"web_search": {
-  "allowed_domains": ["helpcenter.example/hc", "x.com/youraccount"],
-  "fetch_allowed_domains": ["helpcenter.example"],
-  "fetch": true
-}
-```
-
-Here search is confined to your help center *and* your one social account, but fetch can only ever reach `helpcenter.example` — a pasted `x.com/someone-else` URL is not fetchable. Note the search side only sandboxes cleanly on platforms that keep an account's content under its handle path (X/Twitter, TikTok `@handle`, Facebook); use the `handle/` or `handle/*` form to avoid a prefix bleed. Instagram is an exception — posts live at `instagram.com/p/<code>`, not under the handle — so it can't be account-sandboxed by path.
-
-The allowlist is a **hard, server-side sandbox**, not a prompt request — off-list results are dropped and an off-list fetch target returns `url_not_allowed`, which is the exfiltration mitigation Anthropic recommends for bots processing untrusted input. Keep the list tight. A fetch can still fail for site-side reasons (bot protection such as Cloudflare returns `url_not_accessible`); the search snippet plus citations remain the reliable signal, so a full fetch is a bonus, not a dependency.
-
-`web_fetch` can only open a URL that a `web_search` result surfaced (or the user pasted) — never one the model invents or rebuilds from a page title; those return `url_not_in_prior_context`. So a fetch-enabled bot's prompt should steer it to **search first, then fetch a returned URL**, and to **re-search with a more specific query** (rather than guess a URL) when the exact page it wants isn't in the results.
-
-Web search is **not free** — Anthropic bills per search (plus the tokens the results add) — so scope the allowlist and `max_uses` deliberately, and lean on a prompt that tells the bot to search only when a question actually turns on current or authoritative information. Search activity logs as `[web] ...` lines, and long multi-search turns are handled transparently (the engine follows Anthropic's `pause_turn` continuations up to a small cap, so a slow search doesn't truncate the reply).
-
-> [!TIP]
-> For deep request/response debugging, the Anthropic Go SDK ships `option.WithDebugLog(...)` (dumps full HTTP bodies with auth headers redacted). It is not wired into the bot — dev-only, add it temporarily to the client constructor if you ever need wire-level traces.
-
-### Future: persistent memory
-
-The Anthropic memory tool (`memory_20250818`) is a candidate future feature for cross-conversation recall (a self-hosted analog of ChatGPT's "memory"). The Go SDK already ships the types (`BetaMemoryTool20250818Param` and its tool-union slot plus the six-command union: `view`/`create`/`str_replace`/`insert`/`delete`/`rename`), but — unlike the Python/TypeScript/Java SDKs — provides **no handler helper**: the bot would have to hand-write client-side command dispatch against per-chat storage, including strict path validation (canonicalize and confine every model-supplied path under a fixed memory root; reject `..`/symlink traversal) and a no-secrets policy for stored content. Not implemented yet.
-
 ## Systemd Unit Setup
 
 To enable the bot to start automatically on system boot and run in the background, set up a systemd unit.

album_buffer.go

@@ -8,18 +8,37 @@ import (
 	"github.com/go-telegram/bot/models"
 )
 
+// albumFlushWindow is the debounce delay before a buffered Telegram media_group
+// is flushed as a single coalesced user turn. 1s matches the de-facto community
+// standard across the dominant third-party album plugins (aiogram-media-group,
+// DieTime/telegraf-media-group) and sits above the sub-100ms values documented
+// as lossy under network jitter (openclaw#1811). Telegram has no official
+// "album complete" signal, so timeout-based flush is the only option.
 const albumFlushWindow = 1 * time.Second
 
+// pendingAlbum holds a Telegram media_group as its items arrive, plus the
+// per-user metadata captured from the first item. All items in an album share
+// the same chat/user, so we record metadata once and reuse it at flush time.
 type pendingAlbum struct {
-	items                                       []*models.Message
+	items []*models.Message
+	// Metadata captured from the first arriving item. Albums always come from
+	// the same user/chat, so these are stable across the buffering window.
 	chatID, userID                              int64
 	username, firstName, lastName, languageCode string
 	isPremium                                   bool
 	messageTime                                 int
+	isNewChat, isOwner                          bool
 	businessConnectionID                        string
-	timer                                       *time.Timer
+	// timer flushes the album after albumFlushWindow with no further arrivals.
+	// Each new arrival stops the previous timer (best-effort) and installs a
+	// fresh one — the standard debounce pattern.
+	timer *time.Timer
 }
 
+// bufferAlbumItem appends an incoming Telegram album item to the per-MediaGroupID
+// buffer. On first arrival it captures the user/chat metadata and starts the
+// flush timer; on subsequent arrivals it appends the item and extends the timer.
+// The 1s debounce gives the rest of the album time to arrive over the network.
 func (b *Bot) bufferAlbumItem(
 	ctx context.Context,
 	msg *models.Message,
@@ -28,6 +47,7 @@ func (b *Bot) bufferAlbumItem(
 	isPremium bool,
 	languageCode string,
 	messageTime int,
+	isNewChat, isOwner bool,
 	businessConnectionID string,
 ) {
 	b.albumBuffersMu.Lock()
@@ -44,12 +64,17 @@ func (b *Bot) bufferAlbumItem(
 			isPremium:            isPremium,
 			languageCode:         languageCode,
 			messageTime:          messageTime,
+			isNewChat:            isNewChat,
+			isOwner:              isOwner,
 			businessConnectionID: businessConnectionID,
 		}
 		b.albumBuffers[msg.MediaGroupID] = album
 	}
 	album.items = append(album.items, msg)
 
+	// Stop the previous timer best-effort; even if it already fired the race
+	// is benign because flushAlbum removes the map entry under the lock — a
+	// late arrival would simply seed a fresh album.
 	if album.timer != nil {
 		album.timer.Stop()
 	}
@@ -59,6 +84,10 @@ func (b *Bot) bufferAlbumItem(
 	})
 }
 
+// flushAlbum is called by the flush timer (or by code that needs to force-flush
+// during shutdown). It removes the album from the buffer, sorts items by
+// message_id (Telegram does not guarantee in-order arrival), runs the rate-limit
+// check once, and dispatches to handlePhotoMessage.
 func (b *Bot) flushAlbum(ctx context.Context, mediaGroupID string) {
 	b.albumBuffersMu.Lock()
 	album, exists := b.albumBuffers[mediaGroupID]
@@ -68,11 +97,15 @@ func (b *Bot) flushAlbum(ctx context.Context, mediaGroupID string) {
 	}
 	delete(b.albumBuffers, mediaGroupID)
 	items := album.items
-	captured := *album
+	captured := *album // copy fields for use after unlock
 	b.albumBuffersMu.Unlock()
 
+	// Sort by Telegram message_id: items in an album arrive as separate Updates
+	// over the network and may interleave. Sorting restores the user's intended
+	// order before we hand them to Claude.
 	sort.Slice(items, func(i, j int) bool { return items[i].ID < items[j].ID })
 
+	// Rate-limit fires once per coalesced album, not once per item.
 	if !b.checkRateLimits(captured.userID) {
 		b.sendRateLimitExceededMessage(ctx, captured.chatID, captured.businessConnectionID)
 		return
@@ -83,6 +116,7 @@ func (b *Bot) flushAlbum(ctx context.Context, mediaGroupID string) {
 		captured.chatID, captured.userID,
 		captured.username, captured.firstName, captured.lastName,
 		captured.isPremium, captured.languageCode, captured.messageTime,
+		captured.isNewChat, captured.isOwner,
 		captured.businessConnectionID,
 	)
 }

anthropic.go

@@ -6,71 +6,128 @@ import (
 	"fmt"
 	"net/http"
 	"strings"
-	"sync/atomic"
 	"time"
 
 	"github.com/anthropics/anthropic-sdk-go"
 	"github.com/anthropics/anthropic-sdk-go/packages/param"
 )
 
+// ErrModelNotFound is returned when the configured Anthropic model is no longer available
+// (deprecated or removed). Callers can use errors.Is to detect this and surface an
+// actionable message to admins/owners while keeping the response vague for regular users.
 var ErrModelNotFound = errors.New("model not found or deprecated")
 
+// maxFileNotFoundRetries caps the runtime 404 self-heal loop. If multiple
+// referenced file_ids are gone from Anthropic simultaneously (admin purge, AUP
+// enforcement, etc.), we strip them one at a time and retry. Three attempts
+// covers all realistic cascades without leaving the call hanging indefinitely.
 const maxFileNotFoundRetries = 3
 
-const maxPauseTurnContinuations = 5
+// getAnthropicResponse streams the model's response. Each completed text block
+// is delivered to onSegment as soon as the model finishes writing it — so the
+// caller can send segments to Telegram with natural rhythm around tool calls,
+// rather than batched at the very end of the turn. onSegment may be nil for
+// callers that only want the joined text (voice TTS, sticker reactions, etc.).
+// The returned string is every text segment joined by blank lines.
+//
+// chatID is required for the runtime 404 self-heal: when Anthropic returns
+// "File not found:" for a referenced file_id, the dead file_id is stripped
+// from this chat's in-memory ChatMemory and the corresponding DB rows are
+// stamped FilesCleanedAt so a reconciliation job can finish the cleanup.
+func (b *Bot) getAnthropicResponse(ctx context.Context, chatID int64, messages []anthropic.BetaMessageParam, isNewChat, isOwner, isEmojiOnly bool, username string, firstName string, lastName string, isPremium bool, languageCode string, messageTime int, onSegment func(string) error) (string, error) {
+	// Use prompts from config
+	var systemMessage string
+	if isNewChat {
+		systemMessage = b.config.SystemPrompts["new_chat"]
+	} else {
+		systemMessage = b.config.SystemPrompts["continue_conversation"]
+	}
 
-const defaultMaxTokens = 1000
+	// Combine default prompt with custom instructions
+	systemMessage = b.config.SystemPrompts["default"] + " " + b.config.SystemPrompts["custom_instructions"] + " " + systemMessage
 
-const mcpUnsupportedSentinel = "format not currently supported by the Anthropic API"
+	// Handle username placeholder
+	usernameValue := username
+	if username == "" {
+		usernameValue = "unknown" // Use "unknown" when username is not available
+	}
+	systemMessage = strings.ReplaceAll(systemMessage, "{username}", usernameValue)
 
-var mcpUnsupportedCount atomic.Uint64
+	// Handle firstname placeholder
+	firstnameValue := firstName
+	if firstName == "" {
+		firstnameValue = "unknown" // Use "unknown" when first name is not available
+	}
+	systemMessage = strings.ReplaceAll(systemMessage, "{firstname}", firstnameValue)
 
-type mcpCall struct{ server, name, input string }
+	// Handle lastname placeholder
+	lastnameValue := lastName
+	if lastName == "" {
+		lastnameValue = "" // Empty string when last name is not available
+	}
+	systemMessage = strings.ReplaceAll(systemMessage, "{lastname}", lastnameValue)
 
-func (b *Bot) getAnthropicResponse(ctx context.Context, chatID int64, messages []anthropic.BetaMessageParam, isEmojiOnly bool, username string, firstName string, lastName string, isPremium bool, languageCode string, messageTime int, onSegment func(string) error) (string, error) {
-	staticPrompt := strings.TrimSpace(b.config.SystemPrompts["custom_instructions"])
+	// Handle language code placeholder
+	langValue := languageCode
+	if languageCode == "" {
+		langValue = "en" // Default to English when language code is not available
+	}
+	systemMessage = strings.ReplaceAll(systemMessage, "{language}", langValue)
 
+	// Handle premium status
+	premiumStatus := "regular user"
+	if isPremium {
+		premiumStatus = "premium user"
+	}
+	systemMessage = strings.ReplaceAll(systemMessage, "{premium_status}", premiumStatus)
+
+	// Handle time awareness
+	timeObj := time.Unix(int64(messageTime), 0)
+	hour := timeObj.Hour()
+	var timeContext string
+	if hour >= 5 && hour < 12 {
+		timeContext = "morning"
+	} else if hour >= 12 && hour < 18 {
+		timeContext = "afternoon"
+	} else if hour >= 18 && hour < 22 {
+		timeContext = "evening"
+	} else {
+		timeContext = "night"
+	}
+	systemMessage = strings.ReplaceAll(systemMessage, "{time_context}", timeContext)
+
+	if !isOwner {
+		systemMessage += " " + b.config.SystemPrompts["avoid_sensitive"]
+	}
+
+	if isEmojiOnly {
+		systemMessage += " " + b.config.SystemPrompts["respond_with_emojis"]
+	}
+
+	// Debug logging
 	InfoLogger.Printf("Sending %d messages to Anthropic", len(messages))
 
-	maxTokens := int64(defaultMaxTokens)
-	if b.config.MaxTokens > 0 {
-		maxTokens = int64(b.config.MaxTokens)
-	}
 	params := anthropic.BetaMessageNewParams{
 		Model:     b.config.Model,
-		MaxTokens: maxTokens,
+		MaxTokens: 1000,
 		Messages:  messages,
-		Betas:     []anthropic.AnthropicBeta{anthropic.AnthropicBetaFilesAPI2025_04_14},
-	}
-
-	if staticPrompt != "" {
-		blocks := []anthropic.BetaTextBlockParam{
-			{Text: staticPrompt, CacheControl: anthropic.NewBetaCacheControlEphemeralParam()},
-		}
-		tail := buildUserContext(username, firstName, lastName, isPremium, languageCode, messageTime)
-		if isEmojiOnly {
-			if rule := strings.TrimSpace(b.config.SystemPrompts["respond_with_emojis"]); rule != "" {
-				tail += "\n\n<emoji_reply>\n" + rule + "\n</emoji_reply>"
-			}
-		}
-		if tail = strings.TrimSpace(tail); tail != "" {
-			blocks = append(blocks, anthropic.BetaTextBlockParam{Text: tail})
-		}
-		params.System = blocks
+		System:    []anthropic.BetaTextBlockParam{{Text: systemMessage}},
+		// Files API beta is always on: replayed conversation history may carry
+		// image content blocks that reference file_ids uploaded on prior turns.
+		Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaFilesAPI2025_04_14},
 	}
 
+	// Apply temperature if set in config
 	if b.config.Temperature != nil {
 		params.Temperature = param.NewOpt(float64(*b.config.Temperature))
 	}
 
-	if thinking, ok := thinkingParamFromConfig(b.config.Thinking, b.config.ThinkingDisplay); ok {
-		params.Thinking = thinking
-	}
-
-	var tools []anthropic.BetaToolUnionParam
-
+	// MCP servers + matching toolset entries. The mcp-client-2025-11-20 beta
+	// requires per-tool filtering on the toolset (Configs + DefaultConfig),
+	// NOT the deprecated per-server tool_configuration block.
 	if len(b.config.MCPServers) > 0 {
 		mcpServers := make([]anthropic.BetaRequestMCPServerURLDefinitionParam, 0, len(b.config.MCPServers))
+		tools := make([]anthropic.BetaToolUnionParam, 0, len(b.config.MCPServers))
 		for _, s := range b.config.MCPServers {
 			srv := anthropic.BetaRequestMCPServerURLDefinitionParam{
 				Name: s.Name,
@@ -98,185 +155,48 @@ func (b *Bot) getAnthropicResponse(ctx context.Context, chatID int64, messages [
 			tools = append(tools, anthropic.BetaToolUnionParam{OfMCPToolset: toolset})
 		}
 		params.MCPServers = mcpServers
+		params.Tools = tools
 		params.Betas = append(params.Betas, anthropic.AnthropicBetaMCPClient2025_11_20)
 	}
 
-	tools = append(tools, webSearchTools(b.config.WebSearch)...)
-
-	if len(tools) > 0 {
-		params.Tools = tools
-	}
-
-	var fullText strings.Builder
-	var lastMsg anthropic.BetaMessage
-	fileRetries, pauseContinuations := 0, 0
-	for {
-		joined, msg, streamErr := b.streamMessages(ctx, params, onSegment)
-		if streamErr != nil {
-			var apiErr *anthropic.Error
-			if !errors.As(streamErr, &apiErr) || apiErr.StatusCode != http.StatusNotFound {
-				return "", fmt.Errorf("error creating Anthropic message: %w", streamErr)
-			}
-			missingFileID := extractMissingFileID(streamErr)
-			if missingFileID == "" {
-				return "", fmt.Errorf("%w: %s", ErrModelNotFound, b.config.Model)
-			}
-			fileRetries++
-			if fileRetries > maxFileNotFoundRetries {
-				return "", fmt.Errorf("max self-heal retries (%d) exceeded: too many file_ids gone from anthropic", maxFileNotFoundRetries)
-			}
-			ErrorLogger.Printf("[%s] self-heal: stripping dead file_id %s from chat %d (attempt %d/%d)",
-				b.config.ID, missingFileID, chatID, fileRetries, maxFileNotFoundRetries)
-			b.stripDeadFileIDFromMemory(chatID, missingFileID)
-			if _, cleanupErr := b.markFilesPendingCleanup(ctx, chatID, []string{missingFileID}); cleanupErr != nil {
-				ErrorLogger.Printf("[%s] mark files pending cleanup: %v", b.config.ID, cleanupErr)
-			}
-			params.Messages = b.prepareContextMessages(b.getOrCreateChatMemory(chatID))
-			continue
+	// Streaming + 404 self-heal loop. A "File not found:" 404 from Anthropic
+	// (admin purge, AUP enforcement, accidental delete elsewhere) is caught
+	// here: the offending file_id is stripped from in-memory ChatMemory + the
+	// affected DB rows are stamped for the reconciliation job, and the call is
+	// re-issued. The loop caps at maxFileNotFoundRetries so cascading deletions
+	// can't pin the call indefinitely.
+	for attempt := 0; attempt < maxFileNotFoundRetries; attempt++ {
+		joined, streamErr := b.streamMessages(ctx, params, onSegment)
+		if streamErr == nil {
+			return joined, nil
 		}
-
-		lastMsg = msg
-		if joined != "" {
-			if fullText.Len() > 0 {
-				fullText.WriteString("\n\n")
-			}
-			fullText.WriteString(joined)
+		var apiErr *anthropic.Error
+		if !errors.As(streamErr, &apiErr) || apiErr.StatusCode != http.StatusNotFound {
+			return "", fmt.Errorf("error creating Anthropic message: %w", streamErr)
 		}
-
-		if msg.StopReason == anthropic.BetaStopReasonPauseTurn {
-			pauseContinuations++
-			if pauseContinuations > maxPauseTurnContinuations {
-				ErrorLogger.Printf("[%s] pause_turn continuations exceeded (%d); returning partial answer",
-					b.config.ID, maxPauseTurnContinuations)
-				break
-			}
-			params.Messages = append(params.Messages, msg.ToParam())
-			continue
+		missingFileID := extractMissingFileID(streamErr)
+		if missingFileID == "" {
+			// 404 without a "File not found:" body — interpret as model-not-found,
+			// matching the legacy behavior pre-Files-API.
+			return "", fmt.Errorf("%w: %s", ErrModelNotFound, b.config.Model)
 		}
-		break
+		ErrorLogger.Printf("[%s] self-heal: stripping dead file_id %s from chat %d (attempt %d/%d)",
+			b.config.ID, missingFileID, chatID, attempt+1, maxFileNotFoundRetries)
+		b.stripDeadFileIDFromMemory(chatID, missingFileID)
+		if _, cleanupErr := b.markFilesPendingCleanup(ctx, chatID, []string{missingFileID}); cleanupErr != nil {
+			ErrorLogger.Printf("[%s] mark files pending cleanup: %v", b.config.ID, cleanupErr)
+		}
+		params.Messages = b.prepareContextMessages(b.getOrCreateChatMemory(chatID))
 	}
-
-	if fullText.Len() == 0 {
-		return "", emptyStreamError(string(lastMsg.StopReason),
-			lastMsg.Usage.OutputTokensDetails.ThinkingTokens, params.MaxTokens)
-	}
-	return fullText.String(), nil
+	return "", fmt.Errorf("max self-heal retries (%d) exceeded: too many file_ids gone from anthropic", maxFileNotFoundRetries)
 }
 
-func webSearchTools(cfg *WebSearchConfig) []anthropic.BetaToolUnionParam {
-	if cfg == nil {
-		return nil
-	}
-	search := &anthropic.BetaWebSearchTool20250305Param{
-		AllowedDomains: cfg.AllowedDomains,
-		BlockedDomains: cfg.BlockedDomains,
-	}
-	if cfg.MaxUses > 0 {
-		search.MaxUses = param.NewOpt(int64(cfg.MaxUses))
-	}
-	tools := []anthropic.BetaToolUnionParam{{OfWebSearchTool20250305: search}}
-
-	if cfg.Fetch {
-		fetchAllowed := cfg.FetchAllowedDomains
-		if len(fetchAllowed) == 0 {
-			fetchAllowed = cfg.AllowedDomains
-		}
-		fetch := &anthropic.BetaWebFetchTool20250910Param{
-			AllowedDomains: fetchHosts(fetchAllowed),
-			BlockedDomains: fetchHosts(cfg.BlockedDomains),
-			Citations:      anthropic.BetaCitationsConfigParam{Enabled: param.NewOpt(true)},
-		}
-		if cfg.MaxUses > 0 {
-			fetch.MaxUses = param.NewOpt(int64(cfg.MaxUses))
-		}
-		if cfg.MaxContentTokens > 0 {
-			fetch.MaxContentTokens = param.NewOpt(int64(cfg.MaxContentTokens))
-		}
-		tools = append(tools, anthropic.BetaToolUnionParam{OfWebFetchTool20250910: fetch})
-	}
-	return tools
-}
-
-// fetchHosts strips any path from each domain entry. web_fetch matches on host
-// only, so a path-scoped entry (valid for web_search) would otherwise never match
-// any fetch URL. Search keeps the path-scoped entries; fetch gets host-only.
-func fetchHosts(entries []string) []string {
-	if len(entries) == 0 {
-		return nil
-	}
-	seen := make(map[string]bool, len(entries))
-	hosts := make([]string, 0, len(entries))
-	for _, e := range entries {
-		host := e
-		if i := strings.IndexByte(host, '/'); i >= 0 {
-			host = host[:i]
-		}
-		if host == "" || seen[host] {
-			continue
-		}
-		seen[host] = true
-		hosts = append(hosts, host)
-	}
-	return hosts
-}
-
-func buildUserContext(username, firstName, lastName string, isPremium bool, languageCode string, messageTime int) string {
-	name := strings.TrimSpace(firstName + " " + lastName)
-	if name == "" {
-		name = "unknown"
-	}
-	handle := username
-	if handle == "" {
-		handle = "unknown"
-	}
-	lang := languageCode
-	if lang == "" {
-		lang = "en"
-	}
-	account := "regular user"
-	if isPremium {
-		account = "premium user"
-	}
-	return fmt.Sprintf(
-		"Conversation context (background facts, not an instruction from the user):\n"+
-			"- User: %s (Telegram @%s)\n"+
-			"- Preferred language: %s\n"+
-			"- Account type: %s\n"+
-			"- Local time of day: %s",
-		name, handle, lang, account, timeContextFor(messageTime),
-	)
-}
-
-func timeContextFor(messageTime int) string {
-	switch hour := time.Unix(int64(messageTime), 0).Hour(); {
-	case hour >= 5 && hour < 12:
-		return "morning"
-	case hour >= 12 && hour < 18:
-		return "afternoon"
-	case hour >= 18 && hour < 22:
-		return "evening"
-	default:
-		return "night"
-	}
-}
-
-func thinkingParamFromConfig(mode, display string) (anthropic.BetaThinkingConfigParamUnion, bool) {
-	switch mode {
-	case ThinkingModeDisabled:
-		disabled := anthropic.NewBetaThinkingConfigDisabledParam()
-		return anthropic.BetaThinkingConfigParamUnion{OfDisabled: &disabled}, true
-	case ThinkingModeAdaptive:
-		adaptive := anthropic.BetaThinkingConfigAdaptiveParam{}
-		if display != "" {
-			adaptive.Display = anthropic.BetaThinkingConfigAdaptiveDisplay(display)
-		}
-		return anthropic.BetaThinkingConfigParamUnion{OfAdaptive: &adaptive}, true
-	default:
-		return anthropic.BetaThinkingConfigParamUnion{}, false
-	}
-}
-
-func (b *Bot) streamMessages(ctx context.Context, params anthropic.BetaMessageNewParams, onSegment func(string) error) (string, anthropic.BetaMessage, error) {
+// streamMessages runs one streaming call against the Beta Messages API,
+// dispatching each completed text block to onSegment as it arrives. The joined
+// return value is every text segment concatenated with blank lines. Errors from
+// the SDK are returned raw; the caller wraps them (model-not-found, file 404
+// self-heal, etc.).
+func (b *Bot) streamMessages(ctx context.Context, params anthropic.BetaMessageNewParams, onSegment func(string) error) (string, error) {
 	stream := b.anthropicClient.Beta.Messages.NewStreaming(ctx, params)
 	defer func() {
 		if err := stream.Close(); err != nil {
@@ -284,35 +204,28 @@ func (b *Bot) streamMessages(ctx context.Context, params anthropic.BetaMessageNe
 		}
 	}()
 
+	// Per-block accumulators. Reset on content_block_start, consumed on
+	// content_block_stop. Only one block is active at a time per the SSE
+	// contract; SDK guarantees deltas arrive between matching start/stop.
 	var (
-		message                                           anthropic.BetaMessage
 		allSegments                                       []string
 		currentKind                                       string
 		currentText                                       strings.Builder
-		currentThinking                                   strings.Builder
 		currentInputJSON                                  strings.Builder
 		currentTUseName, currentTUseServer, currentTUseID string
 		currentTResultUseID, currentTResultServer         string
 		currentTResultIsError                             bool
 		currentTResultContent                             string
-		currentServerToolName, currentServerToolID        string
-		currentServerResult                               string
-		mcpCalls                                          = map[string]mcpCall{}
 	)
 
 	for stream.Next() {
 		e := stream.Current()
-		if accErr := message.Accumulate(e); accErr != nil {
-			ErrorLogger.Printf("[stream] accumulate failed: %v", accErr)
-		}
 		switch e.Type {
 		case "content_block_start":
 			cbs := e.AsContentBlockStart()
 			currentKind = cbs.ContentBlock.Type
 			currentText.Reset()
-			currentThinking.Reset()
 			currentInputJSON.Reset()
-			currentServerResult = ""
 			switch currentKind {
 			case "mcp_tool_use":
 				currentTUseName = cbs.ContentBlock.Name
@@ -322,12 +235,9 @@ func (b *Bot) streamMessages(ctx context.Context, params anthropic.BetaMessageNe
 				currentTResultUseID = cbs.ContentBlock.ToolUseID
 				currentTResultServer = cbs.ContentBlock.ServerName
 				currentTResultIsError = cbs.ContentBlock.IsError
+				// Tool-result content arrives populated on start (server-side
+				// pre-assembled), not via subsequent deltas like text/JSON.
 				currentTResultContent = cbs.ContentBlock.JSON.Content.Raw()
-			case "server_tool_use":
-				currentServerToolName = cbs.ContentBlock.Name
-				currentServerToolID = cbs.ContentBlock.ID
-			case "web_search_tool_result", "web_fetch_tool_result":
-				currentServerResult = cbs.ContentBlock.JSON.Content.Raw()
 			}
 
 		case "content_block_delta":
@@ -337,12 +247,8 @@ func (b *Bot) streamMessages(ctx context.Context, params anthropic.BetaMessageNe
 				if currentKind == "text" {
 					currentText.WriteString(cbd.Delta.Text)
 				}
-			case "thinking_delta":
-				if currentKind == "thinking" {
-					currentThinking.WriteString(cbd.Delta.Thinking)
-				}
 			case "input_json_delta":
-				if currentKind == "mcp_tool_use" || currentKind == "server_tool_use" {
+				if currentKind == "mcp_tool_use" {
 					currentInputJSON.WriteString(cbd.Delta.PartialJSON)
 				}
 			}
@@ -355,16 +261,14 @@ func (b *Bot) streamMessages(ctx context.Context, params anthropic.BetaMessageNe
 					allSegments = append(allSegments, seg)
 					if onSegment != nil {
 						if cbErr := onSegment(seg); cbErr != nil {
+							// Log but keep streaming — the model's response
+							// is still inbound; we want it recorded even if
+							// one Telegram send failed.
 							ErrorLogger.Printf("[stream] onSegment failed: %v", cbErr)
 						}
 					}
 				}
 			case "mcp_tool_use":
-				mcpCalls[currentTUseID] = mcpCall{
-					server: currentTUseServer,
-					name:   currentTUseName,
-					input:  currentInputJSON.String(),
-				}
 				InfoLogger.Printf("[mcp] tool_use server=%q name=%q id=%q input=%s",
 					currentTUseServer, currentTUseName, currentTUseID, currentInputJSON.String())
 			case "mcp_tool_result":
@@ -374,34 +278,9 @@ func (b *Bot) streamMessages(ctx context.Context, params anthropic.BetaMessageNe
 				}
 				InfoLogger.Printf("[mcp] tool_result tool_use_id=%q server=%q is_error=%v content=%s",
 					currentTResultUseID, currentTResultServer, currentTResultIsError, preview)
-				if strings.Contains(currentTResultContent, mcpUnsupportedSentinel) {
-					total := mcpUnsupportedCount.Add(1)
-					call := mcpCalls[currentTResultUseID]
-					ErrorLogger.Printf("[%s][mcp][unsupported] connector could not serialize result "+
-						"(total=%d): server=%q tool=%q input=%s tool_use_id=%q",
-						b.config.ID, total, call.server, call.name, call.input, currentTResultUseID)
-				}
-			case "server_tool_use":
-				InfoLogger.Printf("[web] %s id=%q input=%s",
-					currentServerToolName, currentServerToolID, currentInputJSON.String())
-			case "web_search_tool_result", "web_fetch_tool_result":
-				preview := currentServerResult
-				if len(preview) > 500 {
-					preview = preview[:500] + "...(truncated)"
-				}
-				InfoLogger.Printf("[web] %s content=%s", currentKind, preview)
-			case "thinking", "redacted_thinking":
-				if summary := strings.TrimSpace(currentThinking.String()); summary != "" {
-					if len(summary) > 500 {
-						summary = summary[:500] + "...(truncated)"
-					}
-					InfoLogger.Printf("[thinking] block complete: %s", summary)
-				} else {
-					InfoLogger.Printf("[thinking] block complete (content omitted)")
-				}
 			default:
 				if currentKind != "" {
-					InfoLogger.Printf("[stream] block type=%q (unhandled)", currentKind)
+					InfoLogger.Printf("[mcp] block type=%q (unhandled)", currentKind)
 				}
 			}
 			currentKind = ""
@@ -409,32 +288,10 @@ func (b *Bot) streamMessages(ctx context.Context, params anthropic.BetaMessageNe
 	}
 
 	if err := stream.Err(); err != nil {
-		return "", message, err
+		return "", err
 	}
-
-	stopReason := string(message.StopReason)
-	if stopReason != "" || message.Usage.OutputTokens > 0 {
-		// cache_read/cache_write make the caching configuration falsifiable: a
-		// breakpoint below the model's minimum cacheable prefix fails silently,
-		// reporting cache_write=0 rather than raising an error.
-		InfoLogger.Printf("[usage] model=%s in=%d out=%d thinking=%d cache_read=%d cache_write=%d stop=%s",
-			params.Model, message.Usage.InputTokens, message.Usage.OutputTokens,
-			message.Usage.OutputTokensDetails.ThinkingTokens,
-			message.Usage.CacheReadInputTokens, message.Usage.CacheCreationInputTokens,
-			stopReason)
-		if message.StopReason == anthropic.BetaStopReasonMaxTokens {
-			ErrorLogger.Printf("[usage] response truncated at max_tokens=%d - raise max_tokens (thinking counts toward it)",
-				params.MaxTokens)
-		}
+	if len(allSegments) == 0 {
+		return "", fmt.Errorf("unexpected response format from Anthropic")
 	}
-
-	return strings.Join(allSegments, "\n\n"), message, nil
-}
-
-func emptyStreamError(stopReason string, thinkingTokens, maxTokens int64) error {
-	if stopReason == "max_tokens" {
-		return fmt.Errorf("output budget exhausted before any text (thinking used %d of %d max_tokens) - raise max_tokens",
-			thinkingTokens, maxTokens)
-	}
-	return fmt.Errorf("unexpected response format from Anthropic")
+	return strings.Join(allSegments, "\n\n"), nil
 }

anthropic_files.go

@@ -12,12 +12,25 @@ import (
 	"github.com/anthropics/anthropic-sdk-go"
 )
 
+// fileNotFoundPrefix is the exact prefix Anthropic uses in its 404 error body
+// when a referenced file_id no longer exists. Used by extractMissingFileID to
+// identify the offender for the runtime self-heal path.
 const fileNotFoundPrefix = "File not found: "
 
+// formatUploadFilename returns the canonical filename used when uploading a
+// Telegram photo to the Anthropic Files API. The "tg-" prefix tags the file as
+// bot-owned so a future reconciliation job can distinguish our uploads from
+// foreign files in the same workspace. The triple (botID, chatID, tgMessageID)
+// is unique within Telegram's scope — each photo in an album arrives as a
+// distinct Telegram message with its own message_id, so collisions across
+// album items are impossible.
 func formatUploadFilename(botID uint, chatID int64, tgMessageID int, ext string) string {
 	return fmt.Sprintf("tg-%d-%d-%d.%s", botID, chatID, tgMessageID, ext)
 }
 
+// uploadImageToAnthropic uploads raw image bytes to the Anthropic Files API and
+// returns the resulting file_id. The filename should follow the formatUploadFilename
+// convention so the reconciliation job can identify the file as bot-owned.
 func (b *Bot) uploadImageToAnthropic(ctx context.Context, data []byte, filename, contentType string) (string, error) {
 	resp, err := b.anthropicClient.Beta.Files.Upload(ctx, anthropic.BetaFileUploadParams{
 		File:  anthropic.File(bytes.NewReader(data), filename, contentType),
@@ -29,6 +42,10 @@ func (b *Bot) uploadImageToAnthropic(ctx context.Context, data []byte, filename,
 	return resp.ID, nil
 }
 
+// deleteFileFromAnthropic removes a file from the Anthropic Files API. A 404
+// is treated as success — the file is already gone, which is the same effective
+// outcome the caller wants. This makes the deletion idempotent and safe for the
+// reconciliation job's retries.
 func (b *Bot) deleteFileFromAnthropic(ctx context.Context, fileID string) error {
 	_, err := b.anthropicClient.Beta.Files.Delete(ctx, fileID, anthropic.BetaFileDeleteParams{
 		Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaFilesAPI2025_04_14},
@@ -43,6 +60,11 @@ func (b *Bot) deleteFileFromAnthropic(ctx context.Context, fileID string) error
 	return fmt.Errorf("anthropic files delete %s: %w", fileID, err)
 }
 
+// compensatingDelete fires Delete calls for a set of file_ids that were uploaded
+// successfully but couldn't be committed downstream. Errors are logged rather
+// than returned — the caller has already entered an error path, and orphans on
+// Anthropic are harmless (storage is free until the 500 GB workspace cap and the
+// reconciliation job will mop them up).
 func (b *Bot) compensatingDelete(ctx context.Context, fileIDs []string) {
 	for _, fid := range fileIDs {
 		if err := b.deleteFileFromAnthropic(ctx, fid); err != nil {
@@ -51,6 +73,10 @@ func (b *Bot) compensatingDelete(ctx context.Context, fileIDs []string) {
 	}
 }
 
+// extractMissingFileID inspects an Anthropic API error and returns the file_id
+// that triggered a "File not found:" 404, if any. Returns empty string if the
+// error is not a file-not-found error. Used by the runtime self-heal path to
+// identify which file_id to strip from replay.
 func extractMissingFileID(err error) string {
 	if err == nil {
 		return ""
@@ -65,12 +91,19 @@ func extractMissingFileID(err error) string {
 	return parseMissingFileIDFromBody(apiErr.RawJSON())
 }
 
+// parseMissingFileIDFromBody pulls a file_id out of a raw "File not found:"
+// 404 body. Split out from extractMissingFileID so the string-parsing logic
+// is unit-testable without having to synthesize an *anthropic.Error (whose
+// JSON.raw field is private to the SDK).
 func parseMissingFileIDFromBody(raw string) string {
 	idx := strings.Index(raw, fileNotFoundPrefix)
 	if idx == -1 {
 		return ""
 	}
 	rest := raw[idx+len(fileNotFoundPrefix):]
+	// File IDs are file_<base62>; the message embeds them with no surrounding
+	// quotes, so the id ends at the first character outside the alphanumeric +
+	// underscore set.
 	end := strings.IndexFunc(rest, func(r rune) bool {
 		return (r < 'a' || r > 'z') &&
 			(r < 'A' || r > 'Z') &&
@@ -83,7 +116,24 @@ func parseMissingFileIDFromBody(raw string) string {
 	return rest[:end]
 }
 
+// hardDeleteScope performs the three-step hard-delete pattern on every Message
+// row matching the given WHERE clause:
+//
+//  1. Soft-delete the rows (GORM Delete) — they become invisible to replay
+//     immediately, regardless of how the Anthropic-side cleanup unfolds.
+//  2. For each row, call Anthropic Files.Delete on its ImageFileIDs. 404 is
+//     treated as success (already gone).
+//  3. Rows whose file cleanup succeeded are Unscoped().Delete'd. Rows whose
+//     file cleanup failed remain soft-deleted with FilesCleanedAt NULL — the
+//     reconciliation job will retry them.
+//
+// This gives hard-delete eventually-consistent semantics across the DB and
+// Anthropic, while still presenting the user with an instant "history cleared"
+// outcome (the soft-delete in step 1 hides the rows from any further reads).
 func (b *Bot) hardDeleteScope(ctx context.Context, query string, args ...interface{}) error {
+	// Unscoped on the scan: include already-soft-deleted rows so a hard-delete
+	// after a prior soft-delete still removes them completely. Matches the
+	// existing "erase and bust all caches" semantics for /clear_hard.
 	var rows []Message
 	if err := b.db.Unscoped().Where(query, args...).Find(&rows).Error; err != nil {
 		return fmt.Errorf("scan rows: %w", err)
@@ -91,6 +141,9 @@ func (b *Bot) hardDeleteScope(ctx context.Context, query string, args ...interfa
 	if len(rows) == 0 {
 		return nil
 	}
+	// Soft-delete any rows that aren't already soft-deleted (graceful degradation:
+	// if Anthropic-side file cleanup fails, the row stays invisible to replay).
+	// Already-soft-deleted rows are unaffected by Delete without Unscoped.
 	if err := b.db.Where(query, args...).Delete(&Message{}).Error; err != nil {
 		return fmt.Errorf("soft delete: %w", err)
 	}
@@ -110,6 +163,10 @@ func (b *Bot) hardDeleteScope(ctx context.Context, query string, args ...interfa
 	return nil
 }
 
+// deleteRowFiles tries to delete every file_id referenced by row from the
+// Anthropic Files API. Returns true iff all deletes succeeded (or the row had
+// no images), making the row eligible for hard-delete. False means at least
+// one delete failed and the row should stay soft-deleted for retry.
 func (b *Bot) deleteRowFiles(ctx context.Context, row Message) bool {
 	if len(row.ImageFileIDs) == 0 {
 		return true
@@ -124,6 +181,8 @@ func (b *Bot) deleteRowFiles(ctx context.Context, row Message) bool {
 	return allOk
 }
 
+// stripDeadFileIDs returns the subset of src whose ids are NOT in deadSet, and
+// reports whether any were removed. Empty/nil src yields (empty, false).
 func stripDeadFileIDs(src []string, deadSet map[string]struct{}) (survivors []string, dirty bool) {
 	survivors = make([]string, 0, len(src))
 	for _, fid := range src {
@@ -136,6 +195,11 @@ func stripDeadFileIDs(src []string, deadSet map[string]struct{}) (survivors []st
 	return survivors, dirty
 }
 
+// markFilesPendingCleanup removes a set of dead file_ids from any stored Message
+// rows that reference them, and stamps FilesCleanedAt on the affected rows so
+// the reconciliation job can see they've been touched. Called by the runtime
+// self-heal path after a "File not found:" 404 surfaces during message-create.
+// Returns the number of rows updated.
 func (b *Bot) markFilesPendingCleanup(ctx context.Context, chatID int64, deadFileIDs []string) (int, error) {
 	if len(deadFileIDs) == 0 {
 		return 0, nil
@@ -158,9 +222,15 @@ func (b *Bot) markFilesPendingCleanup(ctx context.Context, chatID int64, deadFil
 			continue
 		}
 		if len(survivors) == 0 {
+			// All files in this row are gone; mark fully cleaned so a future
+			// reconciliation job's `WHERE files_cleaned_at IS NULL` filter
+			// correctly excludes it from retries.
 			row.ImageFileIDs = nil
 			row.FilesCleanedAt = &now
 		} else {
+			// Surviving file_ids are still alive on Anthropic. Leave
+			// FilesCleanedAt NULL so a later death of one of them remains
+			// visible to the reconciliation job's filter.
 			row.ImageFileIDs = survivors
 		}
 		if err := b.db.WithContext(ctx).Save(&row).Error; err != nil {

anthropic_files_test.go

@@ -16,6 +16,8 @@ func TestFormatUploadFilename(t *testing.T) {
 		want        string
 	}{
 		{1, 12345, 42, "jpg", "tg-1-12345-42.jpg"},
+		// Negative chat IDs are how Telegram represents groups/channels —
+		// %d preserves the leading minus, no special handling needed.
 		{7, -1001234567890, 1, "png", "tg-7--1001234567890-1.png"},
 		{0, 0, 0, "webp", "tg-0-0-0.webp"},
 	}
@@ -70,10 +72,10 @@ func TestStripDeadFileIDs(t *testing.T) {
 		"file_b": {},
 	}
 	cases := []struct {
-		name          string
-		input         []string
+		name         string
+		input        []string
 		wantSurvivors []string
-		wantDirty     bool
+		wantDirty    bool
 	}{
 		{
 			name:          "no overlap returns input verbatim",
@@ -113,6 +115,7 @@ func TestMarkFilesPendingCleanup(t *testing.T) {
 	b, _ := setupBotForTest(t, 123)
 	chatID := int64(555)
 
+	// Row 1: has dead file_a + alive file_x → should be updated with survivors.
 	row1 := Message{
 		BotID:        b.botID,
 		ChatID:       chatID,
@@ -126,6 +129,7 @@ func TestMarkFilesPendingCleanup(t *testing.T) {
 	}
 	assert.NoError(t, b.db.Create(&row1).Error)
 
+	// Row 2: only dead files → ImageFileIDs should become nil.
 	row2 := Message{
 		BotID:        b.botID,
 		ChatID:       chatID,
@@ -139,6 +143,7 @@ func TestMarkFilesPendingCleanup(t *testing.T) {
 	}
 	assert.NoError(t, b.db.Create(&row2).Error)
 
+	// Row 3: no dead files → should be untouched.
 	row3 := Message{
 		BotID:        b.botID,
 		ChatID:       chatID,
@@ -152,6 +157,7 @@ func TestMarkFilesPendingCleanup(t *testing.T) {
 	}
 	assert.NoError(t, b.db.Create(&row3).Error)
 
+	// Row 4: different chat → must NOT be touched even if it references a dead file.
 	row4 := Message{
 		BotID:        b.botID,
 		ChatID:       999,
@@ -169,21 +175,27 @@ func TestMarkFilesPendingCleanup(t *testing.T) {
 	assert.NoError(t, err)
 	assert.Equal(t, 2, updated, "rows 1 and 2 should have been updated")
 
+	// Row 1: only file_x should remain; FilesCleanedAt MUST stay nil because
+	// file_x is still alive on Anthropic and a future death of it must remain
+	// visible to the reconciliation job's `WHERE files_cleaned_at IS NULL` filter.
 	var r1 Message
 	assert.NoError(t, b.db.First(&r1, row1.ID).Error)
 	assert.Equal(t, []string{"file_x"}, r1.ImageFileIDs)
 	assert.Nil(t, r1.FilesCleanedAt)
 
+	// Row 2: all gone → ImageFileIDs nil/empty; FilesCleanedAt set.
 	var r2 Message
 	assert.NoError(t, b.db.First(&r2, row2.ID).Error)
 	assert.Empty(t, r2.ImageFileIDs)
 	assert.NotNil(t, r2.FilesCleanedAt)
 
+	// Row 3: untouched.
 	var r3 Message
 	assert.NoError(t, b.db.First(&r3, row3.ID).Error)
 	assert.Equal(t, []string{"file_x", "file_y"}, r3.ImageFileIDs)
 	assert.Nil(t, r3.FilesCleanedAt)
 
+	// Row 4: untouched despite referencing a dead file — scope is per-chat.
 	var r4 Message
 	assert.NoError(t, b.db.First(&r4, row4.ID).Error)
 	assert.Equal(t, []string{"file_a"}, r4.ImageFileIDs)

anthropic_test.go

@@ -1,310 +1,197 @@
 package main
 
 import (
-	"encoding/json"
+	"fmt"
 	"strings"
 	"testing"
 	"time"
-
-	"github.com/anthropics/anthropic-sdk-go"
 )
 
-func TestTimeContextFor(t *testing.T) {
-	cases := []struct {
+// TestLanguageCodeReplacement tests that language code is properly handled and replaced
+func TestLanguageCodeReplacement(t *testing.T) {
+	// Test with provided language code
+	systemMessage := "User's language preference: '{language}'"
+
+	// Test with a specific language code
+	langValue := "fr"
+	result := strings.ReplaceAll(systemMessage, "{language}", langValue)
+
+	if !strings.Contains(result, "User's language preference: 'fr'") {
+		t.Errorf("Expected language code 'fr' to be replaced, got: %s", result)
+	}
+
+	// Test with empty language code (should default to "en")
+	langValue = ""
+	if langValue == "" {
+		langValue = "en" // Default to English when language code is not available
+	}
+	result = strings.ReplaceAll(systemMessage, "{language}", langValue)
+
+	if !strings.Contains(result, "User's language preference: 'en'") {
+		t.Errorf("Expected default language code 'en' to be used, got: %s", result)
+	}
+}
+
+// TestPremiumStatusReplacement tests that premium status is properly handled and replaced
+func TestPremiumStatusReplacement(t *testing.T) {
+	systemMessage := "User is a {premium_status}"
+
+	// Test with premium user
+	isPremium := true
+	premiumStatus := "regular user"
+	if isPremium {
+		premiumStatus = "premium user"
+	}
+	result := strings.ReplaceAll(systemMessage, "{premium_status}", premiumStatus)
+
+	if !strings.Contains(result, "User is a premium user") {
+		t.Errorf("Expected premium status to be replaced with 'premium user', got: %s", result)
+	}
+
+	// Test with regular user
+	isPremium = false
+	premiumStatus = "regular user"
+	if isPremium {
+		premiumStatus = "premium user"
+	}
+	result = strings.ReplaceAll(systemMessage, "{premium_status}", premiumStatus)
+
+	if !strings.Contains(result, "User is a regular user") {
+		t.Errorf("Expected premium status to be replaced with 'regular user', got: %s", result)
+	}
+}
+
+// TestTimeContextCalculation tests that time context is correctly calculated for different hours
+func TestTimeContextCalculation(t *testing.T) {
+	// Test cases for different hours
+	testCases := []struct {
 		hour     int
 		expected string
 	}{
-		{3, "night"},
-		{5, "morning"},
-		{11, "morning"},
-		{12, "afternoon"},
-		{17, "afternoon"},
-		{18, "evening"},
-		{21, "evening"},
-		{22, "night"},
-		{23, "night"},
-	}
-	for _, tc := range cases {
-		ts := int(time.Date(2025, 5, 15, tc.hour, 0, 0, 0, time.Local).Unix())
-		if got := timeContextFor(ts); got != tc.expected {
-			t.Errorf("timeContextFor(hour=%d) = %q, want %q", tc.hour, got, tc.expected)
-		}
-	}
-}
-
-func TestBuildUserContext(t *testing.T) {
-	noon := int(time.Date(2025, 5, 15, 12, 0, 0, 0, time.Local).Unix())
-
-	got := buildUserContext("alice", "Alice", "Smith", true, "de", noon)
-	for _, want := range []string{"Alice Smith", "@alice", "Preferred language: de", "premium user", "afternoon"} {
-		if !strings.Contains(got, want) {
-			t.Errorf("buildUserContext premium: missing %q in:\n%s", want, got)
-		}
+		{3, "night"},      // Night: hours < 5 or hours >= 22
+		{5, "morning"},    // Morning: 5 <= hours < 12
+		{12, "afternoon"}, // Afternoon: 12 <= hours < 18
+		{17, "afternoon"}, // Afternoon: 12 <= hours < 18
+		{18, "evening"},   // Evening: 18 <= hours < 22
+		{21, "evening"},   // Evening: 18 <= hours < 22
+		{22, "night"},     // Night: hours < 5 or hours >= 22
+		{23, "night"},     // Night: hours < 5 or hours >= 22
 	}
 
-	got = buildUserContext("", "", "", false, "", noon)
-	for _, want := range []string{"User: unknown (Telegram @unknown)", "Preferred language: en", "regular user"} {
-		if !strings.Contains(got, want) {
-			t.Errorf("buildUserContext fallback: missing %q in:\n%s", want, got)
-		}
-	}
+	for _, tc := range testCases {
+		t.Run(fmt.Sprintf("Hour_%d", tc.hour), func(t *testing.T) {
+			// Create a timestamp for the specified hour
+			testTime := time.Date(2025, 5, 15, tc.hour, 0, 0, 0, time.UTC)
 
-	got = buildUserContext("bob", "Bob", "", false, "en", noon)
-	if !strings.Contains(got, "User: Bob (Telegram @bob)") {
-		t.Errorf("buildUserContext firstname-only: got:\n%s", got)
-	}
-}
+			// Get the hour directly from the test time to ensure it's what we expect
+			actualHour := testTime.Hour()
+			if actualHour != tc.hour {
+				t.Fatalf("Test setup error: expected hour %d, got %d", tc.hour, actualHour)
+			}
 
-func TestThinkingParamFromConfig(t *testing.T) {
-	cases := []struct {
-		name    string
-		mode    string
-		display string
-		ok      bool
-		want    map[string]any
-	}{
-		{"unset omits param", "", "", false, nil},
-		{"unknown value omits param", "bogus", "", false, nil},
-		{"adaptive no display", ThinkingModeAdaptive, "", true,
-			map[string]any{"type": "adaptive"}},
-		{"adaptive summarized", ThinkingModeAdaptive, ThinkingDisplaySummarized, true,
-			map[string]any{"type": "adaptive", "display": "summarized"}},
-		{"adaptive omitted", ThinkingModeAdaptive, ThinkingDisplayOmitted, true,
-			map[string]any{"type": "adaptive", "display": "omitted"}},
-		{"disabled", ThinkingModeDisabled, "", true,
-			map[string]any{"type": "disabled"}},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			union, ok := thinkingParamFromConfig(tc.mode, tc.display)
-			if ok != tc.ok {
-				t.Fatalf("ok = %v, want %v", ok, tc.ok)
+			// Calculate time context using the same logic as in anthropic.go
+			var timeContext string
+			if actualHour >= 5 && actualHour < 12 {
+				timeContext = "morning"
+			} else if actualHour >= 12 && actualHour < 18 {
+				timeContext = "afternoon"
+			} else if actualHour >= 18 && actualHour < 22 {
+				timeContext = "evening"
+			} else {
+				timeContext = "night"
 			}
-			if !tc.ok {
-				return
-			}
-			raw, err := json.Marshal(union)
-			if err != nil {
-				t.Fatalf("marshal: %v", err)
-			}
-			var got map[string]any
-			if err := json.Unmarshal(raw, &got); err != nil {
-				t.Fatalf("unmarshal %s: %v", raw, err)
-			}
-			if len(got) != len(tc.want) {
-				t.Fatalf("wire shape %s: got %d keys, want %d (%v)", raw, len(got), len(tc.want), tc.want)
-			}
-			for k, v := range tc.want {
-				if got[k] != v {
-					t.Errorf("wire shape %s: key %q = %v, want %v", raw, k, got[k], v)
-				}
+
+			// Check if the calculated time context matches the expected value
+			if timeContext != tc.expected {
+				t.Errorf("For hour %d: expected time context '%s', got '%s'",
+					actualHour, tc.expected, timeContext)
 			}
 		})
 	}
 }
 
-func TestBackwardCompatibleParams(t *testing.T) {
-	params := anthropic.BetaMessageNewParams{
-		Model:     "claude-test",
-		MaxTokens: defaultMaxTokens,
-		Messages: []anthropic.BetaMessageParam{
-			anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("hi")),
-		},
+// TestSystemMessagePlaceholderReplacement tests that all placeholders are correctly replaced
+func TestSystemMessagePlaceholderReplacement(t *testing.T) {
+	systemMessage := "The user you're talking to has username '{username}' and display name '{firstname} {lastname}'.\n" +
+		"User's language preference: '{language}'\n" +
+		"User is a {premium_status}\n" +
+		"It's currently {time_context} in your timezone"
+
+	// Set up test data
+	username := "testuser"
+	firstName := "Test"
+	lastName := "User"
+	isPremium := true
+	languageCode := "de"
+
+	// Create a timestamp for a specific hour (e.g., 14:00 = afternoon)
+	testTime := time.Date(2025, 5, 15, 14, 0, 0, 0, time.UTC)
+	messageTime := int(testTime.Unix())
+
+	// Handle username placeholder
+	usernameValue := username
+	if username == "" {
+		usernameValue = "unknown"
 	}
-	raw, err := json.Marshal(params)
-	if err != nil {
-		t.Fatalf("marshal: %v", err)
+	systemMessage = strings.ReplaceAll(systemMessage, "{username}", usernameValue)
+
+	// Handle firstname placeholder
+	firstnameValue := firstName
+	if firstName == "" {
+		firstnameValue = "unknown"
 	}
-	var got map[string]any
-	if err := json.Unmarshal(raw, &got); err != nil {
-		t.Fatalf("unmarshal: %v", err)
+	systemMessage = strings.ReplaceAll(systemMessage, "{firstname}", firstnameValue)
+
+	// Handle lastname placeholder
+	lastnameValue := lastName
+	if lastName == "" {
+		lastnameValue = ""
 	}
-	if _, present := got["thinking"]; present {
-		t.Errorf("zero Thinking union must omit the key; body: %s", raw)
+	systemMessage = strings.ReplaceAll(systemMessage, "{lastname}", lastnameValue)
+
+	// Handle language code placeholder
+	langValue := languageCode
+	if languageCode == "" {
+		langValue = "en"
 	}
-	if mt, ok := got["max_tokens"].(float64); !ok || int(mt) != defaultMaxTokens {
-		t.Errorf("max_tokens = %v, want %d; body: %s", got["max_tokens"], defaultMaxTokens, raw)
-	}
-}
-
-func TestWebSearchTools(t *testing.T) {
-	t.Run("nil config yields no tools", func(t *testing.T) {
-		if tools := webSearchTools(nil); tools != nil {
-			t.Errorf("webSearchTools(nil) = %v, want nil", tools)
-		}
-	})
-
-	t.Run("search only when fetch off", func(t *testing.T) {
-		tools := webSearchTools(&WebSearchConfig{
-			AllowedDomains: []string{"example.com/hc"},
-			MaxUses:        3,
-		})
-		if len(tools) != 1 {
-			t.Fatalf("got %d tools, want 1 (search only)", len(tools))
-		}
-		if tools[0].OfWebSearchTool20250305 == nil {
-			t.Fatalf("tools[0] is not a web_search tool")
-		}
-		if tools[0].OfWebFetchTool20250910 != nil {
-			t.Error("web_fetch tool present but fetch is off")
-		}
-	})
-
-	t.Run("search + fetch with allowlist and citations", func(t *testing.T) {
-		tools := webSearchTools(&WebSearchConfig{
-			AllowedDomains:   []string{"example.com/hc", "docs.example.com"},
-			MaxUses:          3,
-			Fetch:            true,
-			MaxContentTokens: 50000,
-		})
-		if len(tools) != 2 {
-			t.Fatalf("got %d tools, want 2 (search + fetch)", len(tools))
-		}
-
-		search := tools[0].OfWebSearchTool20250305
-		if search == nil {
-			t.Fatalf("tools[0] is not a web_search tool")
-		}
-		if !sameStrings(search.AllowedDomains, []string{"example.com/hc", "docs.example.com"}) {
-			t.Errorf("search AllowedDomains = %v, want the path-scoped list unchanged", search.AllowedDomains)
-		}
-		if search.MaxUses.Value != 3 {
-			t.Errorf("search MaxUses = %d, want 3", search.MaxUses.Value)
-		}
-
-		fetch := tools[1].OfWebFetchTool20250910
-		if fetch == nil {
-			t.Fatalf("tools[1] is not a web_fetch tool")
-		}
-		if !sameStrings(fetch.AllowedDomains, []string{"example.com", "docs.example.com"}) {
-			t.Errorf("fetch AllowedDomains = %v, want host-only [example.com docs.example.com]", fetch.AllowedDomains)
-		}
-		if fetch.MaxContentTokens.Value != 50000 {
-			t.Errorf("fetch MaxContentTokens = %d, want 50000", fetch.MaxContentTokens.Value)
-		}
-		if fetch.Citations.Enabled.Value != true {
-			t.Error("fetch citations not enabled")
-		}
-	})
+	systemMessage = strings.ReplaceAll(systemMessage, "{language}", langValue)
 
-	t.Run("fetch hosts are deduped", func(t *testing.T) {
-		tools := webSearchTools(&WebSearchConfig{
-			AllowedDomains: []string{"a.com/x", "a.com/y", "b.com"},
-			Fetch:          true,
-		})
-		fetch := tools[1].OfWebFetchTool20250910
-		if fetch == nil {
-			t.Fatalf("tools[1] is not a web_fetch tool")
-		}
-		if !sameStrings(fetch.AllowedDomains, []string{"a.com", "b.com"}) {
-			t.Errorf("fetch AllowedDomains = %v, want deduped [a.com b.com]", fetch.AllowedDomains)
-		}
-	})
-
-	t.Run("social host is search-only via fetch_allowed_domains", func(t *testing.T) {
-		tools := webSearchTools(&WebSearchConfig{
-			AllowedDomains:      []string{"helpshift.example/hc", "x.com/thatskygame"},
-			FetchAllowedDomains: []string{"helpshift.example"},
-			Fetch:               true,
-		})
-		search := tools[0].OfWebSearchTool20250305
-		if search == nil {
-			t.Fatalf("tools[0] is not a web_search tool")
-		}
-		var searchHasSocial bool
-		for _, d := range search.AllowedDomains {
-			if d == "x.com/thatskygame" {
-				searchHasSocial = true
-			}
-		}
-		if !searchHasSocial {
-			t.Errorf("search AllowedDomains = %v, want it to include x.com/thatskygame", search.AllowedDomains)
-		}
-
-		fetch := tools[1].OfWebFetchTool20250910
-		if fetch == nil {
-			t.Fatalf("tools[1] is not a web_fetch tool")
-		}
-		if !sameStrings(fetch.AllowedDomains, []string{"helpshift.example"}) {
-			t.Errorf("fetch AllowedDomains = %v, want only [helpshift.example]", fetch.AllowedDomains)
-		}
-		for _, d := range fetch.AllowedDomains {
-			if strings.HasPrefix(d, "x.com") {
-				t.Errorf("fetch AllowedDomains leaked the social host: %v", fetch.AllowedDomains)
-			}
-		}
-	})
-
-	t.Run("wire shape carries allowed_domains", func(t *testing.T) {
-		tools := webSearchTools(&WebSearchConfig{
-			AllowedDomains: []string{"thatgamecompany.helpshift.com/hc"},
-			MaxUses:        2,
-			Fetch:          true,
-		})
-		raw, err := json.Marshal(tools)
-		if err != nil {
-			t.Fatalf("marshal: %v", err)
-		}
-		body := string(raw)
-		for _, want := range []string{
-			"web_search_20250305",
-			"web_fetch_20250910",
-			"thatgamecompany.helpshift.com/hc",
-			"allowed_domains",
-		} {
-			if !strings.Contains(body, want) {
-				t.Errorf("wire body missing %q:\n%s", want, body)
-			}
-		}
-	})
-}
-
-func sameStrings(got, want []string) bool {
-	if len(got) != len(want) {
-		return false
+	// Handle premium status
+	premiumStatus := "regular user"
+	if isPremium {
+		premiumStatus = "premium user"
 	}
-	for i := range got {
-		if got[i] != want[i] {
-			return false
-		}
+	systemMessage = strings.ReplaceAll(systemMessage, "{premium_status}", premiumStatus)
+
+	// Handle time awareness
+	timeObj := time.Unix(int64(messageTime), 0)
+	hour := timeObj.Hour()
+	var timeContext string
+	if hour >= 5 && hour < 12 {
+		timeContext = "morning"
+	} else if hour >= 12 && hour < 18 {
+		timeContext = "afternoon"
+	} else if hour >= 18 && hour < 22 {
+		timeContext = "evening"
+	} else {
+		timeContext = "night"
 	}
-	return true
-}
+	systemMessage = strings.ReplaceAll(systemMessage, "{time_context}", timeContext)
 
-func TestFetchHosts(t *testing.T) {
-	cases := []struct {
-		name string
-		in   []string
-		want []string
-	}{
-		{"nil in nil out", nil, nil},
-		{"empty in nil out", []string{}, nil},
-		{"host passthrough", []string{"example.com"}, []string{"example.com"}},
-		{"strip path", []string{"example.com/hc/en"}, []string{"example.com"}},
-		{"dedup after strip", []string{"a.com/x", "a.com/y"}, []string{"a.com"}},
-		{"preserve order and subdomains", []string{"docs.example.com/a", "example.com"}, []string{"docs.example.com", "example.com"}},
-		{"drop empty leading slash", []string{"/oops", "ok.com"}, []string{"ok.com"}},
+	// Check that all placeholders were replaced correctly
+	if !strings.Contains(systemMessage, "username 'testuser'") {
+		t.Errorf("Username not replaced correctly, got: %s", systemMessage)
 	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			if got := fetchHosts(tc.in); !sameStrings(got, tc.want) {
-				t.Errorf("fetchHosts(%v) = %v, want %v", tc.in, got, tc.want)
-			}
-		})
+	if !strings.Contains(systemMessage, "display name 'Test User'") {
+		t.Errorf("Display name not replaced correctly, got: %s", systemMessage)
 	}
-}
-
-func TestEmptyStreamError(t *testing.T) {
-	err := emptyStreamError("max_tokens", 3900, 4000)
-	for _, want := range []string{"output budget exhausted", "3900", "4000"} {
-		if !strings.Contains(err.Error(), want) {
-			t.Errorf("max_tokens case: %q missing %q", err.Error(), want)
-		}
+	if !strings.Contains(systemMessage, "language preference: 'de'") {
+		t.Errorf("Language preference not replaced correctly, got: %s", systemMessage)
 	}
-	if got := emptyStreamError("end_turn", 0, 1000).Error(); got != "unexpected response format from Anthropic" {
-		t.Errorf("generic case = %q", got)
+	if !strings.Contains(systemMessage, "User is a premium user") {
+		t.Errorf("Premium status not replaced correctly, got: %s", systemMessage)
 	}
-	if got := emptyStreamError("", 0, 1000).Error(); got != "unexpected response format from Anthropic" {
-		t.Errorf("no-stop-reason case = %q", got)
+	if !strings.Contains(systemMessage, "It's currently afternoon in your timezone") {
+		t.Errorf("Time context not replaced correctly, got: %s", systemMessage)
 	}
 }

bot.go

@@ -26,14 +26,15 @@ type Bot struct {
 	userLimiters    map[int64]*userLimiter
 	userLimitersMu  sync.RWMutex
 	clock           Clock
-	botID           uint
-	albumBuffers    map[string]*pendingAlbum
-	albumBuffersMu  sync.Mutex
-	intakeBuffers   map[int64]*pendingIntake
-	intakeBuffersMu sync.Mutex
-	intakeSeq       uint64
+	botID           uint // Reference to BotModel.ID
+	// albumBuffers holds Telegram media_group items as they arrive, keyed by
+	// MediaGroupID. Each pending album has a 1s flush timer (see album_buffer.go)
+	// that triggers a single coalesced photo turn once arrivals stop.
+	albumBuffers   map[string]*pendingAlbum
+	albumBuffersMu sync.Mutex
 }
 
+// Helper function to determine message type
 func messageType(msg *models.Message) string {
 	if msg.Sticker != nil {
 		return "sticker"
@@ -41,11 +42,13 @@ func messageType(msg *models.Message) string {
 	return "text"
 }
 
+// NewBot initializes and returns a new Bot instance.
 func NewBot(db *gorm.DB, config BotConfig, clock Clock, tgClient TelegramClient) (*Bot, error) {
+	// Retrieve or create Bot entry in the database
 	var botEntry BotModel
 	err := db.Where("identifier = ?", config.ID).First(&botEntry).Error
 	if errors.Is(err, gorm.ErrRecordNotFound) {
-		botEntry = BotModel{Identifier: config.ID, Name: config.ID}
+		botEntry = BotModel{Identifier: config.ID, Name: config.ID} // Customize as needed
 		if err := db.Create(&botEntry).Error; err != nil {
 			return nil, err
 		}
@@ -53,9 +56,11 @@ func NewBot(db *gorm.DB, config BotConfig, clock Clock, tgClient TelegramClient)
 		return nil, err
 	}
 
+	// Ensure the owner exists in the Users table
 	var owner User
 	err = db.Where("telegram_id = ? AND bot_id = ?", config.OwnerTelegramID, botEntry.ID).First(&owner).Error
 	if errors.Is(err, gorm.ErrRecordNotFound) {
+		// Assign the "owner" role
 		var ownerRole Role
 		err := db.Where("name = ?", "owner").First(&ownerRole).Error
 		if err != nil {
@@ -65,12 +70,13 @@ func NewBot(db *gorm.DB, config BotConfig, clock Clock, tgClient TelegramClient)
 		owner = User{
 			BotID:      botEntry.ID,
 			TelegramID: config.OwnerTelegramID,
-			Username:   "",
+			Username:   "", // Initialize as empty; will be updated upon interaction
 			RoleID:     ownerRole.ID,
 			IsOwner:    true,
 		}
 
 		if err := db.Create(&owner).Error; err != nil {
+			// If unique constraint is violated, another owner already exists
 			if strings.Contains(err.Error(), "unique index") {
 				return nil, fmt.Errorf("an owner already exists for this bot")
 			}
@@ -80,6 +86,7 @@ func NewBot(db *gorm.DB, config BotConfig, clock Clock, tgClient TelegramClient)
 		return nil, err
 	}
 
+	// Use the per-bot Anthropic API key
 	anthropicClient := anthropic.NewClient(option.WithAPIKey(config.AnthropicAPIKey))
 
 	b := &Bot{
@@ -90,10 +97,9 @@ func NewBot(db *gorm.DB, config BotConfig, clock Clock, tgClient TelegramClient)
 		config:          config,
 		userLimiters:    make(map[int64]*userLimiter),
 		clock:           clock,
-		botID:           botEntry.ID,
+		botID:           botEntry.ID, // Ensure BotModel has ID field
 		tgBot:           tgClient,
 		albumBuffers:    make(map[string]*pendingAlbum),
-		intakeBuffers:   make(map[int64]*pendingIntake),
 	}
 
 	if tgClient == nil {
@@ -108,6 +114,7 @@ func NewBot(db *gorm.DB, config BotConfig, clock Clock, tgClient TelegramClient)
 	return b, nil
 }
 
+// Start begins the bot's operation.
 func (b *Bot) Start(ctx context.Context) {
 	b.tgBot.Start(ctx)
 }
@@ -117,6 +124,7 @@ func (b *Bot) getOrCreateUser(userID int64, username string, isOwner bool) (User
 	err := b.db.Preload("Role").Where("telegram_id = ? AND bot_id = ?", userID, b.botID).First(&user).Error
 	if err != nil {
 		if errors.Is(err, gorm.ErrRecordNotFound) {
+			// Check if an owner already exists for this bot
 			if isOwner {
 				var existingOwner User
 				err := b.db.Where("bot_id = ? AND is_owner = ?", b.botID, true).First(&existingOwner).Error
@@ -132,7 +140,7 @@ func (b *Bot) getOrCreateUser(userID int64, username string, isOwner bool) (User
 			if isOwner {
 				roleName = "owner"
 			} else {
-				roleName = "user"
+				roleName = "user" // Assign "user" role to non-owner users
 			}
 
 			err := b.db.Where("name = ?", roleName).First(&role).Error
@@ -150,6 +158,7 @@ func (b *Bot) getOrCreateUser(userID int64, username string, isOwner bool) (User
 			}
 
 			if err := b.db.Create(&user).Error; err != nil {
+				// If unique constraint is violated, another owner already exists
 				if strings.Contains(err.Error(), "unique index") {
 					return User{}, fmt.Errorf("an owner already exists for this bot")
 				}
@@ -193,9 +202,10 @@ func (b *Bot) createMessage(chatID, userID int64, username, userRole, text strin
 	return message
 }
 
+// storeMessage stores a message in the database and updates its ID
 func (b *Bot) storeMessage(message *Message) error {
-	message.BotID = b.botID
-	return b.db.Create(message).Error
+	message.BotID = b.botID           // Associate the message with the correct bot
+	return b.db.Create(message).Error // This will update the message with its new ID
 }
 
 func (b *Bot) getOrCreateChatMemory(chatID int64) *ChatMemory {
@@ -209,12 +219,14 @@ func (b *Bot) getOrCreateChatMemory(chatID int64) *ChatMemory {
 
 		chatMemory, exists = b.chatMemories[chatID]
 		if !exists {
+			// Check if this is a new chat by querying the database
 			var count int64
 			b.db.Model(&Message{}).Where("chat_id = ? AND bot_id = ?", chatID, b.botID).Count(&count)
-			isNewChat := count == 0
+			isNewChat := count == 0 // Truly new chat if no messages exist
 
 			var messages []Message
 			if !isNewChat {
+				// Fetch existing messages only if it's not a new chat
 				err := b.db.Where("chat_id = ? AND bot_id = ?", chatID, b.botID).
 					Order("timestamp desc").
 					Limit(b.memorySize * 2).
@@ -222,14 +234,15 @@ func (b *Bot) getOrCreateChatMemory(chatID int64) *ChatMemory {
 
 				if err != nil {
 					ErrorLogger.Printf("Error fetching messages from database: %v", err)
-					messages = []Message{}
+					messages = []Message{} // Initialize an empty slice on error
 				} else {
+					// Reverse from newest-first to chronological order for conversation context.
 					for i, j := 0, len(messages)-1; i < j; i, j = i+1, j-1 {
 						messages[i], messages[j] = messages[j], messages[i]
 					}
 				}
 			} else {
-				messages = []Message{}
+				messages = []Message{} // Ensure messages is initialized for new chats
 			}
 
 			chatMemory = &ChatMemory{
@@ -244,6 +257,11 @@ func (b *Bot) getOrCreateChatMemory(chatID int64) *ChatMemory {
 	return chatMemory
 }
 
+// stripDeadFileIDFromMemory removes a single file_id from every message in the
+// chat's in-memory ChatMemory. Called by the runtime self-heal in
+// getAnthropicResponse after Anthropic 404s for that file_id, so the immediate
+// retry (and any subsequent turn replay) won't reference it. The corresponding
+// DB rows are stamped separately via markFilesPendingCleanup.
 func (b *Bot) stripDeadFileIDFromMemory(chatID int64, deadFileID string) {
 	b.chatMemoriesMu.Lock()
 	defer b.chatMemoriesMu.Unlock()
@@ -265,12 +283,15 @@ func (b *Bot) stripDeadFileIDFromMemory(chatID int64, deadFileID string) {
 	}
 }
 
+// addMessageToChatMemory adds a new message to the chat memory, ensuring the memory size is maintained.
 func (b *Bot) addMessageToChatMemory(chatMemory *ChatMemory, message Message) {
 	b.chatMemoriesMu.Lock()
 	defer b.chatMemoriesMu.Unlock()
 
+	// Add the new message
 	chatMemory.Messages = append(chatMemory.Messages, message)
 
+	// Maintain the memory size
 	if len(chatMemory.Messages) > chatMemory.Size {
 		chatMemory.Messages = chatMemory.Messages[len(chatMemory.Messages)-chatMemory.Size:]
 	}
@@ -280,15 +301,22 @@ func (b *Bot) prepareContextMessages(chatMemory *ChatMemory) []anthropic.BetaMes
 	b.chatMemoriesMu.RLock()
 	defer b.chatMemoriesMu.RUnlock()
 
+	// Debug logging
 	InfoLogger.Printf("Chat memory contains %d messages", len(chatMemory.Messages))
 	for i, msg := range chatMemory.Messages {
 		InfoLogger.Printf("Message %d: IsUser=%v, Text=%q Images=%d", i, msg.IsUser, msg.Text, len(msg.ImageFileIDs))
 	}
 
+	// Note: consecutive messages with the same role are permitted.
+	// The Anthropic API automatically merges them into a single turn rather than
+	// returning an error. This can happen after a /clear (which only deletes user
+	// messages, leaving assistant messages in the DB) followed by a restart.
+	// See: https://platform.claude.com/docs/en/api/messages
 	var contextMessages []anthropic.BetaMessageParam
 	for _, msg := range chatMemory.Messages {
 		blocks := contentBlocksForMessage(msg)
 		if len(blocks) == 0 {
+			// Skip turns that carry neither text nor images.
 			continue
 		}
 		var param anthropic.BetaMessageParam
@@ -302,39 +330,14 @@ func (b *Bot) prepareContextMessages(chatMemory *ChatMemory) []anthropic.BetaMes
 		}
 		contextMessages = append(contextMessages, param)
 	}
-
-	if b.config.CacheHistoryEnabled() {
-		markTrailingCacheBreakpoint(contextMessages)
-	}
 	return contextMessages
 }
 
-// markTrailingCacheBreakpoint puts a cache_control breakpoint on the final
-// content block of the conversation, so the next turn reads the whole prefix
-// from cache instead of reprocessing it. The system prompt keeps its own
-// breakpoint; tools and system render ahead of messages, so the two compose.
-//
-// Caveat worth knowing when reading [usage] lines: chat memory is a sliding
-// window. Once it is full, each new turn evicts the oldest message, which
-// changes the prefix and forces a miss. Until then, and for any chat shorter
-// than the window, this converts a full-price reread into a cache read.
-func markTrailingCacheBreakpoint(messages []anthropic.BetaMessageParam) {
-	if len(messages) == 0 {
-		return
-	}
-	blocks := messages[len(messages)-1].Content
-	if len(blocks) == 0 {
-		return
-	}
-
-	switch last := &blocks[len(blocks)-1]; {
-	case last.OfText != nil:
-		last.OfText.CacheControl = anthropic.NewBetaCacheControlEphemeralParam()
-	case last.OfImage != nil:
-		last.OfImage.CacheControl = anthropic.NewBetaCacheControlEphemeralParam()
-	}
-}
-
+// contentBlocksForMessage assembles the Anthropic content blocks representing
+// one stored Message. Image blocks are emitted before the text block (Anthropic
+// docs: "Claude works best when images come before text"). Multi-image user
+// turns prepend each image with an "Image N:" label, as the docs explicitly
+// recommend for multi-image prompts. Assistant turns carry text only.
 func contentBlocksForMessage(msg Message) []anthropic.BetaContentBlockParamUnion {
 	var blocks []anthropic.BetaContentBlockParamUnion
 	if msg.IsUser && len(msg.ImageFileIDs) > 0 {
@@ -352,6 +355,13 @@ func contentBlocksForMessage(msg Message) []anthropic.BetaContentBlockParamUnion
 	return blocks
 }
 
+func (b *Bot) isNewChat(chatID int64) bool {
+	var count int64
+	b.db.Model(&Message{}).Where("chat_id = ? AND bot_id = ?", chatID, b.botID).Count(&count)
+	return count == 0 // Only consider a chat new if it has 0 messages
+}
+
+// roleHasScope reports whether role (with pre-loaded Scopes) contains the given scope name.
 func roleHasScope(role Role, scope string) bool {
 	for _, s := range role.Scopes {
 		if s.Name == scope {
@@ -361,6 +371,8 @@ func roleHasScope(role Role, scope string) bool {
 	return false
 }
 
+// hasScope reports whether the user identified by userID holds the given scope for this bot.
+// Owners implicitly hold all scopes regardless of their assigned role.
 func (b *Bot) hasScope(userID int64, scope string) bool {
 	var user User
 	if err := b.db.Preload("Role.Scopes").
@@ -374,17 +386,22 @@ func (b *Bot) hasScope(userID int64, scope string) bool {
 	return roleHasScope(user.Role, scope)
 }
 
+// publicBotCommands are shown to every user in the Telegram command palette.
 var publicBotCommands = []models.BotCommand{
 	{Command: "stats", Description: "Get bot statistics. Usage: /stats or /stats user [user_id]"},
 	{Command: "whoami", Description: "Get your user information"},
 	{Command: "clear", Description: "Clear chat history (soft delete). Admins: /clear [user_id]"},
 }
 
+// adminBotCommands are shown only in admin/owner chats via BotCommandScopeChatMember.
 var adminBotCommands = []models.BotCommand{
 	{Command: "clear_hard", Description: "Clear chat history (permanently delete). Admins: /clear_hard [user_id]"},
 	{Command: "set_model", Description: "Switch the AI model (admin/owner only). Usage: /set_model <model-id>"},
 }
 
+// registerAdminCommandsForUser scopes the full command palette to a specific user's private chat.
+// In Telegram private chats, chat_id == user_id, so both fields carry the same value.
+// Errors are logged but treated as non-fatal: the user retains access via permission checks.
 func (b *Bot) registerAdminCommandsForUser(ctx context.Context, telegramID int64) {
 	allCommands := make([]models.BotCommand, 0, len(publicBotCommands)+len(adminBotCommands))
 	allCommands = append(allCommands, publicBotCommands...)
@@ -398,13 +415,16 @@ func (b *Bot) registerAdminCommandsForUser(ctx context.Context, telegramID int64
 	}
 }
 
+// setElevatedCommands registers the full command palette (public + admin) for every user
+// whose role carries the model:set scope, or who is the bot owner. Called once at startup
+// and uses the freshly created tgBot directly (b.tgBot is not yet assigned at that point).
 func setElevatedCommands(tgBot TelegramClient, users []User) {
 	allCommands := make([]models.BotCommand, 0, len(publicBotCommands)+len(adminBotCommands))
 	allCommands = append(allCommands, publicBotCommands...)
 	allCommands = append(allCommands, adminBotCommands...)
 	for _, u := range users {
 		if u.TelegramID == 0 {
-			continue
+			continue // skip placeholder users not yet seen in a chat
 		}
 		if !u.IsOwner && !roleHasScope(u.Role, ScopeModelSet) {
 			continue
@@ -429,6 +449,7 @@ func initTelegramBot(token string, b *Bot) (TelegramClient, error) {
 		return nil, err
 	}
 
+	// Register public commands for all users.
 	_, err = tgBot.SetMyCommands(context.Background(), &bot.SetMyCommandsParams{
 		Commands: publicBotCommands,
 		Scope:    &models.BotCommandScopeDefault{},
@@ -438,6 +459,10 @@ func initTelegramBot(token string, b *Bot) (TelegramClient, error) {
 		return nil, err
 	}
 
+	// Register full command palette (public + admin) scoped to each known elevated user.
+	// BotCommandScopeChatMember targets the user's private DM with the bot (chat_id == user_id).
+	// Elevation is determined by scope rather than role name, so renaming roles requires no code change.
+	// This is best-effort: failures are logged but do not prevent the bot from starting.
 	var allUsers []User
 	if err := b.db.Preload("Role.Scopes").Where("bot_id = ?", b.botID).Find(&allUsers).Error; err != nil {
 		ErrorLogger.Printf("Warning: could not query users for command scoping: %v", err)
@@ -449,12 +474,14 @@ func initTelegramBot(token string, b *Bot) (TelegramClient, error) {
 }
 
 func (b *Bot) sendResponse(ctx context.Context, chatID int64, text string, businessConnectionID string) error {
+	// Pass the outgoing message through the centralized screen for storage and chat memory update
 	_, err := b.screenOutgoingMessage(chatID, text)
 	if err != nil {
 		ErrorLogger.Printf("Error storing assistant message: %v", err)
 		return err
 	}
 
+	// Prepare message parameters
 	params := &bot.SendMessageParams{
 		ChatID: chatID,
 		Text:   text,
@@ -464,6 +491,7 @@ func (b *Bot) sendResponse(ctx context.Context, chatID int64, text string, busin
 		params.BusinessConnectionID = businessConnectionID
 	}
 
+	// Send the message via Telegram client
 	_, err = b.tgBot.SendMessage(ctx, params)
 	if err != nil {
 		ErrorLogger.Printf("[%s] Error sending message to chat %d with BusinessConnectionID %s: %v",
@@ -473,6 +501,11 @@ func (b *Bot) sendResponse(ctx context.Context, chatID int64, text string, busin
 	return nil
 }
 
+// sendOneSegment delivers a single Telegram message without touching storage
+// or chat memory. Used by the streaming response path: each completed text
+// block fires this helper as it arrives, and the full turn is recorded once
+// at end-of-stream via screenOutgoingMessage. Keeps the 1-reply-per-prompt
+// storage invariant while letting the user see segments with natural rhythm.
 func (b *Bot) sendOneSegment(ctx context.Context, chatID int64, text, businessConnectionID string) error {
 	params := &bot.SendMessageParams{
 		ChatID: chatID,
@@ -489,7 +522,9 @@ func (b *Bot) sendOneSegment(ctx context.Context, chatID int64, text, businessCo
 	return nil
 }
 
+// sendStats sends the bot statistics to the specified chat.
 func (b *Bot) sendStats(ctx context.Context, chatID int64, userID int64, targetUserID int64, businessConnectionID string) {
+	// If targetUserID is 0, show global stats
 	if targetUserID == 0 {
 		totalUsers, totalMessages, err := b.getStats()
 		if err != nil {
@@ -500,6 +535,7 @@ func (b *Bot) sendStats(ctx context.Context, chatID int64, userID int64, targetU
 			return
 		}
 
+		// Do NOT manually escape hyphens here
 		statsMessage := fmt.Sprintf(
 			"📊 Bot Statistics:\n\n"+
 				"- Total Users: %d\n"+
@@ -538,12 +574,15 @@ func (b *Bot) sendStats(ctx context.Context, chatID int64, userID int64, targetU
 			}
 		}
 
+		// Send the response through the centralized screen
 		if err := b.sendResponse(ctx, chatID, statsMessage, businessConnectionID); err != nil {
 			ErrorLogger.Printf("Error sending stats message: %v", err)
 		}
 		return
 	}
 
+	// If targetUserID is not 0, show user-specific stats
+	// Check permissions if the user is trying to view someone else's stats
 	if targetUserID != userID {
 		if !b.hasScope(userID, ScopeStatsViewAny) {
 			InfoLogger.Printf("User %d attempted to view stats for user %d without permission", userID, targetUserID)
@@ -554,6 +593,7 @@ func (b *Bot) sendStats(ctx context.Context, chatID int64, userID int64, targetU
 		}
 	}
 
+	// Get user stats
 	username, messagesIn, messagesOut, totalMessages, err := b.getUserStats(targetUserID)
 	if err != nil {
 		ErrorLogger.Printf("Error fetching user stats: %v\n", err)
@@ -563,6 +603,7 @@ func (b *Bot) sendStats(ctx context.Context, chatID int64, userID int64, targetU
 		return
 	}
 
+	// Build the user stats message
 	userInfo := fmt.Sprintf("@%s (ID: %d)", username, targetUserID)
 	if username == "" {
 		userInfo = fmt.Sprintf("User ID: %d", targetUserID)
@@ -584,6 +625,7 @@ func (b *Bot) sendStats(ctx context.Context, chatID int64, userID int64, targetU
 	}
 }
 
+// getStats retrieves the total number of users and messages from the database.
 func (b *Bot) getStats() (int64, int64, error) {
 	var totalUsers int64
 	if err := b.db.Model(&User{}).Where("bot_id = ?", b.botID).Count(&totalUsers).Error; err != nil {
@@ -598,30 +640,36 @@ func (b *Bot) getStats() (int64, int64, error) {
 	return totalUsers, totalMessages, nil
 }
 
+// getUserStats retrieves statistics for a specific user
 func (b *Bot) getUserStats(userID int64) (string, int64, int64, int64, error) {
+	// Get user information from database
 	var user User
 	err := b.db.Where("telegram_id = ? AND bot_id = ?", userID, b.botID).First(&user).Error
 	if err != nil {
 		return "", 0, 0, 0, fmt.Errorf("user not found: %w", err)
 	}
 
+	// Count messages sent by the user (IN)
 	var messagesIn int64
 	if err := b.db.Model(&Message{}).Where("user_id = ? AND bot_id = ? AND is_user = ?",
 		userID, b.botID, true).Count(&messagesIn).Error; err != nil {
 		return "", 0, 0, 0, err
 	}
 
+	// Count responses to the user (OUT)
 	var messagesOut int64
 	if err := b.db.Model(&Message{}).Where("chat_id IN (SELECT DISTINCT chat_id FROM messages WHERE user_id = ? AND bot_id = ? AND deleted_at IS NULL) AND bot_id = ? AND is_user = ?",
 		userID, b.botID, b.botID, false).Count(&messagesOut).Error; err != nil {
 		return "", 0, 0, 0, err
 	}
 
+	// Total messages is the sum
 	totalMessages := messagesIn + messagesOut
 
 	return user.Username, messagesIn, messagesOut, totalMessages, nil
 }
 
+// isOnlyEmojis checks if the string consists solely of emojis.
 func isOnlyEmojis(s string) bool {
 	for _, r := range s {
 		if !isEmoji(r) {
@@ -631,12 +679,14 @@ func isOnlyEmojis(s string) bool {
 	return true
 }
 
+// isEmoji determines if a rune is an emoji.
+// This is a simplistic check and can be expanded based on requirements.
 func isEmoji(r rune) bool {
-	return (r >= 0x1F600 && r <= 0x1F64F) ||
-		(r >= 0x1F300 && r <= 0x1F5FF) ||
-		(r >= 0x1F680 && r <= 0x1F6FF) ||
-		(r >= 0x2600 && r <= 0x26FF) ||
-		(r >= 0x2700 && r <= 0x27BF)
+	return (r >= 0x1F600 && r <= 0x1F64F) || // Emoticons
+		(r >= 0x1F300 && r <= 0x1F5FF) || // Misc Symbols and Pictographs
+		(r >= 0x1F680 && r <= 0x1F6FF) || // Transport and Map
+		(r >= 0x2600 && r <= 0x26FF) || // Misc symbols
+		(r >= 0x2700 && r <= 0x27BF) // Dingbats
 }
 
 func (b *Bot) sendWhoAmI(ctx context.Context, chatID int64, userID int64, username string, businessConnectionID string) {
@@ -666,11 +716,13 @@ func (b *Bot) sendWhoAmI(ctx context.Context, chatID int64, userID int64, userna
 		role.Name,
 	)
 
+	// Send the response through the centralized screen
 	if err := b.sendResponse(ctx, chatID, whoAmIMessage, businessConnectionID); err != nil {
 		ErrorLogger.Printf("Error sending /whoami message: %v", err)
 	}
 }
 
+// screenIncomingMessage centralizes all incoming message processing: storing messages and updating chat memory.
 func (b *Bot) screenIncomingMessage(message *models.Message) (Message, error) {
 	if b.config.DebugScreening {
 		start := time.Now()
@@ -688,6 +740,7 @@ func (b *Bot) screenIncomingMessage(message *models.Message) (Message, error) {
 
 	userRole := "user"
 
+	// Determine message text based on message type
 	messageText := message.Text
 	if message.Sticker != nil {
 		if message.Sticker.Emoji != "" {
@@ -702,25 +755,31 @@ func (b *Bot) screenIncomingMessage(message *models.Message) (Message, error) {
 
 	userMessage := b.createMessage(message.Chat.ID, message.From.ID, message.From.Username, userRole, messageText, true)
 
+	// Handle sticker-specific details if present
 	if message.Sticker != nil {
 		userMessage.StickerFileID = message.Sticker.FileID
-		userMessage.StickerEmoji = message.Sticker.Emoji
+		userMessage.StickerEmoji = message.Sticker.Emoji // Store the sticker emoji
 		if message.Sticker.Thumbnail != nil {
 			userMessage.StickerPNGFile = message.Sticker.Thumbnail.FileID
 		}
 	}
 
+	// Get the chat memory before storing the message
 	chatMemory := b.getOrCreateChatMemory(message.Chat.ID)
 
+	// Store the message and get its ID
 	if err := b.storeMessage(&userMessage); err != nil {
 		return Message{}, err
 	}
 
+	// Add the message to the chat memory
 	b.addMessageToChatMemory(chatMemory, userMessage)
 
 	return userMessage, nil
 }
 
+// screenOutgoingMessage handles storing of outgoing messages and updating chat memory.
+// It also marks the most recent unanswered user message as answered.
 func (b *Bot) screenOutgoingMessage(chatID int64, response string) (Message, error) {
 	if b.config.DebugScreening {
 		start := time.Now()
@@ -735,25 +794,27 @@ func (b *Bot) screenOutgoingMessage(chatID int64, response string) (Message, err
 		}()
 	}
 
+	// Create and store the assistant message
 	assistantMessage := b.createMessage(chatID, 0, "", "assistant", response, false)
 	if err := b.storeMessage(&assistantMessage); err != nil {
 		return Message{}, err
 	}
 
-	// Mark every outstanding user message in the chat, not just the newest one.
-	// A coalesced turn answers the whole batch, so a single-row update would
-	// leave the earlier messages permanently unanswered. This also drops an
-	// UPDATE ... ORDER BY ... LIMIT, which stock SQLite builds do not support.
+	// Find and mark the most recent unanswered user message as answered
 	now := time.Now()
 	err := b.db.Model(&Message{}).
 		Where("chat_id = ? AND bot_id = ? AND is_user = ? AND answered_on IS NULL",
 			chatID, b.botID, true).
+		Order("timestamp DESC").
+		Limit(1).
 		Update("answered_on", now).Error
 
 	if err != nil {
-		ErrorLogger.Printf("Error marking user messages as answered: %v", err)
+		ErrorLogger.Printf("Error marking user message as answered: %v", err)
+		// Continue even if there's an error updating the user message
 	}
 
+	// Update chat memory with the message that now has an ID
 	chatMemory := b.getOrCreateChatMemory(chatID)
 	b.addMessageToChatMemory(chatMemory, assistantMessage)
 
@@ -761,26 +822,31 @@ func (b *Bot) screenOutgoingMessage(chatID int64, response string) (Message, err
 }
 
 func (b *Bot) promoteUserToAdmin(promoterID, userToPromoteID int64) error {
+	// Check if the promoter has the user:promote scope
 	if !b.hasScope(promoterID, ScopeUserPromote) {
 		return errors.New("only admins or owners can promote users to admin")
 	}
 
+	// Get the user to promote
 	userToPromote, err := b.getOrCreateUser(userToPromoteID, "", false)
 	if err != nil {
 		return err
 	}
 
+	// Get the admin role
 	var adminRole Role
 	if err := b.db.Where("name = ?", "admin").First(&adminRole).Error; err != nil {
 		return err
 	}
 
+	// Update the user's role
 	userToPromote.RoleID = adminRole.ID
 	userToPromote.Role = adminRole
 	if err := b.db.Save(&userToPromote).Error; err != nil {
 		return err
 	}
 
+	// Surface admin commands in the newly promoted user's private chat.
 	b.registerAdminCommandsForUser(context.Background(), userToPromoteID)
 	return nil
 }

bot_test.go

@@ -49,6 +49,7 @@ func TestContentBlocksForMessage(t *testing.T) {
 			Text:         "compare these",
 			ImageFileIDs: []string{"file_a", "file_b", "file_c"},
 		})
+		// Expected layout: text "Image 1:", image a, text "Image 2:", image b, text "Image 3:", image c, text "compare these"
 		assert.Len(t, blocks, 7)
 		assert.Equal(t, "Image 1:", blocks[0].OfText.Text)
 		assert.Equal(t, "file_a", blocks[1].OfImage.Source.OfFile.FileID)
@@ -60,6 +61,8 @@ func TestContentBlocksForMessage(t *testing.T) {
 	})
 
 	t.Run("assistant message with images-set is text-only (defensive)", func(t *testing.T) {
+		// Assistant turns shouldn't carry images, but if they ever do we treat
+		// them as text-only — the model returns text, not images.
 		blocks := contentBlocksForMessage(Message{
 			IsUser:       false,
 			Text:         "I see your screenshot",
@@ -85,6 +88,7 @@ func TestStripDeadFileIDFromMemory(t *testing.T) {
 	b, _ := setupBotForTest(t, 100)
 	chatID := int64(42)
 
+	// Seed in-memory chat memory with three messages.
 	cm := b.getOrCreateChatMemory(chatID)
 	cm.Messages = []Message{
 		{IsUser: true, Text: "first", ImageFileIDs: []string{"file_a", "file_b"}},
@@ -101,5 +105,7 @@ func TestStripDeadFileIDFromMemory(t *testing.T) {
 
 func TestStripDeadFileIDFromMemory_UnknownChatIsNoop(t *testing.T) {
 	b, _ := setupBotForTest(t, 100)
+	// Calling on a chat that was never opened should not panic and should be a no-op.
 	b.stripDeadFileIDFromMemory(99999, "file_anything")
+	// Nothing to assert beyond not crashing.
 }

clock.go

@@ -1,25 +1,32 @@
+// clock.go
 package main
 
 import "time"
 
+// Clock is an interface to abstract time-related functions.
 type Clock interface {
 	Now() time.Time
 }
 
+// RealClock implements Clock using the actual time.
 type RealClock struct{}
 
+// Now returns the current local time.
 func (RealClock) Now() time.Time {
 	return time.Now()
 }
 
+// MockClock implements Clock for testing purposes.
 type MockClock struct {
 	currentTime time.Time
 }
 
+// Now returns the mocked current time.
 func (mc *MockClock) Now() time.Time {
 	return mc.currentTime
 }
 
+// Advance moves the current time forward by the specified duration.
 func (mc *MockClock) Advance(d time.Duration) {
 	mc.currentTime = mc.currentTime.Add(d)
 }

config.go

@@ -6,9 +6,11 @@ import (
 	"os"
 	"path/filepath"
 	"strings"
-	"time"
 )
 
+// MCPServer configures a remote Model Context Protocol server that the Anthropic
+// API will connect to on behalf of this bot. AllowedTools, when non-empty, limits
+// which server-exposed tools the model may invoke.
 type MCPServer struct {
 	Name               string   `json:"name"`
 	URL                string   `json:"url"`
@@ -16,44 +18,6 @@ type MCPServer struct {
 	AllowedTools       []string `json:"allowed_tools,omitempty"`
 }
 
-type WebSearchConfig struct {
-	AllowedDomains      []string `json:"allowed_domains,omitempty"`
-	BlockedDomains      []string `json:"blocked_domains,omitempty"`
-	FetchAllowedDomains []string `json:"fetch_allowed_domains,omitempty"`
-	MaxUses             int      `json:"max_uses,omitempty"`
-	Fetch               bool     `json:"fetch,omitempty"`
-	MaxContentTokens    int      `json:"max_content_tokens,omitempty"`
-}
-
-const (
-	ThinkingModeAdaptive      = "adaptive"
-	ThinkingModeDisabled      = "disabled"
-	ThinkingDisplaySummarized = "summarized"
-	ThinkingDisplayOmitted    = "omitted"
-)
-
-// maxDebounceMs bounds debounce_ms. Beyond this the bot reads as unresponsive
-// rather than deliberate, and the coalesced turn drifts far enough from the
-// user's last message that the reply feels stale.
-const maxDebounceMs = 30000
-
-// DebounceWindow is the quiet period an intake buffer waits before dispatching a
-// coalesced turn. Zero disables debouncing entirely (the default), matching the
-// opt-in behavior of comparable gateways.
-func (c *BotConfig) DebounceWindow() time.Duration {
-	if c.DebounceMs <= 0 {
-		return 0
-	}
-	return time.Duration(c.DebounceMs) * time.Millisecond
-}
-
-// CacheHistoryEnabled reports whether a cache_control breakpoint should be placed
-// on the trailing conversation block in addition to the system prompt. Defaults
-// to true; set "cache_history": false to opt out.
-func (c *BotConfig) CacheHistoryEnabled() bool {
-	return c.CacheHistory == nil || *c.CacheHistory
-}
-
 type BotConfig struct {
 	ID                string            `json:"id"`
 	TelegramToken     string            `json:"telegram_token"`
@@ -62,12 +26,7 @@ type BotConfig struct {
 	MessagePerDay     int               `json:"messages_per_day"`
 	TempBanDuration   string            `json:"temp_ban_duration"`
 	Model             string            `json:"model"`
-	Temperature       *float32          `json:"temperature,omitempty"`
-	MaxTokens         int               `json:"max_tokens,omitempty"`
-	Thinking          string            `json:"thinking,omitempty"`
-	ThinkingDisplay   string            `json:"thinking_display,omitempty"`
-	DebounceMs        int               `json:"debounce_ms,omitempty"`
-	CacheHistory      *bool             `json:"cache_history,omitempty"`
+	Temperature       *float32          `json:"temperature,omitempty"` // Controls creativity vs determinism (0.0-1.0)
 	SystemPrompts     map[string]string `json:"system_prompts"`
 	Active            bool              `json:"active"`
 	OwnerTelegramID   int64             `json:"owner_telegram_id"`
@@ -75,16 +34,18 @@ type BotConfig struct {
 	ElevenLabsAPIKey  string            `json:"elevenlabs_api_key"`
 	ElevenLabsVoiceID string            `json:"elevenlabs_voice_id"`
 	ElevenLabsModel   string            `json:"elevenlabs_model"`
-	DebugScreening    bool              `json:"debug_screening"`
+	DebugScreening    bool              `json:"debug_screening"` // Enable detailed screening logs
 	MCPServers        []MCPServer       `json:"mcp_servers,omitempty"`
-	WebSearch         *WebSearchConfig  `json:"web_search,omitempty"`
-	ConfigFilePath    string            `json:"-"`
+	ConfigFilePath    string            `json:"-"` // Set at load time; not serialized
 }
 
+// validateConfigPath ensures the file path is within the allowed directory
 func validateConfigPath(configDir, filename string) (string, error) {
+	// Clean the paths to remove any . or .. components
 	configDir = filepath.Clean(configDir)
 	filename = filepath.Clean(filename)
 
+	// Get absolute paths
 	absConfigDir, err := filepath.Abs(configDir)
 	if err != nil {
 		return "", fmt.Errorf("failed to get absolute path for config directory: %w", err)
@@ -96,11 +57,13 @@ func validateConfigPath(configDir, filename string) (string, error) {
 		return "", fmt.Errorf("failed to get absolute path for config file: %w", err)
 	}
 
+	// Use filepath.Rel to check if the path is within the config directory
 	rel, err := filepath.Rel(absConfigDir, absPath)
 	if err != nil || strings.HasPrefix(rel, "..") || strings.Contains(rel, "..") {
 		return "", fmt.Errorf("invalid config path: file must be within the config directory")
 	}
 
+	// Verify file extension
 	if filepath.Ext(absPath) != ".json" {
 		return "", fmt.Errorf("invalid file extension: must be .json")
 	}
@@ -142,8 +105,6 @@ func loadAllConfigs(dir string) ([]BotConfig, error) {
 				continue
 			}
 
-			logConfigAdvisories(&config)
-
 			config.ConfigFilePath = validPath
 			configs = append(configs, config)
 		}
@@ -156,41 +117,6 @@ func loadAllConfigs(dir string) ([]BotConfig, error) {
 	return configs, nil
 }
 
-// logConfigAdvisories emits non-fatal boot-time notes about settings that are
-// valid but likely to surprise: silently ineffective, or costlier than intended.
-func logConfigAdvisories(config *BotConfig) {
-	if config.Thinking == ThinkingModeAdaptive && config.MaxTokens > 0 && config.MaxTokens < 4000 {
-		InfoLogger.Printf("[%s] thinking=adaptive with max_tokens=%d: thinking tokens count toward max_tokens; consider >= 4000",
-			config.ID, config.MaxTokens)
-	}
-
-	if config.DebounceMs > 0 {
-		InfoLogger.Printf("[%s] intake debounce enabled: coalescing rapid text messages over a %dms quiet window",
-			config.ID, config.DebounceMs)
-	} else {
-		InfoLogger.Printf("[%s] intake debounce disabled: every message dispatches its own turn (set debounce_ms to coalesce rapid follow-ups)",
-			config.ID)
-	}
-
-	if ws := config.WebSearch; ws != nil && len(ws.AllowedDomains) == 0 && len(ws.BlockedDomains) == 0 {
-		InfoLogger.Printf("[%s] web_search enabled with no allowed_domains/blocked_domains: the model may search the open web",
-			config.ID)
-	}
-
-	if ws := config.WebSearch; ws != nil && len(ws.FetchAllowedDomains) > 0 {
-		if !ws.Fetch {
-			InfoLogger.Printf("[%s] web_search.fetch_allowed_domains is set but fetch is disabled: it has no effect",
-				config.ID)
-		}
-		for _, d := range ws.FetchAllowedDomains {
-			if strings.Contains(d, "/") {
-				InfoLogger.Printf("[%s] web_search.fetch_allowed_domains entry %q includes a path: web_fetch matches host-only, so the whole host is fetchable",
-					config.ID, d)
-			}
-		}
-	}
-}
-
 func validateConfig(config *BotConfig, ids, tokens map[string]bool) error {
 	if config.ID == "" {
 		return fmt.Errorf("missing 'id' field")
@@ -212,49 +138,6 @@ func validateConfig(config *BotConfig, ids, tokens map[string]bool) error {
 		return fmt.Errorf("missing 'model' field")
 	}
 
-	switch config.Thinking {
-	case "", ThinkingModeAdaptive, ThinkingModeDisabled:
-	default:
-		return fmt.Errorf("invalid 'thinking' value %q: must be %q or %q (or omitted)",
-			config.Thinking, ThinkingModeAdaptive, ThinkingModeDisabled)
-	}
-
-	switch config.ThinkingDisplay {
-	case "":
-	case ThinkingDisplaySummarized, ThinkingDisplayOmitted:
-		if config.Thinking != ThinkingModeAdaptive {
-			return fmt.Errorf("'thinking_display' requires 'thinking': %q (the API rejects display with thinking disabled)",
-				ThinkingModeAdaptive)
-		}
-	default:
-		return fmt.Errorf("invalid 'thinking_display' value %q: must be %q or %q (or omitted)",
-			config.ThinkingDisplay, ThinkingDisplaySummarized, ThinkingDisplayOmitted)
-	}
-
-	if config.MaxTokens < 0 {
-		return fmt.Errorf("'max_tokens' must be greater than 0 when set")
-	}
-
-	if config.DebounceMs < 0 {
-		return fmt.Errorf("'debounce_ms' must be greater than 0 when set")
-	}
-	if config.DebounceMs > maxDebounceMs {
-		return fmt.Errorf("'debounce_ms' of %d exceeds the maximum of %d (Telegram drops long-idle updates and users read silence as failure)",
-			config.DebounceMs, maxDebounceMs)
-	}
-
-	if ws := config.WebSearch; ws != nil {
-		if len(ws.AllowedDomains) > 0 && len(ws.BlockedDomains) > 0 {
-			return fmt.Errorf("'web_search' cannot set both allowed_domains and blocked_domains (the API rejects that)")
-		}
-		if ws.MaxUses < 0 {
-			return fmt.Errorf("'web_search.max_uses' must be greater than 0 when set")
-		}
-		if ws.MaxContentTokens < 0 {
-			return fmt.Errorf("'web_search.max_content_tokens' must be greater than 0 when set")
-		}
-	}
-
 	if config.MessagePerHour <= 0 {
 		return fmt.Errorf("'messages_per_hour' must be greater than 0")
 	}
@@ -268,6 +151,7 @@ func validateConfig(config *BotConfig, ids, tokens map[string]bool) error {
 
 func loadConfig(filename string) (BotConfig, error) {
 	var config BotConfig
+	// Use filepath.Clean before opening the file
 	file, err := os.OpenFile(filepath.Clean(filename), os.O_RDONLY, 0)
 	if err != nil {
 		return config, fmt.Errorf("failed to open config file %s: %w", filename, err)
@@ -286,12 +170,15 @@ func loadConfig(filename string) (BotConfig, error) {
 	return config, nil
 }
 
+// Reload reloads the BotConfig from the specified filename within the given config directory
 func (c *BotConfig) Reload(configDir, filename string) error {
+	// Validate the config path
 	validPath, err := validateConfigPath(configDir, filename)
 	if err != nil {
 		return fmt.Errorf("invalid config path: %w", err)
 	}
 
+	// Use filepath.Clean before opening the file
 	cleanPath := filepath.Clean(validPath)
 	file, err := os.OpenFile(cleanPath, os.O_RDONLY, 0)
 	if err != nil {
@@ -311,6 +198,8 @@ func (c *BotConfig) Reload(configDir, filename string) error {
 	return nil
 }
 
+// PersistModel updates the model field in memory and writes it back to the config file on disk.
+// Only the "model" key is changed; all other fields are preserved verbatim.
 func (c *BotConfig) PersistModel(newModel string) error {
 	if c.ConfigFilePath == "" {
 		return fmt.Errorf("config file path not set; cannot persist model")

config/default.json

@@ -13,11 +13,12 @@
     "temp_ban_duration": "24h",
     "model": "claude-haiku-4-5",
     "temperature": 0.7,
-    "max_tokens": 1000,
-    "debounce_ms": 2500,
     "debug_screening": false,
     "system_prompts": {
-        "custom_instructions": "You are Atom, a helpful assistant texting through a limited Telegram interface with a 15-word maximum. Write like texting a friend - use shorthand, skip grammar, use slang/abbreviations. The system cuts off anything longer than 15 words.\n\n- Address the user by their first name, and reply in their preferred language (both are in the conversation context).\n- Use time-appropriate greetings based on the user's local time of day.\n- If a user asks about buying apples, inform them that we don't sell apples.\n- When asked for a joke, tell a clean, family-friendly joke about programming or technology.\n- If someone inquires about our services, explain that we offer AI-powered chatbot solutions.\n- For any questions about pricing, direct users to contact our sales team at [email protected].\n- If asked about your capabilities, be honest about what you can and cannot do.\nAlways maintain a friendly and professional tone.",
-        "respond_with_emojis": "The user's message contains only emoji. Reply using only emoji."
+        "default": "You are a helpful assistant.",
+        "custom_instructions": "You are texting through a limited Telegram interface with 15-word maximum. Write like texting a friend - use shorthand, skip grammar, use slang/abbreviations. System cuts off anything longer than 15 words.\n\n- Your name is Atom.\n- The user you're talking to has username '{username}' and display name '{firstname} {lastname}'.\n- User's language preference: '{language}'. Prefer replying in this language when talking to '{username}'.\n- User is a {premium_status}\n- It's currently {time_context} in your timezone. Use appropriate time-based greetings and address the user by name.\n- If a user asks about buying apples, inform them that we don't sell apples.\n- When asked for a joke, tell a clean, family-friendly joke about programming or technology.\n- If someone inquires about our services, explain that we offer AI-powered chatbot solutions.\n- For any questions about pricing, direct users to contact our sales team at [email protected].\n- If asked about your capabilities, be honest about what you can and cannot do.\nAlways maintain a friendly and professional tone.",
+        "continue_conversation": "Continuing our conversation. Remember previous context if relevant.",
+        "avoid_sensitive": "Avoid discussing sensitive topics or providing harmful information.",
+        "respond_with_emojis": "Since the user sent only emojis, respond using emojis only."
     }
 }

config_test.go

@@ -2,18 +2,19 @@ package main
 
 import (
 	"encoding/json"
-	"fmt"
 	"os"
 	"path/filepath"
 	"strings"
 	"testing"
 )
 
+// Set up loggers
 func TestMain(m *testing.M) {
 	initLoggers()
 	os.Exit(m.Run())
 }
 
+// TestBotConfig_UnmarshalJSON tests the custom unmarshalling of BotConfig
 func TestBotConfig_UnmarshalJSON(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
 	jsonData := `{
 		"id": "bot123",
@@ -45,8 +46,10 @@ func TestBotConfig_UnmarshalJSON(t *testing.T) { //NOSONAR go:S100 -- underscore
 		t.Errorf("Expected ID %s, got %s", expectedID, config.ID)
 	}
 
+	// Add more field checks as necessary
 }
 
+// TestValidateConfigPath tests the validateConfigPath function
 func TestValidateConfigPath(t *testing.T) {
 	execDir, err := os.Getwd()
 	if err != nil {
@@ -91,6 +94,7 @@ func TestValidateConfigPath(t *testing.T) {
 		},
 	}
 
+	// Create a subdirectory for testing
 	subDir := filepath.Join(execDir, "subdir")
 	if err := os.MkdirAll(subDir, 0755); err != nil {
 		t.Fatalf("Failed to create subdir: %v", err)
@@ -116,7 +120,9 @@ func TestValidateConfigPath(t *testing.T) {
 	}
 }
 
+// TestLoadConfig tests the loadConfig function
 func TestLoadConfig(t *testing.T) {
+	// Create a temporary directory
 	tempDir, err := os.MkdirTemp("", "config_test")
 	if err != nil {
 		t.Fatalf("Failed to create temp dir: %v", err)
@@ -127,6 +133,7 @@ func TestLoadConfig(t *testing.T) {
 		}
 	}()
 
+	// Valid config JSON
 	validConfig := `{
 		"id": "bot123",
 		"telegram_token": "token123",
@@ -142,6 +149,7 @@ func TestLoadConfig(t *testing.T) {
 		"anthropic_api_key": "api_key_123"
 	}`
 
+	// Invalid config JSON
 	invalidConfig := `{
 		"id": "bot123",
 		"telegram_token": "token123",
@@ -149,11 +157,13 @@ func TestLoadConfig(t *testing.T) {
 		"model": "claude-v1"
 	}`
 
+	// Write valid config file
 	validPath := filepath.Join(tempDir, "valid_config.json")
 	if err := os.WriteFile(validPath, []byte(validConfig), 0644); err != nil {
 		t.Fatalf("Failed to write valid config: %v", err)
 	}
 
+	// Write invalid config file
 	invalidPath := filepath.Join(tempDir, "invalid_config.json")
 	if err := os.WriteFile(invalidPath, []byte(invalidConfig), 0644); err != nil {
 		t.Fatalf("Failed to write invalid config: %v", err)
@@ -206,6 +216,7 @@ func TestLoadConfig(t *testing.T) {
 	}
 }
 
+// TestValidateConfig tests the validateConfig function
 func TestValidateConfig(t *testing.T) {
 	tests := []struct {
 		name          string
@@ -338,7 +349,9 @@ func TestValidateConfig(t *testing.T) {
 	}
 }
 
+// TestLoadAllConfigs tests the loadAllConfigs function
 func TestLoadAllConfigs(t *testing.T) {
+	// Create a temporary directory
 	tempDir, err := os.MkdirTemp("", "load_all_configs_test")
 	if err != nil {
 		t.Fatalf("Failed to create temp dir: %v", err)
@@ -351,7 +364,7 @@ func TestLoadAllConfigs(t *testing.T) {
 
 	tests := []struct {
 		name           string
-		setupFiles     map[string]string
+		setupFiles     map[string]string // filename -> content
 		expectConfigs  int
 		expectError    bool
 		expectErrorMsg string
@@ -509,6 +522,7 @@ func TestLoadAllConfigs(t *testing.T) {
 
 	for _, tt := range tests {
 		t.Run(tt.name, func(t *testing.T) {
+			// Clear the tempDir before each test
 			if err := os.RemoveAll(tempDir); err != nil {
 				t.Fatalf("Failed to remove temp dir: %v", err)
 			}
@@ -516,6 +530,7 @@ func TestLoadAllConfigs(t *testing.T) {
 				t.Fatalf("Failed to create temp dir: %v", err)
 			}
 
+			// Write the test files directly
 			for filename, content := range tt.setupFiles {
 				err := os.WriteFile(filepath.Join(tempDir, filename), []byte(content), 0644)
 				if err != nil {
@@ -535,7 +550,9 @@ func TestLoadAllConfigs(t *testing.T) {
 	}
 }
 
+// TestBotConfig_Reload tests the Reload method of BotConfig
 func TestBotConfig_Reload(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
+	// Create a temporary directory
 	tempDir, err := os.MkdirTemp("", "reload_test")
 	if err != nil {
 		t.Fatalf("Failed to create temp dir: %v", err)
@@ -546,6 +563,7 @@ func TestBotConfig_Reload(t *testing.T) { //NOSONAR go:S100 -- underscore separa
 		}
 	}()
 
+	// Create initial config file
 	config1 := `{
 		"id": "bot123",
 		"telegram_token": "token123",
@@ -565,11 +583,13 @@ func TestBotConfig_Reload(t *testing.T) { //NOSONAR go:S100 -- underscore separa
 		t.Fatalf("Failed to write initial config: %v", err)
 	}
 
+	// Initialize BotConfig
 	var config BotConfig
 	if err := config.Reload(tempDir, "config.json"); err != nil {
 		t.Fatalf("Failed to reload config: %v", err)
 	}
 
+	// Verify initial load
 	if config.ID != "bot123" {
 		t.Errorf("Expected ID 'bot123', got '%s'", config.ID)
 	}
@@ -577,6 +597,7 @@ func TestBotConfig_Reload(t *testing.T) { //NOSONAR go:S100 -- underscore separa
 		t.Errorf("Expected Model 'claude-v1', got '%s'", config.Model)
 	}
 
+	// Update config file
 	config2 := `{
 		"id": "bot123",
 		"telegram_token": "token123_updated",
@@ -595,10 +616,12 @@ func TestBotConfig_Reload(t *testing.T) { //NOSONAR go:S100 -- underscore separa
 		t.Fatalf("Failed to write updated config: %v", err)
 	}
 
+	// Reload config
 	if err := config.Reload(tempDir, "config.json"); err != nil {
 		t.Fatalf("Failed to reload updated config: %v", err)
 	}
 
+	// Verify updated config
 	if config.TelegramToken != "token123_updated" {
 		t.Errorf("Expected TelegramToken 'token123_updated', got '%s'", config.TelegramToken)
 	}
@@ -613,6 +636,7 @@ func TestBotConfig_Reload(t *testing.T) { //NOSONAR go:S100 -- underscore separa
 	}
 }
 
+// TestBotConfig_UnmarshalJSON_Invalid tests unmarshalling with invalid model
 func TestBotConfig_UnmarshalJSON_Invalid(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
 	jsonData := `{
 		"id": "bot123",
@@ -640,11 +664,14 @@ func TestBotConfig_UnmarshalJSON_Invalid(t *testing.T) { //NOSONAR go:S100 -- un
 	}
 }
 
+// Helper function to check substring
 func contains(s, substr string) bool {
 	return strings.Contains(s, substr)
 }
 
+// TestTemperatureConfig tests that the temperature value is correctly loaded
 func TestTemperatureConfig(t *testing.T) {
+	// Create a temporary directory
 	tempDir, err := os.MkdirTemp("", "temperature_test")
 	if err != nil {
 		t.Fatalf("Failed to create temp dir: %v", err)
@@ -655,6 +682,7 @@ func TestTemperatureConfig(t *testing.T) {
 		}
 	}()
 
+	// Create config with temperature
 	configWithTemp := `{
 		"id": "bot123",
 		"telegram_token": "token123",
@@ -670,6 +698,7 @@ func TestTemperatureConfig(t *testing.T) {
 		"anthropic_api_key": "api_key_123"
 	}`
 
+	// Create config without temperature
 	configWithoutTemp := `{
 		"id": "bot124",
 		"telegram_token": "token124",
@@ -684,6 +713,7 @@ func TestTemperatureConfig(t *testing.T) {
 		"anthropic_api_key": "api_key_123"
 	}`
 
+	// Write config files
 	withTempPath := filepath.Join(tempDir, "with_temp.json")
 	if err := os.WriteFile(withTempPath, []byte(configWithTemp), 0644); err != nil {
 		t.Fatalf("Failed to write config with temperature: %v", err)
@@ -694,27 +724,35 @@ func TestTemperatureConfig(t *testing.T) {
 		t.Fatalf("Failed to write config without temperature: %v", err)
 	}
 
+	// Test loading config with temperature
 	configWithTempObj, err := loadConfig(withTempPath)
 	if err != nil {
 		t.Fatalf("Failed to load config with temperature: %v", err)
 	}
 
+	// Verify temperature is set correctly
 	if configWithTempObj.Temperature == nil {
 		t.Errorf("Expected Temperature to be set, got nil")
 	} else if *configWithTempObj.Temperature != 0.42 {
 		t.Errorf("Expected Temperature 0.42, got %f", *configWithTempObj.Temperature)
 	}
 
+	// Test loading config without temperature
 	configWithoutTempObj, err := loadConfig(withoutTempPath)
 	if err != nil {
 		t.Fatalf("Failed to load config without temperature: %v", err)
 	}
 
+	// Verify temperature is nil when not specified
 	if configWithoutTempObj.Temperature != nil {
 		t.Errorf("Expected Temperature to be nil, got %f", *configWithoutTempObj.Temperature)
 	}
 }
 
+// Additional tests can be added here to cover more scenarios
+
+// TestBotConfig_PersistModel verifies that PersistModel updates the model both in memory
+// and on disk while leaving all other config fields unchanged.
 func TestBotConfig_PersistModel(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
 	tempDir, err := os.MkdirTemp("", "persist_model_test")
 	if err != nil {
@@ -744,14 +782,17 @@ func TestBotConfig_PersistModel(t *testing.T) { //NOSONAR go:S100 -- underscore
 		ConfigFilePath: configPath,
 	}
 
+	// Successful model update
 	if err := config.PersistModel("claude-sonnet-4-6"); err != nil {
 		t.Fatalf("PersistModel() unexpected error: %v", err)
 	}
 
+	// In-memory model must be updated immediately
 	if string(config.Model) != "claude-sonnet-4-6" {
 		t.Errorf("in-memory model: got %q, want %q", config.Model, "claude-sonnet-4-6")
 	}
 
+	// On-disk model must be updated; other fields must be preserved
 	data, err := os.ReadFile(configPath)
 	if err != nil {
 		t.Fatalf("Failed to read updated config file: %v", err)
@@ -767,192 +808,9 @@ func TestBotConfig_PersistModel(t *testing.T) { //NOSONAR go:S100 -- underscore
 		t.Errorf("on-disk id should be preserved: got %v, want %q", raw["id"], "bot1")
 	}
 
+	// Error case: empty ConfigFilePath must return an error
 	noPath := BotConfig{Model: "claude-v1"}
 	if err := noPath.PersistModel("claude-sonnet-4-6"); err == nil {
 		t.Error("PersistModel with empty ConfigFilePath: expected error, got nil")
 	}
 }
-
-func thinkingTestConfig(id string) BotConfig {
-	return BotConfig{
-		ID:              id,
-		TelegramToken:   "token-" + id,
-		MemorySize:      10,
-		MessagePerHour:  10,
-		MessagePerDay:   100,
-		TempBanDuration: "1h",
-		Model:           "claude-test",
-	}
-}
-
-func TestThinkingConfig(t *testing.T) {
-	cases := []struct {
-		name     string
-		thinking string
-		display  string
-		wantErr  string
-	}{
-		{"absent", "", "", ""},
-		{"adaptive", ThinkingModeAdaptive, "", ""},
-		{"disabled", ThinkingModeDisabled, "", ""},
-		{"adaptive summarized", ThinkingModeAdaptive, ThinkingDisplaySummarized, ""},
-		{"adaptive omitted", ThinkingModeAdaptive, ThinkingDisplayOmitted, ""},
-		{"legacy enabled rejected", "enabled", "", "invalid 'thinking'"},
-		{"case sensitive", "Adaptive", "", "invalid 'thinking'"},
-		{"unknown display", ThinkingModeAdaptive, "verbose", "invalid 'thinking_display'"},
-		{"display without thinking", "", ThinkingDisplaySummarized, "'thinking_display' requires"},
-		{"display with disabled", ThinkingModeDisabled, ThinkingDisplayOmitted, "'thinking_display' requires"},
-	}
-	for i, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			cfg := thinkingTestConfig(fmt.Sprintf("bot-think-%d", i))
-			cfg.Thinking = tc.thinking
-			cfg.ThinkingDisplay = tc.display
-			err := validateConfig(&cfg, map[string]bool{}, map[string]bool{})
-			if tc.wantErr == "" {
-				if err != nil {
-					t.Fatalf("validateConfig(thinking=%q display=%q) = %v, want nil", tc.thinking, tc.display, err)
-				}
-				return
-			}
-			if err == nil {
-				t.Fatalf("validateConfig(thinking=%q display=%q) = nil, want error containing %q", tc.thinking, tc.display, tc.wantErr)
-			}
-			if !contains(err.Error(), tc.wantErr) {
-				t.Errorf("error %q does not contain %q", err.Error(), tc.wantErr)
-			}
-		})
-	}
-}
-
-func TestMaxTokensConfig(t *testing.T) {
-	var withValue BotConfig
-	if err := json.Unmarshal([]byte(`{"max_tokens": 4000}`), &withValue); err != nil {
-		t.Fatalf("unmarshal: %v", err)
-	}
-	if withValue.MaxTokens != 4000 {
-		t.Errorf("MaxTokens = %d, want 4000", withValue.MaxTokens)
-	}
-
-	var withoutValue BotConfig
-	if err := json.Unmarshal([]byte(`{}`), &withoutValue); err != nil {
-		t.Fatalf("unmarshal: %v", err)
-	}
-	if withoutValue.MaxTokens != 0 {
-		t.Errorf("MaxTokens = %d, want 0 when absent", withoutValue.MaxTokens)
-	}
-
-	neg := thinkingTestConfig("bot-maxtok-neg")
-	neg.MaxTokens = -1
-	if err := validateConfig(&neg, map[string]bool{}, map[string]bool{}); err == nil {
-		t.Error("validateConfig(max_tokens=-1) = nil, want error")
-	}
-	zero := thinkingTestConfig("bot-maxtok-zero")
-	zero.MaxTokens = 0
-	if err := validateConfig(&zero, map[string]bool{}, map[string]bool{}); err != nil {
-		t.Errorf("validateConfig(max_tokens=0) = %v, want nil", err)
-	}
-}
-
-func TestThinkingConfigLoad(t *testing.T) {
-	jsonData := `{
-		"id": "bot-think-load",
-		"thinking": "adaptive",
-		"thinking_display": "omitted",
-		"max_tokens": 4096
-	}`
-	var cfg BotConfig
-	if err := json.Unmarshal([]byte(jsonData), &cfg); err != nil {
-		t.Fatalf("unmarshal: %v", err)
-	}
-	if cfg.Thinking != ThinkingModeAdaptive {
-		t.Errorf("Thinking = %q, want %q", cfg.Thinking, ThinkingModeAdaptive)
-	}
-	if cfg.ThinkingDisplay != ThinkingDisplayOmitted {
-		t.Errorf("ThinkingDisplay = %q, want %q", cfg.ThinkingDisplay, ThinkingDisplayOmitted)
-	}
-	if cfg.MaxTokens != 4096 {
-		t.Errorf("MaxTokens = %d, want 4096", cfg.MaxTokens)
-	}
-}
-
-func TestWebSearchConfig(t *testing.T) {
-	t.Run("absent leaves nil", func(t *testing.T) {
-		var cfg BotConfig
-		if err := json.Unmarshal([]byte(`{}`), &cfg); err != nil {
-			t.Fatalf("unmarshal: %v", err)
-		}
-		if cfg.WebSearch != nil {
-			t.Errorf("WebSearch = %+v, want nil when absent", cfg.WebSearch)
-		}
-	})
-
-	t.Run("loads allowlist", func(t *testing.T) {
-		jsonData := `{
-			"web_search": {
-				"allowed_domains": ["example.com/hc", "docs.example.com"],
-				"max_uses": 3,
-				"fetch": true,
-				"max_content_tokens": 50000
-			}
-		}`
-		var cfg BotConfig
-		if err := json.Unmarshal([]byte(jsonData), &cfg); err != nil {
-			t.Fatalf("unmarshal: %v", err)
-		}
-		if cfg.WebSearch == nil {
-			t.Fatalf("WebSearch = nil, want populated")
-		}
-		if len(cfg.WebSearch.AllowedDomains) != 2 {
-			t.Errorf("AllowedDomains = %v, want 2 entries", cfg.WebSearch.AllowedDomains)
-		}
-		if cfg.WebSearch.MaxUses != 3 {
-			t.Errorf("MaxUses = %d, want 3", cfg.WebSearch.MaxUses)
-		}
-		if !cfg.WebSearch.Fetch {
-			t.Error("Fetch = false, want true")
-		}
-		if cfg.WebSearch.MaxContentTokens != 50000 {
-			t.Errorf("MaxContentTokens = %d, want 50000", cfg.WebSearch.MaxContentTokens)
-		}
-	})
-
-	cases := []struct {
-		name    string
-		ws      *WebSearchConfig
-		wantErr string
-	}{
-		{"nil ok", nil, ""},
-		{"allowlist ok", &WebSearchConfig{AllowedDomains: []string{"example.com"}, MaxUses: 3}, ""},
-		{"blocklist ok", &WebSearchConfig{BlockedDomains: []string{"evil.com"}}, ""},
-		{"empty ok", &WebSearchConfig{}, ""},
-		{"both allow and block rejected",
-			&WebSearchConfig{AllowedDomains: []string{"a.com"}, BlockedDomains: []string{"b.com"}},
-			"cannot set both allowed_domains and blocked_domains"},
-		{"negative max_uses rejected",
-			&WebSearchConfig{AllowedDomains: []string{"a.com"}, MaxUses: -1},
-			"'web_search.max_uses' must be greater than 0"},
-		{"negative max_content_tokens rejected",
-			&WebSearchConfig{AllowedDomains: []string{"a.com"}, MaxContentTokens: -1},
-			"'web_search.max_content_tokens' must be greater than 0"},
-	}
-	for i, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			cfg := thinkingTestConfig(fmt.Sprintf("bot-web-%d", i))
-			cfg.WebSearch = tc.ws
-			err := validateConfig(&cfg, map[string]bool{}, map[string]bool{})
-			if tc.wantErr == "" {
-				if err != nil {
-					t.Fatalf("validateConfig(web_search=%+v) = %v, want nil", tc.ws, err)
-				}
-				return
-			}
-			if err == nil {
-				t.Fatalf("validateConfig(web_search=%+v) = nil, want error containing %q", tc.ws, tc.wantErr)
-			}
-			if !contains(err.Error(), tc.wantErr) {
-				t.Errorf("error %q does not contain %q", err.Error(), tc.wantErr)
-			}
-		})
-	}
-}

database.go

@@ -38,11 +38,17 @@ func initDB() (*gorm.DB, error) {
 	}
 	sqlDB.SetMaxOpenConns(1)
 
+	// AutoMigrate the models
 	err = db.AutoMigrate(&BotModel{}, &ConfigModel{}, &Message{}, &User{}, &Role{}, &Scope{})
 	if err != nil {
 		return nil, fmt.Errorf("failed to migrate database schema: %w", err)
 	}
 
+	// Enforce unique owner per bot using raw SQL
+	// Note: SQLite doesn't support partial indexes, but we can simulate it by making a unique index on (BotID, IsOwner)
+	// and ensuring that IsOwner can only be true for one user per BotID.
+	// This approach allows multiple users with IsOwner=false for the same BotID,
+	// but only one user can have IsOwner=true per BotID.
 	err = db.Exec(`CREATE UNIQUE INDEX IF NOT EXISTS idx_bot_owner ON users (bot_id, is_owner) WHERE is_owner = 1;`).Error
 	if err != nil {
 		return nil, fmt.Errorf("failed to create unique index for bot owners: %w", err)
@@ -87,6 +93,7 @@ func createDefaultScopes(db *gorm.DB) error {
 	assignments := map[string][]string{
 		"user":  userScopes,
 		"admin": elevatedScopes,
+		// owner gets the same scopes as admin; owner uniqueness is enforced by the IsOwner flag
 		"owner": elevatedScopes,
 	}
 	for roleName, scopes := range assignments {

elevenlabs.go

@@ -16,6 +16,7 @@ const (
 	elevenLabsDefaultModel = "eleven_multilingual_v2"
 )
 
+// generateSpeech converts text to an mp3 audio stream via ElevenLabs TTS.
 func (b *Bot) generateSpeech(ctx context.Context, text string) (io.Reader, error) {
 	model := b.config.ElevenLabsModel
 	if model == "" {
@@ -48,12 +49,18 @@ func (b *Bot) generateSpeech(ctx context.Context, text string) (io.Reader, error
 	return resp.Body, nil
 }
 
+// transcribeVoice downloads a Telegram voice file and transcribes it via ElevenLabs STT.
+// Uses a direct multipart HTTP call instead of the SDK wrapper to avoid a bug in the
+// ogen-generated encoder: AdditionalFormats (nil slice) is always written as an empty
+// string with Content-Type: application/json, which ElevenLabs rejects with 400.
 func (b *Bot) transcribeVoice(ctx context.Context, fileID string) (string, error) {
+	// 1. Resolve and download the voice file from Telegram via the shared helper.
 	audioBytes, err := b.downloadTelegramFile(ctx, fileID)
 	if err != nil {
 		return "", err
 	}
 
+	// 2. Build multipart body with binary audio — bypasses SDK encoding issues.
 	var buf bytes.Buffer
 	mw := multipart.NewWriter(&buf)
 	if err := mw.WriteField("model_id", "scribe_v1"); err != nil {
@@ -70,6 +77,7 @@ func (b *Bot) transcribeVoice(ctx context.Context, fileID string) (string, error
 		return "", fmt.Errorf("multipart close error: %w", err)
 	}
 
+	// 3. POST to ElevenLabs STT.
 	req, err := http.NewRequestWithContext(ctx, http.MethodPost,
 		elevenLabsSTTURL, &buf)
 	if err != nil {

go.mod

@@ -3,26 +3,25 @@ module github.com/HugeFrog24/go-telegram-bot
 go 1.26.0
 
 require (
-	github.com/anthropics/anthropic-sdk-go v1.57.0
-	github.com/go-telegram/bot v1.22.0
+	github.com/anthropics/anthropic-sdk-go v1.45.0
+	github.com/go-telegram/bot v1.20.0
 	github.com/stretchr/testify v1.11.1
-	golang.org/x/sync v0.22.0
+	golang.org/x/sync v0.20.0
 	golang.org/x/time v0.15.0
 	gorm.io/driver/sqlite v1.6.0
-	gorm.io/gorm v1.31.2
+	gorm.io/gorm v1.31.1
 )
 
 require (
 	github.com/bahlo/generic-list-go v0.2.0 // indirect
 	github.com/buger/jsonparser v1.2.0 // indirect
 	github.com/davecgh/go-spew v1.1.1 // indirect
-	github.com/invopop/jsonschema v0.14.0 // indirect
+	github.com/invopop/jsonschema v0.13.0 // indirect
 	github.com/jinzhu/inflection v1.0.0 // indirect
 	github.com/jinzhu/now v1.1.5 // indirect
 	github.com/kr/pretty v0.3.1 // indirect
 	github.com/mailru/easyjson v0.9.2 // indirect
-	github.com/mattn/go-sqlite3 v1.14.48 // indirect
-	github.com/pb33f/ordered-map/v2 v2.3.1 // indirect
+	github.com/mattn/go-sqlite3 v1.14.44 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/rogpeppe/go-internal v1.14.1 // indirect
 	github.com/standard-webhooks/standard-webhooks/libraries v0.0.1 // indirect
@@ -32,8 +31,7 @@ require (
 	github.com/tidwall/pretty v1.2.1 // indirect
 	github.com/tidwall/sjson v1.2.5 // indirect
 	github.com/wk8/go-ordered-map/v2 v2.1.8 // indirect
-	go.yaml.in/yaml/v4 v4.0.0-rc.6 // indirect
-	golang.org/x/text v0.40.0 // indirect
+	golang.org/x/text v0.37.0 // indirect
 	gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c // indirect
 	gopkg.in/yaml.v3 v3.0.1 // indirect
 )

go.sum

@@ -1,9 +1,5 @@
 github.com/anthropics/anthropic-sdk-go v1.45.0 h1:rWnpyBpm9OAm97jyH5bi6W4SRCwJeNY/RyhaJ7CHSUI=
 github.com/anthropics/anthropic-sdk-go v1.45.0/go.mod h1:bx5vWuHFuGPkELH8Z4KUiNSohFnUwScdpTyr+50myPo=
-github.com/anthropics/anthropic-sdk-go v1.52.0 h1:1TB9jt4DN87VMwS/hB1VK26tYzK0ipEOtqPaPGFtJQg=
-github.com/anthropics/anthropic-sdk-go v1.52.0/go.mod h1:3EfIfmFqxH6rbiLcIP4tPFyXL/IHakx2wDG4OU+TIEI=
-github.com/anthropics/anthropic-sdk-go v1.57.0 h1:iEAcPbUKfJ2Iqz9uN/jEndCNW2+x7OYLHDidXDhPjI0=
-github.com/anthropics/anthropic-sdk-go v1.57.0/go.mod h1:3EfIfmFqxH6rbiLcIP4tPFyXL/IHakx2wDG4OU+TIEI=
 github.com/bahlo/generic-list-go v0.2.0 h1:5sz/EEAK+ls5wF+NeqDpk5+iNdMDXrh3z3nPnH1Wvgk=
 github.com/bahlo/generic-list-go v0.2.0/go.mod h1:2KvAjgMlE5NNynlg/5iLrrCCZ2+5xWbdbCW3pNTGyYg=
 github.com/buger/jsonparser v1.2.0 h1:4EFcvK1kD4jyj6YqNK6skK6w+y7FHHBR+XBCtxwu/6g=
@@ -15,14 +11,8 @@ github.com/dnaeon/go-vcr v1.2.0 h1:zHCHvJYTMh1N7xnV7zf1m1GPBF9Ad0Jk/whtQ1663qI=
 github.com/dnaeon/go-vcr v1.2.0/go.mod h1:R4UdLID7HZT3taECzJs4YgbbH6PIGXB6W/sc5OLb6RQ=
 github.com/go-telegram/bot v1.20.0 h1:4Pea/qTidSspr4WBJw9FbHUMNhYeqszBqQUfsQEyFbc=
 github.com/go-telegram/bot v1.20.0/go.mod h1:i2TRs7fXWIeaceF3z7KzsMt/he0TwkVC680mvdTFYeM=
-github.com/go-telegram/bot v1.21.0 h1:Va/PbGc2vBDdv57GCUEEVV6ROlHWiC6SklJY9Hvhzps=
-github.com/go-telegram/bot v1.21.0/go.mod h1:i2TRs7fXWIeaceF3z7KzsMt/he0TwkVC680mvdTFYeM=
-github.com/go-telegram/bot v1.22.0 h1:zK29OoTYMmR5emJrCtGa2SjaGleeZiUB/C1i7kc2lXE=
-github.com/go-telegram/bot v1.22.0/go.mod h1:i2TRs7fXWIeaceF3z7KzsMt/he0TwkVC680mvdTFYeM=
 github.com/invopop/jsonschema v0.13.0 h1:KvpoAJWEjR3uD9Kbm2HWJmqsEaHt8lBUpd0qHcIi21E=
 github.com/invopop/jsonschema v0.13.0/go.mod h1:ffZ5Km5SWWRAIN6wbDXItl95euhFz2uON45H2qjYt+0=
-github.com/invopop/jsonschema v0.14.0 h1:MHQqLhvpNUZfw+hM3AZDYK7jxO8FZoQeQM77g8iyZjg=
-github.com/invopop/jsonschema v0.14.0/go.mod h1:ygm6C2EaVNMBDPpaPlnOA2pFAxBnxGjFlMZABxm9n2I=
 github.com/jinzhu/inflection v1.0.0 h1:K317FqzuhWc8YvSVlFMCCUb36O/S9MCKRDI7QkRKD/E=
 github.com/jinzhu/inflection v1.0.0/go.mod h1:h+uFLlag+Qp1Va5pdKtLDYj+kHp5pxUVkryuEj+Srlc=
 github.com/jinzhu/now v1.1.5 h1:/o9tlHleP7gOFmsnYNz3RGnqzefHA47wQpKrrdTIwXQ=
@@ -38,12 +28,6 @@ github.com/mailru/easyjson v0.9.2 h1:dX8U45hQsZpxd80nLvDGihsQ/OxlvTkVUXH2r/8cb2M
 github.com/mailru/easyjson v0.9.2/go.mod h1:1+xMtQp2MRNVL/V1bOzuP3aP8VNwRW55fQUto+XFtTU=
 github.com/mattn/go-sqlite3 v1.14.44 h1:3VSe+xafpbzsLbdr2AWlAZk9yRHiBhTBakioXaCKTF8=
 github.com/mattn/go-sqlite3 v1.14.44/go.mod h1:pjEuOr8IwzLJP2MfGeTb0A35jauH+C2kbHKBr7yXKVQ=
-github.com/mattn/go-sqlite3 v1.14.47 h1:jOBI62gS7nKeZv+as1oGEy0+1qISgXwH/QBlR6KbfIo=
-github.com/mattn/go-sqlite3 v1.14.47/go.mod h1:6JTjA44L93a0QCyJef5YvlPoKXntQPjzWv5gtm9sB6w=
-github.com/mattn/go-sqlite3 v1.14.48 h1:7XHIgl0a8HwOaiK4E47ozLkST78rR9+OtNGx27D/TFs=
-github.com/mattn/go-sqlite3 v1.14.48/go.mod h1:6JTjA44L93a0QCyJef5YvlPoKXntQPjzWv5gtm9sB6w=
-github.com/pb33f/ordered-map/v2 v2.3.1 h1:5319HDO0aw4DA4gzi+zv4FXU9UlSs3xGZ40wcP1nBjY=
-github.com/pb33f/ordered-map/v2 v2.3.1/go.mod h1:qxFQgd0PkVUtOMCkTapqotNgzRhMPL7VvaHKbd1HnmQ=
 github.com/pkg/diff v0.0.0-20210226163009-20ebb0f2a09e/go.mod h1:pJLUxLENpZxwdsKMEsNbx1VGcRFpLqf3715MtcvvzbA=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
@@ -69,20 +53,10 @@ github.com/tidwall/sjson v1.2.5 h1:kLy8mja+1c9jlljvWTlSazM7cKDRfJuR/bOJhcY5NcY=
 github.com/tidwall/sjson v1.2.5/go.mod h1:Fvgq9kS/6ociJEDnK0Fk1cpYF4FIW6ZF7LAe+6jwd28=
 github.com/wk8/go-ordered-map/v2 v2.1.8 h1:5h/BUHu93oj4gIdvHHHGsScSTMijfx5PeYkE/fJgbpc=
 github.com/wk8/go-ordered-map/v2 v2.1.8/go.mod h1:5nJHM5DyteebpVlHnWMV0rPz6Zp7+xBAnxjb1X5vnTw=
-go.yaml.in/yaml/v4 v4.0.0-rc.6 h1:1h7H1ohdUh93/FyE4YaDa1Zh64K6VVbjF4K6WUxMtH4=
-go.yaml.in/yaml/v4 v4.0.0-rc.6/go.mod h1:aZqd9kCMsGL7AuUv/m/PvWLdg5sjJsZ4oHDEnfPPfY0=
 golang.org/x/sync v0.20.0 h1:e0PTpb7pjO8GAtTs2dQ6jYa5BWYlMuX047Dco/pItO4=
 golang.org/x/sync v0.20.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
-golang.org/x/sync v0.21.0 h1:HLII4xRRTtCRkxYp4HNFF0Js/Og6q2i++KXbg0gHCwM=
-golang.org/x/sync v0.21.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
-golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
-golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
 golang.org/x/text v0.37.0 h1:Cqjiwd9eSg8e0QAkyCaQTNHFIIzWtidPahFWR83rTrc=
 golang.org/x/text v0.37.0/go.mod h1:a5sjxXGs9hsn/AJVwuElvCAo9v8QYLzvavO5z2PiM38=
-golang.org/x/text v0.38.0 h1:sXmwo9DwP3OK9EZ7PqAdaooSGozfl/3a6/xJcbzPRhE=
-golang.org/x/text v0.38.0/go.mod h1:YXZt3QhHUKYT53r2lLKFIVi6Ao1jdzrTR/KQ09qyxF4=
-golang.org/x/text v0.40.0 h1:Ub2Z6/xjgF1WrYQz2nuITOEegKFtiIy+rieRJ5lHZKs=
-golang.org/x/text v0.40.0/go.mod h1:hpnzDAfGV753zIKo+wk3u1bVKCGPbrnF7+7LBF/UHVY=
 golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
 golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
@@ -96,5 +70,3 @@ gorm.io/driver/sqlite v1.6.0 h1:WHRRrIiulaPiPFmDcod6prc4l2VGVWHz80KspNsxSfQ=
 gorm.io/driver/sqlite v1.6.0/go.mod h1:AO9V1qIQddBESngQUKWL9yoH93HIeA1X6V633rBwyT8=
 gorm.io/gorm v1.31.1 h1:7CA8FTFz/gRfgqgpeKIBcervUn3xSyPUmr6B2WXJ7kg=
 gorm.io/gorm v1.31.1/go.mod h1:XyQVbO2k6YkOis7C2437jSit3SsDK72s7n7rsSHd+Gs=
-gorm.io/gorm v1.31.2 h1:3o8FXNo9v9S858gil+3LlZA1LkCOzgb4g5BL64FgaCo=
-gorm.io/gorm v1.31.2/go.mod h1:XyQVbO2k6YkOis7C2437jSit3SsDK72s7n7rsSHd+Gs=

handlers.go

@@ -13,7 +13,8 @@ import (
 	"golang.org/x/sync/errgroup"
 )
 
-func (b *Bot) handleVoiceMessage(ctx context.Context, message *models.Message, userMsg Message, chatID, userID int64, username, firstName, lastName string, isPremium bool, languageCode string, messageTime int, businessConnectionID string) {
+func (b *Bot) handleVoiceMessage(ctx context.Context, message *models.Message, userMsg Message, chatID, userID int64, username, firstName, lastName string, isPremium bool, languageCode string, messageTime int, isNewChat, isOwner bool, businessConnectionID string) {
+	// If ElevenLabs is not configured, respond with text — consistent with all other error paths.
 	if b.config.ElevenLabsAPIKey == "" {
 		if err := b.sendResponse(ctx, chatID, "I don't understand voice messages.", businessConnectionID); err != nil {
 			ErrorLogger.Printf("Error sending voice-unsupported message: %v", err)
@@ -28,9 +29,6 @@ func (b *Bot) handleVoiceMessage(ctx context.Context, message *models.Message, u
 		return
 	}
 
-	stopTyping := b.startChatAction(ctx, chatID, businessConnectionID, models.ChatActionTyping)
-	defer stopTyping()
-
 	transcript, err := b.transcribeVoice(ctx, message.Voice.FileID)
 	if err != nil {
 		ErrorLogger.Printf("Error transcribing voice message from user %d: %v", userID, err)
@@ -40,6 +38,8 @@ func (b *Bot) handleVoiceMessage(ctx context.Context, message *models.Message, u
 		return
 	}
 
+	// Replace the stored "[Voice message]" placeholder with the actual transcript,
+	// keeping the audit record intact while giving the LLM meaningful context.
 	if err := b.db.Model(&userMsg).Update("text", transcript).Error; err != nil {
 		ErrorLogger.Printf("Error updating voice transcript in DB: %v", err)
 	}
@@ -56,7 +56,10 @@ func (b *Bot) handleVoiceMessage(ctx context.Context, message *models.Message, u
 
 	chatMemory := b.getOrCreateChatMemory(chatID)
 	contextMessages := b.prepareContextMessages(chatMemory)
-	response, err := b.getAnthropicResponse(ctx, chatID, contextMessages, false, username, firstName, lastName, isPremium, languageCode, messageTime, nil)
+	// Voice path passes nil for onSegment: tool-call narration across multiple
+	// TTS clips would be jarring, so we accumulate everything and synthesize one
+	// audio clip from the joined text.
+	response, err := b.getAnthropicResponse(ctx, chatID, contextMessages, isNewChat, isOwner, false, username, firstName, lastName, isPremium, languageCode, messageTime, nil)
 	if err != nil {
 		ErrorLogger.Printf("Error getting Anthropic response for voice: %v", err)
 		if err := b.sendResponse(ctx, chatID, b.anthropicErrorResponse(err, userID), businessConnectionID); err != nil {
@@ -65,14 +68,9 @@ func (b *Bot) handleVoiceMessage(ctx context.Context, message *models.Message, u
 		return
 	}
 
-	// Switch the indicator once the model is done and synthesis begins, so the
-	// client shows "recording audio" rather than "typing" for a voice reply.
-	stopTyping()
-	stopRecording := b.startChatAction(ctx, chatID, businessConnectionID, models.ChatActionUploadVoice)
-	defer stopRecording()
-
 	audioReader, err := b.generateSpeech(ctx, response)
 	if err != nil {
+		// TTS failed — fall back to text so the user still gets a reply.
 		ErrorLogger.Printf("Error generating speech, falling back to text: %v", err)
 		if err := b.sendResponse(ctx, chatID, response, businessConnectionID); err != nil {
 			ErrorLogger.Printf("Error sending text fallback: %v", err)
@@ -80,6 +78,7 @@ func (b *Bot) handleVoiceMessage(ctx context.Context, message *models.Message, u
 		return
 	}
 
+	// Store the assistant response before sending.
 	if _, err := b.screenOutgoingMessage(chatID, response); err != nil {
 		ErrorLogger.Printf("Error storing assistant voice response: %v", err)
 	}
@@ -96,6 +95,10 @@ func (b *Bot) handleVoiceMessage(ctx context.Context, message *models.Message, u
 	}
 }
 
+// uploadPhotoFromItem downloads the largest PhotoSize from a Telegram message
+// item and uploads it to the Anthropic Files API tagged with the bot's filename
+// convention. Telegram serves photos as JPEG regardless of the user's original
+// format, so the content-type is fixed.
 func (b *Bot) uploadPhotoFromItem(ctx context.Context, item *models.Message, chatID int64) (string, error) {
 	photo := largestPhotoSize(item.Photo)
 	data, err := b.downloadTelegramFile(ctx, photo.FileID)
@@ -106,6 +109,14 @@ func (b *Bot) uploadPhotoFromItem(ctx context.Context, item *models.Message, cha
 	return b.uploadImageToAnthropic(ctx, data, filename, "image/jpeg")
 }
 
+// handlePhotoMessage processes a user turn that contains one or more photos —
+// either a single photo or a Telegram media_group (album) coalesced upstream.
+// For albums the caller passes the items sorted by message_id. Each item's
+// largest PhotoSize is downloaded and uploaded to the Anthropic Files API; the
+// resulting file_ids are persisted on a single Message row representing the
+// whole user turn. On any upload failure, compensating deletes fire against
+// already-uploaded file_ids and the DB row is not written — orphans on
+// Anthropic are preferred over poisoned DB references.
 func (b *Bot) handlePhotoMessage(
 	ctx context.Context,
 	items []*models.Message,
@@ -114,17 +125,19 @@ func (b *Bot) handlePhotoMessage(
 	isPremium bool,
 	languageCode string,
 	messageTime int,
+	isNewChat, isOwner bool,
 	businessConnectionID string,
 ) {
 	if len(items) == 0 {
 		return
 	}
 
-	// Covers the Files API uploads as well as the model turn; on an album this
-	// is the longest wait in the bot.
-	stopTyping := b.startChatAction(ctx, chatID, businessConnectionID, models.ChatActionTyping)
-	defer stopTyping()
-
+	// Phase 1: download + upload each photo in parallel. Album latency collapses
+	// from N*RTT to ~max(t_i) — relevant for the multi-screenshot use case.
+	// Caption capture happens in the sequential loop (one item carries it; order
+	// is preserved upstream via flushAlbum's sort by message_id). uploaded[i]
+	// matches items[i] so file_ids stay in user-intended order; non-photo items
+	// leave their slot empty and are compacted out before commit.
 	uploaded := make([]string, len(items))
 	caption := ""
 	g, gctx := errgroup.WithContext(ctx)
@@ -169,6 +182,11 @@ func (b *Bot) handlePhotoMessage(
 		return
 	}
 
+	// Phase 2: commit Message row. getOrCreateChatMemory MUST run before
+	// storeMessage — on a cold cache, the get-or-create hydrates from DB, and
+	// hydrating after the insert would re-load the just-stored row, causing
+	// addMessageToChatMemory below to produce a duplicate user turn. Mirrors
+	// the ordering used by screenIncomingMessage for the same reason.
 	chatMemory := b.getOrCreateChatMemory(chatID)
 	userMessage := b.createMessage(chatID, userID, username, "user", caption, true)
 	userMessage.ImageFileIDs = finalUploaded
@@ -182,9 +200,10 @@ func (b *Bot) handlePhotoMessage(
 	}
 	b.addMessageToChatMemory(chatMemory, userMessage)
 
+	// Phase 3: stream Anthropic's reply, same shape as the text path.
 	contextMessages := b.prepareContextMessages(chatMemory)
 	joined, err := b.getAnthropicResponse(
-		ctx, chatID, contextMessages, false,
+		ctx, chatID, contextMessages, isNewChat, isOwner, false,
 		username, firstName, lastName, isPremium, languageCode, messageTime,
 		func(seg string) error {
 			return b.sendOneSegment(ctx, chatID, seg, businessConnectionID)
@@ -202,47 +221,10 @@ func (b *Bot) handlePhotoMessage(
 	}
 }
 
-// respondToChat runs one assistant turn against the chat's current memory and
-// streams the reply back. Both the immediate path and the debounced flush go
-// through here, so a coalesced turn is byte-for-byte the same request as a
-// single-message one: the messages were already written to memory at intake, and
-// the model simply sees more of them.
-func (b *Bot) respondToChat(
-	ctx context.Context,
-	chatID, userID int64,
-	isEmojiOnly bool,
-	username, firstName, lastName string,
-	isPremium bool,
-	languageCode string,
-	messageTime int,
-	businessConnectionID string,
-) {
-	stopTyping := b.startChatAction(ctx, chatID, businessConnectionID, models.ChatActionTyping)
-	defer stopTyping()
-
-	chatMemory := b.getOrCreateChatMemory(chatID)
-	contextMessages := b.prepareContextMessages(chatMemory)
-
-	joined, err := b.getAnthropicResponse(
-		ctx, chatID, contextMessages, isEmojiOnly,
-		username, firstName, lastName, isPremium, languageCode, messageTime,
-		func(seg string) error {
-			return b.sendOneSegment(ctx, chatID, seg, businessConnectionID)
-		},
-	)
-	if err != nil {
-		ErrorLogger.Printf("Error getting Anthropic response: %v", err)
-		if sendErr := b.sendResponse(ctx, chatID, b.anthropicErrorResponse(err, userID), businessConnectionID); sendErr != nil {
-			ErrorLogger.Printf("Error sending response: %v", sendErr)
-		}
-		return
-	}
-
-	if _, storeErr := b.screenOutgoingMessage(chatID, joined); storeErr != nil {
-		ErrorLogger.Printf("Error recording assistant turn: %v", storeErr)
-	}
-}
-
+// anthropicErrorResponse returns the message to send back to the user when getAnthropicResponse
+// fails. Admins and owners (anyone with model:set scope) receive the underlying API error so they
+// can act on it — actionable hint for model-deprecation, raw status+body+request-id for everything
+// else. Regular users always get the generic fallback to avoid leaking internal details.
 func (b *Bot) anthropicErrorResponse(err error, userID int64) string {
 	isElevated := b.hasScope(userID, ScopeModelSet)
 
@@ -267,6 +249,7 @@ func (b *Bot) anthropicErrorResponse(err error, userID int64) string {
 			}
 			return out
 		}
+		// Non-API errors (network, context cancel, etc.) — show the Go error text.
 		return fmt.Sprintf("⚠️ Anthropic call failed: %v", err)
 	}
 
@@ -281,9 +264,11 @@ func (b *Bot) handleUpdate(ctx context.Context, tgBot *bot.Bot, update *models.U
 	} else if update.BusinessMessage != nil {
 		message = update.BusinessMessage
 	} else {
+		// No message to process
 		return
 	}
 
+	// Extract businessConnectionID if available
 	var businessConnectionID string
 	if update.BusinessConnection != nil {
 		businessConnectionID = update.BusinessConnection.ID
@@ -292,6 +277,8 @@ func (b *Bot) handleUpdate(ctx context.Context, tgBot *bot.Bot, update *models.U
 	}
 
 	if message.From == nil {
+		// Channel posts and some automated messages have no sender — ignore them.
+		// see: https://core.telegram.org/bots/api#message
 		return
 	}
 
@@ -305,17 +292,24 @@ func (b *Bot) handleUpdate(ctx context.Context, tgBot *bot.Bot, update *models.U
 	messageTime := message.Date
 	text := message.Text
 
+	// Check if it's a new chat (before storing the message so the flag is accurate).
+	isNewChatFlag := b.isNewChat(chatID)
+
+	// Determine if the user is the owner — needed up-front so the album buffer
+	// can capture it alongside other per-turn metadata.
 	var isOwner bool
 	if b.db.Where("telegram_id = ? AND bot_id = ? AND is_owner = ?", userID, b.botID, true).First(&User{}).Error == nil {
 		isOwner = true
 	}
 
+	// Always create/get the user record — on the very first message and on all subsequent ones.
 	user, err := b.getOrCreateUser(userID, username, isOwner)
 	if err != nil {
 		ErrorLogger.Printf("Error getting or creating user: %v", err)
 		return
 	}
 
+	// Update the username if it has changed
 	if user.Username != username {
 		user.Username = username
 		if err := b.db.Save(&user).Error; err != nil {
@@ -323,17 +317,16 @@ func (b *Bot) handleUpdate(ctx context.Context, tgBot *bot.Bot, update *models.U
 		}
 	}
 
-	// Media never waits on the text debounce window. Cancelling here does not
-	// discard the buffered text: those messages are already in chat memory, so
-	// the turn this media triggers answers them too.
+	// Photo routing bypasses screenIncomingMessage entirely: handlePhotoMessage
+	// owns its own DB-row creation (one row per coalesced user turn, holding
+	// all uploaded file_ids). Album items go through the 1s buffer first; only
+	// the flush dispatches to handlePhotoMessage.
 	if message.MediaGroupID != "" && len(message.Photo) > 0 {
-		b.cancelIntake(chatID)
 		b.bufferAlbumItem(ctx, message, chatID, userID, username, firstName, lastName,
-			isPremium, languageCode, messageTime, businessConnectionID)
+			isPremium, languageCode, messageTime, isNewChatFlag, isOwner, businessConnectionID)
 		return
 	}
 	if len(message.Photo) > 0 {
-		b.cancelIntake(chatID)
 		if !b.checkRateLimits(userID) {
 			b.sendRateLimitExceededMessage(ctx, chatID, businessConnectionID)
 			return
@@ -341,32 +334,38 @@ func (b *Bot) handleUpdate(ctx context.Context, tgBot *bot.Bot, update *models.U
 		b.handlePhotoMessage(ctx, []*models.Message{message},
 			chatID, userID, username, firstName, lastName,
 			isPremium, languageCode, messageTime,
-			businessConnectionID)
+			isNewChatFlag, isOwner, businessConnectionID)
 		return
 	}
 
+	// Screen incoming message (store to DB + add to chat memory) — text/voice/sticker only.
 	userMsg, err := b.screenIncomingMessage(message)
 	if err != nil {
 		ErrorLogger.Printf("Error storing user message: %v", err)
 		return
 	}
 
+	// Check if the message is a command — applies on every message, including the very first.
 	if message.Entities != nil {
 		for _, entity := range message.Entities {
 			if entity.Type == "bot_command" {
 				command := strings.TrimSpace(message.Text[entity.Offset : entity.Offset+entity.Length])
 				switch command {
 				case "/stats":
+					// Parse command parameters
 					parts := strings.Fields(message.Text)
 
+					// Default: show global stats
 					if len(parts) == 1 {
 						b.sendStats(ctx, chatID, userID, 0, businessConnectionID)
 						return
 					}
 
+					// Check for "user" parameter
 					if len(parts) >= 2 && parts[1] == "user" {
-						targetUserID := userID
+						targetUserID := userID // Default to current user
 
+						// If a user ID is provided, parse it
 						if len(parts) >= 3 {
 							var parseErr error
 							targetUserID, parseErr = strconv.ParseInt(parts[2], 10, 64)
@@ -383,6 +382,7 @@ func (b *Bot) handleUpdate(ctx context.Context, tgBot *bot.Bot, update *models.U
 						return
 					}
 
+					// Invalid parameter
 					if err := b.sendResponse(ctx, chatID, "Invalid command format. Usage: /stats or /stats user [user_id]", businessConnectionID); err != nil {
 						ErrorLogger.Printf("Error sending response: %v", err)
 					}
@@ -432,6 +432,11 @@ func (b *Bot) handleUpdate(ctx context.Context, tgBot *bot.Bot, update *models.U
 						return
 					}
 					newModel := strings.TrimSpace(parts[1])
+					// No upfront model validation:
+					// - The go-anthropic library constants are not enumerable at runtime (Go has no const reflection).
+					// - A live /v1/models probe would add a network round-trip and show in the API audit log.
+					// - An invalid model ID will produce a 404 on the next real message, which routes through
+					//   anthropicErrorResponse and already delivers an actionable admin-facing hint.
 					if err := b.config.PersistModel(newModel); err != nil {
 						ErrorLogger.Printf("Failed to persist model change: %v", err)
 						if err := b.sendResponse(ctx, chatID, fmt.Sprintf("Model updated in memory to `%s`, but failed to save to config file: %v", newModel, err), businessConnectionID); err != nil {
@@ -476,43 +481,64 @@ func (b *Bot) handleUpdate(ctx context.Context, tgBot *bot.Bot, update *models.U
 		}
 	}
 
+	// Rate limit check applies to all message types including stickers.
 	if !b.checkRateLimits(userID) {
 		b.sendRateLimitExceededMessage(ctx, chatID, businessConnectionID)
 		return
 	}
 
+	// Check if the message contains a voice note (context is built inside the handler
+	// after the transcript replaces the placeholder, so it must not be built here).
 	if message.Voice != nil {
-		b.cancelIntake(chatID)
-		b.handleVoiceMessage(ctx, message, userMsg, chatID, userID, username, firstName, lastName, isPremium, languageCode, messageTime, businessConnectionID)
+		b.handleVoiceMessage(ctx, message, userMsg, chatID, userID, username, firstName, lastName, isPremium, languageCode, messageTime, isNewChatFlag, isOwner, businessConnectionID)
 		return
 	}
 
+	// Build context once — shared by the sticker and text response paths.
+	chatMemory := b.getOrCreateChatMemory(chatID)
+	contextMessages := b.prepareContextMessages(chatMemory)
+
+	// Check if the message contains a sticker
 	if message.Sticker != nil {
-		b.cancelIntake(chatID)
-		contextMessages := b.prepareContextMessages(b.getOrCreateChatMemory(chatID))
 		b.handleStickerMessage(ctx, chatID, userMsg, message, contextMessages, businessConnectionID)
 		return
 	}
 
+	// Proceed only if the message contains text
 	if text == "" {
 		InfoLogger.Printf("Received a non-text message from user %d in chat %d", userID, chatID)
 		return
 	}
 
+	// Determine if the text contains only emojis
 	isEmojiOnly := isOnlyEmojis(text)
 
-	// Plain text is the only thing that debounces: it is what users fragment
-	// across several sends, and it is the only kind whose meaning survives being
-	// read as one turn.
-	if b.config.DebounceWindow() > 0 {
-		b.bufferIntake(ctx, chatID, userID, username, firstName, lastName,
-			isPremium, languageCode, messageTime, businessConnectionID, isEmojiOnly)
+	// Stream Anthropic's reply, sending each completed text block to Telegram
+	// as it arrives — gives the conversational rhythm Claude uses around tool
+	// calls (text → pause for tool → text → pause → text), rather than a long
+	// upfront wait followed by all bubbles at once.
+	joined, err := b.getAnthropicResponse(
+		ctx, chatID, contextMessages, isNewChatFlag, isOwner, isEmojiOnly,
+		username, firstName, lastName, isPremium, languageCode, messageTime,
+		func(seg string) error {
+			return b.sendOneSegment(ctx, chatID, seg, businessConnectionID)
+		},
+	)
+	if err != nil {
+		ErrorLogger.Printf("Error getting Anthropic response: %v", err)
+		// Errors go out as a single message — no need to fan out a one-line error.
+		if sendErr := b.sendResponse(ctx, chatID, b.anthropicErrorResponse(err, userID), businessConnectionID); sendErr != nil {
+			ErrorLogger.Printf("Error sending response: %v", sendErr)
+		}
 		return
 	}
 
-	b.respondToChat(ctx, chatID, userID, isEmojiOnly,
-		username, firstName, lastName, isPremium, languageCode, messageTime,
-		businessConnectionID)
+	// Record the full turn once, at end-of-stream. Same 1-reply-per-prompt
+	// invariant as the non-streaming path: one DB row, one answered_on stamp,
+	// one chat-memory entry containing the joined segments.
+	if _, storeErr := b.screenOutgoingMessage(chatID, joined); storeErr != nil {
+		ErrorLogger.Printf("Error recording assistant turn: %v", storeErr)
+	}
 }
 
 func (b *Bot) sendRateLimitExceededMessage(ctx context.Context, chatID int64, businessConnectionID string) {
@@ -522,10 +548,13 @@ func (b *Bot) sendRateLimitExceededMessage(ctx context.Context, chatID int64, bu
 }
 
 func (b *Bot) handleStickerMessage(ctx context.Context, chatID int64, userMessage Message, message *models.Message, contextMessages []anthropic.BetaMessageParam, businessConnectionID string) {
+	// userMessage was already screened (stored + added to memory) by handleUpdate — do not call screenIncomingMessage again.
 
-	response, err := b.generateStickerResponse(ctx, userMessage, contextMessages, businessConnectionID)
+	// Generate AI response about the sticker
+	response, err := b.generateStickerResponse(ctx, userMessage, contextMessages)
 	if err != nil {
 		ErrorLogger.Printf("Error generating sticker response: %v", err)
+		// Provide a fallback dynamic response based on sticker type
 		if message.Sticker.IsAnimated {
 			response = "Wow, that's a cool animated sticker!"
 		} else if message.Sticker.IsVideo {
@@ -535,19 +564,21 @@ func (b *Bot) handleStickerMessage(ctx context.Context, chatID int64, userMessag
 		}
 	}
 
+	// Send the response
 	if err := b.sendResponse(ctx, chatID, response, businessConnectionID); err != nil {
 		ErrorLogger.Printf("Error sending response: %v", err)
 		return
 	}
 }
 
-func (b *Bot) generateStickerResponse(ctx context.Context, message Message, contextMessages []anthropic.BetaMessageParam, businessConnectionID string) (string, error) {
-	stopTyping := b.startChatAction(ctx, message.ChatID, businessConnectionID, models.ChatActionTyping)
-	defer stopTyping()
-
+func (b *Bot) generateStickerResponse(ctx context.Context, message Message, contextMessages []anthropic.BetaMessageParam) (string, error) {
+	// contextMessages already contains the sticker turn (added by screenIncomingMessage as
+	// "Sent a sticker: <emoji>"), so the full conversation history is preserved.
 	if message.StickerFileID != "" {
 		messageTime := int(message.Timestamp.Unix())
-		response, err := b.getAnthropicResponse(ctx, message.ChatID, contextMessages, true, message.Username, "", "", false, "", messageTime, nil)
+		// Sticker reactions are casual chit-chat; tool use is unusual here, so
+		// pass nil for onSegment and return the joined text for a single bubble.
+		response, err := b.getAnthropicResponse(ctx, message.ChatID, contextMessages, false, false, true, message.Username, "", "", false, "", messageTime, nil)
 		if err != nil {
 			return "", err
 		}
@@ -558,6 +589,7 @@ func (b *Bot) generateStickerResponse(ctx context.Context, message Message, cont
 }
 
 func (b *Bot) clearChatHistory(ctx context.Context, chatID int64, currentUserID int64, targetUserID int64, targetChatID int64, businessConnectionID string, hardDelete bool) {
+	// If targetUserID is provided and different from currentUserID, check permissions
 	if targetUserID != 0 && targetUserID != currentUserID {
 		requiredScope := ScopeHistoryClearAny
 		if hardDelete {
@@ -571,6 +603,7 @@ func (b *Bot) clearChatHistory(ctx context.Context, chatID int64, currentUserID
 			return
 		}
 
+		// Check if the target user exists
 		var targetUser User
 		err := b.db.Where("telegram_id = ? AND bot_id = ?", targetUserID, b.botID).First(&targetUser).Error
 		if err != nil {
@@ -581,19 +614,42 @@ func (b *Bot) clearChatHistory(ctx context.Context, chatID int64, currentUserID
 			return
 		}
 	} else {
+		// If no targetUserID is provided, set it to currentUserID
 		targetUserID = currentUserID
 	}
 
+	// Delete messages from the database
+	//
+	// Assumption: this bot is primarily used in private DMs, where each user's messages
+	// are stored with chat_id == their own user_id — not the caller's chat_id. Scoping
+	// a cross-user delete by the caller's chatID would therefore match 0 rows.
+	//
+	// When clearing another user's history the default (targetChatID == 0) deletes all
+	// of that user's messages across every chat for this bot — the natural meaning of
+	// "/clear <userID>" (wipe their entire history with the bot).
+	//
+	// When targetChatID != 0 the deletion is scoped to that specific chat, which is
+	// useful for group moderation ("/clear <userID> <chatID>").
 	var err error
 	if hardDelete {
+		// Hard delete routes through hardDeleteScope, which orchestrates the
+		// soft-delete → Anthropic Files.Delete → Unscoped().Delete dance. Rows
+		// whose Anthropic-side file cleanup fails stay soft-deleted for the
+		// reconciliation job to retry.
 		if targetUserID == currentUserID {
+			// Own history — delete ALL messages (user + assistant) in the current chat.
 			err = b.hardDeleteScope(ctx, "chat_id = ? AND bot_id = ?", chatID, b.botID)
 			InfoLogger.Printf("User %d permanently deleted their own chat history in chat %d", currentUserID, chatID)
 		} else {
 			if targetChatID != 0 {
+				// Chat-scoped: delete ALL messages (user + assistant) in the specified chat.
 				err = b.hardDeleteScope(ctx, "chat_id = ? AND bot_id = ?", targetChatID, b.botID)
 				InfoLogger.Printf("Admin/owner %d permanently deleted chat history for user %d in chat %d", currentUserID, targetUserID, targetChatID)
 			} else {
+				// Bot-wide: user's own messages across every chat plus assistant
+				// responses in their DM chat (where chat_id == user_id by Telegram
+				// convention). The two clauses are collapsed into one OR-WHERE so
+				// the helper's three-step pattern covers both in a single pass.
 				err = b.hardDeleteScope(ctx,
 					"bot_id = ? AND (user_id = ? OR (chat_id = ? AND is_user = ?))",
 					b.botID, targetUserID, targetUserID, false)
@@ -601,14 +657,19 @@ func (b *Bot) clearChatHistory(ctx context.Context, chatID int64, currentUserID
 			}
 		}
 	} else {
+		// Soft delete messages
 		if targetUserID == currentUserID {
+			// Own history — delete ALL messages (user + assistant) in the current chat.
 			err = b.db.Where("chat_id = ? AND bot_id = ?", chatID, b.botID).Delete(&Message{}).Error
 			InfoLogger.Printf("User %d soft deleted their own chat history in chat %d", currentUserID, chatID)
 		} else {
 			if targetChatID != 0 {
+				// Chat-scoped: delete ALL messages (user + assistant) in the specified chat.
 				err = b.db.Where("chat_id = ? AND bot_id = ?", targetChatID, b.botID).Delete(&Message{}).Error
 				InfoLogger.Printf("Admin/owner %d soft deleted chat history for user %d in chat %d", currentUserID, targetUserID, targetChatID)
 			} else {
+				// Bot-wide: delete all of the user's own messages across every chat, then delete
+				// assistant messages from their DM chat (where chat_id == user_id by Telegram convention).
 				err = b.db.Where("bot_id = ? AND user_id = ?", b.botID, targetUserID).Delete(&Message{}).Error
 				if err == nil {
 					err = b.db.Where("chat_id = ? AND bot_id = ? AND is_user = ?", targetUserID, b.botID, false).Delete(&Message{}).Error
@@ -626,36 +687,28 @@ func (b *Bot) clearChatHistory(ctx context.Context, chatID int64, currentUserID
 		return
 	}
 
-	// Drop any armed intake buffer for the same chat before clearing memory.
-	// Otherwise the debounce timer fires moments later and repopulates the chat
-	// with the very messages that were just deleted — the openclaw/openclaw#51046
-	// failure mode, but with a privacy consequence rather than a stray reply.
-	clearedChatID := chatID
-	if targetUserID != currentUserID {
-		clearedChatID = targetChatID
-		if clearedChatID == 0 {
-			clearedChatID = targetUserID
-		}
-	}
-	if discarded := b.cancelIntake(clearedChatID); discarded > 0 {
-		InfoLogger.Printf("[%s] discarded %d buffered message(s) for chat %d on history clear",
-			b.config.ID, discarded, clearedChatID)
-	}
-
+	// Evict the relevant in-memory cache entry so the next access rebuilds from
+	// the now-clean DB. Applies to all cases: own history, cross-user
+	// scoped to a specific chat, and bot-wide cross-user clear.
 	b.chatMemoriesMu.Lock()
 	if targetUserID == currentUserID {
+		// Own history is always scoped to the current chat.
 		delete(b.chatMemories, chatID)
 	} else if targetChatID != 0 {
+		// Admin cleared a specific chat — evict that chat's cache.
 		delete(b.chatMemories, targetChatID)
 	} else {
+		// Bot-wide clear: primary use-case is DMs where chatID == userID.
 		delete(b.chatMemories, targetUserID)
 	}
 	b.chatMemoriesMu.Unlock()
 
+	// Send a confirmation message
 	var confirmationMessage string
 	if targetUserID == currentUserID {
 		confirmationMessage = "Your chat history has been cleared."
 	} else {
+		// Get the username of the target user if available
 		var targetUser User
 		err := b.db.Where("telegram_id = ? AND bot_id = ?", targetUserID, b.botID).First(&targetUser).Error
 		if err == nil && targetUser.Username != "" {

handlers_test.go

@@ -17,6 +17,7 @@ import (
 )
 
 func TestHandleUpdate_NewChat(t *testing.T) {
+	// Setup
 	db := setupTestDB(t)
 	mockClock := &MockClock{
 		currentTime: time.Now(),
@@ -24,7 +25,7 @@ func TestHandleUpdate_NewChat(t *testing.T) {
 
 	config := BotConfig{
 		ID:              "test_bot",
-		OwnerTelegramID: 123,
+		OwnerTelegramID: 123, // owner's ID
 		TelegramToken:   "test_token",
 		MemorySize:      10,
 		MessagePerHour:  5,
@@ -36,6 +37,7 @@ func TestHandleUpdate_NewChat(t *testing.T) {
 
 	mockTgClient := &MockTelegramClient{}
 
+	// Create bot model first
 	botModel := &BotModel{
 		Identifier: config.ID,
 		Name:       config.ID,
@@ -43,6 +45,7 @@ func TestHandleUpdate_NewChat(t *testing.T) {
 	err := db.Create(botModel).Error
 	assert.NoError(t, err)
 
+	// Create bot config
 	configModel := &ConfigModel{
 		BotID:           botModel.ID,
 		MemorySize:      config.MemorySize,
@@ -56,12 +59,18 @@ func TestHandleUpdate_NewChat(t *testing.T) {
 	err = db.Create(configModel).Error
 	assert.NoError(t, err)
 
+	// Create bot instance
 	b, err := NewBot(db, config, mockClock, mockTgClient)
 	assert.NoError(t, err)
 
 	testCases := []struct {
-		name       string
-		userID     int64
+		name string
+		// userID 123 is the configured owner; any other ID is a regular user.
+		userID int64
+		// wantSubstr must appear in both the Telegram-sent text and the DB-stored
+		// response. Owners (model:set scope) see the raw API error; regular users
+		// get the generic fallback. Substring (not exact) so the test stays robust
+		// against the SDK's evolving error wording for non-API errors.
 		wantSubstr string
 	}{
 		{
@@ -78,12 +87,14 @@ func TestHandleUpdate_NewChat(t *testing.T) {
 
 	for _, tc := range testCases {
 		t.Run(tc.name, func(t *testing.T) {
+			// Setup mock response expectations for error case to test fallback messages
 			mockTgClient.SendMessageFunc = func(ctx context.Context, params *bot.SendMessageParams) (*models.Message, error) {
 				assert.Equal(t, tc.userID, params.ChatID)
 				assert.Contains(t, params.Text, tc.wantSubstr)
 				return &models.Message{}, nil
 			}
 
+			// Create update with new message
 			update := &models.Update{
 				Message: &models.Message{
 					Chat: models.Chat{ID: tc.userID},
@@ -95,12 +106,15 @@ func TestHandleUpdate_NewChat(t *testing.T) {
 				},
 			}
 
+			// Handle the update
 			b.handleUpdate(context.Background(), nil, update)
 
+			// Verify message was stored
 			var storedMsg Message
 			err := db.Where("chat_id = ? AND user_id = ? AND text = ?", tc.userID, tc.userID, "Hello").First(&storedMsg).Error
 			assert.NoError(t, err)
 
+			// Verify response was stored (most recent assistant message in this chat).
 			var respMsg Message
 			err = db.Where("chat_id = ? AND is_user = ?", tc.userID, false).
 				Order("timestamp DESC").
@@ -112,6 +126,7 @@ func TestHandleUpdate_NewChat(t *testing.T) {
 }
 
 func TestClearChatHistory(t *testing.T) {
+	// Setup
 	db := setupTestDB(t)
 	mockClock := &MockClock{
 		currentTime: time.Now(),
@@ -119,7 +134,7 @@ func TestClearChatHistory(t *testing.T) {
 
 	config := BotConfig{
 		ID:              "test_bot",
-		OwnerTelegramID: 123,
+		OwnerTelegramID: 123, // owner's ID
 		TelegramToken:   "test_token",
 		MemorySize:      10,
 		MessagePerHour:  5,
@@ -131,6 +146,7 @@ func TestClearChatHistory(t *testing.T) {
 
 	mockTgClient := &MockTelegramClient{}
 
+	// Create bot model first
 	botModel := &BotModel{
 		Identifier: config.ID,
 		Name:       config.ID,
@@ -138,6 +154,7 @@ func TestClearChatHistory(t *testing.T) {
 	err := db.Create(botModel).Error
 	assert.NoError(t, err)
 
+	// Create bot config
 	configModel := &ConfigModel{
 		BotID:           botModel.ID,
 		MemorySize:      config.MemorySize,
@@ -151,18 +168,22 @@ func TestClearChatHistory(t *testing.T) {
 	err = db.Create(configModel).Error
 	assert.NoError(t, err)
 
+	// Create bot instance
 	b, err := NewBot(db, config, mockClock, mockTgClient)
 	assert.NoError(t, err)
 
+	// Create test users
 	ownerID := int64(123)
 	adminID := int64(456)
 	regularUserID := int64(789)
 	nonExistentUserID := int64(999)
 	chatID := int64(1000)
 
+	// Create admin role
 	adminRole, err := b.getRoleByName("admin")
 	assert.NoError(t, err)
 
+	// Create admin user
 	adminUser := User{
 		BotID:      b.botID,
 		TelegramID: adminID,
@@ -174,6 +195,7 @@ func TestClearChatHistory(t *testing.T) {
 	err = db.Create(&adminUser).Error
 	assert.NoError(t, err)
 
+	// Create regular user
 	regularRole, err := b.getRoleByName("user")
 	assert.NoError(t, err)
 	regularUser := User{
@@ -187,11 +209,15 @@ func TestClearChatHistory(t *testing.T) {
 	err = db.Create(&regularUser).Error
 	assert.NoError(t, err)
 
+	// Create test messages for each user.
+	// Each user's messages are stored with chat_id == their own user_id, mirroring
+	// how Telegram private DMs work (chat_id == user_id in 1-on-1 bot conversations).
+	// Using a shared artificial chatID here would mask the cross-user delete bug.
 	for _, userID := range []int64{ownerID, adminID, regularUserID} {
 		for i := 0; i < 5; i++ {
 			message := Message{
 				BotID:     b.botID,
-				ChatID:    userID,
+				ChatID:    userID, // per-user chat, not a shared chatID
 				UserID:    userID,
 				Username:  "test",
 				UserRole:  "user",
@@ -204,6 +230,7 @@ func TestClearChatHistory(t *testing.T) {
 		}
 	}
 
+	// Test cases
 	testCases := []struct {
 		name           string
 		currentUserID  int64
@@ -266,7 +293,7 @@ func TestClearChatHistory(t *testing.T) {
 			targetUserID:  adminID,
 			hardDelete:    false,
 			expectedError: true,
-			expectedCount: 5,
+			expectedCount: 5, // Messages should remain
 			expectedMsg:   "Permission denied. Only admins and owners can clear other users' histories.",
 		},
 		{
@@ -275,7 +302,7 @@ func TestClearChatHistory(t *testing.T) {
 			targetUserID:  nonExistentUserID,
 			hardDelete:    false,
 			expectedError: true,
-			expectedCount: 5,
+			expectedCount: 5, // Messages should remain for admin
 			expectedMsg:   "User with ID 999 not found.",
 		},
 		{
@@ -288,23 +315,29 @@ func TestClearChatHistory(t *testing.T) {
 			expectedMsg:   "Chat history for user @regular (ID: 789) has been cleared.",
 		},
 		{
+			// targetChatID scopes the delete to a specific chat; messages in other chats survive.
+			// We seed messages with ChatID == userID (per-user DM), so targeting a different chatID
+			// should leave the user's messages untouched (expectedCount == 5).
 			name:          "Admin clears regular user's history scoped to non-matching chat",
 			currentUserID: adminID,
 			targetUserID:  regularUserID,
-			targetChatID:  int64(9999),
+			targetChatID:  int64(9999), // a chat the user has no messages in
 			hardDelete:    false,
 			expectedError: false,
-			expectedCount: 5,
+			expectedCount: 5, // messages in chat 789 are unaffected
 			expectedMsg:   "Chat history for user @regular (ID: 789) has been cleared.",
 		},
 	}
 
 	for _, tc := range testCases {
 		t.Run(tc.name, func(t *testing.T) {
+			// Reset messages for the test case
 			if tc.name != "Owner hard deletes regular user's history" {
+				// Delete all messages for the target user
 				err = db.Where("user_id = ?", tc.targetUserID).Delete(&Message{}).Error
 				assert.NoError(t, err)
 
+				// Recreate messages for the target user
 				for i := 0; i < 5; i++ {
 					message := Message{
 						BotID:     b.botID,
@@ -321,16 +354,20 @@ func TestClearChatHistory(t *testing.T) {
 				}
 			}
 
+			// Setup mock response expectations
 			var sentMessage string
 			mockTgClient.SendMessageFunc = func(ctx context.Context, params *bot.SendMessageParams) (*models.Message, error) {
 				sentMessage = params.Text
 				return &models.Message{}, nil
 			}
 
+			// Call the clearChatHistory method
 			b.clearChatHistory(context.Background(), chatID, tc.currentUserID, tc.targetUserID, tc.targetChatID, tc.businessConnID, tc.hardDelete)
 
+			// Verify the response message
 			assert.Equal(t, tc.expectedMsg, sentMessage)
 
+			// Count remaining messages for the target user
 			var count int64
 			if tc.hardDelete {
 				db.Unscoped().Model(&Message{}).Where("user_id = ? AND chat_id = ?", tc.targetUserID, chatID).Count(&count)
@@ -343,6 +380,7 @@ func TestClearChatHistory(t *testing.T) {
 }
 
 func TestStatsCommand(t *testing.T) {
+	// Setup
 	db := setupTestDB(t)
 	mockClock := &MockClock{
 		currentTime: time.Now(),
@@ -350,7 +388,7 @@ func TestStatsCommand(t *testing.T) {
 
 	config := BotConfig{
 		ID:              "test_bot",
-		OwnerTelegramID: 123,
+		OwnerTelegramID: 123, // owner's ID
 		TelegramToken:   "test_token",
 		MemorySize:      10,
 		MessagePerHour:  5,
@@ -362,6 +400,7 @@ func TestStatsCommand(t *testing.T) {
 
 	mockTgClient := &MockTelegramClient{}
 
+	// Create bot model first
 	botModel := &BotModel{
 		Identifier: config.ID,
 		Name:       config.ID,
@@ -369,6 +408,7 @@ func TestStatsCommand(t *testing.T) {
 	err := db.Create(botModel).Error
 	assert.NoError(t, err)
 
+	// Create bot config
 	configModel := &ConfigModel{
 		BotID:           botModel.ID,
 		MemorySize:      config.MemorySize,
@@ -382,17 +422,21 @@ func TestStatsCommand(t *testing.T) {
 	err = db.Create(configModel).Error
 	assert.NoError(t, err)
 
+	// Create bot instance
 	b, err := NewBot(db, config, mockClock, mockTgClient)
 	assert.NoError(t, err)
 
+	// Create test users
 	ownerID := int64(123)
 	adminID := int64(456)
 	regularUserID := int64(789)
 	chatID := int64(1000)
 
+	// Create admin role
 	adminRole, err := b.getRoleByName("admin")
 	assert.NoError(t, err)
 
+	// Create admin user
 	adminUser := User{
 		BotID:      b.botID,
 		TelegramID: adminID,
@@ -404,6 +448,7 @@ func TestStatsCommand(t *testing.T) {
 	err = db.Create(&adminUser).Error
 	assert.NoError(t, err)
 
+	// Create regular user
 	regularRole, err := b.getRoleByName("user")
 	assert.NoError(t, err)
 	regularUser := User{
@@ -417,8 +462,10 @@ func TestStatsCommand(t *testing.T) {
 	err = db.Create(&regularUser).Error
 	assert.NoError(t, err)
 
+	// Create test messages for each user
 	for _, userID := range []int64{ownerID, adminID, regularUserID} {
 		for i := 0; i < 5; i++ {
+			// User message
 			userMessage := Message{
 				BotID:     b.botID,
 				ChatID:    chatID,
@@ -432,6 +479,7 @@ func TestStatsCommand(t *testing.T) {
 			err = db.Create(&userMessage).Error
 			assert.NoError(t, err)
 
+			// Bot response
 			botMessage := Message{
 				BotID:     b.botID,
 				ChatID:    chatID,
@@ -447,6 +495,7 @@ func TestStatsCommand(t *testing.T) {
 		}
 	}
 
+	// Test cases
 	testCases := []struct {
 		name           string
 		command        string
@@ -515,12 +564,14 @@ func TestStatsCommand(t *testing.T) {
 
 	for _, tc := range testCases {
 		t.Run(tc.name, func(t *testing.T) {
+			// Setup mock response expectations
 			var sentMessage string
 			mockTgClient.SendMessageFunc = func(ctx context.Context, params *bot.SendMessageParams) (*models.Message, error) {
 				sentMessage = params.Text
 				return &models.Message{}, nil
 			}
 
+			// Create update with command
 			update := &models.Update{
 				Message: &models.Message{
 					Chat: models.Chat{ID: chatID},
@@ -533,19 +584,22 @@ func TestStatsCommand(t *testing.T) {
 						{
 							Type:   "bot_command",
 							Offset: 0,
-							Length: 6,
+							Length: 6, // Length of "/stats"
 						},
 					},
 				},
 			}
 
+			// Handle the update
 			b.handleUpdate(context.Background(), nil, update)
 
+			// Verify the response message contains the expected text
 			assert.Contains(t, sentMessage, tc.expectedMsg)
 		})
 	}
 }
 
+// Helper function to get username by ID for test
 func getUsernameByID(id int64) string {
 	switch id {
 	case 123:
@@ -565,11 +619,13 @@ func setupTestDB(t *testing.T) *gorm.DB {
 		t.Fatalf("Failed to open test database: %v", err)
 	}
 
+	// AutoMigrate the models
 	err = db.AutoMigrate(&BotModel{}, &ConfigModel{}, &Message{}, &User{}, &Role{}, &Scope{})
 	if err != nil {
 		t.Fatalf("Failed to migrate database schema: %v", err)
 	}
 
+	// Create default roles and scopes
 	err = createDefaultRoles(db)
 	if err != nil {
 		t.Fatalf("Failed to create default roles: %v", err)
@@ -581,6 +637,8 @@ func setupTestDB(t *testing.T) *gorm.DB {
 	return db
 }
 
+// setupBotForTest creates a minimal Bot instance backed by an in-memory DB.
+// It follows the same pattern as the existing handler tests to avoid duplication.
 func setupBotForTest(t *testing.T, ownerID int64) (*Bot, *MockTelegramClient) {
 	t.Helper()
 	db := setupTestDB(t)
@@ -615,9 +673,13 @@ func setupBotForTest(t *testing.T, ownerID int64) (*Bot, *MockTelegramClient) {
 	return b, mockTgClient
 }
 
+// TestAnthropicErrorResponse verifies that model-deprecation errors surface actionable
+// details only to admin/owner, and that regular users and non-model errors always get
+// the generic fallback.
 func TestAnthropicErrorResponse(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
 	b, _ := setupBotForTest(t, 123)
 
+	// Create admin user
 	adminRole, err := b.getRoleByName("admin")
 	assert.NoError(t, err)
 	assert.NoError(t, b.db.Create(&User{
@@ -625,6 +687,7 @@ func TestAnthropicErrorResponse(t *testing.T) { //NOSONAR go:S100 -- underscore
 		RoleID: adminRole.ID, Role: adminRole,
 	}).Error)
 
+	// Create regular user
 	userRole, err := b.getRoleByName("user")
 	assert.NoError(t, err)
 	assert.NoError(t, b.db.Create(&User{
@@ -662,6 +725,8 @@ func TestAnthropicErrorResponse(t *testing.T) { //NOSONAR go:S100 -- underscore
 			wantMissing: "/set_model",
 		},
 		{
+			// Non-model errors (network, plain errors, API errors other than 404)
+			// surface to anyone with model:set scope so admins/owners can diagnose.
 			name:        "owner receives elevated detail for non-API error",
 			err:         otherErr,
 			userID:      123,
@@ -669,6 +734,8 @@ func TestAnthropicErrorResponse(t *testing.T) { //NOSONAR go:S100 -- underscore
 			wantMissing: "I'm sorry",
 		},
 		{
+			// Regular users keep getting the generic fallback for any non-model error
+			// to avoid leaking internal details.
 			name:        "regular user receives generic message for non-model error",
 			err:         otherErr,
 			userID:      789,
@@ -688,9 +755,12 @@ func TestAnthropicErrorResponse(t *testing.T) { //NOSONAR go:S100 -- underscore
 	}
 }
 
+// TestSetModelCommand verifies that /set_model enforces permissions, validates input,
+// updates the model in memory, and persists the change to the config file on disk.
 func TestSetModelCommand(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
 	b, mockTgClient := setupBotForTest(t, 123)
 
+	// Point the config at a temporary file so PersistModel can write to disk.
 	tempDir, err := os.MkdirTemp("", "set_model_cmd_test")
 	assert.NoError(t, err)
 	defer func() { _ = os.RemoveAll(tempDir) }()
@@ -700,6 +770,7 @@ func TestSetModelCommand(t *testing.T) { //NOSONAR go:S100 -- underscore separat
 	assert.NoError(t, os.WriteFile(configPath, []byte(initialJSON), 0600))
 	b.config.ConfigFilePath = configPath
 
+	// Create admin and regular users
 	adminRole, err := b.getRoleByName("admin")
 	assert.NoError(t, err)
 	assert.NoError(t, b.db.Create(&User{
@@ -715,6 +786,8 @@ func TestSetModelCommand(t *testing.T) { //NOSONAR go:S100 -- underscore separat
 
 	chatID := int64(1000)
 
+	// Seed chat 1000 with a prior message so isNewChatFlag is false for all subtests.
+	// Commands are only processed in the non-new-chat branch of handleUpdate.
 	assert.NoError(t, b.db.Create(&Message{
 		BotID: b.botID, ChatID: chatID, UserID: 789, Username: "regular",
 		UserRole: "user", Text: "hello", IsUser: true,
@@ -777,6 +850,7 @@ func TestSetModelCommand(t *testing.T) { //NOSONAR go:S100 -- underscore separat
 		})
 	}
 
+	// Verify the successful update took effect in memory and on disk.
 	t.Run("model change persisted in memory and on disk", func(t *testing.T) {
 		assert.Equal(t, "claude-sonnet-4-6", string(b.config.Model))
 		data, err := os.ReadFile(configPath)
@@ -785,10 +859,12 @@ func TestSetModelCommand(t *testing.T) { //NOSONAR go:S100 -- underscore separat
 	})
 }
 
+// TestHasScope verifies that scope checks honour role assignments and the owner bypass.
 func TestHasScope(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
 	const ownerID int64 = 100
 	b, _ := setupBotForTest(t, ownerID)
 
+	// Admin user
 	adminRole, err := b.getRoleByName("admin")
 	assert.NoError(t, err)
 	assert.NoError(t, b.db.Create(&User{
@@ -796,6 +872,7 @@ func TestHasScope(t *testing.T) { //NOSONAR go:S100 -- underscore separation is
 		RoleID: adminRole.ID, Role: adminRole,
 	}).Error)
 
+	// Regular user
 	userRole, err := b.getRoleByName("user")
 	assert.NoError(t, err)
 	assert.NoError(t, b.db.Create(&User{

intake_buffer.go

@@ -1,129 +0,0 @@
-package main
-
-import (
-	"context"
-	"time"
-)
-
-// pendingIntake holds a chat's coalescing window. The buffered message bodies
-// are deliberately absent: screenIncomingMessage has already persisted each
-// message to the database and to chat memory by the time it is buffered, so the
-// flushed turn picks them all up from memory. What is kept here is the metadata
-// the turn needs, always refreshed to the most recent message in the batch.
-type pendingIntake struct {
-	chatID, userID                              int64
-	username, firstName, lastName, languageCode string
-	isPremium                                   bool
-	messageTime                                 int
-	businessConnectionID                        string
-	allEmojiOnly                                bool
-	count                                       int
-	seq                                         uint64
-	timer                                       *time.Timer
-}
-
-// bufferIntake holds a text message for the configured quiet window instead of
-// dispatching a turn immediately, resetting the window on each new message.
-// Rapid follow-ups therefore produce one reply rather than one per message.
-func (b *Bot) bufferIntake(
-	ctx context.Context,
-	chatID, userID int64,
-	username, firstName, lastName string,
-	isPremium bool,
-	languageCode string,
-	messageTime int,
-	businessConnectionID string,
-	isEmojiOnly bool,
-) {
-	window := b.config.DebounceWindow()
-
-	b.intakeBuffersMu.Lock()
-	defer b.intakeBuffersMu.Unlock()
-
-	pending, exists := b.intakeBuffers[chatID]
-	if !exists {
-		b.intakeSeq++
-		pending = &pendingIntake{seq: b.intakeSeq, allEmojiOnly: true}
-		b.intakeBuffers[chatID] = pending
-	}
-
-	// Reply metadata tracks the most recent message in the batch.
-	pending.chatID = chatID
-	pending.userID = userID
-	pending.username = username
-	pending.firstName = firstName
-	pending.lastName = lastName
-	pending.isPremium = isPremium
-	pending.languageCode = languageCode
-	pending.messageTime = messageTime
-	pending.businessConnectionID = businessConnectionID
-	pending.allEmojiOnly = pending.allEmojiOnly && isEmojiOnly
-	pending.count++
-
-	if pending.timer != nil {
-		pending.timer.Stop()
-	}
-	seq := pending.seq
-	pending.timer = time.AfterFunc(window, func() {
-		b.flushIntake(ctx, chatID, seq)
-	})
-}
-
-// flushIntake dispatches the coalesced turn for a chat. seq guards against a
-// timer that had already fired before its Stop call landed: a stale goroutine
-// would otherwise flush a buffer belonging to a later batch.
-func (b *Bot) flushIntake(ctx context.Context, chatID int64, seq uint64) {
-	b.intakeBuffersMu.Lock()
-	pending, exists := b.intakeBuffers[chatID]
-	if !exists || pending.seq != seq {
-		b.intakeBuffersMu.Unlock()
-		return
-	}
-	delete(b.intakeBuffers, chatID)
-	captured := *pending
-	b.intakeBuffersMu.Unlock()
-
-	if captured.count > 1 {
-		InfoLogger.Printf("[%s] intake flush: coalesced %d messages into one turn for chat %d",
-			b.config.ID, captured.count, chatID)
-	}
-
-	b.respondToChat(
-		ctx, chatID, captured.userID, captured.allEmojiOnly,
-		captured.username, captured.firstName, captured.lastName,
-		captured.isPremium, captured.languageCode, captured.messageTime,
-		captured.businessConnectionID,
-	)
-}
-
-// cancelIntake drops a chat's pending buffer without dispatching, returning how
-// many messages were discarded.
-//
-// This is the fix for the class of bug in openclaw/openclaw#51046, where a stop
-// command aborted the running turn but left the debounce buffer armed, so the
-// timer fired afterwards and started the very turn the user had just cancelled.
-// Here the stakes are higher than a stray turn: /clear and /clear_hard delete
-// chat memory, and a surviving buffer would repopulate it moments later with
-// content the user asked to have removed.
-func (b *Bot) cancelIntake(chatID int64) int {
-	b.intakeBuffersMu.Lock()
-	defer b.intakeBuffersMu.Unlock()
-
-	pending, exists := b.intakeBuffers[chatID]
-	if !exists {
-		return 0
-	}
-	if pending.timer != nil {
-		pending.timer.Stop()
-	}
-	delete(b.intakeBuffers, chatID)
-	return pending.count
-}
-
-// hasPendingIntake reports whether a chat currently holds a buffered batch.
-func (b *Bot) hasPendingIntake(chatID int64) bool {
-	b.intakeBuffersMu.Lock()
-	defer b.intakeBuffersMu.Unlock()
-	_, exists := b.intakeBuffers[chatID]
-	return exists
-}

intake_buffer_test.go

@@ -1,176 +0,0 @@
-package main
-
-import (
-	"context"
-	"testing"
-	"time"
-
-	"github.com/go-telegram/bot"
-	"github.com/go-telegram/bot/models"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-// bufferOnly parks a message in the intake buffer without letting the flush run,
-// by using a window long enough that no test waits it out.
-const bufferOnly = 10 * time.Second
-
-func bufferText(b *Bot, chatID int64, isEmojiOnly bool) {
-	b.bufferIntake(context.Background(), chatID, 555,
-		"tester", "Test", "User", false, "en", int(time.Now().Unix()), "", isEmojiOnly)
-}
-
-func TestBufferIntake_CoalescesIntoSingleTurn(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
-	b, _ := setupBotForTest(t, 123)
-	b.config.DebounceMs = int(bufferOnly / time.Millisecond)
-
-	// The burst this whole feature exists for: one real question, then filler.
-	for i := 0; i < 5; i++ {
-		bufferText(b, 900, false)
-	}
-
-	b.intakeBuffersMu.Lock()
-	defer b.intakeBuffersMu.Unlock()
-	assert.Len(t, b.intakeBuffers, 1, "rapid messages must share one buffer entry")
-	assert.Equal(t, 5, b.intakeBuffers[900].count, "all five messages land in the same batch")
-}
-
-// Separate chats must not share a window; one user's burst cannot delay another's.
-func TestBufferIntake_IsolatesChats(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
-	b, _ := setupBotForTest(t, 123)
-	b.config.DebounceMs = int(bufferOnly / time.Millisecond)
-
-	bufferText(b, 910, false)
-	bufferText(b, 911, false)
-	bufferText(b, 911, false)
-
-	b.intakeBuffersMu.Lock()
-	defer b.intakeBuffersMu.Unlock()
-	assert.Equal(t, 1, b.intakeBuffers[910].count)
-	assert.Equal(t, 2, b.intakeBuffers[911].count)
-}
-
-func TestBufferIntake_ResetsWindowAndKeepsLatestMetadata(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
-	b, _ := setupBotForTest(t, 123)
-	b.config.DebounceMs = int(bufferOnly / time.Millisecond)
-
-	b.bufferIntake(context.Background(), 901, 1, "first", "First", "", false, "en", 1000, "", true)
-	b.bufferIntake(context.Background(), 901, 2, "second", "Second", "", true, "de", 2000, "biz-42", false)
-
-	b.intakeBuffersMu.Lock()
-	defer b.intakeBuffersMu.Unlock()
-	pending := b.intakeBuffers[901]
-	require.NotNil(t, pending)
-
-	assert.Equal(t, 2, pending.count)
-	// OpenClaw semantics: reply metadata follows the most recent message.
-	assert.Equal(t, "second", pending.username)
-	assert.Equal(t, int64(2), pending.userID)
-	assert.Equal(t, "de", pending.languageCode)
-	assert.Equal(t, 2000, pending.messageTime)
-	assert.Equal(t, "biz-42", pending.businessConnectionID)
-	assert.True(t, pending.isPremium)
-	// One non-emoji message makes the whole coalesced turn non-emoji.
-	assert.False(t, pending.allEmojiOnly)
-}
-
-func TestBufferIntake_AllEmojiOnlySurvivesWhenEveryMessageIsEmoji(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
-	b, _ := setupBotForTest(t, 123)
-	b.config.DebounceMs = int(bufferOnly / time.Millisecond)
-
-	bufferText(b, 902, true)
-	bufferText(b, 902, true)
-
-	b.intakeBuffersMu.Lock()
-	defer b.intakeBuffersMu.Unlock()
-	assert.True(t, b.intakeBuffers[902].allEmojiOnly)
-}
-
-func TestCancelIntake_DiscardsPendingBatch(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
-	b, _ := setupBotForTest(t, 123)
-	b.config.DebounceMs = int(bufferOnly / time.Millisecond)
-
-	bufferText(b, 903, false)
-	bufferText(b, 903, false)
-	require.True(t, b.hasPendingIntake(903))
-
-	assert.Equal(t, 2, b.cancelIntake(903), "cancel reports how many messages it discarded")
-	assert.False(t, b.hasPendingIntake(903))
-	assert.Equal(t, 0, b.cancelIntake(903), "cancelling an empty chat is a no-op")
-}
-
-// A cancelled buffer must never dispatch afterwards. This is the openclaw#51046
-// shape: the timer had already been armed when the cancel landed.
-func TestCancelIntake_TimerDoesNotFireAfterCancel(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
-	b, _ := setupBotForTest(t, 123)
-	b.config.DebounceMs = 20
-
-	bufferText(b, 904, false)
-	b.cancelIntake(904)
-
-	time.Sleep(80 * time.Millisecond)
-	assert.False(t, b.hasPendingIntake(904), "cancelled buffer must not resurrect")
-}
-
-// A stale timer from a cancelled batch must not flush a newer batch early.
-func TestFlushIntake_IgnoresSupersededSequence(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
-	b, _ := setupBotForTest(t, 123)
-	b.config.DebounceMs = int(bufferOnly / time.Millisecond)
-
-	bufferText(b, 905, false)
-	b.intakeBuffersMu.Lock()
-	staleSeq := b.intakeBuffers[905].seq
-	b.intakeBuffersMu.Unlock()
-
-	b.cancelIntake(905)
-	bufferText(b, 905, false) // new batch, new sequence
-
-	// The old timer firing late must not consume the new batch.
-	b.flushIntake(context.Background(), 905, staleSeq)
-	assert.True(t, b.hasPendingIntake(905), "superseded flush must leave the newer batch armed")
-}
-
-func TestClearChatHistory_CancelsPendingIntake(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
-	b, mockTg := setupBotForTest(t, 123)
-	b.config.DebounceMs = int(bufferOnly / time.Millisecond)
-	mockTg.SendMessageFunc = func(_ context.Context, _ *bot.SendMessageParams) (*models.Message, error) {
-		return &models.Message{}, nil
-	}
-
-	const chatID int64 = 906
-	bufferText(b, chatID, false)
-	require.True(t, b.hasPendingIntake(chatID))
-
-	b.clearChatHistory(context.Background(), chatID, 123, 0, 0, "", false)
-
-	assert.False(t, b.hasPendingIntake(chatID),
-		"clearing history must disarm the buffer, or deleted messages get replayed into memory")
-}
-
-func TestDebounceWindow(t *testing.T) {
-	cases := []struct {
-		name string
-		ms   int
-		want time.Duration
-	}{
-		{"unset disables debouncing", 0, 0},
-		{"negative disables debouncing", -1, 0},
-		{"positive converts to duration", 2500, 2500 * time.Millisecond},
-	}
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			c := BotConfig{DebounceMs: tc.ms}
-			assert.Equal(t, tc.want, c.DebounceWindow())
-		})
-	}
-}
-
-func TestCacheHistoryEnabled_DefaultsOn(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
-	assert.True(t, (&BotConfig{}).CacheHistoryEnabled(), "cache_history defaults to enabled")
-
-	off := false
-	assert.False(t, (&BotConfig{CacheHistory: &off}).CacheHistoryEnabled())
-
-	on := true
-	assert.True(t, (&BotConfig{CacheHistory: &on}).CacheHistoryEnabled())
-}

logger.go

@@ -5,13 +5,23 @@ import (
 	"os"
 )
 
+// For log management, use journalctl commands:
+//   - View logs: journalctl -u telegram-bot
+//   - Follow logs: journalctl -u telegram-bot -f
+//   - View errors: journalctl -u telegram-bot -p err
+// Refer to the documentation for details on systemd unit setup.
+
+// Initialize loggers for informational and error messages.
 var (
 	InfoLogger  *log.Logger
 	ErrorLogger *log.Logger
 )
 
+// initLoggers sets up separate loggers for stdout and stderr.
 func initLoggers() {
+	// InfoLogger writes to stdout with specific flags.
 	InfoLogger = log.New(os.Stdout, "INFO: ", log.Ldate|log.Ltime|log.Lshortfile)
 
+	// ErrorLogger writes to stderr with specific flags.
 	ErrorLogger = log.New(os.Stderr, "ERROR: ", log.Ldate|log.Ltime|log.Lshortfile)
 }

main.go

@@ -8,30 +8,38 @@ import (
 )
 
 func main() {
+	// Initialize custom loggers
 	initLoggers()
 
+	// Log the start of the application
 	InfoLogger.Println("Starting Telegram Bot Application")
 
+	// Initialize database
 	db, err := initDB()
 	if err != nil {
 		ErrorLogger.Fatalf("Error initializing database: %v", err)
 	}
 
+	// Load all bot configurations
 	configs, err := loadAllConfigs("config")
 	if err != nil {
 		ErrorLogger.Fatalf("Error loading configurations: %v", err)
 	}
 
+	// Create a WaitGroup to manage goroutines
 	var wg sync.WaitGroup
 
+	// Set up context with cancellation
 	ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt)
 	defer cancel()
 
+	// Initialize and start each bot
 	for _, config := range configs {
 		wg.Add(1)
 		go func(cfg BotConfig) {
 			defer wg.Done()
 
+			// Create Bot instance without TelegramClient initially
 			realClock := RealClock{}
 			bot, err := NewBot(db, cfg, realClock, nil)
 			if err != nil {
@@ -39,14 +47,17 @@ func main() {
 				return
 			}
 
+			// Start the bot in a separate goroutine
 			go bot.Start(ctx)
 
+			// Keep the bot running until the context is cancelled
 			<-ctx.Done()
 
 			InfoLogger.Printf("Bot %s stopped", cfg.ID)
 		}(config)
 	}
 
+	// Wait for all bots to finish
 	wg.Wait()
 
 	InfoLogger.Println("All bots have stopped. Exiting application.")

models.go

@@ -8,10 +8,10 @@ import (
 
 type BotModel struct {
 	gorm.Model
-	Identifier string `gorm:"uniqueIndex"`
+	Identifier string `gorm:"uniqueIndex"` // Renamed from ID to Identifier
 	Name       string
 	Configs    []ConfigModel `gorm:"foreignKey:BotID;constraint:OnDelete:CASCADE"`
-	Users      []User        `gorm:"foreignKey:BotID;constraint:OnDelete:CASCADE"`
+	Users      []User        `gorm:"foreignKey:BotID;constraint:OnDelete:CASCADE"` // Associated users
 	Messages   []Message     `gorm:"foreignKey:BotID;constraint:OnDelete:CASCADE"`
 }
 
@@ -22,36 +22,43 @@ type ConfigModel struct {
 	MessagePerHour  int    `json:"messages_per_hour"`
 	MessagePerDay   int    `json:"messages_per_day"`
 	TempBanDuration string `json:"temp_ban_duration"`
-	SystemPrompts   string `json:"system_prompts"`
+	SystemPrompts   string `json:"system_prompts"` // Consider JSON string or separate table
 	TelegramToken   string `json:"telegram_token"`
 	Active          bool   `json:"active"`
 }
 
 type Message struct {
 	gorm.Model
-	BotID          uint   `gorm:"index"`
-	ChatID         int64  `gorm:"index"`
-	UserID         int64  `gorm:"index"`
-	Username       string `gorm:"index"`
-	UserRole       string
+	BotID          uint      `gorm:"index"`
+	ChatID         int64     `gorm:"index"`
+	UserID         int64     `gorm:"index"`
+	Username       string    `gorm:"index"`
+	UserRole       string    // Store the role as a string
 	Text           string    `gorm:"type:text"`
 	Timestamp      time.Time `gorm:"index"`
 	IsUser         bool
 	StickerFileID  string
 	StickerPNGFile string
-	StickerEmoji   string
-	DeletedAt      gorm.DeletedAt `gorm:"index"`
-	AnsweredOn     *time.Time     `gorm:"index"`
-	ImageFileIDs   []string       `gorm:"type:text;serializer:json"`
-	FilesCleanedAt *time.Time     `gorm:"index"`
+	StickerEmoji   string         // Store the emoji associated with the sticker
+	DeletedAt      gorm.DeletedAt `gorm:"index"` // Add soft delete field
+	AnsweredOn     *time.Time     `gorm:"index"` // Tracks when a user message was answered (NULL for assistant messages and unanswered user messages)
+	// ImageFileIDs holds Anthropic Files API file_ids for photos attached to this turn.
+	// Plural for albums (Telegram media_group), single-element for one photo.
+	ImageFileIDs []string `gorm:"type:text;serializer:json"`
+	// FilesCleanedAt is set after a cleanup job deletes the corresponding files from
+	// Anthropic's side. NULL means files are still alive on Anthropic.
+	// Combined with DeletedAt this lets a reconciliation job find rows whose files
+	// are pending cleanup vs rows whose files have already been removed.
+	FilesCleanedAt *time.Time `gorm:"index"`
 }
 
 type ChatMemory struct {
 	Messages             []Message
 	Size                 int
-	BusinessConnectionID string
+	BusinessConnectionID string // New field to store the business connection ID
 }
 
+// Scope name constants — used in DB seeding, hasScope checks, and tests.
 const (
 	ScopeStatsViewOwn        = "stats:view:own"
 	ScopeStatsViewAny        = "stats:view:any"
@@ -77,14 +84,16 @@ type Role struct {
 
 type User struct {
 	gorm.Model
-	BotID      uint  `gorm:"uniqueIndex:idx_user_bot;index"`
-	TelegramID int64 `gorm:"uniqueIndex:idx_user_bot;not null"`
+	BotID      uint  `gorm:"uniqueIndex:idx_user_bot;index"`    // Foreign key to BotModel
+	TelegramID int64 `gorm:"uniqueIndex:idx_user_bot;not null"` // Unique per (telegram_id, bot_id) pair
 	Username   string
 	RoleID     uint
 	Role       Role `gorm:"foreignKey:RoleID"`
-	IsOwner    bool `gorm:"default:false"`
+	IsOwner    bool `gorm:"default:false"` // Indicates if the user is the owner
 }
 
+// idx_user_bot is a composite unique index on (bot_id, telegram_id),
+// allowing the same Telegram user to be registered independently on each bot.
 func (User) TableName() string {
 	return "users"
 }

prompt_cache_test.go

@@ -1,116 +0,0 @@
-package main
-
-import (
-	"testing"
-
-	"github.com/anthropics/anthropic-sdk-go"
-	"github.com/anthropics/anthropic-sdk-go/packages/param"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-func TestMarkTrailingCacheBreakpoint(t *testing.T) {
-	t.Run("marks the final text block of the final turn", func(t *testing.T) {
-		msgs := []anthropic.BetaMessageParam{
-			anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("older")),
-			anthropic.NewBetaUserMessage(
-				anthropic.NewBetaTextBlock("first"),
-				anthropic.NewBetaTextBlock("last"),
-			),
-		}
-
-		markTrailingCacheBreakpoint(msgs)
-
-		last := msgs[1].Content[1].OfText
-		require.NotNil(t, last)
-		assert.False(t, param.IsOmitted(last.CacheControl),
-			"the trailing block carries the breakpoint")
-
-		// Everything earlier stays unmarked: one breakpoint, not one per block.
-		assert.True(t, param.IsOmitted(msgs[1].Content[0].OfText.CacheControl))
-		assert.True(t, param.IsOmitted(msgs[0].Content[0].OfText.CacheControl))
-	})
-
-	t.Run("marks a trailing image block", func(t *testing.T) {
-		msgs := []anthropic.BetaMessageParam{
-			anthropic.NewBetaUserMessage(
-				anthropic.NewBetaImageBlock(anthropic.BetaFileImageSourceParam{FileID: "file_1"}),
-			),
-		}
-
-		markTrailingCacheBreakpoint(msgs)
-
-		require.NotNil(t, msgs[0].Content[0].OfImage)
-		assert.False(t, param.IsOmitted(msgs[0].Content[0].OfImage.CacheControl))
-	})
-
-	t.Run("tolerates empty input", func(t *testing.T) {
-		assert.NotPanics(t, func() { markTrailingCacheBreakpoint(nil) })
-		assert.NotPanics(t, func() {
-			markTrailingCacheBreakpoint([]anthropic.BetaMessageParam{{}})
-		})
-	})
-}
-
-func TestPrepareContextMessages_CacheHistoryToggle(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
-	b, _ := setupBotForTest(t, 123)
-	memory := &ChatMemory{
-		Messages: []Message{
-			{IsUser: true, Text: "hello"},
-			{IsUser: false, Text: "hi there"},
-		},
-		Size: 10,
-	}
-
-	t.Run("enabled by default", func(t *testing.T) {
-		msgs := b.prepareContextMessages(memory)
-		require.Len(t, msgs, 2)
-		assert.False(t, param.IsOmitted(msgs[1].Content[0].OfText.CacheControl))
-	})
-
-	t.Run("opt-out leaves history unmarked", func(t *testing.T) {
-		off := false
-		b.config.CacheHistory = &off
-		defer func() { b.config.CacheHistory = nil }()
-
-		msgs := b.prepareContextMessages(memory)
-		require.Len(t, msgs, 2)
-		assert.True(t, param.IsOmitted(msgs[1].Content[0].OfText.CacheControl))
-	})
-}
-
-func TestValidateConfig_DebounceMs(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
-	base := func(ms int) *BotConfig {
-		return &BotConfig{
-			ID:             "b",
-			TelegramToken:  "t",
-			Model:          "claude-sonnet-4-6",
-			MessagePerHour: 1,
-			MessagePerDay:  1,
-			DebounceMs:     ms,
-		}
-	}
-
-	cases := []struct {
-		name    string
-		ms      int
-		wantErr bool
-	}{
-		{"omitted is valid", 0, false},
-		{"typical chat window is valid", 2500, false},
-		{"at the ceiling is valid", maxDebounceMs, false},
-		{"negative is rejected", -1, true},
-		{"above the ceiling is rejected", maxDebounceMs + 1, true},
-	}
-
-	for _, tc := range cases {
-		t.Run(tc.name, func(t *testing.T) {
-			err := validateConfig(base(tc.ms), map[string]bool{}, map[string]bool{})
-			if tc.wantErr {
-				assert.Error(t, err)
-				return
-			}
-			assert.NoError(t, err)
-		})
-	}
-}

rate_limiter.go

@@ -33,20 +33,26 @@ func (b *Bot) checkRateLimits(userID int64) bool {
 
 	now := limiter.clock.Now()
 
+	// Check if the user is currently banned
 	if now.Before(limiter.banUntil) {
 		return false
 	}
 
+	// Reset hourly limiter if an hour has passed since the last reset
 	if now.Sub(limiter.lastHourlyReset) >= time.Hour {
 		limiter.hourlyLimiter = rate.NewLimiter(rate.Every(time.Hour/time.Duration(b.config.MessagePerHour)), b.config.MessagePerHour)
 		limiter.lastHourlyReset = now
 	}
 
+	// Reset daily limiter if 24 hours have passed since the last reset
 	if now.Sub(limiter.lastDailyReset) >= 24*time.Hour {
 		limiter.dailyLimiter = rate.NewLimiter(rate.Every(24*time.Hour/time.Duration(b.config.MessagePerDay)), b.config.MessagePerDay)
 		limiter.lastDailyReset = now
 	}
 
+	// Check if the message exceeds rate limits.
+	// Reserve from both limiters first, then cancel both if either is over budget.
+	// This prevents consuming a token from one limiter when the other rejects.
 	dailyRes := limiter.dailyLimiter.ReserveN(now, 1)
 	hourlyRes := limiter.hourlyLimiter.ReserveN(now, 1)
 	if dailyRes.DelayFrom(now) > 0 || hourlyRes.DelayFrom(now) > 0 {
@@ -54,6 +60,7 @@ func (b *Bot) checkRateLimits(userID int64) bool {
 		hourlyRes.CancelAt(now)
 		banDuration, err := time.ParseDuration(b.config.TempBanDuration)
 		if err != nil {
+			// If parsing fails, default to a 24-hour ban
 			banDuration = 24 * time.Hour
 		}
 		limiter.banUntil = now.Add(banDuration)

rate_limiter_test.go

@@ -5,22 +5,27 @@ import (
 	"time"
 )
 
+// TestCheckRateLimits tests the checkRateLimits method of the Bot.
+// It verifies that users are allowed or denied based on their message rates.
 func TestCheckRateLimits(t *testing.T) {
+	// Create a mock clock starting at a fixed time
 	mockClock := &MockClock{
 		currentTime: time.Date(2023, 10, 1, 0, 0, 0, 0, time.UTC),
 	}
 
+	// Create a mock configuration with reduced timeframes for testing
 	config := BotConfig{
 		ID:              "bot1",
 		MemorySize:      10,
-		MessagePerHour:  5,
-		MessagePerDay:   10,
-		TempBanDuration: "1m",
+		MessagePerHour:  5,    // Allow 5 messages per hour
+		MessagePerDay:   10,   // Allow 10 messages per day
+		TempBanDuration: "1m", // Temporary ban duration of 1 minute for testing
 		SystemPrompts:   make(map[string]string),
 		TelegramToken:   "YOUR_TELEGRAM_BOT_TOKEN",
 		OwnerTelegramID: 123456789,
 	}
 
+	// Initialize the Bot with mock data and MockClock
 	bot := &Bot{
 		config:       config,
 		userLimiters: make(map[int64]*userLimiter),
@@ -29,39 +34,52 @@ func TestCheckRateLimits(t *testing.T) {
 
 	userID := int64(12345)
 
+	// Helper function to simulate message sending
 	sendMessage := func() bool {
 		return bot.checkRateLimits(userID)
 	}
 
+	// Send 5 messages within the hourly limit
 	for i := 0; i < config.MessagePerHour; i++ {
 		if !sendMessage() {
 			t.Errorf("Expected message %d to be allowed", i+1)
 		}
 	}
 
+	// 6th message should exceed the hourly limit and trigger a ban
 	if sendMessage() {
 		t.Errorf("Expected message to be denied due to hourly limit exceeded")
 	}
 
+	// Attempt to send another message immediately, should still be banned
 	if sendMessage() {
 		t.Errorf("Expected message to be denied while user is banned")
 	}
 
-	mockClock.Advance(time.Minute)
+	// Fast-forward time by TempBanDuration to lift the ban
+	mockClock.Advance(time.Minute) // Banned for 1 minute
 
-	mockClock.Advance(time.Hour)
+	// Advance time to allow hourly limiter to replenish
+	mockClock.Advance(time.Hour) // Advance by 1 hour
 
+	// Send another message, should be allowed now
 	if !sendMessage() {
 		t.Errorf("Expected message to be allowed after ban duration")
 	}
 
+	// Send additional messages to reach the daily limit
 	for i := 0; i < config.MessagePerDay-config.MessagePerHour-1; i++ {
 		if !sendMessage() {
 			t.Errorf("Expected message %d to be allowed towards daily limit", i+1)
 		}
 	}
 
+	// Attempt to exceed the daily limit
 	if sendMessage() {
 		t.Errorf("Expected message to be denied due to daily limit exceeded")
 	}
 }
+
+// To ensure thread safety and avoid race conditions during testing,
+// you can run the tests with the `-race` flag:
+// go test -race -v

telegram_client.go

@@ -1,3 +1,4 @@
+// telegram_client.go
 package main
 
 import (
@@ -7,10 +8,10 @@ import (
 	"github.com/go-telegram/bot/models"
 )
 
+// TelegramClient defines the methods required from the Telegram bot.
 type TelegramClient interface {
 	SendMessage(ctx context.Context, params *bot.SendMessageParams) (*models.Message, error)
 	SendAudio(ctx context.Context, params *bot.SendAudioParams) (*models.Message, error)
-	SendChatAction(ctx context.Context, params *bot.SendChatActionParams) (bool, error)
 	SetMyCommands(ctx context.Context, params *bot.SetMyCommandsParams) (bool, error)
 	GetFile(ctx context.Context, params *bot.GetFileParams) (*models.File, error)
 	FileDownloadLink(f *models.File) string

telegram_client_mock.go

@@ -1,3 +1,4 @@
+// telegram_client_mock.go
 package main
 
 import (
@@ -8,17 +9,18 @@ import (
 	"github.com/stretchr/testify/mock"
 )
 
+// MockTelegramClient is a mock implementation of TelegramClient for testing.
 type MockTelegramClient struct {
 	mock.Mock
 	SendMessageFunc      func(ctx context.Context, params *bot.SendMessageParams) (*models.Message, error)
 	SendAudioFunc        func(ctx context.Context, params *bot.SendAudioParams) (*models.Message, error)
-	SendChatActionFunc   func(ctx context.Context, params *bot.SendChatActionParams) (bool, error)
 	SetMyCommandsFunc    func(ctx context.Context, params *bot.SetMyCommandsParams) (bool, error)
 	GetFileFunc          func(ctx context.Context, params *bot.GetFileParams) (*models.File, error)
 	FileDownloadLinkFunc func(f *models.File) string
 	StartFunc            func(ctx context.Context)
 }
 
+// SendMessage mocks sending a message.
 func (m *MockTelegramClient) SendMessage(ctx context.Context, params *bot.SendMessageParams) (*models.Message, error) {
 	if m.SendMessageFunc != nil {
 		return m.SendMessageFunc(ctx, params)
@@ -30,6 +32,7 @@ func (m *MockTelegramClient) SendMessage(ctx context.Context, params *bot.SendMe
 	return nil, args.Error(1)
 }
 
+// SetMyCommands mocks registering bot commands.
 func (m *MockTelegramClient) SetMyCommands(ctx context.Context, params *bot.SetMyCommandsParams) (bool, error) {
 	if m.SetMyCommandsFunc != nil {
 		return m.SetMyCommandsFunc(ctx, params)
@@ -37,6 +40,7 @@ func (m *MockTelegramClient) SetMyCommands(ctx context.Context, params *bot.SetM
 	return true, nil
 }
 
+// SendAudio mocks sending an audio message.
 func (m *MockTelegramClient) SendAudio(ctx context.Context, params *bot.SendAudioParams) (*models.Message, error) {
 	if m.SendAudioFunc != nil {
 		return m.SendAudioFunc(ctx, params)
@@ -44,13 +48,7 @@ func (m *MockTelegramClient) SendAudio(ctx context.Context, params *bot.SendAudi
 	return nil, nil
 }
 
-func (m *MockTelegramClient) SendChatAction(ctx context.Context, params *bot.SendChatActionParams) (bool, error) {
-	if m.SendChatActionFunc != nil {
-		return m.SendChatActionFunc(ctx, params)
-	}
-	return true, nil
-}
-
+// GetFile mocks retrieving file info from Telegram.
 func (m *MockTelegramClient) GetFile(ctx context.Context, params *bot.GetFileParams) (*models.File, error) {
 	if m.GetFileFunc != nil {
 		return m.GetFileFunc(ctx, params)
@@ -58,6 +56,7 @@ func (m *MockTelegramClient) GetFile(ctx context.Context, params *bot.GetFilePar
 	return &models.File{}, nil
 }
 
+// FileDownloadLink mocks building the file download URL.
 func (m *MockTelegramClient) FileDownloadLink(f *models.File) string {
 	if m.FileDownloadLinkFunc != nil {
 		return m.FileDownloadLinkFunc(f)
@@ -65,6 +64,7 @@ func (m *MockTelegramClient) FileDownloadLink(f *models.File) string {
 	return ""
 }
 
+// Start mocks starting the Telegram client.
 func (m *MockTelegramClient) Start(ctx context.Context) {
 	if m.StartFunc != nil {
 		m.StartFunc(ctx)

telegram_helpers.go

@@ -10,6 +10,10 @@ import (
 	"github.com/go-telegram/bot/models"
 )
 
+// largestPhotoSize returns the highest-resolution PhotoSize from the slice
+// Telegram returns for a single photo. Telegram pre-renders each upload at
+// several resolutions; we want the largest for vision quality. Falls back to
+// the zero value when the slice is empty (caller should guard upstream).
 func largestPhotoSize(photos []models.PhotoSize) models.PhotoSize {
 	if len(photos) == 0 {
 		return models.PhotoSize{}
@@ -26,6 +30,12 @@ func largestPhotoSize(photos []models.PhotoSize) models.PhotoSize {
 	return largest
 }
 
+// downloadTelegramFile resolves a Telegram file_id via the bot API, fetches the
+// download URL, and reads the bytes into memory. The two-step dance (GetFile +
+// fetch via FileDownloadLink) is required by Telegram's protocol — direct
+// downloads aren't possible from file_id alone. Buffered into []byte because
+// downstream callers (multipart uploads to ElevenLabs and Anthropic) re-read
+// the body; streaming would require either tee-ing or a temp file.
 func (b *Bot) downloadTelegramFile(ctx context.Context, fileID string) ([]byte, error) {
 	fileInfo, err := b.tgBot.GetFile(ctx, &tgbot.GetFileParams{FileID: fileID})
 	if err != nil {

typing.go

@@ -1,65 +0,0 @@
-package main
-
-import (
-	"context"
-	"time"
-
-	"github.com/go-telegram/bot"
-	"github.com/go-telegram/bot/models"
-)
-
-// typingRefreshInterval re-arms the chat action before Telegram expires it.
-// The Bot API sets the status "for 5 seconds or less", so anything at or above
-// 5s leaves visible gaps. Telegram also clears the status as soon as the bot
-// sends a message, so streamed segments naturally interrupt it until the next
-// tick; there is no API call to clear it early.
-const typingRefreshInterval = 4 * time.Second
-
-// startChatAction shows a chat action (typing, uploading a photo, recording a
-// voice note) and keeps it alive until the returned stop function runs.
-//
-// The returned function is idempotent and MUST be deferred by the caller. A
-// keepalive loop that can outlive its turn is the failure mode behind
-// openclaw/openclaw#27177, where the indicator stuck on until the process was
-// restarted, so the loop here owns a derived context and exits on the first of:
-// stop being called, or the parent context ending.
-func (b *Bot) startChatAction(
-	ctx context.Context,
-	chatID int64,
-	businessConnectionID string,
-	action models.ChatAction,
-) (stop func()) {
-	actionCtx, cancel := context.WithCancel(ctx)
-
-	send := func() {
-		params := &bot.SendChatActionParams{
-			ChatID: chatID,
-			Action: action,
-		}
-		if businessConnectionID != "" {
-			params.BusinessConnectionID = businessConnectionID
-		}
-		if _, err := b.tgBot.SendChatAction(actionCtx, params); err != nil {
-			// Cosmetic only: a failed indicator must never abort the turn.
-			InfoLogger.Printf("[%s] chat action %q failed for chat %d: %v",
-				b.config.ID, action, chatID, err)
-		}
-	}
-
-	send()
-
-	go func() {
-		ticker := time.NewTicker(typingRefreshInterval)
-		defer ticker.Stop()
-		for {
-			select {
-			case <-actionCtx.Done():
-				return
-			case <-ticker.C:
-				send()
-			}
-		}
-	}()
-
-	return cancel
-}

typing_test.go

@@ -1,133 +0,0 @@
-package main
-
-import (
-	"context"
-	"sync"
-	"sync/atomic"
-	"testing"
-	"time"
-
-	"github.com/go-telegram/bot"
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-)
-
-func TestStartChatAction_SendsImmediately(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
-	b, mockTg := setupBotForTest(t, 123)
-
-	var mu sync.Mutex
-	var got []*bot.SendChatActionParams
-	mockTg.SendChatActionFunc = func(_ context.Context, p *bot.SendChatActionParams) (bool, error) {
-		mu.Lock()
-		defer mu.Unlock()
-		got = append(got, p)
-		return true, nil
-	}
-
-	stop := b.startChatAction(context.Background(), 42, "biz-7", "typing")
-	stop()
-
-	mu.Lock()
-	defer mu.Unlock()
-	require.Len(t, got, 1, "the indicator must show before the slow work starts, not after")
-	assert.Equal(t, int64(42), got[0].ChatID)
-	assert.EqualValues(t, "typing", got[0].Action)
-	assert.Equal(t, "biz-7", got[0].BusinessConnectionID,
-		"business chats need the connection id or the indicator never renders")
-}
-
-func TestStartChatAction_OmitsEmptyBusinessConnectionID(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
-	b, mockTg := setupBotForTest(t, 123)
-
-	var mu sync.Mutex
-	var captured *bot.SendChatActionParams
-	mockTg.SendChatActionFunc = func(_ context.Context, p *bot.SendChatActionParams) (bool, error) {
-		mu.Lock()
-		defer mu.Unlock()
-		captured = p
-		return true, nil
-	}
-
-	stop := b.startChatAction(context.Background(), 42, "", "typing")
-	stop()
-
-	mu.Lock()
-	defer mu.Unlock()
-	require.NotNil(t, captured)
-	assert.Empty(t, captured.BusinessConnectionID)
-}
-
-// The openclaw#27177 guard: once the turn ends, the keepalive must stop. A loop
-// that can re-arm after completion left the indicator stuck on until restart.
-func TestStartChatAction_StopHaltsKeepalive(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
-	b, mockTg := setupBotForTest(t, 123)
-
-	var calls atomic.Int32
-	mockTg.SendChatActionFunc = func(_ context.Context, _ *bot.SendChatActionParams) (bool, error) {
-		calls.Add(1)
-		return true, nil
-	}
-
-	stop := b.startChatAction(context.Background(), 42, "", "typing")
-	stop()
-	after := calls.Load()
-
-	// Well past a refresh tick had the loop survived.
-	time.Sleep(50 * time.Millisecond)
-	assert.Equal(t, after, calls.Load(), "no chat action may be sent after stop")
-}
-
-// Cancelling the parent context must also tear the loop down, so a turn aborted
-// upstream cannot leak a goroutine that keeps calling Telegram.
-func TestStartChatAction_ParentCancelHaltsKeepalive(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
-	b, mockTg := setupBotForTest(t, 123)
-
-	var calls atomic.Int32
-	mockTg.SendChatActionFunc = func(_ context.Context, _ *bot.SendChatActionParams) (bool, error) {
-		calls.Add(1)
-		return true, nil
-	}
-
-	ctx, cancel := context.WithCancel(context.Background())
-	stop := b.startChatAction(ctx, 42, "", "typing")
-	defer stop()
-
-	cancel()
-	after := calls.Load()
-	time.Sleep(50 * time.Millisecond)
-	assert.Equal(t, after, calls.Load(), "parent cancellation must stop the keepalive")
-}
-
-func TestStartChatAction_StopIsIdempotent(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
-	b, mockTg := setupBotForTest(t, 123)
-	mockTg.SendChatActionFunc = func(_ context.Context, _ *bot.SendChatActionParams) (bool, error) {
-		return true, nil
-	}
-
-	stop := b.startChatAction(context.Background(), 42, "", "typing")
-	// The voice path calls stop early and again via defer.
-	assert.NotPanics(t, func() {
-		stop()
-		stop()
-	})
-}
-
-// A failed indicator is cosmetic and must never surface as a turn failure.
-func TestStartChatAction_SendErrorIsNonFatal(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
-	b, mockTg := setupBotForTest(t, 123)
-	mockTg.SendChatActionFunc = func(_ context.Context, _ *bot.SendChatActionParams) (bool, error) {
-		return false, assert.AnError
-	}
-
-	assert.NotPanics(t, func() {
-		stop := b.startChatAction(context.Background(), 42, "", "typing")
-		stop()
-	})
-}
-
-// Telegram clears the status after "5 seconds or less", so the refresh must be
-// strictly under that or the indicator visibly drops out mid-turn.
-func TestTypingRefreshInterval_UnderTelegramExpiry(t *testing.T) { //NOSONAR go:S100 -- underscore separation is idiomatic in Go test names
-	assert.Less(t, typingRefreshInterval, 5*time.Second,
-		"Telegram expires a chat action after at most 5s")
-}

user_management_test.go

@@ -22,18 +22,22 @@ const (
 )
 
 func TestOwnerAssignment(t *testing.T) {
+	// Initialize loggers
 	initLoggers()
 
+	// Initialize in-memory database for testing
 	db, err := gorm.Open(sqlite.Open(memoryDSN), &gorm.Config{})
 	if err != nil {
 		t.Fatalf(errOpenDB, err)
 	}
 
+	// Migrate the schema
 	err = db.AutoMigrate(&BotModel{}, &ConfigModel{}, &Message{}, &User{}, &Role{}, &Scope{})
 	if err != nil {
 		t.Fatalf(errMigrateSchema, err)
 	}
 
+	// Create default roles and scopes
 	err = createDefaultRoles(db)
 	if err != nil {
 		t.Fatalf(errCreateRoles, err)
@@ -42,6 +46,7 @@ func TestOwnerAssignment(t *testing.T) {
 		t.Fatalf(errCreateScopes, err)
 	}
 
+	// Create a bot configuration
 	config := BotConfig{
 		ID:              "test_bot",
 		TelegramToken:   "TEST_TELEGRAM_TOKEN",
@@ -54,41 +59,49 @@ func TestOwnerAssignment(t *testing.T) {
 		OwnerTelegramID: 111111111,
 	}
 
+	// Initialize MockClock
 	mockClock := &MockClock{
 		currentTime: time.Now(),
 	}
 
+	// Initialize MockTelegramClient
 	mockTGClient := &MockTelegramClient{
 		SendMessageFunc: func(ctx context.Context, params *bot.SendMessageParams) (*models.Message, error) {
 			chatID, ok := params.ChatID.(int64)
 			if !ok {
 				return nil, fmt.Errorf("ChatID is not of type int64")
 			}
+			// Simulate successful message sending
 			return &models.Message{ID: 1, Chat: models.Chat{ID: chatID}}, nil
 		},
 	}
 
+	// Create the bot with the mock Telegram client
 	bot, err := NewBot(db, config, mockClock, mockTGClient)
 	if err != nil {
 		t.Fatalf(errCreateBot, err)
 	}
 
+	// Verify that the owner exists
 	var owner User
 	err = db.Where("telegram_id = ? AND bot_id = ? AND is_owner = ?", config.OwnerTelegramID, bot.botID, true).First(&owner).Error
 	if err != nil {
 		t.Fatalf("Owner was not created: %v", err)
 	}
 
+	// Attempt to create another owner for the same bot
 	_, err = bot.getOrCreateUser(222222222, "AnotherOwner", true)
 	if err == nil {
 		t.Fatalf("Expected error when creating a second owner, but got none")
 	}
 
+	// Verify that the error message is appropriate
 	expectedErrorMsg := "an owner already exists for this bot"
 	if err.Error() != expectedErrorMsg {
 		t.Fatalf("Unexpected error message: %v", err)
 	}
 
+	// Assign admin role to a new user
 	regularUser, err := bot.getOrCreateUser(333333333, "RegularUser", false)
 	if err != nil {
 		t.Fatalf("Failed to create regular user: %v", err)
@@ -98,6 +111,7 @@ func TestOwnerAssignment(t *testing.T) {
 		t.Fatalf("Expected role 'user', got '%s'", regularUser.Role.Name)
 	}
 
+	// Attempt to change an existing user to owner
 	_, err = bot.getOrCreateUser(333333333, "AdminUser", true)
 	if err == nil {
 		t.Fatalf("Expected error when changing existing user to owner, but got none")
@@ -108,21 +122,27 @@ func TestOwnerAssignment(t *testing.T) {
 		t.Fatalf("Unexpected error message: %v", err)
 	}
 
+	// If you need to test admin creation, you should do it through a separate admin creation function
+	// or by updating an existing user's role with proper authorization checks
 }
 
 func TestPromoteUserToAdmin(t *testing.T) {
+	// Initialize loggers
 	initLoggers()
 
+	// Initialize in-memory database for testing
 	db, err := gorm.Open(sqlite.Open(memoryDSN), &gorm.Config{})
 	if err != nil {
 		t.Fatalf(errOpenDB, err)
 	}
 
+	// Migrate the schema
 	err = db.AutoMigrate(&BotModel{}, &ConfigModel{}, &Message{}, &User{}, &Role{}, &Scope{})
 	if err != nil {
 		t.Fatalf(errMigrateSchema, err)
 	}
 
+	// Create default roles and scopes
 	err = createDefaultRoles(db)
 	if err != nil {
 		t.Fatalf(errCreateRoles, err)
@@ -151,11 +171,13 @@ func TestPromoteUserToAdmin(t *testing.T) {
 		t.Fatalf(errCreateBot, err)
 	}
 
+	// Create an owner
 	owner, err := bot.getOrCreateUser(config.OwnerTelegramID, "OwnerUser", true)
 	if err != nil {
 		t.Fatalf("Failed to create owner: %v", err)
 	}
 
+	// Test promoting a user to admin
 	regularUser, err := bot.getOrCreateUser(444444444, "RegularUser", false)
 	if err != nil {
 		t.Fatalf("Failed to create regular user: %v", err)
@@ -166,6 +188,7 @@ func TestPromoteUserToAdmin(t *testing.T) {
 		t.Fatalf("Failed to promote user to admin: %v", err)
 	}
 
+	// Refresh user data
 	promotedUser, err := bot.getOrCreateUser(444444444, "RegularUser", false)
 	if err != nil {
 		t.Fatalf("Failed to get promoted user: %v", err)
@@ -176,19 +199,26 @@ func TestPromoteUserToAdmin(t *testing.T) {
 	}
 }
 
+// TestGetOrCreateUser tests the getOrCreateUser method of the Bot.
+// It verifies that a new user is created when one does not exist,
+// and an existing user is returned when one does exist.
 func TestGetOrCreateUser(t *testing.T) {
+	// Initialize loggers
 	initLoggers()
 
+	// Initialize in-memory database for testing
 	db, err := gorm.Open(sqlite.Open(memoryDSN), &gorm.Config{})
 	if err != nil {
 		t.Fatalf(errOpenDB, err)
 	}
 
+	// Migrate the schema
 	err = db.AutoMigrate(&BotModel{}, &ConfigModel{}, &Message{}, &User{}, &Role{}, &Scope{})
 	if err != nil {
 		t.Fatalf(errMigrateSchema, err)
 	}
 
+	// Create default roles and scopes
 	err = createDefaultRoles(db)
 	if err != nil {
 		t.Fatalf(errCreateRoles, err)
@@ -197,10 +227,12 @@ func TestGetOrCreateUser(t *testing.T) {
 		t.Fatalf(errCreateScopes, err)
 	}
 
+	// Create a mock clock starting at a fixed time
 	mockClock := &MockClock{
 		currentTime: time.Date(2023, 10, 1, 0, 0, 0, 0, time.UTC),
 	}
 
+	// Create a mock configuration
 	config := BotConfig{
 		ID:              "bot1",
 		MemorySize:      10,
@@ -212,49 +244,62 @@ func TestGetOrCreateUser(t *testing.T) {
 		OwnerTelegramID: 123456789,
 	}
 
+	// Initialize MockTelegramClient
 	mockTGClient := &MockTelegramClient{
 		SendMessageFunc: func(ctx context.Context, params *bot.SendMessageParams) (*models.Message, error) {
 			chatID, ok := params.ChatID.(int64)
 			if !ok {
 				return nil, fmt.Errorf("ChatID is not of type int64")
 			}
+			// Simulate successful message sending
 			return &models.Message{ID: 1, Chat: models.Chat{ID: chatID}}, nil
 		},
 	}
 
+	// Create the bot with the mock Telegram client
 	bot, err := NewBot(db, config, mockClock, mockTGClient)
 	if err != nil {
 		t.Fatalf(errCreateBot, err)
 	}
 
+	// Verify that the owner exists
 	var owner User
 	err = db.Where("telegram_id = ? AND bot_id = ? AND is_owner = ?", config.OwnerTelegramID, bot.botID, true).First(&owner).Error
 	if err != nil {
 		t.Fatalf("Owner was not created: %v", err)
 	}
 
+	// Attempt to create another owner for the same bot
 	_, err = bot.getOrCreateUser(222222222, "AnotherOwner", true)
 	if err == nil {
 		t.Fatalf("Expected error when creating a second owner, but got none")
 	}
 
+	// Create a new user
 	newUser, err := bot.getOrCreateUser(987654321, "TestUser", false)
 	if err != nil {
 		t.Fatalf("Failed to create a new user: %v", err)
 	}
 
+	// Verify that the new user was created
 	var userInDB User
 	err = db.Where("telegram_id = ?", newUser.TelegramID).First(&userInDB).Error
 	if err != nil {
 		t.Fatalf("New user was not created in the database: %v", err)
 	}
 
+	// Get the existing user
 	existingUser, err := bot.getOrCreateUser(987654321, "TestUser", false)
 	if err != nil {
 		t.Fatalf("Failed to get existing user: %v", err)
 	}
 
+	// Verify that the existing user is the same as the new user
 	if existingUser.ID != userInDB.ID {
 		t.Fatalf("Expected to get the existing user, but got a different user")
 	}
 }
+
+// To ensure thread safety and avoid race conditions during testing,
+// you can run the tests with the `-race` flag:
+// go test -race -v