SSE Done Sentinel Normalizer (proxy/sse_done.py)

Tracks and normalizes Server-Sent Events [DONE] sentinels for OpenAI-compatible streaming proxies. Reuse when ensuring reliable stream termination in HTTP proxy implementations.

# Source: https://github.com/fathah/hermes-agent | License: MIT | Copyright 2025 Nous Research
# Provided via justclaw.it.com; keep this notice with the code.
"""SSE ``[DONE]`` sentinel normalization for OpenAI-compatible proxies.

Strict OpenAI clients treat a stream without ``data: [DONE]`` as truncated. The tracker watches the
forwarded SSE bytes and says whether to append ONE ``[DONE]`` after a *clean* upstream EOF: only after
a terminal choice (``finish_reason`` non-null) or ``lastOne: true``; never after an error event, an
interrupted stream, or when the upstream already sent ``[DONE]``.
"""

from __future__ import annotations

import json
from dataclasses import dataclass, field


DONE_SSE_FRAME = b"data: [DONE]\n\n"


@dataclass
class SseDoneTracker:
    """Incremental scanner over

... (truncated -- full source via MCP)