Add SSE envelope helpers under app.services.streaming.

surfsense_backend/app/services/streaming/envelope/__init__.py

@@ -0,0 +1,23 @@
+"""Wire framing layer."""
+
+from __future__ import annotations
+
+from .identifiers import (
+    generate_message_id,
+    generate_reasoning_id,
+    generate_subagent_run_id,
+    generate_text_id,
+    generate_tool_call_id,
+)
+from .sse import format_done, format_sse, get_response_headers
+
+__all__ = [
+    "format_done",
+    "format_sse",
+    "generate_message_id",
+    "generate_reasoning_id",
+    "generate_subagent_run_id",
+    "generate_text_id",
+    "generate_tool_call_id",
+    "get_response_headers",
+]

surfsense_backend/app/services/streaming/envelope/identifiers.py

@@ -0,0 +1,25 @@
+"""Prefixed UUID generators for stream parts."""
+
+from __future__ import annotations
+
+import uuid
+
+
+def generate_message_id() -> str:
+    return f"msg_{uuid.uuid4().hex}"
+
+
+def generate_text_id() -> str:
+    return f"text_{uuid.uuid4().hex}"
+
+
+def generate_reasoning_id() -> str:
+    return f"reasoning_{uuid.uuid4().hex}"
+
+
+def generate_tool_call_id() -> str:
+    return f"call_{uuid.uuid4().hex}"
+
+
+def generate_subagent_run_id() -> str:
+    return f"subagent_{uuid.uuid4().hex}"

surfsense_backend/app/services/streaming/envelope/sse.py

@@ -0,0 +1,25 @@
+"""Server-Sent-Events wire framing."""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+
+def format_sse(data: Any) -> str:
+    if isinstance(data, str):
+        return f"data: {data}\n\n"
+    return f"data: {json.dumps(data)}\n\n"
+
+
+def format_done() -> str:
+    return "data: [DONE]\n\n"
+
+
+def get_response_headers() -> dict[str, str]:
+    return {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        "Connection": "keep-alive",
+        "x-vercel-ai-ui-message-stream": "v1",
+    }