fix(desktop): honor display.interim_assistant_messages — stop collapsing mid-turn narration

[lucasfdale]

What does this PR do?

On the Desktop app, a multi-step turn (text → tool → text → tool → …)
streams all its mid-turn narration live, then collapses to only the final
message the instant message.complete lands. Any substantive point the model
makes between tool calls that the final message doesn't restate disappears from
the transcript. The text is persisted to state.db and reappears on session
reload — the loss is render-only — but Desktop is the only surface that does
this.

Root cause: completeAssistantMessage in
apps/desktop/src/app/session/hooks/use-message-stream/index.ts ran a
replaceTextPart that unconditionally dropped every text part on
completion and re-appended the gateway's final_response (message.complete.text)
as one trailing part. final_response is only the agent's last assistant
segment (agent/conversation_loop.py: final_response = assistant_message.content
in the no-tool-calls branch), so every earlier narration segment was discarded.
git blame shows this filter is original to the desktop app's first commit —
incidental, never a deliberate design decision.

This is a real divergence: the setting that governs interim commentary already
exists product-wide — display.interim_assistant_messages (default true,
documented as "signal, not noise") — and every other surface already keeps
interim text: the messaging gateway gates sending on it; the Ink TUI keeps
interleaved segments and appends only the final tail
(ui-tui/.../turnController.ts::recordMessageComplete); and Desktop's own
reload path (toChatMessages) reconstructs the interleaving. Desktop's
live-completion path was the sole outlier and consulted the setting nowhere.

The fix wires Desktop to honor the existing display.interim_assistant_messages
setting (default true, so the improved behavior is on by default; an explicit
false preserves the old lean collapse) and corrects the merge so keep-mode
matches what the TUI and reload path already produce — no new config key, no new
IPC (the renderer already fetches config.display).

Why this content is worth keeping (not filler)

Because final_response is only the agent's last segment, the dropped text is
specifically everything the agent worked out along the way — root-cause
findings, decisions, caveats, partial results — that the closing line doesn't
restate. The screenshot below is a debugging turn: the agent diagnoses that a
bare catch {} is silently swallowing Stripe errors, then finishes with a terse
"Fixed." BEFORE, the user is told it's fixed but never sees why it broke —
the diagnosis is gone. AFTER, the root-cause finding is preserved. That's the
case for interim being signal: it frequently carries the single most valuable
sentence in the turn.

Screenshot

Both panels are rendered by the real shipping Thread component, and the two
message states are produced by running the actual mergeFinalAssistantText
function this PR adds over one shared streamed input (built with the real
appendAssistantTextPart / upsertToolPart builders): left = keepInterim:false
(today's collapse), right = keepInterim:true (this PR's default). It is a
faithful render of the function's output, not a hand-drawn mockup — though not a
live end-to-end gateway capture.

Related Issue

Fixes #54905. Fixes #61297. Fixes #61822. (Same Desktop root cause — the streamed
analysis / interim narration collapses to only the brief final message.) Prior
report #40903 was closed completed without a fix — same bug.

Scope note: this is the Desktop renderer fix. The classic-CLI path (registering
interim_assistant_callback in cli.py) is a separate, complementary change
tracked in #61880 and is intentionally out of scope here.

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)

Changes Made

• apps/desktop/src/lib/chat-messages.ts — extract the completion-merge into a
  pure, exported mergeFinalAssistantText(parts, finalText, keepInterim).
  keepInterim: true keeps interim narration and upgrades the trailing streamed
  text segment in place (the one final_response restates), or appends when the
  final text is genuinely new; keepInterim: false is byte-identical to the old
  collapse. Reasoning-dedup behavior is unchanged.
• apps/desktop/src/app/session/hooks/use-message-stream/index.ts — replace the
  inline replaceTextPart with a call to mergeFinalAssistantText, reading the
  new setting atom.
• apps/desktop/src/store/session.ts — add $keepInterimAssistantMessages atom
  (default true) + setter, mirroring the backend config.
• apps/desktop/src/app/session/hooks/use-hermes-config.ts — set the atom from
  config.display.interim_assistant_messages on config refresh (default true;
  only an explicit false opts into lean).
• apps/desktop/src/types/hermes.ts — add interim_assistant_messages?: boolean
  to the HermesConfig.display type.
• apps/desktop/src/lib/chat-messages.test.ts — 7 unit tests for
  mergeFinalAssistantText (keep + lean modes).
• apps/desktop/src/app/session/hooks/use-message-stream/interim-narration.test.tsx
  — integration test driving the real hook through
  message.start → delta → tool.start → tool.complete → delta → message.complete,
  asserting narration survives when on and collapses when off.
• cli-config.yaml.example + hermes_cli/config.py — update the
  interim_assistant_messages comments (were "Gateway-only") to document that it
  now also governs Desktop transcript behavior. Comment-only; no default change.

How to Test

