Skip to content

Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.

60.0 KB
Raw Blame
package agent

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

	"github.com/Tencent/WeKnora/internal/agent/collaboration"
	"github.com/Tencent/WeKnora/internal/agent/compaction"
	"github.com/Tencent/WeKnora/internal/agent/skills"
	agenttoken "github.com/Tencent/WeKnora/internal/agent/token"
	agenttools "github.com/Tencent/WeKnora/internal/agent/tools"
	"github.com/Tencent/WeKnora/internal/common"
	appconfig "github.com/Tencent/WeKnora/internal/config"
	"github.com/Tencent/WeKnora/internal/event"
	"github.com/Tencent/WeKnora/internal/logger"
	"github.com/Tencent/WeKnora/internal/modelcontext"
	"github.com/Tencent/WeKnora/internal/models/chat"
	"github.com/Tencent/WeKnora/internal/sandbox"
	"github.com/Tencent/WeKnora/internal/tracing/langfuse"
	"github.com/Tencent/WeKnora/internal/types"
)

// langfuseQueryPreview caps the query length we ship as the agent.execute
// span input — long quoted-context queries can be many KB of prose.
const langfuseQueryPreview = 2000

// AgentEngine is the core engine for running ReAct agents.
//
// History persistence note: the engine is stateless across turns. Conversation
// history is rebuilt from the DB once per turn by the caller
// (see service.LoadAgentHistory) and passed into Execute as llmContext. The
// engine therefore does not maintain its own cache, system-prompt store, or
// cross-turn buffer.
type AgentEngine struct {
	collaboration        *collaboration.Binding
	config               *types.AgentConfig
	toolRegistry         *agenttools.ToolRegistry
	chatModel            chat.Chat
	eventBus             *event.EventBus
	knowledgeBasesInfo   []*KnowledgeBaseInfo    // Detailed knowledge base information for prompt
	selectedDocs         []*SelectedDocumentInfo // User-selected documents (via @ mention)
	pinnedMCPServices    []*PinnedMCPServiceInfo // User @mentioned MCP services for this turn
	pinnedSkills         []*PinnedSkillInfo      // User @mentioned skills for this turn
	questionOrigin       *QuestionOriginInfo     // Source of a picked suggested question, if any
	pageContext          *PageContextInfo        // Page the user has open, if any
	assistantName        string                  // Workspace name for the assistant, if renamed
	sessionID            string                  // Session ID for logging and event emission
	systemPromptTemplate string                  // System prompt template (optional, uses default if empty)
	memoryPrompt         string                  // Long-term memory envelope appended to the system prompt
	runNote              string                  // How this run was started; see SetRunNote
	skillsManager        *skills.Manager         // Skills manager for Progressive Disclosure (optional)
	appConfig            *appconfig.Config       // Application config for prompt template resolution (optional)
	imageDescriber       ImageDescriberFunc      // VLM function for describing images in tool results (optional)
	imageDescribeSlots   chan struct{}           // Bounds VLM calls across parallel tool calls
	tokenEstimator       *agenttoken.Estimator   // Token estimator for context window management, calibrated
	rawEstimator         *agenttoken.Estimator   // Same tokenizer at scale 1, for measuring the calibration
	compactor            *compaction.Compactor   // Summarizes older history to fit the context window (nil = disabled)
	lastUsage            types.TokenUsage        // Token usage from the most recent LLM call
	lastSentMsgCount     int                     // Number of messages sent in the most recent LLM call
	// overflowRecovered records that this turn already spent its one
	// compact-and-retry on a context overflow. A second attempt would mean
	// history size was never the problem, and looping on it burns the round
	// budget without changing anything.
	overflowRecovered bool
	// compactionExhaustedAt is the message count at which compaction last
	// reported it could free nothing. Below that count the answer has not
	// changed, so there is no reason to spend another summarization call.
	compactionExhaustedAt int
	// checkpointSink, when set, persists compactions that end on a stored
	// turn so later turns start from them. Nil keeps compaction turn-local.
	checkpointSink types.ContextCheckpointSink
	// calibration learns the provider's tokens per estimated token from
	// consecutive requests (see calibrateEstimator).
	calibration tokenCalibration
	// contextRewrites counts compactions and tool-result trims. Either one
	// changes messages an earlier request already sent, so the next request
	// cannot be compared with that one for calibration.
	contextRewrites int
	modelContext    *modelcontext.Registry // single request-local boundary for every model handle
	// steerSink, when set, lets users append messages into the running turn.
	// Drained at every round boundary; nil disables mid-run injection.
	steerSink         types.SteerSink
	allowSteerOverrun bool // one extra ReAct round after a loop-end inject past MaxIterations
	steerOverruns     int  // how many times this turn has already used the extra round
	// backgroundRun, when set, supplies background-work notices and reminders
	// at the same two boundaries as steer. Nil disables them.
	backgroundRun   BackgroundRun
	workspaceLayout sandbox.WorkspaceLayout
	// suspendable lets a user prompt end the run so it can be resumed later;
	// suspendRequest is saved with the run for that (see EnableSuspension).
	suspendable    bool
	suspendRequest []byte
	// collaborationOnlySuspension limits suspension to collaboration waits.
	collaborationOnlySuspension bool
	// mode: whether the client renders prompt cards and can answer them.
	mode     types.RunMode
	progress turnProgress
	// Hold speculative parent prose until delegated work has been reviewed.
	holdCollaborationAnswer bool
}

// maxSteerOverruns caps loop-end injects past MaxIterations. One extra round
// lets a last-moment nudge (a steered message or a background reminder) revise
// the answer; further injects stay queued for a follow-up turn instead of
// stretching the same run indefinitely.
const maxSteerOverruns = 1

// ImageDescriberFunc generates a text description of an image.
// Signature matches vlm.VLM.Predict so it can be injected without importing the vlm package.
type ImageDescriberFunc func(ctx context.Context, imgBytes []byte, prompt string) (string, error)

// NewAgentEngine creates a new agent engine
func NewAgentEngine(
	config *types.AgentConfig,
	chatModel chat.Chat,
	toolRegistry *agenttools.ToolRegistry,
	eventBus *event.EventBus,
	knowledgeBasesInfo []*KnowledgeBaseInfo,
	selectedDocs []*SelectedDocumentInfo,
	sessionID string,
	systemPromptTemplate string,
) *AgentEngine {
	if eventBus == nil {
		eventBus = event.NewEventBus()
	}
	tokenEst, err := agenttoken.NewEstimator()
	if err != nil {
		return nil
	}
	// The previous turn's measured scale, so this turn's first compaction
	// check is calibrated before it has a provider count of its own.
	tokenEst.SetScale(config.ContextTokenScale)
	engine := &AgentEngine{
		config:               config,
		toolRegistry:         toolRegistry,
		chatModel:            chatModel,
		eventBus:             eventBus,
		knowledgeBasesInfo:   knowledgeBasesInfo,
		selectedDocs:         selectedDocs,
		sessionID:            sessionID,
		systemPromptTemplate: systemPromptTemplate,
		tokenEstimator:       tokenEst,
		rawEstimator:         tokenEst.Unscaled(),
		modelContext:         modelcontext.NewRegistry(config.CitationsEnabled()),
	}

	engine.compactor = compaction.New(chatModel, tokenEst, compaction.Settings{
		Enabled:          true,
		MaxContextTokens: config.MaxContextTokens,
		ReserveTokens:    engine.contextReserveTokens(),
		KeepRecentTokens: config.CompactionKeepRecentTokens,
		MaxSummaryTokens: engine.getCompletionTokenBudget(),
		StallTimeout:     engine.getLLMStallTimeout(),
	})

	return engine
}

// SetQuestionOrigin records the knowledge source of a suggested question the
// user picked for this turn; nil clears it.
func (e *AgentEngine) SetQuestionOrigin(origin *QuestionOriginInfo) {
	e.questionOrigin = origin
}

// SetPageContext records the WeKnora page the user has open for this turn;
// nil clears it.
func (e *AgentEngine) SetPageContext(page *PageContextInfo) {
	e.pageContext = page
}

