PR #68351: fix(openrouter): surface reasoning_details visible-text as user output (#68261)

• Repository: openclaw/openclaw
• Author: neeravmakwana
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/68351

Description (problem / solution / changelog)

Summary

• Problem: OpenRouter model runs (e.g. openrouter/google/gemini-2.5-flash, Grok 4.x, minimax-m2.7) return blank responses with stopReason=stop payloads=0 and surface ⚠️ Agent couldn't generate a response.
• Why it matters: Entire classes of OpenRouter-proxied models have been unusable since 2026.4.14/15 despite healthy gateway and successful upstream responses.
• What changed: getCompletionsReasoningDelta in src/agents/openai-transport-stream.ts now discriminates the OpenRouter reasoning_details stream between hidden reasoning (reasoning.text) and OpenAI Responses–style visible output (response.output_text, response.text, text). Visible-output items are routed through the same text-block path as choice.delta.content instead of being buried in a thinking block.
• What did NOT change (scope boundary): no changes to prompts, auth, sandbox, tool policy, secret handling, provider routing, request assembly, transcript bytes, or prompt-cache order. Previous reasoning.text behavior is preserved byte-for-byte.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #68261
• Related #67410, #67575, #67698, #67907, #67425, #68030, #68076, #68185
• This PR fixes a bug or regression

Root Cause

e0bf756b50 ("fix: handle OpenRouter Qwen3 reasoning_details streams") taught getCompletionsReasoningDelta to parse reasoning_details items, but it unconditionally classified every matching item as hidden thinking. Some OpenRouter upstreams (Gemini 2.5 Flash via the Responses-style reasoning proxy, xAI Grok 4.x, and related models) deliver the assistant's final answer inside reasoning_details using OpenAI Responses content types such as response.output_text, response.text, and plain text, with an empty choice.delta.content. Because the parser treated those as thinking, the stream closed with stopReason=stop, zero text blocks, and the incomplete-turn detector in src/agents/pi-embedded-runner/run/incomplete-turn.ts surfaced the generic error.

• Root cause: reasoning_details visible-output types were misclassified as internal reasoning and never emitted as user-visible text.
• Missing detection / guardrail: no regression covered reasoning_details streams where the final answer arrives without a separate content field.
• Contributing context: OpenRouter's proxy layer for several reasoning models started folding visible output into reasoning_details alongside reasoning bytes.

Regression Test Plan

• Coverage level that should have caught this:
  • Unit test
• Target test or file: src/agents/openai-transport-stream.test.ts
• Scenario the test should lock in: a mixed reasoning_details stream where reasoning.text items stay as thinking while response.output_text, response.text, and text items surface as a user-visible text block with stopReason=stop.
• Why this is the smallest reliable guardrail: it exercises the exact parser path that decides whether bytes become visible text or hidden thinking.
• Existing test that already covers this: handles reasoning_details from OpenRouter/Qwen3 in completions stream only covered content + reasoning.text mixes, not the visible-text-in-reasoning_details case.

User-visible / Behavior Changes

• OpenRouter models that deliver the final answer inside reasoning_details (e.g. Gemini 2.5 Flash, Grok 4.x) now produce visible replies instead of the generic ⚠️ Agent couldn't generate a response error. No configuration, defaults, or docs change.

Diagram

Before:
OpenRouter -> reasoning_details[{type:"response.output_text", text:"hello"}]
           -> classified as thinking
           -> stopReason=stop, payloads=0
           -> "⚠️ Agent couldn't generate a response."

After:
OpenRouter -> reasoning_details[{type:"response.output_text", text:"hello"}]
           -> classified as visible text
           -> text block "hello", stopReason=stop, payloads>=1
           -> user sees "hello"

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Runtime-enforced controls that are explicitly unchanged by this PR: tool policy/allowlist, sandbox, exec approval, subagent policy, secrets plan, owner-only gating, OpenRouter routing, auth profiles, and prompt-cache request assembly. The fix is confined to classification of bytes the upstream already returned over an authenticated, already-policy-gated channel; it does not rely on or modify any prompt text or runtime policy. A malicious upstream that labels reasoning as type: "text" cannot leak more than it could by setting choice.delta.content directly, which is already the default visible path.

