coderouter-cli 2.14.0__tar.gz → 2.15.0__tar.gz

{coderouter_cli-2.14.0 → coderouter_cli-2.15.0}/CHANGELOG.md

@@ -9,6 +9,136 @@ are kept verbatim where the Japanese text itself is the subject).
 
 ---
 
+## [v2.15.0] — 2026-08-21 (fallback explainability + stream truncation detection)
+
+### Added
+
+- **Fallback explainability — `X-CodeRouter-Fallback-*` response headers.**
+  When a request changes providers, the response now says who it left, who
+  took over, and why: `X-CodeRouter-Fallback-From` / `-To` / `-Reason` /
+  `-Chain` (multi-hop chains render as `local>ollama>openrouter` with one
+  comma-separated reason per departure). Reasons come from a single
+  canonical vocabulary in `coderouter/routing/fallback_trace.py` covering
+  both chain-resolve filters (`paid-gate`, `budget-exceeded`,
+  `memory-pressure`, `backend-unhealthy`, `self-healing-excluded`,
+  `unknown-provider`) and runtime attempt failures (`timeout`,
+  `rate-limit`, `auth`, `upstream-5xx`, `upstream-4xx`, `connection`,
+  `empty-response`, `empty-stream`). The same trail is emitted as
+  structured `fallback-occurred` log lines (auditable) and, on the
+  Anthropic streaming path, as a trailing `coderouter_fallback` SSE
+  metadata event for reasons discovered after the HTTP headers ship.
+  Purely additive — a request served by its first provider produces no new
+  headers, no SSE trailer and no log lines.
+- **Stream truncation detection — `stream_truncation_action`
+  (`off` | `warn` | `error`, default `off`).** An upstream can end its HTTP
+  body *cleanly* while the LLM protocol carried inside it is still
+  mid-message: no `message_stop` on the Anthropic wire, no `data: [DONE]`
+  and no `finish_reason` on the OpenAI wire. llama.cpp slot preemption, an
+  `--n-predict` cut-off, a proxy closing an EOF-delimited body, or a local
+  server that OOM'd all look exactly like that. Transport breakage
+  (timeouts, `httpx.RemoteProtocolError`) was already caught; this is the
+  layer the transport cannot see, and until now CodeRouter reported it as a
+  *successful* completion — the translation layer's terminator-synthesis
+  guards fabricated `stop_reason: end_turn` so the client would not hang,
+  which also erased every trace of the cut. The synthesis stays (removing
+  it hangs Claude Code); what is new is that the engine gets told. Both
+  adapters now track whether a terminator arrived, and under `error` raise
+  a retryable `StreamTruncatedError` that joins the *existing* branches: no
+  bytes forwarded yet → fall back to the next provider with reason
+  `stream-truncated`; bytes already out → `MidStreamError`, which
+  `partial_stitch_action: surface` renders as a graceful close carrying a
+  `coderouter_partial` event labelled `stream_truncated`. If *every*
+  provider in the chain truncates before any byte reached the client, the
+  request ends in `NoProvidersAvailableError` (an `overloaded_error` SSE
+  frame) rather than flushing a half-written message — see **Fixed** below.
+  Because the failure is an ordinary `AdapterError`, the L2/L4/L5/L6
+  self-healing guards learn it — a backend that keeps going quiet gets
+  demoted by adaptive routing instead of being *preferred* for its fast
+  first byte. `warn` measures without changing a single byte of output;
+  `off` is byte-for-byte v2.14.0 **on the wire** — see the caveat on
+  guard-internal state below. Observability: a `stream-truncation-detected` log
+  line (with `wire`, `events_forwarded`, `saw_stream_start`,
+  `tool_call_in_flight`), `stream_truncated_total` in `/metrics.json` and
+  Prometheus (labelled by provider and by action), and the
+  `stream-truncated` reason on the `X-CodeRouter-Fallback-*` headers.
+  Terminator matching is deliberately lenient — a `message_delta` carrying
+  a `stop_reason`, or a `finish_reason` on any choice, both count — so
+  providers that legitimately omit the sentinel are not flagged. On the
+  Anthropic streaming path, pre-content fallback additionally needs
+  `empty_response_action: fallback`, which is the knob that withholds the
+  opening events from the client. Known gap: the terminator synthesis this
+  entry refers to lives in `translation/convert.py`, so the one route that
+  does not pass through it — `/v1/messages` served by a `kind: anthropic`
+  backend, i.e. native passthrough — has never had it. Under `off` a
+  truncated native stream still reaches the client unterminated, exactly as
+  in v2.14.0; that route is the strongest argument for moving to `warn`.
+  Docs: `docs/concepts/stream-truncation.md` / `.en.md`.
+- **Tool-call integrity regression tests across a fallback hop**
+  (`tests/test_fallback_tool_integrity.py`): the conversation handed to the
+  second provider keeps every `tool_use` / `tool_result` id paired, and the
+  response the client receives is still a structurally valid `tool_use`
+  block on both the buffered and the streaming path.
+- **Stream truncation tests** (`tests/test_stream_truncation.py`): both
+  adapters driven over real SSE bodies (off / warn / error, the
+  terminator-leniency false-positive guards, the tool-call-in-flight flag),
+  engine-level fallback and `MidStreamError` integration, the ingress
+  `coderouter_partial` labelling, and an explicit `off` regression proving
+  the default path — including the H6 terminator synthesis — is unchanged.
+
+### Fixed
+
+- **Anthropic streaming: a provider that failed before forwarding any byte
+  was invisible to the self-healing guards.** Under
+  `empty_response_action: fallback` the engine withholds the opening events
+  until real content appears, and an `AdapterError` raised in that window
+  is handled by swapping providers instead of raising. That branch recorded
+  an adaptive failure but never called the L2 memory-pressure / L4 drift /
+  L5 backend-health hooks — while `_observe_provider_success` had *already*
+  fired the moment the first event landed. The net effect was a backend
+  that opens a stream and then dies keeping a clean bill of health, and
+  adaptive routing preferring it for its fast first byte. The identical
+  failure under `empty_response_action: off` takes the mid-stream path and
+  *was* observed, so provider health effectively depended on an unrelated
+  knob. Both hooks now run on that branch (and the error joins the `errors`
+  list carried by `NoProvidersAvailableError`), matching the mid-stream
+  sibling. A stream that terminates cleanly with no content is still not a
+  failure — it is a 200 blank, and reaches neither hook.
+  **Operational note:** this is a behavior change for anyone already
+  running `empty_response_action: fallback` — pre-content failures now
+  reach L2/L4/L5, so if `memory_pressure_action: skip` and/or
+  `backend_health_action: demote` are also set, skips and demotions can
+  become *more frequent* for a backend that was silently dying before real
+  content shipped, even though nothing about those knobs' own
+  configuration changed. This is independent of `stream_truncation_action`
+  — it fires under the default `off` exactly as it does under `warn` /
+  `error`, since the branch it lives in is the *pre-existing*
+  `empty_response_action: fallback` path, not the new truncation
+  detection. See `docs/concepts/stream-truncation.md` / `.en.md` for
+  details.
+- **Anthropic streaming: a chain where every provider truncated left the
+  client hanging.** On chain exhaustion the engine flushes the last
+  buffered preamble so a genuinely empty chain returns a well-formed 200
+  blank (`message_start` … `message_stop`). A *truncated* stream's buffer
+  has no `message_stop` by definition, so flushing it emitted an SSE
+  sequence that never ended — no exception, no error frame, and a client
+  waiting forever — and charged `empty_responses_total` for a stream that
+  was not empty. The flush is now gated on the buffer actually terminating;
+  a truncation-produced buffer falls through to `NoProvidersAvailableError`,
+  which the ingress turns into a terminal `overloaded_error` SSE frame. Only
+  reachable with `stream_truncation_action: error`, so the default path is
+  unchanged, and the empty-chain 200 blank is untouched (including the
+  mixed case where a truncated hop is followed by a provider that answered
+  with a well-formed empty message — that buffer still gets flushed).
+- **`partial-stitch-surfaced` log shape under the default `off`.** The
+  `reason` key added for truncation labelling was attached
+  unconditionally, so every `partial_stitch_action: surface` log line
+  gained a field even where truncation detection is disabled and the value
+  could only ever be `mid_stream_failure`. It is now emitted only when it
+  says something new, restoring the v2.14.0 key set. (`/metrics.json` was
+  never affected — `MetricsCollector` whitelists the fields it copies.)
+
+---
+
 ## [v2.14.0] — 2026-08-09 (credential hygiene + undo)
 
 Five changes that came out of reading `duolahypercho/codex-router` and