// SetAssistantName records the name the workspace gave the assistant; empty
// keeps the one in the system prompt.
func (e *AgentEngine) SetAssistantName(name string) {
	e.assistantName = name
}

// SetPinnedMentions sets per-turn @mention scope for MCP services and skills.
func (e *AgentEngine) SetPinnedMentions(mcpServices []*PinnedMCPServiceInfo, skills []*PinnedSkillInfo) {
	e.pinnedMCPServices = mcpServices
	e.pinnedSkills = skills
}

// SetWorkspaceLayout injects the session's real workspace into the system
// prompt. Host sessions must pass the user directory so the model does not
// keep listing /workspace.
func (e *AgentEngine) SetWorkspaceLayout(layout sandbox.WorkspaceLayout) {
	if e == nil {
		return
	}
	e.workspaceLayout = layout
}

func (e *AgentEngine) systemPromptOptions(ctx context.Context) *BuildSystemPromptOptions {
	opts := &BuildSystemPromptOptions{
		Language:         types.LanguageNameFromContext(ctx),
		Config:           e.appConfig,
		SkillInstallMode: e.config.SkillInstallMode(),
		MemoryPrompt:     e.memoryPrompt,
		ProtocolPrompt:   e.modelContext.ProtocolPrompt(),
		WorkspaceLayout:  e.workspaceLayout,
	}
	if e.skillsManager != nil && e.skillsManager.IsEnabled() {
		opts.SkillsMetadata = e.skillsManager.GetAllMetadata()
	}
	if e.toolRegistry != nil {
		opts.SelectedTools = e.toolRegistry.ListTools()
		if _, err := e.toolRegistry.GetTool("local_browser"); err == nil {
			metadata := make([]*skills.SkillMetadata, 0, len(opts.SkillsMetadata))
			for _, item := range opts.SkillsMetadata {
				if item != nil && item.Name != "browser" && item.Name != "browser-skill" {
					metadata = append(metadata, item)
				}
			}
			opts.SkillsMetadata = metadata
		}
		_, err := e.toolRegistry.GetTool(agenttools.ToolShellExec)
		opts.ShellExecEnabled = err == nil
	}
	return opts
}

func (e *AgentEngine) buildSystemPrompt(ctx context.Context) string {
	sections := BuildSystemPromptSections(
		e.knowledgeBasesInfo,
		e.config.WebSearchEnabled,
		e.systemPromptOptions(ctx),
		e.systemPromptTemplate,
	)
	for _, section := range sections {
		logger.Debugf(ctx, "[Agent][Prompt] section=%s bytes=%d", section.Name, len(section.Content))
	}
	prompt := renderSystemPromptSections(sections) + e.collaborationGuidance()
	if e.runNote != "" {
		prompt += "\n\n" + e.runNote
	}
	return prompt
}

// SetRunNote adds note to the end of this run's system prompt.
func (e *AgentEngine) SetRunNote(note string) {
	e.runNote = strings.TrimSpace(note)
}

// SetMemoryPrompt supplies the long-term memory envelope for this run. Empty
// input leaves the system prompt untouched.
func (e *AgentEngine) SetMemoryPrompt(prompt string) {
	e.memoryPrompt = prompt
}

// NewAgentEngineWithSkills creates a new agent engine with skills support
func NewAgentEngineWithSkills(
	config *types.AgentConfig,
	chatModel chat.Chat,
	toolRegistry *agenttools.ToolRegistry,
	eventBus *event.EventBus,
	knowledgeBasesInfo []*KnowledgeBaseInfo,
	selectedDocs []*SelectedDocumentInfo,
	sessionID string,
	systemPromptTemplate string,
	skillsManager *skills.Manager,
) *AgentEngine {
	engine := NewAgentEngine(
		config,
		chatModel,
		toolRegistry,
		eventBus,
		knowledgeBasesInfo,
		selectedDocs,
		sessionID,
		systemPromptTemplate,
	)
	engine.skillsManager = skillsManager
	return engine
}

// SetAppConfig sets the application config for prompt template resolution.
// This allows the engine to read default prompts from config/prompt_templates/ YAML files.
func (e *AgentEngine) SetAppConfig(cfg *appconfig.Config) {
	e.appConfig = cfg
}

// SetImageDescriber sets the VLM function for generating text descriptions of images
// in tool results. When set and the chat model cannot view images, tool result
// images are described while their tool call runs and the descriptions are
// appended to the tool message content.
func (e *AgentEngine) SetImageDescriber(fn ImageDescriberFunc) {
	e.imageDescriber = fn
	e.imageDescribeSlots = make(chan struct{}, toolImageDescribeConcurrency)
}

// describeToolImages runs inside the tool call, so the UI keeps showing the
// call as running while the vision model works and the description lands in
// the tool result the user sees.
func (e *AgentEngine) describeToolImages(ctx context.Context, result *types.ToolResult) {
	if result == nil || !result.Success || len(result.Images) == 0 || e.imageDescriber == nil ||
		(e.config != nil && e.config.ChatModelSupportsVision) {
		return
	}
	if len(result.ImageDescriptions) != len(result.Images) {
		result.ImageDescriptions = e.describeImages(ctx, result.Images, toolImagePrompts(result))
	}
	if result.Data != nil {
		result.Data["image_descriptions"] = result.ImageDescriptions
	}
}

// SetSkillsManager sets the skills manager for the engine
func (e *AgentEngine) SetSkillsManager(manager *skills.Manager) {
	e.skillsManager = manager
}

// GetSkillsManager returns the skills manager
func (e *AgentEngine) GetSkillsManager() *skills.Manager {
	return e.skillsManager
}

// estimateCurrentTokens returns the best estimate of the current context token
// count:
//
//   - When API usage from a previous round is available, that number is the
//     baseline (the provider already billed tools + system + history) and only
//     the messages appended since then are BPE-estimated.
//   - Otherwise it is a pure message-size estimate. Tool schemas are NOT
//     added here. Adding 232 tool schemas (~105k) to a 12k conversation made
//     every round look over the 111k threshold even after a successful
//     compaction.
//
// The baseline already contains the assistant reply, as the `output` half of
// the round that produced it. So the delta must start *after* that reply.
func (e *AgentEngine) estimateCurrentTokens(messages []chat.Message) int {
	if baseline := contextTokensFromUsage(e.lastUsage); baseline > 0 &&
		e.lastSentMsgCount > 0 && e.lastSentMsgCount <= len(messages) {
		return baseline + e.tokenEstimator.EstimateMessages(messages[e.deltaStart(messages):])
	}
	return e.tokenEstimator.EstimateMessages(messages)
}

// deltaStart is the first message not already accounted for by e.lastUsage.
func (e *AgentEngine) deltaStart(messages []chat.Message) int {
	start := e.lastSentMsgCount
	// The reply to the previous request lands here. Its tokens are the usage's
	// completion half, so skip it — but only if it is really there, since a
	// failed round appends nothing.
	if start < len(messages) && messages[start].Role == "assistant" {
		start++
	}
	return start
}

// contextTokensFromUsage reduces a usage report to the size of the context it
// describes. Cache counters are not added in: WeKnora normalizes PromptTokens
// to the provider's full input count, with read/write/miss as descriptive
// subsets of it (see types.TokenUsage.SetPromptCacheUsage).
func contextTokensFromUsage(usage types.TokenUsage) int {
	if usage.TotalTokens > 0 {
		return usage.TotalTokens
	}
	return usage.PromptTokens + usage.CompletionTokens
}

