docs(open-sse): in-stream error handling recipe + CHANGELOG

CHANGELOG.md

@@ -1,6 +1,17 @@
+# Unreleased
+
+## Features
+
+- **Stream error patterns**: per-provider `streamErrorPatterns` setting (UI: provider page → Stream Error Patterns) — HTTP-200 streams whose first bytes match configured patterns (plain text or `/regex/`) are treated as failed requests: fallback works for non-streaming and early stream errors, and late streaming errors are logged as FAILED. Zero overhead when unconfigured.
+
+## Fixes
+
+- **CommandCode**: in-stream `{"type":"error"}` events now emit OpenAI error chunks + an executor early-peek → 502 fallback instead of fake success content (`[CommandCode error: ...]`).
+
 # v0.5.45 (2026-07-30)
 
 ## Features
+
 - **Providers**: add Poolside (OpenAI-compatible)
 - **Providers**: add api-airforce, baidu, bazaarlink, bluesminds, kilo-gateway, llm7, morph, sambanova, tencent
 - **OAuth**: zed / trae / windsurf providers + harden callback proxies
@@ -13,6 +24,7 @@
 - **Usage**: SuperGrok weekly pool via gRPC-web
 
 ## Fixes
+
 - **Refresh**: rotate `refresh_token` between retry attempts
 - **Kiro**: canonicalize tool history and route API keys correctly
 - **Kiro**: normalize dashboard thinking intensity models
@@ -27,18 +39,21 @@
 - **Dashboard**: flex quota rows, thin global scrollbars, no hidden-row overflow
 
 ## Docs
+
 - **i18n**: expand pt-BR translation to 986 terms
 - README: Indonesian translation
 
 # v0.5.40 (2026-07-20)
 
 ## Features
+
 - **i18n**: add Khmer (km) translations
 - **CLI tools**: configure Grok Build subagent models
 - **Kimi**: merge OAuth into dual-auth provider, add K3 / K2.7 models
 - **Dashboard**: ProviderTopology flow animation
 
 ## Fixes
+
 - **DB**: resolve better-sqlite3 parameter binding crash
 - **Translator**: pass `service_tier` through OpenAI → Responses conversion
 - **Kiro**: map GPT-5.6 reasoning effort fields
@@ -49,10 +64,10 @@
 - **Cursor**: HTTP/2 AgentService support + version bump 3.12.17
 - **Dashboard**: cut duplicate API/icon spam, lazy-load provider assets
 
-
 # v0.5.35 (2026-07-16)
 
 ## Features
+
 - **xAI**: Grok Imagine video generation (`/v1/videos`) + CLI
 - **CLI tools**: Grok Build setup — choose separate main/general-purpose/explore/plan models and preserve each model's context window
 - **GitHub Copilot**: route Claude models through Copilot's native `/v1/messages`
@@ -63,6 +78,7 @@
 - **i18n**: Thai (th) + Persian (fa) translations / README
 
 ## Fixes
+
 - **Providers**: bulk-add API keys no longer overwrite existing keys (gap-fill `Key N`)
 - **Anthropic**: lowercase `anthropic-version` header to prevent duplication on `/v1/messages`
 - **Alicode-intl**: use DashScope compatible-mode endpoint so standard keys work
@@ -75,14 +91,17 @@
 - **Translator**: strip `client_metadata` when converting openai-responses → openai
 
 ## Improvements
+
 - **Perf**: skip inactive background services on startup
 
 ## Docs
+
 - README: Persian YouTube tutorial
 
 # v0.5.30 (2026-07-10)
 
 ## Features
