llm-messages 0.4.8 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,39 @@ 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]
+
+## [0.5.0] - 2026-06-07
+
+### Added
+
+- Added OpenAI Responses API response normalization via
+  `responseFromOpenAIResponses(...)` and explicit `normalizeResponse(...)`
+  routing, 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.
+- Preserved Anthropic `tool_result.is_error` as optional canonical tool-message
+  metadata across Anthropic round trips.
+- Preserved standalone Gemini `functionResponse.name` as optional canonical
+  tool-message metadata so orphaned tool results can convert back to Gemini
+  without using the result id as the function name.
+- Added `dropped-metadata` warnings for OpenAI message names and provider-only
+  tool result metadata that the selected target provider cannot represent.
+
+### Fixed
+
+- Kept empty user turns intact when round-tripping through Anthropic or Gemini.
+- Preserved mixed Anthropic user text and `tool_result` block order when
+  converting into canonical OpenAI-compatible messages and back.
+
+## [0.4.9] - 2026-06-04
+
+### Added
+
+- Added a public adoption guide for teams evaluating OpenAI-compatible provider
+  fallback, local validation, and production conversion checks.
+- Included the examples directory in the published npm package.
+
 ## [0.4.8] - 2026-06-04
 
 ### Changed

package/README.md

@@ -3,6 +3,7 @@
 [![npm version](https://img.shields.io/npm/v/llm-messages.svg)](https://www.npmjs.com/package/llm-messages)
 [![npm downloads](https://img.shields.io/npm/dm/llm-messages.svg)](https://www.npmjs.com/package/llm-messages)
 [![CI](https://github.com/slegarraga/llm-messages/actions/workflows/ci.yml/badge.svg)](https://github.com/slegarraga/llm-messages/actions/workflows/ci.yml)
+[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/slegarraga/llm-messages/badge)](https://scorecard.dev/viewer/?uri=github.com/slegarraga/llm-messages)
 [![license](https://img.shields.io/npm/l/llm-messages.svg)](./LICENSE)
 [![zero dependencies](https://img.shields.io/badge/dependencies-0-brightgreen.svg)](./package.json)
 
@@ -87,7 +88,10 @@ fromGemini(toGemini(messages)); // deep-equals the original `messages`
 
 Arguments are parsed and re-serialized, ids are preserved (and regenerated
 deterministically when a Gemini payload omits them), and parallel tool results
-are grouped into the single user turn each provider expects.
+are grouped into the single user turn each provider expects. Anthropic
+`tool_result.is_error` is preserved as optional canonical tool-message metadata;
+standalone Gemini `functionResponse.name` is also preserved so orphaned tool
+results can be sent back to Gemini without renaming the function to the id.
 
 ## Conversion report
 
@@ -101,7 +105,9 @@ toGemini(messages, {
 ```
 
 Warning codes: `generated-id`, `unmapped-tool-result`, `merged-role`,
-`dropped-content`, `invalid-json-arguments`, `system-midstream`.
+`dropped-content`, `dropped-metadata`, `invalid-json-arguments`,
+`system-midstream`, `gemini-url-image`, `gemini-url-media`,
+`unsupported-modality`.
 
 ## Reading responses
 
@@ -109,20 +115,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
 
@@ -169,7 +180,11 @@ dropped with an `unsupported-modality` warning. Documents convert across all thr
 
 Version 0.x covers text, system prompts, tool calls/results, images, audio and
 documents, which is the core of every agent loop. Unsupported parts are reported
-via `dropped-content` rather than failing.
+via `dropped-content` rather than failing. Provider-only fields are preserved
+only when the canonical OpenAI-compatible shape has an explicit optional
+metadata field for them, such as Anthropic `tool_result.is_error` and standalone
+Gemini `functionResponse.name`. When that metadata has no target-provider
+equivalent, conversion continues and reports `dropped-metadata`.
 
 ## Roadmap
 
@@ -179,6 +194,13 @@ cases. The [conformance fixtures plan](./docs/conformance-fixtures.md) describes
 how API credits should be used to refresh deterministic public fixtures without
 putting secrets in CI.
 
+For teams evaluating the package, the
+[adoption guide](./docs/adoption-guide.md) covers the OpenAI-compatible boundary,
+local validation and production checks.
+
+Security posture is tracked in [docs/security-posture.md](./docs/security-posture.md),
+including CodeQL, OpenSSF Scorecard, Dependabot and branch rules.
+
 ## Provider portability suite
 
 `llm-messages` is the conversation boundary in a small provider-portability

package/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
 

package/dist/index.cjs

@@ -28,6 +28,7 @@ __export(index_exports, {
   responseFromAnthropic: () => responseFromAnthropic,
   responseFromGemini: () => responseFromGemini,
   responseFromOpenAI: () => responseFromOpenAI,
+  responseFromOpenAIResponses: () => responseFromOpenAIResponses,
   toAnthropic: () => toAnthropic,
   toDataUrl: () => toDataUrl,
   toGemini: () => toGemini
@@ -280,6 +281,12 @@ function splitSystem(messages, reporter) {
   let started = false;
   for (const message of messages) {
     if (isSystem(message)) {
+      if (typeof message.name === "string") {
+        reporter.warn(
+          "dropped-metadata",
+          `${message.role} message name '${message.name}' has no top-level system prompt equivalent; dropped.`
+        );
+      }
       if (started) {
         reporter.warn(
           "system-midstream",
@@ -308,7 +315,18 @@ function toAnthropic(messages, options = {}) {
       let j = i;
       while (j < rest.length && rest[j].role === "tool") {
         const tool = rest[j];
-        blocks.push({ type: "tool_result", tool_use_id: tool.tool_call_id, content: textOf(tool.content) });
+        if (typeof tool.name === "string") {
+          reporter.warn(
+            "dropped-metadata",
+            `Tool message name '${tool.name}' has no Anthropic tool_result equivalent; dropped.`
+          );
+        }
+        blocks.push({
+          type: "tool_result",
+          tool_use_id: tool.tool_call_id,
+          content: textOf(tool.content),
+          ...typeof tool.is_error === "boolean" ? { is_error: tool.is_error } : {}
+        });
         j++;
       }
       out.push({ role: "user", content: blocks });
@@ -316,6 +334,7 @@ function toAnthropic(messages, options = {}) {
       continue;
     }
     if (message.role === "user") {
+      warnDroppedName("User", message.name, "Anthropic", reporter);
       out.push({ role: "user", content: userContent(message.content, reporter) });
       continue;
     }
@@ -349,6 +368,7 @@ function userContent(content, reporter) {
   return blocks;
 }
 function assistantContent(message, reporter) {
+  warnDroppedName("Assistant", message.name, "Anthropic", reporter);
   const text = textOf(message.content ?? "");
   const toolCalls = message.tool_calls ?? [];
   if (toolCalls.length === 0) return text;
@@ -364,6 +384,10 @@ function assistantContent(message, reporter) {
   }
   return blocks;
 }
+function warnDroppedName(role, name, provider, reporter) {
+  if (typeof name !== "string") return;
+  reporter.warn("dropped-metadata", `${role} message name '${name}' has no ${provider} equivalent; dropped.`);
+}
 function mergeConsecutive(messages, reporter) {
   const result = [];
   for (const message of messages) {
@@ -393,18 +417,31 @@ function fromAnthropic(conversation, options = {}) {
   for (const message of conversation.messages) {
     const blocks = asBlocks(message.content);
     if (message.role === "user") {
-      const toolResults = blocks.filter((b) => b.type === "tool_result");
-      const contentBlocks = blocks.filter((b) => b.type !== "tool_result");
-      for (const block of toolResults) {
+      if (blocks.length === 0) {
+        out.push({ role: "user", content: "" });
+        continue;
+      }
+      let contentBlocks = [];
+      const flushContent = () => {
+        if (contentBlocks.length > 0) {
+          out.push({ role: "user", content: userContentToOpenAI(contentBlocks, reporter) });
+          contentBlocks = [];
+        }
+      };
+      for (const block of blocks) {
+        if (block.type !== "tool_result") {
+          contentBlocks.push(block);
+          continue;
+        }
+        flushContent();
         out.push({
           role: "tool",
           tool_call_id: String(block.tool_use_id ?? ""),
-          content: textOf(block.content)
+          content: textOf(block.content),
+          ...typeof block.is_error === "boolean" ? { is_error: block.is_error } : {}
         });
       }
-      if (contentBlocks.length > 0) {
-        out.push({ role: "user", content: userContentToOpenAI(contentBlocks, reporter) });
-      }
+      flushContent();
       continue;
     }
     const text = textOf(blocks.filter((b) => b.type === "text"));
@@ -462,7 +499,20 @@ function toGemini(messages, options = {}) {
       let j = i;
       while (j < rest.length && rest[j].role === "tool") {
         const tool = rest[j];
-        const name = idToName.get(tool.tool_call_id);
+        const matchingName = idToName.get(tool.tool_call_id);
+        if (typeof tool.is_error === "boolean") {
+          reporter.warn(
+            "dropped-metadata",
+            `Tool message is_error=${tool.is_error} has no Gemini functionResponse equivalent; dropped.`
+          );
+        }
+        if (typeof tool.name === "string" && matchingName && tool.name !== matchingName) {
+          reporter.warn(
+            "dropped-metadata",
+            `Tool message name '${tool.name}' differs from matching tool call '${matchingName}'; used the tool-call function name for Gemini.`
+          );
+        }
+        const name = matchingName ?? tool.name;
         if (!name) {
           reporter.warn(
             "unmapped-tool-result",
@@ -483,9 +533,11 @@ function toGemini(messages, options = {}) {
       continue;
     }
     if (message.role === "user") {
+      warnDroppedName2("User", message.name, "Gemini", reporter);
       contents.push({ role: "user", parts: userParts(message.content, reporter) });
       continue;
     }
+    warnDroppedName2("Assistant", message.name, "Gemini", reporter);
     contents.push({ role: "model", parts: assistantParts(message, reporter) });
   }
   const merged = mergeConsecutive2(contents, reporter);
@@ -529,6 +581,10 @@ function assistantParts(message, reporter) {
   }
   return parts.length > 0 ? parts : [{ text: "" }];
 }
+function warnDroppedName2(role, name, provider, reporter) {
+  if (typeof name !== "string") return;
+  reporter.warn("dropped-metadata", `${role} message name '${name}' has no ${provider} equivalent; dropped.`);
+}
 function mergeConsecutive2(contents, reporter) {
   const result = [];
   for (const content of contents) {
@@ -583,8 +639,13 @@ function fromGemini(conversation, options = {}) {
     for (const part of parts) {
       if (isRecord(part) && isRecord(part.functionResponse)) {
         const fr = part.functionResponse;
-        const id = resolveResponseId(fr, pending, reporter, generateId);
-        out.push({ role: "tool", tool_call_id: id, content: unwrapResponse(fr.response ?? {}) });
+        const { id, matched } = resolveResponseId(fr, pending, reporter, generateId);
+        out.push({
+          role: "tool",
+          tool_call_id: id,
+          content: unwrapResponse(fr.response ?? {}),
+          ...matched ? {} : { name: fr.name }
+        });
         continue;
       }
       const image = imageFromGemini(part);
@@ -611,7 +672,7 @@ function fromGemini(conversation, options = {}) {
         out.push({ role: "user", content: contentParts });
       } else {
         const text = textOf(contentParts);
-        if (text) out.push({ role: "user", content: text });
+        out.push({ role: "user", content: text });
       }
     }
   }
@@ -621,20 +682,20 @@ function resolveResponseId(response, pending, reporter, generateId) {
   if (response.id) {
     const index2 = pending.findIndex((p) => p.id === response.id);
     if (index2 >= 0) pending.splice(index2, 1);
-    return response.id;
+    return { id: response.id, matched: index2 >= 0 };
   }
   const index = pending.findIndex((p) => p.name === response.name);
   if (index >= 0) {
     const { id: id2 } = pending[index];
     pending.splice(index, 1);
-    return id2;
+    return { id: id2, matched: true };
   }
   const id = generateId(response.name);
   reporter.warn(
     "unmapped-tool-result",
     `Gemini functionResponse for '${response.name}' had no matching call; generated '${id}'.`
   );
-  return id;
+  return { id, matched: false };
 }
 
 // src/convert.ts
@@ -697,6 +758,48 @@ function responseFromOpenAI(body) {
     usage: { inputTokens: num(usage.prompt_tokens), outputTokens: num(usage.completion_tokens) }
   };
 }
+var OPENAI_RESPONSES_INCOMPLETE = {
+  max_output_tokens: "length",
+  content_filter: "content_filter"
+};
+function responseApiFinishReason(root) {
+  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";
+}
+function responseFromOpenAIResponses(body) {
+  const root = isRecord(body) ? body : {};
+  const output = Array.isArray(root.output) ? root.output : [];
+  const textPieces = [];
+  const toolCalls = [];
+  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) }
+  };
+}
 var ANTHROPIC_FINISH = {
   end_turn: "stop",
   stop_sequence: "stop",
@@ -771,6 +874,8 @@ function normalizeResponse(body, route, options = {}) {
   switch (route.from) {
     case "openai":
       return responseFromOpenAI(body);
+    case "openai-responses":
+      return responseFromOpenAIResponses(body);
     case "anthropic":
       return responseFromAnthropic(body);
     case "gemini":
@@ -789,6 +894,7 @@ function normalizeResponse(body, route, options = {}) {
   responseFromAnthropic,
   responseFromGemini,
   responseFromOpenAI,
+  responseFromOpenAIResponses,
   toAnthropic,
   toDataUrl,
   toGemini