// Execute executes the agent with conversation history and streaming output
// All events are emitted to EventBus and handled by subscribers (like Handler layer)
func (e *AgentEngine) Execute(
	ctx context.Context,
	sessionID, messageID, query string,
	llmContext []chat.Message,
	imageURLs ...[]string,
) (*types.AgentState, error) {
	logger.Infof(ctx, "[Agent] Starting execution: session=%s, message=%s, query_len=%d, context_msgs=%d",
		sessionID, messageID, len(query), len(llmContext))
	// Ensure tools are cleaned up after execution
	defer e.toolRegistry.Cleanup(ctx)

	common.PipelineInfo(ctx, "Agent", "execute_start", map[string]interface{}{
		"session_id":   sessionID,
		"message_id":   messageID,
		"query":        query,
		"context_msgs": len(llmContext),
	})

	// Open a top-level Langfuse span so the agent run — including every
	// round's LLM call and every tool execution — groups under a single
	// node in the Langfuse UI instead of being flat children of the HTTP
	// trace. No-op when Langfuse is disabled.
	imgCount := 0
	if len(imageURLs) > 0 {
		imgCount = len(imageURLs[0])
	}
	kbIDs := make([]string, 0, len(e.knowledgeBasesInfo))
	for _, kb := range e.knowledgeBasesInfo {
		if kb != nil {
			kbIDs = append(kbIDs, kb.ID)
		}
	}
	spanCtx, agentSpan := langfuse.GetManager().StartSpan(ctx, langfuse.SpanOptions{
		Name: "agent.execute",
		Input: map[string]interface{}{
			"query":        truncateRunes(query, langfuseQueryPreview),
			"query_len":    len(query),
			"context_msgs": len(llmContext),
			"image_count":  imgCount,
		},
		Metadata: map[string]interface{}{
			"session_id":          sessionID,
			"message_id":          messageID,
			"max_iterations":      e.config.MaxIterations,
			"parallel_tool_calls": e.config.ParallelToolCalls,
			"web_search":          e.config.WebSearchEnabled,
			"multi_turn":          e.config.MultiTurnEnabled,
			"knowledge_base_ids":  kbIDs,
			"allowed_tools":       e.config.AllowedTools,
		},
	})
	ctx = spanCtx

	// Initialize state
	state := &types.AgentState{
		RoundSteps:    []types.AgentStep{},
		KnowledgeRefs: []*types.SearchResult{},
		IsComplete:    false,
		CurrentRound:  0,
		// A turn that measures no scale of its own (no tool call, so no two
		// requests to compare) passes on the one it started from, so the
		// newest turn always carries the latest known scale and the loader
		// never has to look past its first page for one.
		TurnUsage: types.TokenUsage{ContextTokenScale: e.config.ContextTokenScale},
	}

	// Build system prompt using progressive RAG prompt
	// If skills are enabled, include skills metadata (Level 1 - Progressive Disclosure)
	systemPrompt := e.buildSystemPrompt(ctx)
	logger.Debugf(ctx, "[Agent] SystemPrompt: %d chars", len(systemPrompt))

	// Initialize messages with history
	var imgs []string
	if len(imageURLs) > 0 {
		imgs = imageURLs[0]
	}
	e.beginTurn(query, imgs, state)
	messages := e.buildMessagesWithLLMContext(systemPrompt, query, sessionID, llmContext, imgs)
	if e.toolRegistry != nil {
		e.toolRegistry.RememberMCPHistory(messages)
		e.toolRegistry.RefreshMCPTools(ctx)
	}

	// Get tool definitions for function calling
	tools := e.buildToolsForLLM()
	toolListStr := strings.Join(listToolNames(tools), ", ")
	logger.Infof(ctx, "[Agent] Ready: %d messages, %d tools [%s], mcp_catalog=%d chars, %d images",
		len(messages), len(tools), toolListStr, mcpCatalogDescriptionLen(tools), len(imgs))
	common.PipelineInfo(ctx, "Agent", "tools_ready", map[string]interface{}{
		"session_id": sessionID,
		"tool_count": len(tools),
		"tools":      toolListStr,
	})

	_, err := e.executeLoop(ctx, state, query, messages, tools, sessionID, messageID)
	if err != nil {
		logger.Errorf(ctx, "[Agent] Execution failed: %v", err)
		e.eventBus.Emit(ctx, event.Event{
			ID:        generateEventID("error"),
			Type:      event.EventError,
			SessionID: sessionID,
			Data: event.ErrorData{
				Error:     err.Error(),
				Stage:     "agent_execution",
				SessionID: sessionID,
			},
		})
		finishAgentSpan(agentSpan, state, err)
		return nil, err
	}

	logger.Infof(ctx, "[Agent] Completed: %d rounds, %d steps, complete=%v",
		state.CurrentRound, len(state.RoundSteps), state.IsComplete)
	common.PipelineInfo(ctx, "Agent", "execute_complete", map[string]interface{}{
		"session_id": sessionID,
		"rounds":     state.CurrentRound,
		"steps":      len(state.RoundSteps),
		"complete":   state.IsComplete,
	})
	finishAgentSpan(agentSpan, state, nil)
	return state, nil
}

// finishAgentSpan records the final outcome of an agent execution onto the
// top-level Langfuse span. Extracted so the same payload is used for both
// success and error return paths in Execute().
func finishAgentSpan(span *langfuse.Span, state *types.AgentState, err error) {
	if span == nil {
		return
	}
	totalToolCalls := 0
	for _, step := range state.RoundSteps {
		totalToolCalls += len(step.ToolCalls)
	}
	output := map[string]interface{}{
		"rounds":           state.CurrentRound,
		"steps":            len(state.RoundSteps),
		"tool_calls":       totalToolCalls,
		"complete":         state.IsComplete,
		"final_answer_len": len(state.FinalAnswer),
		"final_answer":     truncateRunes(state.FinalAnswer, langfuseQueryPreview),
	}
	span.Finish(output, map[string]interface{}{
		"rounds":     state.CurrentRound,
		"steps":      len(state.RoundSteps),
		"tool_calls": totalToolCalls,
		"complete":   state.IsComplete,
	}, err)
}

// truncateRunes caps s to n runes and appends "…" when truncated. Identical
// in spirit to the helper in act.go, but kept locally so both files stay
// independent and the truncation budget can diverge if needed.
func truncateRunes(s string, n int) string {
	if n <= 0 || s == "" {
		return s
	}
	r := []rune(s)
	if len(r) <= n {
		return s
	}
	return string(r[:n]) + "…"
}

// withinIterationBudget reports whether another ReAct round is allowed.
// A negative MaxIterations is unlimited: the loop still stops on a natural
// finish, user cancel, empty-response retries, or a repeated-content stall.
func (e *AgentEngine) withinIterationBudget(round int) bool {
	if e.config == nil {
		return false
	}
	if e.config.UnlimitedIterations() {
		return true
	}
	return round < e.config.MaxIterations
}

// loopGuards is the per-turn state the ReAct loop uses to notice it is not
// making progress. The counters cover empty answers, repeated answers,
// completion-token cutoffs, and identical failed tool calls.
type loopGuards struct {
	// emptyRetries counts nudges sent after a stop with no content.
	emptyRetries         int
	pendingRuntimeNotice string
	childAnswerRevised   bool
	// consecutiveSameContent counts plain rounds that repeated the previous
	// plain round verbatim, an identical lack of content included.
	consecutiveSameContent int
	// sawPlainRound records whether lastResponseContent holds a real
	// observation yet, so the first plain round of a turn is never counted as
	// a repeat of the zero value.
	sawPlainRound       bool
	lastResponseContent string
	// consecutiveLength counts rounds in a row that the provider cut off at
	// the completion-token cap.
	consecutiveLength int
	// failedToolCallSignature and consecutiveFailedToolCalls track identical
	// failed calls across rounds. A single guidance message is sent per streak.
	failedToolCallSignature    string
	consecutiveFailedToolCalls int
	failedToolCallNudged       bool
}

// recordFailedToolCall tracks consecutive failures of the same model-facing
// tool name and arguments. A successful or different call breaks the streak.
func (g *loopGuards) recordFailedToolCall(call types.ToolCall) (string, int, bool) {
	if call.Result != nil && call.Result.Success {
		g.resetFailedToolCallStreak()
		return "", 0, false
	}
	if call.Name == "" {
		g.resetFailedToolCallStreak()
		return "", 0, false
	}
	args, err := json.Marshal(call.Args)
	if err != nil {
		g.resetFailedToolCallStreak()
		return "", 0, false
	}
	signature := call.Name + "\x00" + string(args)
	if signature != g.failedToolCallSignature {
		g.failedToolCallSignature = signature
		g.consecutiveFailedToolCalls = 1
		g.failedToolCallNudged = false
	} else {
		g.consecutiveFailedToolCalls++
	}
	if g.consecutiveFailedToolCalls >= maxConsecutiveFailedToolCalls && !g.failedToolCallNudged {
		g.failedToolCallNudged = true
		return call.Name, g.consecutiveFailedToolCalls, true
	}
	return "", g.consecutiveFailedToolCalls, false
}

