Skip to content

~95% on SimpleQA (e.g. Qwen3.6-27B on a 3090). Supports all local and cloud LLMs (llama.cpp, Ollama, Google, ...). 10+ search engines - arXiv, PubMed, your private documents. Everything Local & Encrypted.

fix(web): preserve streaming citation text on formatting failures (#6126)

LearningCircuit7f597516a8cd
diff --git a/changelog.d/+chat-stream-carry-fallback.bugfix.md b/changelog.d/+chat-stream-carry-fallback.bugfix.md
new file mode 100644
index 0000000000..c0f247e20f
--- /dev/null
+++ b/changelog.d/+chat-stream-carry-fallback.bugfix.md
@@ -0,0 +1 @@
+Fix a bug where a hyperlink formatting failure in live chat output could drop, duplicate, or reorder buffered citation text; the raw text is now emitted exactly once, including when the next chunk starts another incomplete citation.
diff --git a/src/local_deep_research/web/services/research_service.py b/src/local_deep_research/web/services/research_service.py
index 8506d60eaf..7967a8e8b3 100644
--- a/src/local_deep_research/web/services/research_service.py
+++ b/src/local_deep_research/web/services/research_service.py
@@ -735,14 +735,17 @@ def _make_chat_stream_callback(
"""
if source_resolver is None or formatter is None:
return chunk
+ # Keep the complete raw delta before updating carry for this chunk.
+ # The source resolver runs before that update; only formatting
+ # can fail after it.
+ text = carry[0] + chunk
try:
sources = source_resolver() or []
if not sources:
# Reset carry so the leading "[" we held onto doesn't
# disappear from the client's accumulated text.
- released, carry[0] = carry[0], ""
- return released + chunk
- text = carry[0] + chunk
+ carry[0] = ""
+ return text
pending = _PARTIAL_BRACKET_RE.search(text)
if pending:
safe = text[: pending.start()]
@@ -765,14 +768,14 @@ def _make_chat_stream_callback(
return ""
return formatter.apply_inline_hyperlinks(safe, sources)
except Exception:
- # Hyperlinking is quality-of-life. On any failure fall back
- # to emitting the raw chunk so the user still sees the text.
+ # Include the previous carry exactly once even if formatting
+ # failed after replacing it with a new incomplete bracket.
logger.debug(
"Inline citation hyperlinking failed; emitting raw chunk",
exc_info=True,
)
- released, carry[0] = carry[0], ""
- return released + chunk
+ carry[0] = ""
+ return text
def stream_callback(chunk: str):
# Resolve through the module namespace each call so tests can
diff --git a/tests/web/services/test_research_service_error_paths.py b/tests/web/services/test_research_service_error_paths.py
new file mode 100644
index 0000000000..ff09d62724
--- /dev/null
+++ b/tests/web/services/test_research_service_error_paths.py
@@ -0,0 +1,360 @@
+"""Exercise best-effort research cleanup paths that must never mask outcomes.
+
+These branches sit behind socket, chat-context, and database failures, so normal
+success-path tests cannot reach them. The tests keep those boundaries mocked
+while calling the real service helpers and worker error mapper.
+"""
+
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from typing import NotRequired, TypedDict
+from unittest.mock import MagicMock, create_autospec, patch
+
+import pytest
+
+from local_deep_research.web.services import research_service
+from tests.web.services.helpers import MODULE
+from tests.web.services.test_research_service_config_error_scrub import (
+ _run_with,
+)
+
+
+class StreamingState(TypedDict):
+ chunks_sent: int
+ chunks: list[str]
+ _bytes: int
+ _truncated: bool
+ _persisted: NotRequired[bool]
+ _flush_carry: NotRequired[Callable[[], str]]
+
+
+def _streaming_state(*, chunks_sent: int = 0) -> StreamingState:
+ return {
+ "chunks_sent": chunks_sent,
+ "chunks": [],
+ "_bytes": 0,
+ "_truncated": False,
+ }
+
+
+def test_chat_save_keeps_response_when_context_update_fails() -> None:
+ state = _streaming_state()
+ chat_service = MagicMock()
+ context_manager = MagicMock()
+ context_manager.extract_context_updates.side_effect = RuntimeError(
+ "bad context"
+ )
+
+ with (
+ patch(
+ "local_deep_research.chat.service.ChatService",
+ return_value=chat_service,
+ ),
+ patch(
+ "local_deep_research.chat.context.ChatContextManager",
+ return_value=context_manager,
+ ),
+ patch(f"{MODULE}.logger") as logger,
+ ):
+ research_service._save_chat_message_and_context(
+ "chat-1",
+ "research-1",
+ "alice",
+ "answer",
+ False,
+ state,
+ MagicMock(),
+ )
+
+ chat_service.add_message.assert_called_once()
+ logger.opt.return_value.warning.assert_called_once_with(
+ "Could not update accumulated context"
+ )
+
+
+def test_chat_save_continues_to_final_sentinel_after_carry_emit_fails() -> None:
+ state = _streaming_state(chunks_sent=1)
+ state["_flush_carry"] = MagicMock(return_value="[12")
+ socket_service = MagicMock()
+ socket_service.emit_to_subscribers.side_effect = [
+ RuntimeError("down"),
+ None,
+ ]
+
+ with (
+ patch("local_deep_research.chat.service.ChatService"),
+ patch("local_deep_research.chat.context.ChatContextManager"),
+ ):
+ research_service._save_chat_message_and_context(
+ "chat-1",
+ "research-1",
+ "alice",
+ "answer",
+ True,
+ state,
+ socket_service,
+ )
+
+ assert socket_service.emit_to_subscribers.call_count == 2
+ assert (
+ socket_service.emit_to_subscribers.call_args.args[2]["is_final"] is True
+ )
+
+
+def test_stream_callback_releases_carry_when_sources_disappear() -> None:
+ state = _streaming_state()
+ socket_service = MagicMock()
+ formatter = MagicMock()
+ formatter.apply_inline_hyperlinks.side_effect = lambda text, _sources: text
+ source_resolver = MagicMock(
+ side_effect=[[{"url": "https://example.test"}], []]
+ )
+ callback = research_service._make_chat_stream_callback(
+ "research-1",
+ state,
+ socket_service,
+ "alice",
+ source_resolver=source_resolver,
+ formatter=formatter,
+ )
+
+ with patch(
+ "local_deep_research.web.routes.globals.is_termination_requested",
+ return_value=False,
+ ):
+ callback("[12")
+ callback(" remains text")
+
+ socket_service.emit_to_subscribers.assert_called_once()
+ assert socket_service.emit_to_subscribers.call_args.args[2]["chunk"] == (
+ "[12 remains text"
+ )
+
+
+def test_stream_callback_emits_raw_chunk_when_hyperlinking_fails() -> None:
+ state = _streaming_state()
+ socket_service = MagicMock()
+ formatter = MagicMock()
+ formatter.apply_inline_hyperlinks.side_effect = RuntimeError(
+ "formatter failed"
+ )
+ callback = research_service._make_chat_stream_callback(
+ "research-1",
+ state,
+ socket_service,
+ "alice",
+ source_resolver=lambda: [{"url": "https://example.test"}],
+ formatter=formatter,
+ )
+
+ with patch(
+ "local_deep_research.web.routes.globals.is_termination_requested",
+ return_value=False,
+ ):
+ callback("raw answer")
+
+ assert (
+ socket_service.emit_to_subscribers.call_args.args[2]["chunk"]
+ == "raw answer"
+ )
+
+
[email protected]("held", ["[", "[12", "【12"])
[email protected]("next_chunk", ["3]", " complete [3"])
+def test_stream_callback_preserves_carry_after_hyperlinking_failure(
+ held: str, next_chunk: str
+) -> None:
+ state = _streaming_state()
+ socket_service = MagicMock()
+ formatter = MagicMock()
+ formatter.apply_inline_hyperlinks.side_effect = lambda text, _sources: text
+ source_resolver = MagicMock(return_value=[{"url": "https://example.test"}])
+ callback = research_service._make_chat_stream_callback(
+ "research-1",
+ state,
+ socket_service,
+ "alice",
+ source_resolver=source_resolver,
+ formatter=formatter,
+ )
+
+ with patch(
+ "local_deep_research.web.routes.globals.is_termination_requested",
+ return_value=False,
+ ):
+ callback(held)
+ socket_service.emit_to_subscribers.assert_not_called()
+ formatter.apply_inline_hyperlinks.side_effect = RuntimeError(
+ "formatter failed"
+ )
+ callback(next_chunk)
+
+ socket_service.emit_to_subscribers.assert_called_once()
+ assert socket_service.emit_to_subscribers.call_args.args[2][
+ "chunk"
+ ] == (held + next_chunk)
+ assert state["_flush_carry"]() == ""
+ assert state["chunks"] == [held, next_chunk]
+
+ formatter.apply_inline_hyperlinks.side_effect = lambda text, _sources: (
+ text
+ )
+ callback(" after")
+
+ displayed = "".join(
+ call.args[2]["chunk"]
+ for call in socket_service.emit_to_subscribers.call_args_list
+ )
+ assert displayed == held + next_chunk + " after"
+ assert state["chunks"] == [held, next_chunk, " after"]
+
+
+def test_stream_callback_swallows_socket_failure() -> None:
+ state = _streaming_state()
+ socket_service = MagicMock()
+ socket_service.emit_to_subscribers.side_effect = RuntimeError(
+ "socket failed"
+ )
+ callback = research_service._make_chat_stream_callback(
+ "research-1", state, socket_service, "alice"
+ )
+
+ with patch(
+ "local_deep_research.web.routes.globals.is_termination_requested",
+ return_value=False,
+ ):
+ callback("answer")
+
+ socket_service.emit_to_subscribers.assert_called_once()
+ assert state["chunks"] == ["answer"]
+
+
+def test_terminate_persistence_survives_final_socket_failure() -> None:
+ state = _streaming_state()
+ chat_service = MagicMock()
+ # autospec, not a bare MagicMock: see the rationale in helpers.py's
+ # ``_base_run_patches`` for why the adapter singleton is patched with a
+ # signature-enforcing mock rather than one that accepts any call shape.
+ socket_emitter = create_autospec(
+ research_service._socket_emitter, spec_set=True
+ )
+ socket_emitter.emit_to_subscribers.side_effect = RuntimeError(
+ "socket failed"
+ )
+
+ with (
+ patch(
+ "local_deep_research.chat.service.ChatService",
+ return_value=chat_service,
+ ),
+ patch(f"{MODULE}._socket_emitter", socket_emitter),
+ ):
+ research_service._save_partial_chat_message_on_terminate(
+ "chat-1",
+ "research-1",
+ "alice",
+ "partial answer",
+ streaming_state=state,
+ )
+
+ socket_emitter.emit_to_subscribers.assert_called_once()
+ assert state["_persisted"] is True
+ chat_service.add_message.assert_called_once()
+
+
+ ("error_type", "message_fragment"),
+ [
+ ("openai_connection_refused", "Could not connect"),
+ ("openai_timeout", "timed out"),
+ ("openai_auth", "Authentication"),
+ ("openai_permission_denied", "denied access"),
+ ("openai_model_not_found", "model was not found"),
+ ("openai_bad_request", "rejected the request"),
+ ("openai_unknown", "returned an error"),
+ ("openai_rate_limit", "rate-limited"),
+ ],
+)
+def test_openai_error_tokens_map_to_safe_actionable_failures(
+ error_type: str, message_fragment: str
+) -> None:
+ raw_token = f"Error type: {error_type} canary-9d61"
+
+ call = _run_with(
+ f"{MODULE}.get_llm",
+ raw_token,
+ model="model-1",
+ model_provider="openai",
+ )
+
+ assert message_fragment in call.kwargs["error_message"]
+ assert raw_token not in call.kwargs["error_message"]
+ assert call.kwargs["metadata"]["solution"]
+ assert "canary-9d61" not in str(call)
+
+
+@contextmanager
+def _session(session: MagicMock) -> Iterator[MagicMock]:
+ yield session
+
+
+def test_cancel_returns_false_when_owned_row_disappears_before_status_read() -> (
+ None
+):
+ owner_session = MagicMock()
+ owner_session.query.return_value.filter_by.return_value.first.return_value = object()
+ status_session = MagicMock()
+ status_session.query.return_value.filter_by.return_value.first.return_value = None
+
+ with (
+ patch(
+ f"{MODULE}.get_user_db_session",
+ side_effect=[_session(owner_session), _session(status_session)],
+ ),
+ patch(
+ "local_deep_research.web.research_state.set_termination_flag"
+ ) as set_flag,
+ patch(
+ "local_deep_research.web.research_state.is_research_active",
+ return_value=False,
+ ),
+ ):
+ result = research_service.cancel_research("research-1", "alice")
+
+ assert result is False
+ set_flag.assert_called_once_with("research-1")
+
+
+def test_cancel_returns_false_when_second_database_access_fails() -> None:
+ owner_session = MagicMock()
+ owner_session.query.return_value.filter_by.return_value.first.return_value = object()
+
+ with (
+ patch(
+ f"{MODULE}.get_user_db_session",
+ side_effect=[
+ _session(owner_session),
+ RuntimeError("database failed"),
+ ],
+ ) as get_user_db_session,
+ patch("local_deep_research.web.research_state.set_termination_flag"),
+ patch(
+ "local_deep_research.web.research_state.is_research_active",
+ return_value=False,
+ ),
+ patch(f"{MODULE}.logger") as logger,
+ ):
+ result = research_service.cancel_research("research-1", "alice")
+
+ assert result is False
+ # Confirms the ownership check and the status update each open their own
+ # session (not a reused one) before either can fail.
+ assert get_user_db_session.call_count == 2
+ # Removing the inner except (the one wrapping the second database
+ # access) does not change ``result`` or ``call_count`` -- the outer
+ # except at the bottom of cancel_research also returns False after the
+ # same two accesses. What it does change is which handler logs, so pin
+ # that: the inner handler's "Error accessing database" message, not the
+ # outer handler's "Unexpected error in cancel_research".
+ logger.exception.assert_called_once()
+ assert "Error accessing database" in logger.exception.call_args.args[0]
diff --git a/tests/web/services/test_research_service_execution.py b/tests/web/services/test_research_service_execution.py
index c873fa2446..0b754827ee 100644
--- a/tests/web/services/test_research_service_execution.py
+++ b/tests/web/services/test_research_service_execution.py
@@ -107,6 +107,11 @@ class TestProgressCallback:
cb("x", None, {"phase": "output_generation"}) # must not raise
assert state[0] == baseline
+ def test_quick_output_generation_starts_at_eighty_five_percent(self):
+ with captured_progress_callback("quick") as (callback, state, _):
+ callback("starting output", 0, {"phase": "output_generation"})
+ assert state[0] == 85
+
def test_search_plan_extracted_from_message(self):
"""SEARCH_PLAN: in message → engines extracted into metadata."""
with captured_progress_callback("detailed") as (cb, _, __):