opencode-thinking-fix 3.2.0 → 3.3.1

package/README.md

@@ -10,23 +10,65 @@
 npm install opencode-thinking-fix
 ```
 
-> Restores reasoning content that clients and SDKs drop from multi-turn conversations — DeepSeek, Kimi, GLM, MiMo, MiniMax, and OpenCode Go.
+> Restores reasoning content that clients and SDKs drop from multi-turn conversations — DeepSeek, Kimi, GLM, MiMo, MiniMax, OpenCode Go, and OpenRouter.
 >
-> **Zero config.** Install via `Ctrl+P`, restart OpenCode, done. The plugin auto-detects reasoning models and only patches when needed.
+> **Zero config.** Install via `Ctrl+P`, restart OpenCode, done. The plugin detects reasoning models and only patches when needed.
 >
 > Docs: [OpenCode Plugins](https://opencode.ai/docs/plugins)
 
-Your AI has a secret notebook.
+## The problem
 
-When DeepSeek or Kimi answers you, it scribbles notes first. "Let me think... the user wants a login page... I should use React Hook Form... check the API docs..." These notes are `reasoning_content`. You never see them. But the AI needs them.
+When DeepSeek or Kimi answers you, it scribbles notes first. "Let me think... the user wants a login page... I should use React Hook Form... check the API docs..." These notes are `reasoning_content`. You never see them. But the AI needs them — the provider docs require the notes to be sent back on every later turn.
 
-The client and its SDK throw the notebook away. Next turn, the AI reaches for it — but the request already went to the API without it. The request carries no notes, or a blank notebook. The AI doesn't crash, but it forgot everything it was thinking. That is why your AI seems dumber on turn 2. It's not dumber. It just lost its notes.
+The client and its SDK throw the notebook away. Next turn, the AI reaches for it, but the request already went out without it. The AI doesn't crash. It just forgot everything it was thinking. That is why your AI seems dumber on turn 2. It's not dumber. It lost its notes.
 
-The drop happens in SDK serializers and client transforms (truthy checks, missing type members, stripped signatures), not in the providers — the providers are doing exactly what their docs say.
+The drop happens in SDK serializers and client transforms (truthy checks, missing type members, stripped signatures), not in the providers. The providers do exactly what their docs say.
 
-**Without the plugin:** "Build me a login page." → AI builds it. "Now add password reset." → AI lost its notes, conversation degrades.
+**Without the fix:** "Build me a login page." → AI builds it. "Now add password reset." → notes gone, the answer comes back generic.
 
-**With the plugin:** "Build me a login page." → AI builds it, notes saved. "Now add password reset." → AI reads its notes: "I used React Hook Form for login, I'll extend that for password reset." → Works.
+**With the fix:** "Now add password reset." → AI reads its notes: "I used React Hook Form for login, I'll extend that." → works.
+
+## See it happen in 5 minutes
+
+You need OpenCode and any reasoning model. No proxy, no plugin — this reproduces the drop on a stock install.
+
+1. Start a session with a reasoning model (free tier works, e.g. `opencode/hy3-free`) and give it a real task. It thinks, answers, and emits `reasoning_content`.
+2. Ask a follow-up that depends on the first answer, then capture the outgoing request. Every `reasoning_content` field from turn 1 arrives empty or missing.
+3. The same request through the SDK alone keeps the field. The client is the difference.
+
+Captured evidence for exactly this sequence: [`proof/free-models/`](proof/free-models/). The A/B controls that isolate the field as the only variable: [`proof/curl-control-results.txt`](proof/curl-control-results.txt).
+
+## Why you've probably never seen it
+
+This bug is conditional, and the conditions are "you work the tool hard":
+
+- **Short sessions never hit it.** The drop happens on turn 2+, worst after tool calls. A two-message chat looks fine.
+- **Most gateways don't enforce the contract.** On the free `opencode/zen` tier and OpenRouter, a missing field is accepted, so nothing errors. The model just quietly loses context. No 400, no warning, only worse answers.
+- **Non-reasoning models are unaffected.** GPT, Claude, Qwen, Gemini never emit the field.
+
+If you run long sessions, heavy tool calls, model switching, or subagents, you have probably been hit and blamed the model. That is who this fix is for. If you send three messages a day, you may genuinely never notice — and the plugin detects that and does nothing.
+
+## The evidence
+
+We ran four passive taps (DeepSeek, OpenCode Go, OpenCode Zen, OpenRouter) that forwarded traffic byte-for-byte untouched and logged only metadata. They ran for a week of real work, then were retired. Methodology and raw data: [`proof/` directory](proof/).
+
+- **1,968 drops captured** — a turn that carried reasoning earlier in the same session arrives at the API without it.
+- **2.29 million characters** of reasoning erased over a week of real traffic.
+- **68% of drops happened with zero model change** — same model, same session. Not a model-switch artifact.
+- **OpenRouter drops it too** — 22 drops with confirmed session identity on models served through openrouter.ai, plus the same pattern on DeepSeek and OpenCode Go lanes.
+- **The SDK is innocent.** `@ai-sdk/openai-compatible` round-trips the field correctly; the drop happens in the client's own transform. Captured side by side in [`proof/free-models/`](proof/free-models/).
+
+Every number is recomputable from [`proof/reasoning-drop/drops.csv`](proof/reasoning-drop/drops.csv) and [`proof/reasoning-drop/switches.csv`](proof/reasoning-drop/switches.csv).
+
+## For the skeptics
+
+Three objections come up every time this is posted. Fair questions, with the evidence:
+
+**"Works on my side."** Probably true. The drop is silent on most gateways — no 400, just worse answers, so nothing looks broken unless you compare turn-3 quality with and without. The A/B controls hold everything constant except the field. And the 68% stat rules out model switching as the explanation.
+
+**"Your config is broken."** The configs this was captured on are published, redacted, in [`proof/` directory](proof/). The root cause is in the client's message transform, not config — the SDK control shows the field surviving when only the client is removed from the path.
+
+**"The model cards already say to pass reasoning back."** They do. That is the point. The provider requires the field; the client drops it. The model card is the spec this repo implements.
 
 ---
 
@@ -71,9 +113,7 @@ causing cross-provider poisoning. v3.1 fixes that:
   (MiniMax split mode), `reasoning` (OpenCode Go / fixed-upstream). Previously the proxy
   filled all three fields, so a GLM turn stored under `reasoning` could poison a later
   DeepSeek replay that expects `reasoning_content`.
-- **R1 vs V4 split.** `deepseek-reasoner` (R1) must **not** receive reasoning echoed back
-  (400 if you do) while V4 must. R1 uses the v3.2 `reasoningKey: 'strip'` sentinel,
-  which actively removes reasoning fields before forwarding.
+- **Legacy DeepSeek aliases vs V4.** DeepSeek retired the `deepseek-chat` / `deepseek-reasoner` aliases on 2026-07-24; the current catalog is `deepseek-v4-flash`, `deepseek-v4-pro`, and the experimental `deepseek-v4-flash-vision-exp`. While the R1 alias was live it had the inverted contract (echoed reasoning → 400), which is why the proxy carries a `strip` route: it actively removes reasoning fields before forwarding, kept today only as a compatibility guard for clients that still send the old name. V4 thinking mode uses the normal passback contract instead.
 - **Never fabricate reasoning.** Unknown models and providers that reject echo
   (Qwen, GPT, Claude, Gemini, Llama, Mistral, Cerebras-hosted GLM) default to
   `reasoningKey: null` — the body is forwarded untouched.
@@ -125,7 +165,7 @@ opencode plugin opencode-thinking-fix
 For a specific version:
 
 ```bash