func (g *loopGuards) resetFailedToolCallStreak() {
	g.failedToolCallSignature = ""
	g.consecutiveFailedToolCalls = 0
	g.failedToolCallNudged = false
}

// closeAnswerStream emits the Done:true marker for an answer that is actually
// finishing. Loop-end inject skips this so the client does not drop isReplying
// while the engine continues. truncated rides along on the marker because an
// answer streamed live only finds out about the completion cap at the close.
func (e *AgentEngine) closeAnswerStream(ctx context.Context, sessionID, answerID string, truncated bool) {
	if e.eventBus == nil || answerID == "" {
		return
	}
	_ = e.eventBus.Emit(ctx, event.Event{
		ID:        answerID,
		Type:      event.EventAgentFinalAnswer,
		SessionID: sessionID,
		Data: event.AgentFinalAnswerData{
			Content:   "",
			Done:      true,
			Truncated: truncated,
		},
	})
}

// finishStalledTurn ends a turn that a guard stopped rather than the model.
// Whatever text the last round produced stands as the answer; when the round
// produced none, a fallback says why instead of completing with an empty
// message. The answer stream is closed here because no natural-stop path will
// reach it once the loop breaks.
func (e *AgentEngine) finishStalledTurn(
	ctx context.Context,
	state *types.AgentState,
	sessionID string,
	response *types.ChatResponse,
	truncated bool,
) {
	// Text that arrived alongside tool calls is a preamble — "let me look that
	// up" — from a round that meant to keep working. Presenting it as the final
	// answer would show an opening line and call the turn finished, so the
	// fallback speaks for it instead.
	answer := response.Content
	if len(response.ToolCalls) > 0 {
		answer = ""
	}
	answerID := ""
	if response.AnswerStreamed && answer != "" {
		answerID = response.AnswerEventID
	}
	if strings.TrimSpace(answer) == "" {
		answer = stalledAnswerFallback
		if truncated {
			answer = truncatedAnswerFallback
		}
		answerID = ""
	}
	// No answer stream reached the client for this text: the round never
	// streamed it, or it is the fallback just chosen. Emit it once so the turn
	// does not end on a Done marker for content the client never saw.
	if answerID == "" && e.eventBus != nil {
		answerID = generateEventID("answer")
		_ = e.eventBus.Emit(ctx, event.Event{
			ID:        answerID,
			Type:      event.EventAgentFinalAnswer,
			SessionID: sessionID,
			Data: event.AgentFinalAnswerData{
				Content:   answer,
				Done:      false,
				Truncated: truncated,
			},
		})
	}
	e.closeAnswerStream(ctx, sessionID, answerID, truncated)
	state.FinalAnswer = answer
	state.IsComplete = true
}

func (e *AgentEngine) maxIterationsDisplay() string {
	if e.config != nil && e.config.UnlimitedIterations() {
		return "unlimited"
	}
	n := 0
	if e.config != nil {
		n = e.config.MaxIterations
	}
	return fmt.Sprintf("%d", n)
}

// executeLoop executes the main ReAct loop
// All events are emitted through EventBus with the given sessionID
func (e *AgentEngine) executeLoop(
	ctx context.Context,
	state *types.AgentState,
	query string,
	messages []chat.Message,
	tools []chat.Tool,
	sessionID string,
	messageID string,
) (*types.AgentState, error) {
	if e.collaboration != nil {
		var stop func()
		ctx, stop = e.collaboration.Start(ctx)
		defer stop()
		e.bindCollaborationInput(sessionID, messageID)
	}
	startTime := time.Now()
	common.PipelineInfo(ctx, "Agent", "loop_start", map[string]interface{}{
		"max_iterations": e.config.MaxIterations,
	})

	// Guarantee exactly-one EventAgentComplete emission on every exit path
	// (normal finish, ctx cancel observed at the loop head, or iteration error
	// bubbling up while ctx was cancelled). The emission triggers
	// agent_stream_handler.handleComplete, which is where state.RoundSteps
	// (thinking + tool_call history) gets written onto assistantMessage.AgentSteps
	// so it can be persisted by the caller's defer. Use WithoutCancel so a
	// cancelled ctx does not short-circuit the emit on the stop path.
	completionEmitted := false
	emitCompletion := func() {
		if completionEmitted {
			return
		}
		completionEmitted = true
		e.emitCompletionEvent(context.WithoutCancel(ctx), state, sessionID, messageID, startTime)
	}
	defer emitCompletion()
	if e.collaboration != nil {
		defer func() {
			b := e.collaboration
			if b.Child == nil && ctx.Err() != nil && state.Suspended == nil {
				g, err := b.Runtime.Store.Read(context.WithoutCancel(ctx), b.Scope)
				if err == nil && g.Status == "active" && g.ParentWait != nil && g.ParentOwner == b.ParentOwner {
					state.Suspended = &types.PromptSuspension{
						PromptID: b.Scope.ID,
						Kind:     "collaboration_wait",
						Detached: true,
					}
				}
			}
			b.End(state.Suspended != nil)
		}()
	}

	if e.collaboration != nil && e.collaboration.Child == nil {
		if err := e.collaboration.Runtime.Store.Change(e.collaboration.Context(ctx),
			e.collaboration.Scope,
			func(g *collaboration.Group) error {
				if g.RootQuery == "" {
					g.RootQuery = string([]rune(query)[:min(len([]rune(query)), 16000)])
				}
				return nil
			}); err != nil {
			return state, err
		}
	}

	guards := &loopGuards{}
loop:
	for e.withinIterationBudget(state.CurrentRound) || e.allowSteerOverrun {
		e.allowSteerOverrun = false
		// Check for context cancellation (request timeout, user cancel, etc.)
		select {
		case <-ctx.Done():
			logger.Warnf(ctx, "[Agent] Context cancelled at round %d: %v",
				state.CurrentRound+1, ctx.Err())
			// Try to salvage existing results
			if totalTC := countTotalToolCalls(state.RoundSteps); totalTC > 0 {
				logger.Infof(ctx, "[Agent] Synthesizing final answer from %d existing tool results",
					totalTC)
				_ = e.streamFinalAnswerToEventBus(ctx, query, state, sessionID, messages)
				state.IsComplete = true
			}
			return state, ctx.Err()
		default:
		}

		// A slow startup, OAuth discovery or explicit refresh may have produced
		// new definitions since the previous response. Publish them only here,
		// after all previous tool calls have finished, and rebuild the wire list.
		if e.toolRegistry != nil {
			e.toolRegistry.RefreshMCPTools(ctx)
			tools = e.buildToolsForLLM()
		}

		// Each iteration runs inside an "agent.round.<N>" Langfuse span.
		// We execute the body in a closure so `defer span.Finish()` fires at
		// every exit path (break/continue/next) without having to sprinkle
		// manual finish calls throughout the many branches below.
		outcome, iterErr := e.runReActIteration(ctx, state, &messages, tools,
			sessionID, messageID, query, guards)
		if iterErr != nil {
			return state, iterErr
		}
		switch outcome {
		case iterOutcomeContinue:
			continue loop
		case iterOutcomeBreak:
			break loop
		case iterOutcomeNext:
			state.CurrentRound++
		}
	}

	// If loop finished without final answer, generate one — but skip this
	// when the context was cancelled (user pressed stop). In that case the
	// fallback LLM call would fail on the already-cancelled ctx and set
	// state.FinalAnswer to the generic "Sorry, I was unable to generate a
	// complete answer." message, which then leaks to the UI as the final
	// answer for a conversation the user deliberately stopped.
	// A suspended run has not finished either; it resumes once the user
	// answers, so no answer is synthesized for it.
	if !state.IsComplete && ctx.Err() == nil && state.Suspended == nil {
		if e.collaboration != nil && e.collaboration.Child == nil && e.collaborationOwnsFailure(ctx) {
			return state, fmt.Errorf("parent iteration budget exhausted; remaining delegated work was cancelled")
		}
		if err := e.handleMaxIterations(ctx, query, state, sessionID, messages); err != nil {
			return state, err
		}
	}

	return state, nil
}

