Skip to content

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

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.ts
new file mode 100644
index 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.mjs
index 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.vue
index 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" multiple
style="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.mjs
index 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.ts
index 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) => void
onAgentAnswerDone?: (message: ChatMessage) => void
onAgentChunkBound?: (message: ChatMessage, created: boolean) => void
+ onUserMessageInjected?: (steerId: string) => void
+ /** Remote or local stop: the composer overlay must drop server-discarded items. */
+ onGenerationStopped?: () => void
debug?: 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 | undefined
if (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') return
message.isAgentMode = true
if (!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 true
return 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 false
if (item.request_id === payload.id) return true
return 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 = true
onAgentAnswerDone?.(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 = !existingMessage
if (!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 === true
const 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 = false
isReplying.value = false
currentAssistantMessageId.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 false
if (item.request_id === data.id) return true
return item.id === data.id
})
@@ -1081,10 +1164,12 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {
isReplying.value = false
fullContent.value = ''
currentAssistantMessageId.value = ''
+ onGenerationStopped?.()
return
}
const existingMessage = findLastMessage((item) => {
+ if (item.role !== 'assistant') return false
if (item.request_id === data.id) return true
return item.id === data.id
})
diff --git a/frontend/src/i18n/locales/en-US.ts b/frontend/src/i18n/locales/en-US.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.mjs
new file mode 100644
index 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.ts
new file mode 100644
index 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.vue
index 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 true
const 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.mjs
index 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.vue
index 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 = [];
// 初始化状态:加载历史消息时不应显示loading
loading.value = false;
diff --git a/frontend/src/views/chat/steerFollowUp.test.mjs b/frontend/src/views/chat/steerFollowUp.test.mjs
new file mode 100644
index 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.go
index 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 int
modelContext *modelcontext.Registry // single request-local boundary for every model handle
+ // steerSink, when set, lets users append messages into the running turn.
+ // Drained at every round boundary; nil disables mid-run injection.
+ steerSink types.SteerSink
+ allowSteerOverrun bool // one extra ReAct round after a loop-end inject past MaxIterations
+ steerOverruns int // how many times this turn has already used the extra round
}
+// 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 := 0
lastResponseContent := ""
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 = true
state.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.finalAnswer
state.IsComplete = true
state.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.go
index 165a5768a..98c12acd0 100644
--- a/internal/agent/observe.go
+++ b/internal/agent/observe.go
@@ -322,6 +322,11 @@ type responseVerdict struct {
finalAnswer string
emptyContent bool // LLM returned stop with no tool calls and empty content
step 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
index 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.Message
assistant *types.Message
createdAt 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.go
index 7c57e4527..5f45af07b 100644
--- a/internal/application/service/agent_history_test.go
+++ b/internal/application/service/agent_history_test.go
@@ -3,6 +3,7 @@ package service
import (
"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.go
index 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.Query
var agentImageURLs []string
if 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.go
index 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 *installFixture
diff --git a/internal/application/service/tenant_skill_transcript_test.go b/internal/application/service/tenant_skill_transcript_test.go
index 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.go
index 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 events
EventSessionTitle EventType = "session_title" // 会话标题更新
diff --git a/internal/event/event_data.go b/internal/event/event_data.go
index 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 data
type AgentReflectionData struct {
ToolCallID string `json:"tool_call_id"` // Tool call ID for tracking
diff --git a/internal/handler/sandbox_skill_test.go b/internal/handler/sandbox_skill_test.go
index 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.go
index 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.E
return 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 events
func (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.go
index 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.go
index 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 bool
reqAgentID string
+
+ // skipSSE is set for server-started follow-up runs (steer backlog after
+ // the previous turn exits). Events still land in StreamManager so the
+ // client can attach via continue-stream; nothing is written to gin.
+ skipSSE bool
+ // steerCarryOver is appended to this run's steer sub-list before the run
+ // is published as live, so leftover inject / after messages from the
+ // previous run are visible to this engine from round 1 and to any client
+ // that reloads the queue.
+ steerCarryOver []interfaces.StreamEvent
}
// 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.Context
cancel context.CancelFunc
assistantMessage *types.Message
+ // steerSink bridges the engine's round-boundary drain to the steer
+ // sub-list and user-row persistence. Nil for non-agent modes.
+ steerSink *steerSink
+ // liveRunFailed is set when SetLiveRun failed. executeQA must not start
+ // the engine: /steer would see no marker and the client would start a
+ // second turn.
+ liveRunFailed bool
+ liveRunErr error
}
// 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 resolution
baseCtx := reqCtx.ctx
if 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 context
eventBus := 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 handler
h.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 creation
if 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 = assistantMessagePtr
if mode == qaModeNormal {
logger.Infof(ctx, "Using knowledge bases: %v", reqCtx.knowledgeBaseIDs)
@@ -954,8 +1112,34 @@ func (h *Handler) executeQA(reqCtx *qaRequestContext, mode qaMode, generateTitle
logger.Infof(ctx, "Calling agent QA service, session ID: %s", sessionID)
}
+ // Move the previous run's leftovers onto this run's queue before the run
+ // announces itself as live. The other order leaves a window where a
+ // client that reloads the queue sees an empty one and drops messages the
+ // user can still see in the composer.
+ if len(reqCtx.steerCarryOver) > 0 && reqCtx.assistantMessage != nil {
+ if err := h.streamManager.AppendSteerEvents(
+ ctx, sessionID, reqCtx.assistantMessage.ID, reqCtx.steerCarryOver,
+ ); err != nil {
+ logger.Warnf(ctx, "steer carry-over append failed for session %s: %v", sessionID, err)
+ }
+ }
+
// Setup SSE stream
- streamCtx := h.setupSSEStream(reqCtx, generateTitle)
+ 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, generateTitle
context.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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
new file mode 100644
index 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.go
index 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 each
diff --git a/internal/stream/factory.go b/internal/stream/factory.go
index 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.Hour
return NewRedisStreamManager(
os.Getenv("REDIS_ADDR"),
os.Getenv("REDIS_USERNAME"),
diff --git a/internal/stream/memory_manager.go b/internal/stream/memory_manager.go
index 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 memory
type memoryStreamData struct {
events []interfaces.StreamEvent
+ steerEvents []interfaces.StreamEvent // control-plane events, never surfaced on SSE
lastUpdated time.Time
mu 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 storage
type MemoryStreamManager struct {
// Map: sessionID -> messageID -> stream data
streams 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 manager
func 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 interface
var _ interfaces.StreamManager = (*MemoryStreamManager)(nil)
diff --git a/internal/stream/redis_live_run_test.go b/internal/stream/redis_live_run_test.go
new file mode 100644
index 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.go
index f5e7e8da4..f6b976e2f 100644
--- a/internal/stream/redis_manager.go
+++ b/internal/stream/redis_manager.go
@@ -3,6 +3,7 @@ package stream
import (
"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 streaming
type 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 RPush
func (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 offset
nextOffset := 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 connection
func (r *RedisStreamManager) Close() error {
return r.client.Close()
diff --git a/internal/types/chat.go b/internal/types/chat.go
index 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 otherwise
diff --git a/internal/types/interfaces/agent.go b/internal/types/interfaces/agent.go
index 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 operations
diff --git a/internal/types/interfaces/stream_manager.go b/internal/types/interfaces/stream_manager.go
index 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, error
GetEvents(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.go
index 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 message
type MessageImage struct {
URL string `json:"url"`
diff --git a/internal/types/qa_request.go b/internal/types/qa_request.go
index 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 request
QuotedContext 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
}