llm-messages 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -6,6 +6,128 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+## [0.5.2] - 2026-06-12
+
+### Summary
+
+- Added an offline conformance suite for OpenAI Chat Completions, OpenAI
+  Responses, Anthropic and Gemini edge cases around tool-call ids, arguments,
+  refusals and tool-result mapping.
+- Strengthened the release path with one local validation command, package
+  dry-run checks, installed ESM/CommonJS/type smoke tests and a Node 18 consumer
+  smoke in CI.
+- Documented the response-normalization helpers, stable warning-code export and
+  fixture workflow so users and maintainers can audit the supported portability
+  surface before publishing.
+
+### Changed
+
+- Added an offline conformance fixture harness and committed fixtures for
+  OpenAI Chat Completions, OpenAI Responses, Anthropic and Gemini request and
+  response conversions.
+- Covered deterministic id generation and reservation, duplicate provider ids,
+  malformed function names, invalid argument payloads, refusals, unsupported
+  OpenAI tool-call types, Anthropic `tool_result` mapping and Gemini
+  `functionResponse` matching.
+- Documented direct response normalizers, stable warning codes, Gemini id/name
+  matching, the fixture contract and inventory, roadmap distinctions,
+  contributor validation commands and release staging review steps.
+- Aligned the pull request checklist with the conformance fixture inventory
+  workflow so fixture changes are reviewed with their docs update.
+- Added `npm run check`, `pack:check` and `examples:check`, then aligned CI and
+  release validation around format, typecheck, lint, tests, build, examples,
+  pack dry-run and package smoke checks.
+- Added a CommonJS usage example and extended packaged examples to cover
+  response normalization and the `warningCodes` export.
+- Strengthened package smoke testing to install the packed tarball, exercise
+  ESM/CommonJS/types, run bundled examples, verify intentional public files,
+  reject private source/test/script/config leaks, validate package metadata and
+  inspect source maps and audit packaged Markdown file and heading-anchor links.
+- Added a fixture-backed self-test for the packaged Markdown link checker so the
+  smoke script verifies missing files, missing anchors and package-escaping links
+  before auditing the real tarball.
+- Exported, froze and documented the `warningCodes` runtime list from the
+  package root so tests and consumers can validate warning-code values against
+  the public API.
+- Tightened the conformance warning-code guard so stale public warning codes
+  fail tests if they are no longer emitted by the source.
+
+### Fixed
+
+- Drop Gemini `thought: true` (reasoning) response parts with a
+  `dropped-content` warning instead of mixing the model's reasoning text into
+  the canonical assistant content.
+- Preserve OpenAI Chat Completions refusal text and refusal content parts when
+  assistant `content` is empty or array-shaped.
+- Drop unsupported OpenAI Chat Completions `tool_calls[]` types with a
+  `dropped-content` warning instead of emitting malformed canonical function
+  calls.
+- Warn and continue when OpenAI Chat Completions `tool_calls` payloads or
+  entries are malformed instead of silently skipping provider output.
+- Normalize legacy OpenAI Chat Completions `message.function_call` responses
+  into canonical `tool_calls` with deterministic ids.
+- Warn and fall back to empty canonical arguments when OpenAI Chat Completions,
+  OpenAI Responses, Anthropic or Gemini tool-call argument payloads are
+  malformed JSON, JSON non-objects or explicit non-object provider-native
+  values.
+- Warn and fall back to empty canonical arguments when provider-native argument
+  objects cannot be JSON serialized.
+- Preserve malformed response-level tool calls from OpenAI Chat Completions,
+  OpenAI Responses, Anthropic and Gemini by substituting the same stable
+  fallback function name used by conversation converters.
+- Warn with `dropped-content` when OpenAI Chat Completions, OpenAI Responses,
+  Anthropic or Gemini response-level content parts are unsupported instead of
+  silently dropping provider output parts.
+- Warn with `dropped-content` when OpenAI Chat Completions, OpenAI Responses,
+  Anthropic or Gemini response normalizers receive malformed top-level response
+  bodies.
+- Warn with `dropped-content` when OpenAI Chat Completions, Anthropic or Gemini
+  response bodies omit or malform their primary output arrays instead of
+  silently returning an empty assistant message.
+- Warn with `dropped-content` when OpenAI Chat Completions response choices omit
+  or malform their assistant `message` object instead of silently dropping the
+  choice payload.
+- Warn with `dropped-content` when OpenAI Responses top-level `output[]` items
+  are malformed or unsupported instead of silently skipping provider output
+  items.
+- Treat whitespace-only, OpenAI-incompatible and longer-than-64-character
+  provider function names as malformed before emitting canonical tool calls.
+- Generate deterministic OpenAI tool-call ids for OpenAI Chat Completions,
+  OpenAI Responses, Anthropic and Gemini values that are omitted, empty or
+  non-string.
+- Reserve provider-supplied tool-call ids before generating fallbacks, avoid
+  generated-id collisions and regenerate duplicate provider-supplied ids with a
+  `generated-id` warning.
+- Preserve Gemini `functionResponse` behavior by preferring explicit ids,
+  warning on unmapped ids without consuming same-name pending calls, recovering
+  omitted or malformed names from id matches, ignoring non-string ids before
+  falling back by name and preserving mixed user text/result order.
+- Warn and fall back to an empty canonical tool result when Gemini
+  `functionResponse.response` payloads cannot be JSON serialized.
+- Map Gemini policy-blocked finish reasons, including blocklist, prohibited
+  content, SPII, Model Armor and image safety stops, to the neutral
+  `content_filter` finish reason instead of `unknown`.
+- Preserve empty canonical user turns, with `dropped-content` warnings, when
+  Anthropic or Gemini document URLs cannot be represented in OpenAI Chat
+  Completions content.
+- Use the tool-call id as the Gemini `functionResponse.name` fallback when a
+  standalone canonical tool message has an empty name.
+- Warn on Anthropic `tool_result.tool_use_id` values that are missing or do not
+  match a prior `tool_use`, generating deterministic canonical ids for missing
+  values while preserving explicit unmapped ids.
+- Regenerate later duplicate Anthropic `tool_result.tool_use_id` values when
+  they are explicit but do not match any prior `tool_use`.
+- Emit an empty Anthropic user string, not an empty content-block array, when
+  every OpenAI user content part is dropped as unsupported.
+- Reserve Anthropic `tool_result.tool_use_id` values before generating fallback
+  `tool_use` ids so explicit result references are not reused by id-less calls.
+
+## [0.5.1] - 2026-06-11
+
+### Changed
+
+- Published README download badge updates so the npm package page shows the refreshed 30-day download badge.
+
 ## [0.5.0] - 2026-06-07
 
 ### Added
