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

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

@@ -9,6 +9,260 @@ 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
+comparing it with what CodeRouter actually does. Four of them close holes
+this project had; one imports a capability it was missing. Everything is
+opt-in except the `.envrc` behaviour change called out under **Changed
+(BREAKING)**.
+
+### Added
+
+- **`credential.source: cli_session` — borrow the token a vendor CLI
+  already wrote.** A subscription-authenticated provider (Kimi Code CLI,
+  Grok CLI, …) can now be an ordinary `openai_compat` / `anthropic`
+  entry: CodeRouter reads the OAuth token out of the JSON file the
+  vendor's CLI maintains and makes the HTTP call itself. Until now the
+  only answer to those was `kind: agent_cli`, which spawns the CLI once
+  per request and therefore has no streaming, no tool-call repair, no
+  context-budget guard, and does not sit in a fallback chain — the
+  subscription ended up an island. It is now a chain link:
+  `providers: [kimi-sub, free-cloud, local-llama]` just works.
+  Refresh delegates to the vendor's own CLI (`refresh.command`, an argv
+  list run with `shell=False`) rather than reimplementing OAuth, because
+  endpoints, client ids and rotation policies all change and a bespoke
+  implementation rots. Refresh is single-flighted in-process and
+  serialised across processes with an advisory `flock`. `credential` and
+  `api_key_env` are mutually exclusive at load time, `credential.path`
+  must live under `$HOME`, and a missing or malformed session file
+  resolves to `None` (unauthenticated request → upstream 401 → the chain
+  moves on) instead of raising. See `examples/providers.cli-session.yaml`.
+- **`coderouter rollback`** — restores `providers.yaml`,
+  `~/.coderouter/model-capabilities.yaml` and (with `--workspace`)
+  `.vscode/settings.json` / `.envrc` from their `.bak` siblings.
+  `doctor --apply` and `vscode-init` have always written a backup and
+  never offered a way back. Restore is a **swap**: the current contents
+  become the new `.bak`, so a second run returns you to where you
+  started. Exit 0 restored / 2 nothing to restore / 1 a restore failed.
+- **`coderouter doctor --check-secrets`** — proves the log-redaction
+  filter scrubs by pushing a canary through it, reports which declared
+  `api_key_env` vars are actually set, flags credentials pasted into a
+  `base_url`, and scans the already-written `requests.jsonl` /
+  `audit.jsonl` (plus rotated `.1`) for live key values. Same 0/2/1 exit
+  contract as `--check-env`. The log scan is the part that produces
+  evidence rather than reassurance.
+- **`CODEROUTER_METRICS_TOKEN`** — opt-in token auth for `/dashboard`,
+  `/metrics.json` and `/metrics`, mirroring `CODEROUTER_LAUNCHER_TOKEN`.
+
+### Changed (BREAKING)
+
+- **`vscode-init --with-envrc --force` no longer replaces `.envrc`.** The
+  block CodeRouter owns is now fenced between
+  `# BEGIN coderouter-managed` / `# END coderouter-managed`, and only
+  that block is rewritten. Consequences:
+  - A re-run against a fenced file needs **no `--force`** — rewriting our
+    own fence is not destructive, so a port change is an ordinary update
+    instead of a conflict to override.
+  - `--force` now means "adopt a file I did not write": the block is
+    appended and every existing line survives. Previously it deleted
+    them, which is how the H-11 `.envrc` incident happened — including
+    the `source_env_if_exists .envrc.local` line the docs tell users to
+    add.
+  - A managed variable exported *outside* the fence is refused, because
+    direnv applies exports in order and a silent duplicate leaves nobody
+    able to say which value is live. Commented-out lines are not
+    conflicts.
+  - A file byte-identical to a pre-v2.14.0 generation is adopted into the
+    fence silently, so upgrading does not demand `--force` for our own
+    previous output.
+  `settings.json` handling is unchanged (it already refused to overwrite
+  a user-owned value without `--force`).
+- **A failed `doctor --apply` is now a no-op instead of a partial one.**
+  The write loop had no error handling: an apply spanning `providers.yaml`
+  and `model-capabilities.yaml` left the first file rewritten when the
+  second failed. It now restores what it already wrote (and deletes what
+  it created) before raising.
+
+### Fixed (security)
+
+- **Credentials are scrubbed from every log sink.** CodeRouter had no
+  notion of "this string is a secret": keys were read by
+  `resolve_api_key`, dropped into `x-api-key` / `Authorization`, and
+  nothing masked them because nothing knew which strings needed masking.
+  No call site logged a header dict, so this was not a live leak — the
+  problem was that the safety of every future log line depended on
+  whoever wrote it remembering what was in their hand. There is now a
+  process-global registry keyed on the exact credential value, armed by
+  `resolve_api_key` (the choke point every key passes through, plugins
+  included) and pre-armed by `load_config`, plus a
+  `SecretRedactingFilter` on the stderr handler, `RequestLogHandler` and
+  `AuditLogHandler`. It scrubs the message, printf args, `exc_text` and
+  every `extra={...}` field, recursing into nested dicts and lists.
+  Exact-match registry first (zero false positives); a small set of
+  anchored backstop patterns (`sk-*`, `gh*_`, `AIza*`, `Bearer`,
+  `?api_key=`, URL userinfo) covers credentials that never passed through
+  the resolver. Values under 8 characters are refused — redacting those
+  would corrupt ordinary log text.
+- **`/dashboard`, `/metrics.json` and `/metrics` were unauthenticated
+  with no way to close them.** They change nothing, so they were never
+  part of the H-8 work, but `/metrics.json` returns every provider's
+  name, kind, paid flag and `base_url` plus the profile graph — the full
+  topology of which models an operator runs and which vendors they pay.
+  With `CODEROUTER_METRICS_TOKEN` unset they stay open exactly as before
+  (no running scrape breaks on upgrade) and log a one-time
+  `metrics-auth-disabled` warning. The check runs **before** the payload
+  is assembled, so a 401 leaks nothing, and the page receives only a
+  boolean — never the token. `base_url` now also goes through the
+  scrubber on its way into the JSON, since it is the one config field an
+  operator can paste a credential into and this endpoint hands it to a
+  browser.
+
+### Tests
+
+- 2572 passed / 1 skipped (was 2464 on `main`), ruff clean, and 51 mypy
+  errors against 53 on `main` (net −2; strict mypy is not CI-enforced).
+- New: `tests/test_secret_redaction.py` (36),
+  `tests/test_credentials.py` (25), `tests/test_rollback.py` (17),
+  `tests/test_ui_auth.py` (17), plus 9 in `tests/test_vscode_init.py` and
+  1 in `tests/test_doctor_apply.py`.
+- `test_existing_envrc_force_overwrites` asserted the old destructive
+  `--force` contract and is rewritten as
+  `test_existing_envrc_force_adopts_without_destroying`, pinning the
+  opposite.
+
+---
+
 ## [v2.13.0] — 2026-08-07 (remaining-high security hardening)
 
 ### Changed (BREAKING)

