message_loop.go

package main

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"os"
	"regexp"
	"strings"
	"sync"
	"time"

	"sokratos/config"
	"sokratos/db"
	"sokratos/engine"
	"sokratos/google"
	"sokratos/grammar"
	"sokratos/llm"
	"sokratos/logger"
	"sokratos/memory"
	"sokratos/supervisor"
	"sokratos/pipelines"
	"sokratos/platform"
	"sokratos/prompts"
	"sokratos/routines"
	"sokratos/textutil"
	"sokratos/timeouts"
	"sokratos/toolreg"
	"sokratos/tools"
)

// messageContext bundles all session-level dependencies needed by the message
// handling functions. All fields are reference types (pointers, maps, funcs)
// so passing by value is safe.
type messageContext struct {
	cfg            *config.AppConfig
	svc            *serviceBundle
	eng            *engine.Engine
	lb             *llmBundle
	registry       *tools.Registry
	triageCfg      *pipelines.TriageConfig
	confirmExec    func(context.Context, json.RawMessage) (string, error)
	skillMtimes    map[string]time.Time
	skillDeps      tools.SkillDeps
	rebuildGrammar func()
	router         engine.SlotRouter
	platform       platform.Platform
	selector       *toolreg.ToolSelector // nil = use full tool set (no dynamic selection)
}

// handleReload forces a full re-sync of routines.toml and skills from disk.
// Returns a human-readable summary of what changed.
func handleReload(mc messageContext) string {
	added, updated, deleted := routines.SyncFromFile(db.Pool, ".config/routines.toml")
	skillsChanged := tools.SyncSkills(mc.registry, "skills", mc.rebuildGrammar, mc.skillMtimes, mc.skillDeps)
	var parts []string
	if len(added)+len(updated)+len(deleted) > 0 {
		parts = append(parts, fmt.Sprintf("Routines: +%d ~%d -%d", len(added), len(updated), len(deleted)))
	}
	if skillsChanged {
		parts = append(parts, "Skills: reloaded")
	}
	if len(parts) > 0 {
		return "Reloaded: " + strings.Join(parts, ", ")
	}
	return "Everything up to date."
}

// handleMetrics runs a pre-built metrics report. Accepts optional args:
// "/metrics" (overview, 1h), "/metrics slots", "/metrics dispatch 24h".
func handleMetrics(_ messageContext, args string) string {
	parts := strings.Fields(args)
	var report, window string
	if len(parts) >= 1 {
		report = parts[0]
	}
	if len(parts) >= 2 {
		window = parts[1]
	}
	ctx, cancel := context.WithTimeout(context.Background(), timeouts.RoutineDB)
	defer cancel()
	result, err := tools.QueryMetricsReport(ctx, db.Pool, report, window)
	if err != nil {
		return "Metrics query failed: " + err.Error()
	}
	return result
}

// handleBootstrap launches a profile generation run in the background.
// Returns an immediate acknowledgement string.
func handleBootstrap(mc messageContext) string {
	if db.Pool == nil || mc.svc.DTC == nil || mc.cfg.EmbedURL == "" {
		return "Bootstrap requires database, deep thinker, and embedding service."
	}
	bootstrapSend := func(text string) {
		mc.platform.Broadcast(context.Background(), text)
	}
	go pipelines.RunBootstrap(pipelines.BootstrapConfig{
		PipelineDeps: pipelines.PipelineDeps{
			Pool:          db.Pool,
			DTC:           mc.svc.DTC,
			EmbedEndpoint: mc.cfg.EmbedURL,
			EmbedModel:    mc.cfg.EmbedModel,
			GrammarFn:     mc.svc.BgGrammarFunc,
		},
		AgentName: mc.cfg.AgentName,
		SendFunc:  bootstrapSend,
		OnProfile: func() {
			mc.eng.RefreshProfile()
			mc.eng.RefreshPersonality()
		},
		QueueFn: mc.svc.QueueFunc,
	})
	return "Profile generation started in the background. I'll notify you when it's ready."
}