@@ -102,7 +224,9 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - Audio and document content parts. Audio (OpenAI `input_audio`) converts between
   OpenAI and Gemini; Anthropic has no audio input, so audio is dropped with an
   `unsupported-modality` warning. Documents (OpenAI `file`, Anthropic `document`,
-  Gemini `inlineData` / `fileData`) convert across all three, base64 losslessly.
+  Gemini `inlineData`) convert across all three when base64-backed; OpenAI
+  `file_id` references map to Anthropic file sources and are dropped for Gemini
+  with an `unsupported-modality` warning.
   Adds the `MediaPart` type and `unsupported-modality` / `gemini-url-media`
   warning codes. (#5)
 

package/README.md

@@ -1,13 +1,16 @@
 # llm-messages
 
 [![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)
+[![npm downloads](https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2Fslegarraga%2Fllm-messages%2Fmain%2Fbadges%2Fnpm-downloads%2Fllm-messages.json)](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)
 
-Convert chat conversations between **OpenAI**, **Anthropic** and **Gemini** message formats. Tool calls, system prompts and roles handled correctly. Zero dependencies.
+Convert chat conversations between **OpenAI**, **Anthropic** and **Gemini**
+message formats, and normalize provider responses into the same
+OpenAI-compatible assistant shape. Tool calls, system prompts, roles and
+response metadata handled correctly. Zero dependencies.
 
 Switching an agent from one provider to another (or running fallback across providers) means rewriting the whole conversation, and the differences are subtle enough to break at runtime:
 
@@ -15,7 +18,8 @@ Switching an agent from one provider to another (or running fallback across prov
 - The assistant role is `assistant` in OpenAI and Anthropic but `model` in Gemini.
 - Tool-call arguments are a **JSON string** in OpenAI but a **parsed object** in Anthropic and Gemini.
 - Tool results are a standalone `role: "tool"` message in OpenAI, a `tool_result` block inside a user turn in Anthropic, and a `functionResponse` part in Gemini.
-- Gemini matches tool calls to results **by function name**, while OpenAI and Anthropic use ids.
+- Gemini can match tool calls to results **by id when present** or by function
+  name when ids are omitted, while OpenAI and Anthropic require ids.
 - Anthropic and Gemini reject consecutive same-role turns; OpenAI does not.
 
 `llm-messages` handles all of it. Write the conversation once, send it to any provider.
@@ -28,13 +32,19 @@ npm install llm-messages
 
 Requires Node 18+. Ships ESM and CommonJS with full TypeScript types.
 
+CommonJS consumers can import the same package root:
+
+```js
+const { toAnthropic, toGemini } = require('llm-messages');
+```
+
 ## Quick start
 
 ```ts
-import { toAnthropic, toGemini } from 'llm-messages';
+import { toAnthropic, toGemini, type OpenAIMessage } from 'llm-messages';
 
 // A normal OpenAI Chat Completions conversation
-const messages = [
+const messages: OpenAIMessage[] = [
   { role: 'system', content: 'You are a weather assistant.' },
   { role: 'user', content: "What's the weather in Paris?" },
 ];
@@ -47,7 +57,9 @@ const gemini = toGemini(messages);
 //      contents: [{ role: 'user', parts: [{ text: "What's the weather in Paris?" }] }] }
 ```
 
-## The canonical hub
+## API
+
+### The canonical hub
 
 OpenAI Chat Completions is the canonical format. Every conversion routes through
 it, so you get a function for each direction:
@@ -67,12 +79,14 @@ convert(anthropicBody, { from: 'anthropic', to: 'gemini' });
 `convert` is fully typed: the input and output shapes are inferred from the
 `from` and `to` providers.
 
-## Tool calls round trip losslessly
+### Tool calls round trip losslessly
 
 The hard part is tool use, and it survives a full round trip unchanged:
 
 ```ts
-const messages = [
+import { fromGemini, toGemini, type OpenAIMessage } from 'llm-messages';
+
+const messages: OpenAIMessage[] = [
   {
     role: 'assistant',
     content: null,
@@ -87,16 +101,19 @@ 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. Anthropic
+deterministically when a Gemini payload does not provide a non-empty string id), and
+parallel tool results 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.
+results can be sent back to Gemini without renaming the function to the id. When
+Anthropic includes `tool_result.tool_use_id` or Gemini includes
+`functionResponse.id`, it is matched before provider-specific fallback behavior.
 
-## Conversion report
+### Conversion report
 
-Conversions never throw on malformed input. Instead they make a deterministic
-choice and optionally report it, so you can surface or log what happened:
+When typed provider payloads contain malformed tool-call or media fields,
+conversions make a deterministic choice and optionally report it, so you can
+surface or log what happened:
 
 ```ts
 toGemini(messages, {
@@ -109,13 +126,22 @@ Warning codes: `generated-id`, `unmapped-tool-result`, `merged-role`,
 `system-midstream`, `gemini-url-image`, `gemini-url-media`,
 `unsupported-modality`.
 
-## Reading responses
+Consumers that validate fixture metadata or warning filters can import the same
+stable list from the package root as `warningCodes`.
+
+### Reading responses
 
 The same idea applies to the read side. Normalize a provider's response body into
 a canonical OpenAI assistant message, plus a neutral finish reason and token usage:
 
 ```ts
-import { responseFromAnthropic, responseFromOpenAIResponses, normalizeResponse } from 'llm-messages';
+import {
+  responseFromAnthropic,
+  responseFromGemini,
+  responseFromOpenAI,
+  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)
@@ -126,6 +152,12 @@ const responses = responseFromOpenAIResponses(openaiResponsesBody);
 // OpenAI Responses API `output_text` items become assistant `content`.
 // `function_call` items become Chat Completions-compatible `tool_calls`.
 
+const chat = responseFromOpenAI(openaiChatBody);
+// Chat Completions `choices[0].message.tool_calls` stay Chat Completions-compatible.
+
+const gemini = responseFromGemini(geminiResponseBody);
+// Gemini `functionCall` parts become assistant `tool_calls`.
+
 // Or dispatch by provider:
 normalizeResponse(geminiResponseBody, { from: 'gemini' });
 normalizeResponse(openaiResponsesBody, { from: 'openai-responses' });
@@ -133,9 +165,10 @@ normalizeResponse(openaiResponsesBody, { from: 'openai-responses' });
 
 `finishReason` is normalized to `tool_calls` whenever the model called a tool, even
 for Gemini (which reports `STOP`) and Responses API bodies with `function_call`
-items. Gemini tool calls without an id get a deterministic one.
+items. OpenAI Chat Completions, OpenAI Responses, Anthropic and Gemini tool
+calls without a non-empty string id get a deterministic one.
 
-## Format cheatsheet
+### Format cheatsheet
 
 |                  | OpenAI                   | Anthropic                        | Gemini                          |
 | ---------------- | ------------------------ | -------------------------------- | ------------------------------- |
@@ -144,15 +177,17 @@ items. Gemini tool calls without an id get a deterministic one.
 | Tool call        | `tool_calls[].function`  | `tool_use` block                 | `functionCall` part             |
 | Call arguments   | JSON string              | object (`input`)                 | object (`args`)                 |
 | Tool result      | `role: "tool"` message   | `tool_result` block in user turn | `functionResponse` part in user |
-| Match key        | `tool_call_id`           | `tool_use_id`                    | function `name` (id optional)   |
+| Match key        | `tool_call_id`           | `tool_use_id`                    | `id` when present, else `name`  |
 | Role alternation | not required             | strict                           | strict                          |
 
-## Images, audio and documents
+### Images, audio and documents
 
 Image parts convert across all three providers:
 
 ```ts
-const messages = [
+import { toAnthropic, toGemini, type OpenAIMessage } from 'llm-messages';
+
+const messages: OpenAIMessage[] = [
   {
     role: 'user',
     content: [
@@ -162,8 +197,11 @@ const messages = [
   },
 ];
 
-toAnthropic(messages); // -> { type: 'image', source: { type: 'base64', media_type: 'image/png', data: '...' } }
-toGemini(messages); //    -> { inlineData: { mimeType: 'image/png', data: '...' } }
+toAnthropic(messages).messages[0]?.content;
+// -> [{ type: 'text', ... }, { type: 'image', source: { type: 'base64', media_type: 'image/png', data: '...' } }]
+
+toGemini(messages).contents[0]?.parts;
+// -> [{ text: 'What is in this image?' }, { inlineData: { mimeType: 'image/png', data: '...' } }]
 ```
 
 Base64 data URLs round trip losslessly. A remote `https` URL maps to an Anthropic
@@ -171,28 +209,35 @@ Base64 data URLs round trip losslessly. A remote `https` URL maps to an Anthropi
 `gemini-url-image` warning, since Gemini may require the Files API for non-Google
 URIs.
 
+If you need to handle image payloads directly, `parseDataUrl` and `toDataUrl`
+are exported for the same base64 data URL shape used by the converters.
+
 **Audio** (`input_audio`) and **documents** (`file`, e.g. PDF) convert too. Audio
 moves between OpenAI and Gemini; Anthropic has no audio input, so an audio part is
-dropped with an `unsupported-modality` warning. Documents convert across all three
-(OpenAI `file`, Anthropic `document`, Gemini `inlineData`).
+dropped with an `unsupported-modality` warning. Base64 document payloads convert
+across all three providers (OpenAI `file`, Anthropic `document`, Gemini
+`inlineData`). OpenAI `file_id` document references map to Anthropic `file`
+sources; Gemini has no equivalent and drops them with `unsupported-modality`.
 
 ## Scope
 
 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. 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`.
+documents, which is the core of every agent loop. Unsupported or lossy parts are
+reported through stable warning codes such as `dropped-content`,
+`unsupported-modality` or provider-specific media warnings 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
 
 See [ROADMAP.md](./ROADMAP.md) for current maintenance priorities, including
-OpenAI Responses API coverage, live conformance fixtures and tool-call edge
-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.
+OpenAI Responses API coverage, offline conformance fixtures and tool-call edge
+cases. The [conformance fixtures guide](./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,

package/ROADMAP.md

@@ -15,11 +15,11 @@ fallback behavior matter.
 
    Public issue: https://github.com/slegarraga/llm-messages/issues/6
 
-2. **Live conformance fixtures**
+2. **Provider-backed fixture refreshes**
 
    Add provider-backed fixture generation for OpenAI, Anthropic and Gemini
-   payloads, keeping the committed test fixtures deterministic and safe to run
-   without API keys.
+   payloads, while keeping the committed conformance fixtures deterministic,
+   offline, and safe to run without API keys.
 
    Plan: [docs/conformance-fixtures.md](./docs/conformance-fixtures.md)
 

package/SECURITY.md

@@ -0,0 +1,24 @@
+# Security Policy
+
+## Supported versions
+
+The latest published `0.x` release receives security fixes.
+
+## Reporting a vulnerability
+
+Please report security issues privately rather than opening a public issue.
+
+- Use GitHub's [private vulnerability reporting](https://github.com/slegarraga/llm-messages/security/advisories/new), or
+- Email **sebastian@0a.cl** with the details.
+
+Include a description, a reproduction, and the impact. You can expect an initial
+response within a few days. Once a fix is released, we are happy to credit you in
+the advisory unless you prefer to remain anonymous.
+
+## Scope
+
+`llm-messages` has zero runtime dependencies and performs only in-memory data
+transformation: it does not make network requests, read or write files, or
+execute code from its input. The most relevant risks are denial of service from
+pathological input (for example, deeply nested structures). Reports along those
+lines are welcome.