Add MAPPING span tracing for tool toModelOutput transforms (#16347)

## Description

This PR adds observability tracing for tool `toModelOutput`
transformations by emitting a `MAPPING` span type. When a tool defines a
`toModelOutput` function and it executes successfully, a child span is
created to track the transformation of the tool result before it's
passed to the model.

### Changes Made

1. **New Span Type**: Added `MAPPING` span type to `SpanType` enum in
`observability/types/tracing.ts` to represent inline data transforms
between pipeline stages.

2. **New Attributes Interface**: Created `MappingAttributes` interface
to capture mapping-specific metadata:
   - `mappingType`: Identifier of the mapping (e.g., `toModelOutput`)
- `toolCallId`: Associated tool call ID when mapping operates on a tool
result

3. **Span Emission Logic**: Updated `llm-mapping-step.ts` to:
- Create a child `MAPPING` span when `toModelOutput` is defined and the
tool result is non-null
- Capture the tool result as span input and the transformed output as
span output
- Mark the span as errored if `toModelOutput` throws, then re-throw the
error
- Skip span creation if the tool has no `toModelOutput` or if the result
is null/undefined

4. **Comprehensive Tests**: Added four test cases covering:
   - Successful mapping span emission with correct attributes and output
   - No span emission when tool lacks `toModelOutput`
   - No span emission when tool result is null/undefined
   - Error handling when `toModelOutput` throws

## Related Issue(s)

Fixes #15486

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [ ] Documentation update
- [ ] Code refactoring
- [ ] Performance improvement
- [x] Test update

## Checklist

- [x] I have made corresponding changes to the documentation (if
applicable)
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] I have addressed all Coderabbit comments on this PR

https://claude.ai/code/session_018bEDqEtGS2XkdsqBjye6JC

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## ELI5

When a tool changes its result before the AI model sees it, the system
now records that transformation in traces so you can see both the
original tool output and what the model actually received.

## Overview

This PR adds observability for tool toModelOutput transformations by
introducing a MAPPING span type and emitting a child MAPPING span when a
tool defines toModelOutput and the tool result is non-null. The span
records the raw tool result as input and the transformed model-facing
output as span output, and marks the span errored if the transform
throws. No mapping span is created when toModelOutput is absent or the
tool result is null/undefined.

## Changes

- Added SpanType.MAPPING = 'mapping' and exported MappingAttributes in
packages/core/src/observability/types/tracing.ts to represent inline
data transforms and carry mapping-specific attributes (mappingType,
toolCallId).
- Updated
packages/core/src/loop/workflows/agentic-execution/llm-mapping-step.ts
to:
- create a child MAPPING span (EntityType.TOOL) when tool.toModelOutput
exists and the tool result is non-null,
- set span input to the raw tool result and end the span with the
transformed modelOutput,
- mark the span errored (endSpan: true) and re-throw if toModelOutput
throws,
- avoid creating a span when toModelOutput is undefined or tool result
is null/undefined,
- attach modelOutput into providerMetadata.mastra.modelOutput when
present.
- Added tests in
packages/core/src/loop/workflows/agentic-execution/llm-mapping-step.test.ts
covering:
- successful MAPPING span emission with expected attributes and output,
  - no span when the tool lacks toModelOutput,
  - no span when tool result is null/undefined,
- error handling when toModelOutput throws (span errored and error
re-thrown).
- Updated client SDK route types
(client-sdks/client-js/src/route-types.generated.ts) to include
'mapping' in relevant union types.
- Documented the change in the changeset (.changeset/loud-ads-double.md)
and regenerated client types as part of the commit.

## Issue Resolution

Addresses issue #15486 by capturing toModelOutput return values in
tracing so traces can distinguish "not invoked" vs "no-op" vs
"transformed" for tool-to-model mappings.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: epinzur

.changeset/loud-ads-double.md

@@ -0,0 +1,5 @@
+---
+'@mastra/core': patch
+---
+
+Tool `toModelOutput` invocations now emit a `MAPPING` tracing span, showing the transformed output the model receives.

client-sdks/client-js/src/route-types.generated.ts

@@ -11363,6 +11363,7 @@ export type GetObservabilityTraces_QueryParams = {
             | 'rag_vector_operation'
             | 'rag_action'
             | 'graph_action'
+            | 'mapping'
           )
         | undefined
       )