// handleGoogle triggers Google OAuth re-authentication via the platform.
// Uses a single OAuth flow with combined Gmail+Calendar scopes so only
// one auth URL + code paste is needed. Re-initializes both services and
// registers tools that were previously disabled.
func handleGoogle(mc messageContext) string {
	gmailWasNil := google.GmailService == nil
	calWasNil := google.CalendarService == nil

	// Delete existing token to force a fresh OAuth flow.
	os.Remove(mc.cfg.GoogleTokenPath)

	// Build auth IO that reads replies from the platform.
	authIO := &google.AuthIO{
		Send: func(msg string) {
			mc.platform.Broadcast(context.Background(), msg)
		},
		Receive: func() (string, error) {
			return mc.platform.ReadReply()
		},
	}

	// Combined scopes for a single OAuth flow.
	scopes := []string{
		"https://www.googleapis.com/auth/gmail.readonly",
		"https://www.googleapis.com/auth/gmail.send",
		"https://www.googleapis.com/auth/calendar",
		"https://www.googleapis.com/auth/contacts.readonly",
	}

	client, err := google.GetClient(
		context.Background(), "Google",
		mc.cfg.GmailCredsPath, mc.cfg.GoogleTokenPath,
		scopes, authIO,
	)
	if err != nil {
		return fmt.Sprintf("❌ Google auth failed: %v", err)
	}
	if client == nil {
		return "⚠️ Google credentials file not found — features disabled"
	}

	// Create both services from the single authenticated client.
	var results []string

	if err := google.InitGmailFromClient(context.Background(), client); err != nil {
		results = append(results, fmt.Sprintf("Gmail: ❌ %v", err))
	} else {
		results = append(results, "Gmail: ✅")
	}

	if err := google.InitCalendarFromClient(context.Background(), client); err != nil {
		results = append(results, fmt.Sprintf("Calendar: ❌ %v", err))
	} else {
		results = append(results, "Calendar: ✅")
	}

	if err := google.InitPeopleFromClient(context.Background(), client); err != nil {
		results = append(results, fmt.Sprintf("People: ❌ %v", err))
	} else {
		results = append(results, "People: ✅")
		google.LoadContacts()
	}

	// Register tools that were previously disabled.
	if gmailWasNil && google.GmailService != nil {
		registerGmailTools(mc.registry, db.Pool, mc.triageCfg, mc.cfg.EmailDisplayBatch, mc.svc.Subagent)
		mc.rebuildGrammar()
		logger.Log.Info("[/google] Gmail tools registered")
	}
	if calWasNil && google.CalendarService != nil {
		registerCalendarTools(mc.registry, db.Pool)
		mc.rebuildGrammar()
		logger.Log.Info("[/google] Calendar tools registered")
	}

	// Reset the auth error once so future expiry triggers a new notification.
	mc.svc.AuthErrorOnce = &sync.Once{}

	// Also invalidate the calendar list cache since we have a fresh token.
	google.InvalidateCache()

	return strings.Join(results, "\n")
}