1. In the Desktop app, ask for something that produces a multi-step turn where
   the model narrates between tool calls (e.g. "check the repo layout, then
   summarize", where it says something substantive before the final answer).
2. Before: on completion the bubble collapses to only the final message; the
   mid-turn narration vanishes until you reload the session.
   After (default): the mid-turn narration stays in the transcript alongside
   the tool calls and the final message.
3. Set display.interim_assistant_messages: false in ~/.hermes/config.yaml and
   repeat — the old lean collapse (final message only) is preserved.
4. Automated: from the repo root,
   npm run --prefix apps/desktop typecheck (clean),
   npm run --prefix apps/desktop build (clean),
   and cd apps/desktop && ../../node_modules/.bin/vitest run --environment jsdom src/lib/chat-messages.test.ts src/app/session/hooks/use-message-stream/interim-narration.test.tsx (37 passing).

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(desktop): …)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix
• I've run the relevant test suites (tests/hermes_cli/test_config.py 145,
  tests/gateway/test_display_config.py 52, desktop vitest 37) — all pass.
  Note: desktop CI is typecheck + production build (both pass here); vitest
  is included as fix evidence. The Python change is comment-only.
• I've added tests for my changes (7 unit + 2 integration)
• I've tested on my platform: macOS 26.5.2 (Apple Silicon)

Documentation & Housekeeping

• I've updated relevant documentation — cli-config.yaml.example +
  hermes_cli/config.py comments for interim_assistant_messages
• I've updated cli-config.yaml.example (comment clarified; the key already
  existed, no new key added)
• I've updated CONTRIBUTING.md/AGENTS.md — N/A (no architecture change)
• I've considered cross-platform impact — renderer logic only, no
  platform-specific code paths
• I've updated tool descriptions/schemas — N/A (no tool change)

Open question for maintainers

Desktop ignored display.interim_assistant_messages while the TUI, messaging
gateway, and reload path all respect/implement interim text. This PR assumes that
was an oversight to bring in line, not a deliberate Desktop-only lean default. If
it was deliberate, what's the rationale — so the default can be revisited rather
than flipped. Happy to add a Settings → Display toggle that writes the key if a
GUI control is wanted; kept out of this PR to keep the diff minimal since the
config key already drives it.

[kyssta-exe]

This PR also fixes #61297 (same root cause — interim narration collapsing). Mentioning here for cross-reference.

[lucasfdale]

Thanks for the cross-reference — confirmed, #61297 is the same root cause (Desktop's live-completion path dropping every interim segment and keeping only final_response, the agent's last segment). I've added Fixes #61297 to the description so it closes on merge.

Worth noting the report also ticks CLI (interactive chat) as a component, but the Ink TUI's recordMessageComplete already preserves interim segments — the defect is Desktop-only, which this PR covers in full.

[tonydwb]

Code Review Summary

Verdict: LGTM

What the PR Does

Honor display.interim_assistant_messages configuration, stopping mid-turn narration from being collapsed.

Assessment

• Small config honoring fix.

---

Reviewed by Hermes Agent

[giggling-ginger]

Review note / issue linkage

This also fixes #61822 (same Desktop root cause).

Why #61822 maps here

• Report: intermediate thinking / tool narration flashes briefly, then is replaced by the final answer only.
• Reporter has interim assistant messages enabled.
• Debug dump shows Desktop + platform=tui / tui_gateway, not classic CLI-only.
• That matches this PR's collapse-on-message.complete analysis exactly (replaceTextPart drops every text part and keeps only final_response).

Please add Fixes #61822 to the PR body (alongside #54905 / #61297) so the issue auto-closes on merge.

Sanity check done against current main

• Cherry-picked this branch cleanly onto latest main; desktop vitest for mergeFinalAssistantText + interim narration integration: 37 passed.
• Only real merge friction was an unrelated scripts/release.py AUTHOR_MAP collision if someone salvages later — not a problem for merging this PR as-is if it's rebased.

Scope caveat (not a blocker)