@@ -11528,7 +11529,8 @@ export type GetObservabilityTraces_Response = {
       | 'rag_embedding'
       | 'rag_vector_operation'
       | 'rag_action'
-      | 'graph_action';
+      | 'graph_action'
+      | 'mapping';
     /** Whether this is an event (point-in-time) vs a span (duration) */
     isEvent: boolean;
     /** When the span started */
@@ -11735,6 +11737,7 @@ export type GetObservabilityBranches_QueryParams = {
             | 'rag_vector_operation'
             | 'rag_action'
             | 'graph_action'
+            | 'mapping'
           )
         | undefined
       )
@@ -11901,7 +11904,8 @@ export type GetObservabilityBranches_Response = {
       | 'rag_embedding'
       | 'rag_vector_operation'
       | 'rag_action'
-      | 'graph_action';
+      | 'graph_action'
+      | 'mapping';
     /** Whether this is an event (point-in-time) vs a span (duration) */
     isEvent: boolean;
     /** When the span started */
@@ -12091,7 +12095,8 @@ export type GetObservabilityTracesTraceIdBranchesSpanId_Response = {
       | 'rag_embedding'
       | 'rag_vector_operation'
       | 'rag_action'
-      | 'graph_action';
+      | 'graph_action'
+      | 'mapping';
     /** Whether this is an event (point-in-time) vs a span (duration) */
     isEvent: boolean;
     /** When the span started */
@@ -12274,7 +12279,8 @@ export type GetObservabilityTracesTraceId_Response = {
       | 'rag_embedding'
       | 'rag_vector_operation'
       | 'rag_action'
-      | 'graph_action';
+      | 'graph_action'
+      | 'mapping';
     /** Whether this is an event (point-in-time) vs a span (duration) */
     isEvent: boolean;
     /** When the span started */
@@ -12451,7 +12457,8 @@ export type GetObservabilityTracesTraceIdLight_Response = {
       | 'rag_embedding'
       | 'rag_vector_operation'
       | 'rag_action'
-      | 'graph_action';
+      | 'graph_action'
+      | 'mapping';
     /** Whether this is an event (point-in-time) vs a span (duration) */
     isEvent: boolean;
     /** When the span started */
@@ -12549,7 +12556,8 @@ export type GetObservabilityTracesTraceIdSpansSpanId_Response = {
       | 'rag_embedding'
       | 'rag_vector_operation'
       | 'rag_action'
-      | 'graph_action';
+      | 'graph_action'
+      | 'mapping';
     /** Whether this is an event (point-in-time) vs a span (duration) */
     isEvent: boolean;
     /** When the span started */
@@ -12854,6 +12862,7 @@ export type GetObservabilityTracesTraceIdSpanIdScores_Response = {
           | 'rag_vector_operation'
           | 'rag_action'
           | 'graph_action'
+          | 'mapping'
         )
       | undefined;
     structuredOutput?: boolean | undefined;

packages/core/src/loop/workflows/agentic-execution/llm-mapping-step.test.ts

@@ -1195,4 +1195,198 @@ describe('createLLMMappingStep toModelOutput', () => {
     // toModelOutput should NOT be called for undefined results
     expect(toModelOutputMock).not.toHaveBeenCalled();
   });
+
+  // ---- MAPPING span coverage (issue #15486) ----
+
+  type MockChildSpan = {
+    createOptions: any;
+    endOptions?: any;
+    errorOptions?: any;
+    ended: boolean;
+    errored: boolean;
+    end: Mock;
+    error: Mock;
+  };
+
+  function createMockParentSpan() {
+    const childSpans: MockChildSpan[] = [];
+    const parentSpan: any = {
+      createChildSpan: vi.fn((opts: any) => {
+        const child: MockChildSpan = {
+          createOptions: opts,
+          ended: false,
+          errored: false,
+          end: vi.fn(),
+          error: vi.fn(),
+        };
+        child.end = vi.fn((endOpts: any) => {
+          child.endOptions = endOpts;
+          child.ended = true;
+        }) as any;
+        child.error = vi.fn((errOpts: any) => {
+          child.errorOptions = errOpts;
+          child.errored = true;
+        }) as any;
+        childSpans.push(child);
+        return child;
+      }),
+    };
+    return { parentSpan, childSpans };
+  }
+
+  it('should emit a MAPPING child span when toModelOutput is defined and runs', async () => {
+    const { parentSpan, childSpans } = createMockParentSpan();
+    const toModelOutputMock = vi.fn((output: any) => ({ type: 'text', value: output.temperature }));
+
+    const llmMappingStep = createLLMMappingStep(
+      {
+        models: {} as any,
+        controller,
+        messageList,
+        runId: 'test-run',
+        _internal: { generateId: () => 'test-message-id' },
+        tools: {
+          weather: {
+            execute: async () => ({ temperature: 72 }),
+            toModelOutput: toModelOutputMock,
+            inputSchema: z.object({}),
+          },
+        },
+        modelSpanTracker: {
+          getTracingContext: () => ({ currentSpan: parentSpan }),
+        },
+      } as any,
+      llmExecutionStep,
+    );
+
+    const inputData: ToolCallOutput[] = [
+      { toolCallId: 'call-1', toolName: 'weather', args: {}, result: { temperature: 72 } },
+    ];
+
+    await llmMappingStep.execute(createExecuteParams(inputData));
+
+    expect(parentSpan.createChildSpan).toHaveBeenCalledTimes(1);
+    expect(childSpans).toHaveLength(1);
+    const [span] = childSpans;
+    expect(span.createOptions).toMatchObject({
+      type: 'mapping',
+      name: "tool output mapping: 'weather'",
+      entityType: 'tool',
+      entityId: 'weather',
+      entityName: 'weather',
+      input: { temperature: 72 },
+      attributes: {
+        mappingType: 'toModelOutput',
+        toolCallId: 'call-1',
+      },
+    });
+    expect(span.ended).toBe(true);
+    expect(span.endOptions).toEqual({ output: { type: 'text', value: 72 } });
+    expect(span.errored).toBe(false);
+  });
+
+  it('should NOT emit a MAPPING span when the tool has no toModelOutput', async () => {
+    const { parentSpan, childSpans } = createMockParentSpan();
+
+    const llmMappingStep = createLLMMappingStep(
+      {
+        models: {} as any,
+        controller,
+        messageList,
+        runId: 'test-run',
+        _internal: { generateId: () => 'test-message-id' },
+        tools: {
+          plain: {
+            execute: async () => ({ temperature: 72 }),
+            inputSchema: z.object({}),
+          },
+        },
+        modelSpanTracker: {
+          getTracingContext: () => ({ currentSpan: parentSpan }),
+        },
+      } as any,
+      llmExecutionStep,
+    );
+
+    const inputData: ToolCallOutput[] = [
+      { toolCallId: 'call-1', toolName: 'plain', args: {}, result: { temperature: 72 } },
+    ];
+
+    await llmMappingStep.execute(createExecuteParams(inputData));
+
+    expect(parentSpan.createChildSpan).not.toHaveBeenCalled();
+    expect(childSpans).toHaveLength(0);
+  });
+
+  it('should NOT emit a MAPPING span when tool result is null/undefined even if toModelOutput is defined', async () => {
+    const { parentSpan, childSpans } = createMockParentSpan();
+
+    const llmMappingStep = createLLMMappingStep(
+      {
+        models: {} as any,
+        controller,
+        messageList,
+        runId: 'test-run',
+        _internal: { generateId: () => 'test-message-id' },
+        tools: {
+          hitlTool: {
+            toModelOutput: vi.fn(),
+            inputSchema: z.object({}),
+          },
+        },
+        modelSpanTracker: {
+          getTracingContext: () => ({ currentSpan: parentSpan }),
+        },
+      } as any,
+      llmExecutionStep,
+    );
+
+    const inputData: ToolCallOutput[] = [{ toolCallId: 'call-1', toolName: 'hitlTool', args: {}, result: undefined }];
+
+    await llmMappingStep.execute(createExecuteParams(inputData));
+
+    expect(parentSpan.createChildSpan).not.toHaveBeenCalled();
+    expect(childSpans).toHaveLength(0);
+  });
+
+  it('should mark the MAPPING span as errored and re-throw when toModelOutput throws', async () => {
+    const { parentSpan, childSpans } = createMockParentSpan();
+    const failure = new Error('transform failed');
+    const toModelOutputMock = vi.fn(() => {
+      throw failure;
+    });
+
+    const llmMappingStep = createLLMMappingStep(
+      {
+        models: {} as any,
+        controller,
+        messageList,
+        runId: 'test-run',
+        _internal: { generateId: () => 'test-message-id' },
+        tools: {
+          broken: {
+            execute: async () => ({ data: 'raw' }),
+            toModelOutput: toModelOutputMock,
+            inputSchema: z.object({}),
+          },
+        },
+        modelSpanTracker: {
+          getTracingContext: () => ({ currentSpan: parentSpan }),
+        },
+      } as any,
+      llmExecutionStep,
+    );
+
+    const inputData: ToolCallOutput[] = [
+      { toolCallId: 'call-1', toolName: 'broken', args: {}, result: { data: 'raw' } },
+    ];
+
+    await expect(llmMappingStep.execute(createExecuteParams(inputData))).rejects.toBe(failure);
+
+    expect(childSpans).toHaveLength(1);
+    const [span] = childSpans;
+    expect(span.ended).toBe(false);
+    expect(span.errored).toBe(true);
+    expect(span.errorOptions).toEqual({ error: failure, endSpan: true });
+  });
 });

packages/core/src/loop/workflows/agentic-execution/llm-mapping-step.ts

@@ -1,7 +1,7 @@
 import type { ToolSet } from '@internal/ai-sdk-v5';
 import { z } from 'zod/v4';
 import { sanitizeToolName } from '../../../agent/message-list/utils/tool-name';
-import { createObservabilityContext } from '../../../observability';
+import { createObservabilityContext, EntityType, SpanType } from '../../../observability';
 import type { ProcessorState } from '../../../processors';
 import { ProcessorRunner } from '../../../processors/runner';
 import type { ChunkType, ProviderMetadata } from '../../../stream/types';
@@ -108,9 +108,13 @@ export function createLLMMappingStep<Tools extends ToolSet = ToolSet, OUTPUT = u
        *
        * Looks up the tool from dynamically loaded tools (`_internal.stepTools`, e.g. via
        * ToolSearchProcessor) first, then falls back to the agent's static tool definitions.
+       *
+       * When toModelOutput is defined, the transform runs under a MAPPING child span so
+       * traces can distinguish "never invoked" from "ran no-op" from "ran transforming."
        */
       async function getProviderMetadataWithModelOutput(toolCall: {
         toolName: string;
+        toolCallId?: string;
         result?: unknown;
         providerMetadata?: Record<string, unknown>;
       }) {
@@ -121,7 +125,26 @@ export function createLLMMappingStep<Tools extends ToolSet = ToolSet, OUTPUT = u
           | undefined;
         let modelOutput: unknown;
         if (tool?.toModelOutput && toolCall.result != null) {
-          modelOutput = await tool.toModelOutput(toolCall.result);
+          const parentSpan = observabilityContext?.tracingContext?.currentSpan;
+          const mappingSpan = parentSpan?.createChildSpan({
+            type: SpanType.MAPPING,
+            name: `tool output mapping: '${toolCall.toolName}'`,
+            entityType: EntityType.TOOL,
+            entityId: toolCall.toolName,
+            entityName: toolCall.toolName,
+            input: toolCall.result,
+            attributes: {
+              mappingType: 'toModelOutput',
+              toolCallId: toolCall.toolCallId,
+            },
+          });
+          try {
+            modelOutput = await tool.toModelOutput(toolCall.result);
+            mappingSpan?.end({ output: modelOutput });
+          } catch (err) {
+            mappingSpan?.error({ error: err as Error, endSpan: true });
+            throw err;
+          }
         }
 
         const existingMastra = (toolCall.providerMetadata as any)?.mastra;

packages/core/src/observability/types/tracing.ts

@@ -84,6 +84,8 @@ export enum SpanType {
   RAG_ACTION = 'rag_action',
   /** Graph operations (build / traverse) - not RAG-specific */
   GRAPH_ACTION = 'graph_action',
+  /** Inline data mapping between pipeline stages (e.g. a tool's `toModelOutput` transform) */
+  MAPPING = 'mapping',
 }
 
 export { EntityType };
@@ -342,6 +344,17 @@ export interface MCPToolCallAttributes extends AIBaseAttributes {
   success?: boolean;
 }
 
+/**
+ * Mapping attributes — for inline data transforms between pipeline stages
+ * (e.g. a tool's `toModelOutput` reshaping the tool result before the model sees it).
+ */
+export interface MappingAttributes extends AIBaseAttributes {
+  /** Identifier of the mapping (e.g. `toModelOutput`) so UIs can group related mappings */
+  mappingType?: string;
+  /** Associated tool call id when the mapping operates on a tool result */
+  toolCallId?: string;
+}
+
 /**
  * Processor attributes
  */
@@ -647,6 +660,7 @@ export interface SpanTypeMap {
   [SpanType.RAG_VECTOR_OPERATION]: RagVectorOperationAttributes;
   [SpanType.RAG_ACTION]: RagActionAttributes;
   [SpanType.GRAPH_ACTION]: GraphActionAttributes;
+  [SpanType.MAPPING]: MappingAttributes;
 }
 
 /**