fix(openai): surface chat-completions refusal as visible text by xydt-tanshanshan · Pull Request #102334 · openclaw/openclaw

xydt-tanshanshan · 2026-07-09T01:24:05Z

What Problem This Solves

When an OpenAI chat-completions response carries a safety or structured-output refusal, the assistant turn resolves to empty content and the user sees nothing. OpenAI returns refusals in a top-level refusal field with content: null and finish_reason: "stop", but the completions streaming assembler never reads refusal, so the refusal text is silently dropped.

Why This Change Was Made

Two streaming assemblers had the same blind spot:

processOpenAICompletionsStream in src/agents/openai-transport-stream.ts — the delta loop reads content, reasoning deltas, and tool_calls from choice.delta but never checks refusal
streamOpenAICompletions in packages/ai/src/providers/openai-completions.ts — same pattern, drops refusal

The sibling Responses path (same file, lines 1635, 1697-1700, 1878) already routes refusal correctly. The fix mirrors that pattern: when content is null/absent, check refusal and route it as visible assistant text.

User Impact

For users whose prompts trigger an OpenAI safety refusal on the openai-completions API, the assistant reply will now show the refusal text (e.g. "I can't help with that.") instead of a blank empty reply. Users of the Responses API are unaffected (already handled).

Evidence

Real proof — streaming delta refusal (after fix):

Proof run on disposable Node.js, stubbing only the transport input as an async iterable, keeping the processOpenAICompletionsStream assembly logic real:

$ node --import tsx -e "
import { testing } from './src/agents/openai-transport-stream.js';
const model = { id: 'gpt-5.4-mini', name: 'GPT-5.4 Mini', api: 'openai-completions',
  provider: 'openai', baseUrl: 'https://api.openai.com/v1', reasoning: false, input: ['text'],
  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }, contextWindow: 200000, maxTokens: 8192 };
const output = { role: 'assistant', content: [], api: 'openai-completions', provider: 'openai',
  model: 'gpt-5.4-mini', usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0,
    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } },
  stopReason: 'stop', timestamp: Date.now() };