-opencode plugin opencode-thinking-fix@3.2.0
+opencode plugin opencode-thinking-fix@3.3.0
 ```
 
 Restart OpenCode after installing.
@@ -150,13 +190,17 @@ See also: [OpenCode plugin docs](https://opencode.ai/docs/plugins)
 
 ---
 
-- [What problem this fixes](#what-problem-this-fixes)
+- [The problem](#the-problem)
+- [See it happen in 5 minutes](#see-it-happen-in-5-minutes)
+- [Why you've probably never seen it](#why-youve-probably-never-seen-it)
+- [The evidence](#the-evidence)
+- [For the skeptics](#for-the-skeptics)
 - [Option 1: Plugin (safety net)](#option-1-plugin-safety-net)
 - [Option 2: Proxy (replays real reasoning)](#option-2-proxy-replays-real-reasoning)
 - [Option 3: Watchdog (auto-recovery)](#option-3-watchdog-auto-recovery)
 - [How they work together](#how-they-work-together)
 - [Affected models](#affected-models)
-- [Model routing](#model-routing)
+- [Model routing](#model-routing-proxy-port-3457)
 - [Is it working?](#is-it-working)
 - [This bug is everywhere](#this-bug-is-everywhere)
 - [Files in this repo](#files-in-this-repo)
@@ -171,7 +215,7 @@ The client/SDK dropped the field before it reached the API — the providers are
 
 > **Deprecated:** the historical symptom of this drop — `HTTP 400: The reasoning_content in the thinking mode must be passed back to the API` — is **resolved** by this fix. This repo is about the drop itself, not the error it used to cause.
 
-DeepSeek V4 (and Kimi K2.7, GLM 5.x, MiMo V2.5) require that `reasoning_content` from every prior assistant turn gets included in subsequent API requests. The [docs](https://api-docs.deepseek.com/guides/thinking_mode) say it clearly: if you do not pass back `reasoning_content` correctly, the API rejects the request. All five providers confirm this in their official documentation:
+DeepSeek V4 (and Kimi K2.7, GLM 5.x, MiMo V2.5) require that `reasoning_content` from every prior assistant turn gets included in subsequent API requests. The [docs](https://api-docs.deepseek.com/guides/thinking_mode) describe the contract, and the strictness varies by provider and endpoint: some reject the request, some ignore the field, and the conversation still loses its context either way. All five providers confirm the passback requirement in their official documentation:
 
 - **DeepSeek**: "[The reasoning_content will be ignored by the API](https://api-docs.deepseek.com/guides/thinking_mode)", but the conversation history must contain the field.
 - **Z.AI / GLM**: "[Key: return reasoning_content to keep the reasoning coherent](https://docs.z.ai/en/api/thinking)."
@@ -343,12 +387,14 @@ The plugin is the safety net. If the proxy goes down, the plugin still injects e
 | Model | Plugin helps | Proxy helps | What it needs |
 |---|---|---|---|
 | DeepSeek V4 Pro / Flash | Yes | Nice to have | Accepts `""` (tool-call turns need real text) |
+| DeepSeek V4 Flash Vision (exp) | Yes | Nice to have | Text + image input on a separate model id; same passback contract |
 | Kimi K2.5 / K2.6 | Yes | Nice to have | Accepts `""` |
 | **Kimi K2.7 Code** | **Not enough alone** | **Required** | Field must be *present*; real text keeps it coherent |
 | GLM-5.x / Zhipu | Yes | Nice to have | Accepts `""` |
 | MiMo V2.5 | Yes | Nice to have | `reasoning_content` on `api.xiaomimimo.com/v1` |
 | **MiniMax-M3** | Yes | **Recommended** | `reasoning_details[]` array; ~40% quality loss if stripped. Proxy injects `reasoning_split:true` to keep thinking separate from content. |
 | OpenCode Go | Yes | Recommended for chat/message routes | Chat uses `reasoning`; Anthropic messages are handled; unsupported response formats pass through |
+| OpenRouter (reasoning models via openrouter.ai) | Yes | Recommended | Field depends on the upstream model; the fixed-upstream proxy replays `reasoning_content` and passes everything else through |
 | Qwen, GPT, Claude, Gemini, Llama, Mistral | No | No | No reasoning_content |
 
 ---
@@ -359,8 +405,9 @@ The proxy auto-routes by model name prefix. All routes:
 
 | Prefix | Upstream | Reasoning |
 |---|---|---|
-| `deepseek-v4-pro`, `deepseek-v4-flash`, `deepseek-chat` | `https://api.deepseek.com` | Yes (`reasoning_content`) |
-| `deepseek-reasoner` | `https://api.deepseek.com` | **No — actively stripped** (R1 contract: reasoning must NOT be echoed) |
+| `deepseek-v4-flash`, `deepseek-v4-pro`, `deepseek-v4-flash-vision-exp` | `https://api.deepseek.com` | Yes (`reasoning_content`) |
+| `deepseek-chat` | `https://api.deepseek.com` | Non-thinking alias (no reasoning emitted; passback is a harmless no-op) |
+| `deepseek-r1`, `deepseek-reasoner` | `https://api.deepseek.com` | Legacy — retired by DeepSeek 2026-07-24; kept as a compatibility guard with active stripping |
 | `kimi`, `moonshot` | `https://api.moonshot.ai/v1` | Yes (`reasoning_content`) |
 | `glm`, `zhipu` | `https://open.bigmodel.cn/api/paas/v4` | Yes (`reasoning_content`) |
 | `minimax` | `https://api.minimax.io/v1` | Yes (`reasoning_details`, `reasoning_split:true`) |
