Release 0.5.0

Author: slegarraga

CHANGELOG.md

@@ -6,13 +6,28 @@ 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 `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.
+  `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
 

README.md

@@ -88,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
 
@@ -102,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
 
@@ -175,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
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "llm-messages",
-  "version": "0.4.9",
+  "version": "0.5.0",
   "description": "Convert chat conversations and responses between OpenAI, Anthropic and Gemini. Tool calls, images, audio, documents and roles handled. Zero dependencies.",
   "keywords": [
     "openai",

package.json

@@ -37,7 +37,18 @@ export function toAnthropic(messages: OpenAIMessage[], options: ConvertOptions =
       let j = i;
       while (j < rest.length && rest[j].role === 'tool') {
         const tool = rest[j] as OpenAIToolMessage;
-        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 });
@@ -46,6 +57,7 @@ export function toAnthropic(messages: OpenAIMessage[], options: ConvertOptions =
     }
 
     if (message.role === 'user') {
+      warnDroppedName('User', message.name, 'Anthropic', reporter);
       out.push({ role: 'user', content: userContent(message.content, reporter) });
       continue;
     }
@@ -83,6 +95,7 @@ function userContent(content: string | OpenAIContentPart[], reporter: Reporter):
 }
 
 function assistantContent(message: OpenAIAssistantMessage, reporter: Reporter): string | AnthropicContentBlock[] {
+  warnDroppedName('Assistant', message.name, 'Anthropic', reporter);
   const text = textOf(message.content ?? '');
   const toolCalls = message.tool_calls ?? [];
   if (toolCalls.length === 0) return text;
@@ -100,6 +113,11 @@ function assistantContent(message: OpenAIAssistantMessage, reporter: Reporter):
   return blocks;
 }
 
+function warnDroppedName(role: string, name: string | undefined, provider: string, reporter: Reporter): void {
+  if (typeof name !== 'string') return;
+  reporter.warn('dropped-metadata', `${role} message name '${name}' has no ${provider} equivalent; dropped.`);
+}
+
 /** Merges adjacent same-role messages by concatenating their content blocks. */
 function mergeConsecutive(messages: AnthropicMessage[], reporter: Reporter): AnthropicMessage[] {
   const result: AnthropicMessage[] = [];
@@ -144,18 +162,36 @@ export function fromAnthropic(conversation: AnthropicConversation, options: Conv
     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: AnthropicContentBlock[] = [];
+      const flushContent = (): void => {
+        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 as { tool_use_id?: string }).tool_use_id ?? ''),
           content: textOf((block as { content?: unknown }).content),
+          ...(typeof (block as { is_error?: unknown }).is_error === 'boolean'
+            ? { is_error: (block as { is_error: boolean }).is_error }
+            : {}),
         });
       }
-      if (contentBlocks.length > 0) {
-        out.push({ role: 'user', content: userContentToOpenAI(contentBlocks, reporter) });
-      }
+      flushContent();
       continue;
     }
 

src/providers/anthropic.ts

@@ -48,7 +48,20 @@ export function toGemini(messages: OpenAIMessage[], options: ConvertOptions = {}
       let j = i;
       while (j < rest.length && rest[j].role === 'tool') {
         const tool = rest[j] as OpenAIToolMessage;
-        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',
@@ -70,10 +83,12 @@ export function toGemini(messages: OpenAIMessage[], options: ConvertOptions = {}
     }
 
     if (message.role === 'user') {
+      warnDroppedName('User', message.name, 'Gemini', reporter);
       contents.push({ role: 'user', parts: userParts(message.content, reporter) });
       continue;
     }
 
+    warnDroppedName('Assistant', message.name, 'Gemini', reporter);
     contents.push({ role: 'model', parts: assistantParts(message, reporter) });
   }
 
@@ -123,6 +138,11 @@ function assistantParts(message: OpenAIAssistantMessage, reporter: Reporter): Ge
   return parts.length > 0 ? parts : [{ text: '' }];
 }
 
+function warnDroppedName(role: string, name: string | undefined, provider: string, reporter: Reporter): void {
+  if (typeof name !== 'string') return;
+  reporter.warn('dropped-metadata', `${role} message name '${name}' has no ${provider} equivalent; dropped.`);
+}
+
 /** Merges adjacent same-role contents by concatenating their `parts` arrays. */
 function mergeConsecutive(contents: GeminiContent[], reporter: Reporter): GeminiContent[] {
   const result: GeminiContent[] = [];
@@ -196,8 +216,13 @@ export function fromGemini(conversation: GeminiConversation, options: ConvertOpt
     for (const part of parts) {
       if (isRecord(part) && isRecord(part.functionResponse)) {
         const fr = part.functionResponse as { id?: string; name: string; response?: Record<string, unknown> };
-        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);
@@ -224,7 +249,7 @@ export function fromGemini(conversation: GeminiConversation, options: ConvertOpt
         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 });
       }
     }
   }