{coderouter_cli-2.14.0 → coderouter_cli-2.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: coderouter-cli
-Version: 2.14.0
+Version: 2.15.0
 Summary: Local-first, free-first, fallback-built-in LLM router. Claude Code / OpenAI compatible.
 Project-URL: Homepage, https://github.com/zephel01/CodeRouter
 Project-URL: Repository, https://github.com/zephel01/CodeRouter

{coderouter_cli-2.14.0 → coderouter_cli-2.15.0}/coderouter/adapters/anthropic_native.py

@@ -44,9 +44,14 @@ from coderouter.adapters.base import (
     ChatResponse,
     ProviderCallOverrides,
     StreamChunk,
+    StreamTruncatedError,
 )
 from coderouter.credentials import resolve_provider_credential
-from coderouter.logging import get_logger, log_output_filter_applied
+from coderouter.logging import (
+    get_logger,
+    log_output_filter_applied,
+    log_stream_truncation_detected,
+)
 from coderouter.output_filters import OutputFilterChain
 from coderouter.translation.anthropic import (
     AnthropicRequest,
@@ -74,6 +79,74 @@ _RETRYABLE_STATUSES = {404, 408, 425, 429, 500, 502, 503, 504}
 _DEFAULT_ANTHROPIC_VERSION = "2023-06-01"
 
 
+class _AnthropicTerminatorTracker:
+    """v2.15.0: watch an Anthropic SSE event stream for its terminator.
+
+    The parse loop in :meth:`AnthropicAdapter.stream_anthropic` used to be
+    stateless across events — ``current_event`` was reset on every blank
+    line and nothing remembered whether the stream had ended *properly*.
+    That made "upstream sent 30 deltas and hung up" indistinguishable from
+    "upstream sent the whole message". This tracker is the missing memory.
+
+    What counts as a terminator (deliberately generous, to keep the false
+    positive rate down — see ``stream_truncation_action`` in
+    ``config/schemas.py``):
+
+    * ``message_stop`` — the canonical Anthropic terminator.
+    * ``message_delta`` carrying a non-null ``stop_reason`` — the message is
+      semantically complete even if the provider omits ``message_stop``.
+      Some Anthropic-compatible local servers do exactly that, and their
+      content is *not* truncated, so flagging them would be a false positive.
+    * a top-level ``error`` event — the upstream ended the stream on purpose
+      and the frame is forwarded to the client verbatim (current behavior).
+      Reporting truncation on top would double-report one failure.
+
+    ``open_block_type`` tracks the currently-open content block so a stream
+    cut in the middle of a ``tool_use`` block's ``input_json_delta`` can be
+    reported as such: that is the case where the translation layer's
+    terminator synthesis closes a block whose argument JSON is provably
+    incomplete.
+    """
+
+    __slots__ = ("events", "open_block_type", "saw_start", "saw_terminator")
+
+    def __init__(self) -> None:
+        """Start with nothing observed."""
+        self.saw_terminator: bool = False
+        self.saw_start: bool = False
+        self.events: int = 0
+        self.open_block_type: str | None = None
+
+    def observe(self, event_type: str, data: Any) -> None:
+        """Fold one parsed SSE event into the tracked state.
+
+        ``data`` is whatever ``json.loads`` produced for the block, so it is
+        not guaranteed to be a mapping; non-dict payloads are treated as
+        empty rather than raising inside a streaming hot path.
+        """
+        self.events += 1
+        if not isinstance(data, dict):
+            data = {}
+        if event_type == "message_start":
+            self.saw_start = True
+        elif event_type == "content_block_start":
+            block = data.get("content_block")
+            self.open_block_type = block.get("type") if isinstance(block, dict) else None
+        elif event_type == "content_block_stop":
+            self.open_block_type = None
+        elif event_type == "message_delta":
+            delta = data.get("delta")
+            if isinstance(delta, dict) and delta.get("stop_reason"):
+                self.saw_terminator = True
+        elif event_type in {"message_stop", "error"}:
+            self.saw_terminator = True
+
+    @property
+    def tool_call_in_flight(self) -> bool:
+        """True when a ``tool_use`` block was still open at end-of-stream."""
+        return self.open_block_type == "tool_use"
+
+
 def anthropic_messages_url(base_url: str) -> str:
     """Resolve the ``/v1/messages`` endpoint URL from a ``base_url``.
 
@@ -475,6 +548,12 @@ class AnthropicAdapter(BaseAdapter):
         filter_chains: dict[int, OutputFilterChain] = {}
         logged_flag: list[bool] = [False]
 
+        # v2.15.0 (stream-truncation): remember whether the upstream ever
+        # terminated its message. Resolved once per call — the knob is a
+        # profile-level setting threaded in through ProviderCallOverrides.
+        truncation_action = self.effective_stream_truncation_action(overrides)
+        terminator = _AnthropicTerminatorTracker()
+
         try:
             # H3: stream over the shared client (pool / keep-alive / TLS
             # reuse). Only the ``stream(...)`` context is scoped here; the
@@ -514,6 +593,7 @@ class AnthropicAdapter(BaseAdapter):
                                 current_event = None
                                 data_lines = []
                                 continue
+                            terminator.observe(current_event, data_obj)
                             for out_event in self._process_stream_event_for_filters(
                                 AnthropicStreamEvent(type=current_event, data=data_obj),
                                 chains=filter_chains,
@@ -542,12 +622,37 @@ class AnthropicAdapter(BaseAdapter):
                     except json.JSONDecodeError:
                         data_obj = None
                     if data_obj is not None:
+                        terminator.observe(current_event, data_obj)
                         for out_event in self._process_stream_event_for_filters(
                             AnthropicStreamEvent(type=current_event, data=data_obj),
                             chains=filter_chains,
                             logged_flag=logged_flag,
                         ):
                             yield out_event
+
+            # v2.15.0 (stream-truncation): the upstream line iterator is
+            # exhausted. Reaching here with no terminator observed means the
+            # HTTP body ended cleanly while the Anthropic message was still
+            # open — the exact case transport-level error handling below
+            # cannot see (``httpx.RemoteProtocolError`` and timeouts already
+            # raise). Under ``off`` this block is inert, which is what keeps
+            # the default byte-for-byte identical to v2.14.0.
+            if truncation_action != "off" and not terminator.saw_terminator:
+                log_stream_truncation_detected(
+                    logger,
+                    self.name,
+                    action=truncation_action,
+                    wire="anthropic",
+                    events_forwarded=terminator.events,
+                    saw_stream_start=terminator.saw_start,
+                    tool_call_in_flight=terminator.tool_call_in_flight,
+                )
+                if truncation_action == "error":
+                    raise StreamTruncatedError(
+                        "upstream stream truncated (no message_stop terminator)",
+                        provider=self.name,
+                        tool_call_in_flight=terminator.tool_call_in_flight,
+                    )
         except httpx.TimeoutException as exc:
             raise AdapterError(
                 f"timeout streaming from {url}", provider=self.name, retryable=True

{coderouter_cli-2.14.0 → coderouter_cli-2.15.0}/coderouter/adapters/base.py

@@ -137,6 +137,49 @@ class AdapterError(CodeRouterError):
         return f"[{self.provider}{sc}] {super().__str__()}"
 
 
+# v2.15.0 (stream-truncation): raised by an adapter when the upstream SSE
+# stream ended *without* its protocol terminator (``message_stop`` on the
+# Anthropic wire, ``data: [DONE]`` / a ``finish_reason`` on the OpenAI wire).
+#
+# HTTP-level breakage (timeout, ``httpx.RemoteProtocolError``) already became a
+# plain ``AdapterError`` in both adapters. This subclass covers the layer
+# mismatch the transport cannot see: the HTTP body ended cleanly, but the *LLM
+# protocol* carried inside it was still mid-message.
+#
+# It subclasses ``AdapterError`` on purpose — every existing engine branch
+# (``except AdapterError``) keeps working untouched, and the L2/L4/L5/L6 guards
+# learn from the failure automatically. The subclass only adds identity, so
+# ``classify_adapter_error`` can label the hop ``stream-truncated`` instead of
+# the generic ``upstream-error``.
+#
+# Raised only when the active profile sets ``stream_truncation_action: error``.
+# Under ``off`` (the default) and ``warn`` the adapter returns normally and the
+# legacy terminator-synthesis path in ``coderouter.translation.convert`` (H6 /
+# M9) runs byte-for-byte as before.
+class StreamTruncatedError(AdapterError):
+    """Upstream SSE stream ended without its protocol terminator event."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        provider: str,
+        tool_call_in_flight: bool = False,
+    ) -> None:
+        """Construct a truncation error.
+
+        Args:
+            message: Human-readable reason. Never contains upstream body text.
+            provider: The ``ProviderConfig.name`` whose stream was cut.
+            tool_call_in_flight: True when the stream was cut while a
+                ``tool_use`` / ``tool_calls`` block was still open, i.e. the
+                accumulated argument JSON is certainly incomplete. Carried for
+                observability only — it never changes control flow.
+        """
+        super().__init__(message, provider=provider, status_code=None, retryable=True)
+        self.tool_call_in_flight = tool_call_in_flight
+
+
 # v0.6-B: per-call overrides resolved from the active profile. The engine
 # builds one instance per request (since a profile is invariant across its
 # chain) and threads it through every adapter call on that chain. Adapters
@@ -150,6 +193,13 @@ class AdapterError(CodeRouterError):
 #   - ``append_system_prompt=""`` is a meaningful explicit value: "for
 #     this profile, clear the provider's directive". The adapter must
 #     distinguish ``None`` (no override) from ``""`` (override-to-empty).
+#
+# v2.15.0 (stream-truncation): ``stream_truncation_action`` rides the same
+# channel. It is a *profile*-level knob but has to be read inside the adapter's
+# SSE parse loop, and ``ProviderCallOverrides`` is the only object the engine
+# already threads into every adapter call. Its default of ``"off"`` keeps
+# ``ProviderCallOverrides()`` (and every legacy call site that passes nothing)
+# on the pre-v2.15.0 behavior.
 class ProviderCallOverrides(BaseModel):
     """Per-call provider overrides, resolved from the active profile."""
 
@@ -157,6 +207,7 @@ class ProviderCallOverrides(BaseModel):
 
     timeout_s: float | None = None
     append_system_prompt: str | None = None
+    stream_truncation_action: Literal["off", "warn", "error"] = "off"
 
 
 class BaseAdapter(ABC):
@@ -236,6 +287,20 @@ class BaseAdapter(ABC):
             return overrides.append_system_prompt or None
         return self.config.append_system_prompt
 
+    def effective_stream_truncation_action(
+        self, overrides: ProviderCallOverrides | None
+    ) -> str:
+        """v2.15.0: resolve ``stream_truncation_action`` for this call.
+
+        There is no per-provider counterpart — the knob lives on the profile
+        only — so this is just a null-safe read. ``None`` overrides (legacy
+        call sites, unit tests constructing adapters directly) resolve to
+        ``"off"``, which is the pre-v2.15.0 behavior.
+        """
+        if overrides is None:
+            return "off"
+        return overrides.stream_truncation_action
+
     @abstractmethod
     async def healthcheck(self) -> bool:
         """Lightweight check that the upstream is reachable. Return True if healthy."""

{coderouter_cli-2.14.0 → coderouter_cli-2.15.0}/coderouter/adapters/openai_compat.py

@@ -28,12 +28,14 @@ from coderouter.adapters.base import (
     ChatResponse,
     ProviderCallOverrides,
     StreamChunk,
+    StreamTruncatedError,
 )
 from coderouter.credentials import resolve_provider_credential
 from coderouter.logging import (
     get_logger,
     log_capability_degraded,
     log_output_filter_applied,
+    log_stream_truncation_detected,
 )
 from coderouter.output_filters import OutputFilterChain
 
@@ -347,6 +349,20 @@ class OpenAICompatAdapter(BaseAdapter):
         # Captured for the closing flush chunk (if any): reuse the last
         # seen chunk's id/model so the flush emission looks native.
         last_chunk_template: dict[str, Any] | None = None
+
+        # v2.15.0 (stream-truncation): the loop below used to treat "saw
+        # [DONE]" and "the line iterator ran out" as the same event. These
+        # three flags are the memory that tells them apart.
+        #
+        # A terminator is EITHER ``data: [DONE]`` OR a ``finish_reason`` on
+        # any choice. Accepting ``finish_reason`` matters: a provider that
+        # emits a complete message and then closes without the ``[DONE]``
+        # sentinel is not truncated, and flagging it would be a false
+        # positive. See ``stream_truncation_action`` in ``config/schemas.py``.
+        truncation_action = self.effective_stream_truncation_action(overrides)
+        saw_terminator = False
+        chunks_seen = 0
+        tool_call_in_flight = False
         try:
             # H3: stream over the shared client so the connection pool /
             # keep-alive / TLS session are reused. Only the ``stream(...)``
@@ -376,11 +392,31 @@ class OpenAICompatAdapter(BaseAdapter):
                         continue
                     data_str = line[len("data:") :].strip()
                     if data_str == "[DONE]":
+                        # v2.15.0: the sentinel — this stream ended on purpose.
+                        saw_terminator = True
                         break
                     try:
                         payload_obj = json.loads(data_str)
                     except json.JSONDecodeError:
                         continue  # skip malformed chunks rather than abort
+                    # v2.15.0 (stream-truncation): fold this chunk into the
+                    # terminator state before any filtering / validation, so a
+                    # chunk that is later dropped as malformed still counts as
+                    # "the upstream got this far".
+                    chunks_seen += 1
+                    for _choice in payload_obj.get("choices") or []:
+                        if not isinstance(_choice, dict):
+                            continue
+                        if _choice.get("finish_reason"):
+                            # A finish_reason means the message is complete
+                            # even if the [DONE] sentinel never arrives, and
+                            # it also closes any tool call that was open.
+                            saw_terminator = True
+                            tool_call_in_flight = False
+                        elif isinstance(_choice.get("delta"), dict) and _choice[
+                            "delta"
+                        ].get("tool_calls"):
+                            tool_call_in_flight = True
                     if strip_reasoning:
                         stripped = _strip_reasoning_field(
                             payload_obj.get("choices"), delta_key=True
@@ -446,6 +482,30 @@ class OpenAICompatAdapter(BaseAdapter):
                         streaming=True,
                     )
                     output_filter_logged = True
+
+            # v2.15.0 (stream-truncation): decided AFTER the filter flush on
+            # purpose — the flush is the last chance to hand the caller every
+            # safe byte the filter chain was still holding, and under
+            # ``partial_stitch_action: surface`` those bytes end up in the
+            # partial content the client receives. Under ``off`` this block is
+            # inert, keeping the default byte-for-byte identical to v2.14.0.
+            if truncation_action != "off" and not saw_terminator:
+                log_stream_truncation_detected(
+                    logger,
+                    self.name,
+                    action=truncation_action,
+                    wire="openai",
+                    events_forwarded=chunks_seen,
+                    saw_stream_start=chunks_seen > 0,
+                    tool_call_in_flight=tool_call_in_flight,
+                )
+                if truncation_action == "error":
+                    raise StreamTruncatedError(
+                        "upstream stream truncated "
+                        "(no [DONE] sentinel and no finish_reason)",
+                        provider=self.name,
+                        tool_call_in_flight=tool_call_in_flight,
+                    )
         except httpx.TimeoutException as exc:
             raise AdapterError(
                 f"timeout streaming from {url}", provider=self.name, retryable=True

{coderouter_cli-2.14.0 → coderouter_cli-2.15.0}/coderouter/config/schemas.py

@@ -1232,6 +1232,71 @@ class FallbackChain(BaseModel):
         ),
     )
 