// processMessage runs the full supervisor pipeline for a regular user message:
// prefetch → temporal context → supervisor → slide/archive → triage → reply.
func processMessage(mc messageContext, msg *platform.IncomingMessage, msgText, userPrompt string, visionParts []llm.ContentPart) {
	messageStart := time.Now()
	typingCancel := mc.platform.StartTyping(context.Background(), msg.ChannelID)

	// Phase 0: Pipeline isolation — tag this message and exclude prior pipeline's memories.
	pipelineID := msg.PipelineID()
	excludePipelineID := mc.svc.StateMgr.LastPipelineID()

	// Phase 1: Snapshot history (StateManager has its own RWMutex).
	history := mc.svc.StateMgr.ReadMessages()

	// Phase 1.5: Staleness trim — if there's a long gap since the last
	// conversation message, old topics are stale and will confuse the model.
	// Keep only recent messages for immediate context.
	const staleGap = 30 * time.Minute
	if len(history) > 4 {
		lastMsg := history[len(history)-1]
		if !lastMsg.Time.IsZero() && time.Since(lastMsg.Time) > staleGap {
			history = history[len(history)-4:]
		}
	}

	// Carry-forward: if last prefetch was useful, boost those memory IDs.
	var boostIDs []int64
	if mc.svc.StateMgr.PrefetchUseful() {
		boostIDs = mc.svc.StateMgr.LastPrefetchIDs()
	}

	// Phase 2: Start prefetch + temporal context + tool selection in parallel.
	type prefetchData struct {
		content    string
		ids        []int64
		summaries  string
		temporal   string
		reflection string
	}
	pfCh := make(chan prefetchData, 1)
	go func() {
		pfStart := time.Now()
		var pd prefetchData
		var memoriesFound int
		if db.Pool != nil && mc.cfg.EmbedURL != "" && strings.TrimSpace(msgText) != "" {
			pfCtx, pfCancel := context.WithTimeout(context.Background(), tools.TimeoutPrefetch)
			if pf := subconsciousPrefetch(pfCtx, db.Pool, mc.cfg.EmbedURL, mc.cfg.EmbedModel, msgText, history, excludePipelineID, boostIDs...); pf != nil {
				pd.content = pf.Summaries
				pd.ids = pf.IDs
				pd.summaries = pf.Summaries
				memoriesFound = len(pf.IDs)
			}
			pfCancel()
		}
		if db.Pool != nil {
			pd.temporal = engine.BuildTemporalContext(context.Background(), db.Pool)
		}
		// Load latest reflection insight for the supervisor.
		if db.Pool != nil {
			rfCtx, rfCancel := context.WithTimeout(context.Background(), timeouts.DBQuery)
			pd.reflection = memory.QueryLatestReflection(rfCtx, db.Pool)
			rfCancel()
		}
		mc.svc.Metrics.Since("prefetch.duration", pfStart, map[string]string{
			"memories_found": fmt.Sprintf("%d", memoriesFound),
		})
		pfCh <- pd
	}()

	// Tool selection: embed query and select relevant tools (parallel with prefetch).
	type toolSelectionData struct {
		agent *llm.ToolAgentConfig // nil = use full tool set
	}
	tsCh := make(chan toolSelectionData, 1)
	go func() {
		if mc.selector == nil {
			tsCh <- toolSelectionData{}
			return
		}
		tsCtx, tsCancel := context.WithTimeout(context.Background(), timeouts.Embedding)
		defer tsCancel()
		// Include recent conversation context for short/ambiguous queries so the
		// embedding match has enough signal. "Remove it" alone is meaningless, but
		// "...reminder about cousins in Poland | Remove it" matches check_background_task.
		selectQuery := msgText
		if len(msgText) < 40 {
			if recent := mc.eng.SM.LastAssistantMessage(); recent != "" {
				// Truncate prior response to keep the embedding focused.
				if len(recent) > 150 {
					recent = recent[:150]
				}
				selectQuery = recent + " | " + msgText
			}
		}
		names, err := mc.selector.Select(tsCtx, selectQuery)
		if err != nil {
			logger.Log.Warnf("[tool-selector] selection failed, using full set: %v", err)
			tsCh <- toolSelectionData{}
			return
		}
		if names == nil {
			tsCh <- toolSelectionData{}
			return
		}
		// Build per-request tool descriptions and grammar.
		// CompactIndex provides core tools (always visible); BuildSelectedToolIndex
		// adds the RAG-selected extras. Both are needed so the supervisor always
		// sees search_web, search_memory, etc.
		coreIndex := mc.registry.CompactIndex()
		selectedIndex := mc.registry.BuildSelectedToolIndex(names)
		toolIndex := coreIndex
		if selectedIndex != "" {
			toolIndex += "\n" + selectedIndex
		}
		td := strings.Replace(prompts.Tools, "%TOOL_INDEX%", toolIndex, 1)
		schemas := mc.registry.SchemasForTools(names)
		grammarStr := grammar.BuildSubagentToolGrammar(schemas)
		tsCh <- toolSelectionData{
			agent: &llm.ToolAgentConfig{
				ToolDescriptions: td,
				Grammar:          grammarStr,
			},
		}
	}()

	// Phase 3: Snapshot personality/profile under the lock (microseconds),
	// then release before the multi-second inference call.
	mc.eng.Mu.Lock()
	personalityContent := mc.eng.PersonalityContent
	profileContent := mc.eng.ProfileContent
	mc.eng.Mu.Unlock()

	// Phase 3.3: Inject recent system actions (routines, heartbeats) so the
	// supervisor knows what the system recently did and avoids duplicate work.
	if xml := mc.eng.FormatRecentActionsXML(2 * mc.cfg.HeartbeatInterval); xml != "" {
		userPrompt += "\n\n" + xml
	}

	// Phase 3.4: Inject active background job context so the supervisor can
	// route user messages to background Brain jobs via reply_to_job/cancel_job.
	if jobCtx := buildJobContext(mc.svc.StateMgr.GetJobs()); jobCtx != "" {
		userPrompt += "\n\n" + jobCtx
	}

	// Phase 3.5: Wait for prefetch and tool selection results.
	pf := <-pfCh
	ts := <-tsCh

	// Track prefetch IDs for carry-forward.
	mc.svc.StateMgr.SetLastPrefetchIDs(pf.ids)
	mc.svc.StateMgr.SetPrefetchUseful(len(pf.ids) > 0)

	// Inject latest reflection insight into temporal context if available.
	if pf.reflection != "" {
		// Extract actionable sections (patterns + predictions).
		sections := extractReflectionForPrompt(pf.reflection)
		if sections != "" {
			if pf.temporal != "" {
				pf.temporal += "\n\n"
			}
			pf.temporal += "<recent_reflection>\n" + sections + "\n</recent_reflection>"
		}
	}

	// Phase 3.5: Brain strategic planning — proactive guidance before slot acquire.
	// Non-blocking — if the Brain slot is busy, proceed without guidance.
	// When the Brain provides guidance (task is complex), route to Brain for supervision.
	var strategicGuidance string
	if mc.svc.DTC != nil {
		var historyCtx strings.Builder
		for i := len(history) - 1; i >= 0 && historyCtx.Len() < 2000; i-- {
			m := history[i]
			if m.Role == "user" || m.Role == "assistant" {
				line := fmt.Sprintf("[%s]: %s\n", m.Role, m.Content)
				if len(line) > 400 {
					line = line[:400] + "...\n"
				}
				historyCtx.WriteString(line)
			}
		}
		historySection := ""
		if historyCtx.Len() > 0 {
			historySection = "Recent conversation:\n" + historyCtx.String()
		}
		memoriesSection := ""
		if pf.content != "" {
			memoriesSection = "Retrieved memories:\n" + pf.content
		}
		planPrompt := strings.NewReplacer(
			"%QUERY%", msgText,
			"%HISTORY%", historySection,
			"%MEMORIES%", memoriesSection,
		).Replace(prompts.BrainStrategic)

		planCtx, planCancel := context.WithTimeout(context.Background(), 15*time.Second)
		planCtx = engine.WithPriority(planCtx, engine.PriorityUser)
		raw, err := mc.svc.DTC.TryCompleteNoThink(planCtx,
			"You are a strategic planner guiding a smaller routing model.",
			planPrompt, 256)
		planCancel()
		if err != nil {
			logger.Log.Debugf("[brain-strategic] skipped: %v", err)
		} else {
			raw = textutil.StripThinkTags(raw)
			raw = strings.TrimSpace(raw)
			if !strings.EqualFold(raw, "NONE") && raw != "" {
				strategicGuidance = raw
				logger.Log.Infof("[brain-strategic] guidance: %.120s", raw)
			}
		}
	}
	useBrain := strategicGuidance != ""

	// Phase 4: Acquire supervisor slot.
	// When the Brain flagged the task as complex (provided guidance), prefer Brain
	// for supervision — it has the reasoning depth for multi-step tool chains.
	// Simple tasks (NONE) use the 9B for speed.
	choice := mc.router.AcquireOrFallback(context.Background(), useBrain, engine.PriorityUser)
	if useBrain {
		logger.Log.Info("[supervisor] routed to Brain for complex task")
	}
	acquired := true
	defer func() {
		if acquired {
			choice.Release()
		}
	}()

	// Progress tracking: send "Thinking..." immediately, first tool call
	// replaces it, subsequent tool calls send new messages (visible trail).
	ph, _ := platform.NewProgressHandle(context.Background(), mc.platform, msg.ChannelID, "Thinking...", msg.ID)
	firstToolCall := true

	// Wrap confirmExec to inject progress reporting into the tool context.
	progressExec := func(ctx context.Context, raw json.RawMessage) (string, error) {
		if ph != nil {
			ctx = tools.WithProgress(ctx, func(status string) {
				ph.Update(context.Background(), status)
			})
		}
		return mc.confirmExec(ctx, raw)
	}

	// Use per-request tool selection if available, otherwise fall back to full set.
	toolAgent := mc.lb.ToolAgent
	if ts.agent != nil {
		toolAgent = ts.agent
	}

	// BrainFinalize: the Brain composes all substantive user-facing responses.
	// The 9B handles tool routing; the Brain handles response quality.
	var brainFinalize func(ctx context.Context, toolContext, draft string) (string, error)
	if mc.svc.DTC != nil {
		dtc := mc.svc.DTC
		brainFinalize = func(ctx context.Context, toolContext, draft string) (string, error) {
			if ph != nil {
				ph.Update(context.Background(), "Composing response...")
			}
			// Build recent conversation context so the Brain knows what was
			// discussed. Truncate to last ~2K chars to stay within budget.
			var historyCtx strings.Builder
			for i := len(history) - 1; i >= 0 && historyCtx.Len() < 2000; i-- {
				m := history[i]
				if m.Role == "user" || m.Role == "assistant" {
					line := fmt.Sprintf("[%s]: %s\n", m.Role, m.Content)
					if len(line) > 500 {
						line = line[:500] + "...\n"
					}
					historyCtx.WriteString(line)
				}
			}

			var prompt strings.Builder
			if historyCtx.Len() > 0 {
				fmt.Fprintf(&prompt, "Recent conversation:\n%s\n", historyCtx.String())
			}
			fmt.Fprintf(&prompt, "The user said: %s\n\n", msgText)
			if toolContext != "" {
				fmt.Fprintf(&prompt, "Tool results:\n%s\n", toolContext)
			}
			fmt.Fprintf(&prompt, "Draft response from the routing model:\n%s\n\n", draft)
			prompt.WriteString("Compose a polished, concise response. Preserve all facts and URLs. Fix any errors — if the draft contradicts the conversation history, correct it. Be direct — no filler, no preamble.")

			return dtc.CompleteNoThink(ctx, "You are composing a final response for a Telegram chat. Be concise and factual.", prompt.String(), 2048)
		}
	}

	// BrainReview: mid-loop oversight and error escalation. Fires on round 2+
	// (multi-step oversight) and after tool errors. Round-0 review is replaced
	// by the strategic guidance call above.
	var brainReview func(ctx context.Context, userQuery, thinking, context string) (string, error)
	if mc.svc.DTC != nil {
		dtc := mc.svc.DTC
		brainReview = func(ctx context.Context, userQuery, thinking, reviewCtx string) (string, error) {
			// Detect whether this is a mid-loop escalation (reviewCtx contains
			// recent exchange with [user]/[assistant] lines) vs round-0 review.
			isMidLoop := strings.Contains(reviewCtx, "[user]:")

			var userPrompt string
			if isMidLoop {
				p := strings.NewReplacer("%QUERY%", userQuery, "%EXCHANGE%", reviewCtx).Replace(prompts.BrainEscalation)
				userPrompt = p
			} else {
				p := strings.NewReplacer("%QUERY%", userQuery, "%TOOL_CALL%", reviewCtx).Replace(prompts.BrainReview)
				if thinking != "" {
					p = "The routing model thought: " + thinking + "\n\n" + p
				}
				userPrompt = p
			}

			// Include recent conversation history for context.
			var historyCtx strings.Builder
			for i := len(history) - 1; i >= 0 && historyCtx.Len() < 2000; i-- {
				m := history[i]
				if m.Role == "user" || m.Role == "assistant" {
					line := fmt.Sprintf("[%s]: %s\n", m.Role, m.Content)
					if len(line) > 400 {
						line = line[:400] + "...\n"
					}
					historyCtx.WriteString(line)
				}
			}
			if historyCtx.Len() > 0 {
				userPrompt = "Recent conversation:\n" + historyCtx.String() + "\n" + userPrompt
			}

			maxTokens := 256
			if isMidLoop {
				maxTokens = 512
			}
			raw, err := dtc.CompleteNoThink(ctx,
				"You are a senior engineer reviewing a tool routing decision. Be specific and actionable.",
				userPrompt, maxTokens)
			if err != nil {
				return "", err
			}
			raw = textutil.StripThinkTags(raw)
			raw = strings.TrimSpace(raw)
			if strings.EqualFold(raw, "OK") || strings.HasPrefix(strings.ToLower(raw), "ok") {
				return "", nil
			}
			return "BRAIN GUIDANCE: " + raw + "\nFollow this guidance for your next action.", nil
		}
	}

	// SummarizeFn: condense oversized tool results via subagent instead of truncating.
	// Uses TryComplete so it falls back to truncation if no slot is available.
	var summarizeFn func(ctx context.Context, toolName, result, userGoal string) (string, error)
	if mc.svc.Subagent != nil {
		subagent := mc.svc.Subagent
		summarizeFn = func(ctx context.Context, toolName, result, userGoal string) (string, error) {
			userContent := fmt.Sprintf("The user asked: %s\n\nThe tool %q returned the following output (%d chars). "+
				"Extract the information relevant to the task. Include:\n"+
				"- Key facts, values, names, and identifiers\n"+
				"- Code examples, API calls, curl commands, and parameter formats VERBATIM (do not paraphrase code)\n"+
				"- URLs, endpoints, ports, and protocol details\n"+
				"Omit: boilerplate, navigation menus, ads, repeated structure, XML namespaces.\n\n%s",
				userGoal, toolName, len(result), result)
			return subagent.TryComplete(ctx,
				"You are a tool result summarizer. Preserve code examples and API details verbatim.",
				userContent, 2048)
		}
	}

	// Accumulate thinking tokens for UI display.
	var thinkingBuf strings.Builder
	var thinkingMu sync.Mutex
	lastThinkUpdate := time.Now()

	opts := llm.QuerySupervisorOpts{
		Parts:              visionParts,
		History:            history,
		PersonalityContent: personalityContent,
		ProfileContent:     profileContent,
		TemporalContext:    pf.temporal,
		PrefetchContent:    pf.content,
		StrategicGuidance:  strategicGuidance,
		MaxToolResultLen:   mc.cfg.MaxToolResultLen,
		MaxWebSources:      mc.cfg.MaxWebSources,
		ToolAgent:          toolAgent,
		MandatedBrainTools: mandatedBrainTools,
		SummarizeFn:        summarizeFn,
		// Both Brain and 9B think on round 0 only. Brain doesn't need thinking
		// on every round — it's slow (60-80s/round) and round-0 thinking is
		// sufficient for strategy. The strategic guidance already provides context.
		FirstRoundThinking: true,
		BrainFinalize:      brainFinalize,
		BrainReview:        brainReview,
		OnThinkingToken: func(token string) {
			thinkingMu.Lock()
			defer thinkingMu.Unlock()
			thinkingBuf.WriteString(token)
			// Throttle updates to avoid flooding Telegram API (max 1 update/500ms).
			if time.Since(lastThinkUpdate) >= 500*time.Millisecond && ph != nil {
				text := strings.TrimSpace(thinkingBuf.String())
				// Strip any residual think tags that leaked through.
				text = strings.ReplaceAll(text, "</think>", "")
				text = strings.ReplaceAll(text, "<think>", "")
				if text == "" {
					return
				}
				// Truncate from the front to keep the message under Telegram's
				// 4096 char limit while showing the most recent reasoning.
				const maxDisplay = 3800
				if len(text) > maxDisplay {
					text = "..." + text[len(text)-maxDisplay:]
				}
				if err := ph.Update(context.Background(), "Thinking:\n"+text); err != nil {
					logger.Log.Warnf("[thinking-stream] progress update failed: %v", err)
				} else {
					logger.Log.Debugf("[thinking-stream] updated progress (%d chars)", len(text))
				}
				lastThinkUpdate = time.Now()
			}
		},
		OnToolStart: func(toolSummary string) {
			choice.ReleaseReserved()
			acquired = false

			// Format tool call summaries. For parallel calls (joined by " + "),
			// each command gets its own collapsible block. For single calls,
			// long content is wrapped in a collapsible block.
			display := formatToolDisplay(toolSummary)

			if firstToolCall {
				firstToolCall = false
				if ph != nil {
					ph.Update(context.Background(), display)
				}
			} else {
				msgID, err := mc.platform.Send(context.Background(), msg.ChannelID, display, "")
				if err == nil && ph != nil {
					ph.MessageID = msgID
				}
			}
		},
		OnToolEnd: func(reCtx context.Context) error {
			if reErr := choice.Reacquire(reCtx); reErr != nil {
				return reErr
			}
			acquired = true
			return nil
		},
		OnToolResult: func(toolName, result string) {
			if result == "" {
				return
			}
			// Send full output in collapsible blocks. Split into chunks
			// if needed to stay within Telegram's 4096 char message limit.
			const maxChunk = 3800 // leave room for collapsible wrapper overhead
			for i := 0; i < len(result); i += maxChunk {
				end := i + maxChunk
				isLast := end >= len(result)
				if end > len(result) {
					end = len(result)
				}
				chunk := result[i:end]
				title := toolName + " result"
				if !isLast {
					title = fmt.Sprintf("%s result (part %d)", toolName, i/maxChunk+1)
				}
				collapsed := platform.FormatCollapsible(title, chunk)
				msgID, err := mc.platform.Send(context.Background(), msg.ChannelID, collapsed, "")
				if err == nil && ph != nil {
					ph.MessageID = msgID
				}
			}
		},
		OnToolExec: func(tool string, dur time.Duration, toolErr error) {
			result := "ok"
			if toolErr != nil {
				result = "hard_error"
			}
			mc.svc.Metrics.EmitDuration("tool.exec", dur, map[string]string{"tool": tool, "result": result})
		},
	}

	// When Brain is supervising, disable self-review and self-finalize.
	if useBrain {
		opts.BrainFinalize = nil
		opts.BrainReview = nil
	}

	// Tag the supervisor ctx with PriorityUser so all downstream DTC calls
	// (brainFinalize, brainReview, deep_think, consult_deep_thinker) acquire
	// the Brain slot ahead of background cognitive work.
	supCtx := engine.WithPriority(context.Background(), engine.PriorityUser)
	reply, msgs, err := llm.QuerySupervisor(supCtx, choice.Client, choice.Model, userPrompt, progressExec, mc.lb.TrimFn, &opts)

	// Build thinking text for the collapsible block at the bottom of the reply.
	// Includes strategic guidance (if any) + the 9B's reasoning.
	thinkingMu.Lock()
	thinkingText := thinkingBuf.String()
	thinkingMu.Unlock()
	var thinkingBlock string
	{
		var parts []string
		if strategicGuidance != "" {
			parts = append(parts, "Strategic guidance:\n"+strategicGuidance)
		}
		if thinkingText != "" {
			clean := strings.TrimSpace(thinkingText)
			clean = strings.ReplaceAll(clean, "</think>", "")
			clean = strings.ReplaceAll(clean, "<think>", "")
			clean = strings.TrimSpace(clean)
			if clean != "" {
				parts = append(parts, clean)
			}
		}
		if len(parts) > 0 {
			thinkingBlock = platform.FormatCollapsible("Thinking", strings.Join(parts, "\n\n"))
		}
	}

	// Check for BackgroundJobRequest — spawn a background Brain job.
	var bjr *supervisor.BackgroundJobRequest
	if errors.As(err, &bjr) {
		choice.Release()
		acquired = false
		typingCancel()

		userGoal := bjr.UserGoal
		if bjr.ProblemStatement != "" {
			userGoal = bjr.ProblemStatement
		}
		job := mc.svc.StateMgr.CreateJob(bjr.Tool, userGoal, msg.ChannelID)
		job.TaskType = bjr.TaskType

		ack := brainSessionAcks[bjr.Tool]
		if ack == "" {
			ack = "Working on that in the background..."
		}
		mc.platform.Send(context.Background(), msg.ChannelID, ack, msg.ID)

		// Store the user message in conversation state.
		mc.svc.StateMgr.AppendMessage(llm.Message{Role: "user", Content: msgText})
		mc.svc.StateMgr.AppendMessage(llm.Message{Role: "assistant", Content: ack})

		go runBackgroundJob(mc, job)
		return
	}

	typingCancel()

	mc.svc.Metrics.Since("message.total", messageStart, map[string]string{"path": "supervisor"})

	toolCtx, toolsUsed := summarizeToolContext(msgs)

	// Track tool co-occurrence for selection learning.
	if mc.selector != nil && toolsUsed {
		usedTools := extractToolNames(msgs)
		if len(usedTools) > 0 {
			mc.selector.TrackToolRun(usedTools)
		}
	}

	// Append thinking block to the reply so it appears at the bottom.
	if thinkingBlock != "" && reply != "" && !strings.Contains(reply, "<NO_ACTION_REQUIRED>") {
		reply = reply + "\n\n" + thinkingBlock
	}
	// Clear the streaming thinking from the progress message since it's
	// now included in the reply. Update to a brief note so it's not blank.
	if ph != nil && thinkingBlock != "" {
		ph.Update(context.Background(), "Done")
	}

	completeMessageHandling(mc, msg, messageResult{
		Reply:             reply,
		Messages:          condenseToolResults(msgs),
		ToolContext:       toolCtx,
		ToolsUsed:         toolsUsed,
		MsgText:           msgText,
		PrefetchIDs:       pf.ids,
		PrefetchSummaries: pf.summaries,
		PipelineID:        pipelineID,
		Err:               err,
	})
}

// ---------------------------------------------------------------------------
// Shared post-processing for both Brain and dispatch paths.
// ---------------------------------------------------------------------------

// messageResult normalizes the output of the supervisor path so that
// completeMessageHandling can apply identical post-processing.
type messageResult struct {
	Reply             string        // final text reply to send
	Messages          []llm.Message // condensed messages for state
	ToolContext       string        // summarized tool usage for triage
	ToolsUsed         bool          // whether tools were called
	MsgText           string        // original user message text
	PrefetchIDs       []int64       // memory IDs from prefetch
	PrefetchSummaries string        // memory summaries from prefetch
	PipelineID        int64         // message ID for memory isolation
	Err               error         // LLM/execution error (nil on success)
}

// completeMessageHandling runs shared post-processing after the supervisor:
// append to state, slide/archive, triage, memory usefulness evaluation,
// error fallback, and send reply.
func completeMessageHandling(mc messageContext, msg *platform.IncomingMessage, mr messageResult) {
	// Append messages to conversation state.
	for _, m := range mr.Messages {
		mc.svc.StateMgr.AppendMessage(m)
	}

	// Slide and archive (token-budget-aware).
	if db.Pool != nil && mc.cfg.EmbedURL != "" {
		engine.SlideAndArchiveContext(context.Background(), mc.svc.StateMgr, engine.ArchiveDeps{
			DB: db.Pool, EmbedEndpoint: mc.cfg.EmbedURL, EmbedModel: mc.cfg.EmbedModel,
			MemoryFuncs: engine.MemoryFuncs{
				DTCQueueFn: mc.svc.DTCQueueFunc, SubagentFn: mc.svc.SubagentFunc,
				GrammarFn: mc.svc.GrammarFunc, BgGrammarFn: mc.svc.BgGrammarFunc, QueueFn: mc.svc.QueueFunc,
			},
			PipelineID:  mr.PipelineID,
			Tokenizer:   mc.lb.Client,
			TokenBudget: mc.cfg.ContextTokenBudget,
		})
	}

	// Queue triage for deferred processing during heartbeat ticks.
	// This keeps the Brain prompt cache warm for interactive messages.
	if mr.Err == nil && db.Pool != nil && mc.cfg.EmbedURL != "" && mc.svc.DTC != nil && mc.triageCfg != nil {
		exchange := mr.ToolContext + fmt.Sprintf("user: %s\nassistant: %s", mr.MsgText, mr.Reply)
		pipelines.EnqueueConversationTriage(db.Pool, exchange, mr.ToolsUsed, mr.PipelineID)
	}

	// Record pipeline ID so the next message's prefetch can exclude stale memories.
	if mr.PipelineID != 0 {
		mc.svc.StateMgr.SetLastPipelineID(mr.PipelineID)
	}

	// Memory usefulness evaluation.
	if mr.Err == nil && len(mr.PrefetchIDs) > 0 && db.Pool != nil && mc.svc.Subagent != nil {
		capturedIDs := mr.PrefetchIDs
		capturedReply := mr.Reply
		capturedMsgText := mr.MsgText
		capturedSubagent := mc.svc.Subagent
		capturedSummaries := mr.PrefetchSummaries
		go evaluateMemoryUsefulnessViaSubagent(db.Pool, capturedSubagent, capturedIDs, capturedMsgText, capturedReply, capturedSummaries)
	}

	reply := mr.Reply
	if mr.Err != nil {
		logger.Log.Errorf("LLM error: %v", mr.Err)
		reply = "Sorry, something went wrong processing your message."
	}

	// Don't send supervisor control tags to the user.
	if strings.Contains(reply, "<NO_ACTION_REQUIRED>") {
		return
	}

	// Send reply via platform (handles formatting + fallback internally).
	if _, err := mc.platform.Send(context.Background(), msg.ChannelID, reply, msg.ID); err != nil {
		logger.Log.Errorf("Error sending message: %v", err)
	}

	// Emit curiosity signal when the supervisor expressed uncertainty.
	emitConversationGapSignal(mc.eng, reply)
}