// Test 1: streaming delta with refusal
const o1 = { ...output, content: [] };
await testing.processOpenAICompletionsStream(
  (async function*() {
    yield { id: 'cmpl-1', object: 'chat.completion.chunk', created: 1, model: 'gpt-5.4-mini',
      choices: [{ index: 0, delta: { role: 'assistant', refusal: \"I can't help.\" }, logprobs: null, finish_reason: 'stop' }] };
  })(), o1, model, { push: () => {} });
console.log('Streaming delta:', JSON.stringify(o1.content));

// Test 2: aggregated message with refusal
const o2 = { ...output, content: [] };
await testing.processOpenAICompletionsStream(
  (async function*() {
    yield { id: 'cmpl-2', object: 'chat.completion.chunk', created: 1, model: 'gpt-5.4-mini',
      choices: [{ index: 0, message: { role: 'assistant', content: null, refusal: \"I can't help.\" }, logprobs: null, finish_reason: 'stop' }] };
  })(), o2, model, { push: () => {} });
console.log('Aggregated msg: ', JSON.stringify(o2.content));
"

Streaming delta: [{"type":"text","text":"I can't help."}]
Aggregated msg:  [{"type":"text","text":"I can't help."}]

Both forms now surface the refusal as visible assistant text instead of empty content.

Code change — src/agents/openai-transport-stream.ts (after choiceDelta.content block):

    } else if (
      !choiceDelta.content &&
      typeof (choiceDelta as { refusal?: string }).refusal === "string"
    ) {
      // Chat Completions can put safety/structured-output refusals in a top-level
      // `refusal` field with content: null. Surface refusal as visible text
      // (Responses path already routes refusal deltas).
      const refusalText = (choiceDelta as { refusal?: string }).refusal!;
      const routedDeltas = hasMirroredReasoning
        ? reasoningTagTextPartitioner.push(refusalText)
        : reasoningTagTextPartitioner.pushVisible(refusalText);
      for (const routedDelta of routedDeltas) {
        appendPartitionedVisibleDelta(routedDelta);
      }
    }

Code change — packages/ai/src/providers/openai-completions.ts (after choice.delta.content block):

    } else if (typeof choice.delta.refusal === "string") {
      appendPartitionedContent(choice.delta.refusal, Boolean(foundReasoningField));
    }

Test coverage — 3 new tests across 2 files:

src/agents/openai-transport-stream.test.ts: streaming delta refusal + aggregated message refusal
packages/ai/src/providers/openai-completions.test.ts: streaming delta refusal in the shared assembler

All tests feed a refusal-only chunk and assert output.content equals [{ type: "text", text: "I can't help with that." }].

Environment: Linux x86_64, Node v24.13.1, commit 615cab6.

Fixes #102321

clawsweeper · 2026-07-09T01:25:03Z

Thanks for the context here. I swept through the related work, and this is now duplicate or superseded.

Close as superseded: the same linked refusal bug now has a better canonical landing candidate at #102344, while this branch is conflicting and still misses the shared-provider message.refusal case.

Canonical path: Use #102344 as the canonical landing path for the linked refusal bug, then close the duplicate refusal-fix branches.

So I’m closing this here and keeping the remaining discussion on #102344.

Review details

Best possible solution:

Use #102344 as the canonical landing path for the linked refusal bug, then close the duplicate refusal-fix branches.

Do we have a high-confidence way to reproduce the issue?

Yes. Source inspection gives a high-confidence path: feed either completions assembler a refusal-only delta or message chunk and current main never reads the refusal field.

Is this the best way to solve the issue?

No. The narrow parser-parity fix is the right shape, but this branch is not the best landing path because it leaves the shared provider's aggregated message.refusal case uncovered and is superseded by a proof-positive sibling PR.

Security review:

Security review cleared: No concrete security or supply-chain regression was found; the diff touches provider parsing and focused tests without dependency, workflow, secret, package, or install-script changes.

AGENTS.md: found and applied where relevant.

What I checked:

Repository policy read: Root AGENTS.md and scoped src/agents/AGENTS.md were read fully; provider/runtime reviews require source, sibling-surface, dependency-contract, and best-fix checks. (AGENTS.md:1, e90bf3182927)
Current main agent assembler gap: Current main normalizes choice.delta ?? choice.message in processOpenAICompletionsStream, then handles content, reasoning, and tool calls without reading choiceDelta.refusal. (src/agents/openai-transport-stream.ts:3135, e90bf3182927)
Current main shared provider gap: Current main streamOpenAICompletions only enters the parser block for choice.delta, so a chunk with only choice.message.refusal is skipped. (packages/ai/src/providers/openai-completions.ts:427, e90bf3182927)
This PR still leaves the shared message path uncovered: At the PR head, the shared provider adds choice.delta.refusal handling but does not normalize choice.delta ?? choice.message, so the aggregated message.refusal form from the linked issue remains unfixed on that sibling surface. (src/llm/providers/openai-completions.ts:430, 1484e4e8f4d8)
Canonical PR is viable: fix: surface OpenAI chat-completions refusal as assistant text #102344 is open, mergeable, labeled proof: sufficient, and marked ready for maintainer look. (1e49e5005dc3)
Canonical PR covers the missing path: The canonical PR normalizes choice.delta ?? choice.message in the shared provider and adds coverage for aggregated message.refusal. (packages/ai/src/providers/openai-completions.ts:424, 1e49e5005dc3)

Likely related people:

steipete: Commit 062f88e extracted the reusable AI runtime package and touched both the shared provider and agent transport; commit 4bf70be recently touched the shared OpenAI completions provider path. (role: AI runtime package refactor owner and recent adjacent contributor; confidence: high; commits: 062f88e3e3af, 4bf70be01a21; files: packages/ai/src/providers/openai-completions.ts, packages/ai/src/providers/register-builtins.ts, src/agents/openai-transport-stream.ts)
vincentkoc: Commit bf8626c touched the shared OpenAI completions provider while adding provider support, making this person a plausible reviewer for provider-shape handling. (role: recent provider contributor; confidence: medium; commits: bf8626c0e950; files: packages/ai/src/providers/openai-completions.ts)
balajisiva: Commit efab976 fixed a nearby OpenAI-compatible completions parser issue involving silent output loss in the agent transport path. (role: adjacent parser bug-fix author; confidence: medium; commits: efab9763dc87; files: src/agents/openai-transport-stream.ts)

Codex review notes: model internal, reasoning high; reviewed against e90bf3182927.

xydt-tanshanshan · 2026-07-09T02:00:28Z

@clawsweeper re-review

clawsweeper · 2026-07-09T02:00:30Z

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

OpenAI chat-completions safety/structured-output refusals arrive in a top-level refusal field with content: null. The streaming assembler never read this field, so the assistant turn resolved to empty content. - src/agents/openai-transport-stream.ts: add else-if branch for choiceDelta.refusal in processOpenAICompletionsStream delta loop, routing refusal text through appendTextDelta - packages/ai/src/providers/openai-completions.ts: add else-if for refusal in streamOpenAICompletions, routing through appendPartitionedContent - Add 2 tests (streaming delta + aggregated message) covering refusal surfacing - Sibling Responses path already handled refusal at lines 1635, 1697-1700, 1878 Fixes openclaw#102321

…efusal routing, add packages/ai test

xydt-tanshanshan · 2026-07-09T03:39:01Z

@clawsweeper re-review

clawsweeper · 2026-07-09T03:39:04Z

🦞🧹
ClawSweeper could not start a re-review for this item.

Reason: re-review requires an open issue or PR.

openclaw-barnacle Bot added agents Agent runtime and tooling size: S labels Jul 9, 2026

clawsweeper Bot mentioned this pull request Jul 9, 2026

fix(openai): surface chat-completions refusal text #102342

Closed

clawsweeper Bot mentioned this pull request Jul 9, 2026

fix(openai): surface chat-completions refusal text as visible content #102349

Closed

5 tasks

github-actions Bot mentioned this pull request Jul 9, 2026

🦞 OpenClaw 生态日报 2026-07-09 zx0828/big_model_radar#236

Open

clawsweeper Bot mentioned this pull request Jul 9, 2026

fix: surface OpenAI chat-completions refusal as assistant text #102344

Merged

openclaw-barnacle Bot added app: ios App: ios size: M scripts Repository scripts and removed size: S labels Jul 9, 2026

hailory added 2 commits July 9, 2026 11:21

[AI] improve(openai): typeof guard, reasoningTagTextPartitioner for r…

1484e4e

…efusal routing, add packages/ai test

xydt-tanshanshan force-pushed the fix/chat-completions-refusal-102321 branch from b1c062b to 1484e4e Compare July 9, 2026 03:25

openclaw-barnacle Bot added size: S and removed app: ios App: ios scripts Repository scripts size: M labels Jul 9, 2026

xydt-tanshanshan closed this Jul 9, 2026

github-actions Bot mentioned this pull request Jul 9, 2026

🦞 OpenClaw 生态日报 2026-07-09 96loveslife/big_model_radar#131

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(openai): surface chat-completions refusal as visible text#102334

fix(openai): surface chat-completions refusal as visible text#102334
xydt-tanshanshan wants to merge 2 commits into
openclaw:mainfrom
xydt-tanshanshan:fix/chat-completions-refusal-102321

xydt-tanshanshan commented Jul 9, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jul 9, 2026 •

edited

Loading

Uh oh!

xydt-tanshanshan commented Jul 9, 2026

Uh oh!

clawsweeper Bot commented Jul 9, 2026 •

edited

Loading

Uh oh!

xydt-tanshanshan commented Jul 9, 2026

Uh oh!

clawsweeper Bot commented Jul 9, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

xydt-tanshanshan commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Problem This Solves

Why This Change Was Made

User Impact

Evidence

Uh oh!

clawsweeper Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

xydt-tanshanshan commented Jul 9, 2026

Uh oh!

clawsweeper Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

xydt-tanshanshan commented Jul 9, 2026

Uh oh!

clawsweeper Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

xydt-tanshanshan commented Jul 9, 2026 •

edited

Loading

clawsweeper Bot commented Jul 9, 2026 •

edited

Loading

clawsweeper Bot commented Jul 9, 2026 •

edited

Loading

clawsweeper Bot commented Jul 9, 2026 •

edited

Loading