+    # --- v2.15.0 (stream-truncation): upstream SSE cut without a terminator --
+    #
+    # A streaming upstream can end its HTTP body *cleanly* while the LLM
+    # protocol carried inside it is still mid-message: no ``message_stop`` on
+    # the Anthropic wire, no ``data: [DONE]`` and no ``finish_reason`` on the
+    # OpenAI wire. llama.cpp slot preemption, an ``--n-predict`` cut-off, a
+    # front proxy closing an EOF-delimited body, or an OOM'd local server all
+    # produce exactly this shape. Transport-level breakage (timeout,
+    # ``httpx.RemoteProtocolError``) was already caught; this is the layer the
+    # transport cannot see.
+    #
+    # Before v2.15.0 that stream was indistinguishable from a complete one:
+    # the adapters never recorded whether a terminator arrived, and the
+    # translation layer's terminator-synthesis guards (H6 / M9 in
+    # ``coderouter.translation.convert``) then fabricated a ``stop_reason:
+    # end_turn`` / ``finish_reason: "stop"`` so the client would not hang. The
+    # synthesis is correct and stays; what was missing is telling the *engine*
+    # that it happened.
+    #
+    #   * ``off``   — no detection, no log, no metric. Backward-compatible
+    #                 default: byte-for-byte identical to v2.14.0 on every path.
+    #   * ``warn``  — emit a ``stream-truncation-detected`` log line (and the
+    #                 ``stream_truncated_total`` metric); the stream still
+    #                 terminates through the legacy synthesis path, so the
+    #                 client sees exactly what it saw before.
+    #   * ``error`` — the adapter raises ``StreamTruncatedError`` (a retryable
+    #                 ``AdapterError``) at the point the terminator should have
+    #                 arrived. The engine's existing branches take over: no
+    #                 bytes forwarded yet → fall back to the next provider with
+    #                 reason ``stream-truncated``; bytes already forwarded →
+    #                 ``MidStreamError``, which ``partial_stitch_action:
+    #                 surface`` renders as a graceful close carrying a
+    #                 ``coderouter_partial`` event with reason
+    #                 ``stream_truncated``.
+    #
+    # Caveats for ``error``:
+    #   * False positives are possible against an upstream that legitimately
+    #     omits the terminator. A ``message_delta`` carrying a ``stop_reason``
+    #     (Anthropic) and a ``finish_reason`` on any choice (OpenAI) are both
+    #     accepted as terminators to keep that risk low, but running ``warn``
+    #     first to measure the real rate is the recommended rollout.
+    #   * Falling back re-generates the answer on the next provider, so the
+    #     tokens the truncated attempt burned are paid twice.
+    #   * On the Anthropic streaming path the pre-content fallback requires
+    #     ``empty_response_action: fallback`` as well — that is the knob that
+    #     withholds the opening events from the client. Without it the opening
+    #     ``message_start`` has already shipped, so a truncation is by
+    #     definition mid-stream.
+    stream_truncation_action: Literal["off", "warn", "error"] = Field(
+        default="off",
+        description=(
+            "v2.15.0: action when an upstream SSE stream ends without its "
+            "protocol terminator (no ``message_stop`` / no ``[DONE]`` and no "
+            "``finish_reason``). ``off`` (default) does nothing — identical to "
+            "v2.14.0. ``warn`` emits a ``stream-truncation-detected`` log and "
+            "metric while the stream still ends through the legacy terminator "
+            "synthesis. ``error`` raises a retryable ``StreamTruncatedError`` "
+            "so the engine falls back to the next provider (reason "
+            "``stream-truncated``) when nothing has reached the client yet, or "
+            "raises ``MidStreamError`` when it has. Pair with "
+            "``empty_response_action: fallback`` for pre-content fallback on "
+            "the Anthropic streaming path."
+        ),
+    )
+
     # --- ⑧ (empty-response): per-request empty-response fallback ------------
     #
     # Some local backends (observed: gemma4:26b on ``no_tool_temptation``