feat: normalize OpenAI Responses API output (#9)

Author: slegarraga

CHANGELOG.md

@@ -4,6 +4,16 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and this project adheres
 to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+
+- Added OpenAI Responses API response normalization via
+  `responseFromOpenAIResponses(...)` and `normalizeResponse(body, { from:
+  'openai-responses' })`, mapping `output_text` to assistant content,
+  `function_call` to Chat Completions-compatible `tool_calls`, and Responses
+  usage/status fields to neutral `usage` and `finishReason` values.
+
 ## [0.4.9] - 2026-06-04
 
 ### Added

README.md

@@ -110,20 +110,25 @@ The same idea applies to the read side. Normalize a provider's response body int
 a canonical OpenAI assistant message, plus a neutral finish reason and token usage:
 
 ```ts
-import { responseFromAnthropic, normalizeResponse } from 'llm-messages';
+import { responseFromAnthropic, responseFromOpenAIResponses, normalizeResponse } from 'llm-messages';
 
 const { message, finishReason, usage } = responseFromAnthropic(anthropicResponseBody);
 // message     -> { role: 'assistant', content, tool_calls? }  (tool input re-serialized to a JSON string)
 // finishReason -> 'stop' | 'tool_calls' | 'length' | 'content_filter' | 'unknown'
 // usage       -> { inputTokens, outputTokens }
 
+const responses = responseFromOpenAIResponses(openaiResponsesBody);
+// OpenAI Responses API `output_text` items become assistant `content`.
+// `function_call` items become Chat Completions-compatible `tool_calls`.
+
 // Or dispatch by provider:
 normalizeResponse(geminiResponseBody, { from: 'gemini' });
+normalizeResponse(openaiResponsesBody, { from: 'openai-responses' });
 ```
 
 `finishReason` is normalized to `tool_calls` whenever the model called a tool, even
-for Gemini (which reports `STOP`). Gemini tool calls without an id get a
-deterministic one.
+for Gemini (which reports `STOP`) and Responses API bodies with `function_call`
+items. Gemini tool calls without an id get a deterministic one.
 
 ## Format cheatsheet
 

ROADMAP.md

@@ -9,8 +9,9 @@ fallback behavior matter.
 
 1. **OpenAI Responses API coverage**
 
-   Track and test how Responses API text, multimodal and tool-call payloads map
-   to the current OpenAI Chat Completions-compatible hub shape.
+   Initial response normalization now maps Responses API `output_text` and
+   `function_call` items back into the current OpenAI Chat Completions-compatible
+   hub shape. Next: expand multimodal and streaming conformance fixtures.
 
    Public issue: https://github.com/slegarraga/llm-messages/issues/6
 

src/index.ts

@@ -5,8 +5,14 @@ export type { ConversationOf } from './convert.js';
 export { parseDataUrl, toDataUrl } from './image.js';
 export type { NormalizedImage } from './image.js';
 export type { MediaPart, MediaModality, MediaSource } from './media.js';
-export { responseFromOpenAI, responseFromAnthropic, responseFromGemini, normalizeResponse } from './response.js';
-export type { NormalizedResponse, FinishReason, Usage } from './response.js';
+export {
+  responseFromOpenAI,
+  responseFromOpenAIResponses,
+  responseFromAnthropic,
+  responseFromGemini,
+  normalizeResponse,
+} from './response.js';
+export type { NormalizedResponse, FinishReason, Usage, ResponseProvider } from './response.js';
 
 export type {
   Provider,

src/response.ts

@@ -58,6 +58,63 @@ export function responseFromOpenAI(body: unknown): NormalizedResponse {
   };
 }
 
+const OPENAI_RESPONSES_INCOMPLETE: Record<string, FinishReason> = {
+  max_output_tokens: 'length',
+  content_filter: 'content_filter',
+};
+
+function responseApiFinishReason(root: Record<string, unknown>): FinishReason {
+  if (root.status === 'completed') return 'stop';
+  if (root.status !== 'incomplete') return 'unknown';
+
+  const details = isRecord(root.incomplete_details) ? root.incomplete_details : {};
+  return OPENAI_RESPONSES_INCOMPLETE[String(details.reason)] ?? 'unknown';
+}
+
+/** Normalizes an OpenAI Responses API response body. */
+export function responseFromOpenAIResponses(body: unknown): NormalizedResponse {
+  const root = isRecord(body) ? body : {};
+  const output = Array.isArray(root.output) ? root.output : [];
+  const textPieces: string[] = [];
+  const toolCalls: OpenAIToolCall[] = [];
+  let counter = 0;
+
+  for (const item of output) {
+    if (!isRecord(item)) continue;
+
+    if (item.type === 'message') {
+      const content = Array.isArray(item.content) ? item.content : [];
+      for (const part of content) {
+        if (!isRecord(part)) continue;
+        if (typeof part.text === 'string' && (part.type === 'output_text' || part.type === 'text')) {
+          textPieces.push(part.text);
+        } else if (part.type === 'refusal' && typeof part.refusal === 'string') {
+          textPieces.push(part.refusal);
+        }
+      }
+    } else if (item.type === 'function_call' && typeof item.name === 'string') {
+      const name = item.name;
+      const id =
+        typeof item.call_id === 'string'
+          ? item.call_id
+          : typeof item.id === 'string'
+            ? item.id
+            : `call_${name.replace(/[^a-zA-Z0-9_-]/g, '_')}_${counter++}`;
+      const args = typeof item.arguments === 'string' ? item.arguments : JSON.stringify(item.arguments ?? {});
+      toolCalls.push({ id, type: 'function', function: { name, arguments: args } });
+    }
+  }
+
+  const usage = isRecord(root.usage) ? root.usage : {};
+  return {
+    message: buildMessage(textPieces.join(''), toolCalls),
+    finishReason: finalReason(responseApiFinishReason(root), toolCalls),
+    usage: { inputTokens: num(usage.input_tokens), outputTokens: num(usage.output_tokens) },
+  };
+}
+
+export type ResponseProvider = Provider | 'openai-responses';
+
 /* ------------------------------- Anthropic ----------------------------- */
 
 const ANTHROPIC_FINISH: Record<string, FinishReason> = {
@@ -147,12 +204,14 @@ export function responseFromGemini(body: unknown, options: ConvertOptions = {}):
 /** Normalizes a provider response body into the canonical shape. */
 export function normalizeResponse(
   body: unknown,
-  route: { from: Provider },
+  route: { from: ResponseProvider },
   options: ConvertOptions = {},
 ): NormalizedResponse {
   switch (route.from) {
     case 'openai':
       return responseFromOpenAI(body);
+    case 'openai-responses':
+      return responseFromOpenAIResponses(body);
     case 'anthropic':
       return responseFromAnthropic(body);
     case 'gemini':

test/response.test.ts

@@ -1,5 +1,11 @@
 import { describe, it, expect } from 'vitest';
-import { responseFromOpenAI, responseFromAnthropic, responseFromGemini, normalizeResponse } from '../src/index.ts';
+import {
+  responseFromOpenAI,
+  responseFromOpenAIResponses,
+  responseFromAnthropic,
+  responseFromGemini,
+  normalizeResponse,
+} from '../src/index.ts';
 import type { Warning } from '../src/index.ts';
 
 describe('responseFromOpenAI', () => {
@@ -28,6 +34,55 @@ describe('responseFromOpenAI', () => {
   });
 });
 
+describe('responseFromOpenAIResponses', () => {
+  it('collects output_text items, function calls, finish reason and usage', () => {
+    const r = responseFromOpenAIResponses({
+      object: 'response',
+      status: 'completed',
+      output: [
+        {
+          type: 'message',
+          role: 'assistant',
+          content: [{ type: 'output_text', text: 'Checking.' }],
+        },
+        {
+          type: 'function_call',
+          call_id: 'call_weather',
+          name: 'get_weather',
+          arguments: '{"location":"Paris"}',
+        },
+      ],
+      usage: { input_tokens: 12, output_tokens: 6, total_tokens: 18 },
+    });
+
+    expect(r.message).toEqual({
+      role: 'assistant',
+      content: 'Checking.',
+      tool_calls: [
+        {
+          id: 'call_weather',
+          type: 'function',
+          function: { name: 'get_weather', arguments: '{"location":"Paris"}' },
+        },
+      ],
+    });
+    expect(r.finishReason).toBe('tool_calls');
+    expect(r.usage).toEqual({ inputTokens: 12, outputTokens: 6 });
+  });
+
+  it('maps incomplete max output token responses to length', () => {
+    const r = responseFromOpenAIResponses({
+      object: 'response',
+      status: 'incomplete',
+      incomplete_details: { reason: 'max_output_tokens' },
+      output: [{ type: 'message', role: 'assistant', content: [{ type: 'output_text', text: 'partial' }] }],
+    });
+
+    expect(r.message).toEqual({ role: 'assistant', content: 'partial' });
+    expect(r.finishReason).toBe('length');
+  });
+});
+
 describe('responseFromAnthropic', () => {
   it('collects text, serializes tool input, maps stop_reason and usage', () => {
     const r = responseFromAnthropic({
@@ -100,4 +155,13 @@ describe('normalizeResponse', () => {
     expect(r.message.content).toBe('hi');
     expect(r.finishReason).toBe('stop');
   });
+
+  it('dispatches OpenAI Responses API bodies explicitly', () => {
+    const r = normalizeResponse(
+      { object: 'response', status: 'completed', output: [{ type: 'message', content: [{ type: 'output_text', text: 'hi' }] }] },
+      { from: 'openai-responses' },
+    );
+    expect(r.message.content).toBe('hi');
+    expect(r.finishReason).toBe('stop');
+  });
 });