+
 - **Perplexity**: add Agent API provider (#2492)
 - **Grok CLI**: add Grok CLI / Grok Build provider with OAuth device-code flow (#2502)
 - **Featherless**: add OpenAI-compatible provider presets
@@ -94,6 +113,7 @@
 - **Proxy-Pools**: auto-rotate strategy for no-auth providers (#2409)
 
 ## Fixes
+
 - **Cloudflare-AI**: support accountId in bulk key import (#2449)
 - **DB**: backup on schema change, MCP child cleanup, codex models, usage providers OOM
 - **Codex**: avoid bare-email OAuth dedup (#2477)
@@ -110,6 +130,7 @@
 - **Pricing**: update Claude/Codex model rates and add new models
 
 ## Improvements
+
 - **i18n(zh-CN)**: complete Chinese translations for all UI strings (#2436)
 - **API**: caching for tunnel and version status endpoints
 - **Perf**: faster dev startup and lighter bundle
@@ -117,12 +138,14 @@
 # v0.5.20 (2026-07-07)
 
 ## Features
+
 - **Thinking**: per-model thinking level picker on provider page — appends `(level)` suffix to copied model names for forced reasoning effort across all formats (openai, claude, gemini, deepseek, kimi, qwen, zai, minimax, hunyuan, step)
 - **RTK**: add JS-native git-log filter (#2423)
 - **Caveman**: add targeted upstream-aligned style rules (#2424)
 - **i18n**: add Farsi (fa) language support (#2385)
 
 ## Fixes
+
 - **Thinking**: strip `(level)` suffix from upstream `body.model` so providers no longer reject requests
 - **Translator**: preserve developer instructions in openai-responses conversion (#2434)
 - **count_tokens**: count structured Anthropic blocks (#2419)
@@ -136,12 +159,14 @@
 # v0.5.18 (2026-07-03)
 
 ## Features
+
 - **Usage**: track cached tokens + correct input/output/cache cost (#2209) — hodtien
 - **Codex**: show reset credit expiry details (#2290) — Rafli Ahmad Zulfikar
 - **NVIDIA**: add new models and capabilities — decolua
 - **ClinePass**: add provider support — sternelee
 
 ## Fixes
+
 - **Usage**: dedupe streaming request-details log entries — Qin Li
 - **Claude**: drop foreign thinking signatures in passthrough — decolua
 - Prevent non-SSE stream pipe crash and cross-IdP account overwrites (#2244) — KunN-21
@@ -158,11 +183,13 @@
 # v0.5.15 (2026-06-29)
 
 ## Features
+
 - Add Kimchi OAuth provider — Nant361
 - Refine Qwen vision/video + thinking model patterns — decolua
 - Opt-in Codex auto-ping quota keep-alive — Emirhan
 
 ## Fixes
+
 - **Responses**: handle response.done terminal events (#2142) — rifuki
 - **Headroom**: skip unsafe responses tool history (#2132) — Sutarto Jordan Chrisfivo
 - **Translator**: map mid-conversation system message to user (claude→openai) — decolua
@@ -179,6 +206,7 @@
 # v0.5.12 (2026-06-26)
 
 ## Features
+
 - Add token-saver dashboard page — decolua
 - Add bulk delete for provider connections — teddytkz
 - Resolve GitHub Copilot model catalog from upstream — caiqinzhou
@@ -187,6 +215,7 @@
 - Overhaul Blackbox provider catalog + WebUI test support — suryacagur
 
 ## Fixes
+
 - Provider thinking compatibility (DeepSeek/Gemini) — Mink Nguyen
 - Stop double-counting streaming usage at source — decolua
 - Usage logging dedupe to reduce stats churn — Mink Nguyen
@@ -215,11 +244,13 @@
 # v0.5.8 (2026-06-21)
 
 ## Features
+
 - **Antigravity**: native image generation support (image models tagged kind:image, hiển thị trong media-providers UI)
 - **CodeBuddy CN**: API key auth + credit quota tracker
 - **CodeBuddy CN**: short model prefix alias "cbcn"
 
 ## Fixes
+
 - **MiniMax-M3**: enable vision capability
 - **Headroom**: support Docker sidecar proxy
 - **Antigravity**: image executor fixes
@@ -233,12 +264,14 @@
 # v0.5.6 (2026-06-20)
 
 ## Features
+
 - **Ponytail**: minimalist code generation feature
 - **Headroom**: proxy lifecycle management + dashboard UI (one-click start/stop, install detection, status probing, token saver, claude↔openai shape conversion)
 - **CodeBuddy CN**: new OAuth provider (copilot.tencent.com) — 15-model catalog, /v2 inference, forced streaming, OpenAI-style reasoning
 - **OpenCode-Go**: align models with official endpoints; route Qwen 3.7 MiniMax via /v1/messages, GLM/Kimi/DeepSeek/MiMo via /chat/completions
 
 ## Fixes
+
 - **Anthropic-compatible validation**: use POST /v1/messages (GET /models not spec, false "invalid" for valid keys)
 - **CLI tools**: tolerate JSONC configs in all 8 settings routes (opencode, openclaw, kilo, droid, cowork, copilot, claude, cline)
 - **Gemini/Antigravity**: preserve 'pattern' in tool schema translation (glob/grep)
@@ -249,6 +282,7 @@
 # v0.5.4 (2026-06-18)
 
 ## Fixes
+
 - **Kiro**: honor thinking effort budgets
 - **AG/Kiro/Xiaomi**: provider fixes
 - **Combo/Fusion**: flatten tool history in panel calls to prevent 503
@@ -258,6 +292,7 @@
 # v0.5.2 (2026-06-17)
 
 ## Features
+
 - **Combo Fusion strategy** — fans the prompt out to all member models in parallel, then a configurable judge model synthesizes one final answer (quorum-grace, anonymized sources, graceful degradation)
 - **Per-combo strategy selector** — pick `fallback` / `round-robin` / `fusion` / `capacity` per combo (replaces the old round-robin toggle), with a judge picker for fusion
 - **Capacity auto-switch** — reorders models per request so images/PDFs route to capable models first
@@ -265,6 +300,7 @@
 - **Claude auto-ping** — warms the 5h quota window right after reset so a fresh window starts immediately (per-connection toggle)
 
 ## Fixes
+
 - **Claude 429**: stop hammering the OAuth usage endpoint — cache resetAt, throttle quota refresh to 3 min, cool down after a 429 (chat unaffected)
 - **Usage logs always empty**: missing `await` on `getAdapter()` in `getRecentLogs` made `/api/usage/logs` & `/api/usage/request-logs` return nothing
 - **Executors**: strip params unsupported by the provider/model (drops deprecated `temperature` for claude-opus-4 → Anthropic 400)
@@ -276,11 +312,13 @@
 - **Security**: SSRF hardening on web fetch
 
 ## Internal
+
 - Large **open-sse / translator refactor** (~40 commits): unified provider/model registry (LiteLLM-style `models[]` + `kind` field, 100 co-located registry files), single-sourced media/OAuth/refresh/token URLs, registry-based dispatch for usage & token-refresh, DRY translator concerns (buildUsage, encodeDataUri, finishReasonMap, chunkBuilder, reasoningDelta…), ESM-safe registry init, large-file splits, dead-code removal, and golden/no-regression test gates
 
 # v0.4.80 (2026-06-13)
 
 ## Features
+
 - Vercel AI Gateway: support embeddings, images and credit usage (#1183)
 - Add MiMo Free no-auth provider (#1789)
 - Vertex: support ADC `authorized_user` credential
@@ -289,6 +327,7 @@
 - Kiro: enable multi-endpoint failover for GenerateAssistantResponse (#1722)
 
 ## Fixes
+
 - Security: re-auth on DB export/import + SSRF guard on web fetch
 - Auth: real client IP rate-limiting + remote default-password guard
 - Cerebras/Mistral: strip unsupported `client_metadata` from downstream requests (#1742)
@@ -307,11 +346,13 @@
 - Dashboard: show provider node name instead of connection name in topology (#1770) + show explicit `kind="llm"` combos on combos page (#1684)
 
 ## Docs
+
 - README: add Indonesian 9Router tutorial video (#1709)
 
 # v0.4.71 (2026-06-06)
 
 ## Features
+
 - Caveman: add wenyan classical Chinese levels and sync upstream prompts; locale-based visibility on endpoint page
 - i18n: endpoint exposure notice across multiple languages + Russian README
 - Antigravity: add gemini-3.5-flash-extra-low (Low) model
@@ -320,6 +361,7 @@
 - MiniMax: add MiniMax-M3 + update Quota Tracker coding/CN (#1631)
 
 ## Fixes
+
 - Codex: harden streaming timeouts (stall/connect raised to 60s, configurable per-provider), accept `response.done` event, and always emit a terminal `response.failed` + `[DONE]` for Responses passthrough when a stream closes, stalls, or aborts before a terminal event — prevents codex clients from hanging (#1648, #1680, #1688, #1618)
 - Codex: durable OAuth refresh lifecycle (#1664)
 - Tunnel: skip virtual interfaces to prevent false netchange watchdog
@@ -333,21 +375,25 @@
 - Model-test: route image/STT probes to their real endpoints, harden STT ping; add opencode-go + xiaomi-tokenplan to connection test (#1576, #1628)
 
 ## Improvements
+
 - Dashboard: reorganize menu actions across sidebar/header/profile
 - Translator: add data-driven coverage, bug-exposing cases, and real provider smoke tests
 
 # v0.4.66 (2026-05-29)
 
 ## Features
+
 - Add Qoder provider: device-flow OAuth, COSY signing, WAF-bypass body encoding, live model catalog, dashboard quota tracker, 11 models (#1372)
 - Add new models: Claude Opus 4.8 (Claude Code), GPT 5.4 Mini (Codex)
 
 ## Fixes
+
 - DeepSeek thinking mode: echo `reasoning_content` back on follow-up/tool-call turns so OpenCode-free and custom providers no longer 400 with "reasoning_content must be passed back" (#1543)
 - Reasoning injector: match deepseek/kimi model ids case-insensitively (covers custom providers using capitalized model names)
 - OpenCode suggested-models: include free models without the `-free` suffix, e.g. `big-pickle` (#1535)
 
 ## Improvements
+
 - Codex: trim sunset models, keep gpt-5.5 / gpt-5.4 / gpt-5.3-codex family, add gpt-5.4-mini
 - volcengine-ark: refresh model list (add DeepSeek-V4-Flash/Pro, drop EOL entries)
 - Lower stream stall timeout 35s → 30s for faster hang detection
@@ -355,15 +401,18 @@
 # v0.4.63 (2026-05-26)
 
 ## Fixes
+
 - GitHub Copilot: never route Gemini/Claude models to the `/responses` endpoint; prevents misleading "does not support Responses API" 400s (#1062)
 - proxyFetch: restore missing `Readable` import causing runtime `ReferenceError` in DNS-bypass fetch path
 
 ## Improvements
+
 - Lower stream stall timeout from 60s → 35s for faster hang detection
 
 # v0.4.62 (2026-05-26)
 
 ## Fixes
+
 - Codex: auto-retry when upstream drops mid-stream (no more hangs)
 - Codex: fix random 400/404 errors, tool-calling failures, and unstable prompt cache
 - MITM: support Antigravity 2.x
@@ -375,25 +424,30 @@
 - Gemini CLI: reuse stored OAuth project IDs for quota checks and show clearer setup guidance when the project is missing (#1271, #1428)
 
 ## Features
+
 - Add Cloudflare Workers proxy deployer and pool integration (#1360)
 - Add Deno Deploy relays support and improved proxy pools dashboard layout (#1437)
 
 ## Improvements
+
 - Refactor Tunnel into dedicated Cloudflare and Tailscale manager modules
 - Refactor tokenRefresh service with in-flight dedup to prevent refresh_token_reused errors
 
 # v0.4.59 (2026-05-21)
 
 ## Fixes
+
 - OAuth: fix login flow on Windows
 
 # v0.4.58 (2026-05-21)
 
 ## Features
+
 - xAI Grok provider (OAuth, API key, image)
 - Provider limits: paginated accounts with page size controls
 
 ## Fixes
+
 - Tailscale: fix connection status on Windows (#1300)
 - Tunnel: fix false "checking" when tunnel URL is reachable
 - Stream: fix pipe errors on client disconnect/abort
@@ -401,11 +455,13 @@
 # v0.4.55 (2026-05-18)
 
 ## Features
+
 - Xiaomi MiMo Token Plan: region selector (Singapore / China / Europe) — keys are cluster-specific
 - Antigravity: risk confirmation dialog before first connection
 - Gemini CLI: surface upstream retry delay on 429 errors
 
 ## Fixes
+
 - MITM: cannot kill process on macOS under sudo (lsof not found in PATH)
 - Stream: false-positive stall timeout on Claude reasoning / Kiro responses
 - Tunnel: cannot re-enable after disable (stuck state)
@@ -414,16 +470,19 @@
 - Antigravity OAuth: metadata now matches the official client
 
 ## Improvements
+
 - Gemini CLI: bump engine to 0.34.0
 - Re-hide `qwen` (OAuth EOL) and `iflow` (not ready) providers
 
 # v0.4.52 (2026-05-17)
 
 ## Features
+
 - Add Vercel AI Gateway provider support (#1183)
 - rtk: Kiro format tool result compression — handle conversationState.history & currentMessage, preserve error results, ~13.6% savings (#1194)
 
 ## Fixes
+
 - openclaw: normalize agent.model object form `{primary, fallbacks}` before .startsWith → fix TypeError & 'not configured' status (#1216)
 - Usage Details pagination: stay inside mobile viewport <640px (#1218)
 - Fix test model error
@@ -433,6 +492,7 @@
 # v0.4.50 (2026-05-16)
 
 ## Fixes
+
 - Fix duplicate tray icon on macOS when hiding to tray
 - Fix tray not showing in background mode on macOS
 - Fix hide to tray broken on Windows/Linux
@@ -441,11 +501,13 @@
 # v0.4.49 (2026-05-16)
 
 ## Features
+
 - Add Kiro provider support: full request/response translation, live model listing, reasoning content support
 - Add `buildOutput` RTK filter with autodetect for npm/yarn/cargo build logs
 - Add MITM warning notification in tray and dashboard
 
 ## Improvements
+
 - Add modalities (input/output) to model configuration for OpenCode
 - Fix tray hide-to-tray: keep current process alive instead of spawning detached child (fixes macOS NSStatusItem ghost icon)
 - Fix tray kill: graceful shutdown with SIGTERM/SIGKILL escalation
@@ -454,9 +516,11 @@
 - Update i18n across 32 languages
 
 ## Fixes
+
 - Fix model check (test-models) blocked by dashboardGuard: pass machineId-based CLI token in internal self-calls
 
 # v0.4.46 (2026-05-15)
 
 ## Breaking Changes
+
 - Tunnel public URL changed — old tunnel links no longer work, please reconnect to get the new URL

open-sse/AGENTS.md

@@ -37,3 +37,7 @@ Provider-agnostic SSE engine: one OpenAI-style request → any provider (LLM cha
 - `registry/index.js` is an auto-generated static import list; regenerate it (don't hand-edit) after adding a `registry/{id}.js`. REGISTRY_TEMPLATE is excluded by design.
 - Special binary/protobuf formats (kiro EventStream, cursor protobuf, commandcode NDJSON) don't round-trip through OpenAI — handle in their executor.
 - `rtk/` + `headroom.js` mutate the request body in-place and are **fail-open**: any error returns null and leaves the body untouched — never throw out of them. RTK skips `is_error`/`status:"error"` tool results to preserve traces.
+- **HTTP 200 in-stream errors**: some upstreams signal failure INSIDE a 200 stream (AI SDK v5 `{"type":"error"}` events, error text in content). HTTP-level success checks miss these → no fallback, `Status: success` in logs. Three hook points + one config escape hatch:
+  1. **Translator** — never map an error event to content. Emit an OpenAI-shaped `chunk.error = { message, type }` + terminal chunk (`translator/response/commandcode-to-openai.js` is the worked example). Downstream `parseSSEToOpenAIResponse` already detects `chunk?.error`.
+  2. **Executor early-peek** — for streaming fallback, read the first events BEFORE returning the response; an error → non-ok Response (`executors/commandcode.js` `peekForUpstreamError`).
+  3. **Config escape hatch (no code)** — per-provider `streamErrorPatterns` setting (UI: provider page → Stream Error Patterns). Patterns matched against the first ~8KB of the stream and the assembled non-streaming content; see `utils/streamErrorPeek.js` + `utils/streamErrorPatterns.js`.