@mastra/mcp-docs-server 1.1.35-alpha.6 → 1.1.35

package/.docs/reference/editor/tool-provider.md

@@ -14,7 +14,7 @@ Tool providers implement these methods:
 
 **getToolSchema(slug)** (`(slug: string) => Promise<JSONSchema>`): Returns the JSON schema for a specific tool identified by its slug.
 
-**resolveTools(slugs, options?)** (`(slugs: string[], options?) => Promise<Record<string, ToolAction>>`): Resolves tool slugs into executable Mastra tool actions. The options object can include userId for per-user authentication.
+**resolveTools(slugs, options?)** (`(slugs: string[], options?) => Promise<Record<string, ToolAction>>`): Resolves tool slugs into executable Mastra tool actions. Built-in providers use resourceId from request context for per-user authentication.
 
 ***
 
@@ -47,7 +47,7 @@ Composio tools use uppercase slug format: `GITHUB_CREATE_ISSUE`, `SLACK_SEND_MES
 
 ### Authentication
 
-Tool execution is scoped to a `userId` passed through request context. Each user authenticates with the integration separately through Composio's auth flow.
+Tool execution is scoped to the `resourceId` passed through request context. The provider maps that value to the user identity required by Composio's auth flow.
 
 ***
 
@@ -82,4 +82,4 @@ Arcade tools use `Toolkit.ToolName` format: `Github.GetRepository`, `Slack.SendM
 
 ### Authentication
 
-Like Composio, tool execution requires a `userId` for per-user authorization through Arcade's auth flow.
+Like Composio, tool execution uses `resourceId` from request context for per-user authorization. The provider maps that value to the user identity required by Arcade's auth flow.

package/.docs/reference/harness/harness-class.md

@@ -98,7 +98,7 @@ await harness.sendMessage({ content: 'Hello!' })
 
 **omConfig** (`HarnessOMConfig`): Default configuration for observational memory (observer/reflector model IDs and thresholds).
 
-**disableBuiltinTools** (`BuiltinToolId[]`): Built-in harness tool IDs to remove from the \`harnessBuiltIn\` toolset. Valid values are \`ask\_user\`, \`submit\_plan\`, \`task\_write\`, \`task\_check\`, and \`subagent\`.
+**disableBuiltinTools** (`BuiltinToolId[]`): Built-in harness tool IDs to remove from the \`harnessBuiltIn\` toolset. Valid values are \`ask\_user\`, \`submit\_plan\`, \`task\_write\`, \`task\_update\`, \`task\_complete\`, \`task\_check\`, and \`subagent\`.
 
 **heartbeatHandlers** (`HeartbeatHandler[]`): Periodic background tasks started during \`init()\`. Use for gateway sync, cache refresh, and similar tasks.
 
@@ -162,6 +162,17 @@ Return the current `HarnessDisplayState` snapshot for UI rendering.
 const displayState = harness.getDisplayState()
 ```
 
+#### `restoreDisplayTasks(tasks)`
+
+Restore the task portion of `HarnessDisplayState` after a UI replays persisted task tool history. This emits `display_state_changed` without emitting a live `task_updated` event.
+
+If later task tools should read the replayed tasks, persist the same task list with `setState({ tasks })` before calling `restoreDisplayTasks(tasks)`.
+
+```typescript
+await harness.setState({ tasks: replayedTasks })
+harness.restoreDisplayTasks(replayedTasks)
+```
+
 #### `setState(updates)`
 
 Update the harness state. Validates against `stateSchema` if provided, and emits a `state_changed` event with the new state and changed keys.
@@ -831,13 +842,15 @@ The harness emits events through registered listeners. The following table lists
 
 The harness provides built-in tools to agents in every mode:
 
