@mastra/mcp-docs-server 1.1.37-alpha.1 → 1.1.37-alpha.4

package/.docs/models/providers/xpersona.md

@@ -0,0 +1,71 @@
+# ![Xpersona logo](https://models.dev/logos/xpersona.svg)Xpersona
+
+Access 1 Xpersona model through Mastra's model router. Authentication is handled automatically using the `XPERSONA_API_KEY` environment variable.
+
+Learn more in the [Xpersona documentation](https://xpersona.co/docs).
+
+```bash
+XPERSONA_API_KEY=your-api-key
+```
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: "xpersona/xpersona-frieren-coder"
+});
+
+// Generate a response
+const response = await agent.generate("Hello!");
+
+// Stream a response
+const stream = await agent.stream("Tell me a story");
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+> **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Xpersona documentation](https://xpersona.co/docs) for details.
+
+## Models
+
+| Model                             | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| --------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `xpersona/xpersona-frieren-coder` | 128K    |       |           |       |       |       | $2         | $6          |
+
+## Advanced configuration
+
+### Custom headers
+
+```typescript
+const agent = new Agent({
+  id: "custom-agent",
+  name: "custom-agent",
+  model: {
+    url: "https://xpersona.co/v1",
+    id: "xpersona/xpersona-frieren-coder",
+    apiKey: process.env.XPERSONA_API_KEY,
+    headers: {
+      "X-Custom-Header": "value"
+    }
+  }
+});
+```
+
+### Dynamic model selection
+
+```typescript
+const agent = new Agent({
+  id: "dynamic-agent",
+  name: "Dynamic Agent",
+  model: ({ requestContext }) => {
+    const useAdvanced = requestContext.task === "complex";
+    return useAdvanced
+      ? "xpersona/xpersona-frieren-coder"
+      : "xpersona/xpersona-frieren-coder";
+  }
+});
+```

package/.docs/models/providers.md

@@ -105,6 +105,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [Xiaomi Token Plan (China)](https://mastra.ai/models/providers/xiaomi-token-plan-cn)
 - [Xiaomi Token Plan (Europe)](https://mastra.ai/models/providers/xiaomi-token-plan-ams)
 - [Xiaomi Token Plan (Singapore)](https://mastra.ai/models/providers/xiaomi-token-plan-sgp)
+- [Xpersona](https://mastra.ai/models/providers/xpersona)
 - [Z.AI](https://mastra.ai/models/providers/zai)
 - [Z.AI Coding Plan](https://mastra.ai/models/providers/zai-coding-plan)
 - [ZenMux](https://mastra.ai/models/providers/zenmux)

package/.docs/reference/cli/mastra.md

@@ -600,12 +600,13 @@ It accepts [common flags](#common-flags).
 
 ## `mastra api`
 
-Calls a Mastra runtime server with JSON input and JSON output. Use it for local development servers, deployed Mastra platform projects, or self-hosted Mastra servers.
+Calls a Mastra runtime server with JSON input and JSON output. Use it for local development servers, deployed Mastra platform projects, self-hosted Mastra servers, or hosted Mastra Platform Observability APIs.
 
 ```bash
 mastra api agent list --pretty
 mastra api agent run weather-agent '{"messages":"What is the weather in London?"}'
 mastra api tool execute get-weather '{"location":"San Francisco"}'
+mastra api trace list '{"page":0,"perPage":20}' --pretty
 ```
 
 Use `mastra api <resource> <action> --help` to see examples for a command.
@@ -638,7 +639,7 @@ Errors are written to `stderr` as JSON and return a non-zero exit code:
 
 ### Target resolution
 
-The command resolves the target server in this order:
+For runtime commands, the command resolves the target server in this order:
 
 1. `--url <url>` for an explicit remote or self-hosted server.
 2. `http://localhost:4111` for a local `mastra dev` server.
@@ -646,6 +647,15 @@ The command resolves the target server in this order:
 
 Automatic platform auth is only used when the CLI resolves a Mastra platform target from `.mastra-project.json`. Localhost targets and explicit `--url` targets don't receive automatic credentials. Headers passed with `--header` are sent to any target, including localhost.
 
+For observability commands (`trace`, `log`, `score`, and `metric`), the CLI targets `https://observability.mastra.ai` by default instead of a project deployment URL. It resolves credentials in this order:
+
+1. Explicit `Authorization` and `X-Mastra-Project-Id` headers passed with `--header`.
+2. `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` from your environment.
+3. Project metadata from `.mastra-project.json` for the project ID.
+4. Your Mastra CLI login token as an auth fallback.
+
+Use `--url` and `--header` when you need to override the default hosted observability target or credentials.
+
 ### Flags
 
 #### `--url <url>`
@@ -701,6 +711,13 @@ List commands accept `page` and `perPage` in the JSON input when the target rout
 
 ```bash
 mastra api score list '{"page":0,"perPage":50}'
+mastra api trace list '{"page":0,"perPage":20}'
+```
+
+Routes that support filters accept them in the same JSON input. For example, observability trace listing supports pagination and route-supported filters:
+
+```bash
+mastra api trace list '{"page":0,"perPage":20,"filters":{"spanType":"agent"}}' --pretty
 ```
 
 ### Get command-specific help
@@ -956,14 +973,26 @@ Lists observability traces. Pass optional JSON input for route-supported filters
 
 ```bash
 mastra api trace list [input]
+mastra api trace list '{"page":0,"perPage":20}' --pretty
 ```
 
+`trace list` returns full root span records. For debugging large traces without overfetching, use `trace get` first and then fetch a specific span with `trace span` only when you need full span payloads.
+
 #### `mastra api trace get`
 
-Gets one observability trace by ID.
+Gets a lightweight timeline for one observability trace without fetching full span input, output, attributes, or metadata payloads. Pass `--verbose` to fetch the full trace payload.
 
 ```bash
 mastra api trace get <traceId>
+mastra api trace get <traceId> --verbose
+```
+
+#### `mastra api trace span`
+
+Gets one full span from an observability trace. Use this after `trace get` when you know which span you need to inspect.
+
+```bash
+mastra api trace span <traceId> <spanId>
 ```
 
 #### `mastra api log list`
@@ -974,6 +1003,88 @@ Lists observability logs. Pass optional JSON input for route-supported filters o
 mastra api log list [input]
 ```
 
+#### `mastra api metric aggregate`
+
+Gets a single aggregate metric value.
+
+```bash
+mastra api metric aggregate '{"name":["latency_ms"],"aggregation":"avg"}'
+```
+
+#### `mastra api metric breakdown`
+
+Gets metric values grouped by a label or field.
+
+```bash
+mastra api metric breakdown '{"name":["latency_ms"],"aggregation":"avg","groupBy":["model"],"limit":10}'
+```
+
+#### `mastra api metric timeseries`
+
+Gets metric values over time.
+
+```bash
+mastra api metric timeseries '{"name":["latency_ms"],"aggregation":"avg","interval":"1h"}'
+```
+
+#### `mastra api metric percentiles`
+
+Gets metric percentile values over time. Percentile values use decimals from `0` to `1`.
+
+```bash
+mastra api metric percentiles '{"name":"latency_ms","percentiles":[0.5,0.95,0.99],"interval":"1h"}'
+```
+
+#### `mastra api metric names`
+
+Lists discovered metric names. Pass optional JSON input for prefix search and limit.
+
+```bash
+mastra api metric names '{"prefix":"lat","limit":10}'
+```
+
+#### `mastra api metric label-keys`
+
+Lists label keys for a metric.
+
+```bash
+mastra api metric label-keys '{"metricName":"latency_ms"}'
+```
+
+#### `mastra api metric label-values`
+
+Lists label values for a metric label key. Pass optional prefix and limit values to narrow the result.
+
+```bash
+mastra api metric label-values '{"metricName":"latency_ms","labelKey":"model","prefix":"g","limit":10}'
+```
+
+#### Observability with `curl`
+
+You can call the hosted observability API directly with your platform access token and project ID:
+
+```bash
+curl -sS "https://observability.mastra.ai/api/observability/traces?page=0&perPage=20" \
+  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
+  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq
+```
+
+Get a lightweight trace timeline:
+
+```bash
+curl -sS "https://observability.mastra.ai/api/observability/traces/<trace-id>/light" \
+  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
+  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq
+```
+
+Get a specific span:
+
+```bash
+curl -sS "https://observability.mastra.ai/api/observability/traces/<trace-id>/spans/<span-id>" \
+  -H "Authorization: Bearer $MASTRA_PLATFORM_ACCESS_TOKEN" \
+  -H "X-Mastra-Project-Id: $MASTRA_PROJECT_ID" | jq
+```
+
 #### `mastra api score create`
 
 Creates an observability score. The input uses the server score body shape; inspect it with `--schema`.

package/.docs/reference/index.md

@@ -267,6 +267,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [PlayAI](https://mastra.ai/reference/voice/playai)
 - [Sarvam](https://mastra.ai/reference/voice/sarvam)
 - [Speechify](https://mastra.ai/reference/voice/speechify)
+- [xAI Realtime](https://mastra.ai/reference/voice/xai-realtime)
 - [.addInstructions()](https://mastra.ai/reference/voice/voice.addInstructions)
 - [.addTools()](https://mastra.ai/reference/voice/voice.addTools)
 - [.answer()](https://mastra.ai/reference/voice/voice.answer)

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

@@ -4,75 +4,83 @@ The `Processor` interface defines the contract for all processors in Mastra. Pro
 
 ## When processor methods run
 
-The seven processor methods run at different points in the agent execution lifecycle:
+The eight processor methods run at different points in the agent execution lifecycle:
 
 ```text
-┌─────────────────────────────────────────────────────────────────┐
-│                     Agent Execution Flow                        │
-├─────────────────────────────────────────────────────────────────┤
-│                                                                 │
-│  User Input                                                     │
-│      │                                                          │
-│      ▼                                                          │
-│  ┌─────────────────┐                                            │
-│  │  processInput   │  ← Runs ONCE at start                      │
-│  └────────┬────────┘                                            │
-│           │                                                     │
-│           ▼                                                     │
-│  ┌─────────────────────────────────────────────────────────┐    │
-│  │                   Agentic Loop                          │    │
-│  │  ┌─────────────────────┐                                │    │
-│  │  │  processInputStep   │  ← Runs at EACH step           │    │
-│  │  └──────────┬──────────┘                                │    │
-│  │             │                                           │    │
-│  │             ▼                                           │    │
-│  │  ┌─────────────────────┐                                │    │
-│  │  │  processLLMRequest   │  ← Runs before provider call   │    │
-│  │  └──────────┬──────────┘                                │    │
-│  │             │                                           │    │
-│  │             ▼                                           │    │
-│  │       LLM Execution ──── API Error? ──┐                │    │
-│  │             │                          │                │    │
-│  │             │              ┌───────────────────┐        │    │
-│  │             │              │  processAPIError  │        │    │
-│  │             │              └─────────┬─────────┘        │    │
-│  │             │                 retry? └── Loop back ──┐  │    │
-│  │             ▼                                        │  │    │
-│  │  ┌──────────────────────┐                            │  │    │
-│  │  │ processOutputStream  │  ← Runs on EACH stream chunk  │    │
-│  │  └──────────┬───────────┘                               │    │
-│  │             │                                           │    │
-│  │             ▼                                           │    │
-│  │  ┌──────────────────────┐                               │    │
-│  │  │  processOutputStep   │  ← Runs after EACH LLM step   │    │
-│  │  └──────────┬───────────┘                               │    │
-│  │             │                                           │    │
-│  │             ▼                                           │    │
-│  │     Tool Execution (if needed)                          │    │
-│  │             │                                           │    │
-│  │             └──────── Loop back if tools called ────────│    │
-│  └─────────────────────────────────────────────────────────┘    │
-│           │                                                     │
-│           ▼                                                     │
-│  ┌─────────────────────┐                                        │
-│  │ processOutputResult │  ← Runs ONCE after completion          │
-│  └─────────────────────┘                                        │
-│           │                                                     │
-│           ▼                                                     │
-│     Final Response                                              │
-│                                                                 │
-└─────────────────────────────────────────────────────────────────┘
+┌────────────────────────────────────────────────────────────────────┐
+│                        Agent Execution Flow                        │
+├────────────────────────────────────────────────────────────────────┤
+│                                                                    │
+│  User Input                                                        │
+│      │                                                             │
+│      ▼                                                             │
+│  ┌────────────────────────┐                                        │
+│  │  processInput          │  ← Runs ONCE at start                  │
+│  └───────────┬────────────┘                                        │
+│              │                                                     │
+│              ▼                                                     │
+│  ┌──────────────────────────────────────────────────────────────┐  │
+│  │                        Agentic Loop                          │  │
+│  │                                                              │  │
+│  │  ┌────────────────────────┐                                  │  │
+│  │  │  processInputStep      │  ← Runs at EACH step             │  │
+│  │  └───────────┬────────────┘                                  │  │
+│  │              │                                               │  │
+│  │              ▼                                               │  │
+│  │  ┌────────────────────────┐                                  │  │
+│  │  │  processLLMRequest     │  ← Before provider call          │  │
+│  │  └───────────┬────────────┘                                  │  │
+│  │              │                                               │  │
+│  │              ▼                                               │  │
+│  │        LLM Execution ──── API Error? ───┐                    │  │
+│  │              │                          │                    │  │
+│  │              │              ┌───────────┴──────────┐         │  │
+│  │              │              │  processAPIError     │         │  │
+│  │              │              └──────────────────────┘         │  │
+│  │              │                (retry loops back to LLM)      │  │
+│  │              ▼                                               │  │
+│  │  ┌────────────────────────┐                                  │  │
+│  │  │  processOutputStream   │  ← Runs on EACH stream chunk     │  │
+│  │  └───────────┬────────────┘                                  │  │
+│  │              │                                               │  │
+│  │              ▼                                               │  │
+│  │  ┌────────────────────────┐                                  │  │
+│  │  │  processLLMResponse    │  ← After stream completes        │  │
+│  │  └───────────┬────────────┘                                  │  │
+│  │              │                                               │  │
+│  │              ▼                                               │  │
+│  │  ┌────────────────────────┐                                  │  │
+│  │  │  processOutputStep     │  ← Runs after EACH LLM step      │  │
+│  │  └───────────┬────────────┘                                  │  │
+│  │              │                                               │  │
+│  │              ▼                                               │  │
+│  │        Tool Execution (if needed)                            │  │
+│  │              │                                               │  │
+│  │              └──────── Loop back if tools called ────────────│  │
+│  │                                                              │  │
+│  └──────────────────────────────────────────────────────────────┘  │
+│              │                                                     │
+│              ▼                                                     │
+│  ┌────────────────────────┐                                        │
+│  │  processOutputResult   │  ← Runs ONCE after completion          │
+│  └────────────────────────┘                                        │
+│              │                                                     │
+│              ▼                                                     │
+│        Final Response                                              │
+│                                                                    │
+└────────────────────────────────────────────────────────────────────┘
 ```
 
-| 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                                                     |
+| 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                                  |
+| `processLLMResponse`  | After the LLM step completes and stream chunks are collected | Capture or cache the full response, run post-call side effects paired with `processLLMRequest` |
+| `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
 
@@ -107,6 +115,10 @@ interface Processor<TId extends string = string, TTripwireMetadata = unknown> {
     args: ProcessLLMRequestArgs<TTripwireMetadata>,
   ): Promise<ProcessLLMRequestResult> | ProcessLLMRequestResult
 
+  processLLMResponse?(
+    args: ProcessLLMResponseArgs<TTripwireMetadata>,
+  ): Promise<ProcessLLMResponseResult> | ProcessLLMResponseResult
+
   processAPIError?(
     args: ProcessAPIErrorArgs<TTripwireMetadata>,
   ): Promise<ProcessAPIErrorResult | void> | ProcessAPIErrorResult | void
@@ -255,8 +267,11 @@ processInputStep?<TTripwireMetadata = unknown>(
 3. `prepareStep` callback (runs as part of the processInputStep pipeline, after inputProcessors)
 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
+6. `processOutputStream` from outputProcessors (on each streaming chunk)
+7. `processLLMResponse` from inputProcessors (after stream completes, pairs with `processLLMRequest`)
+8. `processOutputStep` from outputProcessors (after LLM response, before tool execution)
+9. Tool execution (if needed)
+10. Repeat from step 2 if tools were called
 
 #### `ProcessInputStepArgs`
 
@@ -401,6 +416,62 @@ processLLMRequest?(
 
 ***
 
+### `processLLMResponse`
+
+Processes the LLM response after the step completes (or after a cached response is replayed) and after output processors have collected the response chunks. This hook pairs with `processLLMRequest`: use `processLLMRequest` to stash state (such as a cache key) before the provider call, and `processLLMResponse` to act on the completed response (such as writing it to a cache).
+
+The `state` object is the same instance passed to `processLLMRequest` for the same step, so processors can correlate pre- and post-call work.
+
+```typescript
+processLLMResponse?(
+  args: ProcessLLMResponseArgs,
+): Promise<ProcessLLMResponseResult> | ProcessLLMResponseResult;
+```
+
+#### `ProcessLLMResponseArgs`
+
+**chunks** (`CachedLLMStepChunk[]`): Chunks produced by the LLM call (or replayed from cache) for this step, in stripped form (\`{ type, payload }\`).
+
+**model** (`MastraLanguageModel`): The model that produced (or would have produced) the response.
+
+**stepNumber** (`number`): Current step number (0-indexed).
+
+**steps** (`StepResult[]`): All completed steps so far, including this step.
+
+**state** (`Record<string, unknown>`): Per-processor state shared with \`processLLMRequest\` for the same step. Use this to pass data between the two hooks (e.g. a cache key).
+
+**fromCache** (`boolean`): When \`true\`, the response was replayed from a cache via \`processLLMRequest\` returning \`{ response }\`. Processors that write to a cache should skip writes when this is \`true\`.
+
+**warnings** (`LanguageModelV2CallWarning[]`): Warnings reported by the language model call (e.g. unsupported settings).
+
+**request** (`unknown`): Provider request body, when available. Useful for tracing.
+
+**rawResponse** (`unknown`): Raw provider response, when available. Useful for tracing.
+
+**abort** (`(reason?: string, options?: { retry?: boolean; metadata?: unknown }) => never`): Function to abort processing. Throws a TripWire error that stops execution.
+
+**retryCount** (`number`): Current retry attempt count. 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.
+
+**abortSignal** (`AbortSignal`): Signal for cancelling the operation.
+
+#### Return value
+
+`processLLMResponse` returns `ProcessLLMResponseResult`, which is `undefined | void`. The return value is reserved for future extensibility.
+
+#### Use cases
+
+- Writing LLM responses to a cache after a live call (paired with cache-key derivation in `processLLMRequest`)
+- Logging or recording the full response for analytics
+- Triggering side effects based on the completed response
+
+***
+
 ### `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.
@@ -628,8 +699,14 @@ export class QualityGuardrail implements Processor {
 Mastra provides type aliases to ensure processors implement the required methods:
 
 ```typescript
-// Must implement processInput OR processInputStep (or both)
-type InputProcessor = Processor & ({ processInput: required } | { processInputStep: required })
+// Must implement processInput, processInputStep, processLLMRequest, or processLLMResponse (or any combination)
+type InputProcessor = Processor &
+  (
+    | { processInput: required }
+    | { processInputStep: required }
+    | { processLLMRequest: required }
+    | { processLLMResponse: required }
+  )
 
 // Must implement processOutputStream, processOutputStep, OR processOutputResult (or any combination)
 type OutputProcessor = Processor &
@@ -813,11 +890,11 @@ export class WordCounter implements Processor {
 
 ## State lifecycle
 
-Every processor receives a `state` object in `processOutputStream`, `processOutputStep`, `processOutputResult`, and `processAPIError`. State has three important properties:
+Every processor receives a `state` object in `processLLMRequest`, `processLLMResponse`, `processOutputStream`, `processOutputStep`, `processOutputResult`, and `processAPIError`. State has three important properties:
 
 - **Per-processor**: Each processor gets its own `state` object, keyed by the processor's `id`. Two processors with different ids cannot read or overwrite each other's state.
 - **Per-request**: A fresh state object is created at the start of every `agent.generate()` or `agent.stream()` call. State does not leak between requests or between users.
-- **Shared across methods**: Within one request, the same `state` object is passed to `processOutputStream` (for every chunk), `processOutputStep` (after every LLM step), `processOutputResult` (once at the end), and `processAPIError` (when an LLM call fails). Accumulate data in `processOutputStream` and read it in `processOutputResult` or `processAPIError`.
+- **Shared across methods**: Within one request, the same `state` object is passed to `processLLMRequest` (before the provider call), `processLLMResponse` (after the step completes), `processOutputStream` (for every chunk), `processOutputStep` (after every LLM step), `processOutputResult` (once at the end), and `processAPIError` (when an LLM call fails). For example, `processLLMRequest` can stash a cache key and `processLLMResponse` can read it back to write the response.
 
 Initialize fields defensively on first access, because `state` starts as an empty object: