feat(responses): pad shape for openresponses spec

[RATCHAW]

Summary

Pads the /v1/responses API output to satisfy the Open Responses spec’s ResponseResource required-fields list. Adds ~25 fields that were previously missing (tools, tool_choice, truncation, parallel_tool_calls, text.format, top_p, temperature, reasoning, completed_at, incomplete_details, store, background, service_tier, safety_identifier, prompt_cache_key, etc.) and always emits usage.input_tokens_details.cached_tokens and usage.output_tokens_details.reasoning_tokens.

Same padding applied to:

• non-streaming response (convertChatResponseToResponses)
• streaming response.created / response.completed / response.failed payloads
• GET /v1/responses/:id

Accepts the optional phase field on input messages.

Compatibility

Additive only. No existing fields removed or retyped. Standard JSON / OpenAI-SDK clients are unaffected.

Summary by CodeRabbit

• New Features

  • Responses API endpoints now return enriched payloads with echoed request parameters and comprehensive usage tracking.
  • Message inputs now support optional type and phase designation.
  • Streaming responses include more detailed token usage information.

• Tests

  • Added comprehensive compliance validation tests for response formats.

[coderabbitai]

Caution

Review failed

Failed to post review comments

Walkthrough

This PR introduces Open Responses API compliance by expanding response shapes and conversion logic. Schema definitions gain optional message item fields; conversion functions are reworked to accept a request parameter and populate expanded response structures with echoed fields, detailed usage, and metadata; streaming state is enriched to track request context; and comprehensive compliance tests validate the new shapes.

Changes

Open Responses API Compliance

Layer / File(s)	Summary
Data Shape apps/gateway/src/responses/schemas.ts	messageItemSchema gains optional type ("message") and phase ("commentary" | "final_answer") fields, expanding the ResponsesRequest shape.
Conversion Interfaces apps/gateway/src/responses/tools/convert-chat-to-responses.ts	New public interfaces ResponsesApiUsage, ResponsesApiResponse (with 20+ expanded fields), and ResponsesEchoRequest define the richer response contract and echo-back request subset.
Non-Streaming Conversion apps/gateway/src/responses/tools/convert-chat-to-responses.ts	convertChatResponseToResponses signature expanded to accept optional request parameter; usage construction switched to ResponsesApiUsage type with unconditional details; response payload now maps request-driven fields (instructions, tools, tool_choice, reasoning, etc.) and merges metadata.
Streaming Conversion apps/gateway/src/responses/tools/convert-streaming-to-responses.ts	createStreamingState signature updated to accept optional request; StreamingState gains request field and extended usage.output_tokens_details; new buildResponsePayload helper centralizes final response assembly; event builders (createResponseCreatedEvent, createCompletionEvents, createFailedEvent) refactored to use buildResponsePayload.
Endpoint Integration apps/gateway/src/responses/responses.ts	Request object now threaded to createStreamingState and convertChatResponseToResponses; GET /v1/responses/:response_id enriched to build fully-populated ResponsesApiResponse with derived created_at, status typing, detailed usage, and additional fields.
Tests & Compliance apps/gateway/src/responses/responses.spec.ts, apps/gateway/src/responses/openresponses-compliance.spec.ts	responses.spec.ts updated with non-null assertions for usage access; new comprehensive openresponses-compliance.spec.ts validates non-streaming and streaming shapes, function_call/message/reasoning outputs, incomplete statuses, request echoing, and alignment with upstream ResponseResource fixture.

Sequence Diagram

sequenceDiagram
    participant Client
    participant Gateway as /v1/responses
    participant Converter as convertChatResponseToResponses
    participant StreamState as createStreamingState
    participant StateBuilder as buildResponsePayload

    rect rgba(100, 150, 200, 0.5)
        Note over Client,StateBuilder: Non-Streaming Path
        Client->>Gateway: POST with chat completion + request fields
        Gateway->>Converter: convertChatResponseToResponses(chatResp, responseId, request)
        Converter->>Converter: Extract created timestamp
        Converter->>Converter: Build ResponsesApiUsage with details
        Converter->>Converter: Map echo fields from request
        Converter-->>Gateway: ResponsesApiResponse
        Gateway-->>Client: Response with echoed fields + usage details
    end

    rect rgba(150, 200, 100, 0.5)
        Note over Client,StateBuilder: Streaming Path
        Client->>Gateway: POST stream with chat completion + request fields
        Gateway->>StreamState: createStreamingState(model, responseId, request)
        StreamState-->>Gateway: StreamingState(request, usage)
        loop Stream chunks
            Gateway->>StateBuilder: buildResponsePayload(state, { status, output })
            StateBuilder->>StateBuilder: Merge state.request fields into payload
            StateBuilder->>StateBuilder: Populate usage with token details
            StateBuilder-->>Gateway: response.created/response.completed payload
            Gateway-->>Client: SSE event
        end
    end

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• theopenco/llmgateway#1983: Modifies how assistant message outputs are emitted/constructed in convert-chat-to-responses.ts.
• theopenco/llmgateway#2134: Updates Responses input/output schema and conversion logic, including handling of reasoning items and structured function_call_output.

Suggested reviewers

• steebchen
• smakosh

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 75.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(responses): pad shape for openresponses spec' clearly and concisely summarizes the main change: adding missing fields to the /v1/responses API output to comply with the Open Responses specification.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}