REVIVAL-10: OpenAICompatible named provider + true SSE streaming (OpenRouter/Groq/DeepSeek first-class)

[Chris0Jeky]

Wave: REVIVAL Phase 2 (v0.2) — docs/REVIVAL_PLAN.md §4. Review tier: FULL (provider + settings regex). Independent of REVIVAL-08 (can land first).

Context (verified 2026-07-10)

Two adversarially confirmed facts: (1) the OpenAI provider's BaseUrl already accepts any public HTTPS OpenAI-compatible endpoint (OpenRouter/Groq/DeepSeek/Anthropic-compat) with config only — but it's an undocumented hack, and the named-provider list is a hardcoded regex Mock|OpenAi|Gemini|Ollama (LlmProviderSettings.cs:11) plus a DI switch (LlmProviderRegistration.cs:156-163); (2) all four providers fake streaming — StreamAsync buffers the full completion then replays word-split tokens, and OpenAI/Ollama even send "stream": false (OpenAiLlmProvider.cs:395-409,262,509; equivalents in Gemini/Ollama/Mock). The SSE chat endpoint's first token arrives only after full completion.

Acceptance criteria

1. New first-class provider name OpenAICompatible (settings: BaseUrl required, ApiKey, Model, optional extra headers) — same SSRF/HTTPS validation as today; registered through the existing 4-file pattern (settings regex, selection policy, DI switch, provider class — follow the Ollama precedent). The OpenAI provider itself stays unchanged for api.openai.com defaults.
2. True SSE streaming for the OpenAI-compatible wire format (stream: true + delta parsing) in this one provider — it covers every cheap-model vendor at once. Honest fallback: if the endpoint rejects streaming, degrade to complete-then-emit and mark the result metadata accordingly (no silent fakery).
3. The chat SSE endpoint (ChatController.cs:155-181) streams real deltas end-to-end for this provider; existing pseudo-streaming providers keep working unchanged (de-faking them is out of scope; Ollama marking is ARCHIVE-08: Dead-surface removal - ink-bleed decision, orphaned Paper code, cohorts stub, voice capture, Ollama marking #1276's decision).
4. response_format/json_object handling: degrade gracefully when a compat endpoint rejects it (verified edge: instruction extraction sends it) — fall back to prompt-enforced JSON + robust parsing.
5. Config documented in docs/platform/LLM_PROVIDER_SETUP_GUIDE.md + CONFIGURATION_REFERENCE with copy-paste examples for OpenRouter, Groq, DeepSeek.
6. Tests: provider unit tests (streaming parse, malformed SSE, mid-stream error, cancellation), selection-policy tests, one resilience test in the existing pattern (LlmProviderResilienceTests).

Traps

• Circuit breaker/quota/kill-switch/egress wiring must apply to the new provider (registration extension methods — don't bypass LlmProviderRegistration plumbing).
• SSRF ConnectCallback applies at DNS level; don't weaken it for streaming connections.
• Tool-calling: implement CompleteWithToolsAsync for the compat provider if cheap (OpenAI wire format), else inherit the NotSupported default — the orchestrator degrades gracefully (verified).

Verification

Unit + resilience tests; live smoke against one real compat endpoint (maintainer key) recorded in PR; chat streaming visibly incremental in dev-up.

[Chris0Jeky]

PR #1505 parked-review acceptance remainder — exact head 6ee17a4849427d679722a9d1e034d4622536f4fe

The final bounded review round leaves 3 HIGH, 10 MEDIUM, and 2 LOW valid findings. PR #1505 is parked; this comment makes the remaining #1306 scope cold-readable without starting a third fix/review cascade.

HIGH

1. Quota settlement lacks upstream-dispatch provenance. Post-dispatch error-only SSE, stream cancellation before the first delta, and buffered CompleteAsync cancellation can release rather than commit the estimate (thread, security review, correctness review).
2. Abandoned/cancelled half-open probes can immediately repeat. The current release sets the open deadline to now instead of honoring the configured break (security review).

MEDIUM

3. A stale pre-open success can erase a newer companion circuit open (security review).
4. Companion success can publish Closed while Polly remains open, making health snapshots false (thread).
5. The mirror race lets a stale pre-open failure re-poison state after a successful half-open probe (correctness review).
6. SSE limits count decoded/re-encoded text rather than raw received bytes, undercounting UTF-16/32 and overcounting non-BMP UTF-8 (raw-byte thread, scalar thread).
7. Non-empty output with authoritative total_tokens: 0 releases quota instead of treating usage as unknown (thread).
8. Broad provider catches swallow typed EgressViolationException, losing the security-boundary signal (thread).
9. Buffered content: null refusal/filter completions fail parsing before finish_reason is handled (thread).
10. HTTP 501 fallback can be rejected because Polly opens before the fallback request when threshold is one (thread).
11. A zero-content terminal Error is shown live but not persisted, so reload loses the outcome (correctness review).
12. Setup docs advertise generic loopback HTTP / 127.0.0.1, while validation permits only literal localhost (thread).

LOW

13. The testing-guide total-heading rename leaves stale canonical references in STATUS and LIVING_DOCUMENTS_GUIDE (thread).
14. STATUS advertises OpenAICompatible while retaining an older OpenAI/Gemini-only inventory (thread).

Separately tracked security successor

15. HIGH — ambient/system proxies can move SSRF validation from the configured origin to the proxy for OpenAI, Gemini, Ollama, and outbound webhooks. This shared cross-provider seam is now tracked with concrete acceptance criteria in [Security] Make SSRF origin enforcement proxy-safe across OpenAI, Gemini, Ollama, and webhooks #1513 (Next / Priority I).

The initial Windows API failure and identical-head green rerun remain tracked in #1512; the green rerun is evidence of nondeterminism, not closure. Maintainer-key provider canaries, visibly incremental real UI streaming, and deployment remain unverified.