fix: Refine clarification workflow state handling (#641)

* fix: support local models by making thought field optional in Plan model

- Make thought field optional in Plan model to fix Pydantic validation errors with local models
- Add Ollama configuration example to conf.yaml.example
- Update documentation to include local model support
- Improve planner prompt with better JSON format requirements

Fixes local model integration issues where models like qwen3:14b would fail
due to missing thought field in JSON output.

* feat: Add intelligent clarification feature for research queries

- Add multi-turn clarification process to refine vague research questions
- Implement three-dimension clarification standard (Tech/App, Focus, Scope)
- Add clarification state management in coordinator node
- Update coordinator prompt with detailed clarification guidelines
- Add UI settings to enable/disable clarification feature (disabled by default)
- Update workflow to handle clarification rounds recursively
- Add comprehensive test coverage for clarification functionality
- Update documentation with clarification feature usage guide

Key components:
- src/graph/nodes.py: Core clarification logic and state management
- src/prompts/coordinator.md: Detailed clarification guidelines
- src/workflow.py: Recursive clarification handling
- web/: UI settings integration
- tests/: Comprehensive test coverage
- docs/: Updated configuration guide

* fix: Improve clarification conversation continuity

- Add comprehensive conversation history to clarification context
- Include previous exchanges summary in system messages
- Add explicit guidelines for continuing rounds in coordinator prompt
- Prevent LLM from starting new topics during clarification
- Ensure topic continuity across clarification rounds

Fixes issue where LLM would restart clarification instead of building upon previous exchanges.

* fix: Add conversation history to clarification context

* fix: resolve clarification feature message to planer, prompt, test issues

- Optimize coordinator.md prompt template for better clarification flow
- Simplify final message sent to planner after clarification
- Fix API key assertion issues in test_search.py

* fix: Add configurable max_clarification_rounds and comprehensive tests

- Add max_clarification_rounds parameter for external configuration
- Add comprehensive test cases for clarification feature in test_app.py
- Fixes issues found during interactive mode testing where:
  - Recursive call failed due to missing initial_state parameter
  - Clarification exited prematurely at max rounds
  - Incorrect logging of max rounds reached

* Move clarification tests to test_nodes.py and add max_clarification_rounds to zh.json

* fix: add max_clarification_rounds parameter passing from frontend to backend

- Add max_clarification_rounds parameter in store.ts sendMessage function
- Add max_clarification_rounds type definition in chat.ts
- Ensure frontend settings page clarification rounds are correctly passed to backend

* fix: refine clarification workflow state handling and coverage

- Add clarification history reconstruction
- Fix clarified topic accumulation
- Add clarified_research_topic state field
- Preserve clarification state in recursive calls
- Add comprehensive test coverage

* refactor: optimize coordinator logic and type annotations

- Simplify handoff topic logic in coordinator_node
- Update type annotations from Tuple to tuple
- Improve code readability and maintainability

---------

Co-authored-by: Willem Jiang <willem.jiang@gmail.com>

tests/unit/server/test_app.py

@@ -47,6 +47,79 @@ class TestMakeEvent:
         assert result == expected
 
 
+@pytest.mark.asyncio
+async def test_astream_workflow_generator_preserves_clarification_history():
+    messages = [
+        {"role": "user", "content": "Research on renewable energy"},
+        {
+            "role": "assistant",
+            "content": "What type of renewable energy would you like to know about?",
+        },
+        {"role": "user", "content": "Solar and wind energy"},
+        {
+            "role": "assistant",
+            "content": "Please tell me the research dimensions you focus on, such as technological development or market applications.",
+        },
+        {"role": "user", "content": "Technological development"},
+        {
+            "role": "assistant",
+            "content": "Please specify the time range you want to focus on, such as current status or future trends.",
+        },
+        {"role": "user", "content": "Current status and future trends"},
+    ]
+
+    captured_data = {}
+
+    def empty_async_iterator(*args, **kwargs):
+        captured_data["workflow_input"] = args[1]
+        captured_data["workflow_config"] = args[2]
+
+        class IteratorObject:
+            def __aiter__(self):
+                return self
+
+            async def __anext__(self):
+                raise StopAsyncIteration
+
+        return IteratorObject()
+
+    with (
+        patch("src.server.app._process_initial_messages"),
+        patch("src.server.app._stream_graph_events", side_effect=empty_async_iterator),
+    ):
+        generator = _astream_workflow_generator(
+            messages=messages,
+            thread_id="clarification-thread",
+            resources=[],
+            max_plan_iterations=1,
+            max_step_num=1,
+            max_search_results=5,
+            auto_accepted_plan=True,
+            interrupt_feedback="",
+            mcp_settings={},
+            enable_background_investigation=True,
+            report_style=ReportStyle.ACADEMIC,
+            enable_deep_thinking=False,
+            enable_clarification=True,
+            max_clarification_rounds=3,
+        )
+
+        with pytest.raises(StopAsyncIteration):
+            await generator.__anext__()
+
+    workflow_input = captured_data["workflow_input"]
+    assert workflow_input["clarification_history"] == [
+        "Research on renewable energy",
+        "Solar and wind energy",
+        "Technological development",
+        "Current status and future trends",
+    ]
+    assert (
+        workflow_input["clarified_research_topic"]
+        == "Research on renewable energy - Solar and wind energy, Technological development, Current status and future trends"
+    )
+
+
 class TestTTSEndpoint:
     @patch.dict(
         os.environ,