Merge branch 'main' into rayhpeng/persistence-scaffold

# Conflicts:
#	.env.example
#	backend/packages/harness/deerflow/agents/middlewares/title_middleware.py

backend/app/gateway/routers/memory.py

@@ -49,6 +49,7 @@ class Fact(BaseModel):
     confidence: float = Field(default=0.5, description="Confidence score (0-1)")
     createdAt: str = Field(default="", description="Creation timestamp")
     source: str = Field(default="unknown", description="Source thread ID")
+    sourceError: str | None = Field(default=None, description="Optional description of the prior mistake or wrong approach")
 
 
 class MemoryResponse(BaseModel):
@@ -108,6 +109,7 @@ class MemoryStatusResponse(BaseModel):
 @router.get(
     "/memory",
     response_model=MemoryResponse,
+    response_model_exclude_none=True,
     summary="Get Memory Data",
     description="Retrieve the current global memory data including user context, history, and facts.",
 )
@@ -152,6 +154,7 @@ async def get_memory() -> MemoryResponse:
 @router.post(
     "/memory/reload",
     response_model=MemoryResponse,
+    response_model_exclude_none=True,
     summary="Reload Memory Data",
     description="Reload memory data from the storage file, refreshing the in-memory cache.",
 )
@@ -171,6 +174,7 @@ async def reload_memory() -> MemoryResponse:
 @router.delete(
     "/memory",
     response_model=MemoryResponse,
+    response_model_exclude_none=True,
     summary="Clear All Memory Data",
     description="Delete all saved memory data and reset the memory structure to an empty state.",
 )
@@ -187,6 +191,7 @@ async def clear_memory() -> MemoryResponse:
 @router.post(
     "/memory/facts",
     response_model=MemoryResponse,
+    response_model_exclude_none=True,
     summary="Create Memory Fact",
     description="Create a single saved memory fact manually.",
 )
@@ -209,6 +214,7 @@ async def create_memory_fact_endpoint(request: FactCreateRequest) -> MemoryRespo
 @router.delete(
     "/memory/facts/{fact_id}",
     response_model=MemoryResponse,
+    response_model_exclude_none=True,
     summary="Delete Memory Fact",
     description="Delete a single saved memory fact by its fact id.",
 )
@@ -227,6 +233,7 @@ async def delete_memory_fact_endpoint(fact_id: str) -> MemoryResponse:
 @router.patch(
     "/memory/facts/{fact_id}",
     response_model=MemoryResponse,
+    response_model_exclude_none=True,
     summary="Patch Memory Fact",
     description="Partially update a single saved memory fact by its fact id while preserving omitted fields.",
 )
@@ -252,6 +259,7 @@ async def update_memory_fact_endpoint(fact_id: str, request: FactPatchRequest) -
 @router.get(
     "/memory/export",
     response_model=MemoryResponse,
+    response_model_exclude_none=True,
     summary="Export Memory Data",
     description="Export the current global memory data as JSON for backup or transfer.",
 )
@@ -264,6 +272,7 @@ async def export_memory() -> MemoryResponse:
 @router.post(
     "/memory/import",
     response_model=MemoryResponse,
+    response_model_exclude_none=True,
     summary="Import Memory Data",
     description="Import and overwrite the current global memory data from a JSON payload.",
 )
@@ -317,6 +326,7 @@ async def get_memory_config_endpoint() -> MemoryConfigResponse:
 @router.get(
     "/memory/status",
     response_model=MemoryStatusResponse,
+    response_model_exclude_none=True,
     summary="Get Memory Status",
     description="Retrieve both memory configuration and current data in a single request.",
 )

backend/app/gateway/routers/suggestions.py

@@ -2,6 +2,7 @@ import json
 import logging
 
 from fastapi import APIRouter
+from langchain_core.messages import HumanMessage, SystemMessage
 from pydantic import BaseModel, Field
 
 from deerflow.models import create_chat_model
@@ -106,22 +107,21 @@ async def generate_suggestions(thread_id: str, request: SuggestionsRequest) -> S
     if not conversation:
         return SuggestionsResponse(suggestions=[])
 
-    prompt = (
+    system_instruction = (
         "You are generating follow-up questions to help the user continue the conversation.\n"
         f"Based on the conversation below, produce EXACTLY {n} short questions the user might ask next.\n"
         "Requirements:\n"
-        "- Questions must be relevant to the conversation.\n"
+        "- Questions must be relevant to the preceding conversation.\n"
         "- Questions must be written in the same language as the user.\n"
         "- Keep each question concise (ideally <= 20 words / <= 40 Chinese characters).\n"
         "- Do NOT include numbering, markdown, or any extra text.\n"
-        "- Output MUST be a JSON array of strings only.\n\n"
-        "Conversation:\n"
-        f"{conversation}\n"
+        "- Output MUST be a JSON array of strings only.\n"
     )
+    user_content = f"Conversation Context:\n{conversation}\n\nGenerate {n} follow-up questions"
 
     try:
         model = create_chat_model(name=request.model_name, thinking_enabled=False)
-        response = model.invoke(prompt)
+        response = await model.ainvoke([SystemMessage(content=system_instruction), HumanMessage(content=user_content)])
         raw = _extract_response_text(response.content)
         suggestions = _parse_json_string_list(raw) or []
         cleaned = [s.replace("\n", " ").strip() for s in suggestions if s.strip()]

backend/app/gateway/routers/thread_runs.py

@@ -38,6 +38,7 @@ class RunCreateRequest(BaseModel):
     command: dict[str, Any] | None = Field(default=None, description="LangGraph Command")
     metadata: dict[str, Any] | None = Field(default=None, description="Run metadata")
     config: dict[str, Any] | None = Field(default=None, description="RunnableConfig overrides")
+    context: dict[str, Any] | None = Field(default=None, description="DeerFlow context overrides (model_name, thinking_enabled, etc.)")
     webhook: str | None = Field(default=None, description="Completion callback URL")
     checkpoint_id: str | None = Field(default=None, description="Resume from checkpoint")
     checkpoint: dict[str, Any] | None = Field(default=None, description="Full checkpoint object")

backend/app/gateway/routers/threads.py

@@ -413,16 +413,19 @@ async def get_thread(thread_id: str, request: Request) -> ThreadResponse:
             "metadata": {k: v for k, v in ckpt_meta.items() if k not in ("created_at", "updated_at", "step", "source", "writes", "parents")},
         }
 
-    status = _derive_thread_status(checkpoint_tuple) if checkpoint_tuple is not None else record.get("status", "idle")  # type: ignore[union-attr]
+    if record is None:
+        raise HTTPException(status_code=404, detail=f"Thread {thread_id} not found")
+
+    status = _derive_thread_status(checkpoint_tuple) if checkpoint_tuple is not None else record.get("status", "idle")
     checkpoint = getattr(checkpoint_tuple, "checkpoint", {}) or {} if checkpoint_tuple is not None else {}
     channel_values = checkpoint.get("channel_values", {})
 
     return ThreadResponse(
         thread_id=thread_id,
         status=status,
-        created_at=str(record.get("created_at", "")),  # type: ignore[union-attr]
-        updated_at=str(record.get("updated_at", "")),  # type: ignore[union-attr]
-        metadata=record.get("metadata", {}),  # type: ignore[union-attr]
+        created_at=str(record.get("created_at", "")),
+        updated_at=str(record.get("updated_at", "")),
+        metadata=record.get("metadata", {}),
         values=serialize_channel_values(channel_values),
     )