From a9bf7ab7d23d27141da245fbd85d773071203940 Mon Sep 17 00:00:00 2001
From: CREDO23 <bakerathierry@gmail.com>
Date: Wed, 6 May 2026 20:08:47 +0200
Subject: [PATCH] Add SSE envelope helpers under app.services.streaming.

---
 .../services/streaming/envelope/__init__.py   | 23 +++++++++++++++++
 .../streaming/envelope/identifiers.py         | 25 +++++++++++++++++++
 .../app/services/streaming/envelope/sse.py    | 25 +++++++++++++++++++
 3 files changed, 73 insertions(+)
 create mode 100644 surfsense_backend/app/services/streaming/envelope/__init__.py
 create mode 100644 surfsense_backend/app/services/streaming/envelope/identifiers.py
 create mode 100644 surfsense_backend/app/services/streaming/envelope/sse.py

diff --git a/surfsense_backend/app/services/streaming/envelope/__init__.py b/surfsense_backend/app/services/streaming/envelope/__init__.py
new file mode 100644
index 000000000..862e84c8d
--- /dev/null
+++ b/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",
+]
diff --git a/surfsense_backend/app/services/streaming/envelope/identifiers.py b/surfsense_backend/app/services/streaming/envelope/identifiers.py
new file mode 100644
index 000000000..2fdd6ff09
--- /dev/null
+++ b/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}"
diff --git a/surfsense_backend/app/services/streaming/envelope/sse.py b/surfsense_backend/app/services/streaming/envelope/sse.py
new file mode 100644
index 000000000..508fc1b1c
--- /dev/null
+++ b/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",
+    }