Add OpenAI Responses API support and unified refusal handling

[sroussey]

Summary

This PR adds comprehensive support for OpenAI's Responses API (the successor to Chat Completions) and implements unified refusal handling across all providers. The Responses API offers typed streaming events, better tool-call streaming, and reasoning support for the GPT-5.6 family.

Key Changes

OpenAI Responses API Support

• New module OpenAIShapedResponses.ts with helpers for the Responses API:

  • buildResponsesInput() — converts unified message format to Responses input + instructions
  • buildResponsesTools() — flattens tool definitions (no nested function wrapper)
  • mapResponsesToolChoice() — maps tool choice to Responses format
  • parseResponsesToolCalls() — parses non-streaming tool calls from output[]
  • accumulateOpenAIResponsesStream() — adapts typed Responses events to workglow StreamEvents (text-delta, object-delta, refusal)

• Updated OpenAI run-fns to use Responses API:

  • OpenAI_TextGeneration_Stream — now uses client.responses.create()
  • OpenAI_ToolCalling_Stream — streams tool calls via Responses
  • OpenAI_TextRewriter_Stream — uses Responses with instructions channel
  • OpenAI_TextSummary_Stream — migrated to Responses

• New OpenAI client helpers:

  • getReasoningConfig() — resolves reasoning settings for GPT-5.6 sol/terra/luna and o-series models
  • resolvePromptCacheKey() — derives stable cache keys from model + system + tools, or uses explicit override
  • isStrictCompatibleSchema() — validates JSON schemas for Responses strict mode compatibility
  • finalizeResponsesRequest() — applies reasoning, cache key, and strict mode to Responses requests

• Model capability inference for GPT-5.6 family (sol/terra/luna variants) with tool-use, json-mode, and vision support

Unified Refusal Handling

• New StreamEvent type refusal — first-class refusal events with optional category field

• Provider-agnostic emitRefusal() helper in RefusalHelpers.ts

• Per-provider refusal detection:

  • OpenAI: response.refusal.delta events (Responses API)
  • OpenAI Chat: delta.refusal in chat completions
  • Anthropic: message_delta with stop_reason: "refusal" → Anthropic_Refusal.ts
  • Gemini: finishReason in {SAFETY, PROHIBITED_CONTENT, …} or promptFeedback.blockReason → Gemini_Refusal.ts
  • xAI: delta.refusal in chat completions

• Refusal accumulation in StreamEventAccumulator and StreamProcessor:

  • Refusals fold into reserved refusal output field (concatenated if streamed)
  • Optional refusal_category field for provider-specific reason
  • Task still COMPLETES (not an error)

• Structured generation respects refusals — stops retry loop if model refuses

Testing

• Comprehensive test suite OpenAIShapedResponses.test.ts covering:

  • Text delta mapping
  • Tool call argument accumulation and fragmentation
  • Concurrent tool calls (separate by output_index)
  • Interleaved text and tool-call streams
  • Orphaned deltas (synthesized IDs)
  • Refusal deltas
  • Lifecycle event filtering

• Cross-provider refusal tests CrossProviderRefusals.test.ts validating OpenAI, Anthropic, and Gemini refusal signals

• Updated OpenAiProvider.test.ts with reasoning config and schema validation tests

Implementation Details

https://claude.ai/code/session_014wMFWnofYaAj8vcLMHS1p9

[Copilot]

Pull request overview

This PR migrates the OpenAI provider’s streaming text/tool/structured-generation run-fns to the Responses API and adds a provider-agnostic “refusal” stream event that is accumulated into reserved output fields so callers can reliably detect policy/safety declines across providers.

Changes:

• Add OpenAI Responses API shaping helpers (input/tools/tool choice/tool call parsing + typed event stream adapter) and migrate OpenAI streaming run-fns to client.responses.create(...).
• Introduce first-class refusal stream events and plumb refusal accumulation through StreamProcessor, StreamEventAccumulator, StructuredGenerationTask, and cache behavior.
• Add/refine refusal detection for Anthropic, Gemini, and OpenAI-compatible chat providers (xAI / HFI), plus new test coverage for Responses streaming + cross-provider refusals.

