@mastra/mcp-docs-server 1.2.26 → 1.2.27-alpha.11

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

@@ -1079,6 +1079,90 @@ See the [Storage migration guide](https://mastra.ai/reference/migrations/upgrade
 
 It accepts [common flags](#common-flags).
 
+## `mastra traces import`
+
+Imports historical traces from a supported observability provider into an existing Mastra Platform project. The command prepares complete traces locally, uploads whole-trace batches, supports resume, and verifies a sample through Mastra Platform.
+
+```bash
+mastra traces import <provider> [options]
+```
+
+The following provider is currently supported:
+
+| Provider | Argument   | Requirements                                       |
+| -------- | ---------- | -------------------------------------------------- |
+| Langfuse | `langfuse` | Langfuse Cloud or self-hosted Langfuse v4 or later |
+
+See [Import existing traces](https://mastra.ai/docs/mastra-platform/observability) for the complete workflow, data mapping, local-file lifecycle, and limits.
+
+### Options
+
+#### `--project <name|slug|id>`
+
+Selects the destination Mastra Platform project. `MASTRA_PROJECT_ID` takes precedence when set. Without either value, the command uses the project linked in `.mastra-project.json`.
+
+#### `--from <date>`
+
+Sets the inclusive start of the import window as an ISO 8601 date or timestamp. It defaults to 30 days before `--to`, clamped to the current 30-day Platform retention boundary.
+
+#### `--to <date>`
+
+Sets the exclusive end of the import window as an ISO 8601 date or timestamp. It defaults to the time when the import starts and can't be in the future.
+
+The complete window must fall within the current 30-day Platform retention period, `--from` must be earlier than `--to`, and the window can't exceed 30 days.
+
+#### `--dry-run`
+
+Reads the source and prepares valid traces locally without uploading them. The command writes a report and prints a command that resumes the prepared import.
+
+#### `--resume <import-id>`
+
+Resumes a prepared import using its saved provider, destination project, date window, and acknowledged progress. Use the same destination project shown in the generated resume command. This option can't be combined with `--from`, `--to`, or `--dry-run`.
+
+#### `-y, --yes`
+
+Uploads without asking for confirmation.
+
+### Environment variables
+
+The command loads `.env` and `.env.local` from the current directory.
+
+| Variable                       | Required                                        | Description                                                                                                       |
+| ------------------------------ | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `LANGFUSE_PUBLIC_KEY`          | For new Langfuse imports                        | Public project API key.                                                                                           |
+| `LANGFUSE_SECRET_KEY`          | For new Langfuse imports                        | Secret project API key.                                                                                           |
+| `LANGFUSE_BASE_URL`            | No                                              | Langfuse host. Defaults to `https://cloud.langfuse.com`.                                                          |
+| `MASTRA_API_TOKEN`             | For headless authentication                     | Mastra Platform API token. Without it, the command uses credentials from `mastra auth login`.                     |
+| `MASTRA_ORG_ID`                | With `MASTRA_API_TOKEN`                         | Organization that owns the destination project.                                                                   |
+| `MASTRA_PLATFORM_ACCESS_TOKEN` | For upload and read-back with interactive login | Mastra Platform access token for the destination. Not required for `--dry-run` or when `MASTRA_API_TOKEN` is set. |
+| `MASTRA_PROJECT_ID`            | When no project is otherwise linked             | Destination project ID. Takes precedence over `--project`.                                                        |
+
+### Examples
+
+Preview the default 30-day window without uploading:
+
+```bash
+mastra traces import langfuse --project my-project --dry-run
+```
+
+Import a smaller date window without a confirmation prompt:
+
+```bash
+mastra traces import langfuse \
+  --project my-project \
+  --from "$FROM" \
+  --to "$TO" \
+  --yes
+```
+
+Resume an existing import:
+
+```bash
+mastra traces import langfuse \
+  --resume 00000000-0000-0000-0000-000000000000 \
+  --project my-project
+```
+
 ## `mastra api`
 
 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.

package/.docs/reference/client-js/agents.md

@@ -119,6 +119,31 @@ while (true) {
 }
 ```
 
+#### Cancelling a stream
+
+Cancelling the response body aborts the underlying HTTP request and stops any pending client tool executions and follow-up requests:
+
+```typescript
+const response = await agent.stream('Tell me a story')
+const reader = response.body.getReader()
+
+const { value } = await reader.read()
+await reader.cancel('user navigated away')
+```
+
+You can also pass an `abortSignal` to cancel from outside the stream. The same option is available on `streamUntilIdle()`, `resumeStream()`, `resumeStreamUntilIdle()`, `approveToolCall()`, `declineToolCall()`, `generate()`, and `generateLegacy()`:
+
+```typescript
+const controller = new AbortController()
+
+const response = await agent.stream('Tell me a story', {
+  abortSignal: controller.signal,
+})
+
+// Later
+controller.abort()
+```
+
 #### AI SDK compatible format
 
 To stream AI SDK-formatted parts on the client from an `agent.stream(...)` response, wrap `response.processDataStream` into a `ReadableStream<ChunkType>` and use `toAISdkStream`:

package/.docs/reference/client-js/mastra-client.md

@@ -81,7 +81,7 @@ You can also pass `requestContext` as a `Record<string, any>`.
 
 **getWorkflow(workflowId)** (`Workflow`): Retrieves a specific workflow instance by ID.
 
-**getAgentBuilderActions()** (`Promise<Record<string, WorkflowInfo>>`): Returns all available Agent Builder actions. See Agent Builder API.
+**getAgentBuilderActions()** (`Promise<GetAgentBuilderActionsResponse>`): Returns all available Agent Builder actions. See Agent Builder API.
 
 **getAgentBuilderAction(actionId)** (`AgentBuilder`): Retrieves an Agent Builder action by ID. See Agent Builder API.
 

package/.docs/reference/client-js/observability.md

@@ -65,9 +65,9 @@ const selected = await mastraClient.getTrace(list.spans[0].traceId)
 
 It accepts the same filtering, ordering and delta-polling arguments as `listTraces()`. Use `listTraces()` when you actually need the full span payloads.
 
-## Querying traces with recursive predicates
+## Querying traces and threads
 
-`queryTraces()` finds completed logical traces using trace fields and conditions over related spans or scores. Every query requires an ISO timestamp range of at most 31 days.
+`queryTraces()` finds completed logical traces using trace fields and conditions over related spans, scores, or feedback. Every query requires an ISO timestamp range of at most 31 days.
 
 ```typescript
 const result = await mastraClient.queryTraces({
@@ -89,9 +89,106 @@ const result = await mastraClient.queryTraces({
 })
 ```
 
-The API limits predicate depth, nodes, related clauses, set members, literal bytes, and the total literal budget before storage execution. Cursor pages are deterministic but aren't a database snapshot, so signals written between requests can change later pages. PostgreSQL and ClickHouse queries have a configurable 15-second execution timeout.
+### Discover trace-query fields and values
 
-See [Advanced trace queries](https://mastra.ai/reference/observability/tracing/trace-query) for the complete limits, request fields, predicates, grouping, cursor pagination, response shapes, and errors.
+`getTraceQueryFields()` returns canonical query fields and observed top-level string metadata fields for one predicate scope. The response includes each field's value kind, supported operators, and whether value suggestions are available.
+
+```typescript
+const timeRange = {
+  from: '2026-08-01T00:00:00.000Z',
+  to: '2026-08-08T00:00:00.000Z',
+}
+
+const fields = await mastraClient.getTraceQueryFields({
+  timeRange,
+  predicateScope: 'spans',
+  search: 'model',
+  limit: 25,
+})
+```
+
+Use the exact local path from the response with the same scope. For example, `model` belongs inside a `spans.some` or `spans.none` predicate. A global picker can fetch `trace`, `spans`, `scores`, and `feedback` in parallel.
+
+Call `getTraceQueryValues()` only after selecting a field with `valueSuggestions: true`:
+
+```typescript
+const controller = new AbortController()
+
+const values = await mastraClient.getTraceQueryValues(
+  {
+    timeRange,
+    predicateScope: 'spans',
+    path: 'model',
+    search: 'claude',
+    limit: 25,
+  },
+  { signal: controller.signal },
+)
+
+// Cancel this autocomplete request when the search text changes.
+controller.abort()
+```
+
+Both methods use case-insensitive literal substring search and accept an empty search. Limits default to 25 and can't exceed 100. Results are ordered by occurrence count, then deterministically by path or value. `observedFieldsTruncated` and `valuesTruncated` indicate that the caller should refine `search`. Discovery has no cursor.
+
+Suggestions are bounded and advisory. Manual values remain valid when suggestions are unavailable, empty, or truncated. Discovery doesn't accept a draft query predicate. The client doesn't retry either request, and a per-call `AbortSignal` takes precedence over the signal configured on `MastraClient`.
+
+A discovery timeout rejects with `504 TRACE_QUERY_EXECUTION_TIMEOUT`. Backend memory or resource exhaustion rejects with `503 TRACE_QUERY_RESOURCE_LIMIT`. Neither error contains partial suggestions; truncation flags are only present on successful, completely ranked responses.
+
+`queryTraceThreads()` returns thread identities derived from observability traces after applying eligibility and cross-trace conditions. It doesn't read or return memory thread records or messages. In this example, one production trace can have the low factuality score while another production trace in the same thread has the clinician correction:
+
+```typescript
+const result = await mastraClient.queryTraceThreads({
+  traces: {
+    timeRange: {
+      from: '2026-08-01T00:00:00.000Z',
+      to: '2026-08-08T00:00:00.000Z',
+    },
+    where: {
+      op: 'eq',
+      left: { path: 'environment' },
+      right: { literal: 'production' },
+    },
+  },
+  where: {
+    op: 'and',
+    args: [
+      {
+        traces: {
+          some: {
+            scores: {
+              some: {
+                op: 'lt',
+                left: { path: 'score' },
+                right: { literal: 0.6 },
+              },
+            },
+          },
+        },
+      },
+      {
+        traces: {
+          some: {
+            feedback: {
+              some: {
+                op: 'eq',
+                left: { path: 'feedbackType' },
+                right: { literal: 'clinician-correction' },
+              },
+            },
+          },
+        },
+      },
+    ],
+  },
+})
+
+// { threads: [{ threadId: 'thread-123' }], page: { next: null } }
+```
+
+The API limits predicate depth, nodes, related clauses, set members, literal bytes, and the total literal budget before storage execution. Cursor pages are deterministic but aren't a database snapshot, so signals written between requests can change later pages. PostgreSQL and ClickHouse trace and thread queries have a configurable 15-second execution timeout.
+
+See [Advanced trace queries](https://mastra.ai/reference/observability/tracing/trace-query) for the complete limits, request fields, predicates, thread qualification semantics, cursor pagination, response shapes, and errors.
 
 ## Deleting traces
 

package/.docs/reference/code-sdk/mount-agent-controller.md

@@ -94,6 +94,29 @@ const { controller } = await mountAgentControllerOnMastra({ mastra })
 
 **authStorage** (`AuthStorage`): Credential storage used by the built-in model gateway.
 
+## Nested controllers in plugins
+
+A plugin that boots another controller in the same process must borrow the host's storage instead of opening the same database files with its own native SQLite library.
+
+### `context.getStorage()`
+
+The optional accessor on `MastraCodePluginContext` returns the host's `storage` (`MastraCompositeStore`), `storageBackend` (`'libsql' | 'pg'`), and optional `vector` (`MastraVector`). Call it when the tool runs, then pass the returned object to `bootLocalAgentController()`:
+
+```typescript
+import { bootLocalAgentController } from '@mastra/code-sdk'
+import type { MastraCodePluginContext } from '@mastra/code-sdk/plugin'
+
+async function bootNestedController(context: MastraCodePluginContext) {
+  const sharedStorage = context.getStorage?.()
+  if (!sharedStorage) {
+    throw new Error('This plugin requires host-provided shared storage.')
+  }
+  return bootLocalAgentController({ cwd: context.cwd, ...sharedStorage })
+}
+```
+
+The host owns these instances. Stop the nested controller's workers and destroy its controller when finished, but don't close the borrowed stores or invoke its storage-maintenance methods. If the accessor is unavailable on an older host, don't fall back to opening the same database files.
+
 ## Related
 
 - [AgentController class](https://mastra.ai/reference/agent-controller/agent-controller-class)

package/.docs/reference/core/getMCPServer.md

@@ -38,6 +38,53 @@ const serverById = mastra.getMCPServerById('my-mcp-server')
 
 **server** (`MCPServerBase | undefined`): The MCP server instance with the specified registry key, or undefined if not found.
 
+## MCP 1.x and 2026-07-28 servers
+
+Both `@mastra/mcp` 1.x and 2.x servers extend the same `MCPServerBase` from `@mastra/core/mcp`. A 2.x server sets `mcpVersion` to `2`, while 1.x servers leave it undefined and need no new properties or methods. The differences are limited to what the 2026-07-28 protocol changed: `startSSE` and `startHonoSSE` are no longer abstract and throw unless a 1.x server overrides them (only 1.x implements the standalone SSE transport, and both are deprecated), and a server with `mcpVersion` set to `2` resolves `executeTool` to a `MCPToolExecutionResultV2` that reports a suspended tool rather than a bare result.
+
+The 1.x-only surfaces are marked `@deprecated` and are removed in the next major release of `@mastra/core`: `startSSE`, `startHonoSSE`, `MCPServerSSEOptions`, `MCPServerHonoSSEOptions`, `MCPServerHTTPOptions.options`, and on `context.mcp` the members `elicitation`, `extra.sendNotification` and `extra.sendRequest`.
+
+### Tools that ask for input
+
+A 2026-07-28 server runs ordinary `createTool` definitions. A tool that needs something from the user before it can finish declares `suspendSchema` and `resumeSchema` and calls `suspend()`, exactly as it would for an agent or a workflow. Core reports the suspension as `{ status: 'suspended', suspendPayload, resumeSchema }` from `executeTool`. An `@mastra/mcp` 2.x server turns that into an `input_required` round on the wire, and resumes the tool with the answer in `resumeData`.
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+const confirm = createTool({
+  id: 'confirm',
+  description: 'Ask for confirmation before charging',
+  inputSchema: z.object({ amount: z.number() }),
+  outputSchema: z.boolean(),
+  suspendSchema: z.object({ phase: z.literal('confirm'), amount: z.number() }),
+  resumeSchema: z.object({ confirmed: z.boolean() }),
+  execute: async ({ amount }, context) => {
+    if (!context.resumeData) {
+      await context.suspend?.({ phase: 'confirm', amount })
+      return
+    }
+    return context.resumeData.confirmed
+  },
+})
+```
+
+On a 2026-07-28 server and in direct execution, `suspend`, `resumeData` and `suspendPayload` sit at the top level of the tool context. Agents and workflows still nest them under `context.agent` and `context.workflow` until the next major release of `@mastra/core`. `resumeSchema` must be a flat object of primitive fields so it can be presented as an input form.
+
+Each round is a separate request. `resumeData` carries only the current round's answer, validated against `resumeSchema`, and `suspendPayload` carries what the tool last suspended with. Because the framework never replays earlier rounds, handlers branch on explicit named phases, every round is re-authorized, and writes rely on domain-owned idempotency. `suspendPayload` is also handed back to tools resumed by agents and workflows.
+
+### The `mcp` context
+
+Both server versions hand a tool the same `context.mcp` (`MCPToolExecutionContext`): `extra` with the request's `signal`, `requestId`, `authInfo` and `_meta`, plus `log(level, message, data?)` and `progress({ progress, total?, message? })`. A tool that only uses these works unchanged on either version. A 2026-07-28 server also sets `context.mcp.protocolVersion` to `'2026-07-28'`.
+
+The 2026-07-28 protocol removed server-initiated requests, so on a 2.x server the deprecated members `elicitation.sendRequest`, `extra.sendRequest` and `extra.sendNotification` throw with a message naming the replacement instead of doing nothing. A 1.x server keeps providing them as before. To ask the user for input, call `context.suspend()` and read `context.resumeData`.
+
+### Registration and execution
+
+Tools are registered on the Mastra instance exactly as a 1.x server registers them. On a server with `mcpVersion` set to `2`, `executeTool(toolId, args, context?)` returns `{ status: 'completed', output }` or, when the tool suspended, `{ status: 'suspended', suspendPayload, resumeSchema }` with `resumeSchema` as JSON Schema. The result has no failure variant: a tool that throws, or input or resume data that fails its schema, rejects the promise. Shared REST execution endpoints return the suspended shape instead of pretending the tool finished, and accept `resumeData` plus the echoed `suspendPayload` on the next call to continue the tool. Legacy SSE routes remain available only to 1.x servers. A server with `mcpVersion` set to `2` gets a 404 there.
+
+Registering another server under an occupied registry key keeps the existing instance. Registry keys and intrinsic server IDs remain distinct.
+
 ## Related methods
 
 - [Mastra.getMCPServerById()](https://mastra.ai/reference/core/getMCPServerById): Retrieve an MCP server by its intrinsic `id` property

package/.docs/reference/core/mastra-class.md

@@ -131,7 +131,7 @@ Visit the [Configuration reference](https://mastra.ai/reference/configuration) f
 
 **recovery** (`MastraRecoveryConfig`): Boot-time recovery behavior for orphaned agent and workflow runs. See Crash recovery. (Default: `{ durableAgents: 'off' }`)
 
-**recovery.durableAgents** (`'auto' | 'off'`): Set to 'auto' to automatically re-drive orphaned RUNNING durable agent runs on server boot. Recovery re-issues LLM calls and re-executes tool calls, so tools must be idempotent. See Crash recovery.
+**recovery.durableAgents** (`'auto' | 'off'`): Set to 'auto' to automatically re-drive orphaned RUNNING durable agent runs on server boot. This also controls the default snapshot-persistence policy for durable agents: running checkpoints are only written when set to 'auto' (or when an agent sets a custom shouldPersistSnapshot that includes running). Recovery re-issues LLM calls and re-executes tool calls, so tools must be idempotent. See Crash recovery.
 
 ## Methods
 

package/.docs/reference/index.md

@@ -352,6 +352,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Task tools](https://mastra.ai/reference/tools/task-tools)
 - [Amazon S3 Vector Store](https://mastra.ai/reference/vectors/s3vectors)
 - [Astra Vector Store](https://mastra.ai/reference/vectors/astra)
+- [Azure AI Search Vector Store](https://mastra.ai/reference/vectors/azure-ai-search)
 - [Chroma Vector Store](https://mastra.ai/reference/vectors/chroma)
 - [Cloudflare Vector Store](https://mastra.ai/reference/vectors/vectorize)
 - [Convex Vector Store](https://mastra.ai/reference/vectors/convex)
@@ -368,6 +369,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Qdrant Vector Store](https://mastra.ai/reference/vectors/qdrant)
 - [Turbopuffer Vector Store](https://mastra.ai/reference/vectors/turbopuffer)
 - [Upstash Vector Store](https://mastra.ai/reference/vectors/upstash)
+- [Weaviate Vector Store](https://mastra.ai/reference/vectors/weaviate)
 - [Overview](https://mastra.ai/reference/voice/overview)
 - [Composite Voice](https://mastra.ai/reference/voice/composite-voice)
 - [Events](https://mastra.ai/reference/voice/voice.events)

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

@@ -41,6 +41,8 @@ export const agent = new Agent({
 
 **options.lastMessages** (`number | false`): Number of most recent messages to include in context. Set to false to disable the message history feature entirely (messages are not loaded into context or saved). Use Number.MAX\_SAFE\_INTEGER to retrieve all messages with no limit. To load messages without saving new ones, use the readOnly option. The window slides forward on every request, so once a thread exceeds the limit, each turn invalidates the provider prompt cache. For long-running conversations, use Observational Memory instead.
 
+**options.messageHistory** (`{ maxTokens: number; atMaxRemoveTokens?: number }`): Token budget for the complete prompt, including remembered history, system instructions, context, and the current turn. When the prompt exceeds maxTokens, the oldest remembered messages are dropped until the prompt is at most maxTokens - atMaxRemoveTokens (defaults to 25% of maxTokens). Protected content is never removed. Linked tool calls and results are removed together. During agent runs, trimmed history is excluded from later turns via a persisted per-thread boundary, but the messages themselves stay in storage. When set without an explicit lastMessages, the default 10-message cap is not applied. Set maxTokens to 0 to disable message history. Prefer this over lastMessages, since message count is a poor proxy for context size.
+
 **options.readOnly** (`boolean`): When true, prevents memory from saving new messages and provides working memory as read-only context (without the updateWorkingMemory tool). Useful for read-only operations like previews, internal routing agents, or sub agents that should reference but not modify memory.
 
 **options.semanticRecall** (`boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }`): Enable semantic search in message history. Can be a boolean or an object with configuration options. When enabled, requires both vector store and embedder to be configured. Default topK is 4, default messageRange is {before: 1, after: 1}.

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

@@ -73,9 +73,9 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **observation.maxTokensPerBatch** (`number`): Maximum tokens per batch when observing multiple threads in resource scope. Threads are chunked into batches of this size and processed in parallel. Lower values mean more parallelism but more API calls.
 
-**observation.modelSettings** (`ObservationalMemoryModelSettings`): Model settings for the Observer agent. The maxOutputTokens: 100\_000 default is only applied with default model selection (no model set, "default", or a ModelByInputTokens selector). Custom models get no maxOutputTokens default.
+**observation.modelSettings** (`ObservationalMemoryModelSettings`): Model settings for the Observer agent. The temperature: 0.3 default is only applied when the resolved model is known to support temperature. The maxOutputTokens: 100\_000 default is only applied with default model selection (no model set, "default", or a ModelByInputTokens selector). Custom models get no maxOutputTokens default.
 
-**observation.modelSettings.temperature** (`number`): Temperature for generation. Lower values produce more consistent output.
+**observation.modelSettings.temperature** (`number`): Temperature for generation. Lower values produce more consistent output. The 0.3 default is only applied when the resolved model is known to support temperature.
 
 **observation.modelSettings.maxOutputTokens** (`number`): Maximum output tokens. Set high to prevent truncation of observations. The 100000 default is only applied with default model selection; custom models get no default.
 
@@ -107,9 +107,9 @@ OM performs thresholding with fast local token estimation. Text uses `tokenx`, a
 
 **reflection.observationTokens** (`number`): Token count of observations that triggers reflection. When observation tokens exceed this threshold, the Reflector agent is called to condense them.
 
-**reflection.modelSettings** (`ObservationalMemoryModelSettings`): Model settings for the Reflector agent. The maxOutputTokens: 100\_000 default is only applied with default model selection (no model set, "default", or a ModelByInputTokens selector). Custom models get no maxOutputTokens default.
+**reflection.modelSettings** (`ObservationalMemoryModelSettings`): Model settings for the Reflector agent. The temperature: 0 default is only applied when the resolved model is known to support temperature. The maxOutputTokens: 100\_000 default is only applied with default model selection (no model set, "default", or a ModelByInputTokens selector). Custom models get no maxOutputTokens default.
 
-**reflection.modelSettings.temperature** (`number`): Temperature for generation. Lower values produce more consistent output.
+**reflection.modelSettings.temperature** (`number`): Temperature for generation. Lower values produce more consistent output. The 0 default is only applied when the resolved model is known to support temperature.
 
 **reflection.modelSettings.maxOutputTokens** (`number`): Maximum output tokens. Set high to prevent truncation of observations. The 100000 default is only applied with default model selection; custom models get no default.
 
@@ -883,6 +883,36 @@ const selector = new ModelByInputTokens({
 
 **getThresholds** (`() => number[]`): Returns the configured thresholds in ascending order. Useful for introspection.
 
+### skillResultRedactor
+
+`skillResultRedactor` builds a `beforeObservation` transform hook that redacts the results of the built-in Agent Skills tools (`skill`, `skill_search`, and `skill_read`) before the Observer model sees them. Each result is replaced with a placeholder while the tool call is kept, so the Observer still records which skill was used and what it was called with, without the skill text.
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { skillResultRedactor } from '@mastra/memory/hooks'
+
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'google/gemini-2.5-flash',
+      hooks: {
+        beforeObservation: skillResultRedactor(),
+      },
+    },
+  },
+})
+```
+
+#### Parameters
+
+**toolNames** (`readonly string[]`): Tool names whose results are redacted. Defaults to the built-in skill tools: skill, skill\_search, and skill\_read. Use this to redact a different set of tool results.
+
+#### Returns
+
+`(input: { messages: MastraDBMessage[] } & ObserveHookContext) => { messages: MastraDBMessage[] } | undefined`
+
+The hook returns messages with matching tool results replaced by a placeholder, or `undefined` when no message matched (which passes the payload through unchanged). Tool calls, arguments, and every other message are left as they are.
+
 ### Related
 
 - [Observational Memory](https://mastra.ai/docs/memory/observational-memory)

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

@@ -346,12 +346,14 @@ Use `onDroppedEvent` on a custom exporter or bridge to forward these events to e
 
 Interface for span output processors.
 
+`process()` must mutate the span it receives and return the same instance, or return `undefined` to drop the span. A copy of the span (for example `{ ...span }`) can't be exported because `exportSpan()` and `isValid` are instance members of the live span; if a processor returns one, Mastra logs a processor error and drops the span.
+
 ```typescript
 interface SpanOutputProcessor {
   /** Processor name */
   name: string
 
-  /** Process span before export */
+  /** Process span before export. Mutate in place and return the same span, or return undefined to drop it. */
   process(span?: AnySpan): AnySpan | undefined
 
   /** Shutdown processor */