// formatToolDisplay formats a tool call summary for Telegram display.
// Single calls with long content get wrapped in a collapsible block.
// Parallel calls (joined by " + ") get one collapsible block with all commands listed.
func formatToolDisplay(toolSummary string) string {
	// Parallel calls: wrap all commands in a single collapsible block.
	if strings.Contains(toolSummary, " + ") {
		parts := strings.Split(toolSummary, " + ")
		// Build a title from unique tool names and list commands inside.
		seen := make(map[string]struct{})
		var names []string
		var sb strings.Builder
		for _, part := range parts {
			part = strings.TrimSpace(part)
			if idx := strings.Index(part, ": "); idx > 0 {
				name := part[:idx]
				if _, ok := seen[name]; !ok {
					seen[name] = struct{}{}
					names = append(names, name)
				}
				sb.WriteString(part[idx+2:])
			} else {
				sb.WriteString(part)
			}
			sb.WriteByte('\n')
		}
		title := fmt.Sprintf("%s (%d calls)", strings.Join(names, "+"), len(parts))
		return platform.FormatCollapsible(title, strings.TrimSpace(sb.String()))
	}

	// Single call: wrap in collapsible if long.
	if len(toolSummary) > 100 {
		if idx := strings.Index(toolSummary, ": "); idx > 0 {
			title := toolSummary[:idx]
			content := toolSummary[idx+2:]
			return platform.FormatCollapsible(title, content)
		}
	}
	return toolSummary
}

