@mastra/mcp-docs-server 1.1.35-alpha.3 → 1.1.35-alpha.30

package/.docs/reference/observability/tracing/exporters/mastra-storage-exporter.md

@@ -0,0 +1,194 @@
+# MastraStorageExporter
+
+Persists traces to Mastra's configured storage with automatic batching and retry logic.
+
+> **Note:** `MastraStorageExporter` was previously called `DefaultExporter`. The original `DefaultExporter` class is still exported from `@mastra/observability` so existing imports keep working, but it is deprecated and will be removed in a future major version. New code should use `MastraStorageExporter`.
+
+## Constructor
+
+```typescript
+new MastraStorageExporter(config?: MastraStorageExporterConfig)
+```
+
+## `MastraStorageExporterConfig`
+
+```typescript
+interface MastraStorageExporterConfig extends BaseExporterConfig {
+  /** Maximum number of spans per batch. Default: 1000 */
+  maxBatchSize?: number
+
+  /** Maximum total buffer size before emergency flush. Default: 10000 */
+  maxBufferSize?: number
+
+  /** Maximum time to wait before flushing batch in milliseconds. Default: 5000 */
+  maxBatchWaitMs?: number
+
+  /** Maximum number of retry attempts. Default: 4 */
+  maxRetries?: number
+
+  /** Base retry delay in milliseconds (uses exponential backoff). Default: 500 */
+  retryDelayMs?: number
+
+  /** Tracing storage strategy or 'auto' for automatic selection. Default: 'auto' */
+  strategy?: TracingStorageStrategy | 'auto'
+}
+```
+
+Extends `BaseExporterConfig`, which includes:
+
+- `logger?: IMastraLogger` - Logger instance
+- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Log level (default: INFO)
+
+## `TracingStorageStrategy`
+
+```typescript
+type TracingStorageStrategy = 'realtime' | 'batch-with-updates' | 'insert-only'
+```
+
+### Strategy Behaviors
+
+- **realtime**: Immediately persists each event to storage
+- **batch-with-updates**: Batches creates and updates separately, applies in order
+- **insert-only**: Only processes SPAN\_ENDED events, ignores updates
+
+## Properties
+
+```typescript
+readonly name = 'mastra-storage-exporter';
+```
+
+The deprecated `DefaultExporter` class continues to use `'mastra-default-observability-exporter'` as its `name` for backward compatibility.
+
+## Methods
+
+### init
+
+```typescript
+init(options: InitExporterOptions): void
+```
+
+Initializes the exporter after dependencies are ready. Resolves tracing strategy based on storage capabilities.
+
+### `exportTracingEvent`
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Processes a tracing event according to the resolved strategy.
+
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any buffered events to storage without shutting down the exporter. Useful in serverless environments where you need to ensure spans are exported before the runtime terminates.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Flushes remaining buffered events and performs cleanup.
+
+## Automatic strategy selection
+
+When `strategy: 'auto'` (default), the exporter queries the storage adapter for its capabilities:
+
+```typescript
+interface TracingStrategy {
+  /** Strategies supported by this adapter */
+  supported: TracingStorageStrategy[]
+
+  /** Preferred strategy for optimal performance */
+  preferred: TracingStorageStrategy
+}
+```
+
+The exporter will:
+
+1. Use the storage adapter's preferred strategy if available
+2. Fall back to the first supported strategy if preferred isn't available
+3. Log a warning if a user-specified strategy isn't supported
+
+## Batching behavior
+
+### Flush Triggers
+
+The buffer flushes when any of these conditions are met:
+
+- Buffer size reaches `maxBatchSize`
+- Time since first buffered event exceeds `maxBatchWaitMs`
+- Buffer size reaches `maxBufferSize` (emergency flush)
+- `shutdown()` is called
+
+### Retry Logic
+
+Failed flushes are retried with exponential backoff:
+
+- Retry delay: `retryDelayMs * 2^attempt`
+- Maximum attempts: `maxRetries`
+- Batch is dropped after all retries fail
+
+### Out-of-Order Handling
+
+For `batch-with-updates` strategy:
+
+- Tracks which spans have been created
+- Rejects updates/ends for spans not yet created
+- Logs warnings for out-of-order events
+- Maintains sequence numbers for ordered updates
+
+## Usage
+
+```typescript
+import { MastraStorageExporter } from '@mastra/observability'
+
+// Default configuration
+const exporter = new MastraStorageExporter()
+
+// Custom batching configuration
+const customExporter = new MastraStorageExporter({
+  maxBatchSize: 500,
+  maxBatchWaitMs: 2000,
+  strategy: 'batch-with-updates',
+  logLevel: 'debug',
+})
+```
+
+## Migrating from `DefaultExporter`
+
+The two classes share the same constructor signature and behavior. To migrate, replace the import and constructor:
+
+```typescript
+// Before
+import { DefaultExporter } from '@mastra/observability'
+const exporter = new DefaultExporter()
+
+// After
+import { MastraStorageExporter } from '@mastra/observability'
+const exporter = new MastraStorageExporter()
+```
+
+The original `DefaultExporter` is preserved unchanged so dashboards or alert rules that match the previous `mastra-default-observability-exporter` exporter name keep working until you migrate.
+
+## See also
+
+### Documentation
+
+- [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview): Complete guide
+- [Exporters](https://mastra.ai/docs/observability/tracing/overview): Exporter concepts
+
+### Other Exporters
+
+- [MastraPlatformExporter](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter): Mastra platform
+- [ConsoleExporter](https://mastra.ai/reference/observability/tracing/exporters/console-exporter): Debug output
+- [Langfuse](https://mastra.ai/reference/observability/tracing/exporters/langfuse): Langfuse integration
+- [Braintrust](https://mastra.ai/reference/observability/tracing/exporters/braintrust): Braintrust integration
+
+### Reference
+
+- [Configuration](https://mastra.ai/reference/observability/tracing/configuration): Configuration options
+- [Interfaces](https://mastra.ai/reference/observability/tracing/interfaces): Type definitions

package/.docs/reference/observability/tracing/exporters/otel.md

@@ -1,6 +1,6 @@
 # OtelExporter
 
-Sends Tracing data to any OpenTelemetry-compatible observability platform using standardized GenAI semantic conventions.
+Sends traces and logs to any OpenTelemetry-compatible observability platform. Traces use the standardized GenAI semantic conventions; logs carry their original severity and message body and are correlated to traces via both the OTEL log record's native trace context and `mastra.traceId` / `mastra.spanId` attributes.
 
 ## Constructor
 
@@ -13,6 +13,10 @@ new OtelExporter(config: OtelExporterConfig)
 ```typescript
 interface OtelExporterConfig {
   provider?: ProviderConfig
+  signals?: {
+    traces?: boolean
+    logs?: boolean
+  }
   timeout?: number
   batchSize?: number
   logLevel?: 'debug' | 'info' | 'warn' | 'error'
@@ -157,14 +161,14 @@ const exporter = new OtelExporter({
 
 ## Protocol requirements
 
-Different providers require different OTEL exporter packages:
+Different providers require different OTEL exporter packages. Trace and log export are independent: install only the trace package if you only need traces, or install both the trace and log packages for the chosen protocol if you also want log export. Zipkin does not support OTLP logs.
 
-| Protocol      | Required Package                           | Providers                  |
-| ------------- | ------------------------------------------ | -------------------------- |
-| gRPC          | `@opentelemetry/exporter-trace-otlp-grpc`  | Dash0                      |
-| HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` | SigNoz, New Relic, Laminar |
-| HTTP/JSON     | `@opentelemetry/exporter-trace-otlp-http`  | Traceloop, Custom          |
-| Zipkin        | `@opentelemetry/exporter-zipkin`           | Zipkin collectors          |
+| Protocol      | Trace package                                                 | Log package                                                  |
+| ------------- | ------------------------------------------------------------- | ------------------------------------------------------------ |
+| gRPC          | `@opentelemetry/exporter-trace-otlp-grpc` (+ `@grpc/grpc-js`) | `@opentelemetry/exporter-logs-otlp-grpc` (+ `@grpc/grpc-js`) |
+| HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto`                    | `@opentelemetry/exporter-logs-otlp-proto`                    |
+| HTTP/JSON     | `@opentelemetry/exporter-trace-otlp-http`                     | `@opentelemetry/exporter-logs-otlp-http`                     |
+| Zipkin        | `@opentelemetry/exporter-zipkin`                              | not supported                                                |
 
 ## Tags support
 

package/.docs/reference/observability/tracing/instances.md

@@ -102,6 +102,6 @@ class CustomObservabilityInstance extends BaseObservabilityInstance {
 
 ### Exporters
 
-- [DefaultExporter](https://mastra.ai/reference/observability/tracing/exporters/default-exporter): Storage persistence
-- [CloudExporter](https://mastra.ai/reference/observability/tracing/exporters/cloud-exporter): Mastra platform integration
+- [MastraStorageExporter](https://mastra.ai/reference/observability/tracing/exporters/mastra-storage-exporter): Storage persistence
+- [MastraPlatformExporter](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter): Mastra platform integration
 - [ConsoleExporter](https://mastra.ai/reference/observability/tracing/exporters/console-exporter): Debug output

package/.docs/reference/observability/tracing/interfaces.md

@@ -141,10 +141,18 @@ interface ObservabilityExporter {
   /** Handle feedback events */
   onFeedbackEvent?(event: FeedbackEvent): void | Promise<void>
 
+  /** Handle exporter pipeline droppedEvent */
+  onDroppedEvent?(event: ObservabilityDropEvent): void | Promise<void>
+
   /** Export tracing events */
   exportTracingEvent(event: TracingEvent): Promise<void>
 
-  /** Add score to a trace (optional) */
+  /**
+   * @deprecated Implement `onScoreEvent` instead. Eval scores now flow through the
+   * unified observability bus as `ScoreEvent`s. This method is preserved on the
+   * interface for backwards compatibility with existing exporters; new exporters
+   * should not implement it.
+   */
   addScoreToTrace?({
     traceId,
     spanId,
@@ -169,7 +177,34 @@ interface ObservabilityExporter {
 }
 ```
 
-Event callback payloads use observability event bus envelopes: `TracingEvent` carries span lifecycle events with `exportedSpan`, `LogEvent` wraps `ExportedLog` in `log`, `MetricEvent` wraps `ExportedMetric` in `metric`, `ScoreEvent` wraps `ExportedScore` in `score`, and `FeedbackEvent` wraps `ExportedFeedback` in `feedback`. For Cloud exporter behavior for these callbacks, see [CloudExporter](https://mastra.ai/reference/observability/tracing/exporters/cloud-exporter).
+Event callback payloads use observability event bus envelopes: `TracingEvent` carries span lifecycle events with `exportedSpan`, `LogEvent` wraps `ExportedLog` in `log`, `MetricEvent` wraps `ExportedMetric` in `metric`, `ScoreEvent` wraps `ExportedScore` in `score`, and `FeedbackEvent` wraps `ExportedFeedback` in `feedback`. For Mastra Platform exporter behavior for these callbacks, see [MastraPlatformExporter](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter).
+
+### `ObservabilityDropEvent`
+
+Structured event emitted when the exporter pipeline drops observability events.
+
+```typescript
+type ObservabilityDropSignal = 'tracing' | 'log' | 'metric' | 'score' | 'feedback'
+
+type ObservabilityDropReason = 'unsupported-storage' | 'retry-exhausted'
+
+interface ObservabilityDropEvent {
+  type: 'drop'
+  signal: ObservabilityDropSignal
+  reason: ObservabilityDropReason
+  count: number
+  timestamp: Date
+  exporterName: string
+  storageName?: string
+  error?: {
+    id?: string
+    domain?: string
+    message: string
+  }
+}
+```
+
+Use `onDroppedEvent` on a custom exporter or bridge to forward these events to external metrics or alerting systems.
 
 ### `SpanOutputProcessor`
 

package/.docs/reference/observability/tracing/processors/sensitive-data-filter.md

@@ -2,6 +2,28 @@
 
 A SpanOutputProcessor that redacts sensitive information from span fields.
 
+## Auto-applied by default
+
+`Observability` automatically appends a `SensitiveDataFilter` to every configured instance's `spanOutputProcessors` so secrets are redacted before they reach exporters such as the Mastra cloud exporter. The filter runs last (after any user-provided processors) so that sensitive data introduced or surfaced by upstream processors is still redacted. You do not need to add it manually unless you want to customize its options.
+
+To opt out or customize the auto-applied filter, use the `sensitiveDataFilter` option on the [`Observability` registry config](https://mastra.ai/reference/observability/tracing/configuration):
+
+```typescript
+import { Observability } from '@mastra/observability'
+
+new Observability({
+  configs: {
+    /* ... */
+  },
+  // disable the auto-applied filter
+  sensitiveDataFilter: false,
+  // or customize it
+  // sensitiveDataFilter: { sensitiveFields: ['mySecret'], redactionStyle: 'partial' },
+})
+```
+
+If a config already includes a `SensitiveDataFilter` in `spanOutputProcessors`, the auto-applied filter is skipped to avoid double redaction. Pre-instantiated `ObservabilityInstance` values are not modified — add a `SensitiveDataFilter` to their processors yourself if needed.
+
 ## Constructor
 
 ```typescript

package/.docs/reference/observability/tracing/span-filtering.md

@@ -11,7 +11,7 @@ The following example demonstrates how to combine `excludeSpanTypes` and `spanFi
 ```ts
 import { Mastra } from '@mastra/core'
 import { SpanType } from '@mastra/core/observability'
-import { Observability, DefaultExporter } from '@mastra/observability'
+import { Observability, MastraStorageExporter } from '@mastra/observability'
 import { LangfuseExporter } from '@mastra/langfuse'
 
 export const mastra = new Mastra({
@@ -19,7 +19,7 @@ export const mastra = new Mastra({
     configs: {
       default: {
         serviceName: 'my-app',
-        exporters: [new DefaultExporter(), new LangfuseExporter()],
+        exporters: [new MastraStorageExporter(), new LangfuseExporter()],
         excludeSpanTypes: [SpanType.MODEL_CHUNK, SpanType.MODEL_STEP],
         spanFilter: span => {
           if (span.type === SpanType.TOOL_CALL && span.attributes?.success) {

package/.docs/reference/processors/prefill-error-handler.md

@@ -2,7 +2,7 @@
 
 The `PrefillErrorHandler` is an **error processor** that handles assistant-response prefill errors. This error occurs when a conversation ends with an assistant message and the model rejects the request because it interprets it as prefilling the assistant response.
 
-When the error is detected, the processor appends a hidden `<system-reminder>continue</system-reminder>` user message to the conversation and signals a retry. The reminder is persisted with `metadata.systemReminder = { type: 'anthropic-prefill-processor-retry' }`, which keeps it available for retry reconstruction and raw history while standard UI-facing message conversions hide it.
+When the error is detected, the processor sends a hidden `system-reminder` signal with `continue` as its contents and signals a retry. The reminder is persisted as signal metadata, which keeps it available for retry reconstruction and raw history while standard UI-facing message conversions hide it.
 
 Add this processor to `errorProcessors` when you want Mastra to recover from assistant prefill rejections (for example Anthropic's "assistant message prefill" and Qwen/llama.cpp's "assistant response prefill is incompatible with `enable_thinking`" errors).
 
@@ -10,7 +10,7 @@ Add this processor to `errorProcessors` when you want Mastra to recover from ass
 
 1. The LLM API call fails with a known assistant-prefill rejection message
 2. `PrefillErrorHandler` checks that this is the first retry attempt
-3. It appends a hidden `<system-reminder>continue</system-reminder>` user message to the `messageList`
+3. It sends a hidden `system-reminder` signal with `continue` as its contents
 4. It returns `{ retry: true }` to signal the LLM call should be retried with the modified messages
 
 The processor now reacts to the API rejection itself instead of re-checking whether the conversation currently ends with an assistant message. This makes it resilient to cases where the provider rejects the request for prefill semantics even if the trailing message shape has already been transformed upstream.
@@ -62,7 +62,7 @@ The `PrefillErrorHandler` takes no constructor parameters.
 
 **name** (`'Prefill Error Handler'`): Processor display name.
 
-**processAPIError** (`(args: ProcessAPIErrorArgs) => ProcessAPIErrorResult | void`): Handles known assistant-prefill errors by appending a hidden system reminder continue message and signaling retry. Only triggers on the first retry attempt.
+**processAPIError** (`(args: ProcessAPIErrorArgs) => ProcessAPIErrorResult | void`): Handles known assistant-prefill errors by sending a hidden system reminder signal and signaling retry. Only triggers on the first retry attempt.
 
 ## Related
 

package/.docs/reference/processors/processor-interface.md

@@ -4,7 +4,7 @@ The `Processor` interface defines the contract for all processors in Mastra. Pro
 
 ## When processor methods run
 
-The six processor methods run at different points in the agent execution lifecycle:
+The seven processor methods run at different points in the agent execution lifecycle:
 
 ```text
 ┌─────────────────────────────────────────────────────────────────┐
@@ -26,6 +26,11 @@ The six processor methods run at different points in the agent execution lifecyc
 │  │  └──────────┬──────────┘                                │    │
 │  │             │                                           │    │
 │  │             ▼                                           │    │
+│  │  ┌─────────────────────┐                                │    │
+│  │  │  processLLMRequest   │  ← Runs before provider call   │    │
+│  │  └──────────┬──────────┘                                │    │
+│  │             │                                           │    │
+│  │             ▼                                           │    │
 │  │       LLM Execution ──── API Error? ──┐                │    │
 │  │             │                          │                │    │
 │  │             │              ┌───────────────────┐        │    │
@@ -59,14 +64,15 @@ The six processor methods run at different points in the agent execution lifecyc
 └─────────────────────────────────────────────────────────────────┘
 ```
 
-| Method                | When it runs                                           | Use case                                                                      |
-| --------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------- |
-| `processInput`        | Once at the start, before the agentic loop             | Validate/transform initial user input, add context                            |
-| `processInputStep`    | At each step of the agentic loop, before each LLM call | Transform messages between steps, handle tool results                         |
-| `processAPIError`     | When an LLM API call fails                             | Inspect API rejections, optionally mutate state/messages, and request a retry |
-| `processOutputStream` | On each streaming chunk during LLM response            | Filter/modify streaming content, detect patterns in real-time                 |
-| `processOutputStep`   | After each LLM response, before tool execution         | Validate output quality, implement guardrails with retry                      |
-| `processOutputResult` | Once after generation completes                        | Post-process final response, log results                                      |
+| Method                | When it runs                                           | Use case                                                                                     |
+| --------------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
+| `processInput`        | Once at the start, before the agentic loop             | Validate/transform initial user input, add context                                           |
+| `processInputStep`    | At each step of the agentic loop, before each LLM call | Transform messages between steps, handle tool results                                        |
+| `processLLMRequest`   | After LLM request conversion, before the provider call | Rewrite the outbound `LanguageModelV2Prompt` for the current call without persisting changes |
+| `processAPIError`     | When an LLM API call fails                             | Inspect API rejections, optionally mutate state/messages, and request a retry                |
+| `processOutputStream` | On each streaming chunk during LLM response            | Filter/modify streaming content, detect patterns in real-time                                |
+| `processOutputStep`   | After each LLM response, before tool execution         | Validate output quality, implement guardrails with retry                                     |
+| `processOutputResult` | Once after generation completes                        | Post-process final response, log results                                                     |
 
 ## Interface definition
 
@@ -97,6 +103,10 @@ interface Processor<TId extends string = string, TTripwireMetadata = unknown> {
     | void
     | undefined
 
+  processLLMRequest?(
+    args: ProcessLLMRequestArgs<TTripwireMetadata>,
+  ): Promise<ProcessLLMRequestResult> | ProcessLLMRequestResult
+
   processAPIError?(
     args: ProcessAPIErrorArgs<TTripwireMetadata>,
   ): Promise<ProcessAPIErrorResult | void> | ProcessAPIErrorResult | void
@@ -243,9 +253,10 @@ processInputStep?<TTripwireMetadata = unknown>(
 1. `processInput` (once at start)
 2. `processInputStep` from inputProcessors (at each step, before LLM call)
 3. `prepareStep` callback (runs as part of the processInputStep pipeline, after inputProcessors)
-4. LLM execution
-5. Tool execution (if needed)
-6. Repeat from step 2 if tools were called
+4. `processLLMRequest` from inputProcessors (after prompt conversion, before the provider call)
+5. LLM execution
+6. Tool execution (if needed)
+7. Repeat from step 2 if tools were called
 
 #### `ProcessInputStepArgs`
 
@@ -339,6 +350,57 @@ System messages are **reset to their original values** at the start of each step
 
 ***
 
+### `processLLMRequest`
+
+Processes the final LLM request after Mastra converts the `MessageList` into `LanguageModelV2Prompt` and before the provider call. Use this method for transient, model-aware rewrites that should affect only the current outbound request.
+
+Returned prompt changes are forwarded to the model for the current call only. They are not persisted back to `MessageList`, memory, UI history, or later provider calls.
+
+```typescript
+processLLMRequest?(
+  args: ProcessLLMRequestArgs,
+): Promise<ProcessLLMRequestResult> | ProcessLLMRequestResult;
+```
+
+#### `ProcessLLMRequestArgs`
+
+**prompt** (`LanguageModelV2Prompt`): The LLM request prompt that will be sent to the provider for this call.
+
+**model** (`MastraLanguageModel`): The resolved model that will receive the prompt. Use this to scope provider-specific rewrites.
+
+**stepNumber** (`number`): Current step number (0-indexed). Step 0 is the initial LLM call.
+
+**steps** (`StepResult[]`): Results from previous steps, including text, toolCalls, and toolResults.
+
+**state** (`Record<string, unknown>`): Per-processor state that persists across all method calls within this request.
+
+**abort** (`(reason?: string, options?: { retry?: boolean; metadata?: unknown }) => never`): Function to abort processing. Throws a TripWire error that stops execution and emits a \`tripwire\` chunk.
+
+**retryCount** (`number`): Current retry attempt count from \`ProcessorContext\`. Starts at \`0\`; use to cap processor-triggered retries.
+
+**requestContext** (`RequestContext`): Request-scoped context with execution metadata.
+
+**tracingContext** (`TracingContext`): Tracing context for observability.
+
+**writer** (`ProcessorStreamWriter`): Stream writer for emitting custom data chunks during streaming. Use \`writer.custom()\` to send transient UI signals.
+
+**abortSignal** (`AbortSignal`): Signal for cancelling the operation.
+
+#### Return value
+
+`processLLMRequest` returns `ProcessLLMRequestResult`, which is `{ prompt?: LanguageModelV2Prompt } | undefined | void`.
+
+- Return `{ prompt }` to replace the outbound prompt for the current provider call.
+- Return `undefined` or `void` to forward the original prompt unchanged.
+
+#### Use cases
+
+- Removing or reshaping provider-specific prompt parts before a model call
+- Normalizing roles or content to match a provider's input requirements
+- Adapting tool result formats when switching providers mid-loop
+
+***
+
 ### `processAPIError`
 
 Handles LLM API rejection errors before they surface as final errors. This runs when the API call fails with a non-retryable error (such as a 400 or 422 status code). Unlike `processOutputStep` which runs after successful responses, this runs when the API rejects the request.

package/.docs/reference/processors/provider-history-compat.md

@@ -0,0 +1,132 @@
+# ProviderHistoryCompat
+
+The `ProviderHistoryCompat` processor handles provider-specific history incompatibilities. It can rewrite the outbound language model prompt before a provider call, or react to API errors and retry with repaired message history.
+
+Use it when an agent may switch between model providers, reuse message history across providers, or call a provider that rejects fields emitted by another provider.
+
+## Usage example
+
+Add `ProviderHistoryCompat` to `inputProcessors` when you want all built-in compatibility rules available for an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { ProviderHistoryCompat } from '@mastra/core/processors'
+
+export const agent = new Agent({
+  name: 'my-agent',
+  instructions: 'You are a helpful assistant.',
+  model: 'anthropic/claude-sonnet-4-5',
+  inputProcessors: [new ProviderHistoryCompat()],
+})
+```
+
+Mastra agents don't add this processor automatically. Add it explicitly when you need provider history compatibility rules, reactive API error recovery, custom rules, or predictable processor ordering.
+
+## Constructor parameters
+
+**opts** (`{ additionalRules?: CompatRule[] }`): Configuration options for provider history compatibility rules.
+
+**opts.additionalRules** (`CompatRule[]`): Custom compatibility rules to run after the built-in rules. Rules can rewrite the outbound prompt or repair persisted messages after matching an API error.
+
+## Properties
+
+**id** (`'provider-history-compat'`): Processor identifier.
+
+**name** (`'Provider History Compat'`): Processor display name.
+
+**processLLMRequest** (`(args: ProcessLLMRequestArgs) => ProcessLLMRequestResult`): Runs preemptive compatibility rules against the converted LanguageModelV2Prompt immediately before the provider call. Returned prompt changes are transient and are not persisted to memory or message history.
+
+**processAPIError** (`(args: ProcessAPIErrorArgs) => Promise<ProcessAPIErrorResult | void>`): Runs reactive compatibility rules when a provider rejects the request. Matching rules can mutate the message list and return retry: true on the first retry attempt.
+
+## Built-in rules
+
+`ProviderHistoryCompat` includes these built-in compatibility rules:
+
+| Rule                                        | Provider  | Timing                      | Behavior                                                                                                                          |
+| ------------------------------------------- | --------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `anthropic-tool-id-format`                  | Anthropic | Reactive API error recovery | Rewrites tool call IDs that contain characters outside `[a-zA-Z0-9_-]` and retries the request.                                   |
+| `cerebras-strip-reasoning-content`          | Cerebras  | Preemptive prompt rewrite   | Removes assistant `reasoning` parts from the outbound prompt so they're not serialized as unsupported `reasoning_content` fields. |
+| `anthropic-strip-foreign-reasoning-content` | Anthropic | Preemptive prompt rewrite   | Removes non-Anthropic assistant `reasoning` parts from the outbound prompt. Anthropic-native thinking history is preserved.       |
+
+Preemptive rules run through `processLLMRequest` after Mastra converts messages to the model prompt format and before the prompt is sent to the provider. These rewrites affect only the current provider call.
+
+Reactive rules run through `processAPIError` after a provider rejection. They can update the persisted `messageList` and request a retry.
+
+## `CompatRule`
+
+A `CompatRule` defines one provider history compatibility fix:
+
+```typescript
+import type { CompatRule } from '@mastra/core/processors'
+
+const removeUnsupportedPromptParts: CompatRule = {
+  name: 'remove-unsupported-prompt-parts',
+  applyToPrompt({ prompt, model }) {
+    // Return a modified LanguageModelV2Prompt, or undefined to leave it unchanged.
+    return undefined
+  },
+}
+```
+
+**name** (`string`): Human-readable rule identifier for logs and debugging.
+
+**errorPatterns** (`RegExp[]`): Patterns matched against provider API error messages and response bodies. Required for reactive rules that implement fix.
+
+**fix** (`(messages: MastraDBMessage[]) => boolean`): Reactive fix that mutates persisted database messages after a matching API error. Return true when the rule changed messages and the request should retry.
+
+**applyToPrompt** (`(args: { prompt: LanguageModelV2Prompt; model: unknown }) => LanguageModelV2Prompt | undefined`): Preemptive fix that rewrites the outbound prompt for the current provider call. Return undefined when no prompt change is needed.
+
+## Custom rules
+
+Pass custom rules through `additionalRules`. Custom rules run after the built-in rules:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { ProviderHistoryCompat, type CompatRule } from '@mastra/core/processors'
+
+const stripUnsupportedAssistantMetadata: CompatRule = {
+  name: 'strip-unsupported-assistant-metadata',
+  applyToPrompt({ prompt, model }) {
+    if (typeof model !== 'string' || !model.startsWith('example-provider/')) {
+      return undefined
+    }
+
+    let changed = false
+    const nextPrompt = prompt.map(message => {
+      if (message.role !== 'assistant' || typeof message.content === 'string') {
+        return message
+      }
+
+      const nextContent = message.content.map(part => {
+        if (!('providerOptions' in part)) return part
+        changed = true
+        const { providerOptions: _providerOptions, ...rest } = part
+        return rest
+      })
+
+      return { ...message, content: nextContent }
+    })
+
+    return changed ? nextPrompt : undefined
+  },
+}
+
+export const agent = new Agent({
+  name: 'custom-provider-agent',
+  instructions: 'You are a helpful assistant.',
+  model: 'example-provider/model',
+  inputProcessors: [
+    new ProviderHistoryCompat({
+      additionalRules: [stripUnsupportedAssistantMetadata],
+    }),
+  ],
+})
+```
+
+Use `applyToPrompt` for provider-specific rewrites that shouldn't be saved to memory. Use `fix` with `errorPatterns` when the provider rejects persisted message history and the repaired history should be reused on future turns.
+
+## Related
+
+- [Processor interface](https://mastra.ai/reference/processors/processor-interface)
+- [Processors](https://mastra.ai/docs/agents/processors)
+- [PrefillErrorHandler](https://mastra.ai/reference/processors/prefill-error-handler)