streamText leaves pending message row unfinalized when final step has empty content

[Kingpin007]

Summary

When the final step of a thread.streamText(..., { saveStreamDeltas: true }) agentic loop has finishReason: "stop" with zero content (no text, no tool calls, no reasoning text), the trailing pending assistant message row is never finalized. It stays status: "pending" in the agent component's messages table indefinitely.

The stream is correctly marked finished and result.text / result.finishReason resolve cleanly, so the calling action returns success and any watchdog tied to that action exits. The orphan pending row is only discovered later by an external recovery path.

Environment

• @convex-dev/agent@0.6.1
• ai@^6.0.175
• @openrouter/ai-sdk-provider@^2.9.0
• Model where we hit it: google/gemini-3.5-flash via OpenRouter

Root Cause (verified against published dist/ files in 0.6.1)

1. dist/client/streamText.js:73-86 — onStepFinish sees the final step has no continuation, sets streamer.markFinishedExternally() and stores pendingFinalStep = step. Defers the save.
2. dist/client/streamText.js:115-118 — After stream consumption, calls call.save({ step: pendingFinalStep }, false, finishStreamId).
3. dist/client/start.js:119-122 — serializeResponseMessages(step, model, newResponseMessages) runs with newResponseMessages = allResponseMessages.slice(previousResponseMessageCount). For an empty completion, step.response.messages adds no new entries, so this slice is [].
4. dist/mapping.js:191-193 → 212-237 — serializeStepMessages maps over [], returns { messages: [] }.
5. dist/client/start.js:132-142 — addMessages is called with messages: []. In dist/component/messages.js:159, the for-loop iterates zero times. The pending row is never replaced.
6. dist/client/start.js:157 — pendingMessageId = undefined is set in memory, but the DB row remains status: pending with content: [].

Why generateText is not affected

generateText calls serializeNewMessagesInStep (dist/mapping.js:198-211), which has a fallback at lines 207-209:

else {
    messagesToSerialize = [{ role: "assistant", content: [] }];
}

This synthetic empty-assistant message ensures the pending row gets replaced and marked status: "success". The streaming path uses serializeResponseMessages (the non-new variant) instead and has no such fallback.

Minimal Repro Idea

Any provider/model that returns finishReason: "stop" with empty content. Gemini 3.5-flash via OpenRouter does this sporadically. A mock language model returning a single { type: 'finish', finishReason: 'stop', usage: {...} } chunk with no text/tool parts should reproduce deterministically.

[ianmacartney]

I believe this has been fixed in @convex-dev/agent@0.6.2 - can you confirm?

[ianmacartney]

@Kingpin007 can you confirm if it's fixed in the latest release?

[evanhammer]

I'm having this issue too. I'm on @convex-dev/agent@0.6.4

It looks like #266 only fixed the saveStreamDeltas.returnImmediately path. The awaited path — streamText(..., { saveStreamDeltas: true }) with returnImmediately unset — still leaves the row pending, exactly as the original analysis describes: an empty final step goes serializeResponseMessages → serializeStepMessages([]) → addMessages([]), which never replaces the placeholder. generateText is unaffected because serializeNewMessagesInStep injects the [{ role: "assistant", content: [] }] fallback (dist/mapping.js:211 on 0.6.4); the streaming path has no equivalent.

I'm off getting finishReason: stop, while the assistant row is stuck in 'ending with empty content.

Deterministic repro — a mock LanguageModelV3 whose entire stream is:
{ type: 'stream-start', warnings: [] }
{ type: 'finish', finishReason: { unified: 'stop', raw: undefined }, usage }
leaves the pending row every time under saveStreamDeltas: true.