-| Tool          | Description                                                                                                                                                                                          |
-| ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ask_user`    | Ask the user a question and wait for their response. Supports free text, single-select choices, and multi-select choices.                                                                            |
-| `submit_plan` | Submit a plan for user review and approval.                                                                                                                                                          |
-| `task_write`  | Create or update a structured task list for tracking progress.                                                                                                                                       |
-| `task_check`  | Check the completion status of the current task list.                                                                                                                                                |
-| `subagent`    | Spawn a focused subagent with constrained tools (only available when `subagents` is configured). Pass `forked: true` to inherit the parent conversation — see [Forked subagents](#forked-subagents). |
+| Tool            | Description                                                                                                                                                                                          |
+| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ask_user`      | Ask the user a question and wait for their response. Supports free text, single-select choices, and multi-select choices.                                                                            |
+| `submit_plan`   | Submit a plan for user review and approval.                                                                                                                                                          |
+| `task_write`    | Create or replace a structured task list for tracking progress. Assigns task IDs when omitted and returns the structured task list snapshot.                                                         |
+| `task_update`   | Update one tracked task by ID and return the structured task list snapshot.                                                                                                                          |
+| `task_complete` | Mark one tracked task completed by ID and return the structured task list snapshot.                                                                                                                  |
+| `task_check`    | Check the completion status of the current task list and return `tasks`, `summary`, `incompleteTasks`, and `isError` fields.                                                                         |
+| `subagent`      | Spawn a focused subagent with constrained tools (only available when `subagents` is configured). Pass `forked: true` to inherit the parent conversation — see [Forked subagents](#forked-subagents). |
 
 ### `ask_user` selections
 

package/.docs/reference/index.md

@@ -170,6 +170,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [PromptInjectionDetector](https://mastra.ai/reference/processors/prompt-injection-detector)
 - [ProviderHistoryCompat](https://mastra.ai/reference/processors/provider-history-compat)
 - [RegexFilterProcessor](https://mastra.ai/reference/processors/regex-filter-processor)
+- [ResponseCache](https://mastra.ai/reference/processors/response-cache)
 - [SemanticRecall](https://mastra.ai/reference/processors/semantic-recall-processor)
 - [SkillSearchProcessor](https://mastra.ai/reference/processors/skill-search-processor)
 - [StreamErrorRetryProcessor](https://mastra.ai/reference/processors/stream-error-retry-processor)
@@ -198,6 +199,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [registerApiRoute()](https://mastra.ai/reference/server/register-api-route)
 - [Server Routes](https://mastra.ai/reference/server/routes)
 - [Overview](https://mastra.ai/reference/storage/overview)
+- [Aurora DSQL Storage](https://mastra.ai/reference/storage/dsql)
 - [ClickHouse Storage](https://mastra.ai/reference/storage/clickhouse)
 - [Cloudflare D1 Storage](https://mastra.ai/reference/storage/cloudflare-d1)
 - [Cloudflare KV Storage](https://mastra.ai/reference/storage/cloudflare)
@@ -222,6 +224,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.stream()](https://mastra.ai/reference/streaming/workflows/stream)
 - [.timeTravelStream()](https://mastra.ai/reference/streaming/workflows/timeTravelStream)
 - [Overview](https://mastra.ai/reference/templates/overview)
+- [Bright Data Tools](https://mastra.ai/reference/tools/brightdata)
 - [createDocumentChunkerTool()](https://mastra.ai/reference/tools/document-chunker-tool)
 - [createGraphRAGTool()](https://mastra.ai/reference/tools/graph-rag-tool)
 - [createTool()](https://mastra.ai/reference/tools/create-tool)
@@ -256,6 +259,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Events](https://mastra.ai/reference/voice/voice.events)
 - [Google](https://mastra.ai/reference/voice/google)
 - [Google Gemini Live](https://mastra.ai/reference/voice/google-gemini-live)
+- [Inworld](https://mastra.ai/reference/voice/inworld)
 - [Mastra Voice](https://mastra.ai/reference/voice/mastra-voice)
 - [Murf](https://mastra.ai/reference/voice/murf)
 - [OpenAI](https://mastra.ai/reference/voice/openai)
@@ -278,6 +282,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Run Class](https://mastra.ai/reference/workflows/run)
 - [Step Class](https://mastra.ai/reference/workflows/step)
 - [Workflow Class](https://mastra.ai/reference/workflows/workflow)
+- [Workflow State Reader](https://mastra.ai/reference/workflows/workflow-state-reader)
 - [.branch()](https://mastra.ai/reference/workflows/workflow-methods/branch)
 - [.commit()](https://mastra.ai/reference/workflows/workflow-methods/commit)
 - [.createRun()](https://mastra.ai/reference/workflows/workflow-methods/create-run)

package/.docs/reference/memory/observational-memory.md

@@ -36,7 +36,9 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **scope** (`'resource' | 'thread'`): Memory scope for observations. \`'thread'\` keeps observations per-thread. \`'resource'\` (experimental) shares observations across all threads for a resource, enabling cross-conversation memory. (Default: `'thread'`)
 
-**activateAfterIdle** (`number | string`): Time before buffered observations or buffered reflections are forced to activate after inactivity, even if their token thresholds have not been reached yet. Accepts milliseconds or duration strings like \`300\_000\`, \`"5m"\`, or \`"1hr"\`. When the gap between the current time and the last assistant message part timestamp exceeds this value, buffered observational memory activates before the next prompt. Useful for aligning with prompt cache TTLs.
+**activateAfterIdle** (`number | string | false`): Time before buffered observations are forced to activate after inactivity, even before \`observation.messageTokens\` is reached. Accepts a numeric millisecond value such as \`300\_000\`, duration strings like \`"5m"\` or \`"1hr"\`, or \`false\` to disable inherited observation idle activation. Reflections do not inherit this setting. Use \`reflection.activateAfterIdle\` to opt reflections into idle activation.
+
+**activateOnProviderChange** (`boolean`): Force buffered observations to activate when the actor provider or model changes. Reflections do not inherit this setting. Use \`reflection.activateOnProviderChange\` to opt reflections into provider-change activation. (Default: `false`)
 
 **shareTokenBudget** (`boolean`): Share the token budget between messages and observations. When enabled, the total budget is \`observation.messageTokens + reflection.observationTokens\`. Messages can use more space when observations are small, and vice versa. This maximizes context usage through flexible allocation. \`shareTokenBudget\` is not yet compatible with async buffering. You must set \`observation: { bufferTokens: false }\` when using this option (this is a temporary limitation). (Default: `false`)
 
@@ -66,6 +68,10 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **observation.bufferActivation** (`number`): Controls how much of the message window to retain after activation. Accepts a ratio (0-1) or an absolute token count (≥ 1000). For example, \`0.8\` means: activate enough buffers to remove 80% of \`messageTokens\` and leave 20% as active message history. An absolute token count like \`4000\` targets a goal of keeping \~4k message tokens remaining after activation. Higher values remove more message history per activation when using a ratio. Higher values keep more message history when using a token count.
 
+**observation.activateAfterIdle** (`number | string | false`): Time before buffered observations are forced to activate after inactivity. Accepts milliseconds, a duration string, or \`false\`. If unset, the top-level \`activateAfterIdle\` value is used for observations. Set \`false\` to disable the top-level idle setting for observations.
+
+**observation.activateOnProviderChange** (`boolean`): Force buffered observations to activate when the actor provider or model changes. If unset, the top-level \`activateOnProviderChange\` value is used for observations.
+
 **observation.blockAfter** (`number`): Token threshold above which synchronous (blocking) observation is forced. Between \`messageTokens\` and \`blockAfter\`, only async buffering/activation is used. Above \`blockAfter\`, a synchronous observation runs as a last resort, while buffered activation still preserves a minimum remaining context (min(1000, retention floor)). Accepts a multiplier (1 < value < 2, multiplied by \`messageTokens\`) or an absolute token count (≥ 2, must be greater than \`messageTokens\`). Only relevant when \`bufferTokens\` is set. Defaults to \`1.2\` when async buffering is enabled.
 
 **observation.previousObserverTokens** (`number | false`): Optional token budget for the observer's previous-observations context. When set to a number, the observations passed to the Observer agent are tail-truncated to fit within this budget while keeping the newest observations and preserving highlighted 🔴 items when possible. When a buffered reflection is pending, the already-reflected observation lines are automatically replaced with the reflection summary before truncation. Set to \`0\` to omit previous observations entirely, or \`false\` to disable truncation explicitly.
@@ -86,6 +92,10 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **reflection.bufferActivation** (`number`): Ratio (0-1) controlling when async reflection buffering starts. When observation tokens reach \`observationTokens \* bufferActivation\`, reflection runs in the background. On activation at the full threshold, the buffered reflection replaces the observations it covers, preserving any new observations appended after that range.
 
+**reflection.activateAfterIdle** (`number | string | false`): Time before buffered reflections are forced to activate after inactivity. Accepts milliseconds, a duration string, or \`false\`. Reflections do not inherit top-level \`activateAfterIdle\`; set this explicitly to opt reflections into idle activation.
+
+**reflection.activateOnProviderChange** (`boolean`): Force buffered reflections to activate when the actor provider or model changes. Reflections do not inherit top-level \`activateOnProviderChange\`; set this explicitly to opt reflections into provider-change activation.
+
 **reflection.blockAfter** (`number`): Token threshold above which synchronous (blocking) reflection is forced. Between \`observationTokens\` and \`blockAfter\`, only async buffering/activation is used. Above \`blockAfter\`, a synchronous reflection runs as a last resort. Accepts a multiplier (1 < value < 2, multiplied by \`observationTokens\`) or an absolute token count (≥ 2, must be greater than \`observationTokens\`). Only relevant when \`bufferActivation\` is set. Defaults to \`1.2\` when async reflection is enabled.
 
 ### Token estimate metadata cache

package/.docs/reference/observability/metrics/automatic-metrics.md

@@ -8,13 +8,11 @@ For setup instructions, see the [Metrics overview](https://mastra.ai/docs/observ
 
 Metrics are extracted from spans when they end. The observability layer inspects each completed span, calculates duration, and (for model generation spans) reads token usage data. No manual instrumentation is needed.
 
-Metrics are routed through an internal event bus to the `DefaultExporter`, which batches and flushes them to storage.
-
 ### What affects whether a metric is available
 
 Two conditions must be true for a metric to reach storage:
 
-1. `DefaultExporter` is configured as an exporter.
+1. `MastraStorageExporter` is configured as an exporter.
 2. The storage backend supports metrics (ClickHouse or DuckDB).
 
 If metrics aren't appearing, see [troubleshooting](#troubleshooting).
@@ -117,7 +115,7 @@ When you spot a spike in latency or token usage on the Metrics dashboard, correl
 ### No metrics are appearing
 
 - **Observability is configured**: Verify that your `Mastra` instance has an `observability` config with at least one exporter.
-- **`DefaultExporter` is present**: Other exporters (Datadog, Langfuse, etc.) don't persist metrics to Mastra storage. `DefaultExporter` is required for the Studio dashboard.
+- **`MastraStorageExporter` or `MastraPlatformExporter` is present**: Other exporters (Datadog, Langfuse, etc.) don't surface metrics in Mastra. `MastraStorageExporter` is required for the local Studio dashboard, and `MastraPlatformExporter` is required to view metrics in Mastra Platform.
 - **Storage supports metrics**: Metrics require an OLAP-capable store (ClickHouse or DuckDB). Row-oriented databases (PostgreSQL, LibSQL, MSSQL) and document stores (MongoDB) are not supported for metrics.
 - **Sampling isn't 0%**: If sampling probability is `0` or strategy is `never`, all spans become no-ops and no metrics are extracted.
 

package/.docs/reference/observability/tracing/bridges/datadog.md

@@ -129,7 +129,7 @@ The bridge can be combined with non-Datadog exporters to send traces to addition
 
 ```typescript
 import { Mastra } from '@mastra/core'
-import { Observability, DefaultExporter } from '@mastra/observability'
+import { Observability, MastraStorageExporter } from '@mastra/observability'
 import { DatadogBridge } from '@mastra/datadog'
 
 const mastra = new Mastra({
@@ -141,7 +141,7 @@ const mastra = new Mastra({
           mlApp: process.env.DD_LLMOBS_ML_APP!,
         }),
         exporters: [
-          new DefaultExporter(), // Studio access
+          new MastraStorageExporter(), // Studio access
         ],
       },
     },

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

@@ -2,7 +2,7 @@
 
 > **Warning:** The OpenTelemetry Bridge is currently **experimental**. APIs and configuration options may change in future releases.
 
-Enables bidirectional integration between Mastra tracing and OpenTelemetry infrastructure. Creates native OTEL spans for Mastra operations and inherits context from active OTEL spans.
+Enables bidirectional integration between Mastra tracing and OpenTelemetry infrastructure. Creates native OTEL spans for Mastra operations and inherits context from active OTEL spans. Also forwards Mastra log events to the globally-registered OTEL `LoggerProvider`, emitting each log under the OTEL context of the originating Mastra span so trace-log correlation works automatically.
 
 ## Constructor
 
@@ -32,7 +32,29 @@ Executes a synchronous function within the OTEL context of a Mastra span.
 
 **Returns:** `T` - The result of the function execution.
 
-### shutdown
+### `onLogEvent`
+
+```typescript
+async onLogEvent(event: LogEvent): Promise<void>
+```
+
+Forwards a Mastra log event to the globally-registered OTEL `LoggerProvider`. Trace correlation is resolved in this order:
+
+1. If the log carries a `spanId` the bridge has an OTEL span for, the log is emitted under that span's stored OTEL context.
+2. Otherwise, if the log carries `traceId` and `spanId`, those IDs are attached to the emitted log record's `SpanContext`.
+3. Otherwise, the log is emitted under whatever OTEL context is currently active.
+
+If no `LoggerProvider` is registered globally, emission is a silent no-op.
+
+### `flush`
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes the global OTEL tracer provider and logger provider if they support `forceFlush`. Useful in serverless environments where you need to drain telemetry before the runtime terminates.
+
+### `shutdown`
 
 ```typescript
 async shutdown(): Promise<void>
@@ -68,7 +90,7 @@ The bridge can be used alongside exporters. The bridge handles OTEL context, whi
 
 ```typescript
 import { Mastra } from '@mastra/core'
-import { Observability, DefaultExporter } from '@mastra/observability'
+import { Observability, MastraStorageExporter } from '@mastra/observability'
 import { OtelBridge } from '@mastra/otel-bridge'
 import { LangfuseExporter } from '@mastra/langfuse'
 
@@ -79,7 +101,7 @@ const mastra = new Mastra({
         serviceName: 'my-service',
         bridge: new OtelBridge(), // Handles OTEL context
         exporters: [
-          new DefaultExporter(), // Studio access
+          new MastraStorageExporter(), // Studio access
           new LangfuseExporter({
             // Additional destination
             publicKey: process.env.LANGFUSE_PUBLIC_KEY,

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

@@ -7,15 +7,18 @@ interface ObservabilityRegistryConfig {
   default?: { enabled?: boolean }
   configs?: Record<string, Omit<ObservabilityInstanceConfig, 'name'> | ObservabilityInstance>
   configSelector?: ConfigSelector
+  sensitiveDataFilter?: boolean | SensitiveDataFilterOptions
 }
 ```
 
-**default** (`{ enabled?: boolean }`): Enable default configuration with DefaultExporter and CloudExporter
+**default** (`{ enabled?: boolean }`): Enable default configuration with MastraStorageExporter and MastraPlatformExporter
 
 **configs** (`Record<string, Omit<ObservabilityInstanceConfig, 'name'> | ObservabilityInstance>`): Named observability instance configurations or pre-instantiated instances
 
 **configSelector** (`ConfigSelector`): Runtime configuration selector function
 
+**sensitiveDataFilter** (`boolean | SensitiveDataFilterOptions`): Controls whether a \[SensitiveDataFilter]\(/reference/observability/tracing/processors/sensitive-data-filter) is auto-applied to every configured instance. Defaults to \`true\`. Pass \`false\` to opt out, or pass a \`SensitiveDataFilterOptions\` object to customize fields, redaction token, or redaction style. If a config already includes a \`SensitiveDataFilter\` in \`spanOutputProcessors\`, it is not duplicated. Pre-instantiated instances are not modified.
+
 ## `ObservabilityInstanceConfig`
 
 ```typescript
@@ -201,8 +204,8 @@ Shuts down all observability instances and clears the registry.
 
 ### Exporters
 
-- [DefaultExporter](https://mastra.ai/reference/observability/tracing/exporters/default-exporter): Storage configuration
-- [CloudExporter](https://mastra.ai/reference/observability/tracing/exporters/cloud-exporter): Cloud setup
+- [MastraStorageExporter](https://mastra.ai/reference/observability/tracing/exporters/mastra-storage-exporter): Persists observability events to Mastra Storage
+- [MastraPlatformExporter](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter): Sends observability events to Mastra Platform
 - [Braintrust](https://mastra.ai/reference/observability/tracing/exporters/braintrust): Braintrust integration
 - [Langfuse](https://mastra.ai/reference/observability/tracing/exporters/langfuse): Langfuse integration
 - [LangSmith](https://mastra.ai/reference/observability/tracing/exporters/langsmith): LangSmith integration

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

@@ -77,7 +77,7 @@ Flushes pending data and shuts down the client.
 ```typescript
 import { ArizeExporter } from '@mastra/arize'
 
-// For Phoenix: Set PHOENIX_ENDPOINT, PHOENIX_API_KEY, PHOENIX_PROJECT_NAME
+// For Phoenix: Set PHOENIX_COLLECTOR_ENDPOINT, PHOENIX_API_KEY, PHOENIX_PROJECT_NAME
 // For Arize AX: Set ARIZE_SPACE_ID, ARIZE_API_KEY, ARIZE_PROJECT_NAME
 const exporter = new ArizeExporter()
 ```

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

@@ -15,6 +15,8 @@ interface BraintrustExporterConfig extends BaseExporterConfig {
   apiKey?: string
   endpoint?: string
   projectName?: string
+  braintrustLogger?: Logger<true>
+  currentSpan?: () => Span | undefined
   tuningParameters?: Record<string, any>
 }
 ```

package/.docs/reference/observability/tracing/exporters/cloud-exporter.md

@@ -1,6 +1,8 @@
 # CloudExporter
 
-**Added in:** `@mastra/observability@1.8.0`
+**Added in:** `@mastra/observability@1.8.0`. **Deprecated in `1.12.0`** in favor of [`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter).
+
+> **Deprecated:** `CloudExporter` is retained for backward compatibility and will be removed in a future major version. Use [`MastraPlatformExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter) for new projects. The two classes share the same constructor, environment variables, and runtime behavior; `CloudExporter` keeps its original `mastra-cloud-observability-exporter` exporter `name` and `CLOUD_EXPORTER_*` error IDs so monitoring rules built against it keep working.
 
 Sends tracing spans, logs, metrics, scores, and feedback to the Mastra platform for online visualization and monitoring.
 

package/.docs/reference/observability/tracing/exporters/console-exporter.md

@@ -124,8 +124,8 @@ const exporterWithLogger = new ConsoleExporter({
 
 ### Other 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
+- [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
 - [Langfuse](https://mastra.ai/reference/observability/tracing/exporters/langfuse): Langfuse integration
 - [Braintrust](https://mastra.ai/reference/observability/tracing/exporters/braintrust): Braintrust integration
 

package/.docs/reference/observability/tracing/exporters/default-exporter.md

@@ -1,6 +1,10 @@
 # DefaultExporter
 
-Persists traces to Mastra's configured storage with automatic batching and retry logic.
+**Deprecated in `@mastra/observability@1.12.0`** in favor of [`MastraStorageExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-storage-exporter).
+
+> **Deprecated:** `DefaultExporter` is retained for backward compatibility and will be removed in a future major version. Use [`MastraStorageExporter`](https://mastra.ai/reference/observability/tracing/exporters/mastra-storage-exporter) for new projects. The two classes share the same constructor, configuration, and runtime behavior; `DefaultExporter` keeps its original `mastra-default-observability-exporter` exporter `name` so monitoring rules built against it keep working.
+
+Persists observability events to Mastra Storage with automatic batching and retry logic.
 
 ## Constructor
 
@@ -128,6 +132,8 @@ Failed flushes are retried with exponential backoff:
 - Maximum attempts: `maxRetries`
 - Batch is dropped after all retries fail
 
+When storage does not support a signal or retries are exhausted, `DefaultExporter` emits an `ObservabilityDropEvent` through `onDroppedEvent` handlers registered on exporters and bridges. The drop event includes the signal, reason, count, exporter name, storage name when known, and sanitized error details.
+
 ### Out-of-Order Handling
 
 For `batch-with-updates` strategy:

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

@@ -0,0 +1,263 @@
+# MastraPlatformExporter
+
+**Added in:** `@mastra/observability@1.12.0`. Earlier releases (`@mastra/observability@1.8.0` through `1.11.x`) export the same exporter as the deprecated `CloudExporter`.
+
+Sends tracing spans, logs, metrics, scores, and feedback to the Mastra platform for online visualization and monitoring.
+
+> **Note:** `MastraPlatformExporter` was previously called `CloudExporter`. The original `CloudExporter` 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 `MastraPlatformExporter`.
+
+## Constructor
+
+```typescript
+new MastraPlatformExporter(config?: MastraPlatformExporterConfig)
+```
+
+## `MastraPlatformExporterConfig`
+
+```typescript
+interface MastraPlatformExporterConfig extends BaseExporterConfig {
+  /** Maximum number of buffered events per batch (spans, logs, metrics, scores, feedback). Default: 1000 */
+  maxBatchSize?: number
+
+  /** Maximum wait time before flushing in milliseconds. Default: 5000 */
+  maxBatchWaitMs?: number
+
+  /** Maximum retry attempts. Default: 3 */
+  maxRetries?: number
+
+  /** Mastra Observability access token (from env or config) */
+  accessToken?: string
+
+  /** Project ID for project-scoped collector routes (letters, numbers, hyphens, underscores) */
+  projectId?: string
+
+  /** Base observability endpoint */
+  endpoint?: string
+
+  /** Explicit traces endpoint override */
+  tracesEndpoint?: string
+
+  /** Explicit logs endpoint override */
+  logsEndpoint?: string
+
+  /** Explicit metrics endpoint override */
+  metricsEndpoint?: string
+
+  /** Explicit scores endpoint override */
+  scoresEndpoint?: string
+
+  /** Explicit feedback endpoint override */
+  feedbackEndpoint?: string
+}
+```
+
+Extends `BaseExporterConfig`, which includes:
+
+- `logger?: IMastraLogger` - Logger instance
+- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Log level (default: INFO)
+
+## Environment variables
+
+The exporter reads these environment variables if not provided in config:
+
+- `MASTRA_CLOUD_ACCESS_TOKEN` - Authentication token for `MastraPlatformExporter` requests
+- `MASTRA_PROJECT_ID` - Project ID to use when deriving project-scoped collector routes such as `/projects/:projectId/ai/spans/publish`
+- `MASTRA_CLOUD_TRACES_ENDPOINT` - Traces endpoint override. Pass either a base origin or a full traces publish URL. Defaults to `https://observability.mastra.ai` in `@mastra/observability@1.9.2` and later
+
+## Properties
+
+```typescript
+readonly name = 'mastra-platform-exporter';
+```
+
+The deprecated `CloudExporter` class continues to use `'mastra-cloud-observability-exporter'` as its `name` for backward compatibility.
+
+## Methods
+
+### `exportTracingEvent`
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Processes tracing events for export to the Mastra platform.
+
+Only `SPAN_ENDED` tracing events are exported. `SPAN_STARTED` and `SPAN_UPDATED` are ignored. Matching spans are buffered and uploaded to the traces endpoint on the next flush.
+
+**Returns:** `Promise<void>` after the tracing event has been accepted for buffering or ignored.
+
+### `onLogEvent`
+
+```typescript
+async onLogEvent(event: LogEvent): Promise<void>
+```
+
+Processes log signals for export.
+
+Every `LogEvent` passed to this handler is buffered and exported to the logs endpoint derived from the configured base endpoint. Unlike tracing, there is no additional event-status filtering at the `MastraPlatformExporter` level. If the exporter is disabled, this method becomes a no-op.
+
+**Returns:** `Promise<void>` after the log event has been accepted for buffering.
+
+### `onMetricEvent`
+
+```typescript
+async onMetricEvent(event: MetricEvent): Promise<void>
+```
+
+Processes metric signals for export.
+
+Every `MetricEvent` passed to this handler is buffered and exported to the metrics endpoint derived from the configured base endpoint. There is no additional filtering by metric subtype or status inside `MastraPlatformExporter`; the exporter forwards every metric event it receives unless it is disabled.
+
+**Returns:** `Promise<void>` after the metric event has been accepted for buffering.
+
+### `onScoreEvent`
+
+```typescript
+async onScoreEvent(event: ScoreEvent): Promise<void>
+```
+
+Processes score signals for export.
+
+Every `ScoreEvent` passed to this handler is buffered and exported to the scores endpoint derived from the configured base endpoint. There is no extra filtering at the exporter layer beyond the disabled-exporter check, so all score events received by this method are forwarded.
+
+**Returns:** `Promise<void>` after the score event has been accepted for buffering.
+
+### `onFeedbackEvent`
+
+```typescript
+async onFeedbackEvent(event: FeedbackEvent): Promise<void>
+```
+
+Processes feedback signals for export.
+
+Every `FeedbackEvent` passed to this handler is buffered and exported to the feedback endpoint derived from the configured base endpoint. There is no feedback-type filtering inside `MastraPlatformExporter`; all feedback events received here are forwarded unless the exporter is disabled.
+
+**Returns:** `Promise<void>` after the feedback event has been accepted for buffering.
+
+### flush
+
+```typescript
+async flush(): Promise<void>
+```
+
+Force flushes any buffered events to the Mastra platform 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 events and performs cleanup.
+
+## Behavior
+
+### Authentication
+
+If no access token is provided via config or environment variable, the exporter:
+
+- Logs a warning with sign-up information
+- Operates as a no-op (discards all events)
+
+### Batching
+
+The exporter batches tracing spans, logs, metrics, scores, and feedback for efficient network usage:
+
+- Flushes when total buffered event count reaches `maxBatchSize`
+- Flushes when `maxBatchWaitMs` elapsed since the first buffered signal in the batch
+- Flushes on `shutdown()`
+
+### Error handling
+
+- Uses exponential backoff retry with `maxRetries` attempts
+- Drops batches after all retries fail
+- Logs errors but continues processing new events
+
+Errors raised by `MastraPlatformExporter` use the `MASTRA_PLATFORM_EXPORTER_*` `id` prefix. The deprecated `CloudExporter` continues to emit `CLOUD_EXPORTER_*` `id`s.
+
+### Endpoint routing
+
+- Base origins derive signal endpoints automatically
+- Without `projectId`, derived routes use `/ai/{signal}/publish`
+- With `projectId` or `MASTRA_PROJECT_ID`, derived routes use `/projects/:projectId/ai/{signal}/publish`
+- Explicit full publish URLs are used as-is, even when `projectId` is configured
+
+### Signal Processing
+
+- `exportTracingEvent()` only exports `SPAN_ENDED` tracing events
+- `onLogEvent()`, `onMetricEvent()`, `onScoreEvent()`, and `onFeedbackEvent()` buffer every event they receive for their respective signal type
+- All supported signal batches are uploaded to their matching publish endpoints during `flush()` and `shutdown()`
+
+## Span wire format
+
+The shape of each span sent to Mastra Platform is documented here for reference only — it is not exported from `@mastra/observability` and should not be imported. The exporter spreads the original `AnyExportedSpan` (so the source field names are preserved) and layers a small set of platform-friendly aliases on top:
+
+```typescript
+type MastraPlatformSpanRecord = AnyExportedSpan & {
+  // Aliases derived from the source span
+  spanId: string // alias for span.id
+  spanType: string // alias for span.type
+  startedAt: Date // alias for span.startTime
+  endedAt: Date | null // alias for span.endTime ?? null
+  error: AnyExportedSpan['errorInfo'] | null
+
+  // Stamped at export time
+  createdAt: Date
+  updatedAt: Date | null
+}
+```
+
+The spread `AnyExportedSpan` also carries the original `id`, `type`, `name`, `traceId`, `parentSpanId`, `isRootSpan`, `isEvent`, `startTime`, `endTime`, `entityType`, `entityId`, `entityName`, `tags`, `attributes`, `metadata`, `input`, `output`, and `errorInfo`. See [Interfaces](https://mastra.ai/reference/observability/tracing/interfaces) for `AnyExportedSpan`.
+
+## Usage
+
+```typescript
+import { MastraPlatformExporter } from '@mastra/observability'
+
+// Uses environment variable for token
+const exporter = new MastraPlatformExporter()
+
+// Explicit configuration
+const customExporter = new MastraPlatformExporter({
+  accessToken: 'your-token',
+  projectId: 'project_123',
+  maxBatchSize: 500,
+  maxBatchWaitMs: 2000,
+  logLevel: 'debug',
+})
+```
+
+## Migrating from `CloudExporter`
+
+The two classes share the same constructor signature, environment variables, and behavior. To migrate, replace the import and constructor:
+
+```typescript
+// Before
+import { CloudExporter } from '@mastra/observability'
+const exporter = new CloudExporter()
+
+// After
+import { MastraPlatformExporter } from '@mastra/observability'
+const exporter = new MastraPlatformExporter()
+```
+
+The original `CloudExporter` is preserved unchanged so dashboards or alert rules that match the previous `CLOUD_EXPORTER_*` error IDs or `mastra-cloud-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
+
+- [MastraStorageExporter](https://mastra.ai/reference/observability/tracing/exporters/mastra-storage-exporter): Storage persistence
+- [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