// iterOutcome directs executeLoop's control flow after one ReAct iteration.
// Using a sentinel (rather than bare return values from runReActIteration)
// keeps the loop's break/continue/next branches explicit in one place.
type iterOutcome int

const (
	// iterOutcomeNext advances state.CurrentRound and loops again.
	iterOutcomeNext iterOutcome = iota
	// iterOutcomeContinue re-runs the loop without advancing the round
	// counter. Used by the empty-content retry path.
	iterOutcomeContinue
	// iterOutcomeBreak exits the loop (final answer, stuck loop, or end).
	iterOutcomeBreak
)

// runReActIteration executes one ReAct step: think → analyze → act → observe.
// Extracted from executeLoop so the whole iteration body can live inside a
// single `defer span.Finish()` scope — otherwise we'd need to sprinkle
// manual finish calls across every break/continue/return branch.
//
// The mutable loop state (messages and the no-progress guards) is shared
// across iterations so each round can see what the previous ones did.
func (e *AgentEngine) runReActIteration(
	parentCtx context.Context,
	state *types.AgentState,
	messagesPtr *[]chat.Message,
	tools []chat.Tool,
	sessionID, assistantMessageID, query string,
	guards *loopGuards,
) (outcome iterOutcome, retErr error) {
	roundStart := time.Now()
	round := state.CurrentRound + 1

	// Open the round-level Langfuse span. Any chat/tool calls made inside
	// this iteration will attach under it via ctx, giving the UI a clean
	// trace → agent.execute → agent.round.N → (chat + tools) structure.
	ctx, roundSpan := langfuse.GetManager().StartSpan(parentCtx, langfuse.SpanOptions{
		Name: fmt.Sprintf("agent.round.%d", round),
		Input: map[string]interface{}{
			"round":          round,
			"message_count":  len(*messagesPtr),
			"max_iterations": e.config.MaxIterations,
		},
		Metadata: map[string]interface{}{
			"iteration":  state.CurrentRound,
			"round":      round,
			"session_id": sessionID,
		},
	})

	var (
		response      *types.ChatResponse
		toolCallCount int
	)
	defer func() {
		if roundSpan == nil {
			return
		}
		out := map[string]interface{}{
			"round":      round,
			"outcome":    outcome.String(),
			"tool_calls": toolCallCount,
		}
		if response != nil {
			out["has_tool_calls"] = len(response.ToolCalls) > 0
			out["finish_reason"] = response.FinishReason
			out["content_len"] = len(response.Content)
			if response.Usage.TotalTokens > 0 {
				out["prompt_tokens"] = response.Usage.PromptTokens
				out["completion_tokens"] = response.Usage.CompletionTokens
				out["total_tokens"] = response.Usage.TotalTokens
			}
		}
		out["duration_ms"] = time.Since(roundStart).Milliseconds()
		roundSpan.Finish(out, map[string]interface{}{
			"round":       round,
			"tool_calls":  toolCallCount,
			"outcome":     outcome.String(),
			"duration_ms": time.Since(roundStart).Milliseconds(),
		}, retErr)
	}()

	// Compact older history before the next assistant response when the
	// estimate is over the threshold. The trigger is estimateCurrentTokens —
	// usage+delta when a previous round reported one, otherwise the message
	// list alone. Tool schemas are not added here.
	currentTokens := e.estimateCurrentTokens(*messagesPtr)
	managed, changed := e.manageContextWindow(ctx, *messagesPtr, round, currentTokens)
	if changed {
		*messagesPtr = managed
		currentTokens = e.tokenEstimator.EstimateMessages(managed)
	}

	// Mid-run steering: drain any user messages queued while the previous
	// round was thinking/executing tools. Runs after compression (injected
	// text stays inside the protected tail) and before lastSentMsgCount is
	// updated (the injected text counts as new delta tokens for the next
	// call), so the very next LLM call sees the user's addition.
	e.drainSteerMessages(ctx, state, messagesPtr, sessionID, assistantMessageID)
	if e.collaboration != nil {
		events, err := e.collaboration.Poll(ctx)
		if err != nil {
			return iterOutcomeBreak, err
		}
		e.deliverCollaborationEvents(messagesPtr, events, len(state.RoundSteps), false)
		e.holdCollaborationAnswer, err = e.collaboration.PendingAnswer(ctx)
		if err != nil {
			return iterOutcomeBreak, err
		}
	}
	if guards.childAnswerRevised {
		tools = nil
	}
	// Background-work context rides the same boundary for the same reasons,
	// after the user's own messages.
	e.injectBackground(ctx, state, messagesPtr, false)

	logger.Infof(ctx, "[Agent][Round-%d/%s] Starting: %d messages, %d tools, est_tokens=%d",
		round, e.maxIterationsDisplay(), len(*messagesPtr), len(tools), currentTokens)
	e.logContextPrediction(ctx, round, *messagesPtr, tools, currentTokens)
	common.PipelineInfo(ctx, "Agent", "round_start", map[string]interface{}{
		"iteration":      state.CurrentRound,
		"round":          round,
		"message_count":  len(*messagesPtr),
		"pending_tools":  len(tools),
		"max_iterations": e.config.MaxIterations,
	})

	// 1. Think: Call LLM with function calling (includes retry + graceful degradation)
	e.lastSentMsgCount = len(*messagesPtr)
	runtimeNotice := guards.pendingRuntimeNotice
	guards.pendingRuntimeNotice = ""
	resp, err := e.callLLMWithRetry(ctx, messagesPtr, tools, state, query, state.CurrentRound, sessionID, runtimeNotice)
	if err != nil {
		retErr = err
		return iterOutcomeNext, err
	}
	if resp == nil {
		return iterOutcomeBreak, nil
	}

	// The round's own token estimate can be wrong — history is estimated, not
	// counted — so a request that looked safe can still come back having hit
	// the window. Compacting and retrying once turns that into a recovered
	// round instead of a wasted one. Once per turn: if the retry overflows
	// too, the problem is not the history size.
	if !e.overflowRecovered && e.responseHitContextLimit(resp) {
		e.overflowRecovered = true
		logger.Warnf(ctx, "[Agent][Round-%d] Response hit the context window (finish=%s, "+
			"completion=%d of %d requested); compacting and retrying once",
			round, resp.FinishReason, resp.Usage.CompletionTokens, e.getCompletionTokenBudget())
		*messagesPtr = e.forceCompaction(ctx, *messagesPtr, round)
		e.lastSentMsgCount = len(*messagesPtr)
		resp, err = e.callLLMWithRetry(
			ctx,
			messagesPtr,
			tools,
			state,
			query,
			state.CurrentRound,
			sessionID,
			runtimeNotice,
		)
		if err != nil {
			retErr = err
			return iterOutcomeNext, err
		}
		if resp == nil {
			return iterOutcomeBreak, nil
		}
	}
	response = resp
	e.logContextDrift(ctx, round, currentTokens, response.Usage)
	// Calibration needs only a prompt count; some providers report no total.
	e.calibrateEstimator(ctx, round, *messagesPtr, tools, response.Usage, state)
	if response.Usage.TotalTokens > 0 {
		e.lastUsage = response.Usage
		state.TurnUsage.Accumulate(response.Usage)
		logger.Infof(ctx, "[Agent][Round-%d] Usage: prompt=%d, completion=%d, total=%d, "+
			"cache_read=%d, cache_write=%d, cache_hit_rate=%.1f%%, cache_status=%s",
			round, response.Usage.PromptTokens,
			response.Usage.CompletionTokens, response.Usage.TotalTokens,
			response.Usage.CacheReadTokens, response.Usage.CacheWriteTokens,
			response.Usage.PromptCacheHitRate(), response.Usage.CacheStatus)
	}

	// Every round in a row that the provider cut off at the completion cap.
	// A truncated *answer* already ends the turn in analyzeResponse, so a run
	// of these means the truncation keeps landing inside tool-call arguments:
	// act.go refuses the calls, the model is told to re-issue them, writes an
	// even longer call, and hits the cap again. Give up rather than spend the
	// whole round budget on it (#3446).
	if isLengthFinishReason(response.FinishReason) {
		guards.consecutiveLength++
		if guards.consecutiveLength >= maxConsecutiveLengthRounds {
			logger.Warnf(ctx, "[Agent][Round-%d] %d consecutive rounds cut off at the completion cap "+
				"(finish=%s, completion=%d of %d); stopping",
				round, guards.consecutiveLength, response.FinishReason,
				response.Usage.CompletionTokens, e.getCompletionTokenBudget())
			common.PipelineWarn(ctx, "Agent", "consecutive_length_stop", map[string]interface{}{
				"iteration":          state.CurrentRound,
				"round":              round,
				"consecutive_length": guards.consecutiveLength,
			})
			// Record the round the way every other round is recorded. The
			// refused tool calls are also what tells the UI that this round's
			// plain text was a preamble: without them the "let me look that
			// up" line stays sitting in the answer area, exactly as if it were
			// the answer.
			step := types.AgentStep{
				Iteration:        state.CurrentRound,
				Thought:          response.Content,
				ReasoningContent: response.ReasoningContent,
				ToolCalls:        make([]types.ToolCall, 0),
				Timestamp:        time.Now(),
				Truncated:        true,
			}
			if len(response.ToolCalls) > 0 {
				e.failTruncatedToolCalls(ctx, response, &step, state.CurrentRound, sessionID)
			}
			state.RoundSteps = append(state.RoundSteps, step)
			if e.collaborationOwnsFailure(ctx) {
				return iterOutcomeBreak, fmt.Errorf("collaboration stopped after repeated output truncation")
			}
			e.finishStalledTurn(ctx, state, sessionID, response, true)
			return iterOutcomeBreak, nil
		}
	} else {
		guards.consecutiveLength = 0
	}

	// Detect stuck loops: a round with no tool calls that repeats the previous
	// such round is not making progress. An identical *lack* of content counts
	// — a model burning its whole budget on reasoning returns empty every
	// round, which used to land in the else branch and reset the counter, so
	// the guard could never fire on the one shape that needs it most (#3446).
	if len(response.ToolCalls) == 0 {
		guards.resetFailedToolCallStreak()
		if guards.sawPlainRound && response.Content == guards.lastResponseContent {
			guards.consecutiveSameContent++
		} else {
			guards.consecutiveSameContent = 0
		}
		guards.sawPlainRound = true
		guards.lastResponseContent = response.Content
		if guards.consecutiveSameContent >= maxRepeatedResponseRounds {
			logger.Warnf(
				ctx,
				"[Agent][Round-%d] Detected stuck loop: same content repeated %d times (finish=%s), stopping",
				round,
				guards.consecutiveSameContent+1,
				response.FinishReason,
			)
			if e.collaborationOwnsFailure(ctx) {
				return iterOutcomeBreak, fmt.Errorf("collaboration stopped after repeated responses without progress")
			}
			e.finishStalledTurn(ctx, state, sessionID, response, false)
			return iterOutcomeBreak, nil
		}
	} else {
		guards.consecutiveSameContent = 0
		guards.sawPlainRound = false
		guards.lastResponseContent = ""
	}

	// Create agent step
	step := types.AgentStep{
		UserMessagesBefore:   state.PendingSteerMessages,
		BackgroundInjections: state.PendingBackground,
		Iteration:            state.CurrentRound,
		Thought:              response.Content,
		ReasoningContent:     response.ReasoningContent,
		ReasoningSignature:   response.ReasoningSignature,
		ReasoningMetadata:    response.ReasoningMetadata,
		ToolCalls:            make([]types.ToolCall, 0),
		Timestamp:            time.Now(),
	}
	state.PendingSteerMessages = nil
	state.PendingBackground = nil

	// If the request was cancelled while the LLM was streaming (e.g. the
	// user pressed "stop"), the stream driver still returns a usable
	// response (partial content / finish_reason="stop" / no tool calls).
	// Do NOT let analyzeResponse treat that partial thinking text as the
	// final answer — it would pollute Message.Content with mid-stream
	// thinking and show up as a duplicate card next to the intermediate-
	// steps tree. Preserve the partial thinking as an AgentStep and break
	// out of the loop without marking state.IsComplete. executeLoop's
	// deferred emitCompletionEvent will persist the step onto
	// Message.AgentSteps so it still appears in the tree on refresh.
	if ctx.Err() != nil {
		logger.Warnf(ctx, "[Agent][Round-%d] Context cancelled during LLM call; preserving partial step",
			round)
		if step.Thought != "" || len(step.ToolCalls) > 0 || len(step.UserMessagesBefore) > 0 ||
			len(step.BackgroundInjections) > 0 {
			state.RoundSteps = append(state.RoundSteps, step)
		}
		return iterOutcomeBreak, nil
	}

	// A delegated deliverable must not silently become a partial success. Give
	// it one text-only revision using existing evidence; never re-run tools or
	// create an unbounded continuation loop. The last truncated step remains
	// explicit if the revision also hits its cap or no round remains.
	if e.collaboration != nil && e.collaboration.Child != nil &&
		isLengthFinishReason(response.FinishReason) && len(response.ToolCalls) == 0 &&
		strings.TrimSpace(
			response.Content,
		) != "" && !guards.childAnswerRevised && e.withinIterationBudget(state.CurrentRound+1) {
		guards.childAnswerRevised = true
		state.FinalAnswer = response.Content // retain the partial deliverable if recovery fails
		step.Truncated, step.IntermediateAnswer = true, true
		state.RoundSteps = append(state.RoundSteps, step)
		*messagesPtr = append(
			*messagesPtr,
			chat.Message{
				Role: "assistant", Content: response.Content,
				ReasoningContent:   response.ReasoningContent,
				ReasoningSignature: response.ReasoningSignature,
				ReasoningMetadata:  response.ReasoningMetadata,
			},
			chat.Message{
				Role: "system",
				Content: "The delegated draft reached the output token limit and is incomplete. Produce " +
					"one shorter, self-contained final deliverable covering all requested sections " +
					"using the evidence already collected. Do not repeat tool calls or claim missing " +
					"sections are complete. Omit process narration and repeated source excerpts. If " +
					"evidence is missing, say so explicitly. This is the only revision attempt.",
			},
		)
		return iterOutcomeNext, nil
	}

	if guards.childAnswerRevised && len(response.ToolCalls) > 0 {
		return iterOutcomeBreak, fmt.Errorf("delegated answer revision requested tools despite text-only recovery")
	}

	// 2. Analyze: Check for stop conditions (natural stop with no tool calls).
	// An answer with page buttons stops like a plain answer once the buttons
	// are offered; if one fails, the round goes on so the model can fix it.
	analyzed, buttonsRan := response, false
	if answersWithPageButtons(response) {
		if e.runRoundTools(ctx, state, response, &step, sessionID, assistantMessageID) {
			return iterOutcomeBreak, nil
		}
		buttonsRan = true
		if toolCallsSucceeded(step.ToolCalls) {
			answer := *response
			answer.ToolCalls, answer.FinishReason = nil, "stop"
			analyzed = &answer
		}
	}
	verdict := e.analyzeResponse(ctx, analyzed, step, state.CurrentRound, sessionID, roundStart)
	if verdict.isDone {
		// Guard against empty content: when the LLM stops naturally with no
		// content and no tool calls (e.g., thinking-only loop without KB),
		// Retry with a runtime notice, without inventing a user request to
		// finalize or preventing the next round from using tools/waiting.
		if verdict.emptyContent {
			guards.emptyRetries++
			if guards.emptyRetries <= maxEmptyResponseRetries {
				state.PendingSteerMessages = step.UserMessagesBefore
				state.PendingBackground = step.BackgroundInjections
				logger.Warnf(ctx, "[Agent][Round-%d] Empty content with stop - retrying (%d/%d)",
					round, guards.emptyRetries, maxEmptyResponseRetries)
				guards.pendingRuntimeNotice = emptyResponseRetryNotice
				return iterOutcomeContinue, nil
			}
			// A fallback answer cannot replace unreviewed child results or mark
			// an empty child deliverable as successful. Propagate a failure so
			// runtime cleanup/parent notification follows the normal error path.
			if e.collaborationOwnsFailure(ctx) {
				return iterOutcomeBreak, fmt.Errorf("collaboration stopped after repeated empty answers")
			}
			// Retries exhausted — use fallback message rather than empty answer.
			// analyzeResponse emitted nothing for the empty rounds (they were
			// retryable), so the fallback must be emitted here as the turn's
			// sole terminal answer event (#2906).
			logger.Warnf(ctx, "[Agent][Round-%d] Empty content after %d retries - using fallback",
				round, maxEmptyResponseRetries)
			fallback := stalledAnswerFallback
			answerID := generateEventID("answer")
			_ = e.eventBus.Emit(ctx, event.Event{
				ID:        answerID,
				Type:      event.EventAgentFinalAnswer,
				SessionID: sessionID,
				Data: event.AgentFinalAnswerData{
					Content: fallback,
					Done:    false,
				},
			})
			_ = e.eventBus.Emit(ctx, event.Event{
				ID:        answerID,
				Type:      event.EventAgentFinalAnswer,
				SessionID: sessionID,
				Data: event.AgentFinalAnswerData{
					Content: "",
					Done:    true,
				},
			})
			state.FinalAnswer = fallback
			state.IsComplete = true
			state.RoundSteps = append(state.RoundSteps, verdict.step)
			e.closeAnswerStream(ctx, sessionID, verdict.answerID, verdict.truncated)
			return iterOutcomeBreak, nil
		}
		// Loop-end inject: a user message queued while this finishing round
		// ran, or background work this run started that is still running,
		// keeps the agent going instead of emitting a final answer.
		// Content-filter stops are terminal and do not take this path.
		// Past MaxIterations only the first inject gets an extra round;
		// anything after that stays in the queue for a follow-up turn.
		if response.FinishReason != "content_filter" {
			nextRound := state.CurrentRound + 1
			canContinue := e.withinIterationBudget(nextRound) || e.steerOverruns < maxSteerOverruns
			if canContinue {
				*messagesPtr = append(*messagesPtr, chat.Message{
					Role:               "assistant",
					Content:            verdict.finalAnswer,
					ReasoningContent:   response.ReasoningContent,
					ReasoningSignature: response.ReasoningSignature,
					ReasoningMetadata:  response.ReasoningMetadata,
				})
				injected := e.drainSteerMessages(ctx, state, messagesPtr, sessionID, assistantMessageID)
				injected += e.injectBackground(ctx, state, messagesPtr, true)
				if injected > 0 {
					*messagesPtr = e.appendCollaborationDeliveryBoundary(*messagesPtr, verdict.finalAnswer)
					verdict.step.IntermediateAnswer = true
					state.RoundSteps = append(state.RoundSteps, verdict.step)
					if !e.withinIterationBudget(nextRound) {
						e.steerOverruns++
						e.allowSteerOverrun = true
					}
					return iterOutcomeNext, nil
				}
			}
		}
		if e.collaboration != nil && response.FinishReason != "content_filter" {
			if e.suspendable && e.collaboration.Child == nil {
				checkpoint := RunSnapshot{
					CollaborationDeliveries: e.progress.collaborationDeliveries,
					CollaborationCursor:     e.collaborationCursor(),
					MCPToolRefs:             e.toolRegistry.MCPExposureSnapshot(),
					Version:                 RunSnapshotVersion,
					CollaborationWait:       true,
					BetweenRounds:           true,
					Request:                 e.suspendRequest,
					Query:                   e.progress.query,
					ImageURLs:               e.progress.imageURLs,
					UserMessages:            e.progress.userMessages,
					CompletedSteps:          append([]types.AgentStep(nil), state.RoundSteps...),
					KnowledgeRefs:           state.KnowledgeRefs,
					CurrentRound:            state.CurrentRound + 1,
					TurnUsage:               state.TurnUsage,
				}
				intermediate := verdict.step
				intermediate.IntermediateAnswer = true
				checkpoint.CompletedSteps = append(checkpoint.CompletedSteps, intermediate)
				data, err := json.Marshal(checkpoint)
				if err != nil {
					return iterOutcomeBreak, err
				}
				if err = e.collaboration.SaveWait(ctx, data, time.Now().Add(time.Hour)); err != nil {
					return iterOutcomeBreak, err
				}
			}
			events, err := e.collaboration.BeforeFinish(ctx)
			inputReady := errors.Is(err, collaboration.ErrInput)
			if err != nil && !inputReady {
				return iterOutcomeBreak, err
			}
			if len(events) > 0 || inputReady {
				if err := e.collaboration.ClearWait(ctx); err != nil {
					return iterOutcomeBreak, err
				}
				if !e.withinIterationBudget(state.CurrentRound + 1) {
					if inputReady && e.steerOverruns < maxSteerOverruns {
						e.steerOverruns++
						e.allowSteerOverrun = true
					} else {
						return iterOutcomeBreak,
							fmt.Errorf("agent iteration budget exhausted with unprocessed collaboration events")
					}
				}
				*messagesPtr = e.appendCollaborationDeliveryBoundary(*messagesPtr, verdict.finalAnswer)
				e.deliverCollaborationEvents(messagesPtr, events, len(state.RoundSteps)+1, true)
				verdict.step.IntermediateAnswer = true
				state.RoundSteps = append(state.RoundSteps, verdict.step)
				return iterOutcomeNext, nil
			}
		}
		if e.holdCollaborationAnswer && response.FinishReason != "content_filter" {
			_ = e.eventBus.Emit(
				ctx,
				event.Event{
					ID: verdict.answerID, Type: event.EventAgentFinalAnswer, SessionID: sessionID,
					Data: event.AgentFinalAnswerData{Content: verdict.finalAnswer, Truncated: verdict.truncated},
				},
			)
		}
		state.FinalAnswer = verdict.finalAnswer
		state.IsComplete = true
		if buttonsRan {
			// The text is the turn's answer; left on the step it would replay
			// twice in later turns and show again as a step on reload.
			verdict.step.Thought = ""
		}
		state.RoundSteps = append(state.RoundSteps, verdict.step)
		e.closeAnswerStream(ctx, sessionID, verdict.answerID, verdict.truncated)
		return iterOutcomeBreak, nil
	}

	// This round is non-terminal (it will execute tools and loop again). Any
	// plain assistant text streamed live to the answer area this round was a
	// preamble (e.g. "let me search the knowledge base…"), not the final
	// answer. No explicit retraction signal is emitted: the agent only ends by
	// stopping naturally with plain text and no tool calls, so the upcoming
	// tool-call events are themselves the authoritative "that wasn't the final
	// answer" marker. Both the stream handler and the UI treat any answer text
	// preceding a tool call in the same stream as a preamble and relocate it
	// into the steps tree. The preamble is still preserved as this round's
	// Thought.
	// A tool-bearing response is an intermediate user update. Publish it on its
	// own channel, never as reasoning or as part of the final deliverable.
	// Page buttons that failed leave their answer text live, since the stream
	// handler and the client keep text before a page button; retract it the
	// same way.
	progress := agenttools.StripThinkBlocks(response.Content)
	if (buttonsRan || e.collaboration != nil && e.collaboration.Child == nil) && strings.TrimSpace(progress) != "" {
		step.Progress = progress
		progressID := response.AnswerEventID
		if progressID == "" {
			progressID = generateEventID("collaboration-progress")
		}
		step.ProgressEventID = progressID
		_ = e.eventBus.Emit(ctx, event.Event{
			ID: progressID, Type: event.EventAgentProgress, SessionID: sessionID,
			Data: event.AgentProgressData{Content: progress, Iteration: state.CurrentRound},
		})
	}

	// 3. Act: Execute tool calls
	if !buttonsRan && e.runRoundTools(ctx, state, response, &step, sessionID, assistantMessageID) {
		return iterOutcomeBreak, nil
	}
	toolCallCount = len(step.ToolCalls)

	// 4. Observe: Add tool results to messages and write to context
	var (
		failedToolName     string
		failedToolAttempts int
	)
	for _, toolCall := range step.ToolCalls {
		if name, attempts, shouldNudge := guards.recordFailedToolCall(toolCall); shouldNudge {
			failedToolName = name
			failedToolAttempts = attempts
		}
	}

	state.RoundSteps = append(state.RoundSteps, step)
	*messagesPtr = e.appendToolResults(*messagesPtr, step)
	*messagesPtr = e.appendToolImages(ctx, *messagesPtr, step)
	if failedToolName != "" {
		logger.Warnf(ctx, "[Agent][Round-%d] Repeated failed call to %q (%d attempts); "+
			"asking the model to change strategy", round, failedToolName, failedToolAttempts)
		guidance := fmt.Sprintf(
			"The tool %q has failed %d consecutive times with identical arguments. "+
				"Do not call it again with those arguments. Switch to a different tool "+
				"or use another approach to complete the task.",
			failedToolName, failedToolAttempts,
		)
		*messagesPtr = append(*messagesPtr, chat.Message{Role: "user", Content: guidance})
	}
	common.PipelineInfo(ctx, "Agent", "round_end", map[string]interface{}{
		"iteration":   state.CurrentRound,
		"round":       round,
		"tool_calls":  toolCallCount,
		"thought_len": len(step.Thought),
	})
	return iterOutcomeNext, nil
}

