fix(server-utils): Map Flue messages to the gen_ai conventions

Flue records its turn messages in pi-ai's shape, with a `toolResult` role
and `toolCall` parts. Sentry renders neither, so tool calls and tool
results were missing from the conversation views, and images were
recorded as base64. A shared pi-ai mapper now translates them to the
conventions, as the Google GenAI integration does.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Author: JPeer264

packages/server-utils/src/ai/flue/utils.ts

@@ -39,6 +39,7 @@ import {
   SERVER_PORT,
 } from '@sentry/conventions/attributes';
 import { getGenAiSpanOp } from '../core/utils';
+import { piAiAssistantMessageToGenAiMessage, piAiMessagesToGenAiMessages } from '../pi-ai/messages';
 import { FLUE_ORIGIN, MAX_TRACKED_FLUE_SPANS } from './constants';
 import type { FlueErrorInfo, FlueModelRequestInfo, FlueObservation, FlueUsage } from './types';
 
@@ -173,9 +174,11 @@ export function endTurnSpan(observation: FlueObservation, turnSpans: SpanTracker
     span.setAttribute(GEN_AI_RESPONSE_FINISH_REASONS, stringify([finishReason]));
   }
 
-  const output = observation.response?.output;
-  if (recordOutputs && output !== undefined) {
-    span.setAttribute(GEN_AI_OUTPUT_MESSAGES, stringify(output));
+  const output = recordOutputs
+    ? piAiAssistantMessageToGenAiMessage(observation.response?.output, finishReason)
+    : undefined;
+  if (output) {
+    span.setAttribute(GEN_AI_OUTPUT_MESSAGES, stringify([output]));
   }
 
   setUsageAttributes(span, observation.response?.usage, observation.isError);
@@ -283,8 +286,9 @@ export function recordRequestContent(observation: FlueObservation, turnSpans: Sp
   if (input.systemPrompt) {
     span.setAttribute(GEN_AI_SYSTEM_INSTRUCTIONS, input.systemPrompt);
   }
-  if (input.messages) {
-    span.setAttribute(GEN_AI_INPUT_MESSAGES, stringify(input.messages));
+  const messages = piAiMessagesToGenAiMessages(input.messages);
+  if (messages.length) {
+    span.setAttribute(GEN_AI_INPUT_MESSAGES, stringify(messages));
   }
   if (input.tools?.length) {
     span.setAttribute(GEN_AI_TOOL_DEFINITIONS, stringify(input.tools));

packages/server-utils/src/ai/pi-ai/messages.ts

@@ -0,0 +1,99 @@
+import { isObjectLike, stringify } from '@sentry/core';
+
+/** A message in the gen_ai conventions shape, see https://develop.sentry.dev/sdk/telemetry/traces/modules/ai-agents/. */
+export interface GenAiMessage {
+  role: string;
+  parts: GenAiMessagePart[];
+  finish_reason?: string;
+}
+
+export type GenAiMessagePart = Record<string, unknown> & { type: string };
+
+/**
+ * Map pi-ai messages (`@earendil-works/pi-ai`, which Flue and pi-durable send) to the gen_ai
+ * conventions. Sentry renders neither pi-ai's `toolResult` role nor its `toolCall` parts.
+ *
+ * System messages are left out: their prompt belongs in `gen_ai.system_instructions`.
+ */
+export function piAiMessagesToGenAiMessages(messages: unknown): GenAiMessage[] {
+  if (!Array.isArray(messages)) {
+    return [];
+  }
+
+  const mapped: GenAiMessage[] = [];
+  for (const message of messages) {
+    if (!isObjectLike(message) || typeof message.role !== 'string' || message.role === 'system') {
+      continue;
+    }
+
+    if (message.role === 'toolResult') {
+      mapped.push({
+        role: 'tool',
+        parts: [
+          {
+            type: 'tool_call_response',
+            id: message.toolCallId,
+            name: message.toolName,
+            result: piAiContentToString(message.content),
+          },
+        ],
+      });
+      continue;
+    }
+
+    const parts = piAiContentToParts(message.content);
+    if (parts.length) {
+      mapped.push({ role: message.role, parts });
+    }
+  }
+  return mapped;
+}
+
+/** The `gen_ai.output.messages` entry of a pi-ai assistant message, or `undefined` when it has no content. */
+export function piAiAssistantMessageToGenAiMessage(message: unknown, finishReason?: string): GenAiMessage | undefined {
+  const parts = isObjectLike(message) ? piAiContentToParts(message.content) : [];
+  if (!parts.length) {
+    return undefined;
+  }
+  return { role: 'assistant', parts, ...(finishReason ? { finish_reason: finishReason } : {}) };
+}
+
+/** Text-only content as its text, joined the way pi-ai joins it; anything else as its mapped parts. */
+export function piAiContentToString(content: unknown): string | undefined {
+  const parts = piAiContentToParts(content);
+  return parts.every(part => part.type === 'text') ? parts.map(part => part.content).join('\n') : stringify(parts);
+}
+
+function piAiContentToParts(content: unknown): GenAiMessagePart[] {
+  if (typeof content === 'string') {
+    return content ? [{ type: 'text', content }] : [];
+  }
+  if (!Array.isArray(content)) {
+    return [];
+  }
+  return content.map(piAiPartToGenAiPart).filter((part): part is GenAiMessagePart => part !== undefined);
+}
+
+/** An image is reported by its media type only: its `data` is base64, which the conventions require to be dropped. */
+function piAiPartToGenAiPart(part: unknown): GenAiMessagePart | undefined {
+  if (!isObjectLike(part)) {
+    return undefined;
+  }
+
+  switch (part.type) {
+    case 'text':
+      return typeof part.text === 'string' ? { type: 'text', content: part.text } : undefined;
+    case 'thinking':
+      // A redacted thinking block carries an encrypted payload, not text.
+      return typeof part.thinking === 'string' && part.thinking && !part.redacted
+        ? { type: 'reasoning', content: part.thinking }
+        : undefined;
+    case 'toolCall':
+      return { type: 'tool_call', id: part.id, name: part.name, arguments: stringify(part.arguments ?? {}, String) };
+    case 'image':
+      return { type: 'blob', mime_type: part.mimeType };
+    default:
+      // Part kinds we don't know yet render as JSON rather than disappearing.
+      return { type: 'object', content: part };
+  }
+}

packages/server-utils/test/ai/lib/tracing/flue.test.ts

@@ -404,7 +404,15 @@ describe('createFlueInstrumentation', () => {
       await instr.interceptor(AGENT_OP, AGENT_CTX, async () => {
         instr.observe({ type: 'turn_start', turnId: 'turn_1', operationId: 'op_1' }, {});
         instr.observe(requestContent, {});
-        instr.observe(turn({ response: { ...turn().response, output: { role: 'assistant' } } }), {});
+        instr.observe(
+          turn({
+            response: {
+              ...turn().response,
+              output: { role: 'assistant', content: [{ type: 'text', text: 'It is sunny.' }] },
+            },
+          }),
+          {},
+        );
         instr.observe(
           {
             type: 'tool_start',
@@ -427,8 +435,11 @@ describe('createFlueInstrumentation', () => {
 
       const chat = findSpan('chat claude-haiku-4.5');
       expect(chat?.data['gen_ai.system_instructions']).toBe('You are helpful.');
-      expect(chat?.data['gen_ai.input.messages']).toContain('"role":"user"');
-      expect(chat?.data['gen_ai.output.messages']).toContain('"role":"assistant"');
+      // Mapped from pi-ai's message shape to the conventions, which is what Sentry renders.
+      expect(chat?.data['gen_ai.input.messages']).toBe('[{"role":"user","parts":[{"type":"text","content":"hi"}]}]');
+      expect(chat?.data['gen_ai.output.messages']).toBe(
+        '[{"role":"assistant","parts":[{"type":"text","content":"It is sunny."}],"finish_reason":"stop"}]',
+      );
       expect(chat?.data['gen_ai.tool.definitions']).toContain('get_weather');
 
       const tool = findSpan('execute_tool get_weather');

packages/server-utils/test/ai/lib/utils/pi-ai-messages.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it } from 'vitest';
+import {
+  piAiAssistantMessageToGenAiMessage,
+  piAiContentToString,
+  piAiMessagesToGenAiMessages,
+} from '../../../../src/ai/pi-ai/messages';
+
+describe('convert pi-ai messages to gen_ai messages', () => {
+  it('maps user, assistant and tool result messages', () => {
+    expect(
+      piAiMessagesToGenAiMessages([
+        { role: 'user', content: 'Weather in Vienna?', timestamp: 1 },
+        {
+          role: 'assistant',
+          content: [
+            { type: 'thinking', thinking: 'The user wants the weather.' },
+            { type: 'text', text: 'Let me check.' },
+            { type: 'toolCall', id: 'call_1', name: 'get_weather', arguments: { city: 'Vienna' } },
+          ],
+          stopReason: 'toolUse',
+        },
+        {
+          role: 'toolResult',
+          toolCallId: 'call_1',
+          toolName: 'get_weather',
+          content: [{ type: 'text', text: 'Sunny in Vienna.' }],
+          isError: false,
+        },
+      ]),
+    ).toStrictEqual([
+      { role: 'user', parts: [{ type: 'text', content: 'Weather in Vienna?' }] },
+      {
+        role: 'assistant',
+        parts: [
+          { type: 'reasoning', content: 'The user wants the weather.' },
+          { type: 'text', content: 'Let me check.' },
+          { type: 'tool_call', id: 'call_1', name: 'get_weather', arguments: '{"city":"Vienna"}' },
+        ],
+      },
+      {
+        role: 'tool',
+        parts: [{ type: 'tool_call_response', id: 'call_1', name: 'get_weather', result: 'Sunny in Vienna.' }],
+      },
+    ]);
+  });
+
+  it('reports images by media type and drops their base64 data', () => {
+    expect(
+      piAiMessagesToGenAiMessages([
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: 'What is this?' },
+            { type: 'image', data: 'iVBORw0KGgo=', mimeType: 'image/png' },
+          ],
+        },
+      ]),
+    ).toStrictEqual([
+      {
+        role: 'user',
+        parts: [
+          { type: 'text', content: 'What is this?' },
+          { type: 'blob', mime_type: 'image/png' },
+        ],
+      },
+    ]);
+  });
+
+  it('leaves out system messages, redacted thinking and messages without content', () => {
+    expect(
+      piAiMessagesToGenAiMessages([
+        { role: 'system', content: '', sections: { preamble: 'You are helpful.' } },
+        { role: 'assistant', content: [{ type: 'thinking', thinking: 'c2VjcmV0', redacted: true }] },
+        { role: 'user', content: '' },
+        'not a message',
+      ]),
+    ).toStrictEqual([]);
+  });
+
+  it('keeps unknown part kinds as objects', () => {
+    expect(piAiMessagesToGenAiMessages([{ role: 'user', content: [{ type: 'audio', url: 'a.mp3' }] }])).toStrictEqual([
+      { role: 'user', parts: [{ type: 'object', content: { type: 'audio', url: 'a.mp3' } }] },
+    ]);
+  });
+
+  it('maps an assistant message to an output message with its finish reason', () => {
+    expect(
+      piAiAssistantMessageToGenAiMessage(
+        {
+          role: 'assistant',
+          content: [{ type: 'toolCall', id: 'call_1', name: 'get_weather', arguments: { city: 'Vienna' } }],
+        },
+        'tool_call',
+      ),
+    ).toStrictEqual({
+      role: 'assistant',
+      parts: [{ type: 'tool_call', id: 'call_1', name: 'get_weather', arguments: '{"city":"Vienna"}' }],
+      finish_reason: 'tool_call',
+    });
+    expect(piAiAssistantMessageToGenAiMessage({ role: 'assistant', content: [] }, 'stop')).toBeUndefined();
+  });
+
+  it('renders text-only content as text and other content as mapped parts', () => {
+    expect(
+      piAiContentToString([
+        { type: 'text', text: 'line 1' },
+        { type: 'text', text: 'line 2' },
+      ]),
+    ).toBe('line 1\nline 2');
+    expect(piAiContentToString([{ type: 'image', data: 'iVBORw0KGgo=', mimeType: 'image/png' }])).toBe(
+      '[{"type":"blob","mime_type":"image/png"}]',
+    );
+  });
+});