[bot] Streaming aggregator and output types drop the structured output `refusal` field

[braintrust-bot]

Summary

When OpenAI returns a safety refusal for a structured output request, the refusal text is sent in a dedicated refusal field on the message (both in non-streaming and streaming responses). The SDK's StreamDelta, ChatMessage, and streaming aggregation logic have no refusal field, so refusal content is silently dropped from logged span output. Users cannot distinguish a refused structured output from an empty response in their Braintrust traces.

What is missing

OpenAI's Chat Completions API includes a refusal field on assistant messages when using response_format: { type: "json_schema", ... }:

Non-streaming response:

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": null,
      "refusal": "I'm sorry, I cannot assist with that request."
    },
    "finish_reason": "stop"
  }]
}

Streaming delta:

{"choices": [{"delta": {"role": "assistant", "refusal": ""}}]}
{"choices": [{"delta": {"refusal": "I'm sorry, I cannot"}}]}
{"choices": [{"delta": {"refusal": " assist with that request."}}]}

Currently in the SDK:

1. StreamDelta (src/stream.rs:651-656) only has role and content fields — no refusal field, so refusal text in streaming deltas is silently ignored during deserialization
2. ChatMessage (src/stream.rs:268-275) only has role, content, and tool_calls — no refusal field, so even if captured during aggregation, it cannot be represented in the output
3. aggregate() (src/stream.rs:727-807) only concatenates delta.content — no logic to accumulate delta.refusal

This means when a model refuses a structured output request:

• The refusal message is lost from the logged span
• The span output shows content: "" (empty) with no indication of why
• Users cannot filter or alert on refusals in Braintrust dashboards

Braintrust docs status

supported — Braintrust's OpenAI integration page documents structured output support with response_format: { type: "json_schema" }. The refusal field is not specifically mentioned. Other Braintrust SDKs capture the full message object including refusal when present.

• https://www.braintrust.dev/docs/integrations/ai-providers/openai — documents structured output tracing

Upstream sources

• OpenAI Structured Outputs guide — documents the refusal field: https://platform.openai.com/docs/guides/structured-outputs
• OpenAI Chat Completions response object — refusal field on message: https://platform.openai.com/docs/api-reference/chat/object
• OpenAI blog post introducing structured outputs and the refusal field: https://openai.com/index/introducing-structured-outputs-in-the-api/

Relationship to existing issues

• Distinct from [BOT ISSUE] Streaming aggregator drops tool calls from Chat Completions deltas #30 (streaming tool call aggregation): [BOT ISSUE] Streaming aggregator drops tool calls from Chat Completions deltas #30 is about the missing tool_calls field in StreamDelta. This is about the missing refusal field — a different message property for a different feature (structured output safety).
• Distinct from [BOT ISSUE] No support for OpenAI Responses API format in streaming or usage extraction #31 (OpenAI Responses API format): [BOT ISSUE] No support for OpenAI Responses API format in streaming or usage extraction #31 is about an entirely different API surface. The refusal field exists in the Chat Completions API which the SDK already partially supports.
• Distinct from [BOT ISSUE] Streaming usage metrics drop reasoning tokens and token detail breakdowns #32 (streaming usage detail loss): [BOT ISSUE] Streaming usage metrics drop reasoning tokens and token detail breakdowns #32 is about missing usage metric fields. This is about missing output content (the refusal text itself).

Local files inspected

• src/stream.rs:651-656 — StreamDelta struct has only role and content; no refusal field
• src/stream.rs:268-275 — ChatMessage struct has role, content, tool_calls; no refusal field
• src/stream.rs:779-789 — aggregate() only reads delta.role and delta.content; no refusal handling
• Full codebase grep for "refusal", "content_filter", "structured_output" — zero results