• Fixes Desktop transcript collapse.
• Does not cover classic CLI missing interim_assistant_callback registration (that's the separate complementary path in feat(cli): register interim_assistant_callback to show mid-turn agent messages #61880). [Bug]: Tool calls and intermediate tool execution text not showing up in chat at all #61822's evidence is Desktop, so this PR is the right fix for that report.

I closed the accidental salvage duplicate #61997 in favor of this original PR.

[lucasfdale]

Thanks for the thorough triage — much appreciated.

Done:

• Added Fixes #61822 (verified: the "flashes for a split second then replaced by the final answer" symptom with interim settings on is exactly this Desktop collapse; the comp/cli label looks misfiled since classic-CLI never emits interim to flash). All three closing refs now parse: Desktop: all intermediate assistant text lost during multi-tool turns — only final message survives #54905, [Bug]: desktop可视化的结果不全 #61297, [Bug]: Tool calls and intermediate tool execution text not showing up in chat at all #61822.
• Rebased onto latest main (was ~189 behind). Clean replay, no conflicts. Re-verified on the new base: tsc --noEmit clean, eslint clean, desktop vitest mergeFinalAssistantText + interim-narration integration 37 passed — matches your cherry-pick result.
• Added a scope note to the PR body: this is the Desktop-renderer fix; the classic-CLI interim_assistant_callback registration (feat(cli): register interim_assistant_callback to show mid-turn agent messages #61880) is the separate complementary path and intentionally out of scope here.

Thanks also for closing the #61997 salvage dup in favor of this one.

[teknium1]

Thanks for isolating a confirmed Desktop completion-path defect. The current main base removes every streamed text part on completion in apps/desktop/src/app/session/hooks/use-message-stream/index.ts:359-377, so preserving interim narration is the right direction.

Problems

• apps/desktop/src/lib/chat-messages.ts:340-352 scans backward across tool boundaries. For text("same") → tool-call → message.complete("same"), it replaces the pre-tool part at line 350 instead of appending the terminal final response after the tool. This can lose the final segment's position whenever final text was not streamed and happens to match earlier narration.

Suggested changes

• Limit replacement to text in the terminal segment after the latest tool/non-stream part; otherwise append. Add the matching-text-after-tool regression case.
• Add a use-hermes-config test for explicit display.interim_assistant_messages: false and the omitted-key default.

Automated hermes-sweeper review.

[teknium1]

This reverse scan crosses tool-call boundaries. With [text('same'), tool-call] and finalText === 'same', line 350 replaces the pre-tool narration rather than appending the terminal final segment after the tool. Stop at the final segment boundary (or append when no post-tool text exists) and add that regression case.

[lucasfdale]

Thanks for the precise review — both points fixed, and hardening the merge surfaced a related bug I fixed too.

1. Terminal-segment boundary (fix(desktop): limit interim final-text merge to the terminal segment)
Confirmed and fixed exactly as you described: the backward scan now stops at the first tool/non-stream boundary, so the in-place upgrade is limited to the terminal segment and otherwise appends. Added the matching-text-after-tool regression case (text("x") → tool → complete("x") now renders [text, tool-call, text], final positioned after the tool), plus coverage for deep multi-tool turns and reasoning-terminal shapes.

2. Config tests — added use-hermes-config cases for explicit display.interim_assistant_messages: true/false and the omitted-key default (defaults to keeping interim).

3. Bonus fix from adversarial testing (fix(desktop): stop short final text from dropping longer reasoning blocks)
While battle-testing the boundary fix (adversarial cases + a property-based fuzzer, ~200k scenarios across both modes), I found a separate pre-existing bug: the reasoning dedup used a bidirectional prefix match, so a short/generic final line ("Done."/"OK") counted as "restating" any longer reasoning block that merely started with it — silently dropping substantive content (e.g. reasoning "Done. Note: the API key is expired…" erased by final "Done."). Same information-loss class this PR targets, in the reasoning lane. Split the predicate so reasoning is only dropped when the final fully covers it (reasoning ⊆ final); the reverse direction stays for the terminal-text upgrade where a truncated stream is legitimately extended by the final.

Kept as two commits so the requested boundary fix and the reasoning fix stay separable. Green on latest main: 54 desktop vitest cases, tsc --noEmit, eslint all clean; fuzzer reports zero invariant violations across 200k cases.

[lucasfdale]

Rebased onto latest main (was 729 behind) and force-pushed — the branch is green and mergeable again (MERGEABLE; the earlier CONFLICTING is cleared).

What changed in this push (no code behavior change):

• Conflict resolved: the only conflict was in hermes_cli/config.py, where main added the show_commentary default + comment block right below interim_assistant_messages. Resolved as a union — kept main's show_commentary and this PR's clarified interim_assistant_messages comment. Every desktop source/test file auto-merged clean; the code diff is unchanged at +547/-37 across 11 files.
• Commits re-authored to my GitHub noreply address so contributor-check auto-resolves without an AUTHOR_MAP entry. The four commits stay separable (honor-setting / screenshot / terminal-segment boundary fix / reasoning-dedup fix).

Re-verified on the new base (macOS, Node 26):

• tsc --noEmit (both tsconfigs): clean
• eslint src/ electron/: 0 errors
• The PR's own suites in isolation: 56 passed (chat-messages.test.ts 44, use-hermes-config.test.ts 10, interim-narration.test.tsx 2)

Note: two unrelated files (app/skills/index.test.tsx, assistant-ui/thread/streaming.test.tsx) flake in the full run — I confirmed they fail the same way on clean upstream/main with this branch absent, and this PR touches neither. Flagging so they're not mistaken for a regression here.

Prior review asks are already in (teknium1's terminal-segment boundary fix + the use-hermes-config explicit-true/false/omitted tests landed in the limit interim final-text merge to the terminal segment commit; tonydwb LGTM). Ready for re-review / CI approval.