// runRoundTools executes the round's tool calls and reports whether the run
// suspended on a prompt.
func (e *AgentEngine) runRoundTools(
	ctx context.Context,
	state *types.AgentState,
	response *types.ChatResponse,
	step *types.AgentStep,
	sessionID, assistantMessageID string,
) bool {
	e.beginRound(*step, response.ToolCalls)
	suspended := e.executeToolCalls(ctx, response, step, state.CurrentRound, sessionID, assistantMessageID)
	e.endRound()
	step.BackgroundSeenIDs = e.takeBackgroundSeen()
	if suspended == nil {
		return false
	}
	// The blocked call and the ones after it have not run, so the round is
	// not part of the transcript yet; it is completed on resume.
	logger.Infof(ctx, "[Agent][Round-%d] Suspended waiting on prompt %s",
		state.CurrentRound+1, suspended.PromptID)
	state.Suspended = suspended
	state.SuspendedStep = step
	return true
}

// answersWithPageButtons reports whether a reply wrote its answer and only
// offers page buttons beside it. That is a final answer, not a step: the
// buttons render under it, and their results tell the model nothing.
func answersWithPageButtons(response *types.ChatResponse) bool {
	if len(response.ToolCalls) == 0 || isLengthFinishReason(response.FinishReason) ||
		strings.TrimSpace(agenttools.StripThinkBlocks(response.Content)) == "" {
		return false
	}
	for _, tc := range response.ToolCalls {
		if !agenttools.IsPageButtonTool(tc.Function.Name) {
			return false
		}
	}
	return true
}

