Open-source LLM knowledge platform: turn raw documents into a queryable RAG, an autonomous reasoning agent, and a self-maintaining Wiki.
Go agentagenticaichatbotdsh-pluginembeddingsevaluationgenerative-aigolangknowledge-basellmmulti-tenantollamaopenaiquestion-answeringragrerankingsemantic-searchvector-searchwiki
feat(chat): append messages to a running agent turn (#3123)
nullptr-errorfbaff900a09b
diff --git a/frontend/src/api/chat/steer.ts b/frontend/src/api/chat/steer.tsnew file mode 100644index 000000000..443bc9cf9--- /dev/null+++ b/frontend/src/api/chat/steer.ts@@ -0,0 +1,55 @@+import { del, get, post } from "../../utils/request";++export type SteerDelivery = 'inject' | 'after'++export type SteerQueueItem = {+ steer_id: string+ content: string+ delivery: SteerDelivery+ mentioned_items?: unknown[]+ promoting?: boolean+ awaitingIdleSend?: boolean+ // True while POST /steer is in flight. The overlay uses a client-side+ // id until the server replies with the durable one; promote/remove are+ // disabled in that window so they cannot hit /steer/{client_id}.+ pending?: boolean+ client_id?: string+}++/**+ * Append a message to a running agent turn.+ * Returns { success, status: 'queued' | 'new_run', steer_id?, delivery?, assistant_message_id? }.+ * - delivery 'after' (default): waits until the current run exits, then starts a follow-up turn.+ * - delivery 'inject': the running engine injects it at the next round boundary.+ * - 'new_run': no run is live; the caller should fall back to a normal send.+ * Lookup failures (503) reject rather than returning new_run — treating them+ * as idle would start a second turn on top of the one still generating.+ */+export async function steerSession(+ session_id: string,+ query: string,+ mentionedItems: any[] = [],+ delivery: SteerDelivery = 'after',+) {+ return post(`/api/v1/sessions/${session_id}/steer`, {+ query,+ mentioned_items: mentionedItems,+ channel: 'web',+ delivery,+ });+}++/** Flip a queued after-message to inject so the running turn reads it next. */+export async function promoteSteerSession(session_id: string, steer_id: string) {+ return post(`/api/v1/sessions/${session_id}/steer/${steer_id}/inject`, {});+}++/** Pending overlay items for the live run. Empty when nothing is generating. */+export async function listSteerSession(session_id: string) {+ return get(`/api/v1/sessions/${session_id}/steer`);+}++/** Drop a queued overlay item so it is neither injected nor sent as a follow-up. */+export async function removeSteerSession(session_id: string, steer_id: string) {+ return del(`/api/v1/sessions/${session_id}/steer/${steer_id}`);+}diff --git a/frontend/src/components/Input-field.agent-switch.test.mjs b/frontend/src/components/Input-field.agent-switch.test.mjsindex 59f1df8ca..67cc2f100 100644--- a/frontend/src/components/Input-field.agent-switch.test.mjs+++ b/frontend/src/components/Input-field.agent-switch.test.mjs@@ -35,3 +35,74 @@ test('shared-agent web search button waits for source readiness metadata', () =>assert.match(showWebSearchButton, /isWebSearchReadinessKnown/)assert.match(showWebSearchButton, /selectedSharedAgent\.value\?\.web_search_ready/)})++test('replying keeps stop visible; typed text also shows send', () => {+ const controlsStart = inputField.indexOf('class="control-right"')+ const controls = inputField.slice(controlsStart, controlsStart + 1200)+ assert.notEqual(controlsStart, -1)+ assert.doesNotMatch(inputField, /steer-delivery-toggle/)+ assert.doesNotMatch(inputField, /setSteerDelivery/)+ assert.match(inputField, /emit\('steer-msg', val\.trim\(\), steerMentions, 'after'\)/)+ assert.match(controls, /v-if="isReplying"/)+ assert.match(controls, /handleStop/)+ assert.match(controls, /v-if="!isReplying \|\| query\.trim\(\)"[\s\S]*createSession\(query\)[\s\S]*send-btn/)+ assert.doesNotMatch(controls, /v-if="isReplying && \(!canSteer \|\| !query\.trim\(\)\)"/)+})++// Only agent turns have a round boundary to take a mid-run message at, and a+// teardown that hands leftovers to a follow-up run. Queueing on a quick-answer+// turn would park the message until it expired, so the composer keeps its old+// stop-only behaviour there.+test('mid-run send is limited to agent sessions', () => {+ const chatView = readFileSync(+ new URL('../views/chat/index.vue', import.meta.url), 'utf8')+ assert.match(chatView, /:canSteer="isAgentStreamSession\(\)"/)++ const fnStart = inputField.indexOf('const createSession = async')+ const fn = inputField.slice(fnStart, fnStart + 1600)+ assert.notEqual(fnStart, -1)+ assert.match(fn, /if \(!props\.canSteer\)/)+ // The guard must come before anything queues the message.+ assert.ok(+ fn.indexOf('props.canSteer') < fn.indexOf("emit('steer-msg'"),+ 'canSteer must be checked before emitting steer-msg',+ )+})++test('queued follow-ups sit in one block with send-now and remove', () => {+ assert.match(inputField, /class="steer-queue"/)+ assert.match(inputField, /queuedSteers/)+ assert.match(inputField, /emit\('promote-steer', item\.steer_id\)/)+ assert.match(inputField, /emit\('remove-steer', item\.steer_id\)/)+ assert.match(inputField, /class="steer-queue-remove"/)+ assert.match(inputField, /\$t\('input\.steerQueueSendNow'\)/)+ assert.match(inputField, /:disabled="item\.promoting \|\| item\.pending"/)+ assert.match(inputField, /\.steer-queue-item \+ \.steer-queue-item/)+})++test('mid-run send refuses attachments that have already uploaded', () => {+ const fnStart = inputField.indexOf('const createSession = async')+ const fn = inputField.slice(fnStart, fnStart + 2200)+ assert.notEqual(fnStart, -1)+ assert.match(fn, /steerHasAttachments/)+ assert.match(fn, /uploadedImages\.value\.length/)+})++test('stop waits for the API before confirming discard', () => {+ const fnStart = inputField.indexOf('const handleStop = async')+ const fnEnd = inputField.indexOf('onBeforeRouteUpdate', fnStart)+ assert.notEqual(fnStart, -1)+ assert.notEqual(fnEnd, -1)+ const fn = inputField.slice(fnStart, fnEnd)+ assert.match(fn, /emit\('stop-generation'\)/)+ assert.match(fn, /emit\('stop-confirmed'\)/)+ assert.match(fn, /emit\('stop-failed'\)/)+ assert.ok(+ fn.indexOf("emit('stop-generation')") < fn.indexOf('await stopSession'),+ 'UI stop must fire before the stop API',+ )+ assert.ok(+ fn.indexOf('await stopSession') < fn.indexOf("emit('stop-confirmed')"),+ 'queue discard must wait for stop API success',+ )+})diff --git a/frontend/src/components/Input-field.vue b/frontend/src/components/Input-field.vueindex 1997423bd..2d476af84 100644--- a/frontend/src/components/Input-field.vue+++ b/frontend/src/components/Input-field.vue@@ -1,5 +1,5 @@<script setup lang="ts">-import { ref, onMounted, onUnmounted, computed, watch, nextTick, h } from "vue";+import { ref, onMounted, onUnmounted, computed, watch, nextTick, h, type PropType } from "vue";import { storeToRefs } from 'pinia';import { useRoute, useRouter } from 'vue-router';import { onBeforeRouteUpdate } from 'vue-router';@@ -10,6 +10,7 @@ import { useMenuStore } from '@/stores/menu';import { listKnowledgeBases, searchKnowledge, batchQueryKnowledge, listKnowledgeTags } from '@/api/knowledge-base';import { listMCPServices, type MCPService } from '@/api/mcp-service';import { stopSession } from '@/api/chat';+import type { SteerQueueItem } from '@/api/chat/steer';import { useOrganizationStore } from '@/stores/organization';import KnowledgeBaseSelector from './KnowledgeBaseSelector.vue';import MentionSelector from './MentionSelector.vue';@@ -516,6 +517,17 @@ const props = defineProps({embeddedMode: {type: Boolean,default: false+ },+ queuedSteers: {+ type: Array as PropType<SteerQueueItem[]>,+ default: () => []+ },+ // Only agent turns have a loop that can take a mid-run message. In a+ // quick-answer session the composer keeps its old behaviour: Stop is the+ // only action while a reply is streaming.+ canSteer: {+ type: Boolean,+ default: false}});@@ -1892,6 +1904,13 @@ watch([selectedKbIds, selectedFileIds], ([kbIds, fileIds]) => {const emit = defineEmits<{(e: 'send-msg', query: string, modelId: string, mentionedItems: MentionRequestItem[], imageFiles: File[], attachmentFiles: AttachmentFile[]): void;(e: 'stop-generation'): void;+ (e: 'stop-confirmed'): void;+ (e: 'stop-failed'): void;+ // Mid-run send queues until the current run exits (delivery=after).+ // Empty input while replying shows Stop; typed text also shows Send.+ (e: 'steer-msg', query: string, mentionedItems: MentionRequestItem[], delivery: 'inject' | 'after'): void;+ (e: 'promote-steer', steerId: string): void;+ (e: 'remove-steer', steerId: string): void;}>();const createSession = async (val: string) => {@@ -1900,7 +1919,37 @@ const createSession = async (val: string) => {return;}if (props.isReplying) {- return MessagePlugin.error(t('input.messages.replying'));+ if (!props.canSteer) {+ // Quick-answer turns have no round boundary to take a message at, and+ // no follow-up handoff on teardown — queueing here would park the+ // message until it expired. Stop first.+ MessagePlugin.info(t('input.messages.replying'));+ return;+ }+ // Mid-run steering: queue until the current run exits (delivery=after).+ // Attachments are intentionally not allowed on the steer path — the+ // running turn already resolved its own scope.+ if (uploadedAttachments.value.some(item => item.status === 'uploading')) {+ MessagePlugin.warning(t('input.messages.steerAttachmentPending'));+ return;+ }+ if (uploadedAttachments.value.length || uploadedImages.value.length) {+ MessagePlugin.warning(t('input.messages.steerHasAttachments'));+ return;+ }+ const steerMentions: MentionRequestItem[] = allSelectedItems.value.map(item => ({+ id: item.id,+ name: item.name,+ type: item.type,+ kb_type: item.type === 'kb' ? (item.kbType || 'document') : undefined,+ kb_id: item.kbId,+ kb_name: item.kbName,+ service_id: item.serviceId,+ skill_name: item.skillName,+ }));+ emit('steer-msg', val.trim(), steerMentions, 'after');+ clearvalue();+ return;}// Only block while the file is still uploading (no document ID yet). Once// uploaded, sending is allowed even if parsing is still in progress: the@@ -2488,14 +2537,15 @@ const handleStop = async () => {console.log('[Stop] Stopping generation for message:', props.assistantMessageId);- // 发送 stop 事件,通知父组件立即清除 loading 状态emit('stop-generation');try {await stopSession(props.sessionId, props.assistantMessageId);+ emit('stop-confirmed');MessagePlugin.success(t('input.messages.stopSuccess'));} catch (error) {console.error('Failed to stop session:', error);+ emit('stop-failed');MessagePlugin.error(t('input.messages.stopFailed'));}}@@ -2520,6 +2570,28 @@ defineExpose({<!-- Hidden file input for image upload --><input ref="imageInputRef" type="file" accept="image/jpeg,image/png,image/gif,image/webp" multiplestyle="display:none" @change="handleImageSelect" />+ <div v-if="queuedSteers.length" class="steer-queue" role="list" :aria-label="$t('input.steerQueueWaiting')">+ <div v-for="item in queuedSteers" :key="item.steer_id" class="steer-queue-item" role="listitem">+ <span class="steer-queue-text">{{ item.content }}</span>+ <div class="steer-queue-actions">+ <button+ v-if="item.delivery !== 'inject'"+ type="button"+ class="steer-queue-send-now"+ :disabled="item.promoting || item.pending"+ @click="emit('promote-steer', item.steer_id)"+ >{{ $t('input.steerQueueSendNow') }}</button>+ <span v-else class="steer-queue-hint">{{ $t('input.steerQueueInjecting') }}</span>+ <button+ type="button"+ class="steer-queue-remove"+ :aria-label="$t('common.remove')"+ :disabled="item.promoting || item.pending"+ @click="emit('remove-steer', item.steer_id)"+ >×</button>+ </div>+ </div>+ </div><!-- 富文本输入框容器 --><div class="rich-input-container" data-guide="chat-input"><!-- 图片预览区域 -->@@ -2741,10 +2813,10 @@ defineExpose({</div></Teleport>- <!-- 右侧控制按钮组 -->+ <!-- 右侧控制:回复中且输入为空是停止,一旦输入新内容同一位置变成发送 --><div class="control-right">- <!-- 停止按钮(仅在回复中时显示) -->- <t-tooltip v-if="isReplying" :content="$t('input.stopGeneration')" placement="top">+ <t-tooltip v-if="isReplying" :content="$t('input.stopGeneration')"+ placement="top"><div @click="handleStop" class="control-btn stop-btn"><svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor"><rect x="5" y="5" width="6" height="6" rx="1" />@@ -2752,8 +2824,7 @@ defineExpose({</div></t-tooltip>- <!-- 发送按钮 -->- <div v-if="!isReplying" @click="createSession(query)" class="control-btn send-btn" data-guide="chat-send"+ <div v-if="!isReplying || query.trim()" @click="createSession(query)" class="control-btn send-btn" data-guide="chat-send":class="{ 'disabled': !query.length }"><img src="../assets/img/sending-aircraft.svg" :alt="$t('input.send')" /></div>@@ -2790,7 +2861,8 @@ const getImgSrc = (url: string) => {transform: translateX(-50%);width: 100%;display: flex;- justify-content: center;+ flex-direction: column;+ align-items: center;&.is-embedded {position: relative;@@ -2799,12 +2871,104 @@ const getImgSrc = (url: string) => {transform: none;z-index: auto;- .rich-input-container {+ .rich-input-container,+ .steer-queue {max-width: 100%;}}}+.steer-queue {+ width: 100%;+ max-width: 960px;+ margin-bottom: 8px;+ background: var(--td-bg-color-container, #fff);+ border: 1px solid var(--td-component-stroke, #dcdcdc);+ border-radius: 12px;+ box-shadow: 0 2px 8px rgba(0, 0, 0, 0.04);+ overflow: hidden;+}++.steer-queue-item {+ display: flex;+ align-items: flex-start;+ gap: 10px;+ padding: 8px 12px;+}++.steer-queue-item + .steer-queue-item {+ border-top: 1px solid var(--td-component-stroke, #dcdcdc);+}++.steer-queue-text {+ flex: 1;+ min-width: 0;+ font-size: 13px;+ line-height: 1.5;+ color: var(--td-text-color-primary);+ white-space: pre-wrap;+ word-break: break-word;+}++.steer-queue-actions {+ display: flex;+ align-items: center;+ flex-shrink: 0;+ gap: 4px;+ padding-top: 1px;+}++.steer-queue-send-now {+ flex-shrink: 0;+ margin: 0;+ padding: 0 4px;+ border: 0;+ background: transparent;+ color: var(--td-brand-color, #07C05F);+ font-size: 12px;+ line-height: 22px;+ cursor: pointer;++ &:disabled {+ opacity: 0.5;+ cursor: default;+ }+}++.steer-queue-hint {+ flex-shrink: 0;+ font-size: 12px;+ line-height: 22px;+ color: var(--td-text-color-secondary);+}++.steer-queue-remove {+ display: inline-flex;+ align-items: center;+ justify-content: center;+ width: 22px;+ height: 22px;+ margin: 0;+ padding: 0;+ border: 0;+ border-radius: 50%;+ background: transparent;+ color: var(--td-text-color-placeholder, #999);+ font-size: 16px;+ line-height: 1;+ cursor: pointer;++ &:hover:not(:disabled) {+ background: var(--td-bg-color-secondarycontainer, #f3f3f3);+ color: var(--td-text-color-primary);+ }++ &:disabled {+ opacity: 0.4;+ cursor: default;+ }+}+/* 富文本输入框容器 */.rich-input-container {position: relative;diff --git a/frontend/src/composables/useChatStreamHandler.test.mjs b/frontend/src/composables/useChatStreamHandler.test.mjsindex bf7479b59..369f497a4 100644--- a/frontend/src/composables/useChatStreamHandler.test.mjs+++ b/frontend/src/composables/useChatStreamHandler.test.mjs@@ -16,3 +16,102 @@ test('later tool_call events merge arguments onto the same pending card', () =>assert.match(source, /function mergeToolCallArguments/)assert.match(source, /toolCallEvent\.arguments = mergeToolCallArguments\(toolCallEvent\.arguments, incomingArguments\)/)})++test('agent chunks bind only to the in-flight assistant after a queued user message', () => {+ const chunkStart = source.indexOf('const handleAgentChunk = ')+ const chunkEnd = source.indexOf('const processStreamChunk = ', chunkStart)+ const chunk = source.slice(chunkStart, chunkEnd)+ assert.notEqual(chunkStart, -1)+ assert.notEqual(chunkEnd, -1)+ assert.match(chunk, /resolveActiveAssistantMessage\(data\)/)+ assert.doesNotMatch(chunk, /item\.request_id === dataId \|\| item\.id === dataId/)+})++test('incomplete assistant is found even when a later user message is the list tail', () => {+ const fnStart = source.indexOf('const getTrailingIncompleteAssistant = ')+ const fnEnd = source.indexOf('const markAssistantStopped = ', fnStart)+ const fn = source.slice(fnStart, fnEnd)+ assert.notEqual(fnStart, -1)+ assert.notEqual(fnEnd, -1)+ assert.match(fn, /item\?\.role === 'assistant'/)+ assert.doesNotMatch(fn, /const last = messagesList\[messagesList\.length - 1\]/)+})++test('global typing indicator stays hidden while an in-flight agent assistant exists', () => {+ const fnStart = source.indexOf('const shouldShowGlobalTypingIndicator = ')+ const fnEnd = source.indexOf('const restoreQuickAnswerFlags = ', fnStart)+ const fn = source.slice(fnStart, fnEnd)+ assert.notEqual(fnStart, -1)+ assert.notEqual(fnEnd, -1)+ assert.match(fn, /messages\.some\(/)+ assert.match(fn, /role === 'assistant'/)+ assert.match(fn, /isAgentMode/)+ assert.match(fn, /is_completed/)+})++// Splitting a turn around an injected message can leave one segment holding+// the answer text and no timeline events. Hiding that row loses the reply.+test('completed agent messages with content but no events still render', () => {+ const fnStart = source.indexOf('const shouldRenderAssistantMessage = ')+ const fnEnd = source.indexOf('const shouldShowGlobalTypingIndicator = ', fnStart)+ const fn = source.slice(fnStart, fnEnd)+ assert.notEqual(fnStart, -1)+ assert.notEqual(fnEnd, -1)+ assert.match(fn, /session\.content/)+})++test('injected user messages fork a continuation assistant below the bubble', () => {+ const chunkStart = source.indexOf("case 'user_message_injected'")+ const chunkEnd = source.indexOf("case 'complete'", chunkStart)+ const chunk = source.slice(chunkStart, chunkEnd)+ assert.notEqual(chunkStart, -1)+ assert.notEqual(chunkEnd, -1)+ assert.match(chunk, /forkAfterInjectedUser/)+ assert.match(chunk, /onUserMessageInjected/)+ assert.match(source, /expandSteerForksInHistory\(processed\)/)+ assert.match(source, /expandSteerForksInHistory\(\[\.\.\.messagesList\]\)/)+})++test('agent answer.done does not mark the session idle', () => {+ const chunkStart = source.indexOf("case 'answer':")+ const chunkEnd = source.indexOf("case 'artifacts_pending'", chunkStart)+ assert.notEqual(chunkStart, -1)+ assert.notEqual(chunkEnd, -1)+ const chunk = source.slice(chunkStart, chunkEnd)+ assert.match(chunk, /if \(!isAgentStreamSession\(\)\)/)+ assert.ok(+ chunk.indexOf('isAgentStreamSession') < chunk.indexOf('isReplying.value = false'),+ 'agent turns must wait for complete before clearing isReplying',+ )+})++// continue-stream replays the event log from the start, so after a refresh+// this event arrives for a message history has already loaded. Synthesizing a+// bubble unconditionally puts the same message on screen twice.+test('a replayed injection reuses the persisted row instead of duplicating it', () => {+ const chunkStart = source.indexOf("case 'user_message_injected'")+ const chunkEnd = source.indexOf("case 'complete'", chunkStart)+ const chunk = source.slice(chunkStart, chunkEnd)+ assert.notEqual(chunkStart, -1)+ assert.notEqual(chunkEnd, -1)++ assert.match(chunk, /messagesList\.find\(/)+ assert.match(chunk, /item\.id === injectedId/)+ assert.match(chunk, /alreadyInList/)+ assert.match(chunk, /if \(!alreadyInList\) emitMessageCreated\(injectedUser\)/)+})++// Remote stop used to mark the assistant done and leave the overlay chips+// in place. The parent owns steerQueue, so the stream handler has to say+// the generation stopped.+test('agent and non-agent stop notify onGenerationStopped', () => {+ assert.match(source, /onGenerationStopped\?: \(\) => void/)++ const agent = source.indexOf("log('[Stop Event] Generation stopped')")+ assert.notEqual(agent, -1)+ assert.match(source.slice(agent, agent + 500), /onGenerationStopped\?\.\(\)/)++ const nonAgent = source.indexOf("log('[Stop Event] Non-agent generation stopped')")+ assert.notEqual(nonAgent, -1)+ assert.match(source.slice(nonAgent, nonAgent + 500), /onGenerationStopped\?\.\(\)/)+})diff --git a/frontend/src/composables/useChatStreamHandler.ts b/frontend/src/composables/useChatStreamHandler.tsindex 56a30b2cb..1fa61d143 100644--- a/frontend/src/composables/useChatStreamHandler.ts+++ b/frontend/src/composables/useChatStreamHandler.ts@@ -3,6 +3,7 @@ import { markRaw, nextTick, type Ref } from 'vue'import { useI18n } from 'vue-i18n'import { ensureRagPipelineHistoryStream } from '@/utils/rag-pipeline-history'import { applyMessageCreatedAt, bindServerTurnTimestamps, ensureMessageCreatedAt } from '@/utils/messageTimestamp'+import { expandSteerForksInHistory, forkAfterInjectedUser } from '@/utils/steerStreamFork'export type ChatMessage = Record<string, unknown>@@ -31,6 +32,9 @@ export interface UseChatStreamHandlerOptions {onMessageUpdated?: (message: ChatMessage, payload?: ChatMessage) => voidonAgentAnswerDone?: (message: ChatMessage) => voidonAgentChunkBound?: (message: ChatMessage, created: boolean) => void+ onUserMessageInjected?: (steerId: string) => void+ /** Remote or local stop: the composer overlay must drop server-discarded items. */+ onGenerationStopped?: () => voiddebug?: boolean}@@ -68,6 +72,8 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {onMessageUpdated,onAgentAnswerDone,onAgentChunkBound,+ onUserMessageInjected,+ onGenerationStopped,debug = false,} = options@@ -93,10 +99,12 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {return undefined}- /** Incomplete assistant row for the current turn (must be the list tail). */+ /** Incomplete assistant for the current turn, even if a later user row is the tail. */const getTrailingIncompleteAssistant = () => {- const last = messagesList[messagesList.length - 1]- if (last?.role === 'assistant' && !last.is_completed) return last+ for (let i = messagesList.length - 1; i >= 0; i--) {+ const item = messagesList[i]+ if (item?.role === 'assistant' && !item.is_completed) return item+ }return undefined}@@ -132,7 +140,12 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {let target: ChatMessage | undefinedif (messageId) {target = messagesList.find(- (m) => m.id === messageId || m.request_id === messageId,+ (m) =>+ m.role === 'assistant' &&+ !m.is_completed &&+ (m.id === messageId ||+ m.assistant_message_id === messageId ||+ m.request_id === messageId),)}if (!target) target = getTrailingIncompleteAssistant()@@ -224,6 +237,7 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {}const ensureAgentMessageShell = (message: ChatMessage, requestId?: string) => {+ if (message.role === 'user') returnmessage.isAgentMode = trueif (!isAgentStreamSession()) {message.isRagMode = true@@ -245,6 +259,11 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {if (Array.isArray(session.knowledge_references) && session.knowledge_references.length > 0) {return true}+ // A turn can carry its answer as plain content with no timeline events —+ // most visibly after a steer fork, where the events are split across+ // segments and one segment can end up holding only the answer text.+ // Hiding that row loses the reply entirely on reload.+ if (typeof session.content === 'string' && session.content.trim()) return truereturn false}@@ -254,8 +273,7 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {isRecovering = false,) => {if (!isLoading && !isRecovering) return false- const last = messages[messages.length - 1]- if (last?.role === 'assistant' && last?.isAgentMode && !last?.is_completed) {+ if (messages.some((m) => m.role === 'assistant' && m.isAgentMode && !m.is_completed)) {return false}return true@@ -465,8 +483,10 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {for (let i = processed.length - 1; i >= 0; i--) {messagesList.unshift(processed[i])}+ const expanded = expandSteerForksInHistory([...messagesList])+ messagesList.splice(0, messagesList.length, ...expanded)} else {- messagesList.push(...processed)+ messagesList.push(...expandSteerForksInHistory(processed))}}@@ -487,6 +507,7 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {const updateAssistantSession = (payload: ChatMessage) => {const message = findLastMessage((item) => {+ if (item.role !== 'assistant') return falseif (item.request_id === payload.id) return truereturn item.id === payload.id})@@ -520,11 +541,13 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {const handleAgentChunk = (data: ChatMessage) => {const dataId = data.id as string | undefined- let message = findLastMessage(- (item) => item.request_id === dataId || item.id === dataId,- )+ let message = resolveActiveAssistantMessage(data)let created = false+ if (message?.role === 'user') {+ message = undefined+ }+if (!message) {const newMsg: ChatMessage = {id: dataId,@@ -878,10 +901,15 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {if (data.done && !answerEvent.done) {answerEvent.done = trueonAgentAnswerDone?.(message)- loading.value = false- isReplying.value = false- fullContent.value = ''- currentAssistantMessageId.value = ''+ // Agent turns may continue after a finishing-round inject. Closing+ // isReplying here lets the composer start a second AgentQA. Wait+ // for `complete` (or a non-agent answer) to mark the session idle.+ if (!isAgentStreamSession()) {+ loading.value = false+ isReplying.value = false+ fullContent.value = ''+ currentAssistantMessageId.value = ''+ }}break}@@ -893,6 +921,56 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {}break}+ case 'user_message_injected': {+ // A message the user queued mid-run was accepted into the running+ // turn. Place it under the work so far, then fork a continuation+ // assistant so later thinking/tools/answer render below it.+ const steerId = dataPayload?.steer_id as string | undefined+ log('[Agent] User message injected, steer_id:', steerId)+ let injectedUser: ChatMessage | undefined+ let alreadyInList = false+ if (steerId) {+ const injectedId = dataPayload?.user_message_id as string | undefined+ // Resuming a turn replays this event from the start of the log, by+ // which point history has already loaded the persisted row. Reuse+ // it — synthesizing here would show the same message twice.+ injectedUser = messagesList.find(+ (item) =>+ item.role === 'user' &&+ ((!!injectedId && item.id === injectedId) || item.steer_id === steerId),+ )+ alreadyInList = Boolean(injectedUser)+ if (!injectedUser) {+ // Queued messages live in the composer overlay, never as chat+ // rows, so the first delivery builds the bubble here.+ injectedUser = {+ id: injectedId || steerId,+ role: 'user',+ content: String(dataPayload?.content || ''),+ steer_id: steerId,+ channel: 'web',+ is_completed: true,+ }+ if (data.created_at) applyMessageCreatedAt(injectedUser, data.created_at)+ }+ }+ if (injectedUser) {+ if (dataId && !injectedUser.request_id) injectedUser.request_id = dataId+ const continuation = forkAfterInjectedUser(+ messagesList,+ message,+ injectedUser,+ steerId,+ )+ if (!alreadyInList) emitMessageCreated(injectedUser)+ if (continuation !== message) {+ emitMessageCreated(continuation)+ onAgentChunkBound?.(continuation, true)+ }+ if (steerId) onUserMessageInjected?.(steerId)+ }+ break+ }case 'complete': {log('[Agent] Complete event received')applyFinalArtifactContent(message, (dataPayload as any)?.final_content)@@ -978,7 +1056,9 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {})let existingMessage = findLastMessage(- (item) => item.id === data.id || item.request_id === data.id,+ (item) =>+ item.role === 'assistant' &&+ (item.id === data.id || item.request_id === data.id),)const created = !existingMessageif (!existingMessage) {@@ -1025,16 +1105,17 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {data.response_type === 'tool_result' ||data.response_type === 'reflection' ||data.response_type === 'artifacts_pending' ||- data.response_type === 'context_compacted'+ data.response_type === 'context_compacted' ||+ data.response_type === 'user_message_injected'- const lastMessage = messagesList[messagesList.length - 1]- const isCurrentlyAgentMode = lastMessage?.isAgentMode === true+ const activeAssistant = getTrailingIncompleteAssistant()+ const isCurrentlyAgentMode = activeAssistant?.isAgentMode === trueconst targetsActiveAgentRequest =isAgentStreamSession() &&!!data.id &&(data.id === currentAssistantMessageId.value ||- lastMessage?.request_id === data.id ||- lastMessage?.id === data.id)+ activeAssistant?.request_id === data.id ||+ activeAssistant?.id === data.id)const isAgentAnswerChunk =data.response_type === 'answer' && (isAgentStreamSession() || targetsActiveAgentRequest)const isAgentCompleteChunk =@@ -1066,6 +1147,7 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {loading.value = falseisReplying.value = falsecurrentAssistantMessageId.value = ''+ onGenerationStopped?.()}return}@@ -1073,6 +1155,7 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {if (data.response_type === 'stop') {log('[Stop Event] Non-agent generation stopped')const stoppedMessage = findLastMessage((item) => {+ if (item.role !== 'assistant') return falseif (item.request_id === data.id) return truereturn item.id === data.id})@@ -1081,10 +1164,12 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {isReplying.value = falsefullContent.value = ''currentAssistantMessageId.value = ''+ onGenerationStopped?.()return}const existingMessage = findLastMessage((item) => {+ if (item.role !== 'assistant') return falseif (item.request_id === data.id) return truereturn item.id === data.id})diff --git a/frontend/src/i18n/locales/en-US.ts b/frontend/src/i18n/locales/en-US.tsindex bb19814f0..388617cef 100755--- a/frontend/src/i18n/locales/en-US.ts+++ b/frontend/src/i18n/locales/en-US.ts@@ -2445,9 +2445,20 @@ export default {noModel: 'No available models',stopGeneration: 'Stop Generation',send: 'Send',+ steerQueueSendNow: 'Send now',+ steerQueueWaiting: 'Will send after the current answer finishes',+ steerQueueInjecting: 'Waiting for the next thinking round',messages: {enterContent: 'Please enter content first!',replying: 'Currently replying, please try again later!',+ steerAttachmentPending: 'Attachment is still uploading. Please try again shortly.',+ steerHasAttachments: 'Attachments cannot be added to a running answer. Remove them first, or send after it finishes.',+ steerFailed: 'Failed to append the message. Please try again.',+ steerPromoteFailed: 'Failed to send now. Please try again.',+ steerRemoveFailed: 'Failed to remove the queued message. Please try again.',+ steerAlreadyInjected: 'This message has already been taken by the running answer.',+ steerFollowUpTimeout: 'The next answer did not start in time. Please send again.',+ steerNoActiveRun: 'No answer is currently running. Please send the message directly.',agentSwitchedOn: 'Switched to Intelligent Reasoning',agentSwitchedOff: 'Switched to Quick Q&A',agentSelected: 'Selected agent "{name}"',diff --git a/frontend/src/i18n/locales/ja-JP.ts b/frontend/src/i18n/locales/ja-JP.tsindex 084a7293d..e47443596 100644--- a/frontend/src/i18n/locales/ja-JP.ts+++ b/frontend/src/i18n/locales/ja-JP.ts@@ -2445,9 +2445,20 @@ export default {noModel: '利用可能なモデルがありません',stopGeneration: '生成を停止',send: '送信',+ steerQueueSendNow: '今すぐ送信',+ steerQueueWaiting: '現在の回答が終わってから送信されます',+ steerQueueInjecting: '次の思考ラウンドを待っています',messages: {enterContent: '先に内容を入力してください。',replying: '回答中です。しばらくしてから再試行してください。',+ steerAttachmentPending: '添付ファイルのアップロードが完了していません。しばらくしてから追加してください。',+ steerHasAttachments: '実行中の回答には添付ファイルを追加できません。先に削除するか、終了後に送信してください。',+ steerFailed: 'メッセージの追加に失敗しました。再試行してください。',+ steerPromoteFailed: '今すぐ送信に失敗しました。再試行してください。',+ steerRemoveFailed: '待機中のメッセージを削除できませんでした。再試行してください。',+ steerAlreadyInjected: 'このメッセージは既に現在の回答に取り込まれています。',+ steerFollowUpTimeout: '次の回答が時間内に始まりませんでした。もう一度送信してください。',+ steerNoActiveRun: '現在実行中の回答はありません。メッセージを直接送信してください。',agentSwitchedOn: 'スマート推論に切り替えました',agentSwitchedOff: 'クイック回答に切り替えました',agentSelected: 'エージェント「{name}」を選択しました',diff --git a/frontend/src/i18n/locales/ko-KR.ts b/frontend/src/i18n/locales/ko-KR.tsindex 9036e4203..103eac378 100755--- a/frontend/src/i18n/locales/ko-KR.ts+++ b/frontend/src/i18n/locales/ko-KR.ts@@ -4510,6 +4510,9 @@ export default {noModel: '사용 가능한 모델 없음',stopGeneration: '생성 중지',send: '전송',+ steerQueueSendNow: '지금 보내기',+ steerQueueWaiting: '현재 답변이 끝난 뒤에 전송됩니다',+ steerQueueInjecting: '다음 사고 라운드를 기다리는 중',webSearchDisabledByAgent: '현재 에이전트에 대해서는 네트워크 검색이 비활성화되어 있습니다.',kbLockedByAgent: '현재 에이전트가 지식베이스 구성을 잠갔습니다.',kbDisabledByAgent: '현재 에이전트가 지식베이스 기능을 비활성화했습니다.',@@ -4519,6 +4522,14 @@ export default {messages: {enterContent: '먼저 내용을 입력해주세요!',replying: '응답 중입니다. 잠시 후 다시 시도해주세요!',+ steerAttachmentPending: '첨부 파일 업로드가 완료되지 않았습니다. 잠시 후 다시 시도해주세요.',+ steerHasAttachments: '진행 중인 응답에는 첨부 파일을 추가할 수 없습니다. 먼저 제거하거나 응답이 끝난 뒤 보내주세요.',+ steerFailed: '메시지 추가에 실패했습니다. 다시 시도해주세요.',+ steerPromoteFailed: '지금 보내기에 실패했습니다. 다시 시도해주세요.',+ steerRemoveFailed: '대기 중인 메시지를 삭제하지 못했습니다. 다시 시도해주세요.',+ steerAlreadyInjected: '이 메시지는 이미 현재 응답에 반영되었습니다.',+ steerFollowUpTimeout: '다음 응답이 제때 시작되지 않았습니다. 다시 보내주세요.',+ steerNoActiveRun: '현재 진행 중인 응답이 없습니다. 메시지를 직접 보내주세요.',agentSwitchedOn: 'Agent 모드로 전환되었습니다',agentSwitchedOff: '일반 모드로 전환되었습니다',agentSelected: '"{name}" 에이전트가 선택되었습니다.',diff --git a/frontend/src/i18n/locales/ru-RU.ts b/frontend/src/i18n/locales/ru-RU.tsindex 5d6124ff9..1a9b1ee95 100755--- a/frontend/src/i18n/locales/ru-RU.ts+++ b/frontend/src/i18n/locales/ru-RU.ts@@ -4510,6 +4510,9 @@ export default {noModel: 'Нет доступных моделей',stopGeneration: 'Остановить генерацию',send: 'Отправить',+ steerQueueSendNow: 'Отправить сейчас',+ steerQueueWaiting: 'Отправится после завершения текущего ответа',+ steerQueueInjecting: 'Ожидание следующего раунда рассуждения',webSearchDisabledByAgent: 'Web search is disabled by the current agent',kbLockedByAgent: 'Knowledge base configuration is locked by the current agent',kbDisabledByAgent: 'Knowledge base is disabled by the current agent',@@ -4519,6 +4522,14 @@ export default {messages: {enterContent: 'Сначала введите содержимое!',replying: 'Ответ формируется, попробуйте позже!',+ steerAttachmentPending: 'Вложение ещё загружается. Повторите попытку чуть позже.',+ steerHasAttachments: 'К текущему ответу нельзя добавить вложения. Удалите их или отправьте после завершения.',+ steerFailed: 'Не удалось добавить сообщение. Попробуйте ещё раз.',+ steerPromoteFailed: 'Не удалось отправить сейчас. Попробуйте ещё раз.',+ steerRemoveFailed: 'Не удалось удалить сообщение из очереди. Попробуйте ещё раз.',+ steerAlreadyInjected: 'Это сообщение уже принято текущим ответом.',+ steerFollowUpTimeout: 'Следующий ответ не начался вовремя. Отправьте сообщение ещё раз.',+ steerNoActiveRun: 'Сейчас нет активного ответа. Отправьте сообщение напрямую.',agentSwitchedOn: 'Переключено в Agent режим',agentSwitchedOff: 'Переключено в обычный режим',agentSelected: 'Selected agent "{name}"',diff --git a/frontend/src/i18n/locales/zh-CN.ts b/frontend/src/i18n/locales/zh-CN.tsindex 532eb23a4..12207a098 100755--- a/frontend/src/i18n/locales/zh-CN.ts+++ b/frontend/src/i18n/locales/zh-CN.ts@@ -4512,6 +4512,9 @@ export default {noModel: '暂无可用模型',stopGeneration: '停止生成',send: '发送',+ steerQueueSendNow: '立即发送',+ steerQueueWaiting: '当前回答结束后发送',+ steerQueueInjecting: '等待下一轮思考',webSearchDisabledByAgent: '当前智能体已禁用网络搜索',kbLockedByAgent: '当前智能体已锁定知识库配置',kbDisabledByAgent: '当前智能体已禁用知识库功能',@@ -4521,6 +4524,14 @@ export default {messages: {enterContent: '请先输入内容!',replying: '正在回复中,请稍后再试!',+ steerAttachmentPending: '附件尚未上传完成,请稍后再追加',+ steerHasAttachments: '进行中的回答无法附带附件,请先移除附件或等当前回答结束后再发送',+ steerFailed: '追加失败,请重试',+ steerPromoteFailed: '立即发送失败,请重试',+ steerRemoveFailed: '删除排队消息失败,请重试',+ steerAlreadyInjected: '该消息已被当前回答接收',+ steerFollowUpTimeout: '下一轮回答未能及时开始,请重新发送',+ steerNoActiveRun: '当前没有正在进行的回答,请直接发送消息',agentSwitchedOn: '已切换到智能推理',agentSwitchedOff: '已切换到快速问答',agentSelected: '已选择智能体「{name}」',diff --git a/frontend/src/utils/steerStreamFork.test.mjs b/frontend/src/utils/steerStreamFork.test.mjsnew file mode 100644index 000000000..a0b7dae7f--- /dev/null+++ b/frontend/src/utils/steerStreamFork.test.mjs@@ -0,0 +1,221 @@+import assert from 'node:assert/strict'+import test from 'node:test'+import { expandSteerForksInHistory, forkAfterInjectedUser } from './steerStreamFork.ts'++test('inject forks later events onto a new assistant below the user bubble', () => {+ const assistant = {+ id: 'assist-1',+ request_id: 'req-1',+ role: 'assistant',+ is_completed: false,+ isAgentMode: true,+ agentEventStream: [{ type: 'thinking', event_id: 't1', thinking: true, done: false }],+ }+ const queued = {+ id: 'user-2',+ role: 'user',+ content: 'wait, search the other doc',+ request_id: 'req-1',+ steer_id: 'steer-1',+ }+ const list = [+ { id: 'user-1', role: 'user', content: 'original', request_id: 'req-1' },+ assistant,+ queued,+ ]++ const continuation = forkAfterInjectedUser(list, assistant, queued, 'steer-1')++ assert.equal(list.length, 4)+ assert.equal(list[1], assistant)+ assert.equal(list[2], queued)+ assert.equal(list[3], continuation)+ assert.equal(assistant.is_completed, true)+ assert.equal(assistant.steerForked, true)+ assert.equal(assistant.agentEventStream[0].thinking, false)+ assert.equal(continuation.role, 'assistant')+ assert.equal(continuation.is_completed, false)+ assert.equal(continuation.request_id, 'req-1')+ assert.equal(continuation.assistant_message_id, 'assist-1')+ assert.notEqual(continuation.id, assistant.id)+})++test('inject moves a queued user that is not already under the source assistant', () => {+ const assistant = {+ id: 'assist-1',+ request_id: 'req-1',+ role: 'assistant',+ is_completed: false,+ agentEventStream: [],+ }+ const queued = { id: 'user-2', role: 'user', content: 'nudge', steer_id: 's2' }+ const list = [queued, assistant]++ forkAfterInjectedUser(list, assistant, queued, 's2')++ assert.equal(list[0], assistant)+ assert.equal(list[1], queued)+ assert.equal(list[2].role, 'assistant')+})++// continue-stream replays the whole event log, so after a refresh the+// injection arrives again for a transcript history has already split. Redoing+// the fork would duplicate the user bubble and seal the segment that is still+// streaming.+test('replaying an injection onto an already split turn is a no-op', () => {+ const sealed = {+ id: 'a0',+ role: 'assistant',+ request_id: 'req-1',+ is_completed: true,+ steerForked: true,+ agentEventStream: [{ type: 'thinking', content: 'before' }],+ }+ const injected = { id: 'u1', role: 'user', request_id: 'req-1', content: 'also check B' }+ const live = {+ id: 'a0:steer:1',+ assistant_message_id: 'a0',+ role: 'assistant',+ request_id: 'req-1',+ is_completed: false,+ agentEventStream: [],+ }+ const list = [{ id: 'u0', role: 'user', content: 'start' }, sealed, injected, live]++ const continuation = forkAfterInjectedUser(list, live, injected, 'steer-1')++ assert.equal(continuation, live, 'must reuse the live segment as the continuation')+ assert.equal(list.length, 4, 'no extra bubble or segment may be inserted')+ assert.equal(list.indexOf(injected), 2, 'the user bubble must not be moved')+ assert.equal(live.is_completed, false, 'the live segment must not be sealed by a replay')+})++// Refreshing while the agent is still working is the case that matters most:+// the turn absorbed an injected message, so it gets split, but the trailing+// segment is still the live one. Marking it completed makes the chat view skip+// continue-stream, and the running agent's output never comes back.+test('an in-flight turn stays in-flight after being split', () => {+ const messages = [+ { id: 'u0', role: 'user', request_id: 'req-1', content: 'start' },+ {+ id: 'a0',+ role: 'assistant',+ request_id: 'req-1',+ content: '',+ is_completed: false,+ isAgentMode: true,+ agentEventStream: [{ type: 'thinking', timestamp: 1000, content: 'before' }],+ },+ {+ id: 'u1',+ role: 'user',+ request_id: 'req-1',+ content: 'also check B',+ created_at: '1970-01-01T00:00:02.000Z',+ },+ ]++ const expanded = expandSteerForksInHistory(messages)+ const tail = expanded[expanded.length - 1]++ assert.equal(tail.role, 'assistant')+ assert.equal(tail.is_completed, false, 'the live segment must not be marked completed')+ assert.ok(!tail.steerForked, 'the live segment is not a sealed fork prefix')+ assert.equal(tail.assistant_message_id, 'a0', 'must still address the persisted row')++ // The sealed prefix keeps its own flags.+ assert.equal(expanded[1].is_completed, true)+ assert.equal(expanded[1].steerForked, true)+})++// The completed turn's trailing segment carries the answer, so it must not+// inherit the sealed-prefix flags either — steerForked there suppresses the+// answer toolbar and follow-up suggestions.+test('the trailing segment does not inherit sealed-prefix flags', () => {+ const messages = [+ { id: 'u0', role: 'user', request_id: 'req-1', content: 'start' },+ {+ id: 'a0',+ role: 'assistant',+ request_id: 'req-1',+ content: 'final',+ is_completed: true,+ agentEventStream: [+ { type: 'thinking', timestamp: 1000, content: 'before' },+ { type: 'answer', content: 'final', done: true },+ ],+ },+ { id: 'u1', role: 'user', request_id: 'req-1', content: 'more', created_at: '1970-01-01T00:00:02.000Z' },+ ]++ const tail = expandSteerForksInHistory(messages).at(-1)+ assert.equal(tail.content, 'final')+ assert.equal(tail.is_completed, true)+ assert.ok(!tail.steerForked)+})++test('history reload splits one assistant around later same-request user rows', () => {+ const messages = [+ { id: 'u0', role: 'user', request_id: 'req-1', content: 'start' },+ {+ id: 'a0',+ role: 'assistant',+ request_id: 'req-1',+ content: 'final',+ is_completed: true,+ agentEventStream: [+ { type: 'thinking', timestamp: 1000, content: 'before' },+ { type: 'tool_call', timestamp: 1100, tool_name: 'knowledge_search' },+ { type: 'thinking', timestamp: 3000, content: 'after inject' },+ { type: 'answer', content: 'final', done: true },+ ],+ },+ { id: 'u1', role: 'user', request_id: 'req-1', content: 'also check B', created_at: '1970-01-01T00:00:02.000Z' },+ ]++ const expanded = expandSteerForksInHistory(messages)+ assert.equal(expanded.length, 4)+ assert.equal(expanded[0].id, 'u0')+ assert.equal(expanded[1].id, 'a0')+ assert.equal(expanded[1].steerForked, true)+ assert.equal(expanded[1].content, '')+ assert.deepEqual(+ expanded[1].agentEventStream.map((e) => e.type),+ ['thinking', 'tool_call'],+ )+ assert.equal(expanded[2].id, 'u1')+ assert.equal(expanded[3].role, 'assistant')+ assert.equal(expanded[3].assistant_message_id, 'a0')+ assert.equal(expanded[3].is_completed, true)+ assert.equal(expanded[3].content, 'final')+ assert.deepEqual(+ expanded[3].agentEventStream.map((e) => e.type),+ ['thinking', 'answer'],+ )+})++test('expanding an already split transcript is a no-op', () => {+ const messages = [+ { id: 'u0', role: 'user', request_id: 'req-1', content: 'start' },+ {+ id: 'a0',+ role: 'assistant',+ request_id: 'req-1',+ content: 'final',+ is_completed: true,+ agentEventStream: [+ { type: 'thinking', timestamp: 1000, content: 'before' },+ { type: 'thinking', timestamp: 3000, content: 'after inject' },+ { type: 'answer', content: 'final', done: true },+ ],+ },+ { id: 'u1', role: 'user', request_id: 'req-1', content: 'also check B', created_at: '1970-01-01T00:00:02.000Z' },+ ]++ const once = expandSteerForksInHistory(messages)+ const twice = expandSteerForksInHistory(once)+ assert.equal(twice.length, once.length)+ assert.equal(twice[1].steerForked, true)+ assert.equal(twice[3].assistant_message_id, 'a0')+ assert.equal(twice[3].id, once[3].id)+})diff --git a/frontend/src/utils/steerStreamFork.ts b/frontend/src/utils/steerStreamFork.tsnew file mode 100644index 000000000..8592255d6--- /dev/null+++ b/frontend/src/utils/steerStreamFork.ts@@ -0,0 +1,221 @@+import { markRaw } from 'vue'++export type ChatMessage = Record<string, unknown>++/**+ * The row id the server knows this assistant message by.+ *+ * A turn that absorbed a mid-run message is shown as several assistant+ * segments, and every segment after the first carries a synthetic id so Vue+ * can key the list. Only the persisted id addresses a real message, so+ * anything that talks to the backend — continue-stream, stop, artifacts —+ * must resolve through here rather than reading `id` directly.+ */+export function persistedAssistantId(message: ChatMessage | undefined): string {+ if (!message) return ''+ if (typeof message.assistant_message_id === 'string' && message.assistant_message_id) {+ return message.assistant_message_id+ }+ return typeof message.id === 'string' ? message.id : ''+}++export function sealAssistantSegment(message: ChatMessage): void {+ message.thinking = false+ message.is_completed = true+ message.steerForked = true+ const stream = message.agentEventStream+ if (!Array.isArray(stream)) return+ for (const raw of stream) {+ if (!raw || typeof raw !== 'object') continue+ const event = raw as ChatMessage+ if (event.type === 'thinking') {+ event.done = true+ event.thinking = false+ }+ }+}++export function forkAfterInjectedUser(+ list: ChatMessage[],+ sourceAssistant: ChatMessage,+ userMessage: ChatMessage,+ steerId?: string,+): ChatMessage {+ // continue-stream replays the whole event log, so after a refresh this runs+ // again for a transcript history has already split. Redoing the fork would+ // duplicate the bubble and seal the segment that is still streaming.+ //+ // "Already split" means the bubble sits *between* two segments of this turn.+ // A bubble merely sitting above the live assistant is the opposite case —+ // it still has to be moved underneath it.+ const existingIdx = list.indexOf(userMessage)+ if (existingIdx > 0) {+ const before = list[existingIdx - 1]+ const after = list[existingIdx + 1]+ if (+ before?.role === 'assistant' &&+ before.request_id === sourceAssistant.request_id &&+ after?.role === 'assistant' &&+ !after.is_completed &&+ after.request_id === sourceAssistant.request_id+ ) {+ return after+ }+ }++ sealAssistantSegment(sourceAssistant)++ let userIdx = list.indexOf(userMessage)+ let sourceIdx = list.indexOf(sourceAssistant)+ if (userIdx < 0) {+ const insertAt = sourceIdx >= 0 ? sourceIdx + 1 : list.length+ list.splice(insertAt, 0, userMessage)+ userIdx = insertAt+ } else if (sourceIdx >= 0 && userIdx !== sourceIdx + 1) {+ list.splice(userIdx, 1)+ if (userIdx < sourceIdx) sourceIdx -= 1+ list.splice(sourceIdx + 1, 0, userMessage)+ userIdx = sourceIdx + 1+ }++ const afterUser = list[userIdx + 1]+ if (+ afterUser?.role === 'assistant' &&+ !afterUser.is_completed &&+ afterUser.request_id === sourceAssistant.request_id+ ) {+ return afterUser+ }++ const persistedId =+ (typeof sourceAssistant.assistant_message_id === 'string' && sourceAssistant.assistant_message_id) ||+ (typeof sourceAssistant.id === 'string' ? sourceAssistant.id : '')+ const continuation: ChatMessage = {+ id: `steer-cont-${steerId || String(Date.now())}`,+ assistant_message_id: persistedId,+ request_id: sourceAssistant.request_id,+ role: 'assistant',+ content: '',+ isAgentMode: true,+ isRagMode: sourceAssistant.isRagMode,+ is_completed: false,+ hideContent: true,+ agentEventStream: [],+ _eventMap: new Map(),+ _pendingToolCalls: new Map(),+ knowledge_references: [],+ }+ list.splice(userIdx + 1, 0, continuation)+ return continuation+}++function eventTime(event: ChatMessage): number {+ if (typeof event.timestamp === 'number' && Number.isFinite(event.timestamp)) {+ return event.timestamp+ }+ if (typeof event.timestamp === 'string') {+ const parsed = Date.parse(event.timestamp)+ return Number.isNaN(parsed) ? 0 : parsed+ }+ return 0+}++function isTrailingTurnEvent(event: ChatMessage): boolean {+ if (event.type === 'agent_complete' || event.type === 'stop') return true+ return event.type === 'answer' && event.done === true && !event.superseded+}++export function expandSteerForksInHistory(messages: ChatMessage[]): ChatMessage[] {+ const out: ChatMessage[] = []+ for (let i = 0; i < messages.length; i++) {+ const item = messages[i]+ if (item.role !== 'assistant' || typeof item.request_id !== 'string' || !item.request_id) {+ out.push(item)+ continue+ }+ if (item.steerForked) {+ out.push(item)+ continue+ }+ const persisted = persistedAssistantId(item)+ if (persisted && item.id !== persisted) {+ out.push(item)+ continue+ }++ const forks: ChatMessage[] = []+ let j = i + 1+ while (+ j < messages.length &&+ messages[j].role === 'user' &&+ messages[j].request_id === item.request_id+ ) {+ forks.push(messages[j])+ j+++ }+ if (!forks.length) {+ out.push(item)+ continue+ }++ const stream = Array.isArray(item.agentEventStream) ? (item.agentEventStream as ChatMessage[]) : []+ const cuts = forks.map((user) => {+ const parsed = Date.parse(String(user.created_at || ''))+ return Number.isNaN(parsed) ? 0 : parsed+ })+ const buckets: ChatMessage[][] = Array.from({ length: forks.length + 1 }, () => [])+ const trailing: ChatMessage[] = []+ for (const event of stream) {+ if (isTrailingTurnEvent(event)) {+ trailing.push(event)+ continue+ }+ const t = eventTime(event)+ let idx = 0+ while (idx < cuts.length && t >= cuts[idx]) idx += 1+ buckets[idx].push(event)+ }+ buckets[buckets.length - 1].push(...trailing)++ const persistedId =+ (typeof item.assistant_message_id === 'string' && item.assistant_message_id) ||+ (typeof item.id === 'string' ? item.id : '')+ // Segment 0 reuses the original object, and sealing it overwrites fields+ // the later segments still need. Snapshot first so every segment is built+ // from the message as it arrived — most importantly `is_completed`: a+ // trailing segment that inherits the prefix's sealed `true` tells the chat+ // view the turn is over, so a still-running agent is never resumed.+ const original: ChatMessage = { ...item }++ for (let s = 0; s < buckets.length; s++) {+ const isLast = s === buckets.length - 1+ const segment: ChatMessage = s === 0+ ? item+ : {+ ...original,+ id: `${persistedId}:steer:${s}`,+ assistant_message_id: persistedId,+ }+ segment.agentEventStream = markRaw(buckets[s])+ if (isLast) {+ segment.content = original.content+ segment.artifacts = original.artifacts+ segment.usage = original.usage+ segment.knowledge_references = original.knowledge_references+ segment.is_completed = original.is_completed+ segment.steerForked = original.steerForked+ } else {+ segment.steerForked = true+ segment.is_completed = true+ segment.content = ''+ segment.artifacts = undefined+ segment.usage = undefined+ segment.knowledge_references = []+ }+ out.push(segment)+ if (s < forks.length) out.push(forks[s])+ }+ i = j - 1+ }+ return out+}diff --git a/frontend/src/views/chat/components/AgentStreamDisplay.vue b/frontend/src/views/chat/components/AgentStreamDisplay.vueindex fb52e8c63..cebe24a5b 100644--- a/frontend/src/views/chat/components/AgentStreamDisplay.vue+++ b/frontend/src/views/chat/components/AgentStreamDisplay.vue@@ -1549,6 +1549,7 @@ watch(eventStream, (stream) => {// Check if conversation is done (based on answer event with done=true or stop event)const isConversationDone = computed(() => {+ if (props.session?.steerForked) return trueconst stream = eventStream.value;if (!stream || stream.length === 0) {console.log('[Collapse] No stream or empty stream');@@ -1653,7 +1654,10 @@ watch(activeAnswerMarkdown, () => {// yet. Hydrating too early would find nothing and leave a permanent placeholder// (until a manual reload). Waiting for full reveal guarantees the image exists.const answerFullyRendered = computed(- () => isConversationDone.value && typedAnswer.value.length >= activeAnswerMarkdown.value.length,+ () =>+ !props.session?.steerForked &&+ isConversationDone.value &&+ typedAnswer.value.length >= activeAnswerMarkdown.value.length,);watch(answerFullyRendered, (ready) => {emit('render-complete-change', ready);@@ -2055,6 +2059,10 @@ const intermediateEvents = computed(() => {const hidden = hiddenThinkingEventIds.value;return result.filter((e: any) => {if (e.type === 'answer' || e.type === 'agent_complete') return false;+ // Mid-run injected user messages render as normal user bubbles in the+ // message list, not inside the steps tree — the tree template has no+ // branch for this type and would otherwise emit an empty node.+ if (e.type === 'user_message_injected') return false;if (e.type === 'thinking' && e.event_id && hidden.has(e.event_id)) return false;return true;});@@ -2072,7 +2080,12 @@ const displayEvents = computed(() => {return [];}- const result = buildFullEventList(stream);+ const result = buildFullEventList(stream).filter(+ // Injected user messages render as normal user bubbles in the message+ // list — never inside the agent timeline (the template has no branch for+ // the type and would render an empty card).+ (e: any) => e.type !== 'user_message_injected',+ );// Quick-answer RAG: pipeline steps (including attachment prep) live in// RagPipelineProgress; this component only renders the answer stream.diff --git a/frontend/src/views/chat/components/answerToolbarCompletion.test.mjs b/frontend/src/views/chat/components/answerToolbarCompletion.test.mjsindex 5d8f5ec98..fc101ca2e 100644--- a/frontend/src/views/chat/components/answerToolbarCompletion.test.mjs+++ b/frontend/src/views/chat/components/answerToolbarCompletion.test.mjs@@ -87,7 +87,7 @@ test('follow-up suggestions wait until the answer is fully rendered', () => {)assert.match(chatView,- /<FollowUpSuggestions v-if="session\.answerFullyRendered && !session\.suggestionsDismissed"/,+ /<FollowUpSuggestions v-if="session\.answerFullyRendered && !session\.steerForked && !session\.suggestionsDismissed"/,)assert.match(botMessage, /emit\('render-complete-change', ready\)/)assert.match(agentStream, /emit\('render-complete-change', ready\)/)diff --git a/frontend/src/views/chat/index.vue b/frontend/src/views/chat/index.vueindex a428e325a..19ae3bb5f 100644--- a/frontend/src/views/chat/index.vue+++ b/frontend/src/views/chat/index.vue@@ -118,8 +118,9 @@:follow-up-loading="Boolean(session.suggestionLoading && !session.suggestionSet?.questions?.length)"@render-complete-change="(ready) => handleAnswerRenderComplete(session, ready)"></botmsg>- <FollowUpSuggestions v-if="session.answerFullyRendered && !session.suggestionsDismissed"- :suggestion-set="session.suggestionSet" :loading="session.suggestionLoading"+ <FollowUpSuggestions v-if="session.answerFullyRendered && !session.steerForked && !session.suggestionsDismissed"+ :suggestion-set="session.suggestionSet"+ :loading="session.suggestionLoading":allow-regenerate="session.suggestionSet?.allow_regenerate"@select="(item) => handleFollowUpSelect(session, item)"@regenerate="loadFollowUpSuggestions(session, true, true)"@@ -144,8 +145,14 @@<div class="input-container" :class="{ 'is-embedded': embeddedMode }"><InputField ref="inputFieldRef"@send-msg="(query, modelId, mentionedItems, imageFiles, attachmentFiles) => sendMsg(query, modelId, mentionedItems, imageFiles, attachmentFiles)"- @stop-generation="handleStopGeneration" :isReplying="isReplying" :sessionId="session_id"- :assistantMessageId="currentAssistantMessageId" :embeddedMode="embeddedMode"></InputField>+ @steer-msg="(query, mentionedItems, delivery) => handleSteerMsg(query, mentionedItems, delivery)"+ @promote-steer="handlePromoteSteer"+ @remove-steer="handleRemoveSteer"+ @stop-generation="handleStopGeneration"+ @stop-confirmed="handleStopConfirmed"+ @stop-failed="handleStopFailed" :isReplying="isReplying" :sessionId="session_id"+ :assistantMessageId="currentAssistantMessageId" :embeddedMode="embeddedMode"+ :queuedSteers="steerQueue" :canSteer="isAgentStreamSession()"></InputField></div></div><KnowledgeBaseEditorModal :visible="uiStore.showKBEditorModal" :mode="uiStore.kbEditorMode"@@ -170,6 +177,8 @@ import { getMessageList, getSession } from "@/api/chat/index";import { getSuggestedQuestions } from "@/api/agent/index";import { deleteTemporaryAttachment, uploadTemporaryAttachment } from '@/api/chat/temporary-attachments';import { useStream } from '../../api/chat/streame'+import { listSteerSession, promoteSteerSession, removeSteerSession, steerSession } from '@/api/chat/steer';+import { persistedAssistantId } from '@/utils/steerStreamFork';import { useMenuStore } from '@/stores/menu';import { useSettingsStore } from '@/stores/settings';import { MessagePlugin } from 'tdesign-vue-next';@@ -289,6 +298,7 @@ const sessionArtifacts = computed(() => collectSessionArtifacts(messagesList));const sessionArtifactsCollecting = computed(() =>messagesList.some((message) => isCollectingSkillArtifacts(message)),);+const steerQueue = ref([]);const isReplying = ref(false);const currentAssistantMessageId = ref(''); // 当前正在生成的 assistant message ID// True only while attaching to an in-flight *IM-originated* reply via continue-stream.@@ -525,6 +535,7 @@ watch([() => route.params], async (newvalue) => {scrollLock.value = false;}messagesList.splice(0);+ steerQueue.value = [];session_id.value = newvalue[0].chatid;currentSession.value = null;clearCitationChunkCache();@@ -613,6 +624,27 @@ const handleScroll = () => {const fetchMessageList = (data) => getMessageList(data);+// The server is the source of truth for what is still queued. `onlyWhenLive`+// guards the hand-off window: a follow-up run publishes itself a moment before+// its carried-over queue is readable, and treating that gap as "queue is+// empty" would wipe messages the user can still see.+const hydrateSteerQueue = async ({ onlyWhenLive = false } = {}) => {+ if (!session_id.value) return;+ try {+ const res = await listSteerSession(session_id.value);+ if (onlyWhenLive && !res?.assistant_message_id) return;+ const items = Array.isArray(res?.items) ? res.items : [];+ steerQueue.value = items.map((item) => ({+ steer_id: item.steer_id,+ content: item.content || '',+ delivery: item.delivery === 'inject' ? 'inject' : 'after',+ mentioned_items: item.mentioned_items || [],+ }));+ } catch (e) {+ console.warn('[Steer] Failed to restore queue:', e);+ }+};+const {findLastMessage,shouldRenderAssistantMessage,@@ -641,20 +673,33 @@ const {void loadFollowUpSuggestions(message, false);}}- const lastMessage = messagesList[messagesList.length - 1];+ if (!steerQueue.value.length) {+ await hydrateSteerQueue();+ }+ // Resume the trailing *assistant*, not simply the last row: a turn+ // that absorbed a mid-run message ends with the injected user bubble+ // in some orderings, and keying off that row would skip the resume+ // entirely, leaving a running agent with no visible output.+ const lastMessage = findLastMessage(+ (message) => message.role === 'assistant' && !message.is_completed+ );const locallyRunning = isReplying.value || isStreaming.value || isImRecovering.value;// History reload can finish after sendMsg already marked this session// running. Do not clear that marker just because the snapshot's last- // message still looks completed.- if (!props.embeddedMode && !locallyRunning && (!lastMessage || lastMessage.is_completed)) {+ // message still looks completed. A scanned incomplete assistant counts: a+ // turn that absorbed a mid-run message leaves such a row in history even+ // when the tail row is a user bubble.+ if (!props.embeddedMode && !locallyRunning && !lastMessage) {sessionActivity.update(activitySessionId.value, false);}- if (lastMessage && !lastMessage.is_completed) {+ if (lastMessage) {isReplying.value = true;- if (lastMessage.role === 'assistant') {- currentAssistantMessageId.value = lastMessage.id;- console.log('[Continue Stream] Set assistant message ID:', lastMessage.id);- }+ // Such a turn renders as several assistant segments; only the+ // persisted id addresses the row continue-stream and stop+ // actually operate on.+ const resumeId = persistedAssistantId(lastMessage);+ currentAssistantMessageId.value = resumeId;+ console.log('[Continue Stream] Set assistant message ID:', resumeId);// Only IM-originated replies (channel === 'im') get the quiet poll-to-recover// path: their answer is generated on the IM side and never streams through// this server, so continue-stream always 404s even though the reply *is*@@ -663,7 +708,7 @@ const {isAttachingImStream.value = lastMessage.channel === 'im';await startStream({session_id: session_id.value,- query: lastMessage.id,+ query: resumeId,method: 'GET',url: '/api/v1/sessions/continue-stream',});@@ -689,8 +734,15 @@ const {attachStreamDebugToMessage(message);pendingStreamDebug.value = null;},+ onUserMessageInjected: (steerId) => {+ dropSteerQueueItem(steerId);+ },+ onGenerationStopped: () => {+ steerQueue.value = [];+ },onTurnComplete: (message) => {void loadFollowUpSuggestions(message, true);+ void flushSteerAfterTurn(persistedAssistantId(message));},});@@ -747,9 +799,252 @@ const handleStopGeneration = () => {isReplying.value = false;if (recoverPollTimer) { clearTimeout(recoverPollTimer); recoverPollTimer = null; }isImRecovering.value = false;- // 标记当前 assistant 为已结束,避免下一条 query 复用该消息行markInFlightAssistantStopped(currentAssistantMessageId.value);- // 保留 currentAssistantMessageId,Input-field 仍需用它调用 stop API+};++const handleStopConfirmed = () => {+ steerQueue.value = [];+};++const handleStopFailed = () => {+ isReplying.value = true;+ loading.value = true;+};++const dropSteerQueueItem = (steerId) => {+ if (!steerId) return;+ const idx = steerQueue.value.findIndex((item) => item.steer_id === steerId);+ if (idx >= 0) steerQueue.value.splice(idx, 1);+};++const findSteerQueueItem = (steerId) =>+ steerQueue.value.find((item) => item.steer_id === steerId);++const makeSteerClientId = () =>+ `steer-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;++// 追加消息到正在运行的 agent turn。默认 delivery=after,排队显示在输入框上方;+// 点「立即发送」再 promote 为 inject。注入后的时间线分叉复用 forkAfterInjectedUser。+const handleSteerMsg = async (value, mentionedItems = [], delivery = 'after') => {+ if (!session_id.value || !value?.trim()) return;+ if (!isReplying.value) {+ // 空闲时没有运行中的 turn 可排队:直接走正常发送,而不是把+ // steering(服务端为 handleSteer/指定事务)当隐形 sendMsg 用。+ await sendMsg(value, '', mentionedItems);+ return;+ }+ const clientId = makeSteerClientId();+ steerQueue.value.push({+ steer_id: clientId,+ client_id: clientId,+ content: value,+ delivery,+ mentioned_items: mentionedItems,+ pending: true,+ });+ try {+ const res = await steerSession(session_id.value, value, mentionedItems, delivery);+ if (res?.status === 'new_run') {+ const item = findSteerQueueItem(clientId);+ // Still attached to a stream: aborting it to POST AgentQA races the+ // finishing turn and can start a second engine. Keep the chip and+ // send once the current SSE completes.+ if (isReplying.value || isStreaming.value) {+ if (item) {+ item.pending = false;+ item.awaitingIdleSend = true;+ item.delivery = 'after';+ }+ return;+ }+ dropSteerQueueItem(clientId);+ await sendMsg(value, '', mentionedItems);+ return;+ }+ const item = findSteerQueueItem(clientId);+ if (item) {+ // The server id is the durable one — promote/remove and the+ // injected-event correlation all go through it. client_id stays+ // so handlePromoteSteer can still find the row while the swap+ // is rendering.+ if (res?.steer_id) item.steer_id = res.steer_id;+ item.pending = false;+ }+ } catch (e) {+ console.error('[Steer] Failed to queue message:', e);+ dropSteerQueueItem(clientId);+ MessagePlugin.error(e?.message || t('input.messages.steerFailed'));+ }+};++const handlePromoteSteer = async (steerId) => {+ if (!session_id.value || !steerId) return;+ const item = findSteerQueueItem(steerId) || steerQueue.value.find((entry) => entry.client_id === steerId);+ if (!item || item.delivery === 'inject') return;+ item.promoting = true;+ try {+ // Promote needs the durable server id; a pending item only has the+ // client-side one. isPending doesn't disable the button yet, so guard+ // here to keep the queue handlers total.+ if (item.pending) {+ MessagePlugin.info(t('input.messages.steerPromoteFailed'));+ return;+ }+ const res = await promoteSteerSession(session_id.value, item.steer_id);+ if (res?.status === 'already_injected') {+ dropSteerQueueItem(item.steer_id);+ MessagePlugin.info(t('input.messages.steerAlreadyInjected'));+ return;+ }+ if (res?.status === 'new_run') {+ if (isReplying.value || isStreaming.value) {+ item.awaitingIdleSend = true;+ item.delivery = 'after';+ return;+ }+ const content = item.content;+ const mentions = item.mentioned_items || [];+ dropSteerQueueItem(steerId);+ await sendMsg(content, '', mentions);+ return;+ }+ item.delivery = 'inject';+ } catch (e) {+ console.error('[Steer] Failed to promote queued message:', e);+ MessagePlugin.error(e?.message || t('input.messages.steerPromoteFailed'));+ } finally {+ item.promoting = false;+ }+};++const handleRemoveSteer = async (steerId) => {+ if (!steerId) return;+ const item = findSteerQueueItem(steerId);+ if (!item) return;+ if (item.pending) return;+ item.promoting = true;+ try {+ if (session_id.value) {+ const res = await removeSteerSession(session_id.value, item.steer_id);+ if (res?.status === 'already_injected') {+ MessagePlugin.info(t('input.messages.steerAlreadyInjected'));+ dropSteerQueueItem(steerId);+ return;+ }+ if (res?.status === 'gone') {+ dropSteerQueueItem(steerId);+ return;+ }+ if (res && res.removed === false) {+ MessagePlugin.error(t('input.messages.steerRemoveFailed'));+ return;+ }+ }+ dropSteerQueueItem(steerId);+ } catch (e) {+ console.error('[Steer] Failed to remove queued message:', e);+ MessagePlugin.error(e?.message || t('input.messages.steerRemoveFailed'));+ } finally {+ if (findSteerQueueItem(steerId)) item.promoting = false;+ }+};++let attachingSteerFollowUp = false;++const flushSteerAfterTurn = async (completedAssistantId) => {+ const awaiting = steerQueue.value.filter((item) => item.awaitingIdleSend);+ if (awaiting.length) {+ const batch = awaiting.slice();+ steerQueue.value = steerQueue.value.filter((item) => !item.awaitingIdleSend);+ const first = batch[0];+ await sendMsg(first.content, '', first.mentioned_items || []);+ for (const rest of batch.slice(1)) {+ await handleSteerMsg(rest.content, rest.mentioned_items || [], rest.delivery || 'after');+ }+ return;+ }+ void attachSteerFollowUp(completedAssistantId);+};++const attachSteerFollowUp = async (completedAssistantId) => {+ const queued = steerQueue.value.slice();+ if (!queued.length || attachingSteerFollowUp || !session_id.value) return;+ const sessionId = session_id.value;+ attachingSteerFollowUp = true;+ isReplying.value = true;+ loading.value = true;+ let attached = false;+ let attachedAssistantId = '';+ const sessionChanged = () => session_id.value !== sessionId;+ try {+ for (let attempt = 0; attempt < 40; attempt++) {+ if (sessionChanged()) return;+ const res = await getMessageList({ session_id: sessionId, limit: 30, created_at: '' });+ if (sessionChanged()) return;+ const batch = res?.data || [];+ const newAssistant = [...batch].reverse().find((m) =>+ m.role === 'assistant' && !m.is_completed && m.id && m.id !== completedAssistantId+ );+ if (newAssistant) {+ // The follow-up run persists its query under its own+ // request_id, so the new user rows are identified exactly.+ // Matching on message text instead would attach the wrong+ // bubble whenever the user sends the same thing twice.+ const claimed = new Set();+ for (const persisted of batch) {+ if (persisted.role !== 'user' || !persisted.id) continue;+ if (persisted.request_id !== newAssistant.request_id) continue;+ if (messagesList.some((existing) => existing.id === persisted.id)) continue;+ const queuedMatch = queued.find(+ (q) => q.content === persisted.content && !claimed.has(q.steer_id)+ );+ if (queuedMatch) claimed.add(queuedMatch.steer_id);+ messagesList.push({+ ...persisted,+ mentioned_items: queuedMatch?.mentioned_items?.length+ ? queuedMatch.mentioned_items+ : persisted.mentioned_items,+ });+ }+ // Rows that made it into the transcript are no longer queued.+ for (const steerId of claimed) dropSteerQueueItem(steerId);+ if (sessionChanged()) return;+ // Then reconcile with the server, which owns the backlog that+ // moved to the new run — but only once that run is visible.+ await hydrateSteerQueue({ onlyWhenLive: true });+ if (sessionChanged()) return;++ currentAssistantMessageId.value = newAssistant.id;+ attachedAssistantId = newAssistant.id;+ await startStream({+ session_id: sessionId,+ query: newAssistant.id,+ method: 'GET',+ url: '/api/v1/sessions/continue-stream',+ });+ attached = true;+ return;+ }+ await new Promise((r) => setTimeout(r, 200));+ }+ } catch (e) {+ console.error('[Steer] Failed to attach follow-up run:', e);+ } finally {+ attachingSteerFollowUp = false;+ if (sessionChanged()) {+ // The session we started on is gone; do not touch the new chat's+ // loading / isReplying, and do not chain another attach there.+ } else if (!attached) {+ loading.value = false;+ isReplying.value = false;+ MessagePlugin.error(t('input.messages.steerFollowUpTimeout'));+ } else if (steerQueue.value.length) {+ // startStream awaits the whole SSE. The follow-up's onTurnComplete+ // therefore runs while attachingSteerFollowUp is still true and+ // no-ops. Chain remaining after-items once that guard drops.+ void attachSteerFollowUp(attachedAssistantId);+ }+ }};const sendMsg = async (value, modelId = '', mentionedItems = [], imageFiles = [], attachmentFiles = []) => {@@ -1033,6 +1328,7 @@ const handleSessionMutation = (event) => {}if (detail.messagesCleared) {messagesList.splice(0);+ steerQueue.value = [];created_at.value = '';hasMoreHistory.value = true;historyLoadingMore.value = false;@@ -1061,6 +1357,7 @@ onBeforeMount(async () => {onMounted(async () => {window.addEventListener(SESSION_MUTATION_EVENT, handleSessionMutation);messagesList.splice(0);+ steerQueue.value = [];// 初始化状态:加载历史消息时不应显示loadingloading.value = false;diff --git a/frontend/src/views/chat/steerFollowUp.test.mjs b/frontend/src/views/chat/steerFollowUp.test.mjsnew file mode 100644index 000000000..30598db75--- /dev/null+++ b/frontend/src/views/chat/steerFollowUp.test.mjs@@ -0,0 +1,182 @@+import assert from 'node:assert/strict'+import { readFileSync } from 'node:fs'+import test from 'node:test'++const source = readFileSync(new URL('./index.vue', import.meta.url), 'utf8')+const steerApi = readFileSync(new URL('../../api/chat/steer.ts', import.meta.url), 'utf8')++function attachSteerFollowUpSource() {+ const start = source.indexOf('const attachSteerFollowUp = async')+ const end = source.indexOf('const sendMsg = async', start)+ assert.notEqual(start, -1)+ assert.notEqual(end, -1)+ return source.slice(start, end)+}++test('refresh restores the overlay queue from the live run', () => {+ assert.match(steerApi, /export async function listSteerSession/)+ assert.match(source, /listSteerSession/)+ assert.match(source, /hydrateSteerQueue/)+ assert.match(source, /if \(!steerQueue\.value\.length\)/)+})++// A turn that absorbed a mid-run message is split into several assistant+// segments, and every segment after the first gets a synthetic id. Resuming+// or stopping with that id hits a row the server has never heard of: the+// stream 404s and the UI looks like the agent died on refresh.+test('resume and stop address the persisted assistant id, not a fork id', () => {+ const fork = readFileSync(new URL('../../utils/steerStreamFork.ts', import.meta.url), 'utf8')+ assert.match(fork, /export function persistedAssistantId/)++ const start = source.indexOf('onAfterMsgList: async ()')+ const end = source.indexOf('onAgentQuery:', start)+ assert.notEqual(start, -1)+ assert.notEqual(end, -1)+ const hook = source.slice(start, end)++ assert.match(hook, /persistedAssistantId\(lastMessage\)/)+ assert.match(hook, /currentAssistantMessageId\.value = resumeId/)+ assert.match(hook, /query: resumeId/)+ assert.doesNotMatch(hook, /query: lastMessage\.id/)++ // An injected user row can be the last entry in the list. Keying the resume+ // off the tail row would then skip continue-stream and the still-running+ // agent would produce nothing visible.+ assert.match(hook, /findLastMessage\(\s*\(message\) => message\.role === 'assistant' && !message\.is_completed\s*\)/)+ assert.doesNotMatch(hook, /messagesList\[messagesList\.length - 1\]/)+})++// Stopping means stopping. Firing off the queued messages as a fresh run is+// the opposite of what the button says. The overlay stays until /stop+// succeeds, so a failed request can restore the composer without losing chips.+test('stop clears the queue only after the stop API succeeds', () => {+ const start = source.indexOf('const handleStopGeneration = ')+ const confirmedStart = source.indexOf('const handleStopConfirmed = ')+ const failedStart = source.indexOf('const handleStopFailed = ')+ const end = source.indexOf('const dropSteerQueueItem', start)+ assert.notEqual(start, -1)+ assert.notEqual(confirmedStart, -1)+ assert.notEqual(failedStart, -1)+ assert.notEqual(end, -1)++ const gen = source.slice(start, confirmedStart)+ assert.doesNotMatch(gen, /steerQueue\.value = \[\]/)+ assert.doesNotMatch(gen, /attachSteerFollowUp/)++ const confirmed = source.slice(confirmedStart, failedStart)+ assert.match(confirmed, /steerQueue\.value = \[\]/)++ const failed = source.slice(failedStart, end)+ assert.match(failed, /isReplying\.value = true/)+})++// Matching queued text against the message list attaches the wrong bubble as+// soon as the user sends the same thing twice. The follow-up run persists its+// query under its own request_id, which identifies the rows exactly.+test('follow-up attaches persisted users by request_id', () => {+ const fn = attachSteerFollowUpSource()+ assert.match(fn, /persisted\.request_id !== newAssistant\.request_id/)+ assert.match(fn, /hydrateSteerQueue\(\{ onlyWhenLive: true \}\)/)+ assert.doesNotMatch(fn, /m\.content === q\.content/)+})++// A 503 from the steer lookup must toast, not fall through to sendMsg. Only+// an explicit new_run (no live turn) starts a normal AgentQA.+test('steer lookup failure does not start a second turn', () => {+ const start = source.indexOf('const handleSteerMsg = async')+ const end = source.indexOf('const handlePromoteSteer = async', start)+ assert.notEqual(start, -1)+ assert.notEqual(end, -1)+ const fn = source.slice(start, end)+ const newRun = fn.indexOf("if (res?.status === 'new_run')")+ const catchIdx = fn.indexOf('} catch (e) {')+ assert.notEqual(newRun, -1)+ assert.notEqual(catchIdx, -1)+ assert.ok(newRun < catchIdx, 'new_run fallback must sit in the try, not the catch')+ const newRunBlock = fn.slice(newRun, catchIdx)+ assert.match(newRunBlock, /awaitingIdleSend/)+ assert.match(newRunBlock, /isReplying/)+ assert.match(newRunBlock, /await sendMsg\(/)+ assert.doesNotMatch(fn.slice(catchIdx), /sendMsg\(/)+})++test('new_run while a stream is live does not abort it', () => {+ const start = source.indexOf('const handleSteerMsg = async')+ const end = source.indexOf('const handlePromoteSteer = async', start)+ const fn = source.slice(start, end)+ const newRun = fn.indexOf("if (res?.status === 'new_run')")+ const catchIdx = fn.indexOf('} catch (e) {')+ const block = fn.slice(newRun, catchIdx)+ assert.match(block, /isStreaming/)+ assert.doesNotMatch(block, /stopStream\(/)+})++test('turn complete flushes idle new_run sends before attaching a follow-up', () => {+ assert.match(source, /const flushSteerAfterTurn = async/)+ assert.match(source, /awaitingIdleSend/)+ const start = source.indexOf('onTurnComplete:')+ const end = source.indexOf('});', start)+ const hook = source.slice(start, end)+ assert.match(hook, /flushSteerAfterTurn\(persistedAssistantId\(message\)\)/)+ assert.doesNotMatch(hook, /attachSteerFollowUp\(persistedAssistantId\(message\)\)/)+})++test('remaining overlay after-items chain after a follow-up stream ends', () => {+ const fn = attachSteerFollowUpSource()+ const finallyStart = fn.indexOf('} finally {')+ assert.notEqual(finallyStart, -1, 'attachSteerFollowUp must have a finally block')+ const finallyBlock = fn.slice(finallyStart)++ // startStream awaits the whole SSE. The follow-up's onTurnComplete therefore+ // runs while attachingSteerFollowUp is still true and would no-op. Remaining+ // after-items have to be retried once that guard drops.+ assert.match(finallyBlock, /steerQueue\.value\.length/)+ assert.match(finallyBlock, /void attachSteerFollowUp\(/)+})++// Switching sessions while the follow-up poll is in flight used to keep+// using session_id.value, so continue-stream landed on the new chat.+test('follow-up attach aborts when the session changes', () => {+ const fn = attachSteerFollowUpSource()+ assert.match(fn, /const sessionId = session_id\.value/)+ assert.match(fn, /session_id\.value !== sessionId/)+ assert.match(fn, /getMessageList\(\{ session_id: sessionId/)+ assert.match(fn, /session_id: sessionId/)+})++// After a mid-run inject the completing bubble is a steer-cont-* segment.+// Passing that id into attachSteerFollowUp cannot exclude the persisted+// row, so the finishing turn was picked as the follow-up.+test('follow-up attach keys off the persisted assistant id, not a fork id', () => {+ const start = source.indexOf('onTurnComplete:')+ const end = source.indexOf('});', start)+ assert.notEqual(start, -1)+ assert.notEqual(end, -1)+ const hook = source.slice(start, end)+ assert.match(hook, /flushSteerAfterTurn\(persistedAssistantId\(message\)\)/)+ assert.doesNotMatch(hook, /attachSteerFollowUp\(message\?\.id\)/)+ const flushStart = source.indexOf('const flushSteerAfterTurn = async')+ const flushEnd = source.indexOf('const attachSteerFollowUp = async', flushStart)+ assert.match(source.slice(flushStart, flushEnd), /attachSteerFollowUp\(completedAssistantId\)/)+})++// A stop that arrives over SSE (other tab, /stop API) discards the server+// queue. The overlay has to drop too, not only the local Stop button.+test('remove drops overlay when the server already injected the item', () => {+ const start = source.indexOf('const handleRemoveSteer = async')+ const end = source.indexOf('let attachingSteerFollowUp', start)+ assert.notEqual(start, -1)+ assert.notEqual(end, -1)+ const fn = source.slice(start, end)+ assert.match(fn, /already_injected/)+ assert.match(fn, /dropSteerQueueItem\(steerId\)/)+ assert.match(fn, /removed === false/)+})++test('remote stop clears the overlay queue', () => {+ assert.match(source, /onGenerationStopped/)+ const start = source.indexOf('onGenerationStopped')+ assert.notEqual(start, -1)+ const snippet = source.slice(start, start + 180)+ assert.match(snippet, /steerQueue\.value = \[\]/)+})diff --git a/internal/agent/engine.go b/internal/agent/engine.goindex e981ce0be..3a3e87e4a 100644--- a/internal/agent/engine.go+++ b/internal/agent/engine.go@@ -61,8 +61,18 @@ type AgentEngine struct {// changed, so there is no reason to spend another summarization call.compactionExhaustedAt intmodelContext *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}+// maxSteerOverruns caps loop-end injects past MaxIterations. One extra round+// lets a last-moment nudge 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)@@ -417,6 +427,24 @@ func (e *AgentEngine) withinIterationBudget(round int) bool {return round < e.config.MaxIterations}+// closeAnswerStream emits the Done:true marker for a natural-stop answer+// that is actually finishing. Loop-end inject skips this so the client+// does not drop isReplying while the engine continues.+func (e *AgentEngine) closeAnswerStream(ctx context.Context, sessionID, answerID string) {+ 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,+ },+ })+}+func (e *AgentEngine) maxIterationsDisplay() string {if e.config != nil && e.config.UnlimitedIterations() {return "unlimited"@@ -465,7 +493,8 @@ func (e *AgentEngine) executeLoop(consecutiveSameContent := 0lastResponseContent := ""loop:- for e.withinIterationBudget(state.CurrentRound) {+ for e.withinIterationBudget(state.CurrentRound) || e.allowSteerOverrun {+ e.allowSteerOverrun = false// Check for context cancellation (request timeout, user cancel, etc.)select {case <-ctx.Done():@@ -616,6 +645,13 @@ func (e *AgentEngine) runReActIteration(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)+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)@@ -744,11 +780,38 @@ func (e *AgentEngine) runReActIteration(state.FinalAnswer = "I'm sorry, I was unable to generate a response. Please try again."state.IsComplete = truestate.RoundSteps = append(state.RoundSteps, verdict.step)+ e.closeAnswerStream(ctx, sessionID, verdict.answerID)return iterOutcomeBreak, nil}+ // Loop-end inject: a user message queued while this finishing round+ // ran should keep 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,+ })+ injected := e.drainSteerMessages(ctx, state, messagesPtr, sessionID, assistantMessageID)+ if injected > 0 {+ state.RoundSteps = append(state.RoundSteps, verdict.step)+ if !e.withinIterationBudget(nextRound) {+ e.steerOverruns+++ e.allowSteerOverrun = true+ }+ return iterOutcomeNext, nil+ }+ }+ }state.FinalAnswer = verdict.finalAnswerstate.IsComplete = truestate.RoundSteps = append(state.RoundSteps, verdict.step)+ e.closeAnswerStream(ctx, sessionID, verdict.answerID)return iterOutcomeBreak, nil}diff --git a/internal/agent/observe.go b/internal/agent/observe.goindex 165a5768a..98c12acd0 100644--- a/internal/agent/observe.go+++ b/internal/agent/observe.go@@ -322,6 +322,11 @@ type responseVerdict struct {finalAnswer stringemptyContent bool // LLM returned stop with no tool calls and empty contentstep types.AgentStep+ // answerID is the EventAgentFinalAnswer id to close with Done:true if+ // this round actually finishes. Natural-stop must not close the stream+ // before the loop-end steer drain: a pending inject continues the turn,+ // and a premature Done tells the client the session is idle.+ answerID string}// isNaturalStopFinishReason reports whether a provider finish reason means the@@ -444,21 +449,16 @@ func (e *AgentEngine) analyzeResponse(})}}- e.eventBus.Emit(ctx, event.Event{- ID: answerID,- Type: event.EventAgentFinalAnswer,- SessionID: sessionID,- Data: event.AgentFinalAnswerData{- Content: "",- Done: true,- },- })+ // Do not emit Done:true here. The caller drains any loop-end inject+ // first; a premature close makes the client think the turn is idle+ // while the engine is about to continue.return responseVerdict{isDone: true,finalAnswer: response.Content,emptyContent: response.Content == "",step: step,+ answerID: answerID,}}diff --git a/internal/agent/steer.go b/internal/agent/steer.gonew file mode 100644index 000000000..6a4f26dde--- /dev/null+++ b/internal/agent/steer.go@@ -0,0 +1,92 @@+package agent++import (+ "context"+ "strings"++ "github.com/Tencent/WeKnora/internal/event"+ "github.com/Tencent/WeKnora/internal/logger"+ "github.com/Tencent/WeKnora/internal/models/chat"+ "github.com/Tencent/WeKnora/internal/types"+)++// sanitizeSteerContent normalizes newlines and trims, same treatment the chat+// pipeline applies to user queries.+func sanitizeSteerContent(content string) string {+ content = strings.ReplaceAll(content, "\r\n", "\n")+ content = strings.ReplaceAll(content, "\r", "\n")+ return strings.TrimSpace(content)+}++// SetSteerSink wires the optional steer channel. Nil (the default) disables+// mid-run injection entirely — every existing call site keeps working. The+// sink satisfies types.SteerSink structurally.+func (e *AgentEngine) SetSteerSink(sink types.SteerSink) {+ e.steerSink = sink+}++// drainSteerMessages is called at the round boundary, after context+// compression and before the next LLM call, so injected text:+// - lands in the protected tail (CompressContext never removes anything+// after the last user message),+// - is included in lastSentMsgCount's delta-token accounting,+// - and is visible to the very next callLLMWithRetry.+//+// Persist happens before append. A persist failure leaves the event+// unconsumed so the next boundary can retry; appending first would put+// text in the model that history never recorded.+func (e *AgentEngine) drainSteerMessages(+ ctx context.Context,+ state *types.AgentState,+ messagesPtr *[]chat.Message,+ sessionID, messageID string,+) int {+ if e.steerSink == nil {+ return 0+ }+ events, _, err := e.steerSink.PollSteer(ctx, sessionID, messageID, 0)+ if err != nil {+ logger.Warnf(ctx, "[Agent] Steer poll failed at round %d: %v", state.CurrentRound+1, err)+ return 0+ }+ if len(events) == 0 {+ return 0+ }++ injected := 0+ for _, evt := range events {+ content := sanitizeSteerContent(getString(evt, "content"))+ if content == "" {+ continue+ }+ steerID := getString(evt, "id")+ userMessageID := e.steerSink.PersistSteerMessage(ctx, sessionID, messageID, steerID, content,+ types.MentionedItemsFromRaw(evt["mentioned_items"]), getString(evt, "channel"))+ if userMessageID == "" {+ logger.Warnf(ctx, "[Agent] Steer persist failed for %s, leaving event pending", steerID)+ continue+ }+ *messagesPtr = append(*messagesPtr, chat.Message{Role: "user", Content: content})+ _ = e.eventBus.Emit(ctx, event.Event{+ ID: generateEventID("injected"),+ Type: event.EventUserMessageInjected,+ SessionID: sessionID,+ Data: event.UserMessageInjectedData{+ SteerID: steerID,+ Content: content,+ MessageID: messageID,+ UserMessageID: userMessageID,+ },+ })+ injected+++ }+ if injected > 0 {+ logger.Infof(ctx, "[Agent][Round-%d] Injected %d steered user message(s) into the turn",+ state.CurrentRound+1, injected)+ }+ return injected+}++func getString(evt map[string]interface{}, key string) string {+ return types.MapString(evt, key)+}diff --git a/internal/agent/steer_test.go b/internal/agent/steer_test.gonew file mode 100644index 000000000..f8c02100a--- /dev/null+++ b/internal/agent/steer_test.go@@ -0,0 +1,488 @@+package agent++import (+ "context"+ "strings"+ "testing"++ agenttools "github.com/Tencent/WeKnora/internal/agent/tools"+ "github.com/Tencent/WeKnora/internal/event"+ "github.com/Tencent/WeKnora/internal/models/chat"+ "github.com/Tencent/WeKnora/internal/types"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++// fakeSteerSink is a types.SteerSink whose queue is fed by the test. It+// records persistence calls so the drain path can be asserted end to end.+type fakeSteerSink struct {+ queued []map[string]interface{}+ persisted []string // contents passed to PersistSteerMessage, in order+ userIDs []string+ mentions []types.MentionedItems // mentions recorded alongside each persist+ failPersist bool+ consumed map[string]struct{}+}++func (s *fakeSteerSink) PollSteer(+ _ context.Context, _, _ string, lastOffset int,+) ([]map[string]interface{}, int, error) {+ _ = lastOffset+ out := make([]map[string]interface{}, 0)+ for _, evt := range s.queued {+ id, _ := evt["id"].(string)+ if _, ok := s.consumed[id]; ok {+ continue+ }+ out = append(out, evt)+ }+ return out, len(s.queued), nil+}++func (s *fakeSteerSink) PersistSteerMessage(+ _ context.Context, _, _, steerID, content string, mentionedItems types.MentionedItems, _ string,+) string {+ if s.failPersist {+ return ""+ }+ s.persisted = append(s.persisted, content)+ id := "user-row-for-" + content+ s.userIDs = append(s.userIDs, id)+ s.mentions = append(s.mentions, mentionedItems)+ if s.consumed == nil {+ s.consumed = map[string]struct{}{}+ }+ if steerID != "" {+ s.consumed[steerID] = struct{}{}+ }+ return id+}++func steerEntry(id, content string) map[string]interface{} {+ return map[string]interface{}{"id": id, "content": content}+}++// TestDrainSteerMessagesInjectsIntoTail verifies the core mid-run steering+// behaviour: a queued message becomes the last user message, is persisted,+// and emits an EventUserMessageInjected on the bus — all at the drain point,+// before the next LLM call would be built.+func TestDrainSteerMessagesInjectsIntoTail(t *testing.T) {+ model := &mockChat{}+ engine := newTestEngine(t, model)+ bus := event.NewEventBus()+ engine.eventBus = bus++ injectedCh := make(chan event.UserMessageInjectedData, 4)+ bus.On(event.EventUserMessageInjected, func(_ context.Context, evt event.Event) error {+ if data, ok := evt.Data.(event.UserMessageInjectedData); ok {+ injectedCh <- data+ }+ return nil+ })++ sink := &fakeSteerSink{+ queued: []map[string]interface{}{+ steerEntry("steer-1", "再补充一点:也对比一下成本"),+ },+ }+ engine.SetSteerSink(sink)++ messages := []chat.Message{+ {Role: "system", Content: "sys"},+ {Role: "user", Content: "original query"},+ {Role: "assistant", Content: "", ToolCalls: []chat.ToolCall{{ID: "tc1"}}},+ {Role: "tool", Content: "tool output"},+ }+ state := &types.AgentState{CurrentRound: 1}+ engine.drainSteerMessages(context.Background(), state, &messages, "sess", "msg")++ require.Len(t, messages, 5)+ assert.Equal(t, "user", messages[4].Role)+ assert.Equal(t, "再补充一点:也对比一下成本", messages[4].Content)+ // Tool result pairing is untouched — the tool message stays where it was.+ assert.Equal(t, "tool", messages[3].Role)++ require.Len(t, sink.persisted, 1)+ assert.Equal(t, "再补充一点:也对比一下成本", sink.persisted[0])++ select {+ case data := <-injectedCh:+ assert.Equal(t, "steer-1", data.SteerID)+ assert.Equal(t, "msg", data.MessageID)+ assert.Equal(t, "user-row-for-再补充一点:也对比一下成本", data.UserMessageID)+ default:+ t.Fatal("expected an EventUserMessageInjected on the bus")+ }+}++// TestDrainSteerMessagesEmptyAndOffset pins that a drained queue is not+// replayed on the next boundary, and an empty queue is a no-op.+func TestDrainSteerMessagesEmptyAndOffset(t *testing.T) {+ model := &mockChat{}+ engine := newTestEngine(t, model)+ engine.eventBus = event.NewEventBus()+ sink := &fakeSteerSink{}+ engine.SetSteerSink(sink)++ messages := []chat.Message{{Role: "user", Content: "q"}}+ state := &types.AgentState{CurrentRound: 0}++ engine.drainSteerMessages(context.Background(), state, &messages, "sess", "msg")+ assert.Len(t, messages, 1)++ sink.queued = []map[string]interface{}{+ steerEntry("s1", "first"),+ steerEntry("s2", "second"),+ }+ engine.drainSteerMessages(context.Background(), state, &messages, "sess", "msg")+ assert.Len(t, messages, 3)+ assert.Equal(t, "first", messages[1].Content)+ assert.Equal(t, "second", messages[2].Content)+ require.Len(t, sink.persisted, 2)++ engine.drainSteerMessages(context.Background(), state, &messages, "sess", "msg")+ assert.Len(t, messages, 3)+ assert.Len(t, sink.persisted, 2)+}++// TestDrainSteerMessagesNilSinkNoOp ensures the default engine (no sink) is+// completely unaffected — the mid-run steering feature is opt-in.+func TestDrainSteerMessagesNilSinkNoOp(t *testing.T) {+ model := &mockChat{}+ engine := newTestEngine(t, model)+ engine.eventBus = event.NewEventBus()++ messages := []chat.Message{{Role: "user", Content: "q"}}+ state := &types.AgentState{CurrentRound: 0}+ engine.drainSteerMessages(context.Background(), state, &messages, "sess", "msg")+ assert.Len(t, messages, 1)+}++// TestDrainSteerMessagesBlankContentSkipped guards against blank steer+// payloads appending empty user turns that would confuse the model and+// SanitizeMessages alike.+func TestDrainSteerMessagesBlankContentSkipped(t *testing.T) {+ model := &mockChat{}+ engine := newTestEngine(t, model)+ engine.eventBus = event.NewEventBus()+ sink := &fakeSteerSink{+ queued: []map[string]interface{}{+ steerEntry("s1", " \n "),+ steerEntry("s2", "real instruction"),+ },+ }+ engine.SetSteerSink(sink)++ messages := []chat.Message{{Role: "user", Content: "q"}}+ state := &types.AgentState{CurrentRound: 0}+ engine.drainSteerMessages(context.Background(), state, &messages, "sess", "msg")++ require.Len(t, messages, 2)+ assert.Equal(t, "real instruction", messages[1].Content)+ require.Len(t, sink.persisted, 1)+}++// TestExecuteLoopInjectsBeforeNextLLMCall is the integration-level guard: with+// a sink wired, a queued steer message that arrives while round 1 is executing+// must appear in the messages array of round 2's LLM call.+func TestExecuteLoopInjectsBeforeNextLLMCall(t *testing.T) {+ // Round 1: model calls a tool; Round 2: model answers and stops.+ model := &mockChat{responses: []mockResponse{+ {chunks: []types.StreamResponse{+ {+ ResponseType: types.ResponseTypeAnswer,+ Content: "let me check",+ ToolCalls: []types.LLMToolCall{{+ ID: "tc1",+ Type: "function",+ Function: types.FunctionCall{Name: "counting_tool", Arguments: "{}"},+ }},+ },+ }},+ {chunks: []types.StreamResponse{+ {ResponseType: types.ResponseTypeAnswer, Content: "done", Done: true},+ }},+ }}+ engine := newTestEngine(t, model)+ engine.eventBus = event.NewEventBus()++ sink := &fakeSteerSink{}+ engine.SetSteerSink(sink)++ // Simulate the user queueing a message while round 1 runs: it is in the+ // queue before the loop's second drain point executes.+ sink.queued = []map[string]interface{}{+ steerEntry("s1", "focus on the cost angle"),+ }++ engine.toolRegistry = agentRegistryForTest(t, "counting_tool")++ state := &types.AgentState{+ CurrentRound: 0,+ RoundSteps: []types.AgentStep{},+ }+ messages := []chat.Message{+ {Role: "system", Content: "sys"},+ {Role: "user", Content: "start"},+ }+ tools := engine.buildToolsForLLM()+ _, err := engine.executeLoop(context.Background(), state, "start", messages, tools, "sess", "msg")+ require.NoError(t, err)+ require.Len(t, model.calls, 2)++ // Round 2's call must contain the injected steer text. SanitizeMessages+ // merges consecutive same-role messages, so the injected user message+ // may be concatenated onto the original "start" user turn — that is the+ // desired end state (the model reads it as the user adding instructions+ // mid-task).+ second := model.calls[1]+ found := false+ for _, msg := range second {+ if msg.Role == "user" && strings.Contains(msg.Content, "focus on the cost angle") {+ found = true+ break+ }+ }+ assert.True(t, found, "injected steer text missing from round 2 LLM call: %+v", second)+ require.Len(t, sink.persisted, 1)+}++// delayedSteerSink hides queued messages until the Nth PollSteer call. Used+// to simulate a user sending a mid-run inject while round 1's LLM call is+// in flight — the round-start drain sees nothing, the natural-stop drain+// sees the message.+type delayedSteerSink struct {+ fakeSteerSink+ hideUntil int+ polls int+}++func (s *delayedSteerSink) PollSteer(+ ctx context.Context, sessionID, messageID string, lastOffset int,+) ([]map[string]interface{}, int, error) {+ s.polls+++ if s.polls < s.hideUntil {+ return nil, lastOffset, nil+ }+ return s.fakeSteerSink.PollSteer(ctx, sessionID, messageID, lastOffset)+}++// TestExecuteLoopContinuesWhenSteerArrivesOnNaturalStop is the loop-end+// inject path: the model is about to finish, a user inject is waiting, and+// the engine must keep going instead of emitting a final answer.+func TestExecuteLoopContinuesWhenSteerArrivesOnNaturalStop(t *testing.T) {+ model := &mockChat{responses: []mockResponse{+ {chunks: []types.StreamResponse{+ {ResponseType: types.ResponseTypeAnswer, Content: "first draft", Done: true, FinishReason: "stop"},+ }},+ {chunks: []types.StreamResponse{+ {ResponseType: types.ResponseTypeAnswer, Content: "revised after steer", Done: true, FinishReason: "stop"},+ }},+ }}+ engine := newTestEngine(t, model)+ engine.eventBus = event.NewEventBus()++ sink := &delayedSteerSink{+ fakeSteerSink: fakeSteerSink{+ queued: []map[string]interface{}{+ steerEntry("s1", "rewrite this from the cost angle"),+ },+ },+ hideUntil: 2, // skip the round-1 start drain+ }+ engine.SetSteerSink(sink)++ state := &types.AgentState{RoundSteps: []types.AgentStep{}}+ messages := []chat.Message{+ {Role: "system", Content: "sys"},+ {Role: "user", Content: "write a draft"},+ }+ _, err := engine.executeLoop(context.Background(), state, "write a draft", messages, nil, "sess", "msg")+ require.NoError(t, err)+ require.Len(t, model.calls, 2)++ second := model.calls[1]+ foundSteer := false+ foundDraft := false+ for _, msg := range second {+ if msg.Role == "user" && strings.Contains(msg.Content, "rewrite this from the cost angle") {+ foundSteer = true+ }+ if msg.Role == "assistant" && strings.Contains(msg.Content, "first draft") {+ foundDraft = true+ }+ }+ assert.True(t, foundSteer, "steer text missing from the continued round: %+v", second)+ assert.True(t, foundDraft, "the would-be final answer must stay in history so the model can revise it: %+v", second)+ assert.Equal(t, "revised after steer", state.FinalAnswer)+ require.Len(t, sink.persisted, 1)+}++// Persist failure must not append the text into the model context. Retrying+// the same event on the next boundary would otherwise duplicate it; leaving it+// unconsumed lets the next drain try again.+func TestDrainSteerMessagesSkipsAppendWhenPersistFails(t *testing.T) {+ model := &mockChat{}+ engine := newTestEngine(t, model)+ engine.eventBus = event.NewEventBus()+ sink := &fakeSteerSink{+ queued: []map[string]interface{}{steerEntry("s1", "keep this pending")},+ failPersist: true,+ }+ engine.SetSteerSink(sink)++ messages := []chat.Message{{Role: "user", Content: "q"}}+ state := &types.AgentState{CurrentRound: 0}+ assert.Equal(t, 0, engine.drainSteerMessages(context.Background(), state, &messages, "sess", "msg"))+ assert.Len(t, messages, 1)+ assert.Empty(t, sink.persisted)+}++func countAnswerDone(bus *event.EventBus) *int {+ n := 0+ bus.On(event.EventAgentFinalAnswer, func(_ context.Context, evt event.Event) error {+ if data, ok := evt.Data.(event.AgentFinalAnswerData); ok && data.Done {+ n+++ }+ return nil+ })+ return &n+}++// Loop-end inject used to close the first answer (Done:true) before deciding+// to continue. The frontend then treated the session as idle and started a+// second AgentQA. Only the actual finishing round may emit Done.+func TestExecuteLoopLoopEndInjectDoesNotCloseAnswerBeforeContinue(t *testing.T) {+ model := &mockChat{responses: []mockResponse{+ {chunks: []types.StreamResponse{+ {ResponseType: types.ResponseTypeAnswer, Content: "first draft", Done: true, FinishReason: "stop"},+ }},+ {chunks: []types.StreamResponse{+ {ResponseType: types.ResponseTypeAnswer, Content: "revised after steer", Done: true, FinishReason: "stop"},+ }},+ }}+ engine := newTestEngine(t, model)+ bus := event.NewEventBus()+ engine.eventBus = bus+ doneCount := countAnswerDone(bus)++ sink := &delayedSteerSink{+ fakeSteerSink: fakeSteerSink{+ queued: []map[string]interface{}{+ steerEntry("s1", "rewrite this from the cost angle"),+ },+ },+ hideUntil: 2,+ }+ engine.SetSteerSink(sink)++ state := &types.AgentState{RoundSteps: []types.AgentStep{}}+ messages := []chat.Message{+ {Role: "system", Content: "sys"},+ {Role: "user", Content: "write a draft"},+ }+ _, err := engine.executeLoop(context.Background(), state, "write a draft", messages, nil, "sess", "msg")+ require.NoError(t, err)+ require.Len(t, model.calls, 2)+ assert.Equal(t, 1, *doneCount, "Done:true must fire once, after the continued round actually finishes")+}++// Inject on the last in-budget round used to increment CurrentRound past the+// cap and fall into handleMaxIterations, which synthesizes from the original+// query and never runs another ReAct round.+func TestExecuteLoopLastRoundInjectRunsAnotherReActRound(t *testing.T) {+ model := &mockChat{responses: []mockResponse{+ {chunks: []types.StreamResponse{+ {ResponseType: types.ResponseTypeAnswer, Content: "first draft", Done: true, FinishReason: "stop"},+ }},+ {chunks: []types.StreamResponse{+ {ResponseType: types.ResponseTypeAnswer, Content: "revised after steer", Done: true, FinishReason: "stop"},+ }},+ }}+ engine := newTestEngine(t, model, withMaxIterations(1))+ engine.eventBus = event.NewEventBus()+ sink := &delayedSteerSink{+ fakeSteerSink: fakeSteerSink{+ queued: []map[string]interface{}{+ steerEntry("s1", "rewrite this from the cost angle"),+ },+ },+ hideUntil: 2,+ }+ engine.SetSteerSink(sink)++ state := &types.AgentState{RoundSteps: []types.AgentStep{}}+ messages := []chat.Message{+ {Role: "system", Content: "sys"},+ {Role: "user", Content: "write a draft"},+ }+ _, err := engine.executeLoop(context.Background(), state, "write a draft", messages, nil, "sess", "msg")+ require.NoError(t, err)+ require.Len(t, model.calls, 2)+ assert.Equal(t, "revised after steer", state.FinalAnswer)+}++type sequencedSteerSink struct {+ fakeSteerSink+ byPoll map[int][]map[string]interface{}+ polls int+}++func (s *sequencedSteerSink) PollSteer(+ ctx context.Context, sessionID, messageID string, lastOffset int,+) ([]map[string]interface{}, int, error) {+ s.polls+++ if batch, ok := s.byPoll[s.polls]; ok {+ s.queued = batch+ } else {+ s.queued = nil+ }+ return s.fakeSteerSink.PollSteer(ctx, sessionID, messageID, lastOffset)+}++// A second loop-end inject after the extra overrun round must not keep the+// turn alive. MaxIterations would otherwise be unbounded for a user who+// keeps sending delivery=inject.+func TestExecuteLoopSecondOverrunDoesNotContinue(t *testing.T) {+ model := &mockChat{responses: []mockResponse{+ {chunks: []types.StreamResponse{+ {ResponseType: types.ResponseTypeAnswer, Content: "first draft", Done: true, FinishReason: "stop"},+ }},+ {chunks: []types.StreamResponse{+ {ResponseType: types.ResponseTypeAnswer, Content: "revised after steer", Done: true, FinishReason: "stop"},+ }},+ {chunks: []types.StreamResponse{+ {ResponseType: types.ResponseTypeAnswer, Content: "should not run", Done: true, FinishReason: "stop"},+ }},+ }}+ engine := newTestEngine(t, model, withMaxIterations(1))+ engine.eventBus = event.NewEventBus()+ sink := &sequencedSteerSink{+ byPoll: map[int][]map[string]interface{}{+ 2: {steerEntry("s1", "rewrite this from the cost angle")},+ 4: {steerEntry("s2", "and again")},+ },+ }+ engine.SetSteerSink(sink)++ state := &types.AgentState{RoundSteps: []types.AgentStep{}}+ messages := []chat.Message{+ {Role: "system", Content: "sys"},+ {Role: "user", Content: "write a draft"},+ }+ _, err := engine.executeLoop(context.Background(), state, "write a draft", messages, nil, "sess", "msg")+ require.NoError(t, err)+ require.Len(t, model.calls, 2)+ assert.Equal(t, "revised after steer", state.FinalAnswer)+ assert.Equal(t, []string{"rewrite this from the cost angle"}, sink.persisted)+}++// agentRegistryForTest builds a registry with one counting tool so the loop+// can exercise a full think → act → observe round without external services.+func agentRegistryForTest(t *testing.T, name string) *agenttools.ToolRegistry {+ t.Helper()+ registry := agenttools.NewToolRegistry()+ tool := newCountingTool(name)+ registry.RegisterTool(tool)+ return registry+}diff --git a/internal/application/service/agent_history.go b/internal/application/service/agent_history.goindex 195caf3af..c24affcb4 100644--- a/internal/application/service/agent_history.go+++ b/internal/application/service/agent_history.go@@ -70,52 +70,97 @@ func LoadAgentHistory(return []chat.Message{}, nil}- type pair struct {- user *types.Message+ // A turn is not always one user message. Mid-run steering persists every+ // injected message under the running turn's request ID, so a turn can be+ // user → tools → user → tools → answer. Keeping only the last user row+ // would drop the original question from the next turn's context.+ type turn struct {+ users []*types.Messageassistant *types.MessagecreatedAt time.Time}- pairs := make(map[string]*pair)+ turns := make(map[string]*turn)for _, msg := range rows {- p, ok := pairs[msg.RequestID]+ t, ok := turns[msg.RequestID]if !ok {- p = &pair{}- pairs[msg.RequestID] = p+ t = &turn{}+ turns[msg.RequestID] = t}switch msg.Role {case "user":- p.user = msg- if p.createdAt.IsZero() || msg.CreatedAt.Before(p.createdAt) {- p.createdAt = msg.CreatedAt+ t.users = append(t.users, msg)+ if t.createdAt.IsZero() || msg.CreatedAt.Before(t.createdAt) {+ t.createdAt = msg.CreatedAt}case "assistant":- p.assistant = msg+ t.assistant = msg}}- completePairs := make([]*pair, 0, len(pairs))- for _, p := range pairs {- if p.user != nil && p.assistant != nil && p.assistant.IsCompleted {- completePairs = append(completePairs, p)+ completeTurns := make([]*turn, 0, len(turns))+ for _, t := range turns {+ if len(t.users) > 0 && t.assistant != nil && t.assistant.IsCompleted {+ sort.SliceStable(t.users, func(i, j int) bool {+ return t.users[i].CreatedAt.Before(t.users[j].CreatedAt)+ })+ completeTurns = append(completeTurns, t)}}- sort.Slice(completePairs, func(i, j int) bool {- return completePairs[i].createdAt.Before(completePairs[j].createdAt)+ sort.Slice(completeTurns, func(i, j int) bool {+ return completeTurns[i].createdAt.Before(completeTurns[j].createdAt)})- if len(completePairs) > maxRounds {- completePairs = completePairs[len(completePairs)-maxRounds:]+ if len(completeTurns) > maxRounds {+ completeTurns = completeTurns[len(completeTurns)-maxRounds:]}- out := make([]chat.Message, 0, len(completePairs)*4)- for _, p := range completePairs {- out = append(out, buildUserHistoryMessage(p.user))- out = append(out, buildAssistantHistoryMessages(p.assistant)...)+ out := make([]chat.Message, 0, len(completeTurns)*4)+ for _, t := range completeTurns {+ out = append(out, buildUserHistoryMessage(t.users[0]))+ out = append(out, buildTurnBodyMessages(t.assistant, t.users[1:])...)}return out, nil}+// buildTurnBodyMessages replays one turn's assistant work with any mid-run+// user messages put back where they happened. Steered messages arrive between+// tool rounds, so replaying them all up-front (or dropping them) would tell+// the model a different story than the one it lived through: it would look+// like the user asked for everything before any tool ran.+//+// Steps carry a timestamp; a user row belongs before the first step that+// starts after it. Anything left over lands just before the final answer.+func buildTurnBodyMessages(assistant *types.Message, midRunUsers []*types.Message) []chat.Message {+ if len(midRunUsers) == 0 {+ return buildAssistantHistoryMessages(assistant)+ }++ out := make([]chat.Message, 0, len(assistant.AgentSteps)*2+len(midRunUsers)+1)+ next := 0+ for _, step := range assistant.AgentSteps {+ stepMsgs := buildAgentStepMessages(step)+ if len(stepMsgs) == 0 {+ continue+ }+ for next < len(midRunUsers) &&+ !step.Timestamp.IsZero() &&+ midRunUsers[next].CreatedAt.Before(step.Timestamp) {+ out = append(out, buildUserHistoryMessage(midRunUsers[next]))+ next+++ }+ out = append(out, stepMsgs...)+ }+ for ; next < len(midRunUsers); next++ {+ out = append(out, buildUserHistoryMessage(midRunUsers[next]))+ }++ if final := finalAnswerHistoryMessage(assistant); final != nil {+ out = append(out, *final)+ }+ return out+}+// buildUserHistoryMessage converts a stored user message into the chat.Message// form that should appear in LLM history. It deliberately ignores// RenderedContent: that field is a snapshot of the old prompt and retrieval@@ -144,39 +189,59 @@ func buildUserHistoryMessage(m *types.Message) chat.Message {func buildAssistantHistoryMessages(m *types.Message) []chat.Message {msgs := make([]chat.Message, 0, len(m.AgentSteps)*2+1)for _, step := range m.AgentSteps {- nonTerminalCalls := filterNonTerminalToolCalls(step.ToolCalls)- if len(nonTerminalCalls) == 0 {- continue- }- assistantMsg := chat.Message{- Role: "assistant",- Content: step.Thought,- ReasoningContent: step.ReasoningContent,- ToolCalls: make([]chat.ToolCall, 0, len(nonTerminalCalls)),- }- for _, tc := range nonTerminalCalls {- argsJSON, _ := json.Marshal(tc.Args)- assistantMsg.ToolCalls = append(assistantMsg.ToolCalls, chat.ToolCall{- ID: tc.ID,- Type: "function",- ProviderMetadata: tc.ProviderMetadata,- Function: chat.FunctionCall{- Name: tc.Name,- Arguments: string(argsJSON),- },- })- }- msgs = append(msgs, assistantMsg)- for _, tc := range nonTerminalCalls {- msgs = append(msgs, chat.Message{- Role: "tool",- Content: toolCallOutput(tc),- ToolCallID: tc.ID,- Name: tc.Name,- })- }+ msgs = append(msgs, buildAgentStepMessages(step)...)+ }+ if final := finalAnswerHistoryMessage(m); final != nil {+ msgs = append(msgs, *final)+ }+ return msgs+}++// buildAgentStepMessages expands one persisted step into the OpenAI-shaped+// assistant + tool pair. Steps whose only calls were terminal or synthetic+// produce nothing, so callers can treat an empty result as "not a real round".+func buildAgentStepMessages(step types.AgentStep) []chat.Message {+ nonTerminalCalls := filterNonTerminalToolCalls(step.ToolCalls)+ if len(nonTerminalCalls) == 0 {+ return nil+ }+ assistantMsg := chat.Message{+ Role: "assistant",+ Content: step.Thought,+ ReasoningContent: step.ReasoningContent,+ ToolCalls: make([]chat.ToolCall, 0, len(nonTerminalCalls)),+ }+ for _, tc := range nonTerminalCalls {+ argsJSON, _ := json.Marshal(tc.Args)+ assistantMsg.ToolCalls = append(assistantMsg.ToolCalls, chat.ToolCall{+ ID: tc.ID,+ Type: "function",+ ProviderMetadata: tc.ProviderMetadata,+ Function: chat.FunctionCall{+ Name: tc.Name,+ Arguments: string(argsJSON),+ },+ })+ }++ msgs := make([]chat.Message, 0, len(nonTerminalCalls)+1)+ msgs = append(msgs, assistantMsg)+ for _, tc := range nonTerminalCalls {+ msgs = append(msgs, chat.Message{+ Role: "tool",+ Content: toolCallOutput(tc),+ ToolCallID: tc.ID,+ Name: tc.Name,+ })}+ return msgs+}+// finalAnswerHistoryMessage is the canonical answer of a turn, or nil when the+// turn produced no text (stopped, or answered purely through tools). The+// generated-file markers belong to that turn, so they are relabeled before+// being replayed into a later turn's history.+func finalAnswerHistoryMessage(m *types.Message) *chat.Message {finalContent := agentHistoryThinkTagRegex.ReplaceAllString(m.Content, "")// Version clarification was written for that message's turn, not this one.finalContent = strings.NewReplacer(@@ -184,10 +249,10 @@ func buildAssistantHistoryMessages(m *types.Message) []chat.Message {"\n\nFile generated this turn: ![", "\n\nFile generated in that historical turn: ![",).Replace(finalContent)finalContent = strings.TrimSpace(finalContent)- if finalContent != "" {- msgs = append(msgs, chat.Message{Role: "assistant", Content: finalContent})+ if finalContent == "" {+ return nil}- return msgs+ return &chat.Message{Role: "assistant", Content: finalContent}}// legacyFinalAnswerToolName is the name of the now-removed final_answer tool.diff --git a/internal/application/service/agent_history_test.go b/internal/application/service/agent_history_test.goindex 7c57e4527..5f45af07b 100644--- a/internal/application/service/agent_history_test.go+++ b/internal/application/service/agent_history_test.go@@ -3,6 +3,7 @@ package serviceimport ("encoding/json""testing"+ "time"agenttools "github.com/Tencent/WeKnora/internal/agent/tools""github.com/Tencent/WeKnora/internal/models/chat"@@ -303,6 +304,96 @@ func TestBuildAssistantHistoryMessages_SkillScriptFailureKeepsStdout(t *testing.assert.Contains(t, got[1].Content, "Error: Script exited with code 1")}+// A steered turn has more than one user message: the original question plus+// whatever the user injected while the agent was working, all sharing the+// run's request ID. Replaying only one of them would hand the next turn a+// conversation that never happened — typically losing the original question,+// since the injected message is the newer row.+func TestBuildTurnBodyMessages_KeepsMidRunUsersInPlace(t *testing.T) {+ firstStep := time.Date(2026, 9, 4, 10, 0, 0, 0, time.UTC)+ secondStep := firstStep.Add(2 * time.Minute)++ assistant := &types.Message{+ Role: "assistant",+ Content: "Both are covered in the guide.",+ AgentSteps: types.AgentSteps{+ {+ Iteration: 0,+ Thought: "Search for A.",+ Timestamp: firstStep,+ ToolCalls: []types.ToolCall{{+ ID: "call_a",+ Name: agenttools.ToolKnowledgeSearch,+ Args: map[string]interface{}{"query": "A"},+ Result: &types.ToolResult{Success: true, Output: "found A"},+ }},+ },+ {+ Iteration: 1,+ Thought: "Now search for B.",+ Timestamp: secondStep,+ ToolCalls: []types.ToolCall{{+ ID: "call_b",+ Name: agenttools.ToolKnowledgeSearch,+ Args: map[string]interface{}{"query": "B"},+ Result: &types.ToolResult{Success: true, Output: "found B"},+ }},+ },+ },+ }+ midRun := []*types.Message{{+ Role: "user",+ Content: "also check B",+ CreatedAt: firstStep.Add(time.Minute),+ }}++ got := buildTurnBodyMessages(assistant, midRun)+ require.Len(t, got, 6)++ assert.Equal(t, "assistant", got[0].Role)+ assert.Equal(t, "tool", got[1].Role)+ assert.Equal(t, "found A", got[1].Content)++ // The injected message belongs between the round it interrupted and the+ // round it caused, not bolted onto either end.+ assert.Equal(t, chat.Message{Role: "user", Content: "also check B"}, got[2])++ assert.Equal(t, "assistant", got[3].Role)+ assert.Equal(t, "tool", got[4].Role)+ assert.Equal(t, "found B", got[4].Content)+ assert.Equal(t, chat.Message{Role: "assistant", Content: "Both are covered in the guide."}, got[5])+}++// A message injected after the last tool round still has to appear before the+// answer, or the turn reads as if the agent answered a question it was never+// asked.+func TestBuildTurnBodyMessages_LateMidRunUserPrecedesAnswer(t *testing.T) {+ step := time.Date(2026, 9, 4, 10, 0, 0, 0, time.UTC)+ assistant := &types.Message{+ Role: "assistant",+ Content: "Here you go.",+ AgentSteps: types.AgentSteps{{+ Iteration: 0,+ Timestamp: step,+ ToolCalls: []types.ToolCall{{+ ID: "call_a",+ Name: agenttools.ToolKnowledgeSearch,+ Result: &types.ToolResult{Success: true, Output: "found"},+ }},+ }},+ }+ midRun := []*types.Message{{+ Role: "user",+ Content: "and keep it short",+ CreatedAt: step.Add(time.Minute),+ }}++ got := buildTurnBodyMessages(assistant, midRun)+ require.Len(t, got, 4)+ assert.Equal(t, chat.Message{Role: "user", Content: "and keep it short"}, got[2])+ assert.Equal(t, chat.Message{Role: "assistant", Content: "Here you go."}, got[3])+}+// TestFilterNonTerminalToolCalls confirms a legacy final_answer entry is// dropped — every other tool (KB search, web search, MCP tools…) must survive.func TestFilterNonTerminalToolCalls(t *testing.T) {diff --git a/internal/application/service/session_agent_qa.go b/internal/application/service/session_agent_qa.goindex 3f8a63922..4eb6075a5 100644--- a/internal/application/service/session_agent_qa.go+++ b/internal/application/service/session_agent_qa.go@@ -230,6 +230,13 @@ func (s *sessionService) AgentQA(}}+ // Mid-run steering: when the caller supplied a sink, the engine will drain+ // user-appended messages at every round boundary and persist accepted ones+ // through it. Nil (IM/embed) keeps the old behaviour untouched.+ if req.SteerSink != nil {+ engine.SetSteerSink(req.SteerSink)+ }+agentQuery := req.Queryvar agentImageURLs []stringif agentModelSupportsVision && len(req.ImageURLs) > 0 {@@ -495,7 +502,9 @@ func applyPerRequestMCPScope(return}mentioned := dedupPreservingOrder(requested)- effective, _ := resolvePerRequestMCPScope(mentioned, agentPresetMCPs, agentConfig.MCPSelectionMode, isSharedAgent)+ effective, _ := resolvePerRequestMCPScope(+ mentioned, agentPresetMCPs, agentConfig.MCPSelectionMode, isSharedAgent,+ )if len(effective) == 0 {logger.Warnf(ctx, "Ignoring @MCP scope outside agent preset: requested=%v agent=%v shared=%v",requested, agentPresetMCPs, isSharedAgent)diff --git a/internal/application/service/tenant_skill_install_test.go b/internal/application/service/tenant_skill_install_test.goindex 9a6a6593e..3fd2f6e2f 100644--- a/internal/application/service/tenant_skill_install_test.go+++ b/internal/application/service/tenant_skill_install_test.go@@ -3167,7 +3167,8 @@ func (e *installAgentEngine) Execute(}return &types.AgentState{IsComplete: true}, nil}-func (e *installAgentEngine) SetMemoryPrompt(string) {}+func (e *installAgentEngine) SetMemoryPrompt(string) {}+func (e *installAgentEngine) SetSteerSink(types.SteerSink) {}type installSessionService struct {fx *installFixturediff --git a/internal/application/service/tenant_skill_transcript_test.go b/internal/application/service/tenant_skill_transcript_test.goindex 7883b435d..ab9936811 100644--- a/internal/application/service/tenant_skill_transcript_test.go+++ b/internal/application/service/tenant_skill_transcript_test.go@@ -33,6 +33,46 @@ func (s *transcriptStreams) GetEvents(return s.events[from:], len(s.events), nil}+func (s *transcriptStreams) AppendSteerEvents(+ _ context.Context, _, _ string, _ []interfaces.StreamEvent,+) error {+ return s.err+}++func (s *transcriptStreams) GetSteerEvents(+ _ context.Context, _, _ string, from int,+) ([]interfaces.StreamEvent, int, error) {+ return nil, from, nil+}++func (s *transcriptStreams) UpdateSteerEventData(+ context.Context, string, string, string, map[string]interface{},+) (bool, error) {+ return false, nil+}++func (s *transcriptStreams) DeleteSteerEvent(+ context.Context, string, string, string,+) (bool, error) {+ return false, nil+}++func (s *transcriptStreams) SetLiveRun(context.Context, string, string, string) error {+ return nil+}++func (s *transcriptStreams) ClaimLiveRun(context.Context, string, string, string) error {+ return nil+}++func (s *transcriptStreams) GetLiveRun(context.Context, string) (string, string, error) {+ return "", "", nil+}++func (s *transcriptStreams) ClearLiveRun(context.Context, string, string) error {+ return nil+}+func (s *transcriptStreams) types() []types.ResponseType {out := make([]types.ResponseType, 0, len(s.events))for _, evt := range s.events {diff --git a/internal/event/event.go b/internal/event/event.goindex a0baa34ab..e686d44db 100644--- a/internal/event/event.go+++ b/internal/event/event.go@@ -78,6 +78,11 @@ const (// away to fit the context window.EventContextCompacted EventType = "context_compacted"+ // EventUserMessageInjected is emitted when a message the user appended+ // while the run was in flight was accepted into the running turn (see+ // agent drainSteerMessages).+ EventUserMessageInjected EventType = "user_message_injected"+// Session eventsEventSessionTitle EventType = "session_title" // 会话标题更新diff --git a/internal/event/event_data.go b/internal/event/event_data.goindex 3cac95478..a92ab3675 100644--- a/internal/event/event_data.go+++ b/internal/event/event_data.go@@ -216,6 +216,17 @@ type ContextCompactedData struct {SplitTurn bool `json:"split_turn,omitempty"`}+// UserMessageInjectedData reports that a message the user appended while the+// run was in flight was accepted into the running turn: a user-role row has+// been persisted under the run's request ID and the text was appended to the+// agent's message list, so the next LLM call already sees it.+type UserMessageInjectedData struct {+ SteerID string `json:"steer_id"` // Correlates with the queued steer event+ Content string `json:"content"` // The injected text, as sent to the model+ MessageID string `json:"message_id"` // Durable assistant message of the run+ UserMessageID string `json:"user_message_id,omitempty"`+}+// AgentReflectionData represents agent reflection datatype AgentReflectionData struct {ToolCallID string `json:"tool_call_id"` // Tool call ID for trackingdiff --git a/internal/handler/sandbox_skill_test.go b/internal/handler/sandbox_skill_test.goindex d73c3d397..b13598514 100644--- a/internal/handler/sandbox_skill_test.go+++ b/internal/handler/sandbox_skill_test.go@@ -975,6 +975,46 @@ func (m *transcriptStreamManager) GetEvents(return out, len(m.events), nil}+func (m *transcriptStreamManager) AppendSteerEvents(+ _ context.Context, _, _ string, _ []interfaces.StreamEvent,+) error {+ return nil+}++func (m *transcriptStreamManager) GetSteerEvents(+ _ context.Context, _, _ string, from int,+) ([]interfaces.StreamEvent, int, error) {+ return nil, from, nil+}++func (m *transcriptStreamManager) UpdateSteerEventData(+ context.Context, string, string, string, map[string]interface{},+) (bool, error) {+ return false, nil+}++func (m *transcriptStreamManager) DeleteSteerEvent(+ context.Context, string, string, string,+) (bool, error) {+ return false, nil+}++func (m *transcriptStreamManager) SetLiveRun(context.Context, string, string, string) error {+ return nil+}++func (m *transcriptStreamManager) ClaimLiveRun(context.Context, string, string, string) error {+ return nil+}++func (m *transcriptStreamManager) GetLiveRun(context.Context, string) (string, string, error) {+ return "", "", nil+}++func (m *transcriptStreamManager) ClearLiveRun(context.Context, string, string) error {+ return nil+}+func (m *transcriptStreamManager) readKey() string {m.mu.Lock()defer m.mu.Unlock()diff --git a/internal/handler/session/agent_stream_handler.go b/internal/handler/session/agent_stream_handler.goindex d64a26893..77d3d1d97 100644--- a/internal/handler/session/agent_stream_handler.go+++ b/internal/handler/session/agent_stream_handler.go@@ -117,6 +117,7 @@ func (h *AgentStreamHandler) Subscribe() {h.eventBus.On(event.EventAgentReferences, h.handleReferences)h.eventBus.On(event.EventMemoryRecalled, h.handleMemoryRecalled)h.eventBus.On(event.EventContextCompacted, h.handleContextCompacted)+ h.eventBus.On(event.EventUserMessageInjected, h.handleUserMessageInjected)h.eventBus.On(event.EventAgentFinalAnswer, h.handleFinalAnswer)h.eventBus.On(event.EventAgentReflection, h.handleReflection)h.eventBus.On(event.EventError, h.handleError)@@ -646,6 +647,33 @@ func (h *AgentStreamHandler) handleSessionTitle(ctx context.Context, evt event.Ereturn nil}+// handleUserMessageInjected forwards a mid-run message injection to the+// user-visible stream so the frontend can flip its optimistic "queued"+// bubble into a normal message of the running turn. The event carries the+// steer ID the client generated queue time, so correlation is exact.+func (h *AgentStreamHandler) handleUserMessageInjected(_ context.Context, evt event.Event) error {+ data, ok := evt.Data.(event.UserMessageInjectedData)+ if !ok {+ return nil+ }++ if err := h.streamManager.AppendEvent(h.ctx, h.sessionID, h.assistantMessageID, interfaces.StreamEvent{+ ID: evt.ID,+ Type: types.ResponseTypeUserMessageInjected,+ Done: true,+ Timestamp: time.Now(),+ Data: map[string]interface{}{+ "steer_id": data.SteerID,+ "message_id": data.MessageID,+ "content": data.Content,+ "user_message_id": data.UserMessageID,+ },+ }); err != nil {+ logger.GetLogger(h.ctx).Error("Append user message injected event to stream failed", "error", err)+ }+ return nil+}+// handleComplete handles agent complete eventsfunc (h *AgentStreamHandler) handleComplete(ctx context.Context, evt event.Event) error {data, ok := evt.Data.(event.AgentCompleteData)diff --git a/internal/handler/session/continue_stream_resource_urls_test.go b/internal/handler/session/continue_stream_resource_urls_test.goindex f573be242..f8424512f 100644--- a/internal/handler/session/continue_stream_resource_urls_test.go+++ b/internal/handler/session/continue_stream_resource_urls_test.go@@ -58,6 +58,46 @@ func (s *stubStreamManager) GetEvents(return s.events[fromOffset:], len(s.events), nil}+func (s *stubStreamManager) AppendSteerEvents(+ context.Context, string, string, []interfaces.StreamEvent,+) error {+ return nil+}++func (s *stubStreamManager) GetSteerEvents(+ _ context.Context, _, _ string, fromOffset int,+) ([]interfaces.StreamEvent, int, error) {+ return nil, fromOffset, nil+}++func (s *stubStreamManager) UpdateSteerEventData(+ context.Context, string, string, string, map[string]interface{},+) (bool, error) {+ return false, nil+}++func (s *stubStreamManager) DeleteSteerEvent(+ context.Context, string, string, string,+) (bool, error) {+ return false, nil+}++func (s *stubStreamManager) SetLiveRun(context.Context, string, string, string) error {+ return nil+}++func (s *stubStreamManager) ClaimLiveRun(context.Context, string, string, string) error {+ return nil+}++func (s *stubStreamManager) GetLiveRun(context.Context, string) (string, string, error) {+ return "", "", nil+}++func (s *stubStreamManager) ClearLiveRun(context.Context, string, string) error {+ return nil+}+// completedAnswerStream is one assistant turn whose answer embeds a knowledge-base// image, with the resource handle straddling two deltas as it does in production// when the model-context decoder flushes mid-reference.diff --git a/internal/handler/session/qa.go b/internal/handler/session/qa.goindex 1e37fe580..140cf9b21 100644--- a/internal/handler/session/qa.go+++ b/internal/handler/session/qa.go@@ -4,6 +4,7 @@ import ("context""crypto/sha256""encoding/json"+ stderrors "errors""fmt""net/http""os"@@ -19,8 +20,10 @@ import ("github.com/Tencent/WeKnora/internal/event""github.com/Tencent/WeKnora/internal/logger""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"@@ -66,17 +69,34 @@ type qaRequestContext struct {// 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 boolreqAgentID 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}// 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.func (rc *qaRequestContext) buildQARequest() *types.QARequest {imageURLs, imageDescription := extractImageURLsAndOCRText(rc.images)- return &types.QARequest{+ req := &types.QARequest{Session: rc.session,Query: rc.query,AssistantMessageID: rc.assistantMessage.ID,@@ -94,6 +114,10 @@ func (rc *qaRequestContext) buildQARequest() *types.QARequest {WebSearchEnabled: rc.webSearchEnabled,Attachments: rc.attachments,}+ if rc.steerSink != nil {+ req.SteerSink = rc.steerSink+ }+ return req}// parseQARequest parses and validates a QA request, returns the request context@@ -612,22 +636,18 @@ type sseStreamContext struct {asyncCtx context.Contextcancel context.CancelFuncassistantMessage *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}// setupSSEStream sets up the SSE streaming context-func (h *Handler) setupSSEStream(reqCtx *qaRequestContext, generateTitle bool) *sseStreamContext {- // Set SSE headers- setSSEHeaders(reqCtx.c)-- // Write initial agent_query event- h.writeAgentQueryEvent(- reqCtx.ctx,- reqCtx.sessionID,- reqCtx.userMessageID,- reqCtx.userCreatedAt,- reqCtx.assistantMessage,- )-+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 resolutionbaseCtx := reqCtx.ctxif reqCtx.effectiveTenantID != 0 && h.tenantService != nil {@@ -660,7 +680,6 @@ func (h *Handler) setupSSEStream(reqCtx *qaRequestContext, generateTitle bool) *baseCtx = types.ApplyAgentMemoryPreference(baseCtx, reqCtx.customAgent.Config.MemoryEnabled)}- // Create EventBus and cancellable contexteventBus := event.NewEventBus()asyncCtx, cancel := context.WithCancel(logger.CloneContext(baseCtx))@@ -671,6 +690,49 @@ func (h *Handler) setupSSEStream(reqCtx *qaRequestContext, generateTitle bool) *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,+ )+// Setup stop event handlerh.setupStopEventHandler(eventBus, reqCtx.sessionID, reqCtx.session.TenantID, reqCtx.assistantMessage, cancel)@@ -896,6 +958,99 @@ const (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.query,+ 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")+}+// 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) {@@ -909,6 +1064,17 @@ func (h *Handler) executeQA(reqCtx *qaRequestContext, mode qaMode, generateTitle// client disconnect doesn't drop the write.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+ }+ }+// Agent mode: emit agent query event before message creationif mode == qaModeAgent {if err := event.Emit(ctx, event.Event{@@ -926,27 +1092,19 @@ func (h *Handler) executeQA(reqCtx *qaRequestContext, mode qaMode, generateTitle}}+ 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.- userMessageAttachments := reqCtx.attachments- if len(reqCtx.attachmentMetas) > 0 {- userMessageAttachments = append(append(types.MessageAttachments{}, reqCtx.attachments...), reqCtx.attachmentMetas...)- }- userMsg, err := h.createUserMessage(ctx, sessionID, reqCtx.query, reqCtx.requestID, reqCtx.mentionedItems, convertImageAttachments(reqCtx.images), userMessageAttachments, reqCtx.channel, reqCtx.suggestionAttribution)- if err != nil {- reqCtx.c.Error(errors.NewInternalServerError(err.Error()))- return- }- reqCtx.userMessageID = userMsg.ID- reqCtx.userCreatedAt = userMsg.CreatedAt-- // Create assistant message- assistantMessagePtr, err := h.createAssistantMessage(ctx, reqCtx.assistantMessage)- if err != nil {- reqCtx.c.Error(errors.NewInternalServerError(err.Error()))+ if err := h.persistTurnMessages(ctx, reqCtx); err != nil {+ 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}- reqCtx.assistantMessage = assistantMessagePtrif mode == qaModeNormal {logger.Infof(ctx, "Using knowledge bases: %v", reqCtx.knowledgeBaseIDs)@@ -954,8 +1112,34 @@ func (h *Handler) executeQA(reqCtx *qaRequestContext, mode qaMode, generateTitlelogger.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)+ streamCtx := h.setupSSEStream(reqCtx, generateTitle, mode)+ if streamCtx.liveRunFailed {+ if streamCtx.cancel != nil {+ streamCtx.cancel()+ }+ 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)@@ -1009,7 +1193,9 @@ func (h *Handler) executeQA(reqCtx *qaRequestContext, mode qaMode, generateTitle}// Execute QA asynchronously+ asyncDone := make(chan struct{})go func() {+ defer close(asyncDone)defer func() {if r := recover(); r != nil {buf := make([]byte, 10240)@@ -1033,7 +1219,40 @@ func (h *Handler) executeQA(reqCtx *qaRequestContext, mode qaMode, generateTitlecontext.WithoutCancel(streamCtx.asyncCtx),types.TenantIDContextKey, reqCtx.session.TenantID,)- h.completeAssistantMessage(updateCtx, streamCtx.assistantMessage, reqCtx.query, reqCtx.userMessageID)++ // 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.completeAssistantMessage(+ updateCtx, streamCtx.assistantMessage, reqCtx.query, reqCtx.userMessageID,+ )+ } else {+ kicked := h.kickNextRunFromSteerBacklog(updateCtx, reqCtx, streamCtx)+ h.completeAssistantMessage(+ updateCtx, streamCtx.assistantMessage, 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)}}()@@ -1080,6 +1299,11 @@ func (h *Handler) executeQA(reqCtx *qaRequestContext, mode qaMode, generateTitle}}()+ if reqCtx.skipSSE {+ <-asyncDone+ return+ }+// Handle SSE events (blocking)shouldWaitForTitle := generateTitle && reqCtx.session.Title == ""h.handleAgentEventsForSSE(ctx, reqCtx.c, sessionID, reqCtx.assistantMessage.ID,diff --git a/internal/handler/session/steer.go b/internal/handler/session/steer.gonew file mode 100644index 000000000..bef55be53--- /dev/null+++ b/internal/handler/session/steer.go@@ -0,0 +1,1059 @@+package session++import (+ "context"+ "fmt"+ "strings"+ "sync"+ "time"++ "github.com/Tencent/WeKnora/internal/errors"+ "github.com/Tencent/WeKnora/internal/logger"+ "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"+)++// Delivery modes for a mid-run user message. Chosen at send time.+const (+ // steerDeliveryInject is drained into the running turn at the next+ // round boundary (and again just before a natural stop, so the agent+ // continues instead of finishing).+ steerDeliveryInject = "inject"+ // steerDeliveryAfter stays in the queue until the current run exits,+ // then becomes the query (or carry-over) of a follow-up run.+ steerDeliveryAfter = "after"+)++// steerDataConsumed marks a steer event the running turn has already taken+// into its message list. It lives on the event itself (not in process memory)+// so every replica agrees on what is still pending: the overlay, the queue+// depth guard and the follow-up backlog all read the same flag.+const steerDataConsumed = "consumed"++// steerDataUserMessageID is the persisted user-row ID written alongside the+// consumed flag so a retried drain can reuse the row instead of inserting again.+const steerDataUserMessageID = "user_message_id"++// SteerMessageRequest is the payload of POST /sessions/:session_id/steer.+type SteerMessageRequest struct {+ Query string `json:"query" binding:"required"`+ MentionedItems []MentionedItemRequest `json:"mentioned_items,omitempty"`+ Channel string `json:"channel,omitempty"`+ // Delivery is "after" (default) or "inject". See the constants above.+ Delivery string `json:"delivery,omitempty"`+}++// Steer request limits. maxSteerQueueDepth bounds how many messages a single+// run can accumulate — past that the run is clearly ignoring its user and the+// honest answer is to refuse instead of queueing silently.+const (+ maxSteerQueueDepth = 10+ maxSteerQueryLength = 10000+ steerDrainBatchLimit = 20+)++// steerSink implements types.SteerSink on the handler side: it reads the+// steer sub-list through the shared StreamManager and persists accepted+// messages as user-role rows under the run's request ID. Constructed per run+// in setupSSEStream and handed to the engine via SetSteerSink.+type steerSink struct {+ ctx context.Context+ sessionID string+ requestID string+ assistantMessage *types.Message+ messageService interfaces.MessageService+ streamManager interfaces.StreamManager++ mu sync.Mutex+ lastUserMessageID string+ drainedOffset int+ injectedIDs map[string]struct{}+}++func newSteerSink(+ ctx context.Context,+ sessionID, requestID string,+ assistantMessage *types.Message,+ messageService interfaces.MessageService,+ streamManager interfaces.StreamManager,+) *steerSink {+ return &steerSink{+ ctx: ctx,+ sessionID: sessionID,+ requestID: requestID,+ assistantMessage: assistantMessage,+ messageService: messageService,+ streamManager: streamManager,+ injectedIDs: make(map[string]struct{}),+ }+}++// PollSteer drains the steer sub-list and returns plain maps so the shape+// matches types.SteerSink without the agent package importing interfaces.+// Satisfies types.SteerSink.+func (s *steerSink) PollSteer(+ ctx context.Context, sessionID, messageID string, lastOffset int,+) ([]map[string]interface{}, int, error) {+ // Always read from the start so an after→inject promote of an already+ // skipped event is visible on the next drain. Consumed injects are+ // filtered by injectedIDs rather than offset.+ _ = lastOffset+ events, total, err := s.streamManager.GetSteerEvents(ctx, sessionID, messageID, 0)+ if err != nil {+ return nil, lastOffset, err+ }+ out := make([]map[string]interface{}, 0)+ for _, evt := range events {+ if steerDeliveryOfEvent(evt) == steerDeliveryAfter {+ continue+ }+ if s.hasInjected(evt.ID) || steerEventConsumed(evt) {+ continue+ }+ if len(out) >= steerDrainBatchLimit {+ break+ }+ s.markInjected(evt.ID)+ out = append(out, steerEventToRaw(evt))+ }+ s.mu.Lock()+ if total > s.drainedOffset {+ s.drainedOffset = total+ }+ s.mu.Unlock()+ return out, total, nil+}++func (s *steerSink) hasInjected(id string) bool {+ if id == "" {+ return false+ }+ s.mu.Lock()+ defer s.mu.Unlock()+ _, ok := s.injectedIDs[id]+ return ok+}++func (s *steerSink) markInjected(id string) {+ if id == "" {+ return+ }+ s.mu.Lock()+ defer s.mu.Unlock()+ if s.injectedIDs == nil {+ s.injectedIDs = make(map[string]struct{})+ }+ s.injectedIDs[id] = struct{}{}+}++func (s *steerSink) unmarkInjected(id string) {+ if id == "" {+ return+ }+ s.mu.Lock()+ defer s.mu.Unlock()+ delete(s.injectedIDs, id)+}++// InjectedIDs is a copy of steer event IDs the engine has already consumed.+func (s *steerSink) InjectedIDs() map[string]struct{} {+ s.mu.Lock()+ defer s.mu.Unlock()+ out := make(map[string]struct{}, len(s.injectedIDs))+ for id := range s.injectedIDs {+ out[id] = struct{}{}+ }+ return out+}++// DrainedOffset is retained for tests. Production teardown uses consumed+// flags plus InjectedIDs, not a numeric offset.+func (s *steerSink) DrainedOffset() int {+ s.mu.Lock()+ defer s.mu.Unlock()+ return s.drainedOffset+}++// steerEventToRaw flattens a StreamEvent into the map shape PollSteer returns.+func steerEventToRaw(evt interfaces.StreamEvent) map[string]interface{} {+ raw := map[string]interface{}{+ "id": evt.ID,+ "content": evt.Content,+ }+ if m, ok := evt.Data["mentioned_items"].([]interface{}); ok {+ raw["mentioned_items"] = m+ }+ if ch, ok := evt.Data["channel"].(string); ok {+ raw["channel"] = ch+ }+ if d, ok := evt.Data["delivery"].(string); ok {+ raw["delivery"] = d+ }+ return raw+}++// PersistSteerMessage stores the accepted steer as a normal user message row+// carrying the run's request ID, so history replay (LoadAgentHistory) places+// it inside this turn and the next turn's LLM context includes it. Satisfies+// types.SteerSink.+//+// Mentions are stored for display and for the next turn only. The running+// turn's tool, KB and skill scope was resolved when it started and is not+// widened mid-flight — @-ing a knowledge base in a steered message does not+// hand the in-flight agent a new retriever.+func (s *steerSink) PersistSteerMessage(+ ctx context.Context, sessionID, messageID, steerID, content string,+ mentionedItems types.MentionedItems,+ channel string,+) string {+ if s.messageService == nil {+ s.unmarkInjected(steerID)+ return ""+ }+ if existing := s.persistedUserMessageID(ctx, sessionID, messageID, steerID); existing != "" {+ s.mu.Lock()+ s.lastUserMessageID = existing+ s.mu.Unlock()+ return existing+ }+ if strings.TrimSpace(channel) == "" {+ channel = "web"+ }+ msg, err := s.messageService.CreateMessage(ctx, &types.Message{+ SessionID: sessionID,+ Role: "user",+ Content: content,+ RequestID: s.requestID,+ MentionedItems: mentionedItems,+ CreatedAt: time.Now(),+ IsCompleted: true,+ Channel: channel,+ })+ if err != nil {+ logger.ErrorWithFields(ctx, err, map[string]interface{}{+ "session_id": sessionID,+ "steer_id": steerID,+ })+ s.unmarkInjected(steerID)+ return ""+ }+ updated, err := s.streamManager.UpdateSteerEventData(ctx, sessionID, messageID, steerID,+ map[string]interface{}{+ steerDataConsumed: true,+ steerDataUserMessageID: msg.ID,+ })+ if err != nil {+ logger.Warnf(ctx, "steer consume flag failed for session %s steer %s: %v",+ sessionID, steerID, err)+ }+ if !updated {+ // Deleted concurrently, or the CAS gave up. The user row must not+ // stay around for a retry to insert a second copy of the same steer.+ if delErr := s.messageService.DeleteMessage(ctx, sessionID, msg.ID); delErr != nil {+ logger.Warnf(ctx, "steer persist rollback failed for session %s message %s: %v",+ sessionID, msg.ID, delErr)+ }+ s.unmarkInjected(steerID)+ if existing := s.persistedUserMessageID(ctx, sessionID, messageID, steerID); existing != "" {+ s.mu.Lock()+ s.lastUserMessageID = existing+ s.mu.Unlock()+ return existing+ }+ return ""+ }+ s.mu.Lock()+ s.lastUserMessageID = msg.ID+ s.mu.Unlock()+ return msg.ID+}++func (s *steerSink) persistedUserMessageID(ctx context.Context, sessionID, messageID, steerID string) string {+ if s.streamManager == nil || steerID == "" {+ return ""+ }+ events, _, err := s.streamManager.GetSteerEvents(ctx, sessionID, messageID, 0)+ if err != nil {+ return ""+ }+ for _, evt := range events {+ if evt.ID == steerID {+ return getString(evt.Data, steerDataUserMessageID)+ }+ }+ return ""+}++// LastPersistedUserMessageID exposes the ID of the most recently persisted+// steer row so the injected event can carry it for frontend correlation.+func (s *steerSink) LastPersistedUserMessageID() string {+ s.mu.Lock()+ defer s.mu.Unlock()+ return s.lastUserMessageID+}++// liveAgentRun resolves which assistant message is currently generating for a+// session, or "" when none is. The marker lives in the shared StreamManager+// rather than in process memory, mirroring how stop events are coordinated:+// a mid-run send that lands on a different replica must find the same run,+// otherwise it would report "no run is live" and the client would start a+// second turn on top of the first.+//+// Because the marker can outlive its process (a TTL'd key, not a map that+// dies with the goroutine), it is verified against the assistant row before+// use. A completed message means the run is over and the caller should start+// a new turn rather than queue into a list nobody will drain.+//+// Lookup failures are returned as errors, not as "". Collapsing a Redis or+// database blip into "no live run" is exactly the duplicate-turn path above:+// SteerMessage would answer new_run and the client would POST a second AgentQA+// while the first is still generating.+func (h *Handler) liveAgentRun(ctx context.Context, sessionID string) (string, error) {+ assistantID, _, err := h.streamManager.GetLiveRun(ctx, sessionID)+ if err != nil {+ return "", err+ }+ if assistantID == "" {+ return "", nil+ }++ msg, err := h.messageService.GetMessage(ctx, sessionID, assistantID)+ if err != nil {+ return "", err+ }+ if msg == nil || msg.IsCompleted {+ if err := h.streamManager.ClearLiveRun(ctx, sessionID, assistantID); err != nil {+ logger.Warnf(ctx, "stale live run cleanup failed for session %s: %v", sessionID, err)+ }+ return "", nil+ }+ return assistantID, nil+}++// resolveLiveAgentRun is the HTTP wrapper around liveAgentRun: a lookup+// failure becomes a retryable 503 so the client toasts instead of starting+// a second turn. ok is false when the handler has already written the error.+func (h *Handler) resolveLiveAgentRun(ctx context.Context, c *gin.Context, sessionID string) (string, bool) {+ assistantID, err := h.liveAgentRun(ctx, sessionID)+ if err != nil {+ logger.ErrorWithFields(ctx, err, map[string]interface{}{"session_id": sessionID})+ _ = c.Error(errors.NewServiceUnavailableError("Failed to look up running turn"))+ return "", false+ }+ return assistantID, true+}++// steerEvent is one queued user message as stored in the StreamManager+// sub-list. Data keys mirror what the injected user_message_injected event+// carries so consumers can correlate queue → injection.+func steerEvent(id, query string, mentionedItems types.MentionedItems, channel string) interfaces.StreamEvent {+ return interfaces.StreamEvent{+ ID: id,+ Type: types.ResponseTypeSteer,+ Content: query,+ Done: true,+ Data: map[string]interface{}{+ "steer_id": id,+ "channel": channel,+ "delivery": steerDeliveryInject,+ "mentioned_items": mentionedItemsToRaw(mentionedItems),+ },+ }+}++// parseSteerDelivery defaults to "after". Queueing until the current turn+// finishes is the conservative reading of "the user sent another message":+// interrupting a running agent is the explicit opt-in, so a client that omits+// the field never lands mid-turn by accident.+func parseSteerDelivery(s string) (string, error) {+ switch strings.ToLower(strings.TrimSpace(s)) {+ case "", steerDeliveryAfter:+ return steerDeliveryAfter, nil+ case steerDeliveryInject:+ return steerDeliveryInject, nil+ default:+ return "", fmt.Errorf("invalid delivery %q (want inject or after)", s)+ }+}++func steerDeliveryOfEvent(evt interfaces.StreamEvent) string {+ if getString(evt.Data, "delivery") == steerDeliveryAfter {+ return steerDeliveryAfter+ }+ return steerDeliveryInject+}++// steerEventConsumed reports whether the running turn already took this event+// into its message list.+func steerEventConsumed(evt interfaces.StreamEvent) bool {+ consumed, _ := evt.Data[steerDataConsumed].(bool)+ return consumed+}++// selectSteerBacklog is the teardown drain: every event the engine has not+// yet consumed as an inject. After events (never consumed) and inject events+// that arrived too late both belong here; consumed events do not.+//+// injectedIDs is the in-flight run's own view, which can be a beat ahead of+// the durable flag; both are checked so a message is never injected twice.+func selectSteerBacklog(events []interfaces.StreamEvent, injectedIDs map[string]struct{}) []interfaces.StreamEvent {+ out := make([]interfaces.StreamEvent, 0)+ for _, evt := range events {+ if steerEventConsumed(evt) {+ continue+ }+ if _, ok := injectedIDs[evt.ID]; ok {+ continue+ }+ out = append(out, evt)+ }+ return out+}++// pendingSteerQueueItems is the overlay restore payload: every steer event+// the live run has not yet consumed as an inject. After events always appear;+// inject events drop out once PollSteer marked them.+func pendingSteerQueueItems(events []interfaces.StreamEvent, injectedIDs map[string]struct{}) []map[string]interface{} {+ pending := selectSteerBacklog(events, injectedIDs)+ out := make([]map[string]interface{}, 0, len(pending))+ for _, evt := range pending {+ item := map[string]interface{}{+ "steer_id": evt.ID,+ "content": evt.Content,+ "delivery": steerDeliveryOfEvent(evt),+ }+ if m, ok := evt.Data["mentioned_items"]; ok && m != nil {+ item["mentioned_items"] = m+ }+ out = append(out, item)+ }+ return out+}++// mentionedItemsToRaw converts typed mentions into plain values that survive+// Redis JSON round-trips without a second unmarshal type on the read side.+func mentionedItemsToRaw(items types.MentionedItems) []interface{} {+ return types.MentionedItemsToRaw(items)+}++// SteerMessage godoc+// @Summary 向运行中的对话追加消息+// @Description 向运行中的 agent turn 追加用户消息(after 排队 / inject 注入)。无活 turn 时返回 new_run。+// @Tags 问答+// @Accept json+// @Produce json+// @Param session_id path string true "会话 ID"+// @Param request body SteerMessageRequest true "追加消息"+// @Success 200 {object} map[string]interface{} "queued | new_run"+// @Failure 400 {object} errors.AppError "请求参数错误"+// @Failure 404 {object} errors.AppError "会话不存在"+// @Failure 503 {object} errors.AppError "活 turn 查询失败,可重试"+// @Security Bearer+// @Security ApiKeyAuth+// @Router /sessions/{session_id}/steer [post]+func (h *Handler) SteerMessage(c *gin.Context) {+ ctx := logger.CloneContext(c.Request.Context())+ sessionID := secutils.SanitizeForLog(c.Param("session_id"))+ if sessionID == "" {+ _ = c.Error(errors.NewBadRequestError(errors.ErrInvalidSessionID.Error()))+ return+ }++ var req SteerMessageRequest+ if err := c.ShouldBindJSON(&req); err != nil {+ logger.ErrorWithFields(ctx, err, map[string]interface{}{"session_id": sessionID})+ _ = c.Error(errors.NewBadRequestError(err.Error()))+ return+ }+ query := strings.TrimSpace(req.Query)+ if query == "" {+ _ = c.Error(errors.NewBadRequestError("query must not be empty"))+ return+ }+ if len([]rune(query)) > maxSteerQueryLength {+ _ = c.Error(errors.NewBadRequestError("query too long"))+ return+ }+ delivery, err := parseSteerDelivery(req.Delivery)+ if err != nil {+ _ = c.Error(errors.NewBadRequestError(err.Error()))+ return+ }++ // Same ownership scope as StopSession: steer mutates an in-flight turn, so+ // use the strict owner scope and reject cross-tenant access.+ if _, err := h.sessionService.GetOwnedSession(ctx, sessionID); err != nil {+ logger.ErrorWithFields(ctx, err, map[string]interface{}{"session_id": sessionID})+ _ = c.Error(errors.NewNotFoundError("Session not found"))+ return+ }++ assistantID, ok := h.resolveLiveAgentRun(ctx, c, sessionID)+ if !ok {+ return+ }+ if assistantID == "" {+ // No run is live: the message starts a brand-new run via the normal+ // AgentQA path. The request returns immediately and the SSE stream+ // for the new turn is opened by the client's next agent-chat call.+ c.JSON(200, gin.H{"success": true, "status": "new_run"})+ return+ }++ // Queue depth guard: refuse rather than silently accumulate. Only pending+ // messages count — a turn that already absorbed ten injects still has an+ // empty overlay, so charging the user for them would refuse a send with+ // nothing on screen to explain it.+ existing, _, err := h.streamManager.GetSteerEvents(ctx, sessionID, assistantID, 0)+ if err != nil {+ logger.ErrorWithFields(ctx, err, map[string]interface{}{"session_id": sessionID})+ _ = c.Error(errors.NewInternalServerError("Failed to check steer queue"))+ return+ }+ pending := len(selectSteerBacklog(existing, nil))+ if pending >= maxSteerQueueDepth {+ _ = c.Error(errors.NewBadRequestError("too many queued messages for the running turn"))+ return+ }++ steerID := uuid.New().String()+ evt := steerEvent(steerID, query, convertMentionedItems(req.MentionedItems), req.Channel)+ evt.Data["delivery"] = delivery+ if err := h.streamManager.AppendSteerEvents(ctx, sessionID, assistantID,+ []interfaces.StreamEvent{evt}); err != nil {+ logger.ErrorWithFields(ctx, err, map[string]interface{}{"session_id": sessionID})+ _ = c.Error(errors.NewInternalServerError("Failed to queue message"))+ return+ }++ queuedOn, status, err := h.rebindSteerIfLiveRunMoved(ctx, sessionID, assistantID, evt)+ if err != nil {+ logger.ErrorWithFields(ctx, err, map[string]interface{}{"session_id": sessionID})+ _ = c.Error(errors.NewInternalServerError("Failed to queue message"))+ return+ }+ if status == "new_run" {+ c.JSON(200, gin.H{"success": true, "status": "new_run"})+ return+ }++ logger.Infof(ctx, "Steer message queued for session=%s run=%s steer_id=%s delivery=%s queue_len=%d",+ sessionID, queuedOn, steerID, delivery, pending+1)++ c.JSON(200, gin.H{+ "success": true,+ "status": "queued",+ "steer_id": steerID,+ "delivery": delivery,+ "assistant_message_id": queuedOn,+ })+}++// PromoteSteerMessage godoc+// @Summary 将排队消息改为立即注入+// @Description 把一条 delivery=after 的排队消息改为 inject,运行中的 agent 会在下一轮边界读到它。+// @Tags 问答+// @Produce json+// @Param session_id path string true "会话 ID"+// @Param steer_id path string true "排队消息 ID"+// @Success 200 {object} map[string]interface{} "queued | new_run"+// @Failure 400 {object} errors.AppError+// @Failure 404 {object} errors.AppError+// @Failure 503 {object} errors.AppError "活 turn 查询失败,可重试"+// @Security Bearer+// @Security ApiKeyAuth+// @Router /sessions/{session_id}/steer/{steer_id}/inject [post]+func (h *Handler) PromoteSteerMessage(c *gin.Context) {+ ctx := logger.CloneContext(c.Request.Context())+ sessionID := secutils.SanitizeForLog(c.Param("session_id"))+ steerID := c.Param("steer_id")+ if sessionID == "" || steerID == "" {+ _ = c.Error(errors.NewBadRequestError(errors.ErrInvalidSessionID.Error()))+ return+ }++ if _, err := h.sessionService.GetOwnedSession(ctx, sessionID); err != nil {+ logger.ErrorWithFields(ctx, err, map[string]interface{}{"session_id": sessionID})+ _ = c.Error(errors.NewNotFoundError("Session not found"))+ return+ }++ assistantID, ok := h.resolveLiveAgentRun(ctx, c, sessionID)+ if !ok {+ return+ }+ if assistantID == "" {+ c.JSON(200, gin.H{"success": true, "status": "new_run"})+ return+ }++ events, _, err := h.streamManager.GetSteerEvents(ctx, sessionID, assistantID, 0)+ if err != nil {+ logger.ErrorWithFields(ctx, err, map[string]interface{}{"session_id": sessionID})+ _ = c.Error(errors.NewInternalServerError("Failed to update queued message"))+ return+ }+ for _, evt := range events {+ if evt.ID == steerID && steerEventConsumed(evt) {+ c.JSON(200, gin.H{+ "success": true,+ "status": "already_injected",+ "steer_id": steerID,+ })+ return+ }+ }++ updated, err := h.streamManager.UpdateSteerEventData(ctx, sessionID, assistantID, steerID,+ map[string]interface{}{"delivery": steerDeliveryInject})+ if err != nil {+ logger.ErrorWithFields(ctx, err, map[string]interface{}{+ "session_id": sessionID,+ "steer_id": steerID,+ })+ _ = c.Error(errors.NewInternalServerError("Failed to update queued message"))+ return+ }+ if !updated {+ _ = c.Error(errors.NewNotFoundError("Queued message not found"))+ return+ }++ logger.Infof(ctx, "Steer message promoted to inject session=%s run=%s steer_id=%s",+ sessionID, assistantID, steerID)+ c.JSON(200, gin.H{+ "success": true,+ "status": "queued",+ "steer_id": steerID,+ "delivery": steerDeliveryInject,+ "assistant_message_id": assistantID,+ })+}++// ListSteerMessages godoc+// @Summary 列出当前运行中尚未消费的排队消息+// @Description 刷新页面后用来恢复输入框上方的队列。没有正在运行的 turn 时返回空列表。+// @Tags 问答+// @Produce json+// @Param id path string true "会话 ID"+// @Success 200 {object} map[string]interface{}+// @Failure 404 {object} errors.AppError+// @Failure 503 {object} errors.AppError "活 turn 查询失败,可重试"+// @Security Bearer+// @Security ApiKeyAuth+// @Router /sessions/{id}/steer [get]+func (h *Handler) ListSteerMessages(c *gin.Context) {+ ctx := logger.CloneContext(c.Request.Context())+ sessionID := secutils.SanitizeForLog(c.Param("id"))+ if sessionID == "" {+ sessionID = secutils.SanitizeForLog(c.Param("session_id"))+ }+ if sessionID == "" {+ _ = c.Error(errors.NewBadRequestError(errors.ErrInvalidSessionID.Error()))+ return+ }++ if _, err := h.sessionService.GetOwnedSession(ctx, sessionID); err != nil {+ logger.ErrorWithFields(ctx, err, map[string]interface{}{"session_id": sessionID})+ _ = c.Error(errors.NewNotFoundError("Session not found"))+ return+ }++ assistantID, ok := h.resolveLiveAgentRun(ctx, c, sessionID)+ if !ok {+ return+ }+ if assistantID == "" {+ c.JSON(200, gin.H{"success": true, "items": []map[string]interface{}{}})+ return+ }++ events, _, err := h.streamManager.GetSteerEvents(ctx, sessionID, assistantID, 0)+ if err != nil {+ logger.ErrorWithFields(ctx, err, map[string]interface{}{"session_id": sessionID})+ _ = c.Error(errors.NewInternalServerError("Failed to load queued messages"))+ return+ }++ c.JSON(200, gin.H{+ "success": true,+ "assistant_message_id": assistantID,+ "items": pendingSteerQueueItems(events, nil),+ })+}++// DeleteSteerMessage godoc+// @Summary 删除一条排队中的消息+// @Description 从当前运行的排队列表里去掉一条,不再注入也不再作为 follow-up 发出。+// @Tags 问答+// @Produce json+// @Param id path string true "会话 ID"+// @Param steer_id path string true "排队消息 ID"+// @Success 200 {object} map[string]interface{}+// @Failure 404 {object} errors.AppError+// @Failure 503 {object} errors.AppError "活 turn 查询失败,可重试"+// @Security Bearer+// @Security ApiKeyAuth+// @Router /sessions/{id}/steer/{steer_id} [delete]+func (h *Handler) DeleteSteerMessage(c *gin.Context) {+ ctx := logger.CloneContext(c.Request.Context())+ sessionID := secutils.SanitizeForLog(c.Param("id"))+ if sessionID == "" {+ sessionID = secutils.SanitizeForLog(c.Param("session_id"))+ }+ steerID := c.Param("steer_id")+ if sessionID == "" || steerID == "" {+ _ = c.Error(errors.NewBadRequestError(errors.ErrInvalidSessionID.Error()))+ return+ }++ if _, err := h.sessionService.GetOwnedSession(ctx, sessionID); err != nil {+ logger.ErrorWithFields(ctx, err, map[string]interface{}{"session_id": sessionID})+ _ = c.Error(errors.NewNotFoundError("Session not found"))+ return+ }++ assistantID, ok := h.resolveLiveAgentRun(ctx, c, sessionID)+ if !ok {+ return+ }+ if assistantID == "" {+ c.JSON(200, gin.H{"success": true, "status": "gone"})+ return+ }++ // A message the engine already took cannot be unsent — it is in the+ // model's context. Say so instead of reporting a delete that did not+ // change what the agent saw.+ events, _, err := h.streamManager.GetSteerEvents(ctx, sessionID, assistantID, 0)+ if err != nil {+ logger.ErrorWithFields(ctx, err, map[string]interface{}{"session_id": sessionID})+ _ = c.Error(errors.NewInternalServerError("Failed to delete queued message"))+ return+ }+ for _, evt := range events {+ if evt.ID == steerID && steerEventConsumed(evt) {+ c.JSON(200, gin.H{+ "success": true,+ "status": "already_injected",+ "removed": false,+ "steer_id": steerID,+ })+ return+ }+ }++ ok, err = h.streamManager.DeleteSteerEvent(ctx, sessionID, assistantID, steerID)+ if err != nil {+ logger.ErrorWithFields(ctx, err, map[string]interface{}{+ "session_id": sessionID,+ "steer_id": steerID,+ })+ _ = c.Error(errors.NewInternalServerError("Failed to delete queued message"))+ return+ }++ c.JSON(200, gin.H{+ "success": true,+ "status": "deleted",+ "removed": ok,+ "steer_id": steerID,+ })+}++// discardSteerBacklog marks every still-pending steer message consumed+// without running any of it. This is the stop path: the user asked the agent+// to stop, and quietly starting a fresh run with the text they had queued is+// the opposite of stopping. Marking (rather than deleting) keeps the events+// around for the run's own audit trail while taking them out of the overlay,+// the depth budget and any follow-up handoff.+func (h *Handler) discardSteerBacklog(+ ctx context.Context,+ sessionID, assistantMessageID string,+ injected map[string]struct{},+) {+ all, _, err := h.streamManager.GetSteerEvents(ctx, sessionID, assistantMessageID, 0)+ if err != nil {+ logger.Warnf(ctx, "steer backlog read failed for session %s: %v", sessionID, err)+ return+ }+ backlog := selectSteerBacklog(all, injected)+ if len(backlog) == 0 {+ return+ }+ h.markSteerEventsConsumed(ctx, sessionID, assistantMessageID, backlog)+ if lateAll, _, err := h.streamManager.GetSteerEvents(ctx, sessionID, assistantMessageID, 0); err != nil {+ logger.Warnf(ctx, "steer discard sweep failed for session %s: %v", sessionID, err)+ } else if late := selectSteerBacklog(lateAll, injected); len(late) > 0 {+ h.markSteerEventsConsumed(ctx, sessionID, assistantMessageID, late)+ backlog = append(backlog, late...)+ }+ logger.Infof(ctx, "Discarded %d queued steer message(s) after stop, session=%s",+ len(backlog), sessionID)+}++// kickNextRunFromSteerBacklog drains steer messages that arrived after the+// loop could no longer inject them (final answer already streaming, max+// iterations reached, or a user stop) and starts a follow-up run with the+// first message as its query. Remaining messages stay queued on the NEW run's+// steer sub-list, so the follow-up run injects them at its own round+// boundaries.+//+// The follow-up is published as the session's live run before this function+// returns, so the finished run's subsequent ClearLiveRun cannot open a+// window where POST /steer answers new_run. executeQA is started afterwards+// and skips message creation that claimNextSteerFollowUp already did.+//+// Runs on the executeQA teardown path with a WithoutCancel context, so a+// user-initiated stop doesn't cancel the follow-up run.+func (h *Handler) kickNextRunFromSteerBacklog(+ ctx context.Context,+ prevReqCtx *qaRequestContext,+ prevStreamCtx *sseStreamContext,+) bool {+ followUp, ok := h.claimNextSteerFollowUp(ctx, prevReqCtx, prevStreamCtx)+ if !ok {+ followUp, ok = h.claimNextSteerFollowUp(ctx, prevReqCtx, prevStreamCtx)+ }+ if !ok {+ return false+ }++ go func() {+ defer func() {+ if r := recover(); r != nil {+ logger.Errorf(ctx, "steer follow-up run panicked: %v", r)+ }+ }()+ h.executeQA(followUp, qaModeAgent, false)+ }()+ return true+}++// claimNextSteerFollowUp persists the follow-up turn and SetLiveRun's it so+// the session is never unmarked between the previous run exiting and the+// next engine loop starting. Returns false when there is nothing to hand off.+func (h *Handler) claimNextSteerFollowUp(+ ctx context.Context,+ prevReqCtx *qaRequestContext,+ prevStreamCtx *sseStreamContext,+) (*qaRequestContext, bool) {+ prevMessageID := prevStreamCtx.assistantMessage.ID++ all, _, err := h.streamManager.GetSteerEvents(ctx, prevReqCtx.sessionID, prevMessageID, 0)+ if err != nil {+ logger.Warnf(ctx, "steer backlog read failed for session %s: %v", prevReqCtx.sessionID, err)+ return nil, false+ }+ injected := map[string]struct{}{}+ if prevStreamCtx.steerSink != nil {+ injected = prevStreamCtx.steerSink.InjectedIDs()+ }+ backlog := selectSteerBacklog(all, injected)+ if len(backlog) == 0 {+ if lateAll, _, lateErr := h.streamManager.GetSteerEvents(+ ctx, prevReqCtx.sessionID, prevMessageID, 0,+ ); lateErr == nil {+ backlog = selectSteerBacklog(lateAll, injected)+ }+ if len(backlog) == 0 {+ return nil, false+ }+ }++ first := backlog[0]+ rest := backlog[1:]++ logger.Infof(ctx, "Steer backlog detected after run completion, session=%s, count=%d, injected=%d",+ prevReqCtx.sessionID, len(backlog), len(injected))++ followUp := *prevReqCtx+ followUp.ctx = ctx+ followUp.query = first.Content+ followUp.requestID = uuid.New().String()+ followUp.channel = getString(first.Data, "channel")+ if followUp.channel == "" {+ followUp.channel = "web"+ }+ h.applyFollowUpMentions(ctx, &followUp, first.Data["mentioned_items"])+ followUp.assistantMessage = &types.Message{+ SessionID: prevReqCtx.sessionID,+ Role: "assistant",+ IsCompleted: false,+ RequestID: followUp.requestID,+ CreatedAt: time.Now(),+ }+ followUp.suggestionAttribution = nil+ followUp.userMessageID = ""+ followUp.steerSink = nil+ followUp.images = nil+ followUp.attachments = nil+ followUp.attachmentIDs = nil+ followUp.attachmentMetas = nil+ followUp.skipSSE = true+ followUp.steerCarryOver = rest++ if err := h.persistTurnMessages(ctx, &followUp); err != nil {+ logger.ErrorWithFields(ctx, err, map[string]interface{}{+ "session_id": prevReqCtx.sessionID,+ })+ h.rollbackTurnMessages(ctx, &followUp, true, true)+ return nil, false+ }+ if followUp.assistantMessage == nil || followUp.assistantMessage.ID == "" {+ h.rollbackTurnMessages(ctx, &followUp, true, true)+ return nil, false+ }+ if err := h.streamManager.ClaimLiveRun(+ ctx, followUp.sessionID, followUp.assistantMessage.ID, followUp.requestID,+ ); err != nil {+ logger.ErrorWithFields(ctx, err, map[string]interface{}{+ "session_id": followUp.sessionID,+ })+ h.rollbackTurnMessages(ctx, &followUp, true, true)+ return nil, false+ }++ h.markSteerEventsConsumed(ctx, prevReqCtx.sessionID, prevMessageID, backlog)++ // A send that landed on A while we persisted still sits on A's list.+ // Sweep it onto B now that B is the live run.+ if lateAll, _, err := h.streamManager.GetSteerEvents(ctx, prevReqCtx.sessionID, prevMessageID, 0); err != nil {+ logger.Warnf(ctx, "steer late-handoff read failed for session %s: %v", prevReqCtx.sessionID, err)+ } else if late := selectSteerBacklog(lateAll, injected); len(late) > 0 {+ h.markSteerEventsConsumed(ctx, prevReqCtx.sessionID, prevMessageID, late)+ followUp.steerCarryOver = append(followUp.steerCarryOver, late...)+ }++ if len(followUp.steerCarryOver) > 0 {+ if err := h.streamManager.AppendSteerEvents(+ ctx, followUp.sessionID, followUp.assistantMessage.ID, followUp.steerCarryOver,+ ); err != nil {+ logger.Warnf(ctx, "steer carry-over append failed for session %s: %v", followUp.sessionID, err)+ } else {+ followUp.steerCarryOver = nil+ }+ }+ return &followUp, true+}++func (h *Handler) markSteerEventsConsumed(+ ctx context.Context, sessionID, assistantID string, events []interfaces.StreamEvent,+) {+ for _, evt := range events {+ if _, err := h.streamManager.UpdateSteerEventData(ctx, sessionID, assistantID, evt.ID,+ map[string]interface{}{steerDataConsumed: true}); err != nil {+ logger.Warnf(ctx, "steer consume flag failed for session %s steer %s: %v",+ sessionID, evt.ID, err)+ }+ }+}++// rebindSteerIfLiveRunMoved moves an event that landed on a run that has+// already handed off. Lookup-then-append is not atomic with SetLiveRun.+func (h *Handler) rebindSteerIfLiveRunMoved(+ ctx context.Context, sessionID, appendedOn string, evt interfaces.StreamEvent,+) (string, string, error) {+ current, err := h.liveAgentRun(ctx, sessionID)+ if err != nil {+ return appendedOn, "queued", err+ }+ if current == appendedOn {+ return appendedOn, "queued", nil+ }+ if current == "" {+ // Leave the event on the finished run. Deleting it here would drop+ // the user's text when the client cannot (and must not) abort a+ // still-open SSE to start a new AgentQA.+ return "", "new_run", nil+ }+ if err := h.streamManager.AppendSteerEvents(ctx, sessionID, current, []interfaces.StreamEvent{evt}); err != nil {+ return "", "", err+ }+ _, _ = h.streamManager.DeleteSteerEvent(ctx, sessionID, appendedOn, evt.ID)+ return current, "queued", nil+}++func mentionedItemsToRequests(items types.MentionedItems) []MentionedItemRequest {+ out := make([]MentionedItemRequest, 0, len(items))+ for _, item := range items {+ out = append(out, MentionedItemRequest{+ ID: item.ID,+ Name: item.Name,+ Type: item.Type,+ KBType: item.KBType,+ KBID: item.KBID,+ KBName: item.KBName,+ ServiceID: item.ServiceID,+ SkillName: item.SkillName,+ })+ }+ return out+}++func (h *Handler) applyFollowUpMentions(ctx context.Context, followUp *qaRequestContext, raw interface{}) {+ snapshot := followUpMentionSnapshot{+ mentionedItems: followUp.mentionedItems,+ knowledgeBaseIDs: append([]string(nil), followUp.knowledgeBaseIDs...),+ knowledgeIDs: append([]string(nil), followUp.knowledgeIDs...),+ mcpServiceIDs: append([]string(nil), followUp.mcpServiceIDs...),+ skillNames: append([]string(nil), followUp.skillNames...),+ tagIDs: append([]string(nil), followUp.tagIDs...),+ tagScopes: append([]types.TagScope(nil), followUp.tagScopes...),+ }+ items := rawToMentionedItems(raw)+ followUp.mentionedItems = items+ reqs := mentionedItemsToRequests(items)+ kbs, files := mergeKnowledgeTargets(followUp.knowledgeBaseIDs, followUp.knowledgeIDs, reqs)+ followUp.knowledgeBaseIDs = kbs+ followUp.knowledgeIDs = files+ followUp.mcpServiceIDs = dedupRequestStrings(append(followUp.mcpServiceIDs, mentionedIDsByType(reqs, "mcp")...))+ followUp.skillNames = dedupRequestStrings(append(followUp.skillNames, mentionedIDsByType(reqs, "skill")...))+ followUp.tagIDs = dedupRequestStrings(append(followUp.tagIDs, mentionedIDsByType(reqs, "tag")...))+ followUp.tagScopes = mergeTagScopesFromRequestIDs(+ tagScopesFromMentionedItems(reqs), followUp.tagIDs, followUp.knowledgeBaseIDs)++ if err := types.AuthorizeTenantAPIKeyKnowledgeTargets(+ ctx, followUp.knowledgeBaseIDs, followUp.knowledgeIDs,+ ); err != nil {+ logger.Warnf(ctx, "dropping follow-up mentions outside API key KB scope: %v", err)+ restoreFollowUpMentions(followUp, snapshot)+ return+ }+ if err := validateUnscopedTagIDs(+ orphanTagIDsForScope(followUp.tagIDs, tagScopesFromMentionedItems(reqs)),+ followUp.knowledgeBaseIDs,+ ); err != nil {+ logger.Warnf(ctx, "dropping follow-up mentions with unscoped tags: %v", err)+ restoreFollowUpMentions(followUp, snapshot)+ }+}++type followUpMentionSnapshot struct {+ mentionedItems types.MentionedItems+ knowledgeBaseIDs []string+ knowledgeIDs []string+ mcpServiceIDs []string+ skillNames []string+ tagIDs []string+ tagScopes []types.TagScope+}++func restoreFollowUpMentions(followUp *qaRequestContext, snapshot followUpMentionSnapshot) {+ followUp.mentionedItems = snapshot.mentionedItems+ followUp.knowledgeBaseIDs = snapshot.knowledgeBaseIDs+ followUp.knowledgeIDs = snapshot.knowledgeIDs+ followUp.mcpServiceIDs = snapshot.mcpServiceIDs+ followUp.skillNames = snapshot.skillNames+ followUp.tagIDs = snapshot.tagIDs+ followUp.tagScopes = snapshot.tagScopes+}++// rawToMentionedItems rebuilds typed mentions from the JSON-safe raw shape+// stored in steer events (inverse of mentionedItemsToRaw).+func rawToMentionedItems(raw interface{}) types.MentionedItems {+ return types.MentionedItemsFromRaw(raw)+}diff --git a/internal/handler/session/steer_delivery_test.go b/internal/handler/session/steer_delivery_test.gonew file mode 100644index 000000000..dd8a7ced6--- /dev/null+++ b/internal/handler/session/steer_delivery_test.go@@ -0,0 +1,350 @@+package session++import (+ "context"+ "errors"+ "testing"++ "github.com/Tencent/WeKnora/internal/stream"+ "github.com/Tencent/WeKnora/internal/types"+ "github.com/Tencent/WeKnora/internal/types/interfaces"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++func TestParseSteerDelivery(t *testing.T) {+ t.Parallel()+ cases := []struct {+ in string+ want string+ wantErr bool+ }{+ // Omitted delivery must queue, not interrupt: a client that does not+ // know about the field should never land inside a running turn.+ {"", steerDeliveryAfter, false},+ {"inject", steerDeliveryInject, false},+ {"INJECT", steerDeliveryInject, false},+ {"after", steerDeliveryAfter, false},+ {"After", steerDeliveryAfter, false},+ {"queue", "", true},+ {"now", "", true},+ {"bogus", "", true},+ }+ for _, tc := range cases {+ got, err := parseSteerDelivery(tc.in)+ if tc.wantErr {+ assert.Error(t, err, "in=%q", tc.in)+ continue+ }+ require.NoError(t, err, "in=%q", tc.in)+ assert.Equal(t, tc.want, got, "in=%q", tc.in)+ }+}++func TestSelectSteerBacklogKeepsAfterAndUndrainedInject(t *testing.T) {+ t.Parallel()+ events := []interfaces.StreamEvent{+ steerEvent("a", "inject-a", nil, "web"),+ steerEventWithDelivery("b", "after-b", steerDeliveryAfter),+ steerEvent("c", "inject-c", nil, "web"),+ steerEventWithDelivery("d", "after-d", steerDeliveryAfter),+ steerEvent("e", "inject-e", nil, "web"),+ }+ backlog := selectSteerBacklog(events, map[string]struct{}{"a": {}, "c": {}})+ require.Len(t, backlog, 3)+ assert.Equal(t, "b", backlog[0].ID)+ assert.Equal(t, "d", backlog[1].ID)+ assert.Equal(t, "e", backlog[2].ID)+}++func TestSelectSteerBacklogNothingWhenAllInjectDrainedAndNoAfter(t *testing.T) {+ t.Parallel()+ events := []interfaces.StreamEvent{+ steerEvent("a", "inject-a", nil, "web"),+ steerEvent("b", "inject-b", nil, "web"),+ }+ assert.Empty(t, selectSteerBacklog(events, map[string]struct{}{"a": {}, "b": {}}))+}++func TestSelectSteerBacklogAllWhenNeverDrained(t *testing.T) {+ t.Parallel()+ events := []interfaces.StreamEvent{+ steerEvent("a", "inject-a", nil, "web"),+ steerEventWithDelivery("b", "after-b", steerDeliveryAfter),+ }+ backlog := selectSteerBacklog(events, nil)+ require.Len(t, backlog, 2)+ assert.Equal(t, "a", backlog[0].ID)+ assert.Equal(t, "b", backlog[1].ID)+}++func TestSelectSteerBacklogKeepsPromotedAfterUntilInjected(t *testing.T) {+ t.Parallel()+ events := []interfaces.StreamEvent{+ steerEventWithDelivery("b", "after-b", steerDeliveryInject),+ }+ backlog := selectSteerBacklog(events, map[string]struct{}{})+ require.Len(t, backlog, 1)+ assert.Equal(t, "b", backlog[0].ID)+ assert.Empty(t, selectSteerBacklog(events, map[string]struct{}{"b": {}}))+}++func TestPollSteerSkipsAfterDeliveryAndAdvancesOffset(t *testing.T) {+ mgr := stream.NewMemoryStreamManager()+ ctx := context.Background()+ require.NoError(t, mgr.AppendSteerEvents(ctx, "sess", "assist", []interfaces.StreamEvent{+ steerEvent("a", "inject-a", nil, "web"),+ steerEventWithDelivery("b", "after-b", steerDeliveryAfter),+ steerEvent("c", "inject-c", nil, "web"),+ }))++ sink := newSteerSink(ctx, "sess", "req", &types.Message{ID: "assist"}, nil, mgr)+ events, next, err := sink.PollSteer(ctx, "sess", "assist", 0)+ require.NoError(t, err)+ require.Len(t, events, 2)+ assert.Equal(t, "a", events[0]["id"])+ assert.Equal(t, "c", events[1]["id"])+ assert.Equal(t, 3, next)+ assert.Equal(t, 3, sink.DrainedOffset())++ events, next, err = sink.PollSteer(ctx, "sess", "assist", next)+ require.NoError(t, err)+ assert.Empty(t, events)+ assert.Equal(t, 3, next)+}++func TestPollSteerPicksUpAfterPromotedToInject(t *testing.T) {+ mgr := stream.NewMemoryStreamManager()+ ctx := context.Background()+ require.NoError(t, mgr.AppendSteerEvents(ctx, "sess", "assist", []interfaces.StreamEvent{+ steerEventWithDelivery("b", "wait-then-nudge", steerDeliveryAfter),+ }))++ sink := newSteerSink(ctx, "sess", "req", &types.Message{ID: "assist"}, nil, mgr)+ events, _, err := sink.PollSteer(ctx, "sess", "assist", 0)+ require.NoError(t, err)+ assert.Empty(t, events)++ ok, err := promoteSteerForTest(ctx, mgr, "b")+ require.NoError(t, err)+ assert.True(t, ok)++ events, _, err = sink.PollSteer(ctx, "sess", "assist", sink.DrainedOffset())+ require.NoError(t, err)+ require.Len(t, events, 1)+ assert.Equal(t, "b", events[0]["id"])+ assert.Equal(t, "wait-then-nudge", events[0]["content"])+}++func TestSetSteerDeliveryUpdatesExistingAfterEvent(t *testing.T) {+ mgr := stream.NewMemoryStreamManager()+ ctx := context.Background()+ require.NoError(t, mgr.AppendSteerEvents(ctx, "sess", "assist", []interfaces.StreamEvent{+ steerEventWithDelivery("keep", "later", steerDeliveryAfter),+ steerEventWithDelivery("flip", "now", steerDeliveryAfter),+ }))++ ok, err := promoteSteerForTest(ctx, mgr, "flip")+ require.NoError(t, err)+ assert.True(t, ok)++ events, _, err := mgr.GetSteerEvents(ctx, "sess", "assist", 0)+ require.NoError(t, err)+ require.Len(t, events, 2)+ assert.Equal(t, steerDeliveryAfter, events[0].Data["delivery"])+ assert.Equal(t, steerDeliveryInject, events[1].Data["delivery"])++ ok, err = promoteSteerForTest(ctx, mgr, "missing")+ require.NoError(t, err)+ assert.False(t, ok)+}++// TestPollSteerMarksConsumedDurably pins the cross-replica contract: once the+// engine has taken a message, the flag lives on the event itself. Anything+// that reads the queue afterwards — the overlay, the depth guard, a follow-up+// handoff running in another process — must see it as gone.+func TestPollSteerMarksConsumedDurably(t *testing.T) {+ mgr := stream.NewMemoryStreamManager()+ ctx := context.Background()+ require.NoError(t, mgr.AppendSteerEvents(ctx, "sess", "assist", []interfaces.StreamEvent{+ steerEventWithDelivery("a", "do it now", steerDeliveryInject),+ steerEventWithDelivery("b", "and later this", steerDeliveryAfter),+ }))++ msgs := &steerPersistingMessageStub{}+ sink := newSteerSink(ctx, "sess", "req", &types.Message{ID: "assist"}, msgs, mgr)+ events, _, err := sink.PollSteer(ctx, "sess", "assist", 0)+ require.NoError(t, err)+ require.Len(t, events, 1)+ require.NotEmpty(t, sink.PersistSteerMessage(ctx, "sess", "assist", "a", "do it now", nil, "web"))++ stored, _, err := mgr.GetSteerEvents(ctx, "sess", "assist", 0)+ require.NoError(t, err)+ require.Len(t, stored, 2)+ assert.True(t, steerEventConsumed(stored[0]), "injected event must be flagged consumed")+ assert.False(t, steerEventConsumed(stored[1]), "queued after-event must stay pending")++ // A fresh sink stands in for another replica: it must not replay the+ // message the first one already handed to the model.+ other := newSteerSink(ctx, "sess", "req", &types.Message{ID: "assist"}, nil, mgr)+ replayed, _, err := other.PollSteer(ctx, "sess", "assist", 0)+ require.NoError(t, err)+ assert.Empty(t, replayed)++ // And it is no longer part of the backlog handed to a follow-up run.+ assert.Len(t, selectSteerBacklog(stored, nil), 1)+}++// TestPollSteerDoesNotMutateAlreadyReadEvents guards the copy-on-write in the+// memory manager: marking consumed must not retroactively edit event copies+// the teardown path already captured for carry-over.+func TestPollSteerDoesNotMutateAlreadyReadEvents(t *testing.T) {+ mgr := stream.NewMemoryStreamManager()+ ctx := context.Background()+ require.NoError(t, mgr.AppendSteerEvents(ctx, "sess", "assist", []interfaces.StreamEvent{+ steerEventWithDelivery("a", "carry me over", steerDeliveryAfter),+ }))++ captured, _, err := mgr.GetSteerEvents(ctx, "sess", "assist", 0)+ require.NoError(t, err)+ require.Len(t, captured, 1)++ ok, err := mgr.UpdateSteerEventData(ctx, "sess", "assist", "a",+ map[string]interface{}{steerDataConsumed: true})+ require.NoError(t, err)+ require.True(t, ok)++ assert.False(t, steerEventConsumed(captured[0]),+ "carry-over copy must stay pending so the follow-up run can inject it")+}++// promoteSteerForTest is the "立即发送" mutation the handler performs.+func promoteSteerForTest(+ ctx context.Context, mgr *stream.MemoryStreamManager, steerID string,+) (bool, error) {+ return mgr.UpdateSteerEventData(ctx, "sess", "assist", steerID,+ map[string]interface{}{"delivery": steerDeliveryInject})+}++func TestDeleteSteerEventRemovesPendingAfter(t *testing.T) {+ mgr := stream.NewMemoryStreamManager()+ ctx := context.Background()+ require.NoError(t, mgr.AppendSteerEvents(ctx, "sess", "assist", []interfaces.StreamEvent{+ steerEventWithDelivery("keep", "later", steerDeliveryAfter),+ steerEventWithDelivery("drop", "gone", steerDeliveryAfter),+ }))++ ok, err := mgr.DeleteSteerEvent(ctx, "sess", "assist", "drop")+ require.NoError(t, err)+ assert.True(t, ok)++ events, _, err := mgr.GetSteerEvents(ctx, "sess", "assist", 0)+ require.NoError(t, err)+ require.Len(t, events, 1)+ assert.Equal(t, "keep", events[0].ID)++ ok, err = mgr.DeleteSteerEvent(ctx, "sess", "assist", "drop")+ require.NoError(t, err)+ assert.False(t, ok)+}++func TestSteerEventCarriesDelivery(t *testing.T) {+ t.Parallel()+ evt := steerEventWithDelivery("id-1", "hello", steerDeliveryAfter)+ assert.Equal(t, types.ResponseTypeSteer, evt.Type)+ assert.Equal(t, steerDeliveryAfter, evt.Data["delivery"])+ assert.Equal(t, "hello", evt.Content)+}++func TestPendingSteerQueueItemsOmitsInjectedKeepsAfter(t *testing.T) {+ t.Parallel()+ events := []interfaces.StreamEvent{+ steerEvent("a", "inject-done", nil, "web"),+ steerEventWithDelivery("b", "first after", steerDeliveryAfter),+ steerEventWithDelivery("c", "second after", steerDeliveryAfter),+ }+ items := pendingSteerQueueItems(events, map[string]struct{}{"a": {}})+ require.Len(t, items, 2)+ assert.Equal(t, "b", items[0]["steer_id"])+ assert.Equal(t, "first after", items[0]["content"])+ assert.Equal(t, steerDeliveryAfter, items[0]["delivery"])+ assert.Equal(t, "c", items[1]["steer_id"])+ assert.Equal(t, steerDeliveryAfter, items[1]["delivery"])+}++func TestPendingSteerQueueItemsOmitsConsumedWithoutInMemoryState(t *testing.T) {+ t.Parallel()+ consumed := steerEventWithDelivery("a", "already injected", steerDeliveryInject)+ consumed.Data[steerDataConsumed] = true+ events := []interfaces.StreamEvent{+ consumed,+ steerEventWithDelivery("b", "still waiting", steerDeliveryAfter),+ }+ // nil injectedIDs stands in for a replica that never ran this turn: the+ // durable flag alone has to keep the overlay honest after a refresh.+ items := pendingSteerQueueItems(events, nil)+ require.Len(t, items, 1)+ assert.Equal(t, "b", items[0]["steer_id"])+}++func steerEventWithDelivery(id, query, delivery string) interfaces.StreamEvent {+ evt := steerEvent(id, query, nil, "web")+ evt.Data["delivery"] = delivery+ return evt+}++type steerUpdateFailingManager struct {+ interfaces.StreamManager+}++func (s *steerUpdateFailingManager) UpdateSteerEventData(+ context.Context, string, string, string, map[string]interface{},+) (bool, error) {+ return false, errors.New("cas exhausted")+}++func TestPersistSteerMessageRollsBackRowWhenConsumeFails(t *testing.T) {+ inner := stream.NewMemoryStreamManager()+ ctx := context.Background()+ require.NoError(t, inner.AppendSteerEvents(ctx, "sess", "assist", []interfaces.StreamEvent{+ steerEventWithDelivery("a", "do it now", steerDeliveryInject),+ }))+ msgs := &steerPersistingMessageStub{}+ sink := newSteerSink(ctx, "sess", "req", &types.Message{ID: "assist"}, msgs,+ &steerUpdateFailingManager{StreamManager: inner})+ assert.Empty(t, sink.PersistSteerMessage(ctx, "sess", "assist", "a", "do it now", nil, "web"))+ assert.Empty(t, msgs.byID, "failed consume must delete the user row so a retry cannot duplicate it")+}++func TestPersistSteerMessageIsIdempotentAfterConsume(t *testing.T) {+ mgr := stream.NewMemoryStreamManager()+ ctx := context.Background()+ require.NoError(t, mgr.AppendSteerEvents(ctx, "sess", "assist", []interfaces.StreamEvent{+ steerEventWithDelivery("a", "do it now", steerDeliveryInject),+ }))+ msgs := &steerPersistingMessageStub{}+ sink := newSteerSink(ctx, "sess", "req", &types.Message{ID: "assist"}, msgs, mgr)+ first := sink.PersistSteerMessage(ctx, "sess", "assist", "a", "do it now", nil, "api")+ require.NotEmpty(t, first)+ second := sink.PersistSteerMessage(ctx, "sess", "assist", "a", "do it now", nil, "api")+ assert.Equal(t, first, second)+ assert.Equal(t, 1, msgs.n)+ assert.Equal(t, "api", msgs.byID[first].Channel)+}++func TestDeleteConsumedSteerEventIsNoOp(t *testing.T) {+ mgr := stream.NewMemoryStreamManager()+ ctx := context.Background()+ evt := steerEventWithDelivery("a", "already in the model", steerDeliveryInject)+ evt.Data[steerDataConsumed] = true+ require.NoError(t, mgr.AppendSteerEvents(ctx, "sess", "assist", []interfaces.StreamEvent{evt}))++ ok, err := mgr.DeleteSteerEvent(ctx, "sess", "assist", "a")+ require.NoError(t, err)+ assert.False(t, ok)++ stored, _, err := mgr.GetSteerEvents(ctx, "sess", "assist", 0)+ require.NoError(t, err)+ require.Len(t, stored, 1)+ assert.Equal(t, "a", stored[0].ID)+}diff --git a/internal/handler/session/steer_live_run_test.go b/internal/handler/session/steer_live_run_test.gonew file mode 100644index 000000000..fecd08d4b--- /dev/null+++ b/internal/handler/session/steer_live_run_test.go@@ -0,0 +1,462 @@+package session++import (+ "bytes"+ "context"+ "encoding/json"+ "errors"+ "fmt"+ "net/http"+ "net/http/httptest"+ "testing"++ "github.com/Tencent/WeKnora/internal/middleware"+ "github.com/Tencent/WeKnora/internal/stream"+ "github.com/Tencent/WeKnora/internal/types"+ "github.com/Tencent/WeKnora/internal/types/interfaces"+ "github.com/gin-gonic/gin"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++// A Redis/DB blip on the live-run lookup used to collapse into "no run is+// live". SteerMessage then answered status=new_run, and the client started a+// second AgentQA on top of the still-generating one. These tests pin the+// contract: lookup failure is retryable (503); only a genuine empty or+// completed marker may say new_run.++type steerOwnedSessionStub struct {+ interfaces.SessionService+}++func (s *steerOwnedSessionStub) GetOwnedSession(_ context.Context, id string) (*types.Session, error) {+ return &types.Session{ID: id}, nil+}++type steerMessageLookupStub struct {+ interfaces.MessageService+ msg *types.Message+ err error+}++func (s *steerMessageLookupStub) GetMessage(_ context.Context, _, _ string) (*types.Message, error) {+ return s.msg, s.err+}++type steerLiveRunLookupStub struct {+ interfaces.StreamManager+ assistantID string+ err error+ cleared string+}++func (s *steerLiveRunLookupStub) GetLiveRun(context.Context, string) (string, string, error) {+ return s.assistantID, "req-1", s.err+}++func (s *steerLiveRunLookupStub) ClearLiveRun(_ context.Context, _, assistantID string) error {+ s.cleared = assistantID+ return nil+}++func newSteerLiveRunRouter(h *Handler) *gin.Engine {+ gin.SetMode(gin.TestMode)+ r := gin.New()+ r.Use(middleware.ErrorHandler())+ r.POST("/sessions/:session_id/steer", h.SteerMessage)+ r.POST("/sessions/:session_id/steer/:steer_id/inject", h.PromoteSteerMessage)+ r.GET("/sessions/:id/steer", h.ListSteerMessages)+ r.DELETE("/sessions/:id/steer/:steer_id", h.DeleteSteerMessage)+ return r+}++func postSteer(t *testing.T, r *gin.Engine, body string) *httptest.ResponseRecorder {+ t.Helper()+ req := httptest.NewRequest(http.MethodPost, "/sessions/sess-1/steer", bytes.NewBufferString(body))+ req.Header.Set("Content-Type", "application/json")+ w := httptest.NewRecorder()+ r.ServeHTTP(w, req)+ return w+}++func TestSteerMessageLiveRunLookupFailureReturns503(t *testing.T) {+ h := &Handler{+ sessionService: &steerOwnedSessionStub{},+ messageService: &steerMessageLookupStub{},+ streamManager: &steerLiveRunLookupStub{err: errors.New("redis timeout")},+ }+ w := postSteer(t, newSteerLiveRunRouter(h), `{"query":"nudge the agent"}`)+ require.Equal(t, http.StatusServiceUnavailable, w.Code, w.Body.String())+ assert.NotContains(t, w.Body.String(), `"new_run"`)+}++func TestSteerMessageMessageLookupFailureReturns503(t *testing.T) {+ h := &Handler{+ sessionService: &steerOwnedSessionStub{},+ messageService: &steerMessageLookupStub{err: errors.New("db timeout")},+ streamManager: &steerLiveRunLookupStub{assistantID: "assist-1"},+ }+ w := postSteer(t, newSteerLiveRunRouter(h), `{"query":"nudge the agent"}`)+ require.Equal(t, http.StatusServiceUnavailable, w.Code, w.Body.String())+ assert.NotContains(t, w.Body.String(), `"new_run"`)+}++func TestSteerMessageNoLiveRunStillReturnsNewRun(t *testing.T) {+ h := &Handler{+ sessionService: &steerOwnedSessionStub{},+ messageService: &steerMessageLookupStub{},+ streamManager: &steerLiveRunLookupStub{},+ }+ w := postSteer(t, newSteerLiveRunRouter(h), `{"query":"hello"}`)+ require.Equal(t, http.StatusOK, w.Code, w.Body.String())++ var body map[string]interface{}+ require.NoError(t, json.Unmarshal(w.Body.Bytes(), &body))+ assert.Equal(t, "new_run", body["status"])+}++func TestSteerMessageCompletedLiveRunStillReturnsNewRun(t *testing.T) {+ streams := &steerLiveRunLookupStub{assistantID: "assist-1"}+ h := &Handler{+ sessionService: &steerOwnedSessionStub{},+ messageService: &steerMessageLookupStub{+ msg: &types.Message{ID: "assist-1", IsCompleted: true},+ },+ streamManager: streams,+ }+ w := postSteer(t, newSteerLiveRunRouter(h), `{"query":"hello"}`)+ require.Equal(t, http.StatusOK, w.Code, w.Body.String())++ var body map[string]interface{}+ require.NoError(t, json.Unmarshal(w.Body.Bytes(), &body))+ assert.Equal(t, "new_run", body["status"])+ assert.Equal(t, "assist-1", streams.cleared)+}++func TestSteerMessageQueuesWhenLiveRunIsVerified(t *testing.T) {+ mgr := stream.NewMemoryStreamManager()+ require.NoError(t, mgr.SetLiveRun(t.Context(), "sess-1", "assist-1", "req-1"))+ h := &Handler{+ sessionService: &steerOwnedSessionStub{},+ messageService: &steerMessageLookupStub{+ msg: &types.Message{ID: "assist-1", SessionID: "sess-1", IsCompleted: false},+ },+ streamManager: mgr,+ }+ w := postSteer(t, newSteerLiveRunRouter(h), `{"query":"keep going","delivery":"after"}`)+ require.Equal(t, http.StatusOK, w.Code, w.Body.String())++ var body map[string]interface{}+ require.NoError(t, json.Unmarshal(w.Body.Bytes(), &body))+ assert.Equal(t, "queued", body["status"])+ assert.Equal(t, "assist-1", body["assistant_message_id"])+}++func TestPromoteAndListLiveRunLookupFailureReturns503(t *testing.T) {+ h := &Handler{+ sessionService: &steerOwnedSessionStub{},+ messageService: &steerMessageLookupStub{},+ streamManager: &steerLiveRunLookupStub{err: errors.New("redis timeout")},+ }+ r := newSteerLiveRunRouter(h)++ promote := httptest.NewRecorder()+ req := httptest.NewRequest(http.MethodPost, "/sessions/sess-1/steer/s1/inject", bytes.NewBufferString(`{}`))+ req.Header.Set("Content-Type", "application/json")+ r.ServeHTTP(promote, req)+ require.Equal(t, http.StatusServiceUnavailable, promote.Code, promote.Body.String())+ assert.NotContains(t, promote.Body.String(), `"new_run"`)++ list := httptest.NewRecorder()+ r.ServeHTTP(list, httptest.NewRequest(http.MethodGet, "/sessions/sess-1/steer", nil))+ require.Equal(t, http.StatusServiceUnavailable, list.Code, list.Body.String())+ assert.NotContains(t, list.Body.String(), `"items"`)++ del := httptest.NewRecorder()+ r.ServeHTTP(del, httptest.NewRequest(http.MethodDelete, "/sessions/sess-1/steer/s1", nil))+ require.Equal(t, http.StatusServiceUnavailable, del.Code, del.Body.String())+ assert.NotContains(t, del.Body.String(), `"gone"`)+}++// steerPersistingMessageStub assigns IDs on create so a follow-up can claim+// the live-run marker without a database.+type steerPersistingMessageStub struct {+ interfaces.MessageService+ n int+ byID map[string]*types.Message+}++func (s *steerPersistingMessageStub) CreateMessage(_ context.Context, msg *types.Message) (*types.Message, error) {+ s.n+++ out := *msg+ if out.ID == "" {+ out.ID = fmt.Sprintf("msg-%d", s.n)+ }+ if s.byID == nil {+ s.byID = map[string]*types.Message{}+ }+ stored := out+ s.byID[out.ID] = &stored+ return &out, nil+}++func (s *steerPersistingMessageStub) DeleteMessage(_ context.Context, _, id string) error {+ if s.byID != nil {+ delete(s.byID, id)+ }+ return nil+}++func (s *steerPersistingMessageStub) GetMessage(_ context.Context, _, id string) (*types.Message, error) {+ if s.byID == nil {+ return nil, errors.New("not found")+ }+ msg, ok := s.byID[id]+ if !ok {+ return nil, errors.New("not found")+ }+ cloned := *msg+ return &cloned, nil+}++// The previous run's ClearLiveRun used to run before the follow-up had an+// assistant row or a live marker. POST /steer then answered new_run and the+// client started a second AgentQA alongside kick's executeQA. Claiming the+// session (persist + SetLiveRun) must finish before that Clear, and the CAS+// Clear of the old id must leave the new marker in place.+func TestSteerFollowUpHandoffKeepsSessionLiveAcrossPreviousClear(t *testing.T) {+ ctx := t.Context()+ mgr := stream.NewMemoryStreamManager()+ require.NoError(t, mgr.SetLiveRun(ctx, "sess-1", "assist-A", "req-A"))+ require.NoError(t, mgr.AppendSteerEvents(ctx, "sess-1", "assist-A", []interfaces.StreamEvent{+ steerEventWithDelivery("after-1", "do this next", steerDeliveryAfter),+ steerEventWithDelivery("after-2", "then this", steerDeliveryAfter),+ }))++ msgs := &steerPersistingMessageStub{}+ h := &Handler{+ sessionService: &steerOwnedSessionStub{},+ messageService: msgs,+ streamManager: mgr,+ }+ prev := &qaRequestContext{+ sessionID: "sess-1",+ session: &types.Session{ID: "sess-1"},+ }+ streamCtx := &sseStreamContext{assistantMessage: &types.Message{ID: "assist-A"}}++ followUp, ok := h.claimNextSteerFollowUp(ctx, prev, streamCtx)+ require.True(t, ok)+ require.NotNil(t, followUp)+ assert.Equal(t, "do this next", followUp.query)+ require.NotEmpty(t, followUp.assistantMessage.ID)+ assert.NotEqual(t, "assist-A", followUp.assistantMessage.ID)+ assert.Empty(t, followUp.steerCarryOver, "carry-over must already sit on the new run's list")++ liveID, liveReq, err := mgr.GetLiveRun(ctx, "sess-1")+ require.NoError(t, err)+ assert.Equal(t, followUp.assistantMessage.ID, liveID)+ assert.Equal(t, followUp.requestID, liveReq)++ require.NoError(t, mgr.ClearLiveRun(ctx, "sess-1", "assist-A"))+ liveID, _, err = mgr.GetLiveRun(ctx, "sess-1")+ require.NoError(t, err)+ assert.Equal(t, followUp.assistantMessage.ID, liveID,+ "ClearLiveRun of the finished run must not drop the follow-up marker")++ events, _, err := mgr.GetSteerEvents(ctx, "sess-1", followUp.assistantMessage.ID, 0)+ require.NoError(t, err)+ require.Len(t, events, 1)+ assert.Equal(t, "after-2", events[0].ID)++ old, _, err := mgr.GetSteerEvents(ctx, "sess-1", "assist-A", 0)+ require.NoError(t, err)+ require.Len(t, old, 2)+ assert.True(t, steerEventConsumed(old[0]))+ assert.True(t, steerEventConsumed(old[1]))++ w := postSteer(t, newSteerLiveRunRouter(h), `{"query":"and this too","delivery":"after"}`)+ require.Equal(t, http.StatusOK, w.Code, w.Body.String())+ var body map[string]interface{}+ require.NoError(t, json.Unmarshal(w.Body.Bytes(), &body))+ assert.Equal(t, "queued", body["status"],+ "a send during handoff must queue on the follow-up, not start a third run")+ assert.Equal(t, followUp.assistantMessage.ID, body["assistant_message_id"])+}++func TestClaimNextSteerFollowUpNoBacklogLeavesMarkerUntouched(t *testing.T) {+ ctx := t.Context()+ mgr := stream.NewMemoryStreamManager()+ require.NoError(t, mgr.SetLiveRun(ctx, "sess-1", "assist-A", "req-A"))++ h := &Handler{streamManager: mgr}+ followUp, ok := h.claimNextSteerFollowUp(ctx, &qaRequestContext{sessionID: "sess-1"},+ &sseStreamContext{assistantMessage: &types.Message{ID: "assist-A"}})+ assert.False(t, ok)+ assert.Nil(t, followUp)++ liveID, _, err := mgr.GetLiveRun(ctx, "sess-1")+ require.NoError(t, err)+ assert.Equal(t, "assist-A", liveID)+}++func TestClaimNextSteerFollowUpPersistFailureLeavesBacklog(t *testing.T) {+ ctx := t.Context()+ mgr := stream.NewMemoryStreamManager()+ require.NoError(t, mgr.SetLiveRun(ctx, "sess-1", "assist-A", "req-A"))+ require.NoError(t, mgr.AppendSteerEvents(ctx, "sess-1", "assist-A", []interfaces.StreamEvent{+ steerEventWithDelivery("after-1", "do this next", steerDeliveryAfter),+ }))++ h := &Handler{+ sessionService: &steerOwnedSessionStub{},+ messageService: &steerFailingCreateStub{},+ streamManager: mgr,+ }+ followUp, ok := h.claimNextSteerFollowUp(ctx, &qaRequestContext{sessionID: "sess-1"},+ &sseStreamContext{assistantMessage: &types.Message{ID: "assist-A"}})+ assert.False(t, ok)+ assert.Nil(t, followUp)++ old, _, err := mgr.GetSteerEvents(ctx, "sess-1", "assist-A", 0)+ require.NoError(t, err)+ require.Len(t, old, 1)+ assert.False(t, steerEventConsumed(old[0]))+}++func TestRebindSteerMovesEventOntoNewLiveRun(t *testing.T) {+ ctx := t.Context()+ mgr := stream.NewMemoryStreamManager()+ require.NoError(t, mgr.SetLiveRun(ctx, "sess-1", "assist-A", "req-A"))+ h := &Handler{+ sessionService: &steerOwnedSessionStub{},+ messageService: &steerMessageLookupStub{+ msg: &types.Message{ID: "assist-B", SessionID: "sess-1", IsCompleted: false},+ },+ streamManager: mgr,+ }+ evt := steerEventWithDelivery("late-1", "landed on A", steerDeliveryAfter)+ require.NoError(t, mgr.AppendSteerEvents(ctx, "sess-1", "assist-A", []interfaces.StreamEvent{evt}))+ require.NoError(t, mgr.ClaimLiveRun(ctx, "sess-1", "assist-B", "req-B"))++ queuedOn, status, err := h.rebindSteerIfLiveRunMoved(ctx, "sess-1", "assist-A", evt)+ require.NoError(t, err)+ assert.Equal(t, "queued", status)+ assert.Equal(t, "assist-B", queuedOn)++ old, _, err := mgr.GetSteerEvents(ctx, "sess-1", "assist-A", 0)+ require.NoError(t, err)+ assert.Empty(t, old)+ moved, _, err := mgr.GetSteerEvents(ctx, "sess-1", "assist-B", 0)+ require.NoError(t, err)+ require.Len(t, moved, 1)+ assert.Equal(t, "late-1", moved[0].ID)+}++func TestApplyFollowUpMentionsMergesKBAndMCP(t *testing.T) {+ h := &Handler{}+ followUp := &qaRequestContext{+ knowledgeBaseIDs: []string{"kb-old"},+ mcpServiceIDs: []string{"mcp-old"},+ }+ h.applyFollowUpMentions(t.Context(), followUp, []interface{}{+ map[string]interface{}{"id": "kb-new", "type": "kb", "name": "New KB"},+ map[string]interface{}{"id": "mcp-new", "type": "mcp", "name": "MCP"},+ })+ assert.Equal(t, []string{"kb-old", "kb-new"}, followUp.knowledgeBaseIDs)+ assert.Equal(t, []string{"mcp-old", "mcp-new"}, followUp.mcpServiceIDs)+}++type steerFailingCreateStub struct {+ interfaces.MessageService+}++func (s *steerFailingCreateStub) CreateMessage(context.Context, *types.Message) (*types.Message, error) {+ return nil, errors.New("db down")+}++func TestPersistTurnMessagesSkipsWhenAlreadyClaimed(t *testing.T) {+ msgs := &steerPersistingMessageStub{}+ h := &Handler{messageService: msgs}+ reqCtx := &qaRequestContext{+ sessionID: "sess-1",+ query: "already persisted",+ requestID: "req-B",+ userMessageID: "user-1",+ assistantMessage: &types.Message{+ ID: "assist-B",+ SessionID: "sess-1",+ Role: "assistant",+ },+ }+ require.NoError(t, h.persistTurnMessages(t.Context(), reqCtx))+ assert.Equal(t, 0, msgs.n)+}++type steerClaimFailingManager struct {+ interfaces.StreamManager+}++func (s *steerClaimFailingManager) ClaimLiveRun(context.Context, string, string, string) error {+ return errors.New("redis down")+}++type steerAppendFailingManager struct {+ interfaces.StreamManager+}++func (s *steerAppendFailingManager) AppendSteerEvents(+ context.Context, string, string, []interfaces.StreamEvent,+) error {+ return errors.New("redis down")+}++func TestClaimNextSteerFollowUpClaimFailureRollsBackMessages(t *testing.T) {+ ctx := t.Context()+ inner := stream.NewMemoryStreamManager()+ require.NoError(t, inner.SetLiveRun(ctx, "sess-1", "assist-A", "req-A"))+ require.NoError(t, inner.AppendSteerEvents(ctx, "sess-1", "assist-A", []interfaces.StreamEvent{+ steerEventWithDelivery("after-1", "do this next", steerDeliveryAfter),+ }))++ msgs := &steerPersistingMessageStub{}+ h := &Handler{+ sessionService: &steerOwnedSessionStub{},+ messageService: msgs,+ streamManager: &steerClaimFailingManager{StreamManager: inner},+ }+ followUp, ok := h.claimNextSteerFollowUp(ctx, &qaRequestContext{sessionID: "sess-1"},+ &sseStreamContext{assistantMessage: &types.Message{ID: "assist-A"}})+ assert.False(t, ok)+ assert.Nil(t, followUp)+ assert.Empty(t, msgs.byID, "ClaimLiveRun failure must not leave a follow-up turn in the database")++ old, _, err := inner.GetSteerEvents(ctx, "sess-1", "assist-A", 0)+ require.NoError(t, err)+ require.Len(t, old, 1)+ assert.False(t, steerEventConsumed(old[0]), "backlog must stay pending so a retry can claim it")+}++func TestRebindSteerKeepsEventWhenAppendFails(t *testing.T) {+ ctx := t.Context()+ inner := stream.NewMemoryStreamManager()+ require.NoError(t, inner.SetLiveRun(ctx, "sess-1", "assist-A", "req-A"))+ h := &Handler{+ sessionService: &steerOwnedSessionStub{},+ messageService: &steerMessageLookupStub{+ msg: &types.Message{ID: "assist-B", SessionID: "sess-1", IsCompleted: false},+ },+ streamManager: &steerAppendFailingManager{StreamManager: inner},+ }+ evt := steerEventWithDelivery("late-1", "landed on A", steerDeliveryAfter)+ require.NoError(t, inner.AppendSteerEvents(ctx, "sess-1", "assist-A", []interfaces.StreamEvent{evt}))+ require.NoError(t, inner.ClaimLiveRun(ctx, "sess-1", "assist-B", "req-B"))++ _, _, err := h.rebindSteerIfLiveRunMoved(ctx, "sess-1", "assist-A", evt)+ require.Error(t, err)++ old, _, err := inner.GetSteerEvents(ctx, "sess-1", "assist-A", 0)+ require.NoError(t, err)+ require.Len(t, old, 1)+ assert.Equal(t, "late-1", old[0].ID)+}diff --git a/internal/handler/session/steer_wiring_test.go b/internal/handler/session/steer_wiring_test.gonew file mode 100644index 000000000..7d80f3322--- /dev/null+++ b/internal/handler/session/steer_wiring_test.go@@ -0,0 +1,198 @@+package session++import (+ "net/http/httptest"+ "testing"+ "time"++ "github.com/Tencent/WeKnora/internal/stream"+ "github.com/Tencent/WeKnora/internal/types"+ "github.com/gin-gonic/gin"+ "github.com/stretchr/testify/assert"+ "github.com/stretchr/testify/require"+)++// newSteerWiringGinContext builds the minimal gin context setupSSEStream+// needs (setSSEHeaders writes to it immediately).+func newSteerWiringGinContext() *gin.Context {+ gin.SetMode(gin.TestMode)+ w := httptest.NewRecorder()+ c, _ := gin.CreateTestContext(w)+ c.Request = httptest.NewRequest("POST", "/", nil)+ return c+}++// TestSetupSSEStreamMirrorsSteerSinkOntoRequestContext is the regression guard+// for the wiring bug where the sink was created on sseStreamContext but+// buildQARequest read qaRequestContext.steerSink — which nobody ever set — so+// queued steer messages were never handed to the engine and sat in the+// sub-list forever. The sink must be reachable from BOTH holders.+func TestSetupSSEStreamMirrorsSteerSinkOntoRequestContext(t *testing.T) {+ streams := stream.NewMemoryStreamManager()+ h := &Handler{streamManager: streams}++ assistantMessage := &types.Message{+ ID: "assist-1",+ SessionID: "sess-1",+ Role: "assistant",+ CreatedAt: time.Now(),+ }+ reqCtx := &qaRequestContext{+ c: newSteerWiringGinContext(),+ ctx: t.Context(),+ sessionID: "sess-1",+ requestID: "req-1",+ session: &types.Session{ID: "sess-1"},+ customAgent: &types.CustomAgent{ID: "agent-1"},+ assistantMessage: assistantMessage,+ }++ streamCtx := h.setupSSEStream(reqCtx, false, qaModeAgent)++ require.NotNil(t, streamCtx, "setupSSEStream returned nil")+ require.NotNil(t, streamCtx.steerSink, "streamCtx.steerSink must be created for agent runs")+ assert.NotNil(t, reqCtx.steerSink,+ "reqCtx.steerSink must mirror the streamCtx sink — buildQARequest reads it; "++ "if this is nil the engine never receives a SteerSink and queued messages are silently dropped")+ assert.Same(t, streamCtx.steerSink, reqCtx.steerSink,+ "both holders must point at the same sink instance")++ // The built QA request must carry the sink through to the service layer.+ qaReq := reqCtx.buildQARequest()+ assert.NotNil(t, qaReq.SteerSink,+ "QARequest.SteerSink must be set for agent runs — nil here means the engine runs without mid-run injection")++ // The live-run marker must be published through the StreamManager, not a+ // process-local map: a steer request that lands on another replica has+ // to find this run instead of reporting "no run is live" and starting a+ // duplicate turn.+ liveID, liveReq, err := streams.GetLiveRun(t.Context(), "sess-1")+ require.NoError(t, err)+ assert.Equal(t, "assist-1", liveID, "agent run must be published as the session's live run")+ assert.Equal(t, "req-1", liveReq)+}++// TestSetupSSEStreamNoSinkWithoutCustomAgent pins the negative case: runs+// without a custom agent (quick-answer) get no sink, matching the previous+// behaviour.+func TestSetupSSEStreamNoSinkWithoutCustomAgent(t *testing.T) {+ streams := stream.NewMemoryStreamManager()+ h := &Handler{streamManager: streams}++ reqCtx := &qaRequestContext{+ ctx: t.Context(),+ c: newSteerWiringGinContext(),+ sessionID: "sess-2",+ requestID: "req-2",+ session: &types.Session{ID: "sess-2"},+ customAgent: nil,+ assistantMessage: &types.Message{ID: "assist-2", SessionID: "sess-2", Role: "assistant", CreatedAt: time.Now()},+ }++ streamCtx := h.setupSSEStream(reqCtx, false, qaModeNormal)+ require.NotNil(t, streamCtx)+ assert.Nil(t, streamCtx.steerSink)+ assert.Nil(t, reqCtx.steerSink)+ qaReq := reqCtx.buildQARequest()+ assert.Nil(t, qaReq.SteerSink)++ // Quick-answer turns must not claim the session either: there is no+ // engine loop to drain a queue, so a steer request pointed here would+ // park messages that never run.+ liveID, _, err := streams.GetLiveRun(t.Context(), "sess-2")+ require.NoError(t, err)+ assert.Empty(t, liveID, "non-agent run must not be published as the live run")+}++// A custom agent configured as quick-answer still has customAgent != nil, but+// executeQA runs KnowledgeQA (qaModeNormal). Publishing a steer sink / live+// marker there parks /steer messages on a turn with no engine loop and no+// teardown ClearLiveRun.+func TestSetupSSEStreamNoSinkForQuickAnswerCustomAgent(t *testing.T) {+ streams := stream.NewMemoryStreamManager()+ h := &Handler{streamManager: streams}++ reqCtx := &qaRequestContext{+ ctx: t.Context(),+ c: newSteerWiringGinContext(),+ sessionID: "sess-3",+ requestID: "req-3",+ session: &types.Session{ID: "sess-3"},+ customAgent: &types.CustomAgent{+ ID: "custom-quick",+ Config: types.CustomAgentConfig{AgentMode: types.AgentModeQuickAnswer},+ },+ assistantMessage: &types.Message{+ ID: "assist-3", SessionID: "sess-3", Role: "assistant", CreatedAt: time.Now(),+ },+ }++ streamCtx := h.setupSSEStream(reqCtx, false, qaModeNormal)+ require.NotNil(t, streamCtx)+ assert.Nil(t, streamCtx.steerSink,+ "KnowledgeQA / quick-answer turns must not get a steer sink")+ assert.Nil(t, reqCtx.steerSink)+ assert.Nil(t, reqCtx.buildQARequest().SteerSink)++ liveID, _, err := streams.GetLiveRun(t.Context(), "sess-3")+ require.NoError(t, err)+ assert.Empty(t, liveID,+ "quick-answer custom-agent turns must not publish a live-run marker")+}++// KnowledgeQA can still resolve a smart-reasoning agent_id (API / stale+// client). The teardown that clears the live marker only runs for+// qaModeAgent, so a live marker here would never be released.+func TestSetupSSEStreamNoSinkForKnowledgeQAEvenWithAgentModeAgent(t *testing.T) {+ streams := stream.NewMemoryStreamManager()+ h := &Handler{streamManager: streams}++ reqCtx := &qaRequestContext{+ ctx: t.Context(),+ c: newSteerWiringGinContext(),+ sessionID: "sess-4",+ requestID: "req-4",+ session: &types.Session{ID: "sess-4"},+ customAgent: &types.CustomAgent{+ ID: "custom-react",+ Config: types.CustomAgentConfig{AgentMode: types.AgentModeSmartReasoning},+ },+ assistantMessage: &types.Message{+ ID: "assist-4", SessionID: "sess-4", Role: "assistant", CreatedAt: time.Now(),+ },+ }++ streamCtx := h.setupSSEStream(reqCtx, false, qaModeNormal)+ require.NotNil(t, streamCtx)+ assert.Nil(t, streamCtx.steerSink)+ liveID, _, err := streams.GetLiveRun(t.Context(), "sess-4")+ require.NoError(t, err)+ assert.Empty(t, liveID)+}++func TestSetupSSEStreamDoesNotWriteSSEWhenLiveRunFails(t *testing.T) {+ streams := stream.NewMemoryStreamManager()+ require.NoError(t, streams.SetLiveRun(t.Context(), "sess-5", "other-assist", "req-other"))+ h := &Handler{streamManager: streams}++ gin.SetMode(gin.TestMode)+ w := httptest.NewRecorder()+ c, _ := gin.CreateTestContext(w)+ c.Request = httptest.NewRequest("POST", "/", nil)++ reqCtx := &qaRequestContext{+ c: c,+ ctx: t.Context(),+ sessionID: "sess-5",+ requestID: "req-5",+ session: &types.Session{ID: "sess-5"},+ customAgent: &types.CustomAgent{ID: "agent-1"},+ assistantMessage: &types.Message{+ ID: "assist-5", SessionID: "sess-5", Role: "assistant", CreatedAt: time.Now(),+ },+ }+ streamCtx := h.setupSSEStream(reqCtx, false, qaModeAgent)+ require.True(t, streamCtx.liveRunFailed)+ assert.NotEqual(t, "text/event-stream", w.Header().Get("Content-Type"),+ "SetLiveRun failure must not start an SSE response the client cannot recover from")+}diff --git a/internal/router/routes_chat.go b/internal/router/routes_chat.goindex 5f718bdf5..6dbb85ff3 100644--- a/internal/router/routes_chat.go+++ b/internal/router/routes_chat.go@@ -65,6 +65,14 @@ func RegisterSessionRoutes(sessions.DELETE("/:id/attachments/:attachment_id", handler.DeleteTemporaryDocument)sessions.POST("/:session_id/stop", handler.StopSession)sessions.POST("/:session_id/sandbox/terminal-ticket", handler.IssueSandboxTerminalTicket)+ // Mid-run message injection: append a user message to the turn that is+ // currently generating. Accepts even when no run is live (the client+ // then falls back to a normal send), mirroring StopSession's ownership+ // rules.+ sessions.POST("/:session_id/steer", handler.SteerMessage)+ sessions.GET("/:id/steer", handler.ListSteerMessages)+ sessions.DELETE("/:id/steer/:steer_id", handler.DeleteSteerMessage)+ sessions.POST("/:session_id/steer/:steer_id/inject", handler.PromoteSteerMessage)// POST and DELETE share this path but gin maintains a separate radix tree// per HTTP verb, and the existing trees use different wildcard names// (POST uses :session_id, DELETE uses :id). Use whatever matches eachdiff --git a/internal/stream/factory.go b/internal/stream/factory.goindex 60f9b4a4f..8a3a916c4 100644--- a/internal/stream/factory.go+++ b/internal/stream/factory.go@@ -22,7 +22,10 @@ func NewStreamManager() (interfaces.StreamManager, error) {if err != nil {db = 0}- ttl := time.Hour // 默认1小时+ // Default 1h. Live-run keys are refreshed while the turn is still+ // streaming (AppendEvent / GetEvents / steer writes), so a run that+ // lasts longer than this TTL does not look idle to /steer.+ ttl := time.Hourreturn NewRedisStreamManager(os.Getenv("REDIS_ADDR"),os.Getenv("REDIS_USERNAME"),diff --git a/internal/stream/memory_manager.go b/internal/stream/memory_manager.goindex e30ac4f81..03aa48367 100644--- a/internal/stream/memory_manager.go+++ b/internal/stream/memory_manager.go@@ -11,21 +11,33 @@ import (// memoryStreamData holds stream events in memorytype memoryStreamData struct {events []interfaces.StreamEvent+ steerEvents []interfaces.StreamEvent // control-plane events, never surfaced on SSElastUpdated time.Timemu sync.RWMutex}+// liveRunMarker names the run that is currently generating for a session.+type liveRunMarker struct {+ assistantMessageID string+ requestID string+}+// MemoryStreamManager implements StreamManager using in-memory storagetype MemoryStreamManager struct {// Map: sessionID -> messageID -> stream datastreams map[string]map[string]*memoryStreamData- mu sync.RWMutex+ // Map: sessionID -> the run currently generating. Single-process only,+ // which is exactly why the memory backend is not suitable for a+ // multi-replica deployment (see stream.NewStreamManager).+ liveRuns map[string]liveRunMarker+ mu sync.RWMutex}// NewMemoryStreamManager creates a new in-memory stream managerfunc NewMemoryStreamManager() *MemoryStreamManager {return &MemoryStreamManager{- streams: make(map[string]map[string]*memoryStreamData),+ streams: make(map[string]map[string]*memoryStreamData),+ liveRuns: make(map[string]liveRunMarker),}}@@ -114,5 +126,170 @@ func (m *MemoryStreamManager) GetEvents(return eventsCopy, nextOffset, nil}+// AppendSteerEvents appends control events to the dedicated steer sub-list.+func (m *MemoryStreamManager) AppendSteerEvents(+ _ context.Context,+ sessionID, messageID string,+ events []interfaces.StreamEvent,+) error {+ stream := m.getOrCreateStream(sessionID, messageID)++ stream.mu.Lock()+ defer stream.mu.Unlock()++ for i := range events {+ if events[i].Timestamp.IsZero() {+ events[i].Timestamp = time.Now()+ }+ stream.steerEvents = append(stream.steerEvents, events[i])+ }+ stream.lastUpdated = time.Now()+ return nil+}++// GetSteerEvents drains the steer sub-list starting fromOffset.+func (m *MemoryStreamManager) GetSteerEvents(+ _ context.Context,+ sessionID, messageID string,+ fromOffset int,+) ([]interfaces.StreamEvent, int, error) {+ stream := m.getStream(sessionID, messageID)+ if stream == nil {+ return []interfaces.StreamEvent{}, fromOffset, nil+ }++ stream.mu.RLock()+ defer stream.mu.RUnlock()++ if fromOffset >= len(stream.steerEvents) {+ return []interfaces.StreamEvent{}, fromOffset, nil+ }++ events := stream.steerEvents[fromOffset:]+ nextOffset := len(stream.steerEvents)+ eventsCopy := make([]interfaces.StreamEvent, len(events))+ copy(eventsCopy, events)+ return eventsCopy, nextOffset, nil+}++// UpdateSteerEventData merges keys into a queued steer event's Data map.+func (m *MemoryStreamManager) UpdateSteerEventData(+ _ context.Context,+ sessionID, messageID, eventID string,+ data map[string]interface{},+) (bool, error) {+ stream := m.getStream(sessionID, messageID)+ if stream == nil {+ return false, nil+ }++ stream.mu.Lock()+ defer stream.mu.Unlock()+ for i := range stream.steerEvents {+ if stream.steerEvents[i].ID != eventID {+ continue+ }+ // Copy before mutating: GetSteerEvents hands out a shallow copy of the+ // slice, so callers may still hold the old Data map.+ merged := make(map[string]interface{}, len(stream.steerEvents[i].Data)+len(data))+ for k, v := range stream.steerEvents[i].Data {+ merged[k] = v+ }+ for k, v := range data {+ merged[k] = v+ }+ stream.steerEvents[i].Data = merged+ stream.lastUpdated = time.Now()+ return true, nil+ }+ return false, nil+}++// DeleteSteerEvent removes a queued steer event by ID.+func (m *MemoryStreamManager) DeleteSteerEvent(+ _ context.Context,+ sessionID, messageID, eventID string,+) (bool, error) {+ stream := m.getStream(sessionID, messageID)+ if stream == nil {+ return false, nil+ }++ stream.mu.Lock()+ defer stream.mu.Unlock()+ for i := range stream.steerEvents {+ if stream.steerEvents[i].ID != eventID {+ continue+ }+ if stream.steerEvents[i].Data != nil {+ if consumed, _ := stream.steerEvents[i].Data["consumed"].(bool); consumed {+ return false, nil+ }+ }+ stream.steerEvents = append(stream.steerEvents[:i], stream.steerEvents[i+1:]...)+ stream.lastUpdated = time.Now()+ return true, nil+ }+ return false, nil+}++// SetLiveRun records the session's currently generating assistant message.+func (m *MemoryStreamManager) SetLiveRun(+ _ context.Context,+ sessionID, assistantMessageID, requestID string,+) error {+ m.mu.Lock()+ defer m.mu.Unlock()+ if existing, ok := m.liveRuns[sessionID]; ok && existing.assistantMessageID != assistantMessageID {+ return ErrLiveRunExists+ }+ m.liveRuns[sessionID] = liveRunMarker{+ assistantMessageID: assistantMessageID,+ requestID: requestID,+ }+ return nil+}++// ClaimLiveRun overwrites the live-run marker for follow-up handoff.+func (m *MemoryStreamManager) ClaimLiveRun(+ _ context.Context,+ sessionID, assistantMessageID, requestID string,+) error {+ m.mu.Lock()+ defer m.mu.Unlock()+ m.liveRuns[sessionID] = liveRunMarker{+ assistantMessageID: assistantMessageID,+ requestID: requestID,+ }+ return nil+}++// GetLiveRun returns the session's generating assistant message, if any.+func (m *MemoryStreamManager) GetLiveRun(+ _ context.Context,+ sessionID string,+) (string, string, error) {+ m.mu.RLock()+ defer m.mu.RUnlock()+ marker, ok := m.liveRuns[sessionID]+ if !ok {+ return "", "", nil+ }+ return marker.assistantMessageID, marker.requestID, nil+}++// ClearLiveRun drops the marker only when it still points at assistantMessageID.+func (m *MemoryStreamManager) ClearLiveRun(+ _ context.Context,+ sessionID, assistantMessageID string,+) error {+ m.mu.Lock()+ defer m.mu.Unlock()+ if marker, ok := m.liveRuns[sessionID]; ok && marker.assistantMessageID == assistantMessageID {+ delete(m.liveRuns, sessionID)+ }+ return nil+}+// Ensure MemoryStreamManager implements StreamManager interfacevar _ interfaces.StreamManager = (*MemoryStreamManager)(nil)diff --git a/internal/stream/redis_live_run_test.go b/internal/stream/redis_live_run_test.gonew file mode 100644index 000000000..8545a4316--- /dev/null+++ b/internal/stream/redis_live_run_test.go@@ -0,0 +1,152 @@+package stream++import (+ "context"+ "testing"+ "time"++ "github.com/Tencent/WeKnora/internal/types"+ "github.com/Tencent/WeKnora/internal/types/interfaces"+ "github.com/alicebob/miniredis/v2"+ "github.com/stretchr/testify/require"+)++func newTestRedisStreamManager(t *testing.T, ttl time.Duration) (*RedisStreamManager, *miniredis.Miniredis) {+ t.Helper()+ mini := miniredis.RunT(t)+ mgr, err := NewRedisStreamManager(mini.Addr(), "", "", 0, "test", ttl)+ require.NoError(t, err)+ t.Cleanup(func() { _ = mgr.Close() })+ return mgr, mini+}++// A corrupt live-run marker used to decode as "no run is live". Steer then+// answered new_run and the client started a second AgentQA on top of the+// still-generating turn. Lookup failures must surface as errors instead.+func TestGetLiveRunCorruptJSONIsError(t *testing.T) {+ mgr, mini := newTestRedisStreamManager(t, time.Hour)+ ctx := context.Background()++ require.NoError(t, mini.Set(mgr.buildLiveRunKey("sess-1"), "not-json"))++ id, req, err := mgr.GetLiveRun(ctx, "sess-1")+ require.Error(t, err)+ require.Empty(t, id)+ require.Empty(t, req)+}++func TestGetLiveRunMissingKeyIsEmpty(t *testing.T) {+ mgr, _ := newTestRedisStreamManager(t, time.Hour)++ id, req, err := mgr.GetLiveRun(context.Background(), "sess-missing")+ require.NoError(t, err)+ require.Empty(t, id)+ require.Empty(t, req)+}++// The live-run key is written once with the StreamManager TTL. A turn that+// runs longer than that TTL used to look idle, and /steer answered new_run.+// Streaming (AppendEvent / GetEvents) must refresh the marker.+func TestAppendEventRefreshesLiveRunTTL(t *testing.T) {+ ttl := 2 * time.Second+ mgr, mini := newTestRedisStreamManager(t, ttl)+ ctx := context.Background()++ require.NoError(t, mgr.SetLiveRun(ctx, "sess-1", "assist-1", "req-1"))+ mini.FastForward(ttl - 200*time.Millisecond)++ require.NoError(t, mgr.AppendEvent(ctx, "sess-1", "assist-1", interfaces.StreamEvent{+ ID: "e1",+ Type: types.ResponseTypeAnswer,+ Content: "chunk",+ }))+ mini.FastForward(ttl - 200*time.Millisecond)++ id, _, err := mgr.GetLiveRun(ctx, "sess-1")+ require.NoError(t, err)+ require.Equal(t, "assist-1", id)+}++func TestGetEventsRefreshesLiveRunTTLWhileWaiting(t *testing.T) {+ ttl := 2 * time.Second+ mgr, mini := newTestRedisStreamManager(t, ttl)+ ctx := context.Background()++ require.NoError(t, mgr.SetLiveRun(ctx, "sess-1", "assist-1", "req-1"))+ mini.FastForward(ttl - 200*time.Millisecond)++ _, _, err := mgr.GetEvents(ctx, "sess-1", "assist-1", 0)+ require.NoError(t, err)+ mini.FastForward(ttl - 200*time.Millisecond)++ id, _, err := mgr.GetLiveRun(ctx, "sess-1")+ require.NoError(t, err)+ require.Equal(t, "assist-1", id)+}++func TestAppendSteerEventsRefreshesLiveRunTTL(t *testing.T) {+ ttl := 2 * time.Second+ mgr, mini := newTestRedisStreamManager(t, ttl)+ ctx := context.Background()++ require.NoError(t, mgr.SetLiveRun(ctx, "sess-1", "assist-1", "req-1"))+ mini.FastForward(ttl - 200*time.Millisecond)++ require.NoError(t, mgr.AppendSteerEvents(ctx, "sess-1", "assist-1", []interfaces.StreamEvent{{+ ID: "s1",+ Type: types.ResponseTypeSteer,+ Content: "queued",+ Done: true,+ }}))+ mini.FastForward(ttl - 200*time.Millisecond)++ id, _, err := mgr.GetLiveRun(ctx, "sess-1")+ require.NoError(t, err)+ require.Equal(t, "assist-1", id)+}++func TestSetLiveRunRejectsADifferentAssistant(t *testing.T) {+ mgr, _ := newTestRedisStreamManager(t, time.Hour)+ ctx := context.Background()++ require.NoError(t, mgr.SetLiveRun(ctx, "sess-1", "assist-1", "req-1"))+ require.ErrorIs(t, mgr.SetLiveRun(ctx, "sess-1", "assist-2", "req-2"), ErrLiveRunExists)++ id, req, err := mgr.GetLiveRun(ctx, "sess-1")+ require.NoError(t, err)+ require.Equal(t, "assist-1", id)+ require.Equal(t, "req-1", req)+}++func TestSetLiveRunIsIdempotentForTheSameAssistant(t *testing.T) {+ mgr, _ := newTestRedisStreamManager(t, time.Hour)+ ctx := context.Background()++ require.NoError(t, mgr.SetLiveRun(ctx, "sess-1", "assist-1", "req-1"))+ require.NoError(t, mgr.SetLiveRun(ctx, "sess-1", "assist-1", "req-1"))+}++func TestClaimLiveRunOverwritesTheMarker(t *testing.T) {+ mgr, _ := newTestRedisStreamManager(t, time.Hour)+ ctx := context.Background()++ require.NoError(t, mgr.SetLiveRun(ctx, "sess-1", "assist-1", "req-1"))+ require.NoError(t, mgr.ClaimLiveRun(ctx, "sess-1", "assist-2", "req-2"))++ id, req, err := mgr.GetLiveRun(ctx, "sess-1")+ require.NoError(t, err)+ require.Equal(t, "assist-2", id)+ require.Equal(t, "req-2", req)+}++func TestMemorySetLiveRunRejectsADifferentAssistant(t *testing.T) {+ mgr := NewMemoryStreamManager()+ ctx := context.Background()++ require.NoError(t, mgr.SetLiveRun(ctx, "sess-1", "assist-1", "req-1"))+ require.ErrorIs(t, mgr.SetLiveRun(ctx, "sess-1", "assist-2", "req-2"), ErrLiveRunExists)+ require.NoError(t, mgr.ClaimLiveRun(ctx, "sess-1", "assist-2", "req-2"))+ id, _, err := mgr.GetLiveRun(ctx, "sess-1")+ require.NoError(t, err)+ require.Equal(t, "assist-2", id)+}diff --git a/internal/stream/redis_manager.go b/internal/stream/redis_manager.goindex f5e7e8da4..f6b976e2f 100644--- a/internal/stream/redis_manager.go+++ b/internal/stream/redis_manager.go@@ -3,6 +3,7 @@ package streamimport ("context""encoding/json"+ "errors""fmt""time"@@ -11,6 +12,10 @@ import ("github.com/redis/go-redis/v9")+// ErrLiveRunExists is returned by SetLiveRun when another assistant already+// holds the session. Follow-up handoff uses ClaimLiveRun to overwrite.+var ErrLiveRunExists = errors.New("session already has a live run")+// RedisStreamManager implements StreamManager using Redis Lists for append-only event streamingtype RedisStreamManager struct {client *redis.Client@@ -56,6 +61,13 @@ func (r *RedisStreamManager) buildKey(sessionID, messageID string) string {return fmt.Sprintf("%s:%s:%s", r.prefix, sessionID, messageID)}+// buildSteerKey builds the Redis key for the per-run steer sub-list. Keeping it+// in a separate key keeps control events off the user-visible SSE stream while+// reusing the same TTL lifecycle.+func (r *RedisStreamManager) buildSteerKey(sessionID, messageID string) string {+ return fmt.Sprintf("%s:%s:%s:steer", r.prefix, sessionID, messageID)+}+// AppendEvent appends a single event to the stream using Redis RPushfunc (r *RedisStreamManager) AppendEvent(ctx context.Context,@@ -84,6 +96,7 @@ func (r *RedisStreamManager) AppendEvent(if err := r.client.Expire(ctx, key, r.ttl).Err(); err != nil {return fmt.Errorf("failed to set TTL: %w", err)}+ r.touchLiveRun(ctx, sessionID)return nil}@@ -108,8 +121,11 @@ func (r *RedisStreamManager) GetEvents(return nil, fromOffset, fmt.Errorf("failed to get events from Redis: %w", err)}- // No new events+ // No new events. Still refresh the live-run marker: the SSE poll loop+ // hits this path while the model is thinking, which is exactly when a+ // long turn would otherwise outlive the one-shot SetLiveRun TTL.if len(results) == 0 {+ r.touchLiveRun(ctx, sessionID)return []interfaces.StreamEvent{}, fromOffset, nil}@@ -126,10 +142,343 @@ func (r *RedisStreamManager) GetEvents(// Calculate next offsetnextOffset := fromOffset + len(results)+ r.touchLiveRun(ctx, sessionID)return events, nextOffset, nil}+// AppendSteerEvents appends control events to the per-run steer sub-list.+func (r *RedisStreamManager) AppendSteerEvents(+ ctx context.Context,+ sessionID, messageID string,+ events []interfaces.StreamEvent,+) error {+ if len(events) == 0 {+ return nil+ }+ key := r.buildSteerKey(sessionID, messageID)++ payloads := make([]interface{}, 0, len(events))+ for i := range events {+ if events[i].Timestamp.IsZero() {+ events[i].Timestamp = time.Now()+ }+ eventJSON, err := json.Marshal(events[i])+ if err != nil {+ return fmt.Errorf("failed to marshal steer event: %w", err)+ }+ payloads = append(payloads, eventJSON)+ }++ pipe := r.client.Pipeline()+ pipe.RPush(ctx, key, payloads...)+ pipe.Expire(ctx, key, r.ttl)+ pipe.Expire(ctx, r.buildLiveRunKey(sessionID), r.ttl)+ if _, err := pipe.Exec(ctx); err != nil {+ return fmt.Errorf("failed to append steer events to Redis: %w", err)+ }+ return nil+}++// GetSteerEvents drains the steer sub-list starting fromOffset.+func (r *RedisStreamManager) GetSteerEvents(+ ctx context.Context,+ sessionID, messageID string,+ fromOffset int,+) ([]interfaces.StreamEvent, int, error) {+ key := r.buildSteerKey(sessionID, messageID)++ results, err := r.client.LRange(ctx, key, int64(fromOffset), -1).Result()+ if err != nil {+ if err == redis.Nil {+ return []interfaces.StreamEvent{}, fromOffset, nil+ }+ return nil, fromOffset, fmt.Errorf("failed to get steer events from Redis: %w", err)+ }+ if len(results) == 0 {+ r.touchLiveRun(ctx, sessionID)+ return []interfaces.StreamEvent{}, fromOffset, nil+ }++ events := make([]interfaces.StreamEvent, 0, len(results))+ for _, result := range results {+ var event interfaces.StreamEvent+ if err := json.Unmarshal([]byte(result), &event); err != nil {+ continue+ }+ events = append(events, event)+ }++ r.touchLiveRun(ctx, sessionID)+ return events, fromOffset + len(results), nil+}++// steerUpdateCAS rewrites one list slot only if it still holds the value we+// read. Rebuilding the whole list (DEL + RPUSH) would silently drop a steer+// message appended by another replica in between, so every mutation is either+// a compare-and-set on a single index or an LREM of an exact value.+var steerUpdateCAS = redis.NewScript(`+if redis.call('LINDEX', KEYS[1], ARGV[1]) ~= ARGV[2] then+ return 0+end+redis.call('LSET', KEYS[1], ARGV[1], ARGV[3])+return 1+`)++// steerUpdateMaxAttempts bounds the CAS retry loop. Contention here is one+// user pressing buttons on their own queue, so a lost race is rare and a+// couple of retries is plenty.+const steerUpdateMaxAttempts = 3++// UpdateSteerEventData merges keys into a queued steer event's Data map.+func (r *RedisStreamManager) UpdateSteerEventData(+ ctx context.Context,+ sessionID, messageID, eventID string,+ data map[string]interface{},+) (bool, error) {+ key := r.buildSteerKey(sessionID, messageID)++ for attempt := 0; attempt < steerUpdateMaxAttempts; attempt++ {+ results, err := r.client.LRange(ctx, key, 0, -1).Result()+ if err != nil {+ if err == redis.Nil {+ return false, nil+ }+ return false, fmt.Errorf("failed to read steer events from Redis: %w", err)+ }++ index := -1+ var current string+ var event interfaces.StreamEvent+ for i, result := range results {+ var candidate interfaces.StreamEvent+ if err := json.Unmarshal([]byte(result), &candidate); err != nil {+ continue+ }+ if candidate.ID != eventID {+ continue+ }+ index, current, event = i, result, candidate+ break+ }+ if index < 0 {+ return false, nil+ }++ if event.Data == nil {+ event.Data = map[string]interface{}{}+ }+ for k, v := range data {+ event.Data[k] = v+ }+ payload, err := json.Marshal(event)+ if err != nil {+ return false, fmt.Errorf("failed to marshal steer event: %w", err)+ }++ updated, err := steerUpdateCAS.Run(ctx, r.client, []string{key}, index, current, payload).Int()+ if err != nil {+ return false, fmt.Errorf("failed to update steer event in Redis: %w", err)+ }+ if updated == 1 {+ _ = r.client.Expire(ctx, key, r.ttl).Err()+ return true, nil+ }+ // Someone rewrote or removed that slot; re-read and try again.+ }+ return false, fmt.Errorf("steer event %s changed concurrently, giving up after %d attempts",+ eventID, steerUpdateMaxAttempts)+}++// DeleteSteerEvent removes a queued steer event by ID from Redis.+func (r *RedisStreamManager) DeleteSteerEvent(+ ctx context.Context,+ sessionID, messageID, eventID string,+) (bool, error) {+ key := r.buildSteerKey(sessionID, messageID)+ for attempt := 0; attempt < steerUpdateMaxAttempts; attempt++ {+ results, err := r.client.LRange(ctx, key, 0, -1).Result()+ if err != nil {+ if err == redis.Nil {+ return false, nil+ }+ return false, fmt.Errorf("failed to read steer events from Redis: %w", err)+ }++ var current string+ var event interfaces.StreamEvent+ found := false+ for _, result := range results {+ if err := json.Unmarshal([]byte(result), &event); err != nil {+ continue+ }+ if event.ID != eventID {+ continue+ }+ current = result+ found = true+ break+ }+ if !found {+ return false, nil+ }+ if event.Data != nil {+ if consumed, _ := event.Data["consumed"].(bool); consumed {+ return false, nil+ }+ }+ removed, err := r.client.LRem(ctx, key, 1, current).Result()+ if err != nil {+ return false, fmt.Errorf("failed to delete steer event from Redis: %w", err)+ }+ if removed > 0 {+ return true, nil+ }+ }+ return false, nil+}++// buildLiveRunKey builds the Redis key holding the session's generating run.+func (r *RedisStreamManager) buildLiveRunKey(sessionID string) string {+ return fmt.Sprintf("%s:%s:live-run", r.prefix, sessionID)+}++// liveRunPayload is the stored shape of the live-run marker.+type liveRunPayload struct {+ AssistantMessageID string `json:"assistant_message_id"`+ RequestID string `json:"request_id"`+}++func (r *RedisStreamManager) marshalLiveRun(assistantMessageID, requestID string) ([]byte, error) {+ payload, err := json.Marshal(liveRunPayload{+ AssistantMessageID: assistantMessageID,+ RequestID: requestID,+ })+ if err != nil {+ return nil, fmt.Errorf("failed to marshal live run marker: %w", err)+ }+ return payload, nil+}++// SetLiveRun records the session's currently generating assistant message so+// every replica routes steer requests to the same run. It refuses to+// replace a different live assistant; ClaimLiveRun is the overwrite path.+func (r *RedisStreamManager) SetLiveRun(+ ctx context.Context,+ sessionID, assistantMessageID, requestID string,+) error {+ payload, err := r.marshalLiveRun(assistantMessageID, requestID)+ if err != nil {+ return err+ }+ ok, err := r.client.SetNX(ctx, r.buildLiveRunKey(sessionID), payload, r.ttl).Result()+ if err != nil {+ return fmt.Errorf("failed to set live run marker in Redis: %w", err)+ }+ if ok {+ return nil+ }+ current, _, err := r.GetLiveRun(ctx, sessionID)+ if err != nil {+ return err+ }+ if current == assistantMessageID {+ return nil+ }+ if current == "" {+ ok, err = r.client.SetNX(ctx, r.buildLiveRunKey(sessionID), payload, r.ttl).Result()+ if err != nil {+ return fmt.Errorf("failed to set live run marker in Redis: %w", err)+ }+ if ok {+ return nil+ }+ }+ return ErrLiveRunExists+}++// ClaimLiveRun overwrites the live-run marker for follow-up handoff.+func (r *RedisStreamManager) ClaimLiveRun(+ ctx context.Context,+ sessionID, assistantMessageID, requestID string,+) error {+ payload, err := r.marshalLiveRun(assistantMessageID, requestID)+ if err != nil {+ return err+ }+ if err := r.client.Set(ctx, r.buildLiveRunKey(sessionID), payload, r.ttl).Err(); err != nil {+ return fmt.Errorf("failed to claim live run marker in Redis: %w", err)+ }+ return nil+}++// GetLiveRun returns the session's generating assistant message, if any.+func (r *RedisStreamManager) GetLiveRun(+ ctx context.Context,+ sessionID string,+) (string, string, error) {+ raw, err := r.client.Get(ctx, r.buildLiveRunKey(sessionID)).Result()+ if err != nil {+ if err == redis.Nil {+ return "", "", nil+ }+ return "", "", fmt.Errorf("failed to read live run marker from Redis: %w", err)+ }+ var payload liveRunPayload+ if err := json.Unmarshal([]byte(raw), &payload); err != nil {+ // Do not collapse a corrupt marker into "no run is live": callers+ // treat empty as new_run and would start a second AgentQA.+ return "", "", fmt.Errorf("failed to decode live run marker: %w", err)+ }+ r.touchLiveRun(ctx, sessionID)+ return payload.AssistantMessageID, payload.RequestID, nil+}++// touchLiveRun extends the live-run marker so a turn longer than the+// StreamManager TTL does not look idle. Expire on a missing key is a no-op.+func (r *RedisStreamManager) touchLiveRun(ctx context.Context, sessionID string) {+ if sessionID == "" {+ return+ }+ _ = r.client.Expire(ctx, r.buildLiveRunKey(sessionID), r.ttl).Err()+}++// clearLiveRunCAS deletes the marker only when it still names the run being+// torn down, so a follow-up run that already claimed the session keeps it.+var clearLiveRunCAS = redis.NewScript(`+local raw = redis.call('GET', KEYS[1])+if not raw then+ return 0+end+if string.find(raw, ARGV[1], 1, true) == nil then+ return 0+end+redis.call('DEL', KEYS[1])+return 1+`)++// ClearLiveRun drops the marker only when it still points at assistantMessageID.+func (r *RedisStreamManager) ClearLiveRun(+ ctx context.Context,+ sessionID, assistantMessageID string,+) error {+ if assistantMessageID == "" {+ return nil+ }+ // Match the serialized field rather than decoding in Lua: the marker is+ // written by SetLiveRun above, so the encoding is ours to rely on.+ idJSON, err := json.Marshal(assistantMessageID)+ if err != nil {+ return fmt.Errorf("failed to marshal assistant message id: %w", err)+ }+ needle := `"assistant_message_id":` + string(idJSON)+ if err := clearLiveRunCAS.Run(ctx, r.client,+ []string{r.buildLiveRunKey(sessionID)}, needle).Err(); err != nil && err != redis.Nil {+ return fmt.Errorf("failed to clear live run marker in Redis: %w", err)+ }+ return nil+}+// Close closes the Redis connectionfunc (r *RedisStreamManager) Close() error {return r.client.Close()diff --git a/internal/types/chat.go b/internal/types/chat.goindex 9b4c45ff4..55f5e1b81 100644--- a/internal/types/chat.go+++ b/internal/types/chat.go@@ -250,6 +250,21 @@ const (// MemoryRecalled: the long-term memories injected into this answer, so// the UI can show and let the user delete what influenced it.ResponseTypeMemoryRecalled ResponseType = "memory_recalled"+ // ResponseTypeSteer is the per-run control signal a client POSTs while a+ // turn is still running. It rides the same StreamManager keyspace as the+ // stop event but in a dedicated sub-list (AppendSteerEvents/GetSteerEvents)+ // so it never appears on the user-visible SSE stream. The running engine+ // drains it at the next round boundary (SteerSink.PollSteer) or, when the+ // loop has already exited, the run's teardown paths hand it to the next+ // run — unless the turn was stopped, in which case it is discarded.+ ResponseTypeSteer ResponseType = "steer"+ // ResponseTypeUserMessageInjected is emitted on the user-visible stream+ // right after a steered message was accepted into the running turn: a+ // user-role DB row has been persisted under the run's request_id and the+ // text was appended to the agent's message list. The frontend uses it to+ // move the queued message out of the composer overlay and into the+ // transcript.+ ResponseTypeUserMessageInjected ResponseType = "user_message_injected"// ResponseTypeContextCompacted is older conversation summarized away to// fit the context window. Surfaced because it changes what the agent// remembers — an answer that forgets an earlier instruction is otherwisediff --git a/internal/types/interfaces/agent.go b/internal/types/interfaces/agent.goindex 889b0428f..ab3edd8bc 100644--- a/internal/types/interfaces/agent.go+++ b/internal/types/interfaces/agent.go@@ -32,6 +32,12 @@ type AgentEngine interface {// SetMemoryPrompt supplies the long-term memory envelope for this run.// It must be called before Execute; an empty string is a no-op.SetMemoryPrompt(prompt string)++ // SetSteerSink enables mid-run message injection for this run. Nil+ // (default) disables it; when set, the engine drains user-appended+ // messages at every round boundary and persists accepted ones through+ // the sink. Must be called before Execute.+ SetSteerSink(sink types.SteerSink)}// AgentService defines the interface for agent-related operationsdiff --git a/internal/types/interfaces/stream_manager.go b/internal/types/interfaces/stream_manager.goindex 6ff3acd92..aa5f69512 100644--- a/internal/types/interfaces/stream_manager.go+++ b/internal/types/interfaces/stream_manager.go@@ -30,4 +30,45 @@ type StreamManager interface {// Uses Redis LRange for incremental reads// Returns: events slice, next offset for subsequent reads, errorGetEvents(ctx context.Context, sessionID, messageID string, fromOffset int) ([]StreamEvent, int, error)++ // AppendSteerEvents appends control events (steer instructions) to a+ // dedicated per-run sub-list that is never surfaced on the SSE stream.+ // Producers are incoming "append a message to the running turn" HTTP+ // requests; the only consumer is the running turn itself.+ AppendSteerEvents(ctx context.Context, sessionID, messageID string, events []StreamEvent) error++ // GetSteerEvents drains the steer sub-list starting fromOffset, mirroring+ // GetEvents semantics. An absent list is an empty result, not an error.+ GetSteerEvents(ctx context.Context, sessionID, messageID string, fromOffset int) ([]StreamEvent, int, error)++ // UpdateSteerEventData merges keys into a queued steer event's Data map+ // (promote to inject, mark consumed). Returns false when the event is+ // missing. Implementations must apply the change atomically so a+ // concurrent AppendSteerEvents cannot be lost.+ UpdateSteerEventData(+ ctx context.Context, sessionID, messageID, eventID string, data map[string]interface{},+ ) (bool, error)++ // DeleteSteerEvent removes a queued steer event by ID. Returns false when+ // the event is missing. Used when the user dismisses an overlay item.+ DeleteSteerEvent(ctx context.Context, sessionID, messageID, eventID string) (bool, error)++ // SetLiveRun records which assistant message is currently generating for+ // a session. It is exclusive: if another assistant is already live, it+ // returns an error so executeQA cannot start a second engine. Calling it+ // again for the same assistant is a no-op. Follow-up handoff that must+ // replace the previous run uses ClaimLiveRun.+ SetLiveRun(ctx context.Context, sessionID, assistantMessageID, requestID string) error++ // ClaimLiveRun overwrites the live-run marker. Used when a finishing+ // turn hands the session to a follow-up before it CAS-clears itself.+ ClaimLiveRun(ctx context.Context, sessionID, assistantMessageID, requestID string) error++ // GetLiveRun returns the session's generating assistant message, or empty+ // strings when no run is marked live.+ GetLiveRun(ctx context.Context, sessionID string) (assistantMessageID, requestID string, err error)++ // ClearLiveRun drops the marker, but only when it still points at+ // assistantMessageID: a follow-up run may already have replaced it.+ ClearLiveRun(ctx context.Context, sessionID, assistantMessageID string) error}diff --git a/internal/types/message.go b/internal/types/message.goindex a2a2f3505..18c0a2d9b 100644--- a/internal/types/message.go+++ b/internal/types/message.go@@ -35,6 +35,60 @@ type MentionedItem struct {SkillName string `json:"skill_name"` // Preloaded agent skill name}+// MapString reads a string from a JSON-decoded map.+func MapString(m map[string]interface{}, key string) string {+ if v, ok := m[key].(string); ok {+ return v+ }+ return ""+}++// MentionedItemsFromRaw rebuilds typed mentions from the JSON-safe shape+// stored on steer events and similar maps.+func MentionedItemsFromRaw(raw interface{}) MentionedItems {+ list, ok := raw.([]interface{})+ if !ok {+ return nil+ }+ out := make(MentionedItems, 0, len(list))+ for _, item := range list {+ m, ok := item.(map[string]interface{})+ if !ok {+ continue+ }+ out = append(out, MentionedItem{+ ID: MapString(m, "id"),+ Name: MapString(m, "name"),+ Type: MapString(m, "type"),+ KBType: MapString(m, "kb_type"),+ KBID: MapString(m, "kb_id"),+ KBName: MapString(m, "kb_name"),+ ServiceID: MapString(m, "service_id"),+ SkillName: MapString(m, "skill_name"),+ })+ }+ return out+}++// MentionedItemsToRaw converts typed mentions into plain values that survive+// Redis JSON round-trips without a second unmarshal type on the read side.+func MentionedItemsToRaw(items MentionedItems) []interface{} {+ out := make([]interface{}, 0, len(items))+ for _, item := range items {+ out = append(out, map[string]interface{}{+ "id": item.ID,+ "name": item.Name,+ "type": item.Type,+ "kb_type": item.KBType,+ "kb_id": item.KBID,+ "kb_name": item.KBName,+ "service_id": item.ServiceID,+ "skill_name": item.SkillName,+ })+ }+ return out+}+// MessageImage represents an image attached to a chat messagetype MessageImage struct {URL string `json:"url"`diff --git a/internal/types/qa_request.go b/internal/types/qa_request.goindex 90eba26e3..5c2eb3b4a 100644--- a/internal/types/qa_request.go+++ b/internal/types/qa_request.go@@ -1,5 +1,36 @@package types+import (+ "context"+)++// SteerSink abstracts the handler-side back half of mid-run message+// injection: draining the queued steer events and persisting accepted+// messages. Declared in types (not agent/interfaces) because both packages+// need the shape and neither may import the other; the engine accepts any+// value implementing it.+type SteerSink interface {+ // PollSteer returns pending inject events as {id, content, mentioned_items,+ // channel} maps. lastOffset is unused: consumed flags (not a numeric+ // offset) are what skip already-handled events, so an after→inject+ // promote of a previously skipped item stays visible. An empty/absent+ // queue is an empty result. PersistSteerMessage is what marks an event+ // consumed, after the user row exists.+ PollSteer(ctx context.Context, sessionID, messageID string, lastOffset int) ([]map[string]interface{}, int, error)+ // PersistSteerMessage stores the accepted message as a user-role row+ // under the run's request ID and returns the new row's ID. An empty ID+ // means persistence failed: the caller must not append the text, so the+ // next drain can retry. Mentions are recorded for history only — the+ // running turn's scope is not widened mid-flight.+ // channel is the source of the steered send ("web", "api", "im"); empty+ // is stored as "web".+ PersistSteerMessage(+ ctx context.Context, sessionID, messageID, steerID, content string,+ mentionedItems MentionedItems,+ channel string,+ ) string+}+// QARequest consolidates all parameters for KnowledgeQA and AgentQA service calls,// replacing the previous 14-parameter method signatures.// EventBus is passed separately to avoid circular dependency with the event package.@@ -21,4 +52,9 @@ type QARequest struct {WebSearchEnabled bool // Whether web search is enabled for this requestQuotedContext string // Quoted message content from IM quote-reply (appended at LLM prompt stage, not used for retrieval)Attachments MessageAttachments // File attachments (processed and ready for prompt injection)+ // SteerSink, when set, enables mid-run message injection for this run:+ // the engine drains user-appended messages at every round boundary and+ // persists accepted ones through this sink. A structural interface so+ // neither package imports the other; handler-owned, nil for IM/embed.+ SteerSink SteerSink}