Skip to content

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

fix(agent): end the turn when the completion cap truncates an answer (#3449)

lyingbug093c16cbb367
diff --git a/frontend/src/composables/useChatStreamHandler.test.mjs b/frontend/src/composables/useChatStreamHandler.test.mjs
index 3b7ecca8a..2ee0152d5 100644
--- a/frontend/src/composables/useChatStreamHandler.test.mjs
+++ b/frontend/src/composables/useChatStreamHandler.test.mjs
@@ -236,3 +236,65 @@ test('a superseded prior round does not block or re-seed the new round', () => {
assert.equal(message._eventMap.get('r2').content, '正式答案')
assert.equal(message.content, '正式答案')
})
+
+// A round the completion cap cut off marks its agent step. History is rebuilt
+// from agent_steps and never replays the live answer events, so the rebuilt
+// answer event has to carry the flag forward or a reloaded half-written answer
+// looks finished.
+const buildReconstruct = () => {
+ const helperStart = source.indexOf('const agentStepsAreTruncated =')
+ const start = source.indexOf('const reconstructEventStreamFromSteps = (')
+ const end = source.indexOf('const handleMsgList = async (', start)
+ const block = source.slice(helperStart, end)
+ return vm.runInNewContext(
+ ts.transpile(`(() => { ${block}; return reconstructEventStreamFromSteps })()`),
+ { markRaw: (v) => v, steerStepEvents: () => [] },
+ )
+}
+
+test('a truncated agent step marks the rebuilt answer event', () => {
+ const reconstruct = buildReconstruct()
+ const steps = [
+ { iteration: 0, thought: 'looking it up', tool_calls: [{ id: 'c1', name: 'wiki_read_page' }] },
+ { iteration: 1, thought: '', tool_calls: [], truncated: true },
+ ]
+ const events = reconstruct(steps, '1. First point. 2. Second po', true, false, 0, undefined)
+ const answer = events.filter((e) => e.type === 'answer').at(-1)
+ assert.equal(answer.content, '1. First point. 2. Second po')
+ assert.equal(answer.truncated, true)
+})
+
+test('an ordinary finished turn is not marked truncated', () => {
+ const reconstruct = buildReconstruct()
+ const steps = [{ iteration: 0, thought: '', tool_calls: [] }]
+ const events = reconstruct(steps, 'a complete answer', true, false, 0, undefined)
+ const answer = events.filter((e) => e.type === 'answer').at(-1)
+ assert.equal(answer.content, 'a complete answer')
+ assert.equal(answer.truncated, undefined)
+})
+
+test('the live answer path carries truncated onto the event and the message', () => {
+ const chunkStart = source.indexOf("case 'answer':")
+ const chunk = source.slice(chunkStart, source.indexOf("case 'artifacts_pending'", chunkStart))
+ const state = { fullContent: { value: '' } }
+ const process = vm.runInNewContext(
+ ts.transpile(`(message, data, dataPayload) => { switch ('answer') { ${chunk} } }`),
+ {
+ ...state,
+ recomposeAgentAnswer: (m) =>
+ (m.agentEventStream || []).filter((e) => e.type === 'answer' && !e.superseded).map((e) => e.content || '').join(''),
+ log() {},
+ onAgentAnswerDone() {},
+ isAgentStreamSession: () => true,
+ loading: { value: true },
+ isReplying: { value: true },
+ },
+ )
+ const message = { agentEventStream: [], _eventMap: new Map(), content: '' }
+ process(message, { content: 'half an answer' }, { event_id: 'r1' })
+ assert.equal(message.truncated, undefined)
+ // The cap is only known at the close, so the Done marker carries it too.
+ process(message, { content: '' }, { event_id: 'r1', done: true, truncated: true })
+ assert.equal(message._eventMap.get('r1').truncated, true)
+ assert.equal(message.truncated, true)
+})
diff --git a/frontend/src/composables/useChatStreamHandler.ts b/frontend/src/composables/useChatStreamHandler.ts
index 3268dadaa..e055b3d38 100644
--- a/frontend/src/composables/useChatStreamHandler.ts
+++ b/frontend/src/composables/useChatStreamHandler.ts
@@ -317,6 +317,10 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {
return out
}
+ const agentStepsAreTruncated = (agentSteps: unknown[] | undefined) =>
+ Array.isArray(agentSteps) &&
+ agentSteps.some((step) => (step as ChatMessage | undefined)?.truncated === true)
+
const reconstructEventStreamFromSteps = (
agentSteps: unknown[],
messageContent: string,
@@ -407,6 +411,11 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {
done: true,
}
if (isFallback) answerEvent.is_fallback = true
+ // A round the completion cap cut off marks its step. Live streaming
+ // carries the same fact on the answer event, but history is rebuilt from
+ // agent_steps and never sees those events, so without this a reloaded
+ // half-written answer looks finished.
+ if (agentStepsAreTruncated(agentSteps)) answerEvent.truncated = true
events.push(answerEvent)
} else if (isCompleted) {
events.push({
@@ -459,6 +468,7 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {
),
)
item.hideContent = true
+ if (agentStepsAreTruncated(item.agent_steps as unknown[])) item.truncated = true
}
restoreQuickAnswerFlags(item)
@@ -934,6 +944,13 @@ export function useChatStreamHandler(options: UseChatStreamHandlerOptions) {
answerEvent.is_fallback = true
message.is_fallback = true
}
+ // The completion cap cut this answer off. The backend sends it on the
+ // content chunks and again on the Done marker, because an answer that
+ // streamed live only learns of the cap at the close.
+ if (dataPayload?.truncated) {
+ answerEvent.truncated = true
+ message.truncated = true
+ }
if (data.done && !answerEvent.done) {
answerEvent.done = true
onAgentAnswerDone?.(message)
diff --git a/frontend/src/i18n/locales/en-US.ts b/frontend/src/i18n/locales/en-US.ts
index afa3cd03d..cae7aed56 100755
--- a/frontend/src/i18n/locales/en-US.ts
+++ b/frontend/src/i18n/locales/en-US.ts
@@ -3701,6 +3701,7 @@ export default {
questionMinimapAttachmentPlaceholder: '(Attachment)',
referenceChunkCount: '{count} chunk(s)',
fallbackHint: 'No relevant content found in knowledge base. Above is a direct response from the model.',
+ truncatedHint: 'This answer was cut off at the per-response output limit. Above is what the model produced before the cut.',
requestInfoTitle: 'Request info',
requestInfoRequestId: 'Request ID',
requestInfoMessageId: 'Message ID',
diff --git a/frontend/src/i18n/locales/ja-JP.ts b/frontend/src/i18n/locales/ja-JP.ts
index 932faed31..6d4cb9c5b 100644
--- a/frontend/src/i18n/locales/ja-JP.ts
+++ b/frontend/src/i18n/locales/ja-JP.ts
@@ -3701,6 +3701,7 @@ export default {
questionMinimapAttachmentPlaceholder: '(添付ファイル)',
referenceChunkCount: '{count}件のチャンク',
fallbackHint: 'ナレッジベースから関連する内容が見つかりませんでした。上記はモデルの直接回答です。',
+ truncatedHint: 'モデルの1回あたりの出力上限で回答が途中で打ち切られました。上記は打ち切り前に生成された内容です。',
requestInfoTitle: 'リクエスト情報',
requestInfoRequestId: 'Request ID',
requestInfoMessageId: 'メッセージID',
diff --git a/frontend/src/i18n/locales/ko-KR.ts b/frontend/src/i18n/locales/ko-KR.ts
index 7a05c85f3..ceb4b2307 100755
--- a/frontend/src/i18n/locales/ko-KR.ts
+++ b/frontend/src/i18n/locales/ko-KR.ts
@@ -3827,6 +3827,7 @@ export default {
questionMinimapAttachmentPlaceholder: '(첨부)',
referenceChunkCount: '{count}개 청크',
fallbackHint: '지식 베이스에서 관련 내용을 찾지 못했습니다. 위는 모델의 직접 응답입니다.',
+ truncatedHint: '모델의 응답당 출력 한도에서 답변이 잘렸습니다. 위 내용은 잘리기 전까지 생성된 부분입니다.',
requestInfoTitle: 'Request info',
requestInfoRequestId: 'Request ID',
requestInfoMessageId: 'Message ID',
diff --git a/frontend/src/i18n/locales/ru-RU.ts b/frontend/src/i18n/locales/ru-RU.ts
index 3321ee933..8c77cae7d 100755
--- a/frontend/src/i18n/locales/ru-RU.ts
+++ b/frontend/src/i18n/locales/ru-RU.ts
@@ -3827,6 +3827,7 @@ export default {
questionMinimapAttachmentPlaceholder: '(Вложение)',
referenceChunkCount: '{count} фрагмент(ов)',
fallbackHint: 'В базе знаний не найдено релевантного содержимого. Выше представлен прямой ответ модели.',
+ truncatedHint: 'Ответ обрезан на лимите вывода модели за один ответ. Выше — то, что было создано до обрыва.',
requestInfoTitle: 'Request info',
requestInfoRequestId: 'Request ID',
requestInfoMessageId: 'Message ID',
diff --git a/frontend/src/i18n/locales/zh-CN.ts b/frontend/src/i18n/locales/zh-CN.ts
index 8d7eed33f..1939eccd0 100755
--- a/frontend/src/i18n/locales/zh-CN.ts
+++ b/frontend/src/i18n/locales/zh-CN.ts
@@ -3829,6 +3829,7 @@ export default {
questionMinimapAttachmentPlaceholder: '(附件)',
referenceChunkCount: '{count}个片段',
fallbackHint: '未从知识库中检索到相关内容,以上为模型直接回答',
+ truncatedHint: '回答在模型单次输出上限处被截断,以上为截断前已生成的内容',
requestInfoTitle: '请求信息',
requestInfoRequestId: 'Request ID',
requestInfoMessageId: '消息 ID',
diff --git a/frontend/src/views/chat/components/AgentStreamDisplay.vue b/frontend/src/views/chat/components/AgentStreamDisplay.vue
index 8f2464221..fcdeb7f37 100644
--- a/frontend/src/views/chat/components/AgentStreamDisplay.vue
+++ b/frontend/src/views/chat/components/AgentStreamDisplay.vue
@@ -418,6 +418,11 @@
<t-icon name="info-circle" />
</t-button>
</t-tooltip>
+ <t-tooltip v-if="event.truncated" :content="$t('chat.truncatedHint')" placement="top">
+ <t-button size="small" variant="outline" shape="round" class="fallback-icon-btn">
+ <t-icon name="info-circle" />
+ </t-button>
+ </t-tooltip>
<ChatRequestInfoButton v-if="showRequestInfo && isConversationDone" :session="session"
:session-id="sessionId" />
<transition name="follow-up-toolbar-loading">
diff --git a/frontend/src/views/chat/components/botmsg.vue b/frontend/src/views/chat/components/botmsg.vue
index d92a941ae..b8c392bca 100644
--- a/frontend/src/views/chat/components/botmsg.vue
+++ b/frontend/src/views/chat/components/botmsg.vue
@@ -85,6 +85,12 @@
<t-icon name="info-circle" />
</t-button>
</t-tooltip>
+ <!-- 输出被单次上限截断的提示 -->
+ <t-tooltip v-if="session.truncated" :content="$t('chat.truncatedHint')" placement="top">
+ <t-button size="small" variant="outline" shape="round" class="fallback-icon-btn">
+ <t-icon name="info-circle" />
+ </t-button>
+ </t-tooltip>
<ChatRequestInfoButton v-if="showRequestInfo" :session="session" :session-id="sessionId" />
<transition name="follow-up-toolbar-loading">
<span v-if="followUpLoading" class="answer-toolbar__follow-up-loading" role="status"
diff --git a/internal/agent/const.go b/internal/agent/const.go
index 8cdeb618f..438638309 100644
--- a/internal/agent/const.go
+++ b/internal/agent/const.go
@@ -51,9 +51,31 @@ const (
// where the LLM returns identical content without any tool calls before
// the loop is forcibly terminated. This catches stuck loops caused by
// unhandled finish reasons (e.g., content_filter not caught elsewhere).
+ // "Identical" includes an identical lack of content: consecutive empty
+ // rounds are the clearest stuck loop there is.
maxRepeatedResponseRounds = 2
+
+ // maxConsecutiveLengthRounds is how many rounds in a row may be cut off at
+ // the completion-token cap before the loop gives up. A truncated answer
+ // already ends the turn (analyzeResponse Case 2), so reaching this limit
+ // means round after round is truncating inside tool-call arguments: the
+ // model is told to re-issue the call, writes an even longer one, and hits
+ // the cap again. Without this the turn burns its whole round budget.
+ maxConsecutiveLengthRounds = 3
)
+// truncatedAnswerFallback is delivered when every attempt at this turn was cut
+// off at the completion cap and none of them produced answer text — there is
+// nothing partial to hand over, so say what happened instead of finishing with
+// an empty message.
+const truncatedAnswerFallback = "Sorry, this answer kept hitting the model's per-response output limit " +
+ "before any text was produced. Try narrowing the question, or raise the agent's " +
+ "max_completion_tokens setting."
+
+// stalledAnswerFallback is delivered when a no-progress guard stopped the turn
+// and the round that tripped it produced no text.
+const stalledAnswerFallback = "I'm sorry, I was unable to generate a response. Please try again."
+
func toolExecutionTimeout(toolName string, arguments ...string) time.Duration {
if toolName == "local_browser" && len(arguments) > 0 {
var input struct {
diff --git a/internal/agent/engine.go b/internal/agent/engine.go
index 319e0fb20..dceea8f8e 100644
--- a/internal/agent/engine.go
+++ b/internal/agent/engine.go
@@ -467,10 +467,31 @@ 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) {
+// loopGuards is the per-turn state the ReAct loop uses to notice it is not
+// making progress. All three counters exist because a model can keep the loop
+// spinning without ever finishing: empty answers, the same answer repeated,
+// and rounds cut off at the completion-token cap.
+type loopGuards struct {
+ // emptyRetries counts nudges sent after a stop with no content.
+ emptyRetries int
+ // consecutiveSameContent counts plain rounds that repeated the previous
+ // plain round verbatim, an identical lack of content included.
+ consecutiveSameContent int
+ // sawPlainRound records whether lastResponseContent holds a real
+ // observation yet, so the first plain round of a turn is never counted as
+ // a repeat of the zero value.
+ sawPlainRound bool
+ lastResponseContent string
+ // consecutiveLength counts rounds in a row that the provider cut off at
+ // the completion-token cap.
+ consecutiveLength int
+}
+
+// closeAnswerStream emits the Done:true marker for an answer that is actually
+// finishing. Loop-end inject skips this so the client does not drop isReplying
+// while the engine continues. truncated rides along on the marker because an
+// answer streamed live only finds out about the completion cap at the close.
+func (e *AgentEngine) closeAnswerStream(ctx context.Context, sessionID, answerID string, truncated bool) {
if e.eventBus == nil || answerID == "" {
return
}
@@ -479,12 +500,65 @@ func (e *AgentEngine) closeAnswerStream(ctx context.Context, sessionID, answerID
Type: event.EventAgentFinalAnswer,
SessionID: sessionID,
Data: event.AgentFinalAnswerData{
- Content: "",
- Done: true,
+ Content: "",
+ Done: true,
+ Truncated: truncated,
},
})
}
+// finishStalledTurn ends a turn that a guard stopped rather than the model.
+// Whatever text the last round produced stands as the answer; when the round
+// produced none, a fallback says why instead of completing with an empty
+// message. The answer stream is closed here because no natural-stop path will
+// reach it once the loop breaks.
+func (e *AgentEngine) finishStalledTurn(
+ ctx context.Context,
+ state *types.AgentState,
+ sessionID string,
+ response *types.ChatResponse,
+ truncated bool,
+) {
+ // Text that arrived alongside tool calls is a preamble — "let me look that
+ // up" — from a round that meant to keep working. Presenting it as the final
+ // answer would show an opening line and call the turn finished, so the
+ // fallback speaks for it instead.
+ answer := response.Content
+ if len(response.ToolCalls) > 0 {
+ answer = ""
+ }
+ answerID := ""
+ if response.AnswerStreamed && answer != "" {
+ answerID = response.AnswerEventID
+ }
+ if strings.TrimSpace(answer) == "" {
+ answer = stalledAnswerFallback
+ if truncated {
+ answer = truncatedAnswerFallback
+ }
+ answerID = ""
+ }
+ // No answer stream reached the client for this text: the round never
+ // streamed it, or it is the fallback just chosen. Emit it once so the turn
+ // does not end on a Done marker for content the client never saw.
+ if answerID == "" && e.eventBus != nil {
+ answerID = generateEventID("answer")
+ _ = e.eventBus.Emit(ctx, event.Event{
+ ID: answerID,
+ Type: event.EventAgentFinalAnswer,
+ SessionID: sessionID,
+ Data: event.AgentFinalAnswerData{
+ Content: answer,
+ Done: false,
+ Truncated: truncated,
+ },
+ })
+ }
+ e.closeAnswerStream(ctx, sessionID, answerID, truncated)
+ state.FinalAnswer = answer
+ state.IsComplete = true
+}
+
func (e *AgentEngine) maxIterationsDisplay() string {
if e.config != nil && e.config.UnlimitedIterations() {
return "unlimited"
@@ -529,9 +603,7 @@ func (e *AgentEngine) executeLoop(
}
defer emitCompletion()
- emptyRetries := 0
- consecutiveSameContent := 0
- lastResponseContent := ""
+ guards := &loopGuards{}
loop:
for e.withinIterationBudget(state.CurrentRound) || e.allowSteerOverrun {
e.allowSteerOverrun = false
@@ -564,7 +636,7 @@ loop:
// every exit path (break/continue/next) without having to sprinkle
// manual finish calls throughout the many branches below.
outcome, iterErr := e.runReActIteration(ctx, state, &messages, tools,
- sessionID, messageID, query, &emptyRetries, &consecutiveSameContent, &lastResponseContent)
+ sessionID, messageID, query, guards)
if iterErr != nil {
return state, iterErr
}
@@ -611,16 +683,15 @@ const (
// single `defer span.Finish()` scope — otherwise we'd need to sprinkle
// manual finish calls across every break/continue/return branch.
//
-// The mutable loop state (messages, empty-retry counter, stuck-loop detector)
-// is passed by pointer so iterations share progress.
+// The mutable loop state (messages and the no-progress guards) is shared
+// across iterations so each round can see what the previous ones did.
func (e *AgentEngine) runReActIteration(
parentCtx context.Context,
state *types.AgentState,
messagesPtr *[]chat.Message,
tools []chat.Tool,
sessionID, assistantMessageID, query string,
- emptyRetries, consecutiveSameContent *int,
- lastResponseContent *string,
+ guards *loopGuards,
) (outcome iterOutcome, retErr error) {
roundStart := time.Now()
round := state.CurrentRound + 1
@@ -750,25 +821,71 @@ func (e *AgentEngine) runReActIteration(
response.Usage.PromptCacheHitRate(), response.Usage.CacheStatus)
}
- // Detect stuck loops: if the LLM keeps returning the same content
- // without tool calls (e.g., an unhandled finish reason), break early.
- if len(response.ToolCalls) == 0 && response.Content != "" {
- if response.Content == *lastResponseContent {
- *consecutiveSameContent++
+ // Every round in a row that the provider cut off at the completion cap.
+ // A truncated *answer* already ends the turn in analyzeResponse, so a run
+ // of these means the truncation keeps landing inside tool-call arguments:
+ // act.go refuses the calls, the model is told to re-issue them, writes an
+ // even longer call, and hits the cap again. Give up rather than spend the
+ // whole round budget on it (#3446).
+ if isLengthFinishReason(response.FinishReason) {
+ guards.consecutiveLength++
+ if guards.consecutiveLength >= maxConsecutiveLengthRounds {
+ logger.Warnf(ctx, "[Agent][Round-%d] %d consecutive rounds cut off at the completion cap "+
+ "(finish=%s, completion=%d of %d); stopping",
+ round, guards.consecutiveLength, response.FinishReason,
+ response.Usage.CompletionTokens, e.getCompletionTokenBudget())
+ common.PipelineWarn(ctx, "Agent", "consecutive_length_stop", map[string]interface{}{
+ "iteration": state.CurrentRound,
+ "round": round,
+ "consecutive_length": guards.consecutiveLength,
+ })
+ // Record the round the way every other round is recorded. The
+ // refused tool calls are also what tells the UI that this round's
+ // plain text was a preamble: without them the "let me look that
+ // up" line stays sitting in the answer area, exactly as if it were
+ // the answer.
+ step := types.AgentStep{
+ Iteration: state.CurrentRound,
+ Thought: response.Content,
+ ReasoningContent: response.ReasoningContent,
+ ToolCalls: make([]types.ToolCall, 0),
+ Timestamp: time.Now(),
+ Truncated: true,
+ }
+ if len(response.ToolCalls) > 0 {
+ e.failTruncatedToolCalls(ctx, response, &step, state.CurrentRound, sessionID)
+ }
+ state.RoundSteps = append(state.RoundSteps, step)
+ e.finishStalledTurn(ctx, state, sessionID, response, true)
+ return iterOutcomeBreak, nil
+ }
+ } else {
+ guards.consecutiveLength = 0
+ }
+
+ // Detect stuck loops: a round with no tool calls that repeats the previous
+ // such round is not making progress. An identical *lack* of content counts
+ // — a model burning its whole budget on reasoning returns empty every
+ // round, which used to land in the else branch and reset the counter, so
+ // the guard could never fire on the one shape that needs it most (#3446).
+ if len(response.ToolCalls) == 0 {
+ if guards.sawPlainRound && response.Content == guards.lastResponseContent {
+ guards.consecutiveSameContent++
} else {
- *consecutiveSameContent = 0
+ guards.consecutiveSameContent = 0
}
- *lastResponseContent = response.Content
- if *consecutiveSameContent >= maxRepeatedResponseRounds {
+ guards.sawPlainRound = true
+ guards.lastResponseContent = response.Content
+ if guards.consecutiveSameContent >= maxRepeatedResponseRounds {
logger.Warnf(ctx, "[Agent][Round-%d] Detected stuck loop: same content repeated %d times (finish=%s), stopping",
- round, *consecutiveSameContent+1, response.FinishReason)
- state.FinalAnswer = response.Content
- state.IsComplete = true
+ round, guards.consecutiveSameContent+1, response.FinishReason)
+ e.finishStalledTurn(ctx, state, sessionID, response, false)
return iterOutcomeBreak, nil
}
} else {
- *consecutiveSameContent = 0
- *lastResponseContent = ""
+ guards.consecutiveSameContent = 0
+ guards.sawPlainRound = false
+ guards.lastResponseContent = ""
}
// Create agent step
@@ -808,11 +925,11 @@ func (e *AgentEngine) runReActIteration(
// content and no tool calls (e.g., thinking-only loop without KB),
// retry with a nudge message instead of accepting an empty answer.
if verdict.emptyContent {
- *emptyRetries++
- if *emptyRetries <= maxEmptyResponseRetries {
+ guards.emptyRetries++
+ if guards.emptyRetries <= maxEmptyResponseRetries {
state.PendingSteerMessages = step.UserMessagesBefore
logger.Warnf(ctx, "[Agent][Round-%d] Empty content with stop - retrying (%d/%d)",
- round, *emptyRetries, maxEmptyResponseRetries)
+ round, guards.emptyRetries, maxEmptyResponseRetries)
*messagesPtr = append(*messagesPtr, chat.Message{
Role: "user",
Content: "Please provide your complete answer now as plain text.",
@@ -825,7 +942,7 @@ func (e *AgentEngine) runReActIteration(
// sole terminal answer event (#2906).
logger.Warnf(ctx, "[Agent][Round-%d] Empty content after %d retries - using fallback",
round, maxEmptyResponseRetries)
- fallback := "I'm sorry, I was unable to generate a response. Please try again."
+ fallback := stalledAnswerFallback
answerID := generateEventID("answer")
_ = e.eventBus.Emit(ctx, event.Event{
ID: answerID,
@@ -848,7 +965,7 @@ func (e *AgentEngine) runReActIteration(
state.FinalAnswer = fallback
state.IsComplete = true
state.RoundSteps = append(state.RoundSteps, verdict.step)
- e.closeAnswerStream(ctx, sessionID, verdict.answerID)
+ e.closeAnswerStream(ctx, sessionID, verdict.answerID, verdict.truncated)
return iterOutcomeBreak, nil
}
// Loop-end inject: a user message queued while this finishing round
@@ -880,7 +997,7 @@ func (e *AgentEngine) runReActIteration(
state.FinalAnswer = verdict.finalAnswer
state.IsComplete = true
state.RoundSteps = append(state.RoundSteps, verdict.step)
- e.closeAnswerStream(ctx, sessionID, verdict.answerID)
+ e.closeAnswerStream(ctx, sessionID, verdict.answerID, verdict.truncated)
return iterOutcomeBreak, nil
}
diff --git a/internal/agent/length_truncation_test.go b/internal/agent/length_truncation_test.go
new file mode 100644
index 000000000..21e8deb6a
--- /dev/null
+++ b/internal/agent/length_truncation_test.go
@@ -0,0 +1,419 @@
+package agent
+
+import (
+ "context"
+ "sync"
+ "testing"
+ "time"
+
+ agenttools "github.com/Tencent/WeKnora/internal/agent/tools"
+ "github.com/Tencent/WeKnora/internal/event"
+ "github.com/Tencent/WeKnora/internal/types"
+ "github.com/stretchr/testify/assert"
+ "github.com/stretchr/testify/require"
+)
+
+// truncationRecorder captures every EventAgentFinalAnswer with its Truncated
+// flag, so a test can tell an ordinary close from one that reports the
+// completion cap.
+type truncationRecorder struct {
+ mu sync.Mutex
+ events []event.AgentFinalAnswerData
+}
+
+func (r *truncationRecorder) attach(bus *event.EventBus) {
+ bus.On(event.EventAgentFinalAnswer, func(_ context.Context, evt event.Event) error {
+ data, ok := evt.Data.(event.AgentFinalAnswerData)
+ if !ok {
+ return nil
+ }
+ r.mu.Lock()
+ defer r.mu.Unlock()
+ r.events = append(r.events, data)
+ return nil
+ })
+}
+
+func (r *truncationRecorder) snapshot() []event.AgentFinalAnswerData {
+ r.mu.Lock()
+ defer r.mu.Unlock()
+ return append([]event.AgentFinalAnswerData(nil), r.events...)
+}
+
+func (r *truncationRecorder) doneEvent(t *testing.T) event.AgentFinalAnswerData {
+ t.Helper()
+ for _, e := range r.snapshot() {
+ if e.Done {
+ return e
+ }
+ }
+ t.Fatal("no Done marker was emitted")
+ return event.AgentFinalAnswerData{}
+}
+
+// A completion cap that cuts the answer off ends the turn. Before #3446 this
+// verdict was non-terminal, and the half-written answer went back into the
+// history for the model to rewrite from the top.
+func TestAnalyzeResponse_TruncatedAnswerEndsTheTurn(t *testing.T) {
+ engine := newTestEngine(t, &mockChat{})
+ recorder := &truncationRecorder{}
+ recorder.attach(engine.eventBus)
+
+ verdict := engine.analyzeResponse(
+ context.Background(),
+ &types.ChatResponse{FinishReason: "length", Content: "step one of eight, and then"},
+ types.AgentStep{}, 0, "sess-1", time.Now(),
+ )
+
+ assert.True(t, verdict.isDone, "a truncated answer must end the turn, not loop")
+ assert.True(t, verdict.truncated)
+ assert.False(t, verdict.emptyContent)
+ assert.Equal(t, "step one of eight, and then", verdict.finalAnswer,
+ "the partial text is the answer; there is nothing else to deliver")
+
+ emitted := recorder.snapshot()
+ require.Len(t, emitted, 1, "the answer was not streamed live, so it is emitted once here")
+ assert.Equal(t, "step one of eight, and then", emitted[0].Content)
+ assert.True(t, emitted[0].Truncated, "the client has to be told the text is partial")
+ assert.False(t, emitted[0].Done, "Done is left to the caller, after the steer drain")
+}
+
+// max_tokens and max_output_tokens mean the same thing as length.
+func TestAnalyzeResponse_TruncationAliasesEndTheTurn(t *testing.T) {
+ for _, reason := range []string{"length", "max_tokens", "max_output_tokens", "MAX_TOKENS"} {
+ t.Run(reason, func(t *testing.T) {
+ engine := newTestEngine(t, &mockChat{})
+ verdict := engine.analyzeResponse(
+ context.Background(),
+ &types.ChatResponse{FinishReason: reason, Content: "partial"},
+ types.AgentStep{}, 0, "sess-1", time.Now(),
+ )
+ assert.True(t, verdict.isDone)
+ assert.True(t, verdict.truncated)
+ })
+ }
+}
+
+// A reasoning model can spend the whole budget thinking and return no text at
+// all. There is no partial answer to hand over, so this defers to the existing
+// bounded empty-content retry rather than finishing with an empty message.
+func TestAnalyzeResponse_TruncatedWithNoTextDefersToEmptyRetry(t *testing.T) {
+ engine := newTestEngine(t, &mockChat{})
+ recorder := &truncationRecorder{}
+ recorder.attach(engine.eventBus)
+
+ verdict := engine.analyzeResponse(
+ context.Background(),
+ &types.ChatResponse{FinishReason: "length", Content: " "},
+ types.AgentStep{}, 0, "sess-1", time.Now(),
+ )
+
+ assert.True(t, verdict.isDone)
+ assert.True(t, verdict.emptyContent, "the caller nudges and retries; it must not end on an empty answer")
+ assert.False(t, verdict.truncated)
+ assert.Empty(t, recorder.snapshot(), "a retryable round must emit no answer event at all (#2906)")
+}
+
+// A round that hits the cap while still asking for tool work stays
+// non-terminal: act.go fails the truncated calls and the model re-issues them.
+func TestAnalyzeResponse_TruncatedToolCallRoundIsNotTerminal(t *testing.T) {
+ engine := newTestEngine(t, &mockChat{})
+ verdict := engine.analyzeResponse(
+ context.Background(),
+ &types.ChatResponse{
+ FinishReason: "length",
+ Content: "let me look that up",
+ ToolCalls: []types.LLMToolCall{{
+ ID: "c1", Type: "function",
+ Function: types.FunctionCall{Name: "wiki_read_page", Arguments: `{"slugs":["a`},
+ }},
+ },
+ types.AgentStep{}, 0, "sess-1", time.Now(),
+ )
+ assert.False(t, verdict.isDone, "the tool-call path owns this round")
+ assert.False(t, verdict.truncated)
+}
+
+// The #3446 reproduction. One response, cut off at the cap, no tool calls.
+// The turn must end on it — mockChat fails the test if a second round is
+// attempted, which is exactly what used to happen (and produced the
+// rewrite-from-the-top spiral).
+func TestExecuteLoop_TruncatedAnswerDoesNotReAnswer(t *testing.T) {
+ mock := &mockChat{responses: []mockResponse{{chunks: []types.StreamResponse{{
+ ResponseType: types.ResponseTypeAnswer,
+ Content: "1. First point. 2. Second point. 3. Third po",
+ Done: true,
+ FinishReason: "length",
+ }}}}}
+ engine := newTestEngine(t, mock)
+ recorder := &truncationRecorder{}
+ recorder.attach(engine.eventBus)
+
+ state := &types.AgentState{}
+ _, err := engine.executeLoop(
+ context.Background(), state, "write me a long outline",
+ emptyMessages(), emptyTools(), "sess-1", "msg-1",
+ )
+
+ require.NoError(t, err)
+ assert.Equal(t, 1, mock.callCount, "the loop must not start another round after a truncated answer")
+ assert.True(t, state.IsComplete)
+ assert.Equal(t, "1. First point. 2. Second point. 3. Third po", state.FinalAnswer)
+ assert.True(t, recorder.doneEvent(t).Truncated,
+ "a live-streamed answer only learns about the cap from the Done marker")
+}
+
+// Truncation that keeps landing inside tool-call arguments is the one shape
+// that still loops: the call is refused, the model re-issues it, and the cap
+// hits again. The guard stops it well before the round budget runs out.
+func TestExecuteLoop_ConsecutiveTruncatedToolCallsStopAtTheGuard(t *testing.T) {
+ truncatedToolRound := mockResponse{chunks: []types.StreamResponse{{
+ ToolCalls: []types.LLMToolCall{{
+ ID: "c1", Type: "function",
+ Function: types.FunctionCall{Name: "wiki_read_page", Arguments: `{"slugs":["very-long`},
+ }},
+ Done: true,
+ FinishReason: "length",
+ }}}
+ // One more than the guard allows: reaching it would fail the test.
+ rounds := make([]mockResponse, maxConsecutiveLengthRounds+1)
+ for i := range rounds {
+ rounds[i] = truncatedToolRound
+ }
+ mock := &mockChat{responses: rounds}
+ engine := newTestEngine(t, mock, func(cfg *types.AgentConfig) { cfg.MaxIterations = 30 })
+
+ state := &types.AgentState{}
+ _, err := engine.executeLoop(
+ context.Background(), state, "read every page",
+ emptyMessages(), emptyTools(), "sess-1", "msg-1",
+ )
+
+ require.NoError(t, err)
+ assert.Equal(t, maxConsecutiveLengthRounds, mock.callCount,
+ "the guard must fire on the Nth consecutive capped round, not at MaxIterations")
+ assert.True(t, state.IsComplete)
+ assert.Equal(t, truncatedAnswerFallback, state.FinalAnswer,
+ "no round produced answer text, so the fallback explains why")
+}
+
+// A finish reason the loop does not recognise, with no content and no tool
+// calls, used to spin until MaxIterations: the stuck-loop guard skipped empty
+// rounds and reset its own counter every time (#3446).
+func TestExecuteLoop_RepeatedEmptyRoundsStopAtTheStuckGuard(t *testing.T) {
+ emptyRound := mockResponse{chunks: []types.StreamResponse{{Done: true, FinishReason: "unrecognised"}}}
+ rounds := make([]mockResponse, maxRepeatedResponseRounds+2)
+ for i := range rounds {
+ rounds[i] = emptyRound
+ }
+ mock := &mockChat{responses: rounds}
+ engine := newTestEngine(t, mock, func(cfg *types.AgentConfig) { cfg.MaxIterations = 30 })
+
+ state := &types.AgentState{}
+ _, err := engine.executeLoop(
+ context.Background(), state, "anything",
+ emptyMessages(), emptyTools(), "sess-1", "msg-1",
+ )
+
+ require.NoError(t, err)
+ assert.Equal(t, maxRepeatedResponseRounds+1, mock.callCount,
+ "identical empty rounds must count as repeats")
+ assert.True(t, state.IsComplete)
+ assert.Equal(t, stalledAnswerFallback, state.FinalAnswer)
+}
+
+// A guard can stop a turn on a round whose text never went out as a stream —
+// the fallback it chooses, or content the round accumulated without
+// streaming. Either way the client must receive the text before the Done
+// marker, not a Done for something it never saw.
+func TestFinishStalledTurn_EmitsAnswerThatNeverStreamed(t *testing.T) {
+ for _, tc := range []struct {
+ name string
+ response *types.ChatResponse
+ truncated bool
+ wantAnswer string
+ }{
+ {
+ name: "unstreamed partial text is delivered as the answer",
+ response: &types.ChatResponse{Content: "half an answer"},
+ truncated: true,
+ wantAnswer: "half an answer",
+ },
+ {
+ name: "no text at all falls back to the truncation message",
+ response: &types.ChatResponse{Content: ""},
+ truncated: true,
+ wantAnswer: truncatedAnswerFallback,
+ },
+ {
+ name: "a non-truncation stall falls back to the generic message",
+ response: &types.ChatResponse{Content: " "},
+ truncated: false,
+ wantAnswer: stalledAnswerFallback,
+ },
+ } {
+ t.Run(tc.name, func(t *testing.T) {
+ engine := newTestEngine(t, &mockChat{})
+ recorder := &truncationRecorder{}
+ recorder.attach(engine.eventBus)
+ state := &types.AgentState{}
+
+ engine.finishStalledTurn(context.Background(), state, "sess-1", tc.response, tc.truncated)
+
+ assert.True(t, state.IsComplete)
+ assert.Equal(t, tc.wantAnswer, state.FinalAnswer)
+
+ emitted := recorder.snapshot()
+ require.Len(t, emitted, 2, "the text, then the Done marker")
+ assert.Equal(t, tc.wantAnswer, emitted[0].Content)
+ assert.False(t, emitted[0].Done)
+ assert.Equal(t, tc.truncated, emitted[0].Truncated)
+ assert.True(t, emitted[1].Done)
+ assert.Equal(t, tc.truncated, emitted[1].Truncated)
+ })
+ }
+}
+
+// When the round did stream its answer live, the guard must close that same
+// stream rather than emit the text a second time.
+func TestFinishStalledTurn_ReusesTheLiveAnswerStream(t *testing.T) {
+ engine := newTestEngine(t, &mockChat{})
+ recorder := &truncationRecorder{}
+ recorder.attach(engine.eventBus)
+ state := &types.AgentState{}
+
+ engine.finishStalledTurn(context.Background(), state, "sess-1", &types.ChatResponse{
+ Content: "already on screen",
+ AnswerStreamed: true,
+ AnswerEventID: "answer-live",
+ }, true)
+
+ emitted := recorder.snapshot()
+ require.Len(t, emitted, 1, "re-emitting would render the answer twice")
+ assert.True(t, emitted[0].Done)
+ assert.True(t, emitted[0].Truncated)
+ assert.Equal(t, "already on screen", state.FinalAnswer)
+}
+
+// A model that writes its reasoning inline as <think> can be cut off before
+// the closing tag. The pair regex leaves such a block whole, so the round
+// looks like it produced an answer when all it produced was reasoning —
+// which would both leak the chain of thought into the answer area and skip
+// the empty-content retry this case is supposed to use.
+func TestAnalyzeResponse_UnterminatedThinkCountsAsNoAnswer(t *testing.T) {
+ engine := newTestEngine(t, &mockChat{})
+ recorder := &truncationRecorder{}
+ recorder.attach(engine.eventBus)
+
+ verdict := engine.analyzeResponse(
+ context.Background(),
+ &types.ChatResponse{
+ FinishReason: "length",
+ Content: "<think>First I should enumerate the eight steps, then for each one",
+ },
+ types.AgentStep{}, 0, "sess-1", time.Now(),
+ )
+
+ assert.True(t, verdict.isDone)
+ assert.True(t, verdict.emptyContent, "reasoning is not an answer; this must reach the empty-content retry")
+ assert.False(t, verdict.truncated)
+ assert.Empty(t, verdict.finalAnswer)
+ assert.Empty(t, recorder.snapshot(), "the chain of thought must not be emitted as the answer")
+}
+
+// The same guard on a closed block followed by real text: the answer survives.
+func TestAnalyzeResponse_ClosedThinkKeepsTheAnswerAfterIt(t *testing.T) {
+ engine := newTestEngine(t, &mockChat{})
+ verdict := engine.analyzeResponse(
+ context.Background(),
+ &types.ChatResponse{
+ FinishReason: "length",
+ Content: "<think>planning</think>1. First point. 2. Second po",
+ },
+ types.AgentStep{}, 0, "sess-1", time.Now(),
+ )
+ assert.True(t, verdict.truncated)
+ assert.Equal(t, "1. First point. 2. Second po", verdict.finalAnswer)
+}
+
+// The truncation has to survive the round trip through agent_steps: history is
+// rebuilt from those, never from the live answer events.
+func TestAnalyzeResponse_TruncatedVerdictMarksItsStep(t *testing.T) {
+ engine := newTestEngine(t, &mockChat{})
+ verdict := engine.analyzeResponse(
+ context.Background(),
+ &types.ChatResponse{FinishReason: "length", Content: "half an answer"},
+ types.AgentStep{Iteration: 3}, 3, "sess-1", time.Now(),
+ )
+ require.True(t, verdict.truncated)
+ assert.True(t, verdict.step.Truncated, "the step is what a reloaded conversation reads")
+
+ // And it must survive the storage sanitizer that runs before the write.
+ stored := agenttools.SanitizeAgentStepsForStorage([]types.AgentStep{verdict.step})
+ require.Len(t, stored, 1)
+ assert.True(t, stored[0].Truncated)
+}
+
+// Text that came with tool calls is a preamble, not an answer. The guard must
+// not hand "let me look that up" to the user as the final answer.
+func TestFinishStalledTurn_IgnoresAToolCallPreamble(t *testing.T) {
+ engine := newTestEngine(t, &mockChat{})
+ recorder := &truncationRecorder{}
+ recorder.attach(engine.eventBus)
+ state := &types.AgentState{}
+
+ engine.finishStalledTurn(context.Background(), state, "sess-1", &types.ChatResponse{
+ Content: "let me look that up",
+ AnswerStreamed: true,
+ AnswerEventID: "answer-live",
+ ToolCalls: []types.LLMToolCall{{
+ ID: "c1", Type: "function",
+ Function: types.FunctionCall{Name: "wiki_read_page", Arguments: `{"slugs":["a`},
+ }},
+ }, true)
+
+ assert.Equal(t, truncatedAnswerFallback, state.FinalAnswer,
+ "a preamble must not become the answer")
+ emitted := recorder.snapshot()
+ require.Len(t, emitted, 2)
+ assert.Equal(t, truncatedAnswerFallback, emitted[0].Content)
+ assert.True(t, emitted[1].Done)
+}
+
+// The round that trips the consecutive-length guard is recorded like any
+// other, and its refused tool calls are what let the UI retract the preamble
+// from the answer area.
+func TestExecuteLoop_ConsecutiveLengthRecordsTheFinalRound(t *testing.T) {
+ truncatedToolRound := mockResponse{chunks: []types.StreamResponse{{
+ ResponseType: types.ResponseTypeAnswer,
+ Content: "let me look that up",
+ ToolCalls: []types.LLMToolCall{{
+ ID: "c1", Type: "function",
+ Function: types.FunctionCall{Name: "wiki_read_page", Arguments: `{"slugs":["very-long`},
+ }},
+ Done: true,
+ FinishReason: "length",
+ }}}
+ rounds := make([]mockResponse, maxConsecutiveLengthRounds)
+ for i := range rounds {
+ rounds[i] = truncatedToolRound
+ }
+ engine := newTestEngine(t, &mockChat{responses: rounds},
+ func(cfg *types.AgentConfig) { cfg.MaxIterations = 30 })
+
+ state := &types.AgentState{}
+ _, err := engine.executeLoop(
+ context.Background(), state, "read every page",
+ emptyMessages(), emptyTools(), "sess-1", "msg-1",
+ )
+
+ require.NoError(t, err)
+ require.Len(t, state.RoundSteps, maxConsecutiveLengthRounds,
+ "the round that tripped the guard must not vanish from the transcript")
+ last := state.RoundSteps[len(state.RoundSteps)-1]
+ assert.True(t, last.Truncated)
+ require.Len(t, last.ToolCalls, 1, "its tool calls are recorded as refused")
+ require.NotNil(t, last.ToolCalls[0].Result)
+ assert.False(t, last.ToolCalls[0].Result.Success)
+ assert.Equal(t, truncatedAnswerFallback, state.FinalAnswer)
+}
diff --git a/internal/agent/observe.go b/internal/agent/observe.go
index a16bff69e..9c1e82337 100644
--- a/internal/agent/observe.go
+++ b/internal/agent/observe.go
@@ -330,7 +330,11 @@ type responseVerdict struct {
isDone bool
finalAnswer string
emptyContent bool // LLM returned stop with no tool calls and empty content
- step types.AgentStep
+ // truncated marks a finalAnswer the completion-token cap cut off. The turn
+ // ends with it rather than looping, so the client has to be told the text
+ // is partial.
+ truncated bool
+ 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,
@@ -486,9 +490,77 @@ func (e *AgentEngine) analyzeResponse(
}
}
+ // Case 2: the completion cap cut this message off and the model asked for
+ // no tool work.
+ //
+ // Looping here is what produced the "answer restarts from the top" spiral
+ // (#3446). `length` is not a natural stop, so the round used to fall
+ // through as non-terminal; with no tool calls to run, appendToolResults
+ // pushed the half-written answer back as a plain assistant message with
+ // nothing instructing the model to continue. The next round rewrote the
+ // answer from the beginning, hit the same cap, and repeated until the
+ // round budget ran out or the user cancelled.
+ //
+ // Deliver what the model produced and end the turn. This matches what the
+ // truncated-tool-call path already does one level down (act.go refuses the
+ // calls rather than running half-serialized arguments) and what other
+ // agent loops do with a text truncation. A continuation nudge is
+ // deliberately not sent: it only grows the prompt with the discarded
+ // fragment, and the reliable form of continuation (assistant prefill) is
+ // not available on most OpenAI-compatible endpoints.
+ if isLengthFinishReason(response.FinishReason) && len(response.ToolCalls) == 0 {
+ response.Content = agenttools.StripThinkBlocks(response.Content)
+ round := iteration + 1
+ // Nothing was produced but reasoning: there is no partial answer to
+ // hand over, so use the existing empty-content path, which nudges and
+ // retries a bounded number of times before falling back.
+ if strings.TrimSpace(response.Content) == "" {
+ logger.Warnf(ctx, "[Agent][Round-%d] Completion cap reached with no answer text (finish=%s); "+
+ "deferring to the empty-content retry", round, response.FinishReason)
+ return responseVerdict{isDone: true, finalAnswer: "", emptyContent: true, step: step}
+ }
+
+ logger.Warnf(ctx, "[Agent][Round-%d] Answer truncated at the completion cap (finish=%s, answer=%d chars); "+
+ "ending the turn instead of re-answering", round, response.FinishReason, len(response.Content))
+ common.PipelineWarn(ctx, "Agent", "round_truncated_answer", map[string]interface{}{
+ "iteration": iteration,
+ "round": round,
+ "answer_len": len(response.Content),
+ "finish_reason": response.FinishReason,
+ })
+
+ // Same two delivery paths as Case 1: reuse the live stream when the
+ // text already went out, otherwise emit it once here. Done is left to
+ // the caller so a loop-end steer inject can still continue the turn.
+ answerID := response.AnswerEventID
+ if !response.AnswerStreamed || answerID == "" {
+ answerID = generateEventID("answer")
+ _ = e.eventBus.Emit(ctx, event.Event{
+ ID: answerID,
+ Type: event.EventAgentFinalAnswer,
+ SessionID: sessionID,
+ Data: event.AgentFinalAnswerData{
+ Content: response.Content,
+ Done: false,
+ Truncated: true,
+ },
+ })
+ }
+
+ step.Truncated = true
+ return responseVerdict{
+ isDone: true,
+ finalAnswer: response.Content,
+ truncated: true,
+ step: step,
+ answerID: answerID,
+ }
+ }
+
// Any round that still requests tool calls is non-terminal: the caller
- // executes the tools and loops again. The agent only ends by stopping
- // naturally (Case 1) with its answer as plain assistant text.
+ // executes the tools and loops again. Apart from the cases above, the
+ // agent only ends by stopping naturally (Case 1) with its answer as plain
+ // assistant text.
return responseVerdict{isDone: false, step: step}
}
diff --git a/internal/agent/tools/strip_think.go b/internal/agent/tools/strip_think.go
index 3c1b652a5..616ccf77a 100644
--- a/internal/agent/tools/strip_think.go
+++ b/internal/agent/tools/strip_think.go
@@ -6,6 +6,11 @@ import "regexp"
// Uses (?s) flag so . matches newlines.
var thinkBlockRe = regexp.MustCompile(`(?s)<think>.*?</think>`)
+// unterminatedThinkRe matches a <think> that never closes, through end of
+// input. Applied after thinkBlockRe, so any <think> still present opens a
+// block the output was cut off inside.
+var unterminatedThinkRe = regexp.MustCompile(`(?s)<think>.*$`)
+
// StripThinkBlocks removes <think>…</think> blocks from LLM output content.
// Some models (DeepSeek, Qwen, etc.) embed chain-of-thought reasoning inside
// <think> tags in the content field. These should be stripped before:
@@ -19,6 +24,13 @@ func StripThinkBlocks(content string) string {
return ""
}
cleaned := thinkBlockRe.ReplaceAllString(content, "")
+ // A block the completion cap cut off mid-reasoning never gets its closing
+ // tag, so the pair regex leaves it whole. Everything from the dangling
+ // <think> to the end is reasoning: the streaming splitter routes exactly
+ // that text to the thought area (ThinkStreamSplitter.Flush), and a caller
+ // asking "is there an answer here?" must get the same answer as the
+ // splitter, not a chain of thought with a tag glued to its front.
+ cleaned = unterminatedThinkRe.ReplaceAllString(cleaned, "")
// Trim leading/trailing whitespace that may remain after removal
result := trimWhitespace(cleaned)
return result
diff --git a/internal/event/event_data.go b/internal/event/event_data.go
index 0182ecda0..f699050a4 100644
--- a/internal/event/event_data.go
+++ b/internal/event/event_data.go
@@ -197,6 +197,12 @@ type AgentFinalAnswerData struct {
Content string `json:"content"`
Done bool `json:"done"`
IsFallback bool `json:"is_fallback,omitempty"` // True when response is a fallback (no knowledge base match)
+ // Truncated marks an answer the provider cut off at the completion-token
+ // cap. The text is what the model had produced when the cap hit, not a
+ // finished answer, so a client should say so rather than present it as
+ // complete. Carried on both the content event and the Done marker,
+ // because a live-streamed answer only learns of the cap at the close.
+ Truncated bool `json:"truncated,omitempty"`
}
// ContextCompactedData reports that older conversation was replaced by a
diff --git a/internal/handler/session/agent_stream_handler.go b/internal/handler/session/agent_stream_handler.go
index 27a3cf2e8..3d6c3f960 100644
--- a/internal/handler/session/agent_stream_handler.go
+++ b/internal/handler/session/agent_stream_handler.go
@@ -580,6 +580,13 @@ func (h *AgentStreamHandler) handleFinalAnswer(ctx context.Context, evt event.Ev
if data.IsFallback {
metadata["is_fallback"] = true
}
+ // The completion cap cut this answer off. Carried on every chunk and on
+ // the Done marker: a live-streamed answer only learns of the cap at the
+ // close, and the metadata is persisted with the stream event so a replay
+ // still shows the notice.
+ if data.Truncated {
+ metadata["truncated"] = true
+ }
h.mu.Unlock()
// Append this chunk to stream (frontend will accumulate by event ID)
diff --git a/internal/types/agent.go b/internal/types/agent.go
index 8f8217028..8ea94d7d3 100644
--- a/internal/types/agent.go
+++ b/internal/types/agent.go
@@ -444,6 +444,12 @@ type AgentStep struct {
ReasoningContent string `json:"reasoning_content,omitempty"`
ToolCalls []ToolCall `json:"tool_calls"` // Tools called in this step (Act phase)
Timestamp time.Time `json:"timestamp"` // When this step occurred
+ // Truncated marks the round the completion-token cap cut off. It rides in
+ // the agent_steps JSON so a reloaded, shared or re-opened conversation can
+ // still show that the answer stops mid-sentence by design, rather than
+ // looking finished. Live streaming carries the same fact on the answer
+ // event; this is what survives the round trip.
+ Truncated bool `json:"truncated,omitempty"`
}
// GetObservations returns observations from all tool calls in this step