@mastra/mcp-docs-server 1.1.35-alpha.2 → 1.1.35-alpha.26

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)

package/.docs/reference/processors/response-cache.md

@@ -0,0 +1,114 @@
+# ResponseCache
+
+`ResponseCache` is an input processor that caches LLM responses on the request/response boundary inside the agentic loop. It hooks into `processLLMRequest` (cache lookup; short-circuits on hit) and `processLLMResponse` (cache write on completion).
+
+The cache key is derived from the resolved `LanguageModelV2Prompt` Mastra is about to send to the model — i.e. _after_ memory has loaded and earlier input processors have transformed the prompt — so two users with different memory contexts produce different cache keys. Each step in an agentic tool loop is independently cached.
+
+There is no agent-level option for response caching; register `ResponseCache` explicitly on `inputProcessors`. Per-call overrides flow through `RequestContext` via [`ResponseCache.context()`](#static-helpers) and [`ResponseCache.applyContext()`](#static-helpers).
+
+## Usage example
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { InMemoryServerCache } from '@mastra/core/cache'
+import { ResponseCache } from '@mastra/core/processors'
+
+const cache = new InMemoryServerCache()
+
+const agent = new Agent({
+  name: 'Search Agent',
+  instructions: 'You answer questions concisely.',
+  model: 'openai/gpt-5',
+  inputProcessors: [new ResponseCache({ cache, ttl: 600 })],
+})
+
+// First call hits the LLM and writes to the cache.
+await agent.generate('What is the capital of France?')
+
+// Second identical call replays the cached response.
+await agent.generate('What is the capital of France?')
+
+// Force a fresh call but still update the cache.
+await agent.generate('What is the capital of France?', {
+  requestContext: ResponseCache.context({ bust: true }),
+})
+```
+
+See [Response caching](https://mastra.ai/docs/agents/response-caching) for the conceptual overview, scoping rules, and recommended deployment patterns.
+
+## Constructor parameters
+
+**cache** (`MastraServerCache`): The cache backend. Required. Pass any \`MastraServerCache\` implementation — \`InMemoryServerCache\` for local development, \`RedisCache\` from \`@mastra/redis\` for production, or your own subclass for a custom backend.
+
+**ttl** (`number`): Time-to-live (seconds) for entries written by this processor. Defaults to 300 seconds (5 minutes), matching OpenRouter's reference implementation. (Default: `300`)
+
+**scope** (`string | null`): Tenant scope appended to the cache key. \`null\` opts out of scoping. When omitted, the processor falls back to the resource id resolved from the request context (\`MASTRA\_RESOURCE\_ID\_KEY\`) for automatic per-user isolation.
+
+**key** (`string | (inputs: ResponseCacheKeyInputs) => string | Promise<string>`): Override the auto-derived cache key. Pass a string to pin a key, or a function that receives \`{ agentId, scope, model, prompt, stepNumber }\` and returns a key. If the function throws, the processor falls back to the deterministic hash so the call still benefits from caching.
+
+**bust** (`boolean`): Force a cache miss on every call: skip the read but still write on completion. Useful for explicit refresh paths. (Default: `false`)
+
+**agentId** (`string`): Logical id used in the cache key namespace. Defaults to \`'mastra-response-cache'\`. Set this to the owning agent's id when you want cache entries scoped per-agent. (Default: `'mastra-response-cache'`)
+
+## Static helpers
+
+`ResponseCache` exposes two static helpers for setting per-call overrides on a `RequestContext`. The helpers keep the underlying context key a private implementation detail — prefer them over reading/writing the raw key.
+
+### `ResponseCache.context(options)`
+
+Build a fresh `RequestContext` preloaded with per-call response cache overrides.
+
+```typescript
+await agent.stream('hello', {
+  requestContext: ResponseCache.context({ key: 'custom', bust: true }),
+})
+```
+
+### `ResponseCache.applyContext(requestContext, options)`
+
+Merge per-call response cache overrides into an existing `RequestContext`. Returns the same context for chaining.
+
+```typescript
+const ctx = new RequestContext()
+ctx.set('caller-meta', { userId: 'u-123' })
+ResponseCache.applyContext(ctx, { bust: true })
+await agent.stream('hello', { requestContext: ctx })
+```
+
+## ResponseCacheContextOptions
+
+The shape passed to `ResponseCache.context()` / `ResponseCache.applyContext()`.
+
+**key** (`string | (inputs: ResponseCacheKeyInputs) => string | Promise<string>`): Overrides the auto-derived cache key for this request only.
+
+**scope** (`string | null`): Overrides the tenant scope for this request only. \`null\` opts out of scoping.
+
+**bust** (`boolean`): Skip the cache read but still write on completion.
+
+`cache`, `ttl`, and `agentId` are intentionally not overridable per call — they are instance-level concerns that should not vary per request.
+
+## ResponseCacheKeyInputs
+
+The argument passed to a `key` function (constructor or per-call). All fields contribute to the deterministic hash by default.
+
+**agentId** (`string`): Logical processor id used to namespace the cache key.
+
+**scope** (`string | null | undefined`): Resolved scope for this request, or \`null\` when scoping is disabled.
+
+**model** (`{ provider?: string; modelId?: string; specVersion?: string }`): Provider/model identity. Different models produce different responses.
+
+**prompt** (`LanguageModelV2Prompt`): The exact prompt the provider would receive, post memory load and post any prompt-modifying input processors.
+
+**stepNumber** (`number`): 0-indexed step number within the agentic loop. Greater than zero for tool steps.
+
+## Helper exports
+
+- `buildResponseCacheKey(inputs)` — the deterministic hash used by default. Re-export it to override individual fields while preserving the rest of the standard key shape.
+- `DEFAULT_RESPONSE_CACHE_TTL_SECONDS` — the default `ttl` (`300`).
+- `RESPONSE_CACHE_CONTEXT_KEY` — the `RequestContext` key the static helpers write to. Exposed for advanced cases (e.g. clearing the override mid-pipeline); prefer the helpers.
+
+## Related
+
+- [Response caching](https://mastra.ai/docs/agents/response-caching)
+- [Processors](https://mastra.ai/docs/agents/processors)
+- [Processor interface](https://mastra.ai/reference/processors/processor-interface)

package/.docs/reference/processors/tool-call-filter.md

@@ -19,6 +19,11 @@ const filterSpecific = new ToolCallFilter({
 const filterAfterRecentTools = new ToolCallFilter({
   filterAfterToolSteps: 2,
 })
+
+// Preserve compact model-facing output for filtered completed tool results
+const filterWithCompactToolHistory = new ToolCallFilter({
+  preserveModelOutput: true,
+})
 ```
 
 ## Constructor parameters
@@ -29,6 +34,8 @@ const filterAfterRecentTools = new ToolCallFilter({
 
 **options.filterAfterToolSteps** (`number`): Enables filtering during agent loops and preserves tool calls and results from this many recent tool-producing steps. If undefined, step filtering is disabled
 
+**options.preserveModelOutput** (`boolean`): Preserves compact model-facing output from completed filtered tool results with providerMetadata.mastra.modelOutput. Raw tool args and raw results are removed
+
 ## Returns
 
 **id** (`string`): Processor identifier set to 'tool-call-filter'
@@ -53,6 +60,27 @@ const filter = new ToolCallFilter({
 })
 ```
 
+## Preserve compact model output
+
+Set `preserveModelOutput: true` to retain compact `toModelOutput` history for completed tool results that the filter removes. This keeps the model-facing output as text in the prompt while removing the raw `toolInvocation.args` and raw `toolInvocation.result` payloads.
+
+Only completed tool results with `providerMetadata.mastra.modelOutput` are preserved. Tool calls, incomplete results, and results without stored model output are still filtered.
+
+```typescript
+const filter = new ToolCallFilter({
+  preserveModelOutput: true,
+})
+```
+
+Combine `preserveModelOutput` with `exclude` to preserve compact output only for filtered tools:
+
+```typescript
+const filter = new ToolCallFilter({
+  exclude: ['searchDatabase'],
+  preserveModelOutput: true,
+})
+```
+
 ## Extended usage example
 
 ```typescript

package/.docs/reference/storage/clickhouse.md

@@ -51,7 +51,7 @@ import { Mastra } from '@mastra/core'
 import { MastraCompositeStore } from '@mastra/core/storage'
 import { PostgresStore } from '@mastra/pg'
 import { ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'
-import { Observability, DefaultExporter } from '@mastra/observability'
+import { Observability, MastraStorageExporter } from '@mastra/observability'
 
 const observabilityStore = new ObservabilityStorageClickhouseVNext({
   url: process.env.CLICKHOUSE_URL!,
@@ -74,14 +74,14 @@ export const mastra = new Mastra({
     configs: {
       default: {
         serviceName: 'mastra',
-        exporters: [new DefaultExporter()],
+        exporters: [new MastraStorageExporter()],
       },
     },
   }),
 })
 ```
 
-`DefaultExporter` automatically selects the `insert-only` strategy when ClickHouse is the observability backend, which gives the highest write throughput. See [tracing strategies](https://mastra.ai/docs/observability/tracing/exporters/default) for details.
+`MastraStorageExporter` automatically selects the `insert-only` strategy when ClickHouse is the observability backend, which gives the highest write throughput. See [tracing strategies](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage) for details.
 
 ### Observability with the legacy domain
 
@@ -226,7 +226,7 @@ import { Mastra } from '@mastra/core'
 import { MastraCompositeStore } from '@mastra/core/storage'
 import { PostgresStore } from '@mastra/pg'
 import { ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'
-import { Observability, DefaultExporter } from '@mastra/observability'
+import { Observability, MastraStorageExporter } from '@mastra/observability'
 
 export const mastra = new Mastra({
   storage: new MastraCompositeStore({
@@ -247,7 +247,7 @@ export const mastra = new Mastra({
     configs: {
       default: {
         serviceName: 'mastra',
-        exporters: [new DefaultExporter()],
+        exporters: [new MastraStorageExporter()],
       },
     },
   }),
@@ -287,14 +287,14 @@ In CI/CD pipelines, set `disableInit: true` on `ClickhouseStore` and run `init()
 
 ClickHouse is the recommended backend for production observability:
 
-- **Insert-only strategy**: `DefaultExporter` writes completed spans in batches without per-span updates, which is the highest-throughput strategy available.
+- **Insert-only strategy**: `MastraStorageExporter` writes completed spans in batches without per-span updates, which is the highest-throughput strategy available.
 - **Columnar compression**: Span attributes and log payloads compress well compared to the same data in row-oriented databases.
 
-For the full strategy matrix and production guidance, see the [`DefaultExporter` reference](https://mastra.ai/docs/observability/tracing/exporters/default).
+For the full strategy matrix and production guidance, see the [`MastraStorageExporter` reference](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage).
 
 ## Related
 
 - [Storage overview](https://mastra.ai/reference/storage/overview)
 - [Composite storage](https://mastra.ai/reference/storage/composite)
-- [`DefaultExporter`](https://mastra.ai/docs/observability/tracing/exporters/default)
+- [`MastraStorageExporter`](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage)
 - [Observability overview](https://mastra.ai/docs/observability/overview)

package/.docs/reference/storage/cloudflare-d1.md

@@ -2,7 +2,7 @@
 
 The Cloudflare D1 storage implementation provides a serverless SQL database solution using Cloudflare D1, supporting relational operations and transactional consistency.
 
-> **Observability Not Supported:** Cloudflare D1 storage **doesn't support the observability domain**. Traces from the `DefaultExporter` can't be persisted to D1, and [Studio's](https://mastra.ai/docs/studio/overview) observability features won't work with D1 as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse or PostgreSQL.
+> **Observability Not Supported:** Cloudflare D1 storage **doesn't support the observability domain**. Traces from the `MastraStorageExporter` can't be persisted to D1, and [Studio's](https://mastra.ai/docs/studio/overview) observability features won't work with D1 as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse.
 
 > **Row Size Limit:** Cloudflare D1 enforces a **1 MiB maximum row size**. This limit can be exceeded when storing messages with base64-encoded attachments such as images. See [Handling large attachments](https://mastra.ai/docs/memory/storage) for workarounds including uploading attachments to external storage.
 

package/.docs/reference/storage/cloudflare.md

@@ -5,7 +5,7 @@ Mastra provides two Cloudflare storage implementations:
 - **Cloudflare KV** (`CloudflareKVStorage`): A globally distributed, eventually consistent key-value store
 - **Cloudflare Durable Objects** (`CloudflareDOStorage`): A strongly consistent, SQLite-based storage using Durable Objects
 
-> **Observability Not Supported:** Cloudflare storage **doesn't support the observability domain**. Traces from the `DefaultExporter` can't be persisted, and [Studio's](https://mastra.ai/docs/studio/overview) observability features won't work with Cloudflare as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse or PostgreSQL.
+> **Observability Not Supported:** Cloudflare storage **doesn't support the observability domain**. Traces from the `MastraStorageExporter` can't be persisted, and [Studio's](https://mastra.ai/docs/studio/overview) observability features won't work with Cloudflare as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse.
 
 ## Installation
 

package/.docs/reference/storage/composite.md

@@ -242,4 +242,4 @@ const storage = new MastraCompositeStore({
 
 > **Note:** `ObservabilityStorageClickhouseVNext` is the current observability domain implementation. The legacy `ObservabilityStorageClickhouse` class is also exported and remains supported for projects that have not migrated. See the [ClickHouse storage reference](https://mastra.ai/reference/storage/clickhouse) for details.
 
-> **Info:** This approach is also required when using storage providers that don't support observability (like Convex, DynamoDB, or Cloudflare). See the [DefaultExporter documentation](https://mastra.ai/docs/observability/tracing/exporters/default) for the full list of supported providers.
+> **Info:** This approach is also required when using storage providers that don't support observability (like Convex, DynamoDB, or Cloudflare). See the [MastraStorageExporter documentation](https://mastra.ai/docs/observability/tracing/exporters/mastra-storage) for the full list of supported providers.

package/.docs/reference/storage/convex.md

@@ -2,7 +2,7 @@
 
 The Convex storage implementation provides a serverless storage solution using [Convex](https://convex.dev), a full-stack TypeScript development platform with real-time sync and automatic caching.
 
-> **Observability Not Supported:** Convex storage **doesn't support the observability domain**. Traces from the `DefaultExporter` can't be persisted to Convex, and [Studio's](https://mastra.ai/docs/studio/overview) observability features won't work with Convex as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse or PostgreSQL.
+> **Observability Not Supported:** Convex storage **doesn't support the observability domain**. Traces from the `MastraStorageExporter` can't be persisted to Convex, and [Studio's](https://mastra.ai/docs/studio/overview) observability features won't work with Convex as your only storage provider. To enable observability, use [composite storage](https://mastra.ai/reference/storage/composite) to route observability data to a supported provider like ClickHouse.
 
 > **Record Size Limit:** Convex enforces a **1 MiB maximum record size**. This limit can be exceeded when storing messages with base64-encoded attachments such as images. See [Handling large attachments](https://mastra.ai/docs/memory/storage) for workarounds including uploading attachments to external storage like S3, Cloudflare R2, or [Convex file storage](https://docs.convex.dev/file-storage).