Reviewed changes

Copilot reviewed 42 out of 42 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
providers/xai/src/ai/common/Xai_ToolCalling.ts	Switches xAI tool-calling stream adapter to the renamed OpenAI-chat accumulator.
providers/xai/src/ai/common/Xai_TextSummary.ts	Emits refusal events when xAI chat deltas include delta.refusal.
providers/xai/src/ai/common/Xai_TextRewriter.ts	Emits refusal events when xAI chat deltas include delta.refusal.
providers/xai/src/ai/common/Xai_TextGeneration.ts	Adds delta.refusal support alongside streamed content.
providers/xai/src/ai/common/Xai_StructuredGeneration.ts	Accumulates chat refusal deltas and emits a terminal refusal event.
providers/openai/src/ai/index.ts	Exposes additional OpenAI internals via _testOnly for new tests.
providers/openai/src/ai/common/OpenAI_ToolCalling.ts	Migrates tool-use streaming to OpenAI Responses API + Responses-shaped tools/tool-choice/input.
providers/openai/src/ai/common/OpenAI_TextSummary.ts	Migrates summary streaming to OpenAI Responses API via Responses stream accumulator.
providers/openai/src/ai/common/OpenAI_TextRewriter.ts	Migrates rewrite streaming to OpenAI Responses API via Responses stream accumulator.
providers/openai/src/ai/common/OpenAI_TextGeneration.ts	Migrates unified text generation streaming to OpenAI Responses API; uses Responses input/instructions mapping.
providers/openai/src/ai/common/OpenAI_StructuredGeneration.ts	Uses Responses text.format=json_schema and adds strict-schema compatibility detection + refusal capture.
providers/openai/src/ai/common/OpenAI_ModelSearch.ts	Adds GPT-5.6 family IDs to fallback model list.
providers/openai/src/ai/common/OpenAI_ModelSchema.ts	Adds provider-config knobs for prompt_cache_key override and reasoning settings.
providers/openai/src/ai/common/OpenAI_Client.ts	Adds reasoning config resolution + deterministic prompt cache key derivation and request finalization.
providers/huggingface-inference/src/ai/common/HFI_ToolCalling.ts	Switches HFI tool-calling to OpenAI-chat accumulator rename.
providers/google-gemini/src/ai/index.ts	Exposes refusal helpers via _testOnly.
providers/google-gemini/src/ai/common/Gemini_ToolCalling.ts	Detects refusal category during streaming and emits a normalized refusal at end.
providers/google-gemini/src/ai/common/Gemini_TextSummary.ts	Detects refusal category during streaming and emits a normalized refusal at end.
providers/google-gemini/src/ai/common/Gemini_TextRewriter.ts	Detects refusal category during streaming and emits a normalized refusal at end.
providers/google-gemini/src/ai/common/Gemini_TextGeneration.ts	Detects refusal category during streaming and emits a normalized refusal at end.
providers/google-gemini/src/ai/common/Gemini_StructuredGeneration.ts	Detects refusal category during streaming and emits a normalized refusal at end.
providers/google-gemini/src/ai/common/Gemini_Refusal.ts	New helper to classify Gemini refusal/block signals and emit normalized refusal events.
providers/anthropic/src/ai/index.ts	Exposes refusal helper via _testOnly.
providers/anthropic/src/ai/common/Anthropic_ToolCalling.ts	Emits refusal when Anthropic stream indicates stop_reason: "refusal".
providers/anthropic/src/ai/common/Anthropic_TextSummary.ts	Emits refusal when Anthropic stream indicates stop_reason: "refusal".
providers/anthropic/src/ai/common/Anthropic_TextRewriter.ts	Emits refusal when Anthropic stream indicates stop_reason: "refusal".
providers/anthropic/src/ai/common/Anthropic_TextGeneration.ts	Emits refusal when Anthropic stream indicates stop_reason: "refusal".
providers/anthropic/src/ai/common/Anthropic_StructuredGeneration.ts	Emits refusal when Anthropic stream indicates stop_reason: "refusal".
providers/anthropic/src/ai/common/Anthropic_Refusal.ts	New helper to detect/emit Anthropic refusals during streaming.
packages/task-graph/src/task/StreamTypes.ts	Adds StreamRefusal plus reserved output keys for refusal text/category.
packages/task-graph/src/task/StreamProcessor.ts	Accumulates streamed refusals into reserved output fields without treating them as errors.
packages/task-graph/src/task/CacheCoordinator.ts	Prevents caching refused outputs.
packages/ai/src/task/StructuredGenerationTask.ts	Stops retry loop when a refusal is observed (terminal valid outcome).
packages/ai/src/provider-utils/RefusalHelpers.ts	New provider-agnostic emitRefusal(...) helper.
packages/ai/src/provider-utils/OpenAIShapedResponses.ts	New Responses API adapter helpers (input/tools/tool choice/tool call parsing + typed stream mapping).
packages/ai/src/provider-utils/OpenAIShapedChat.ts	Renames stream accumulator to accumulateOpenAIChatStream and adds chat refusal delta mapping.
packages/ai/src/provider-utils.ts	Re-exports new Responses + refusal helper modules.
packages/ai/src/capability/StreamEventAccumulator.ts	Accumulates refusals into reserved output fields during materialization.
packages/test/src/test/ai/StreamEventAccumulator.test.ts	Adds unit tests for refusal accumulation semantics.
packages/test/src/test/ai-provider/OpenAIShapedResponses.test.ts	New tests for Responses input/tool shaping and typed stream adaptation (text/tool/refusal).
packages/test/src/test/ai-provider/CrossProviderRefusals.test.ts	New cross-provider refusal tests for OpenAI-chat, Anthropic, and Gemini signals.
packages/test/src/test/ai-provider-api/OpenAiProvider.test.ts	Adds tests for reasoning config, strict-schema compatibility, and prompt cache key derivation.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	62.68%	26409 / 42132
🔵	Statements	62.52%	27320 / 43698
🔵	Functions	63.46%	4967 / 7826
🔵	Branches	51.22%	13000 / 25376

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
scripts/lib/test-credentials.ts	90.62%	78.57%	100%	89.28%	94-99