{coderouter_cli-2.13.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.13.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.13.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,
+    log_stream_truncation_detected,
 )
-from coderouter.config.loader import resolve_api_key
-from coderouter.logging import get_logger, log_output_filter_applied
 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``.
 
@@ -134,7 +207,9 @@ class AnthropicAdapter(BaseAdapter):
                 self.config.extra_body.get("anthropic_version", _DEFAULT_ANTHROPIC_VERSION)
             ),
         }
-        api_key = resolve_api_key(self.config.api_key_env)
+        # v2.14.0: see openai_compat._headers — same resolver, so an
+        # Anthropic-protocol provider can also ride a CLI session token.
+        api_key = resolve_provider_credential(self.config)
         if api_key:
             headers["x-api-key"] = api_key
         # v0.4-D: forward the client's anthropic-beta header verbatim.
@@ -473,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
@@ -512,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,
@@ -540,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.13.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.13.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.config.loader import resolve_api_key
+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
 
@@ -105,7 +107,10 @@ class OpenAICompatAdapter(BaseAdapter):
             "Content-Type": "application/json",
             "User-Agent": "CodeRouter/0.1",
         }
-        api_key = resolve_api_key(self.config.api_key_env)
+        # v2.14.0: resolve_provider_credential covers api_key_env (the
+        # historical path, unchanged) and credential.source=cli_session,
+        # which borrows the token a vendor CLI already wrote to disk.
+        api_key = resolve_provider_credential(self.config)
         if api_key:
             headers["Authorization"] = f"Bearer {api_key}"
         return headers
@@ -344,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(...)``
@@ -373,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
@@ -443,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