func toolCallsSucceeded(calls []types.ToolCall) bool {
	for _, tc := range calls {
		if tc.Result == nil || !tc.Result.Success {
			return false
		}
	}
	return true
}

// String returns a stable label for Langfuse output payloads.
func (o iterOutcome) String() string {
	switch o {
	case iterOutcomeNext:
		return "next"
	case iterOutcomeContinue:
		return "continue"
	case iterOutcomeBreak:
		return "break"
	default:
		return "unknown"
	}
}

// ---------------------------------------------------------------------------
// Tool result image VLM description helpers
// ---------------------------------------------------------------------------

const (
	toolImageBriefPrompt = types.ImageReadBriefPrompt
	toolImageFullPrompt  = types.ImageReadFullPrompt
	toolImageFocusRunes  = types.ImageReadFocusRunes
)

func toolImagePrompt(detail, focus string) string { return types.ImageReadPrompt(detail, focus) }
func toolImagePrompts(result *types.ToolResult) []string {
	prompt := toolImagePrompt(result.ImageDetail, result.ImageFocus)
	prompts := make([]string, len(result.Images))
	for i := range prompts {
		prompts[i] = prompt
	}
	return prompts
}

const (
	toolImageDescribeConcurrency = 4
	toolImageDescribeTimeout     = 120 * time.Second
)