Generated in workflow #2695 for commit 6e49702 by the Vitest Coverage Report Action

[sroussey]

Automated review — must-fix findings

Findings from an automated review of this PR: 2 HIGH.

H1 — Prompt-injection escalation via buildResponsesInput (packages/ai/src/provider-utils/OpenAIShapedResponses.ts).
The loop lifts every role: "system" | "developer" message into instructionParts, not just leading ones. A mid-conversation attacker-injected system turn from a partially-untrusted messages array (RAG-retrieved content, chat-history forwarding, tool outputs shaped as messages) is promoted into the Responses instructions channel — a strict privilege escalation vs. Chat Completions.

Fix:

• Track a liftingInstructions flag that flips false on the first user/assistant/tool message
• Only leading system/developer messages lift; subsequent ones demote to a defanged user-role turn ("[attempted mid-conversation system message, ignored]: …")
• Add regression tests with [system, user, system, user]

H2 — Structured-generation streaming path diverges from .execute() (packages/task-graph/src/task/StreamProcessor.ts finish handler interacting with StructuredGenerationTask.executeStream).
merged[port] = obj from the last accumulator object-delta overrides the run-fn's authoritative finish.data.object. .execute() returns the validated object; .run() returns the accumulator's last partial-parse snapshot. Cache writes store the divergent value.

Fix:

• In StructuredGenerationTask.executeStream, immediately before the successful finish, emit a terminal { type: "object-delta", port: "object", objectDelta: finalObject }
• Preserves delta-wins semantics for both accumulators
• Add a .run() vs .execute() parity regression test

— posted by scheduled review routine

---

Generated by Claude Code