@@ -237,22 +262,22 @@ function resolveResponseId(
   pending: { id: string; name: string }[],
   reporter: Reporter,
   generateId: (name: string) => string,
-): string {
+): { id: string; matched: boolean } {
   if (response.id) {
     const index = pending.findIndex((p) => p.id === response.id);
     if (index >= 0) pending.splice(index, 1);
-    return response.id;
+    return { id: response.id, matched: index >= 0 };
   }
   const index = pending.findIndex((p) => p.name === response.name);
   if (index >= 0) {
     const { id } = pending[index];
     pending.splice(index, 1);
-    return id;
+    return { id, 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/providers/gemini.ts

@@ -31,6 +31,12 @@ export function splitSystem(
 
   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',

src/providers/openai.ts

@@ -17,6 +17,7 @@ export type WarningCode =
   | 'unmapped-tool-result'
   | 'merged-role'
   | 'dropped-content'
+  | 'dropped-metadata'
   | 'invalid-json-arguments'
   | 'system-midstream'
   | 'gemini-url-image'
@@ -104,7 +105,11 @@ export interface OpenAIAssistantMessage {
 export interface OpenAIToolMessage {
   role: 'tool';
   tool_call_id: string;
+  /** Optional provider metadata used to preserve Gemini functionResponse names. */
+  name?: string;
   content: string | OpenAITextPart[];
+  /** Optional provider metadata used to preserve Anthropic tool_result errors. */
+  is_error?: boolean;
 }
 
 export type OpenAIMessage = OpenAISystemMessage | OpenAIUserMessage | OpenAIAssistantMessage | OpenAIToolMessage;

src/types.ts

@@ -42,6 +42,41 @@ describe('toAnthropic', () => {
     expect((userTurn.content as AnthropicContentBlock[]).map((b) => b.type)).toEqual(['tool_result', 'tool_result']);
   });
 
+  it('preserves tool_result error flags from canonical tool messages', () => {
+    const { messages } = toAnthropic([
+      { role: 'tool', tool_call_id: 't1', content: 'failed', is_error: true },
+      { role: 'tool', tool_call_id: 't2', content: 'ok', is_error: false },
+    ]);
+    const content = messages[0].content as AnthropicContentBlock[];
+    expect(content).toEqual([
+      { type: 'tool_result', tool_use_id: 't1', content: 'failed', is_error: true },
+      { type: 'tool_result', tool_use_id: 't2', content: 'ok', is_error: false },
+    ]);
+  });
+
+  it('reports OpenAI message metadata that Anthropic cannot represent', () => {
+    const warnings: Warning[] = [];
+    toAnthropic(
+      [
+        { role: 'system', name: 'policy', content: 'Be concise.' },
+        { role: 'user', name: 'customer', content: 'Hi' },
+        { role: 'assistant', name: 'planner', content: null },
+        { role: 'tool', tool_call_id: 'orphan', name: 'lookup_order', content: 'done' },
+      ],
+      { onWarning: (w) => warnings.push(w) },
+    );
+
+    const messages = warnings.filter((w) => w.code === 'dropped-metadata').map((w) => w.message);
+    expect(messages).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining("system message name 'policy'"),
+        expect.stringContaining("User message name 'customer'"),
+        expect.stringContaining("Assistant message name 'planner'"),
+        expect.stringContaining("Tool message name 'lookup_order'"),
+      ]),
+    );
+  });
+
   it('reports invalid tool-call arguments instead of throwing', () => {
     const warnings: Warning[] = [];
     toAnthropic(
@@ -73,4 +108,41 @@ describe('fromAnthropic', () => {
     });
     expect(out).toEqual([{ role: 'tool', tool_call_id: 't1', content: 'result' }]);
   });
+
+  it('preserves mixed user text, tool_result errors and block order', () => {
+    const out = fromAnthropic({
+      messages: [
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: 'before' },
+            { type: 'tool_result', tool_use_id: 't1', content: 'failed', is_error: true },
+            { type: 'text', text: 'after' },
+          ],
+        },
+      ],
+    });
+    expect(out).toEqual([
+      { role: 'user', content: 'before' },
+      { role: 'tool', tool_call_id: 't1', content: 'failed', is_error: true },
+      { role: 'user', content: 'after' },
+    ]);
+  });
+
+  it('round trips mixed text and tool_result blocks back to one Anthropic user turn', () => {
+    const conversation = {
+      messages: [
+        {
+          role: 'user' as const,
+          content: [
+            { type: 'text' as const, text: 'before' },
+            { type: 'tool_result' as const, tool_use_id: 't1', content: 'failed', is_error: true },
+            { type: 'text' as const, text: 'after' },
+          ],
+        },
+      ],
+    };
+
+    expect(toAnthropic(fromAnthropic(conversation)).messages).toEqual(conversation.messages);
+  });
 });