// DescribeDataURIImages turns user-uploaded data URIs into text with the
// configured VLM. A chat model that cannot see images uses this instead of
// dropping the upload. Uploads ask for a full read; tool results keep the
// prompt that came with the tool call.
func (e *AgentEngine) DescribeDataURIImages(ctx context.Context, imageDataURIs []string) []string {
	prompts := make([]string, len(imageDataURIs))
	for i := range prompts {
		prompts[i] = toolImageFullPrompt
	}
	return e.describeImages(ctx, imageDataURIs, prompts)
}

// describeImages asks the configured VLM to describe tool result images, a
// few at a time, each under its own timeout so a slow image cannot starve the
// rest. prompts is aligned with the images (nil means a brief description for
// each). The result is aligned with the input; an image that could not be
// described is left empty.
func (e *AgentEngine) describeImages(ctx context.Context, imageDataURIs, prompts []string) []string {
	descriptions := make([]string, len(imageDataURIs))
	if e.imageDescriber == nil {
		return descriptions
	}
	sem := e.imageDescribeSlots
	if sem == nil {
		sem = make(chan struct{}, toolImageDescribeConcurrency)
	}
	var wg sync.WaitGroup
	for i, dataURI := range imageDataURIs {
		if ctx.Err() == nil {
			select {
			case sem <- struct{}{}:
			case <-ctx.Done():
			}
		}
		if ctx.Err() != nil {
			logger.Warnf(
				ctx,
				"[Agent] Context cancelled, skipping remaining %d tool result images",
				len(imageDataURIs)-i,
			)
			break
		}
		wg.Add(1)
		go func() {
			defer wg.Done()
			defer func() { <-sem }()
			imgBytes, err := decodeDataURIBytes(dataURI)
			if err != nil {
				logger.Warnf(ctx, "[Agent] Failed to decode tool result image %d: %v", i, err)
				return
			}
			imageCtx, cancel := context.WithTimeout(ctx, toolImageDescribeTimeout)
			defer cancel()
			prompt := toolImageBriefPrompt
			if i < len(prompts) {
				prompt = prompts[i]
			}
			desc, err := e.imageDescriber(imageCtx, imgBytes, prompt)
			if err != nil {
				logger.Warnf(ctx, "[Agent] VLM analysis failed for tool result image %d: %v", i, err)
				return
			}
			descriptions[i] = strings.TrimSpace(desc)
		}()
	}
	wg.Wait()
	return descriptions
}

// decodeDataURIBytes extracts raw bytes from a "data:mime;base64,..." URI.
// Retries with RawStdEncoding when standard base64 decoding fails (some MCP
// servers omit trailing '=' padding).
func decodeDataURIBytes(dataURI string) ([]byte, error) {
	if !strings.HasPrefix(dataURI, "data:") {
		return nil, fmt.Errorf("not a data URI")
	}
	idx := strings.Index(dataURI, ";base64,")
	if idx < 0 {
		return nil, fmt.Errorf("unsupported data URI encoding (expected base64)")
	}
	raw := dataURI[idx+8:]
	decoded, err := base64.StdEncoding.DecodeString(raw)
	if err != nil {
		// Retry without padding — some MCP servers omit trailing '='
		decoded, err = base64.RawStdEncoding.DecodeString(raw)
	}
	return decoded, err
}