// uncertaintyPatterns matches replies where the supervisor expressed a knowledge gap.
var uncertaintyPatterns = regexp.MustCompile(`(?i)(I don't have (?:enough )?information|I'm not sure|I couldn't find|I don't know|I wasn't able to find|I lack information)`)

// nonResearchablePatterns matches gaps that are config/access issues, not knowledge gaps.
var nonResearchablePatterns = regexp.MustCompile(`(?i)(credential|password|SSH|login|authenticate|permission|access denied|allowlist|not in.*list|key|token)`)

// emitConversationGapSignal checks if the supervisor's reply indicates
// uncertainty and emits a curiosity signal for background research.
func emitConversationGapSignal(eng *engine.Engine, reply string) {
	if eng.CuriositySignals == nil || len(reply) < 20 {
		return
	}
	match := uncertaintyPatterns.FindString(reply)
	if match == "" {
		return
	}
	// Don't emit signals for config/access issues — those aren't researchable.
	if nonResearchablePatterns.MatchString(reply) {
		return
	}
	// Extract a topic hint from the reply (first 120 chars after the match).
	idx := strings.Index(reply, match)
	topic := reply
	if idx >= 0 {
		end := idx + len(match) + 120
		if end > len(reply) {
			end = len(reply)
		}
		topic = reply[idx:end]
	}
	select {
	case eng.CuriositySignals <- engine.CuriositySignal{
		Source:   "conversation",
		Query:    topic,
		Priority: 5,
	}:
		logger.Log.Debugf("[curiosity-signal] conversation gap detected: %s", textutil.Truncate(topic, 80))
	default:
		// Channel full, drop.
	}
}