@@ -374,15 +421,37 @@ The proxy auto-routes by model name prefix. All routes:
 
 Unknown models fall back to `https://api.deepseek.com` with reasoning disabled.
 
+### OpenRouter (port 3462)
+
+OpenRouter wraps many upstream models, and reasoning models served through it lose their thinking the same way. Run a third fixed-upstream proxy and point your OpenRouter provider at it:
+
+```bash
+PORT=3462 UPSTREAM_URL=https://openrouter.ai/api/v1 REASONING_KEY=reasoning_content node proxy/proxy.js
+```
+
+```json
+{
+  "provider": {
+    "openrouter": {
+      "options": {
+        "baseURL": "http://127.0.0.1:3462/v1"
+      }
+    }
+  }
+}
+```
+
+The passive-tap corpus includes an OpenRouter lane: 22 session-confirmed drops, concentrated on `minimax/minimax-m3:free` within one long session — enough to show the pattern exists on OpenRouter, with the full model-by-model matrix left to a follow-up corpus. See [The evidence](#the-evidence).
+
 ---
 
 ## Is it working?
 
 The plugin writes a structured JSON log: `~/.local/share/opencode/thinking-fix.log`.
 
-628 unique sessions. 12,551 inspect events (the hook fires twice per message by design — first pass patches, second confirms clean). 297 reasoning model sessions patched, 331 non-reasoning correctly skipped. Zero false patches.
+Every request logs an `inspect` event (field coverage, whether the model is a reasoning model, how many turns were patched), so the plugin is auditable even when it patches nothing. Non-reasoning models are skipped by design — zero false patches is a property of the self-detection, not a promise bolted on.
 
-Before and after, from a real session:
+From a real 104-message session:
 
 ```
 Before:  reasoning dropped on every turn → AI forgets its thinking
@@ -454,11 +523,16 @@ systemd/
   reasoning-cache.service               # proxy systemd unit (port 3457)
   reasoning-cache-go.service            # OpenCode Go proxy unit (port 3458)
   reasoning-proxy-watchdog.service      # watchdog systemd unit
+tests/
+  test-proxy.js                         # 127 proxy assertions
+  test-plugin.js                        # 12 plugin assertions
+  live-minimax-replay.mjs               # self-contained replay gate (mock upstream)
+proof/                                  # evidence: captures, controls, CSVs, repro scripts
 ```
 
 ## Release highlights
 
-- **v3.2.0:** R1 `strip` sentinel (actively remove reasoning for `deepseek-r1`/`deepseek-reasoner`), multibyte-safe SSE decoding (StringDecoder), response hop-by-hop header stripping, oversized-reasoning skip-not-truncate, MiniMax replay shape behind `MINIMAX_REASONING_DETAILS_SHAPE` (default `minimal`), a real-core test suite (95 assertions), glm-5.2 go-mode `reasoning_content` key (F11, live-verified), derived session keys (Option C), and `x-session-id` no longer forwarded upstream. See the changelog.
+- **v3.2.0:** R1 `strip` sentinel (actively remove reasoning for `deepseek-r1`/`deepseek-reasoner`), multibyte-safe SSE decoding (StringDecoder), response hop-by-hop header stripping, oversized-reasoning skip-not-truncate, MiniMax replay shape behind `MINIMAX_REASONING_DETAILS_SHAPE` (default `minimal`), a real-core test suite (95 assertions), glm-5.2 go-mode `reasoning_content` key (live-verified across two turns), derived session keys, and `x-session-id` no longer forwarded upstream. See the changelog.
 - **v3.1.4:** proxy-owned structured JSONL logging with session identifiers truncated in logs.
 - **v3.1.3:** Anthropic-wire dialect detection for OpenCode Go routes.
 - **v3.1.2:** bounded cache/session memory, raw-stream preservation, hop-by-hop header removal, and safer parser failure handling.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-thinking-fix",
-  "version": "3.2.0",
+  "version": "3.3.1",
   "description": "Restores reasoning content dropped from multi-turn OpenCode conversations (DeepSeek, Kimi, GLM, MiMo, MiniMax, OpenCode Go). Plugin + proxy + watchdog.",
   "type": "module",
   "license": "MIT",

package/proxy/core.js

@@ -39,6 +39,21 @@ export function writeLog(entry) {
 const DEBUG = process.env.DEBUG === '1'
 
 export const ROUTES = {
+  // Zen free-tier lane — BARE model ids as sent by the `opencode` provider
+  // section (port 3459, universal mode). MUST stay at the top: generic
+  // prefixes below ('deepseek-v4-flash', 'mimo', ...) would otherwise swallow
+  // these names and route free traffic to provider-native endpoints.
+  'x-preview-f-free': { base: 'https://opencode.ai/zen/v1', reasoningKey: 'reasoning_content' },
+  'hy3-free': { base: 'https://opencode.ai/zen/v1', reasoningKey: 'reasoning_content' },
+  'mimo-v2.5-free': { base: 'https://opencode.ai/zen/v1', reasoningKey: 'reasoning_content' },
+  'muse-spark-1.2-contributor-free': { base: 'https://opencode.ai/zen/v1', reasoningKey: 'reasoning_content' },
+  'deepseek-v4-flash-free': { base: 'https://opencode.ai/zen/v1', reasoningKey: 'reasoning_content' },
+  'ling-3.0-flash-fin-free': { base: 'https://opencode.ai/zen/v1', reasoningKey: 'reasoning_content' },
+  'laguna-s-2.1-free': { base: 'https://opencode.ai/zen/v1', reasoningKey: 'reasoning_content' },
+  'big-pickle': { base: 'https://opencode.ai/zen/v1', reasoningKey: 'reasoning_content' },
+  'ox-alpha-free': { base: 'https://opencode.ai/zen/v1', reasoningKey: 'reasoning_content' },
+  'nemotron-3-ultra-free': { base: 'https://opencode.ai/zen/v1', reasoningKey: 'reasoning_content' },
+  'nemotron-3.5-lightning-free': { base: 'https://opencode.ai/zen/v1', reasoningKey: 'reasoning_content' },
   // R1 aliases: reasoning must not be echoed back — the 'strip' sentinel
   // admits the request to patchRequestBody (to REMOVE any reasoning fields a
   // client/plugin attached) while excluding it from response-side caching.
@@ -62,10 +77,30 @@ export const ROUTES = {
   gemini: { base: 'https://generativelanguage.googleapis.com/v1beta/openai', reasoningKey: null },
   llama: { base: 'https://api.together.xyz', reasoningKey: null },
   mistral: { base: 'https://api.mistral.ai', reasoningKey: null },
+  // opencode/ zen free-tier models — served by the OpenCode zen gateway at
+  // zen/v1 (chat/completions wire, reasoning_content carrier). Distinct from
+  // the opencode-go namespace (port 3458) handled by fixedUpstreamRoute.
+  // Explicit per-model prefixes only: no catch-all `opencode/` prefix, so paid
+  // opencode/* models keep their existing DEFAULT_ROUTE behavior.
+  'opencode/hy3-free': { base: 'https://opencode.ai/zen/v1', reasoningKey: 'reasoning_content' },
+  'opencode/mimo-v2.5-free': { base: 'https://opencode.ai/zen/v1', reasoningKey: 'reasoning_content' },
+  'opencode/muse-spark-1.2-contributor-free': { base: 'https://opencode.ai/zen/v1', reasoningKey: 'reasoning_content' },
+  'opencode/deepseek-v4-flash-free': { base: 'https://opencode.ai/zen/v1', reasoningKey: 'reasoning_content' },
+  'opencode/nemotron-3-ultra-free': { base: 'https://opencode.ai/zen/v1', reasoningKey: 'reasoning_content' },
+  'opencode/nemotron-3.5-lightning-free': { base: 'https://opencode.ai/zen/v1', reasoningKey: 'reasoning_content' },
 }
 
 export const DEFAULT_ROUTE = { base: 'https://api.deepseek.com', reasoningKey: null }
 
+// F13 (2026-08-27): clients may speak either OpenAI-style relative paths
+// (/v1/...) or the upstream's full official prefix (/api/v1/... — OpenRouter's
+// documented base is https://openrouter.ai/api/v1). Never double the prefix.
+export function upstreamPathFor(reqUrl, basePath) {
+  if (!basePath || basePath === '/' || basePath === '/v1') return reqUrl
+  if (reqUrl === basePath || reqUrl.startsWith(basePath + '/')) return reqUrl
+  return basePath + reqUrl.replace(/^\/v1/, '')
+}
+
 export function route(modelName) {
   if (!modelName) return DEFAULT_ROUTE
   const lower = modelName.toLowerCase()
@@ -91,6 +126,15 @@ export function fixedUpstreamRoute(modelName, requestUrl = '') {
   if (stripped === 'glm-5.2' && String(requestUrl).includes('/chat/completions')) {
     return { base: '', reasoningKey: 'reasoning_content' }
   }
+  // REASONING_KEY env override (F12, 2026-08-27): lanes fixed to upstreams whose
+  // wire is reasoning_content-based (zen/v1 free models, OpenRouter normalized
+  // per-message passback) set REASONING_KEY=reasoning_content in their unit.
+  // OpenRouter docs define top-level `reasoning` as a config OBJECT on requests,
+  // so a string injection there must use reasoning_content instead. Units without
+  // the env (validated go lane, 3458) keep the unconditional 'reasoning' behavior.
+  if (process.env.REASONING_KEY) {
+    return { base: '', reasoningKey: process.env.REASONING_KEY }
+  }
   // Unconditional 'reasoning' for go mode: matches current working behavior
   // for chat/completions models; /responses bodies have no `messages` array
   // and pass through untouched.

package/proxy/proxy.js

@@ -58,7 +58,7 @@ import https from 'node:https'
 import url   from 'node:url'
 import {
   ROUTES, cache, stats, route, fixedUpstreamRoute, getSessionCache, patchRequestBody,
-  extractReasoningFromJson, createStreamParser, writeLog, deriveSessionId,
+  extractReasoningFromJson, createStreamParser, writeLog, deriveSessionId, upstreamPathFor,
 } from './core.js'
 
 const PORT            = parseInt(process.env.PORT || '3457', 10)
@@ -170,11 +170,9 @@ const server = http.createServer((req, res) => {
     }
 
     // ── Upstream request options ──
-    let upstreamPath = req.url
-    const basePath = upstream.path || '/'
-    if (basePath !== '/' && basePath !== '/v1') {
-      upstreamPath = basePath + req.url.replace(/^\/v1/, '')
-    }
+    // F13: path normalization lives in core.js (upstreamPathFor) — never double
+    // the upstream's official prefix.
+    const upstreamPath = upstreamPathFor(req.url, upstream.path || '/')
     const transport = upstream.protocol === 'https:' ? https : http
     const HOP_BY_HOP = new Set(['connection', 'keep-alive', 'te', 'trailer', 'transfer-encoding', 'upgrade', 'proxy-', 'x-session-id'])
     const safeHeaders = {}