WeKnora/internal/handler/session/qa.go

2235 lines
85 KiB
Go
Raw Permalink Blame History

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

package session
import (
"context"
"crypto/sha256"
"encoding/json"
stderrors "errors"
"fmt"
"net/http"
"os"
"path/filepath"
"runtime"
"strconv"
"strings"
"sync"
"time"
"github.com/Tencent/WeKnora/internal/application/access"
"github.com/Tencent/WeKnora/internal/errors"
"github.com/Tencent/WeKnora/internal/event"
"github.com/Tencent/WeKnora/internal/infrastructure/docparser"
"github.com/Tencent/WeKnora/internal/logger"
"github.com/Tencent/WeKnora/internal/models/api"
"github.com/Tencent/WeKnora/internal/sandbox"
"github.com/Tencent/WeKnora/internal/storageurl"
"github.com/Tencent/WeKnora/internal/stream"
"github.com/Tencent/WeKnora/internal/tracing/langfuse"
"github.com/Tencent/WeKnora/internal/types"
"github.com/Tencent/WeKnora/internal/types/interfaces"
secutils "github.com/Tencent/WeKnora/internal/utils"
"github.com/gin-gonic/gin"
"github.com/google/uuid"
)
const (
maxAttachmentUploadsPerRequest = 5
maxAttachmentUploadTotalBytes = int64(100 * 1024 * 1024)
)
// qaRequestContext holds all the common data needed for QA requests
type qaRequestContext struct {
ctx context.Context
c *gin.Context
sessionID string
requestID string
receivedAt time.Time // Wall-clock time the handler started processing the request
query string // Question sent to models; the upload-only question when the user typed nothing
userInput string // Text the user typed, stored on the user message; may be empty
session *types.Session
customAgent *types.CustomAgent
assistantMessage *types.Message
knowledgeBaseIDs []string
knowledgeIDs []string
tagScopes []types.TagScope
tagIDs []string
mcpServiceIDs []string
skillNames []string
summaryModelID string
reasoningEffort string
localBrowserEnabled bool
webSearchEnabled bool
mentionedItems types.MentionedItems
effectiveTenantID uint64 // when using shared agent, tenant ID for model/KB/MCP resolution; 0 = use context tenant
sharedAgentReadOnly bool // access was granted by a read-only agent share
images []ImageAttachment // Uploaded images with analysis text
userMessageID string // Created user message ID (populated after createUserMessage)
userCreatedAt time.Time // Persisted user message timestamp, echoed on agent_query
channel string // Source channel: "web", "api", "im", etc.
attachments types.MessageAttachments // Processed base64 file attachments (legacy inline uploads)
attachmentIDs []string // Pre-uploaded session-scoped document IDs, resolved after SSE starts
attachmentMetas types.MessageAttachments // Metadata-only view of attachmentIDs for the persisted user message
suggestionAttribution *types.SuggestionAttribution
questionOrigin *types.QuestionOrigin
pageContext *types.PageContext
assistantAccess types.AssistantAccessLevel
// resourceRewriter turns internal storage references in the outbound stream
// into directly loadable URLs when the caller asks for `resource_urls=public`.
// Disabled (a pass-through) in the default handle mode.
resourceRewriter *storageurl.StreamRewriter
// steerSink bridges the engine's round-boundary drain to the steer
// sub-list and user-row persistence. Set by setupSSEStream for agent
// runs only.
steerSink *steerSink
// Snapshot of the request fields needed to persist the input-bar state
// for session restoration. Kept verbatim from the request so we record
// what the user had selected on the UI (not server-side resolutions).
reqAgentEnabled bool
reqAgentID string
// skipSSE is set for server-started follow-up runs (steer backlog after
// the previous turn exits). Events still land in StreamManager so the
// client can attach via continue-stream; nothing is written to gin.
skipSSE bool
// steerCarryOver is appended to this run's steer sub-list before the run
// is published as live, so leftover inject / after messages from the
// previous run are visible to this engine from round 1 and to any client
// that reloads the queue.
steerCarryOver []interfaces.StreamEvent
// turnLeaseHeld records that executeQA already took the send-side turn
// lease for this request, so the QA service does not take a second one.
turnLeaseHeld bool
// resume continues a suspended run on assistantMessage instead of
// starting a turn.
resume *types.AgentResume
}
// buildQARequest converts the qaRequestContext into a types.QARequest for service invocation.
// steerSink rides along when the caller set one, so agent runs drain mid-run
// message injections at round boundaries.
// calledWithAPIKey reports an X-API-Key caller; the prompt endpoints are
// closed to API keys, so such a caller cannot answer a question.
func calledWithAPIKey(ctx context.Context) bool {
_, ok := types.TenantAPIKeyScopeFromContext(ctx)
return ok
}
func (rc *qaRequestContext) buildQARequest() *types.QARequest {
imageURLs, imageDescription := extractImageURLsAndOCRText(rc.images)
interactive := !calledWithAPIKey(rc.ctx)
mode := types.RunModeUnattended
if interactive {
mode = types.RunModeAttended
}
req := &types.QARequest{
Session: rc.session,
Query: rc.query,
AssistantMessageID: rc.assistantMessage.ID,
SummaryModelID: rc.summaryModelID,
ReasoningEffort: rc.reasoningEffort,
CustomAgent: rc.customAgent,
SharedAgentReadOnly: rc.sharedAgentReadOnly,
KnowledgeBaseIDs: rc.knowledgeBaseIDs,
KnowledgeIDs: rc.knowledgeIDs,
TagScopes: rc.tagScopes,
MCPServiceIDs: rc.mcpServiceIDs,
SkillNames: rc.skillNames,
ImageURLs: imageURLs,
ImageDescription: imageDescription,
UserMessageID: rc.userMessageID,
WebSearchEnabled: rc.webSearchEnabled,
LocalBrowserEnabled: rc.localBrowserEnabled,
Attachments: rc.attachments,
QuestionOrigin: rc.questionOrigin,
PageContext: rc.pageContext,
AssistantAccess: rc.assistantAccess,
TurnLeaseHeld: rc.turnLeaseHeld,
// Only a caller that can answer the prompt later may leave the run
// suspended; an API-key caller would get a turn with no answer.
Suspendable: interactive,
Mode: mode,
Resume: rc.resume,
}
if rc.steerSink != nil {
req.SteerSink = rc.steerSink
}
return req
}
// uploadOnlyQuery returns the question used for a request that carries inline
// image or file content but no text, or "" when it carries neither. URL-only
// images do not count: parseQARequest strips client-supplied image URLs.
// Pre-uploaded attachment IDs do not count either: those documents can still
// fail or time out after the stream starts, leaving nothing to answer from.
func uploadOnlyQuery(ctx context.Context, req *CreateKnowledgeQARequest) string {
hasUpload := false
for _, img := range req.Images {
hasUpload = hasUpload || strings.TrimSpace(img.Data) != ""
}
for _, att := range req.AttachmentUploads {
hasUpload = hasUpload || strings.TrimSpace(att.Data) != ""
}
if !hasUpload {
return ""
}
return types.UploadOnlyQuestion(types.LanguageFromContextOrDefault(ctx))
}
// parseQARequest parses and validates a QA request, returns the request context
func (h *Handler) parseQARequest(c *gin.Context, logPrefix string) (*qaRequestContext, *CreateKnowledgeQARequest, error) {
receivedAt := time.Now()
ctx := logger.CloneContext(c.Request.Context())
requestID := secutils.SanitizeForLog(c.GetString(types.RequestIDContextKey.String()))
logger.Infof(ctx, "[%s] TTFB:start request_id=%s received_at=%d",
logPrefix, requestID, receivedAt.UnixMilli())
// Get session ID from URL parameter
sessionID := secutils.SanitizeForLog(c.Param("session_id"))
if sessionID == "" {
logger.Error(ctx, "Session ID is empty")
return nil, nil, errors.NewBadRequestError(errors.ErrInvalidSessionID.Error())
}
// Parse request body
var request CreateKnowledgeQARequest
if err := c.ShouldBindJSON(&request); err != nil {
logger.Error(ctx, "Failed to parse request data", err)
return nil, nil, errors.NewBadRequestError(err.Error())
}
level, validEffort := api.ParseReasoningEffort(request.ReasoningEffort)
if !validEffort {
return nil, nil, errors.NewBadRequestError(
fmt.Sprintf("reasoning_effort must be one of %v", api.AllReasoningEfforts),
)
}
request.ReasoningEffort = string(level)
// Validate syntax before session lookup or QA work, preserving the original
// query text. KnowledgeQA applies its XSS-pattern check later in the chat
// pipeline; AgentQA must allow frontend code in conversation text.
validatedQuery, valid := secutils.ValidateInputSyntax(request.Query)
if !valid {
logger.Error(ctx, "Query content is invalid")
return nil, nil, errors.NewBadRequestError("Query content contains invalid content")
}
modelQuery := request.Query
if validatedQuery == "" {
modelQuery = uploadOnlyQuery(ctx, &request)
if modelQuery == "" {
logger.Error(ctx, "Query content is empty")
return nil, nil, errors.NewBadRequestError("Query content cannot be empty")
}
request.Query = ""
}
// Resolve the storage-reference representation up front: once the SSE stream
// has started an invalid value can no longer be reported as a 400.
resourceRewriter, err := h.resolveStreamRewriter(c)
if err != nil {
logger.Warnf(ctx, "Rejected resource URL mode: %v", err)
return nil, nil, err
}
if h.suggestionService != nil && request.SuggestionAttribution != nil {
if err := h.suggestionService.ValidateAttribution(ctx, sessionID, request.Query, request.SuggestionAttribution); err != nil {
return nil, nil, errors.NewBadRequestError("invalid suggestion attribution")
}
}
// SSRF protection: strip client-supplied URL/Caption fields from image attachments.
// The URL field must only be populated server-side by saveImageAttachments; an
// attacker could inject internal network URLs to trigger SSRF via the LLM provider.
for i := range request.Images {
request.Images[i].URL = ""
request.Images[i].Caption = ""
}
// Log request details
if requestJSON, err := json.Marshal(request); err == nil {
logger.Infof(ctx, "[%s] Request: session_id=%s, request=%s",
logPrefix, sessionID, secutils.SanitizeForLog(secutils.CompactImageDataURLForLog(string(requestJSON))))
}
// Get session. QA writes new messages into the session, so use the strict
// owner scope: a tenant admin may read an API-key session but must not be
// able to post messages to it (which would otherwise fail later at message
// creation with a 500 instead of a clean not-found).
session, err := h.sessionService.GetOwnedSession(ctx, sessionID)
if err != nil {
logger.Errorf(ctx, "Failed to get session, session ID: %s, error: %v", sessionID, err)
return nil, nil, errors.NewNotFoundError("Session not found")
}
// Get custom agent if agent_id is provided. Backend resolves shared agent from share relation (no client-provided tenant).
customAgent, effectiveTenantID, sharedAgentReadOnly := h.resolveAgent(ctx, c, request.AgentID, request.AgentSourceTenantID)
if request.AgentSourceTenantID != 0 && customAgent == nil {
return nil, nil, errors.NewNotFoundError("Shared agent not found")
}
// Merge @mentioned items into knowledge_base_ids and knowledge_ids
kbIDs, knowledgeIDs := mergeKnowledgeTargets(request.KnowledgeBaseIDs, request.KnowledgeIDs, request.MentionedItems)
if err := types.AuthorizeTenantAPIKeyKnowledgeTargets(ctx, kbIDs, knowledgeIDs); err != nil {
return nil, nil, err
}
// KB-anchored built-in agents (wiki fixer, assistant) are opened from a KB
// page, not from a tenant's regular agent picker. When the KB is shared,
// run them in the source tenant only if the caller has edit permission, so
// KB-scoped models/tools resolve without granting viewers write capability.
if types.RunsInSharedKBWorkspace(customAgent) {
if scopedAgent, scopedTenantID := h.resolveWikiFixerTenantScope(
ctx,
customAgent,
c.GetUint64(types.TenantIDContextKey.String()),
types.TenantRoleFromContext(ctx),
kbIDs,
); scopedTenantID != 0 {
customAgent = scopedAgent
effectiveTenantID = scopedTenantID
sharedAgentReadOnly = false
}
}
// A per-request model override resolves in the workspace the run executes
// in. For a shared agent, or the wiki fixer moved into a shared KB's
// workspace, that is the owner's, where it could select any of the owner's
// models; it would also be stored as the message's model for follow-ups.
if effectiveTenantID != 0 && effectiveTenantID != c.GetUint64(types.TenantIDContextKey.String()) {
request.SummaryModelID = ""
}
if request.LocalBrowserEnabled && (customAgent == nil || !customAgent.IsAgentMode()) {
return nil, nil, errors.NewBadRequestError("Local browser requires an agent with tool calling enabled")
}
// Log merge results for debugging
logger.Infof(ctx, "[%s] @mention merge: request.KnowledgeBaseIDs=%v, request.MentionedItems=%d, merged kbIDs=%v, merged knowledgeIDs=%v",
logPrefix, request.KnowledgeBaseIDs, len(request.MentionedItems), kbIDs, knowledgeIDs)
// Process inline base64 images: decode and save to storage.
// VLM analysis for RAG paths is deferred to the pipeline rewrite step.
// For pure chat paths with non-vision models, VLM analysis runs here as fallback.
if len(request.Images) > 0 {
if customAgent == nil || !customAgent.Config.ImageUploadEnabled {
logger.Warnf(ctx, "[%s] Image upload is not enabled for this agent, rejecting %d images", logPrefix, len(request.Images))
return nil, nil, errors.NewBadRequestError("Image upload is not enabled for this agent")
}
tenantID := c.GetUint64(types.TenantIDContextKey.String())
agentStorageProvider := customAgent.Config.ImageStorageProvider
if err := h.saveImageAttachments(ctx, request.Images, tenantID, agentStorageProvider); err != nil {
logger.Errorf(ctx, "[%s] Failed to save images: %v", logPrefix, err)
return nil, nil, errors.NewBadRequestError(fmt.Sprintf("Image save failed: %v", err))
}
// VLM analysis is always deferred to after SSE stream is up:
// - Agent mode: runs in async execution flow with tool_call/tool_result events
// - Normal RAG mode: runs in the pipeline rewrite step with progress events
// - Normal pure-chat mode: runs in the async goroutine with progress events
}
// Process file attachments: decode and save to storage, extract content
var processedAttachments types.MessageAttachments
if len(request.AttachmentUploads) > 0 {
logger.Infof(ctx, "[%s] processing %d attachment(s)", logPrefix, len(request.AttachmentUploads))
// Decode first and validate actual bytes. Client-declared file_size is
// metadata only and must not be trusted for memory or sandbox limits.
maxSize := secutils.GetMaxFileSize()
decodedAttachments, decodeErr := decodeAndValidateAttachmentUploads(
request.AttachmentUploads,
maxAttachmentUploadsPerRequest,
maxSize,
maxAttachmentUploadTotalBytes,
)
if decodeErr != nil {
return nil, nil, errors.NewBadRequestError(decodeErr.Error())
}
tenantID := c.GetUint64(types.TenantIDContextKey.String())
attachmentRuntimeCtx := ctx
if effectiveTenantID != 0 {
attachmentRuntimeCtx = types.WithExecutionTenant(ctx, effectiveTenantID)
}
// Use ASR only when the agent has audio upload enabled.
asrModelID := ""
if customAgent != nil && customAgent.Config.AudioUploadEnabled && customAgent.Config.ASRModelID != "" {
asrModelID = customAgent.Config.ASRModelID
}
// Resolve the agent's chat parser engine from attachment file types
if customAgent != nil {
for _, att := range request.AttachmentUploads {
ext := strings.ToLower(filepath.Ext(att.FileName))
if engine := customAgent.Config.ResolveChatParserEngine(ext); engine != "" {
attachmentRuntimeCtx = context.WithValue(attachmentRuntimeCtx, types.ChatParserEngineContextKey, engine)
break
}
}
}
// Process all attachments concurrently.
processedAttachments = make(types.MessageAttachments, len(request.AttachmentUploads))
var wg sync.WaitGroup
errChan := make(chan error, len(request.AttachmentUploads))
for i, upload := range request.AttachmentUploads {
wg.Add(1)
go func(idx int, att AttachmentUpload) {
defer wg.Done()
processed, err := h.attachmentProcessor.ProcessAttachment(
attachmentRuntimeCtx, decodedAttachments[idx], att.FileName, int64(len(decodedAttachments[idx])), tenantID, asrModelID,
)
if err != nil {
errChan <- fmt.Errorf("attachment %d processing failed: %w", idx+1, err)
return
}
processedAttachments[idx] = *processed
}(i, upload)
}
wg.Wait()
close(errChan)
if len(errChan) > 0 {
err := <-errChan
logger.Errorf(ctx, "[%s] attachment processing failed: %v", logPrefix, err)
return nil, nil, errors.NewBadRequestError(fmt.Sprintf("attachment processing failed: %v", err))
}
logger.Infof(ctx, "[%s] all attachments processed", logPrefix)
}
// Pre-uploaded documents may still be parsing. Only fetch their metadata
// here (fast, available even while processing) to validate agent file-type
// limits and to record the attachments on the persisted user message. The
// heavy content selection happens after the SSE stream is up, so the send
// is not blocked while parsing finishes (see resolveTemporaryAttachments).
var attachmentIDs []string
var attachmentMetas types.MessageAttachments
if len(request.AttachmentIDs) > 0 {
normalizedIDs, normErr := normalizeTemporaryAttachmentIDs(request.AttachmentIDs)
if normErr != nil {
return nil, nil, errors.NewBadRequestError(normErr.Error())
}
tenantID := session.TenantID
attachmentMetas = make(types.MessageAttachments, 0, len(normalizedIDs))
for _, id := range normalizedIDs {
doc, getErr := h.temporaryDocuments.Get(ctx, tenantID, sessionID, id)
if getErr != nil || doc == nil {
return nil, nil, errors.NewBadRequestError(
fmt.Sprintf("attachment %s was not found in this session", secutils.SanitizeForLog(id)))
}
if customAgent != nil && len(customAgent.Config.SupportedFileTypes) > 0 {
ext := strings.TrimPrefix(strings.ToLower(doc.FileType), ".")
if !containsFileType(customAgent.Config.SupportedFileTypes, ext) {
return nil, nil, errors.NewBadRequestError(
fmt.Sprintf("file type %s is not supported by this agent", ext))
}
}
attachmentMetas = append(attachmentMetas, types.MessageAttachment{
ID: doc.ID, URL: doc.ResourceRef, FileName: doc.FileName,
FileType: doc.FileType, FileSize: doc.FileSize,
})
}
attachmentIDs = normalizedIDs
}
mentionScopes := tagScopesFromMentionedItems(request.MentionedItems)
requestTagIDs := dedupRequestStrings(request.TagIDs)
if err := validateUnscopedTagIDs(orphanTagIDsForScope(requestTagIDs, mentionScopes), secutils.SanitizeForLogArray(kbIDs)); err != nil {
return nil, nil, errors.NewBadRequestError(err.Error())
}
tagScopes := mergeTagScopesFromRequestIDs(mentionScopes, requestTagIDs, secutils.SanitizeForLogArray(kbIDs))
tagIDs := dedupRequestStrings(append(request.TagIDs, mentionedIDsByType(request.MentionedItems, "tag")...))
mcpServiceIDs := dedupRequestStrings(append(request.MCPServiceIDs, mentionedIDsByType(request.MentionedItems, "mcp")...))
skillNames := dedupRequestStrings(append(request.SkillNames, mentionedIDsByType(request.MentionedItems, "skill")...))
executionContext, agentID, agentTenantID, modelID := buildMessageExecutionContext(
ctx,
customAgent,
effectiveTenantID,
request.SummaryModelID,
secutils.SanitizeForLogArray(kbIDs),
secutils.SanitizeForLogArray(knowledgeIDs),
secutils.SanitizeForLogArray(tagIDs),
tagScopes,
secutils.SanitizeForLogArray(mcpServiceIDs),
secutils.SanitizeForLogArray(skillNames),
request.WebSearchEnabled,
)
executionContext.LocalBrowserEnabled = request.LocalBrowserEnabled
// Build request context
reqCtx := &qaRequestContext{
ctx: ctx,
c: c,
sessionID: sessionID,
requestID: requestID,
receivedAt: receivedAt,
query: modelQuery,
userInput: request.Query,
session: session,
customAgent: customAgent,
assistantMessage: &types.Message{
SessionID: sessionID,
Role: "assistant",
RequestID: c.GetString(types.RequestIDContextKey.String()),
IsCompleted: false,
Channel: request.Channel,
AgentID: agentID,
AgentTenantID: agentTenantID,
ModelID: modelID,
ExecutionContext: executionContext,
},
knowledgeBaseIDs: secutils.SanitizeForLogArray(kbIDs),
knowledgeIDs: secutils.SanitizeForLogArray(knowledgeIDs),
tagScopes: tagScopes,
tagIDs: secutils.SanitizeForLogArray(tagIDs),
mcpServiceIDs: secutils.SanitizeForLogArray(mcpServiceIDs),
skillNames: secutils.SanitizeForLogArray(skillNames),
summaryModelID: secutils.SanitizeForLog(request.SummaryModelID),
reasoningEffort: request.ReasoningEffort,
webSearchEnabled: request.WebSearchEnabled,
localBrowserEnabled: request.LocalBrowserEnabled,
mentionedItems: convertMentionedItems(request.MentionedItems),
effectiveTenantID: effectiveTenantID,
sharedAgentReadOnly: sharedAgentReadOnly,
images: request.Images,
channel: request.Channel,
attachments: processedAttachments,
attachmentIDs: attachmentIDs,
attachmentMetas: attachmentMetas,
suggestionAttribution: request.SuggestionAttribution,
questionOrigin: request.QuestionOrigin,
pageContext: request.PageContext,
assistantAccess: request.AssistantAccess,
reqAgentEnabled: request.AgentEnabled,
reqAgentID: request.AgentID,
resourceRewriter: resourceRewriter,
}
return reqCtx, &request, nil
}
func decodeAndValidateAttachmentUploads(
uploads []AttachmentUpload,
maxCount int,
maxFileBytes, maxTotalBytes int64,
) ([][]byte, error) {
if len(uploads) > maxCount {
return nil, fmt.Errorf("at most %d attachments are allowed per request", maxCount)
}
decoded := make([][]byte, len(uploads))
var total int64
for i, upload := range uploads {
data, err := DecodeBase64Attachment(upload.Data)
if err != nil {
return nil, fmt.Errorf("attachment %d decode failed: %w", i+1, err)
}
actualSize := int64(len(data))
if actualSize > maxFileBytes {
return nil, fmt.Errorf("attachment %d exceeds size limit of %d bytes", i+1, maxFileBytes)
}
total += actualSize
if total > maxTotalBytes {
return nil, fmt.Errorf("attachments exceed total request limit of %d bytes", maxTotalBytes)
}
decoded[i] = data
}
return decoded, nil
}
func buildMessageExecutionContext(
ctx context.Context,
agent *types.CustomAgent,
effectiveTenantID uint64,
modelOverride string,
knowledgeBaseIDs []string,
knowledgeIDs []string,
tagIDs []string,
tagScopes []types.TagScope,
mcpServiceIDs []string,
skillNames []string,
webSearchEnabled bool,
) (types.MessageExecutionContext, string, uint64, string) {
locale := types.LanguageFromContextOrDefault(ctx)
snapshot := types.MessageExecutionContext{
KnowledgeBaseIDs: knowledgeBaseIDs,
KnowledgeIDs: knowledgeIDs,
TagIDs: tagIDs,
TagScopes: cloneTagScopes(tagScopes),
MCPServiceIDs: mcpServiceIDs,
SkillNames: skillNames,
WebSearchEnabled: webSearchEnabled,
Locale: locale,
LangfuseTraceparent: langfuse.TraceparentFromContext(ctx),
}
if agent == nil {
return snapshot, "", effectiveTenantID, modelOverride
}
modelID := modelOverride
if modelID == "" {
modelID = agent.Config.ModelID
}
agentTenantID := effectiveTenantID
if agentTenantID == 0 {
agentTenantID = agent.TenantID
}
// Marshal/unmarshal gives the snapshot independent backing slices, so a
// later agent edit cannot mutate an in-flight message context.
if agent.Config.QuestionSuggestions != nil {
if encoded, err := json.Marshal(agent.Config.QuestionSuggestions); err == nil {
var suggestions types.QuestionSuggestionConfig
if json.Unmarshal(encoded, &suggestions) == nil {
snapshot.QuestionSuggestions = &suggestions
}
}
}
hashInput := struct {
QuestionSuggestions *types.QuestionSuggestionConfig `json:"question_suggestions,omitempty"`
KnowledgeBaseIDs []string `json:"knowledge_base_ids,omitempty"`
KnowledgeIDs []string `json:"knowledge_ids,omitempty"`
TagIDs []string `json:"tag_ids,omitempty"`
TagScopes []types.TagScope `json:"tag_scopes,omitempty"`
ModelID string `json:"model_id,omitempty"`
}{
QuestionSuggestions: snapshot.QuestionSuggestions,
KnowledgeBaseIDs: knowledgeBaseIDs,
KnowledgeIDs: knowledgeIDs,
TagIDs: tagIDs,
TagScopes: snapshot.TagScopes,
ModelID: modelID,
}
if encoded, err := json.Marshal(hashInput); err == nil {
hash := sha256.Sum256(encoded)
snapshot.AgentConfigHash = fmt.Sprintf("%x", hash[:])
}
return snapshot, agent.ID, agentTenantID, modelID
}
func cloneTagScopes(scopes []types.TagScope) []types.TagScope {
if len(scopes) == 0 {
return nil
}
cloned := make([]types.TagScope, 0, len(scopes))
for _, scope := range scopes {
if scope.KnowledgeBaseID == "" || len(scope.TagIDs) == 0 {
continue
}
cloned = append(cloned, types.TagScope{
KnowledgeBaseID: scope.KnowledgeBaseID,
TagIDs: append([]string(nil), scope.TagIDs...),
})
}
return cloned
}
// resolveAgent resolves the custom agent by ID: the caller's own agent unless a
// source workspace is given, otherwise (or when no own agent matches) a share.
// Returns (nil, 0) if agentID is empty or not found.
func (h *Handler) resolveAgent(
ctx context.Context,
c *gin.Context,
agentID string,
sourceTenantID uint64,
) (*types.CustomAgent, uint64, bool) {
if agentID == "" {
return nil, 0, false
}
logger.Infof(ctx, "Resolving agent, agent ID: %s", secutils.SanitizeForLog(agentID))
// Without a source workspace the ID names the caller's own agent first.
// Built-in IDs exist in every workspace, so trying shares first would let
// any org member that shares an agent under such an ID take over the
// caller's default agent (and run the caller's chats in its workspace).
// A rejected shared selector (sourceTenantID != 0) must likewise never
// fall back to a same-ID local agent.
var ownErr error
if sourceTenantID == 0 {
agent, err := h.customAgentService.GetAgentByID(ctx, agentID)
if err == nil && agent != nil {
logger.Infof(ctx, "Using own agent: ID=%s, Name=%s, AgentMode=%s",
agent.ID, agent.Name, agent.Config.AgentMode)
return agent, 0, false
}
ownErr = err
}
var shareErr error
userIDVal, _ := c.Get(types.UserIDContextKey.String())
currentTenantID := c.GetUint64(types.TenantIDContextKey.String())
if h.agentShareService != nil && userIDVal != nil && currentTenantID != 0 {
callerTenantRole := types.TenantRoleFromContext(ctx)
agent, err := h.agentShareService.GetSharedAgentForTenant(
ctx, currentTenantID, callerTenantRole, agentID, sourceTenantID)
if err == nil && agent != nil {
logger.Infof(ctx, "Using shared agent: ID=%s, Name=%s, IsBuiltin=%v, AgentMode=%s, effectiveTenantID=%d",
agent.ID, agent.Name, agent.IsBuiltin, agent.Config.AgentMode, agent.TenantID)
return agent, agent.TenantID, true
}
shareErr = err
}
logger.Warnf(ctx, "Failed to get agent, agent ID: %s, source tenant: %d, own error: %v, share error: %v, "+
"using default config", secutils.SanitizeForLog(agentID), sourceTenantID, ownErr, shareErr)
return nil, 0, false
}
// mergeKnowledgeTargets merges request KB/knowledge IDs with @mentioned items into deduplicated slices.
func mergeKnowledgeTargets(requestKBIDs []string, requestKnowledgeIDs []string, mentionedItems []MentionedItemRequest) (kbIDs []string, knowledgeIDs []string) {
kbIDSet := make(map[string]bool)
kbIDs = make([]string, 0, len(requestKBIDs)+len(mentionedItems))
for _, id := range requestKBIDs {
if id != "" && !kbIDSet[id] {
kbIDs = append(kbIDs, id)
kbIDSet[id] = true
}
}
knowledgeIDSet := make(map[string]bool)
knowledgeIDs = make([]string, 0, len(requestKnowledgeIDs)+len(mentionedItems))
for _, id := range requestKnowledgeIDs {
if id != "" && !knowledgeIDSet[id] {
knowledgeIDs = append(knowledgeIDs, id)
knowledgeIDSet[id] = true
}
}
for _, item := range mentionedItems {
if item.ID == "" {
continue
}
switch item.Type {
case "kb":
if !kbIDSet[item.ID] {
kbIDs = append(kbIDs, item.ID)
kbIDSet[item.ID] = true
}
case "file":
if !knowledgeIDSet[item.ID] {
knowledgeIDs = append(knowledgeIDs, item.ID)
knowledgeIDSet[item.ID] = true
}
}
}
return kbIDs, knowledgeIDs
}
// sseStreamContext holds the context for SSE streaming
type sseStreamContext struct {
eventBus *event.EventBus
streamHandler *AgentStreamHandler
asyncCtx context.Context
cancel context.CancelFunc
assistantMessage *types.Message
// steerSink bridges the engine's round-boundary drain to the steer
// sub-list and user-row persistence. Nil for non-agent modes.
steerSink *steerSink
// liveRunFailed is set when SetLiveRun failed. executeQA must not start
// the engine: /steer would see no marker and the client would start a
// second turn.
liveRunFailed bool
liveRunErr error
// releaseTurn ends the sandbox turn lease taken before persist. Knowledge
// mode releases on completion (the pipeline returns before the stream
// finishes); agent mode releases when AgentQA returns.
releaseTurn func()
}
// setupSSEStream sets up the SSE streaming context
func (h *Handler) setupSSEStream(reqCtx *qaRequestContext, generateTitle bool, mode qaMode) *sseStreamContext {
// Base context for async work: when using shared agent, use source tenant for model/KB/MCP resolution
baseCtx := reqCtx.ctx
if reqCtx.effectiveTenantID != 0 && h.tenantService != nil {
if tenant, err := h.tenantService.GetTenantByID(reqCtx.ctx, reqCtx.effectiveTenantID); err == nil && tenant != nil {
baseCtx = types.WithExecutionTenant(reqCtx.ctx, reqCtx.effectiveTenantID)
if reqCtx.customAgent != nil {
baseCtx = access.WithSharedAgent(baseCtx, reqCtx.customAgent)
}
baseCtx = context.WithValue(baseCtx, types.TenantInfoContextKey, tenant)
logger.Infof(
reqCtx.ctx,
"Using effective tenant %d for shared agent (model/KB/MCP)",
reqCtx.effectiveTenantID,
)
}
}
// The session's sandbox stays bound to the session owner even when the
// borrowed tenant above drives everything else, because DeleteSession tears
// that sandbox down from a request that only knows the session's tenant.
baseCtx = types.WithSandboxTenantID(baseCtx, reqCtx.session.TenantID)
// Attachment analysis and title generation run before the QA service.
// Give all asynchronous work the same business conversation identity.
baseCtx = types.WithSessionID(baseCtx, reqCtx.session.ID)
// An agent that opted out of long-term memory has to be opted out of the
// write path too, not just recall. The two run from different contexts:
// recall is marked inside the QA services, while extraction, the explicit
// "remember this" route and document affinity are all kicked off from
// completeAssistantMessage on a context descended from this one. Marking
// the root of the async work is what keeps them from disagreeing — an
// agent that cannot read the memory must not keep writing to it.
if reqCtx.customAgent != nil {
baseCtx = types.ApplyAgentMemoryPreference(baseCtx, reqCtx.customAgent.Config.MemoryEnabled)
}
eventBus := event.NewEventBus()
asyncCtx, cancel := context.WithCancel(logger.CloneContext(baseCtx))
streamCtx := &sseStreamContext{
eventBus: eventBus,
asyncCtx: asyncCtx,
cancel: cancel,
assistantMessage: reqCtx.assistantMessage,
}
// Mid-run steering: only ReAct agent turns (qaModeAgent) have an engine
// loop to drain at and a teardown that ClearLiveRun / kick / discard.
// A custom agent configured as quick-answer still has customAgent != nil
// but executeQA runs KnowledgeQA — publishing a sink there parks /steer
// messages until the Redis TTL expires. The sink is also mirrored onto
// reqCtx so the async goroutine's buildQARequest() picks it up — the
// streamCtx copy alone is never read by the QA call path.
//
// SetLiveRun happens before SSE headers: a 409/503 after text/event-stream
// has started cannot change the status, and the client would sit on a
// stream nobody will write to.
if mode == qaModeAgent && reqCtx.customAgent != nil {
streamCtx.steerSink = newSteerSink(
asyncCtx, reqCtx.sessionID, reqCtx.requestID, reqCtx.assistantMessage,
h.messageService, h.streamManager,
)
reqCtx.steerSink = streamCtx.steerSink
if err := h.streamManager.SetLiveRun(
logger.CloneContext(baseCtx), reqCtx.sessionID,
reqCtx.assistantMessage.ID, reqCtx.requestID,
); err != nil {
logger.ErrorWithFields(reqCtx.ctx, err, map[string]interface{}{
"session_id": reqCtx.sessionID,
})
streamCtx.liveRunFailed = true
streamCtx.liveRunErr = err
return streamCtx
}
}
if !reqCtx.skipSSE {
setSSEHeaders(reqCtx.c)
}
h.writeAgentQueryEvent(
reqCtx.ctx,
reqCtx.sessionID,
reqCtx.userMessageID,
reqCtx.userCreatedAt,
reqCtx.assistantMessage,
reqCtx.resume,
)
if reqCtx.resume != nil {
h.writeRunResumedEvent(reqCtx.ctx, reqCtx.sessionID, reqCtx.assistantMessage.ID, reqCtx.resume.Prompt.ID)
}
// Setup stop event handler
h.setupStopEventHandler(eventBus, reqCtx.sessionID, reqCtx.session.TenantID, reqCtx.assistantMessage, cancel)
// Watch for stop events independently of the client SSE connection so a
// user-requested stop reliably cancels generation even when the client
// has already disconnected (e.g. API-Key callers that close the stream
// before POSTing /stop). The watcher self-terminates on a terminal stream
// event, so its lifetime is decoupled from when the QA service call
// returns (KnowledgeQA returns immediately while streaming continues in a
// background goroutine, whereas AgentQA blocks until done). Use a
// connection-independent context derived from baseCtx so it survives the
// client disconnect.
h.startStopWatcher(logger.CloneContext(baseCtx), reqCtx.sessionID, reqCtx.assistantMessage.ID, eventBus)
// Setup stream handler
streamCtx.streamHandler = h.setupStreamHandler(asyncCtx, reqCtx.sessionID, reqCtx.assistantMessage.ID,
reqCtx.requestID, reqCtx.session.TenantID, reqCtx.receivedAt, reqCtx.assistantMessage, eventBus)
// Generate title if needed
if generateTitle && reqCtx.session.Title == "" {
// Use the same model as the conversation for title generation
modelID := reqCtx.titleModelID()
logger.Infof(reqCtx.ctx, "Session has no title, starting async title generation, session ID: %s, model: %s", reqCtx.sessionID, modelID)
h.sessionService.GenerateTitleAsync(asyncCtx, reqCtx.session, reqCtx.query, modelID, eventBus)
}
return streamCtx
}
// SearchKnowledge godoc
// @Summary 知识搜索
// @Description 在知识库中搜索(不使用LLM总结)。与产品内问答使用同一检索流程(召回、rerank、合并),外部检索首选;可覆盖召回参数与 rerank
// @Tags 问答
// @Accept json
// @Produce json
// @Param request body SearchKnowledgeRequest true "搜索请求"
// @Param resource_urls query string false "文件引用形式,public 返回可加载直链" Enums(handle, public) default(handle)
// @Success 200 {object} map[string]interface{} "搜索结果"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /knowledge-search [post]
func (h *Handler) SearchKnowledge(c *gin.Context) {
ctx := logger.CloneContext(c.Request.Context())
logger.Info(ctx, "Start processing knowledge search request")
// Parse request body
var request SearchKnowledgeRequest
if err := c.ShouldBindJSON(&request); err != nil {
logger.Error(ctx, "Failed to parse request data", err)
c.Error(errors.NewBadRequestError(err.Error()))
return
}
// Validate request parameters
if request.Query == "" {
logger.Error(ctx, "Query content is empty")
c.Error(errors.NewBadRequestError("Query content cannot be empty"))
return
}
// Resolve the storage-reference representation before retrieving, so a typo
// or a rejected scope costs nothing.
rewriter, err := h.resolveResourceRewriter(c)
if err != nil {
logger.Warnf(ctx, "Rejected resource URL mode: %v", err)
_ = c.Error(err)
return
}
// Merge single knowledge_base_id into knowledge_base_ids for backward compatibility
knowledgeBaseIDs := request.KnowledgeBaseIDs
if request.KnowledgeBaseID != "" {
// Check if it's already in the list to avoid duplicates
found := false
for _, id := range knowledgeBaseIDs {
if id == request.KnowledgeBaseID {
found = true
break
}
}
if !found {
knowledgeBaseIDs = append(knowledgeBaseIDs, request.KnowledgeBaseID)
}
}
mentionScopes := tagScopesFromMentionedItems(request.MentionedItems)
requestTagIDs := dedupRequestStrings(request.TagIDs)
if err := validateUnscopedTagIDs(orphanTagIDsForScope(requestTagIDs, mentionScopes), secutils.SanitizeForLogArray(knowledgeBaseIDs)); err != nil {
logger.Error(ctx, err.Error())
c.Error(errors.NewBadRequestError(err.Error()))
return
}
tagScopes := mergeTagScopesFromRequestIDs(mentionScopes, requestTagIDs, secutils.SanitizeForLogArray(knowledgeBaseIDs))
if len(knowledgeBaseIDs) == 0 && len(request.KnowledgeIDs) == 0 && len(tagScopes) == 0 {
logger.Error(ctx, "No knowledge base IDs, knowledge IDs, or tag scopes provided")
c.Error(errors.NewBadRequestError("At least one knowledge_base_id, knowledge_base_ids, knowledge_ids, or scoped tag must be provided"))
return
}
if err := types.AuthorizeTenantAPIKeyKnowledgeTargets(ctx, knowledgeBaseIDs, request.KnowledgeIDs); err != nil {
c.Error(err)
return
}
opts, err := knowledgeSearchOptions(&request)
if err != nil {
_ = c.Error(errors.NewBadRequestError(err.Error()))
return
}
logger.Infof(
ctx,
"Knowledge search request, knowledge base IDs: %v, knowledge IDs: %v, tag scopes: %d, query: %s",
secutils.SanitizeForLogArray(knowledgeBaseIDs),
secutils.SanitizeForLogArray(request.KnowledgeIDs),
len(tagScopes),
secutils.SanitizeForLog(request.Query),
)
// Directly call knowledge retrieval service without LLM summarization
retrieval, err := h.sessionService.SearchKnowledge(
ctx, knowledgeBaseIDs, request.KnowledgeIDs, tagScopes, request.Query, opts,
)
if err != nil {
// Typed AppErrors (e.g. an unknown rerank model_id) keep their code.
if appErr, ok := errors.IsAppError(err); ok {
_ = c.Error(appErr)
return
}
logger.ErrorWithFields(ctx, err, nil)
c.Error(errors.NewInternalServerError(err.Error()))
return
}
logger.Infof(ctx, "Knowledge search completed, found %d results", len(retrieval.Results))
c.JSON(http.StatusOK, gin.H{
"success": true,
"data": rewriter.CopyReferences(ctx, retrieval.Results),
"meta": retrieval.Meta,
})
}
// knowledgeSearchOptions validates the retrieval overrides of a
// knowledge-search request.
func knowledgeSearchOptions(request *SearchKnowledgeRequest) (*types.KnowledgeSearchOptions, error) {
if request.MatchCount < 0 {
return nil, fmt.Errorf("match_count must not be negative")
}
if request.MatchCount > types.MaxRequestedResults {
return nil, fmt.Errorf("match_count must not exceed %d", types.MaxRequestedResults)
}
if request.DisableVectorMatch && request.DisableKeywordsMatch {
return nil, fmt.Errorf("disable_vector_match and disable_keywords_match cannot both be true")
}
if err := request.Rerank.Validate(); err != nil {
return nil, err
}
return &types.KnowledgeSearchOptions{
VectorThreshold: request.VectorThreshold,
KeywordThreshold: request.KeywordThreshold,
MatchCount: request.MatchCount,
DisableKeywordsMatch: request.DisableKeywordsMatch,
DisableVectorMatch: request.DisableVectorMatch,
Rerank: request.Rerank,
}, nil
}
// KnowledgeQA godoc
// @Summary 知识问答
// @Description 基于知识库的问答(使用LLM总结),支持SSE流式响应
// @Tags 问答
// @Accept json
// @Produce text/event-stream
// @Param session_id path string true "会话ID"
// @Param request body CreateKnowledgeQARequest true "问答请求"
// @Param resource_urls query string false "文件引用形式,public 返回可加载直链" Enums(handle, public) default(handle)
// @Success 200 {string} string "SSE 事件流"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /knowledge-chat/{session_id} [post]
func (h *Handler) KnowledgeQA(c *gin.Context) {
// Parse and validate request
reqCtx, request, err := h.parseQARequest(c, "KnowledgeQA")
if err != nil {
c.Error(err)
return
}
// Execute normal mode QA, generate title unless disabled
if request.LocalBrowserEnabled {
_ = c.Error(errors.NewBadRequestError("Local browser requests must use the agent endpoint"))
return
}
h.executeQA(reqCtx, qaModeNormal, !request.DisableTitle)
}
// AgentQA godoc
// @Summary Agent问答
// @Description 基于Agent的智能问答,支持多轮对话和SSE流式响应
// @Tags 问答
// @Accept json
// @Produce text/event-stream
// @Param session_id path string true "会话ID"
// @Param request body CreateKnowledgeQARequest true "问答请求"
// @Param resource_urls query string false "文件引用形式,public 返回可加载直链" Enums(handle, public) default(handle)
// @Success 200 {string} string "SSE 事件流"
// @Failure 400 {object} errors.AppError "请求参数错误"
// @Security Bearer
// @Security ApiKeyAuth
// @Router /agent-chat/{session_id} [post]
func (h *Handler) AgentQA(c *gin.Context) {
// Parse and validate request
reqCtx, request, err := h.parseQARequest(c, "AgentQA")
if err != nil {
c.Error(err)
return
}
// Determine if agent mode should be enabled
// Priority: customAgent.IsAgentMode() > request.AgentEnabled
agentModeEnabled := request.AgentEnabled
if reqCtx.customAgent != nil {
agentModeEnabled = reqCtx.customAgent.IsAgentMode()
logger.Infof(reqCtx.ctx, "Agent mode determined by custom agent: %v (config.agent_mode=%s)",
agentModeEnabled, reqCtx.customAgent.Config.AgentMode)
}
// Sanity gate: agent mode requires a resolved CustomAgent. If we got
// here with agent_enabled=true but agent_id missing/unresolvable, the
// AgentQA service will fail deep inside the async goroutine with a
// generic "custom agent configuration is required" error and the user
// just sees a broken stream. Reject early with a clear 400 so the
// frontend can recover (e.g. fall back to quick-answer). Most likely
// cause is a stale localStorage settings blob where selectedAgentId
// got blanked but isAgentEnabled stayed true — usually after a
// cross-tenant switch where the previously selected agent is no
// longer visible.
if agentModeEnabled && reqCtx.customAgent == nil {
logger.Warnf(reqCtx.ctx,
"Agent mode requested without a resolvable agent_id, rejecting; session=%s, request.AgentID=%q",
reqCtx.sessionID, secutils.SanitizeForLog(request.AgentID))
c.Error(errors.NewBadRequestError(
"agent_id is required when agent mode is enabled"))
return
}
// Route to appropriate handler based on agent mode
if agentModeEnabled {
h.executeQA(reqCtx, qaModeAgent, true)
} else {
logger.Infof(reqCtx.ctx, "Agent mode disabled, delegating to normal mode for session: %s", reqCtx.sessionID)
h.executeQA(reqCtx, qaModeNormal, !request.DisableTitle)
}
}
// qaMode determines which QA execution path to use.
type qaMode int
const (
qaModeNormal qaMode = iota // KnowledgeQA pipeline (RAG / pure chat)
qaModeAgent // Agent engine with tool calling
)
// persistTurnMessages writes the user and assistant rows for this turn.
// Follow-up handoff calls it before SetLiveRun so POST /steer can verify the
// new assistant instead of seeing an empty session. executeQA skips work that
// is already done when those IDs are populated.
func (h *Handler) persistTurnMessages(ctx context.Context, reqCtx *qaRequestContext) error {
createdUser := false
if reqCtx.userMessageID == "" {
userMessageAttachments := reqCtx.attachments
if len(reqCtx.attachmentMetas) > 0 {
userMessageAttachments = append(
append(types.MessageAttachments{}, reqCtx.attachments...),
reqCtx.attachmentMetas...,
)
}
userMsg, err := h.createUserMessage(
ctx,
reqCtx.sessionID,
reqCtx.userInput,
reqCtx.requestID,
reqCtx.mentionedItems,
convertImageAttachments(reqCtx.images),
userMessageAttachments,
reqCtx.channel,
reqCtx.suggestionAttribution,
)
if err != nil {
return err
}
reqCtx.userMessageID = userMsg.ID
reqCtx.userCreatedAt = userMsg.CreatedAt
createdUser = true
}
if reqCtx.assistantMessage == nil {
reqCtx.assistantMessage = &types.Message{
SessionID: reqCtx.sessionID,
Role: "assistant",
IsCompleted: false,
RequestID: reqCtx.requestID,
CreatedAt: time.Now(),
}
}
if reqCtx.assistantMessage.ID == "" {
assistantMessagePtr, err := h.createAssistantMessage(ctx, reqCtx.assistantMessage)
if err != nil {
h.rollbackTurnMessages(ctx, reqCtx, createdUser, false)
return err
}
reqCtx.assistantMessage = assistantMessagePtr
}
return nil
}
// rollbackTurnMessages deletes user/assistant rows this request just created
// so a failed SetLiveRun / ClaimLiveRun cannot leave an orphan turn in history.
func (h *Handler) rollbackTurnMessages(ctx context.Context, reqCtx *qaRequestContext, user, assistant bool) {
if h.messageService == nil || reqCtx == nil {
return
}
sessionID := reqCtx.sessionID
if user && reqCtx.userMessageID != "" {
if err := h.messageService.DeleteMessage(ctx, sessionID, reqCtx.userMessageID); err != nil {
logger.Warnf(ctx, "turn rollback failed for user message %s: %v", reqCtx.userMessageID, err)
} else {
reqCtx.userMessageID = ""
}
}
if assistant && reqCtx.assistantMessage != nil && reqCtx.assistantMessage.ID != "" {
if err := h.messageService.DeleteMessage(ctx, sessionID, reqCtx.assistantMessage.ID); err != nil {
logger.Warnf(ctx, "turn rollback failed for assistant message %s: %v", reqCtx.assistantMessage.ID, err)
} else {
reqCtx.assistantMessage.ID = ""
}
}
}
func (h *Handler) rejectIfOtherAgentRunLive(ctx context.Context, reqCtx *qaRequestContext) error {
liveID, _, err := h.streamManager.GetLiveRun(ctx, reqCtx.sessionID)
if err != nil {
return errors.NewServiceUnavailableError("Failed to look up running turn")
}
if liveID == "" {
return nil
}
self := ""
if reqCtx.assistantMessage != nil {
self = reqCtx.assistantMessage.ID
}
if liveID == self {
return nil
}
return errors.NewConflictError("another turn is already running in this session")
}
func (h *Handler) rejectIfSessionRewinding(ctx context.Context, sessionID string) error {
type rewindSendGuard interface {
RejectSendIfRewinding(context.Context, string) error
}
guard, ok := h.sessionService.(rewindSendGuard)
if !ok {
return nil
}
err := guard.RejectSendIfRewinding(ctx, sessionID)
if err == nil {
return nil
}
if stderrors.Is(err, sandbox.ErrSessionRewindLocked) {
return errors.NewConflictError("session rewind is in progress")
}
return errors.NewInternalServerError(err.Error())
}
func (h *Handler) holdQATurn(ctx context.Context, reqCtx *qaRequestContext) (func(), bool) {
noop := func() {}
if reqCtx == nil {
return noop, true
}
type sessionTurnHolder interface {
HoldSandboxTurn(context.Context, string, string) (func(), error)
}
holder, ok := h.sessionService.(sessionTurnHolder)
if !ok {
return noop, true
}
configID := ""
if reqCtx.customAgent != nil {
configID = reqCtx.customAgent.Config.SandboxConfigID
}
release, err := holder.HoldSandboxTurn(ctx, reqCtx.sessionID, configID)
if err == nil {
// The QA service reads this off the built request and skips its own
// hold, so the send path opens and closes the lease exactly once.
reqCtx.turnLeaseHeld = true
}
if err != nil {
if reqCtx.c != nil && !reqCtx.skipSSE {
if stderrors.Is(err, sandbox.ErrSessionRewindLocked) || stderrors.Is(err, sandbox.ErrSessionTurnActive) {
_ = reqCtx.c.Error(errors.NewConflictError("session rewind is in progress"))
} else {
_ = reqCtx.c.Error(errors.NewInternalServerError(err.Error()))
}
} else {
logger.ErrorWithFields(ctx, err, map[string]interface{}{"session_id": reqCtx.sessionID})
}
return noop, false
}
if release == nil {
release = noop
}
var once sync.Once
return func() { once.Do(release) }, true
}
// executeQA is the unified execution flow for both KnowledgeQA and AgentQA modes.
// It handles message creation, SSE setup, VLM analysis, service invocation, and error handling.
func (h *Handler) executeQA(reqCtx *qaRequestContext, mode qaMode, generateTitle bool) {
ctx := reqCtx.ctx
sessionID := reqCtx.sessionID
// Persist the input-bar state used for this request so reopening the
// session can rehydrate agent / model / KB / web-search / MCP selections.
// This is a pure UI memo (no behavioural effect) and runs in a goroutine
// to avoid adding a DB round-trip to TTFB. Use WithoutCancel so a fast
// client disconnect doesn't drop the write.
if reqCtx.resume == nil {
go h.persistLastRequestState(ctx, reqCtx, mode)
}
if mode == qaModeAgent {
if err := h.rejectIfOtherAgentRunLive(ctx, reqCtx); err != nil {
if reqCtx.c != nil && !reqCtx.skipSSE {
_ = reqCtx.c.Error(err)
} else {
logger.ErrorWithFields(ctx, err, map[string]interface{}{"session_id": sessionID})
}
return
}
}
if err := h.rejectIfSessionRewinding(ctx, sessionID); err != nil {
if reqCtx.c != nil && !reqCtx.skipSSE {
_ = reqCtx.c.Error(err)
} else {
logger.ErrorWithFields(ctx, err, map[string]interface{}{"session_id": sessionID})
}
return
}
// A new message moves on from any prompt still waiting for an answer.
// Its run is closed first so the history this turn loads is well formed.
if reqCtx.resume == nil {
h.supersedeSuspendedRuns(ctx, sessionID)
}
releaseQATurn, held := h.holdQATurn(ctx, reqCtx)
if !held {
return
}
// Agent mode: emit agent query event before message creation
if mode == qaModeAgent {
if err := event.Emit(ctx, event.Event{
Type: event.EventAgentQuery,
SessionID: sessionID,
RequestID: reqCtx.requestID,
Data: event.AgentQueryData{
SessionID: sessionID,
Query: reqCtx.query,
RequestID: reqCtx.requestID,
},
}); err != nil {
releaseQATurn()
logger.Errorf(ctx, "Failed to emit agent query event: %v", err)
return
}
}
createdUser := reqCtx.userMessageID == ""
createdAssistant := reqCtx.assistantMessage == nil || reqCtx.assistantMessage.ID == ""
// Create user message. Include pre-uploaded document metadata so history
// reload shows the attachments even though their content is selected later.
if err := h.persistTurnMessages(ctx, reqCtx); err != nil {
releaseQATurn()
if reqCtx.c != nil && !reqCtx.skipSSE {
_ = reqCtx.c.Error(errors.NewInternalServerError(err.Error()))
} else {
logger.ErrorWithFields(ctx, err, map[string]interface{}{"session_id": sessionID})
}
return
}
if mode == qaModeNormal {
logger.Infof(ctx, "Using knowledge bases: %v", reqCtx.knowledgeBaseIDs)
} else {
logger.Infof(ctx, "Calling agent QA service, session ID: %s", sessionID)
}
// Move the previous run's leftovers onto this run's queue before the run
// announces itself as live. The other order leaves a window where a
// client that reloads the queue sees an empty one and drops messages the
// user can still see in the composer.
if len(reqCtx.steerCarryOver) > 0 && reqCtx.assistantMessage != nil {
if err := h.streamManager.AppendSteerEvents(
ctx, sessionID, reqCtx.assistantMessage.ID, reqCtx.steerCarryOver,
); err != nil {
logger.Warnf(ctx, "steer carry-over append failed for session %s: %v", sessionID, err)
}
}
// Setup SSE stream
streamCtx := h.setupSSEStream(reqCtx, generateTitle, mode)
streamCtx.releaseTurn = releaseQATurn
if streamCtx.liveRunFailed {
if streamCtx.cancel != nil {
streamCtx.cancel()
}
releaseQATurn()
h.rollbackTurnMessages(ctx, reqCtx, createdUser, createdAssistant)
if reqCtx.c != nil && !reqCtx.skipSSE {
if stderrors.Is(streamCtx.liveRunErr, stream.ErrLiveRunExists) {
_ = reqCtx.c.Error(errors.NewConflictError("another turn is already running in this session"))
} else {
_ = reqCtx.c.Error(errors.NewServiceUnavailableError("Failed to publish running turn"))
}
}
return
}
// Normal mode: register completion handler on EventAgentFinalAnswer
// (Agent mode handles completion in the defer block instead)
if mode == qaModeNormal {
var completionHandled bool
// Persist the pipeline's retrieval/attachment stages so a reloaded
// conversation redraws the timeline it showed while streaming, including
// turns that searched and cited nothing.
registerQuickAnswerTimelineRecorder(streamCtx.eventBus, streamCtx.assistantMessage)
// Persist reasoning_content into agent_steps so historical reload can
// reconstruct the thinking card (same shape as Agent-mode steps).
// Accumulate on assistantMessage directly so user-initiated stop also
// keeps whatever reasoning had streamed before the cancel.
streamCtx.eventBus.On(event.EventAgentThought, func(ctx context.Context, evt event.Event) error {
data, ok := evt.Data.(event.AgentThoughtData)
if !ok || data.Content == "" {
return nil
}
appendQuickAnswerReasoning(streamCtx.assistantMessage, data.Content)
return nil
})
streamCtx.eventBus.On(event.EventAgentFinalAnswer, func(ctx context.Context, evt event.Event) error {
data, ok := evt.Data.(event.AgentFinalAnswerData)
if !ok {
return nil
}
streamCtx.assistantMessage.Content += data.Content
if data.IsFallback {
streamCtx.assistantMessage.IsFallback = true
}
if data.Truncated {
markQuickAnswerTruncated(streamCtx.assistantMessage)
}
if data.Done {
if completionHandled {
return nil
}
completionHandled = true
logger.Infof(streamCtx.asyncCtx, "Knowledge QA service completed for session: %s", sessionID)
updateCtx := context.WithValue(streamCtx.asyncCtx, types.TenantIDContextKey, reqCtx.session.TenantID)
h.completeQuickAnswerTurn(updateCtx, streamCtx, reqCtx.query, reqCtx.userMessageID)
}
return nil
})
// A failed pipeline never streams EventAgentFinalAnswer with Done=true,
// so the turn would otherwise end with an empty, incomplete assistant
// row: the live UI shows the error event, but a refresh renders a blank
// bubble and the SSE stream never closes (issue #4145).
h.registerQuickAnswerFailureHandler(streamCtx, &completionHandled, reqCtx.session.TenantID)
}
// Execute QA asynchronously
asyncDone := make(chan struct{})
go func() {
defer close(asyncDone)
defer func() {
if r := recover(); r != nil {
if streamCtx.releaseTurn != nil {
streamCtx.releaseTurn()
}
buf := make([]byte, 10240)
runtime.Stack(buf, true)
stageName := "Knowledge QA"
if mode == qaModeAgent {
stageName = "Agent QA"
}
logger.ErrorWithFields(streamCtx.asyncCtx,
errors.NewInternalServerError(fmt.Sprintf("%s service panicked: %v\n%s", stageName, r, string(buf))),
map[string]interface{}{"session_id": sessionID})
}
// Agent mode: complete the assistant message in defer (normal mode does it via event handler)
if mode == qaModeAgent {
if streamCtx.releaseTurn != nil {
streamCtx.releaseTurn()
}
if streamCtx.streamHandler != nil {
if suspension := streamCtx.streamHandler.Suspension(); suspension != nil && suspension.Detached {
return // The new owner controls persistence and the live-run marker.
}
}
// Use WithoutCancel so a user-triggered stop (which cancels
// asyncCtx) doesn't also cancel the GORM UPDATE that persists
// AgentSteps/Content. Without this, cancelled-ctx makes
// GORM skip the write and the agent's intermediate steps
// (thinking / tool_call history) are lost on page refresh.
updateCtx := context.WithValue(
context.WithoutCancel(streamCtx.asyncCtx),
types.TenantIDContextKey, reqCtx.session.TenantID,
)
// Claim any follow-up before completing this row. liveAgentRun
// treats a completed assistant as idle and would ClearLiveRun
// the old marker — exactly the new_run window. The follow-up
// SetLiveRun's first; this run's CAS ClearLiveRun then no-ops.
if streamCtx.asyncCtx.Err() != nil {
// The turn was cancelled — a user stop. Stopping means
// stopping: queued follow-ups are dropped rather than
// fired off as a brand-new run the user did not ask for.
injected := map[string]struct{}{}
if streamCtx.steerSink != nil {
injected = streamCtx.steerSink.InjectedIDs()
}
h.discardSteerBacklog(updateCtx, sessionID, streamCtx.assistantMessage.ID, injected)
h.completeStreamAssistantMessage(
updateCtx, streamCtx, reqCtx.query, reqCtx.userMessageID,
)
} else {
kicked := h.kickNextRunFromSteerBacklog(updateCtx, reqCtx, streamCtx)
h.completeStreamAssistantMessage(
updateCtx, streamCtx, reqCtx.query, reqCtx.userMessageID,
)
// A /steer that landed while we were completing still sits
// on this run. Claim it before ClearLiveRun so it is not
// stranded on a list nobody will drain.
if !kicked {
h.kickNextRunFromSteerBacklog(updateCtx, reqCtx, streamCtx)
}
}
if err := h.streamManager.ClearLiveRun(
updateCtx, sessionID, streamCtx.assistantMessage.ID,
); err != nil {
logger.Warnf(updateCtx, "live run cleanup failed for session %s: %v", sessionID, err)
}
logger.Infof(streamCtx.asyncCtx, "Agent QA service completed for session: %s", sessionID)
}
// Knowledge mode normally releases on EventAgentFinalAnswer Done.
// If that event never fires, release here so rewind is not blocked
// until the Redis turn TTL expires.
if mode == qaModeNormal && streamCtx.releaseTurn != nil {
streamCtx.releaseTurn()
}
}()
// Resolve pre-uploaded attachments (may still be parsing): waits with a
// timeline step so the send is not blocked, then injects content/images.
if mode == qaModeAgent {
h.describeTemporaryAttachmentsForAgent(streamCtx, reqCtx)
} else {
h.resolveTemporaryAttachments(streamCtx, reqCtx)
}
// Run VLM image analysis if applicable
h.runVLMAnalysisIfNeeded(streamCtx, reqCtx, mode)
// Build QA request and invoke the appropriate service
qaReq := reqCtx.buildQARequest()
var serviceErr error
var stageName string
if mode == qaModeNormal {
stageName = "knowledge_qa_execution"
serviceErr = h.sessionService.KnowledgeQA(streamCtx.asyncCtx, qaReq, streamCtx.eventBus)
} else {
stageName = "agent_execution"
serviceErr = h.sessionService.AgentQA(streamCtx.asyncCtx, qaReq, streamCtx.eventBus)
}
if serviceErr != nil {
if mode == qaModeNormal && streamCtx.releaseTurn != nil {
streamCtx.releaseTurn()
}
// A user-requested stop cancels asyncCtx, which surfaces here as a
// context cancellation. That is an expected outcome, not a failure:
// the stop event already notifies the client, so don't emit a
// spurious error event (which would otherwise show an error toast).
if streamCtx.asyncCtx.Err() != nil {
logger.Infof(streamCtx.asyncCtx, "QA cancelled by user stop for session: %s", sessionID)
} else {
logger.ErrorWithFields(streamCtx.asyncCtx, serviceErr, nil)
streamCtx.eventBus.Emit(streamCtx.asyncCtx, event.Event{
Type: event.EventError,
SessionID: sessionID,
Data: event.ErrorData{
Error: serviceErr.Error(),
Stage: stageName,
SessionID: sessionID,
},
})
}
}
}()
if reqCtx.skipSSE {
<-asyncDone
return
}
// Handle SSE events (blocking)
shouldWaitForTitle := generateTitle && reqCtx.session.Title == ""
h.handleAgentEventsForSSE(ctx, reqCtx.c, sessionID, reqCtx.assistantMessage.ID,
reqCtx.requestID, streamCtx.eventBus, shouldWaitForTitle, reqCtx.resourceRewriter)
}
// runVLMAnalysisIfNeeded runs VLM image analysis within the async goroutine,
// emitting tool_call/tool_result events so the user can see progress.
// For normal mode, VLM only runs on the pure-chat path (no KB, no web search);
// RAG paths defer VLM to the pipeline rewrite step.
// For agent mode, VLM always runs when images and a VLM model are present.
func (h *Handler) runVLMAnalysisIfNeeded(streamCtx *sseStreamContext, reqCtx *qaRequestContext, mode qaMode) {
if len(reqCtx.images) == 0 || reqCtx.customAgent == nil || reqCtx.customAgent.Config.VLMModelID == "" {
return
}
sessionID := reqCtx.sessionID
// In normal mode, only run VLM for pure-chat path
if mode == qaModeNormal {
hasRequestKBs := len(reqCtx.knowledgeBaseIDs) > 0 || len(reqCtx.knowledgeIDs) > 0
agentWillResolveKBs := false
if !hasRequestKBs && reqCtx.customAgent != nil && !reqCtx.customAgent.Config.RetrieveKBOnlyWhenMentioned {
switch reqCtx.customAgent.Config.KBSelectionMode {
case "all":
agentWillResolveKBs = true
case "selected", "":
agentWillResolveKBs = len(reqCtx.customAgent.Config.KnowledgeBases) > 0
case "none":
agentWillResolveKBs = false
default:
agentWillResolveKBs = len(reqCtx.customAgent.Config.KnowledgeBases) > 0
}
}
if hasRequestKBs || agentWillResolveKBs || reqCtx.webSearchEnabled {
return // VLM will be handled by the pipeline rewrite step
}
}
// Emit VLM tool call/result events
toolCallID := uuid.New().String()
iteration := 0 // agent mode uses iteration field
streamCtx.eventBus.Emit(streamCtx.asyncCtx, event.Event{
Type: event.EventAgentToolCall,
SessionID: sessionID,
Data: event.AgentToolCallData{
ToolCallID: toolCallID,
ToolName: "image_analysis",
Iteration: iteration,
},
})
vlmStart := time.Now()
h.analyzeImageAttachments(streamCtx.asyncCtx, reqCtx.images,
reqCtx.customAgent.Config.VLMModelID, reqCtx.query)
outputMsg := "已分析图片内容"
if mode == qaModeAgent {
outputMsg = "已查看图片内容"
}
streamCtx.eventBus.Emit(streamCtx.asyncCtx, event.Event{
Type: event.EventAgentToolResult,
SessionID: sessionID,
Data: event.AgentToolResultData{
ToolCallID: toolCallID,
ToolName: "image_analysis",
Output: outputMsg,
Success: true,
Duration: time.Since(vlmStart).Milliseconds(),
Iteration: iteration,
},
})
}
// defaultAttachmentParseWaitTimeout bounds how long a QA turn waits for
// still-parsing attachments before proceeding with only the finished ones.
// Large or scanned documents can exceed this; raise it via
// WEKNORA_CHAT_ATTACHMENT_WAIT_TIMEOUT_SEC when needed.
const defaultAttachmentParseWaitTimeout = 60 * time.Second
// attachmentParseWaitTimeout returns the configured wait timeout, honoring the
// WEKNORA_CHAT_ATTACHMENT_WAIT_TIMEOUT_SEC override (in seconds) and falling
// back to the default when unset or invalid.
func attachmentParseWaitTimeout() time.Duration {
if raw := strings.TrimSpace(os.Getenv("WEKNORA_CHAT_ATTACHMENT_WAIT_TIMEOUT_SEC")); raw != "" {
if secs, err := strconv.Atoi(raw); err == nil && secs > 0 {
return time.Duration(secs) * time.Second
}
}
return defaultAttachmentParseWaitTimeout
}
// resolveTemporaryAttachments selects prompt content for pre-uploaded documents
// after the SSE stream is live. When any attachment is still parsing it emits a
// "attachment_parsing" timeline step and waits (bounded); unfinished attachments
// are skipped rather than blocking or failing the whole turn.
func (h *Handler) resolveTemporaryAttachments(streamCtx *sseStreamContext, reqCtx *qaRequestContext) {
if len(reqCtx.attachmentIDs) == 0 {
return
}
ctx := streamCtx.asyncCtx
sessionID := reqCtx.sessionID
// Prefer the session's tenant over gin.Context: this runs in an async
// goroutine after the HTTP handler may have returned.
tenantID := reqCtx.session.TenantID
start := time.Now()
var toolCallID string
if h.hasPendingAttachments(ctx, tenantID, sessionID, reqCtx.attachmentIDs) {
toolCallID = uuid.New().String()
streamCtx.eventBus.Emit(ctx, event.Event{
Type: event.EventAgentToolCall,
SessionID: sessionID,
Data: event.AgentToolCallData{
ToolCallID: toolCallID,
ToolName: "attachment_parsing",
Iteration: 0,
},
})
waitTimeout := attachmentParseWaitTimeout()
if reqCtx.customAgent != nil && reqCtx.customAgent.Config.AttachmentParseWaitTimeoutSec > 0 {
waitTimeout = time.Duration(reqCtx.customAgent.Config.AttachmentParseWaitTimeoutSec) * time.Second
}
h.waitForAttachments(ctx, tenantID, sessionID, reqCtx.attachmentIDs, waitTimeout)
}
readyIDs, skipped := h.partitionReadyAttachments(ctx, tenantID, sessionID, reqCtx.attachmentIDs)
var temporaryResult *types.TemporaryDocumentPromptResult
var resolveErr error
if len(readyIDs) > 0 {
temporaryResult, resolveErr = h.temporaryDocuments.ResolveForPrompt(ctx, tenantID, sessionID, readyIDs, reqCtx.query)
}
if toolCallID != "" {
output := fmt.Sprintf("已解析 %d 个附件", len(readyIDs))
if skipped > 0 {
output += fmt.Sprintf(",%d 个未完成已跳过", skipped)
}
success := resolveErr == nil
if resolveErr != nil {
output = fmt.Sprintf("附件解析失败: %v", resolveErr)
}
streamCtx.eventBus.Emit(ctx, event.Event{
Type: event.EventAgentToolResult,
SessionID: sessionID,
Data: event.AgentToolResultData{
ToolCallID: toolCallID,
ToolName: "attachment_parsing",
Output: output,
Success: success,
Duration: time.Since(start).Milliseconds(),
Iteration: 0,
Data: map[string]interface{}{
"display_type": "attachment_parsing",
"parsed_count": len(readyIDs),
"skipped_count": skipped,
},
},
})
}
if resolveErr != nil || temporaryResult == nil {
if resolveErr != nil {
logger.Warnf(ctx, "temporary attachment resolution failed for session %s: %v", sessionID, resolveErr)
}
return
}
h.applyTemporaryAttachments(ctx, reqCtx, temporaryResult)
}
// describeTemporaryAttachmentsForAgent hands an agent turn a manifest of the
// pre-uploaded documents without waiting for parsing to finish or choosing
// content by the question. The agent reads attachments itself through
// read_file's attachment:// paths, which wait for a document that is still
// parsing only when the agent actually needs it.
func (h *Handler) describeTemporaryAttachmentsForAgent(streamCtx *sseStreamContext, reqCtx *qaRequestContext) {
if len(reqCtx.attachmentIDs) == 0 {
return
}
ctx := streamCtx.asyncCtx
h.awaitImageAttachmentsForAgent(streamCtx, reqCtx)
result, err := h.temporaryDocuments.DescribeForAgent(
ctx, reqCtx.session.TenantID, reqCtx.sessionID, reqCtx.attachmentIDs,
)
if err != nil || result == nil {
if err != nil {
logger.Warnf(ctx, "temporary attachment manifest failed for session %s: %v", reqCtx.sessionID, err)
}
return
}
h.applyTemporaryAttachments(ctx, reqCtx, result)
}
// awaitImageAttachmentsForAgent waits for standalone image uploads. Document
// images are read on demand through read_file.
func (h *Handler) awaitImageAttachmentsForAgent(streamCtx *sseStreamContext, reqCtx *qaRequestContext) {
if reqCtx.customAgent == nil || !reqCtx.customAgent.Config.ImageUploadEnabled {
return
}
var imageIDs []string
for _, meta := range reqCtx.attachmentMetas {
if meta.ID != "" && docparser.IsImageFormat(meta.FileType) {
imageIDs = append(imageIDs, meta.ID)
}
}
ctx := streamCtx.asyncCtx
tenantID := reqCtx.session.TenantID
if len(imageIDs) == 0 || !h.hasPendingAttachments(ctx, tenantID, reqCtx.sessionID, imageIDs) {
return
}
start := time.Now()
toolCallID := uuid.New().String()
_ = streamCtx.eventBus.Emit(ctx, event.Event{
Type: event.EventAgentToolCall,
SessionID: reqCtx.sessionID,
Data: event.AgentToolCallData{ToolCallID: toolCallID, ToolName: "attachment_parsing"},
})
waitTimeout := attachmentParseWaitTimeout()
if reqCtx.customAgent.Config.AttachmentParseWaitTimeoutSec > 0 {
waitTimeout = time.Duration(reqCtx.customAgent.Config.AttachmentParseWaitTimeoutSec) * time.Second
}
h.waitForAttachments(ctx, tenantID, reqCtx.sessionID, imageIDs, waitTimeout)
ready, skipped := h.partitionReadyAttachments(ctx, tenantID, reqCtx.sessionID, imageIDs)
output := fmt.Sprintf("已解析 %d 个附件", len(ready))
if skipped > 0 {
output += fmt.Sprintf(",%d 个未完成已跳过", skipped)
}
_ = streamCtx.eventBus.Emit(ctx, event.Event{
Type: event.EventAgentToolResult,
SessionID: reqCtx.sessionID,
Data: event.AgentToolResultData{
ToolCallID: toolCallID,
ToolName: "attachment_parsing",
Output: output,
Success: true,
Duration: time.Since(start).Milliseconds(),
Data: map[string]interface{}{
"display_type": "attachment_parsing",
"parsed_count": len(ready),
"skipped_count": skipped,
},
},
})
}
// applyTemporaryAttachments filters resolved attachments by the agent's
// supported file types, adds them (and their images) to the turn, and stores
// the selected content on the user message for later history replay.
func (h *Handler) applyTemporaryAttachments(
ctx context.Context, reqCtx *qaRequestContext, temporaryResult *types.TemporaryDocumentPromptResult,
) {
attachments := temporaryResult.Attachments
if reqCtx.customAgent != nil && len(reqCtx.customAgent.Config.SupportedFileTypes) > 0 {
filtered := attachments[:0]
for _, att := range attachments {
ext := strings.TrimPrefix(strings.ToLower(att.FileType), ".")
if containsFileType(reqCtx.customAgent.Config.SupportedFileTypes, ext) {
filtered = append(filtered, att)
}
}
attachments = filtered
}
reqCtx.attachments = append(reqCtx.attachments, attachments...)
// Persist the freshly selected content back onto the stored user message.
// The message was created with metadata-only attachment entries (content is
// selected here, after the SSE stream is live), so without this write a
// later Agent-mode turn rebuilds history from the Attachments column and
// sees empty attachments (see buildUserHistoryMessage in agent_history.go).
h.persistResolvedAttachmentContent(ctx, reqCtx, attachments)
if reqCtx.customAgent != nil && reqCtx.customAgent.Config.ImageUploadEnabled {
for _, imageURL := range temporaryResult.ImageURLs {
reqCtx.images = append(reqCtx.images, ImageAttachment{URL: imageURL})
}
}
}
// persistResolvedAttachmentContent writes the parsed content of pre-uploaded
// attachments back onto the stored user message so multi-turn history can
// replay it. Entries are matched by their temporary-document ID; only those
// present on the message are enriched. Failures are logged but never bubble up
// — losing the write only degrades follow-up context, it must not fail the turn.
func (h *Handler) persistResolvedAttachmentContent(
ctx context.Context, reqCtx *qaRequestContext, resolved types.MessageAttachments,
) {
if reqCtx.userMessageID == "" || len(resolved) == 0 {
return
}
// Detach from the request/stream lifetime and pin the session tenant so a
// user-triggered stop (which cancels asyncCtx) does not drop the write.
updateCtx := context.WithValue(
context.WithoutCancel(ctx), types.TenantIDContextKey, reqCtx.session.TenantID,
)
msg, err := h.messageService.GetMessage(updateCtx, reqCtx.sessionID, reqCtx.userMessageID)
if err != nil || msg == nil {
logger.Warnf(updateCtx, "persist attachment content: load user message %s failed: %v",
reqCtx.userMessageID, err)
return
}
byID := make(map[string]types.MessageAttachment, len(resolved))
for _, att := range resolved {
if att.ID != "" {
byID[att.ID] = att
}
}
changed := false
for i := range msg.Attachments {
if msg.Attachments[i].ID == "" {
continue
}
if enriched, ok := byID[msg.Attachments[i].ID]; ok {
msg.Attachments[i] = enriched
changed = true
}
}
if !changed {
return
}
if err := h.messageService.UpdateMessage(updateCtx, msg); err != nil {
logger.Warnf(updateCtx, "persist attachment content: update user message %s failed: %v",
reqCtx.userMessageID, err)
}
}
// normalizeTemporaryAttachmentIDs rejects oversized ID lists before any DB
// lookup, then returns a deduplicated, order-preserving list of non-empty IDs.
func normalizeTemporaryAttachmentIDs(ids []string) ([]string, error) {
if len(ids) > types.MaxTemporaryAttachmentsPerMessage {
return nil, fmt.Errorf("a message can use at most %d attachments", types.MaxTemporaryAttachmentsPerMessage)
}
out := make([]string, 0, len(ids))
seen := make(map[string]struct{}, len(ids))
for _, id := range ids {
id = strings.TrimSpace(id)
if id == "" {
continue
}
if _, ok := seen[id]; ok {
continue
}
seen[id] = struct{}{}
out = append(out, id)
}
return out, nil
}
// hasPendingAttachments reports whether any of the given documents is still
// uploading or being parsed.
func (h *Handler) hasPendingAttachments(ctx context.Context, tenantID uint64, sessionID string, ids []string) bool {
for _, id := range ids {
doc, err := h.temporaryDocuments.Get(ctx, tenantID, sessionID, id)
if err != nil || doc == nil {
continue
}
if doc.Status == types.TemporaryDocumentStatusUploaded ||
doc.Status == types.TemporaryDocumentStatusProcessing {
return true
}
}
return false
}
// waitForAttachments polls until no attachment is pending or the timeout / ctx
// cancellation fires.
func (h *Handler) waitForAttachments(ctx context.Context, tenantID uint64, sessionID string, ids []string, timeout time.Duration) {
deadline := time.Now().Add(timeout)
ticker := time.NewTicker(500 * time.Millisecond)
defer ticker.Stop()
for {
if !h.hasPendingAttachments(ctx, tenantID, sessionID, ids) || time.Now().After(deadline) {
return
}
select {
case <-ctx.Done():
return
case <-ticker.C:
}
}
}
// partitionReadyAttachments splits the ids into ready ones and a count of those
// skipped (missing, failed, or still parsing after the wait).
func (h *Handler) partitionReadyAttachments(ctx context.Context, tenantID uint64, sessionID string, ids []string) (ready []string, skipped int) {
for _, id := range ids {
doc, err := h.temporaryDocuments.Get(ctx, tenantID, sessionID, id)
if err != nil || doc == nil || doc.Status != types.TemporaryDocumentStatusReady {
skipped++
continue
}
ready = append(ready, id)
}
return ready, skipped
}
// persistLastRequestState records the input-bar state the user just sent so
// that reopening this session restores agent/model/KB/web-search/MCP picks.
// Pure UI memo — failures are logged but never bubble up; the caller runs
// this in a goroutine and is safe to discard the returned context.
func (h *Handler) persistLastRequestState(parentCtx context.Context, reqCtx *qaRequestContext, mode qaMode) {
// Detach from the HTTP request lifetime: this write must survive both
// SSE disconnects and the parent gin context being released after the
// handler returns.
ctx := logger.CloneContext(context.WithoutCancel(parentCtx))
agentEnabled := reqCtx.reqAgentEnabled
// Mirror the resolution rule used in AgentQA: a resolved custom agent's
// agent_mode wins over the request flag. For KnowledgeQA the request
// itself carries agent_enabled=false, so this collapses correctly.
if mode == qaModeAgent && reqCtx.customAgent != nil {
agentEnabled = reqCtx.customAgent.IsAgentMode()
}
state := &types.SessionLastRequestState{
AgentID: reqCtx.reqAgentID,
AgentEnabled: agentEnabled,
ModelID: reqCtx.summaryModelID,
ReasoningEffort: reqCtx.reasoningEffort,
KnowledgeBaseIDs: reqCtx.knowledgeBaseIDs,
KnowledgeIDs: reqCtx.knowledgeIDs,
TagIDs: reqCtx.tagIDs,
MCPServiceIDs: reqCtx.mcpServiceIDs,
SkillNames: reqCtx.skillNames,
MentionedItems: reqCtx.mentionedItems,
WebSearchEnabled: reqCtx.webSearchEnabled,
LocalBrowserEnabled: reqCtx.localBrowserEnabled,
}
if err := h.sessionService.UpdateSessionLastRequestState(ctx, reqCtx.sessionID, state); err != nil {
logger.Warnf(ctx, "persist last_request_state failed for session %s: %v", reqCtx.sessionID, err)
}
}
// appendQuickAnswerReasoning accumulates streamed reasoning_content from
// KnowledgeQA (fast answer) into a single AgentStep for history replay.
func appendQuickAnswerReasoning(msg *types.Message, content string) {
if content == "" {
return
}
ensureQuickAnswerStep(msg).ReasoningContent += content
}
// completeQuickAnswerTurn finishes a KnowledgeQA (fast-answer) turn.
// EventAgentComplete must run before the GORM write: handleComplete attaches
// SandboxCheckpoint (and artifacts) to the in-memory message, and
// completeAssistantMessage is the only persist on this path.
func (h *Handler) completeQuickAnswerTurn(
ctx context.Context, streamCtx *sseStreamContext, query, userMessageID string,
) {
if streamCtx == nil || streamCtx.assistantMessage == nil {
return
}
// A stop can cancel the generation context after the final answer event
// was queued. Preserve the streamed answer just as the Agent defer does.
ctx = context.WithoutCancel(ctx)
if streamCtx.eventBus != nil {
// MessageID is what handleComplete keys on. Leave FinalAnswer empty:
// KnowledgeQA already accumulated the answer on the message, and
// handleComplete would append FinalAnswer a second time.
_ = streamCtx.eventBus.Emit(ctx, event.Event{
Type: event.EventAgentComplete,
SessionID: streamCtx.assistantMessage.SessionID,
Data: event.AgentCompleteData{
MessageID: streamCtx.assistantMessage.ID,
},
})
}
h.completeStreamAssistantMessage(ctx, streamCtx, query, userMessageID)
if streamCtx.releaseTurn != nil {
streamCtx.releaseTurn()
}
}
// quickAnswerFailureContent is persisted when a pipeline error carries no
// message, so the failed turn does not save an empty answer.
const quickAnswerFailureContent = "Failed to generate the answer"
// registerQuickAnswerFailureHandler completes and persists the assistant
// message when the quick-answer pipeline reports EventError. The empty query
// keeps the failed turn out of the chat-history index, follow-up suggestions
// and memory writes — only the visible error text belongs in history.
func (h *Handler) registerQuickAnswerFailureHandler(
streamCtx *sseStreamContext, completionHandled *bool, sessionTenantID uint64,
) {
streamCtx.eventBus.On(event.EventError, func(ctx context.Context, evt event.Event) error {
data, ok := evt.Data.(event.ErrorData)
if !ok || *completionHandled {
return nil
}
*completionHandled = true
errorContent := strings.TrimSpace(data.Error)
if errorContent == "" {
errorContent = quickAnswerFailureContent
}
msg := streamCtx.assistantMessage
// Keep any partial answer the stream produced before failing and
// append the error, so a reload shows both instead of losing the text.
if remaining := strings.TrimSpace(msg.Content); remaining != "" {
msg.Content += "\n\n" + errorContent
} else {
msg.Content = errorContent
}
updateCtx := context.WithValue(
context.WithoutCancel(ctx),
types.TenantIDContextKey, sessionTenantID,
)
h.completeQuickAnswerTurn(updateCtx, streamCtx, "", "")
return nil
})
}
// sessionTenantInfoContext makes the tenant info match the session owner (the
// context's tenant here). The chat history KB is read from the tenant info,
// and a shared agent's run carries the agent workspace's: the receiver's
// conversation would be indexed into the owner's chat history KB. When the
// session tenant cannot be loaded the message is not indexed at all.
func (h *Handler) sessionTenantInfoContext(ctx context.Context) (context.Context, bool) {
tenantID, _ := types.TenantIDFromContext(ctx)
if info, ok := types.TenantInfoFromContext(ctx); ok && info != nil && info.ID == tenantID {
return ctx, true
}
if tenantID == 0 || h.tenantService == nil {
return ctx, false
}
tenant, err := h.tenantService.GetTenantByID(ctx, tenantID)
if err != nil || tenant == nil {
logger.Warnf(ctx, "Skipping chat history index: session tenant %d unavailable: %v", tenantID, err)
return ctx, false
}
return context.WithValue(ctx, types.TenantInfoContextKey, tenant), true
}
// completeStreamAssistantMessage makes output readable before notifying clients
// to perform their final image/artifact fetch. A failed write must not announce
// a successful completion whose file authorization evidence is still missing.
func (h *Handler) completeStreamAssistantMessage(
ctx context.Context, streamCtx *sseStreamContext, query, userMessageID string,
) {
if streamCtx.streamHandler != nil {
if suspension := streamCtx.streamHandler.Suspension(); suspension != nil && suspension.Detached {
return
}
}
persist := func() error {
return h.completeAssistantMessage(ctx, streamCtx.assistantMessage, query, userMessageID)
}
if streamCtx.streamHandler != nil && streamCtx.streamHandler.Suspension() != nil {
// The turn is not over: indexing, memory and follow-ups run when the
// resumed run completes.
persist = func() error {
streamCtx.assistantMessage.UpdatedAt = time.Now()
return h.messageService.UpdateMessage(ctx, streamCtx.assistantMessage)
}
}
if err := persist(); err != nil {
if streamCtx.streamHandler != nil {
_ = streamCtx.streamHandler.handleError(ctx, event.Event{
ID: uuid.New().String(), Type: event.EventError, SessionID: streamCtx.assistantMessage.SessionID,
Data: event.ErrorData{Stage: "message_persistence", Error: "Failed to save assistant message"},
})
}
return
}
if streamCtx.streamHandler != nil {
if err := streamCtx.streamHandler.publishCompletion(ctx); err != nil {
logger.Errorf(ctx, "Append persisted message completion failed: %v", err)
}
}
}
// completeAssistantMessage marks an assistant message as complete, updates it,
// and asynchronously indexes the Q&A pair into the chat history knowledge base.
func (h *Handler) completeAssistantMessage(
ctx context.Context, assistantMessage *types.Message, userQuery, userMessageID string,
) error {
assistantMessage.UpdatedAt = time.Now()
assistantMessage.IsCompleted = true
if err := h.messageService.UpdateMessage(ctx, assistantMessage); err != nil {
logger.Errorf(ctx, "Failed to persist assistant message %s: %v", assistantMessage.ID, err)
return err
}
// Asynchronously index the Q&A pair into the chat history knowledge base for vector search.
// Use WithoutCancel so the goroutine survives after the HTTP request context is done.
bgCtx := context.WithoutCancel(ctx)
if indexCtx, ok := h.sessionTenantInfoContext(bgCtx); ok {
go h.messageService.IndexMessageToKB(
indexCtx, userQuery, assistantMessage.Content, assistantMessage.ID, assistantMessage.SessionID)
}
if userQuery != "" && h.suggestionService != nil {
go func() {
if _, err := h.suggestionService.EnsureFollowUps(
bgCtx, assistantMessage.SessionID, assistantMessage.ID, false,
); err != nil {
logger.Warnf(bgCtx, "follow-up suggestion generation failed for message %s: %v", assistantMessage.ID, err)
}
}()
}
if userQuery != "" {
go h.recordTurnMemory(bgCtx, assistantMessage, userQuery, userMessageID)
}
return nil
}
// recordTurnMemory runs the long-term memory write path for a finished turn.
//
// This is the single place a conversation can produce memory, and it sits at
// the point where both the RAG and the Agent path converge, so neither mode
// can silently miss it. A stopped conversation arrives with an empty query and
// is skipped by the caller.
func (h *Handler) recordTurnMemory(
ctx context.Context, assistantMessage *types.Message, userQuery, userMessageID string,
) {
if h.memoryService == nil {
return
}
// An explicit "remember ..." directive is stored verbatim and immediately,
// with no model in the loop. This is what makes the default explicit_only
// mode useful rather than merely safe.
if statement, ok := types.DetectExplicitMemory(userQuery); ok {
if _, err := h.memoryService.Remember(ctx, types.MemoryItem{
Kind: types.MemoryKindFact,
Content: statement,
Importance: 4,
Origin: types.MemoryOriginExplicit,
SourceSessionID: assistantMessage.SessionID,
// Attribute to the user's own message, not the answer. Background
// distillation reads that same message, so the two paths must
// agree on provenance or a memory deleted from one can be
// re-derived by the other.
SourceMessageID: userMessageID,
}); err != nil {
logger.Warnf(ctx, "memory: explicit remember failed for message %s: %v", assistantMessage.ID, err)
}
}
h.recordAnswerSources(ctx, assistantMessage)
h.memoryService.ScheduleExtraction(ctx, assistantMessage.SessionID, assistantMessage.ID, assistantMessage.ModelID)
}
// recordAnswerSources notes which documents this answer drew on, so the
// reranker can prefer the material this person keeps working from.
//
// The references attached to an answer are a weaker signal than an explicit
// thumbs-up: they say the retriever kept picking a document, not that the user
// found it useful. They are, however, the only per-person retrieval signal
// available without asking for anything, and the boost they earn is capped
// accordingly.
func (h *Handler) recordAnswerSources(ctx context.Context, assistantMessage *types.Message) {
if len(assistantMessage.KnowledgeReferences) == 0 {
return
}
seen := make(map[string]struct{}, len(assistantMessage.KnowledgeReferences))
refs := make([]types.MemoryDocAffinity, 0, len(assistantMessage.KnowledgeReferences))
for _, ref := range assistantMessage.KnowledgeReferences {
if ref.KnowledgeID == "" {
continue
}
if _, dup := seen[ref.KnowledgeID]; dup {
continue
}
seen[ref.KnowledgeID] = struct{}{}
refs = append(refs, types.MemoryDocAffinity{
KnowledgeID: ref.KnowledgeID,
KnowledgeBaseID: ref.KnowledgeBaseID,
Title: ref.KnowledgeTitle,
})
}
h.memoryService.RecordAnswerSources(ctx, refs)
}