// extractToolNames parses tool names from supervisor messages.
// Tool calls appear as assistant messages with JSON containing "name" fields.
func extractToolNames(msgs []llm.Message) []string {
	seen := make(map[string]struct{})
	var names []string
	for _, m := range msgs {
		if m.Role != "assistant" {
			continue
		}
		// Extract tool name from grammar-constrained JSON.
		var dec struct {
			Name  string `json:"name"`
			Calls []struct {
				Name string `json:"name"`
			} `json:"calls"`
		}
		if err := json.Unmarshal([]byte(m.Content), &dec); err != nil {
			continue
		}
		if dec.Name != "" && dec.Name != "respond" {
			if _, ok := seen[dec.Name]; !ok {
				seen[dec.Name] = struct{}{}
				names = append(names, dec.Name)
			}
		}
		for _, c := range dec.Calls {
			if c.Name != "" {
				if _, ok := seen[c.Name]; !ok {
					seen[c.Name] = struct{}{}
					names = append(names, c.Name)
				}
			}
		}
	}
	return names
}

// extractReflectionForPrompt pulls PATTERNS and PREDICTIONS from a reflection for supervisor injection.
func extractReflectionForPrompt(summary string) string {
	var result strings.Builder
	lines := strings.Split(summary, "\n")
	capturing := false
	for _, line := range lines {
		trimmed := strings.TrimSpace(line)
		if strings.HasPrefix(trimmed, "**PATTERNS**") || strings.HasPrefix(trimmed, "**PREDICTIONS**") {
			capturing = true
			result.WriteString(trimmed)
			result.WriteByte('\n')
			continue
		}
		if strings.HasPrefix(trimmed, "**") && capturing {
			capturing = false
		}
		if capturing && trimmed != "" {
			result.WriteString(trimmed)
			result.WriteByte('\n')
		}
	}
	s := strings.TrimSpace(result.String())
	// Cap at ~500 chars to avoid bloating the prompt.
	if len(s) > 500 {
		s = s[:500] + "..."
	}
	return s
}