Repro + Verification

Environment

• OS: macOS (Darwin 25.3.0)
• Runtime/container: local OpenClaw gateway (loopback)
• Model/provider: openrouter/google/gemini-2.5-flash, openrouter/x-ai/grok-4.1-fast, openrouter/minimax/minimax-m2.7
• Integration/channel: none (direct openclaw infer model run) and dashboard
• Relevant config: agents.defaults.models = { "openrouter/google/gemini-2.5-flash": {} } (redacted)

Steps

1. openclaw infer model run --model openrouter/google/gemini-2.5-flash --prompt "Reply with exactly: hello" --json
2. Observe response contents and gateway log for incomplete turn detected ... payloads=0.
3. Repeat for Grok 4.x / minimax-m2.7.

Expected

• outputs[0].text contains the assistant reply.
• No payloads=0 / incomplete turn detected warning.

Actual (before fix)

• outputs[0].text = ⚠️ Agent couldn't generate a response. Please try again.
• Gateway log: incomplete turn detected: ... stopReason=stop payloads=0 — surfacing error to user.

Evidence

• Failing test/log before + passing after
• Trace/log snippets

Before: reasoning_details visible-text items classified as thinking, zero text blocks, stopReason=stop payloads=0. After: new test surfaces reasoning_details visible-text as text while keeping reasoning.text as thinking asserts text block emission alongside the preserved thinking block; existing reasoning_details/Qwen3 and tool-call regression tests remain green.

Human Verification (required)

• Verified scenarios:
  • pnpm test src/agents/openai-transport-stream.test.ts — 56/56 pass including the new case.
  • pnpm test src/agents/openai-transport-stream.test.ts -t reasoning_details — 4/4 reasoning_details cases pass.
  • Re-ran pnpm check (host-env-policy, tool-display, no-conflict-markers green); remaining pnpm tsgo/pnpm lint failures are pre-existing in extensions/qa-lab/src/providers/aimock/server.ts on upstream/main and unrelated to this change (verified by running pnpm tsgo on clean upstream/main).
• Edge cases checked:
  • reasoning.text-only stream still becomes a thinking block (existing Qwen3 test).
  • Mixed reasoning.text + visible-text items in the same stream produce both thinking and text blocks in order.
  • reasoning_details arriving alongside tool_calls still routes through the buffered thinking path and preserves tool-call arguments (existing tests).
  • Non-array or unknown-type reasoning_details items are skipped silently.
• What I did not verify:
  • Live OpenRouter run against real keys (no live lane invoked in this change).
  • Parallels smoke / cross-platform onboarding (not in scope for a parser-only fix).

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Risks and Mitigations

• Risk: a model intentionally using type: "text" inside reasoning_details for genuinely-hidden scratchpad content would now surface that content to users.
  • Mitigation: OpenRouter's documented semantics for response.output_text / response.text / text are visible assistant output; the existing reasoning.text type still maps to hidden reasoning. If a specific upstream deviates, follow-up can narrow the visible-type set.
• Risk: Qwen3 regression from #66905 returns.
  • Mitigation: the existing Qwen3 regression test and the tool-call + reasoning_details test remain unchanged and still pass.

Testing notes

• AI-assisted PR, lightly tested (parser unit tests only; no live OpenRouter run).
• Exact tests run:
  • pnpm test src/agents/openai-transport-stream.test.ts (56/56 pass)
  • pnpm test src/agents/openai-transport-stream.test.ts -t reasoning_details (4/4 pass)
  • pnpm test src/agents/openai-transport-stream.test.ts -t visible-text (1/1 pass)
  • pnpm check (pre-existing aimock/server.ts failures on upstream/main; no new failures introduced)

Made with Cursor

Changed files

• CHANGELOG.md (modified, +1/-0)
• src/agents/openai-transport-stream.test.ts (modified, +138/-0)
• src/agents/openai-transport-stream.ts (modified, +63/-14)