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

package/.docs/reference/observability/tracing/trace-query.md

@@ -4,9 +4,9 @@
 
 # Advanced trace queries
 
-Use `POST /api/observability/traces/query` to find completed logical traces that match trace fields and related span or score records. The endpoint returns a fixed lightweight trace projection, or distinct thread IDs when you group by `threadId`.
+Use `queryTraces()` or `POST /api/observability/traces/query` to find completed logical traces that match trace fields and related span, score, or feedback records. Use `queryTraceThreads()` or `POST /api/observability/threads/query` to find thread identities that qualify across multiple eligible traces.
 
-The endpoint uses the same authentication as other observability routes and requires the `observability:read` permission. The configured observability store must support advanced trace queries.
+Both endpoints use the same authentication as other observability routes and require the `observability:read` permission. The configured observability store must support the requested trace-query or thread-query operation.
 
 ## Query traces with the client SDK
 
@@ -37,7 +37,74 @@ const result = await mastraClient.queryTraces({
 
 A `some` clause matches when one related record satisfies its complete nested predicate. In this example, `scorerId`, `scorerVersion`, and `score` must match on the same score record. A `none` clause uses anti-existence semantics: it matches when no related record satisfies its complete nested predicate. A trace with no related scores therefore matches `scores.none`.
 
-Span clauses examine the current root span and current child spans. The root `timeRange` applies only to the selected current root's `startedAt`. Related spans and scores can participate even when their own timestamps are outside that range. Related records correlate only through a matching non-null `traceId`.
+Span clauses examine the current root span and current child spans. The root `timeRange` applies only to the selected current root's `startedAt`. Related spans, scores, and feedback can participate even when their own timestamps are outside that range. Related records correlate only through a matching non-null `traceId`.
+
+## Query threads across traces
+
+Pass an eligible trace selection and an optional thread predicate to `queryTraceThreads()`:
+
+```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' },
+              },
+            },
+          },
+        },
+      },
+    ],
+  },
+  page: { limit: 25 },
+})
+```
+
+The server applies `traces.timeRange` and `traces.where` first. This produces the complete eligible trace population. It then derives distinct non-null `threadId` values and evaluates the top-level `where` predicate against eligible traces in each thread.
+
+One `traces.some` clause requires one eligible trace to satisfy its complete nested trace predicate. Separate `traces.some` clauses are independent, so different traces in the same thread can satisfy them. Nested `spans.some`, `scores.some`, and `feedback.some` clauses still require one related record to satisfy every condition inside that clause.
+
+`traces.none: P` uses anti-existence semantics: it matches only when no eligible trace in the thread satisfies `P`. This differs from `traces.some: { feedback: { none: P } }`, which requires at least one eligible trace with no matching feedback record.
+
+The response contains identities only:
+
+```json
+{
+  "threads": [{ "threadId": "thread-123" }],
+  "page": { "next": null }
+}
+```
 
 ## Send an HTTP request
 
@@ -65,34 +132,143 @@ curl --request POST \
   }'
 ```
 
+## Discover fields and values
+
+Use trace-query discovery to build field and value autocomplete without scanning trace payloads or copying the query grammar into your client. The configured observability store must support `trace-query-discovery`.
+
+Call `getTraceQueryFields()` for one predicate scope:
+
+```typescript
+const timeRange = {
+  from: '2026-08-01T00:00:00.000Z',
+  to: '2026-08-08T00:00:00.000Z',
+}
+
+const fields = await mastraClient.getTraceQueryFields({
+  timeRange,
+  predicateScope: 'trace',
+  search: 'region',
+  limit: 25,
+})
+```
+
+The response separates canonical fields from observed metadata fields:
+
+```json
+{
+  "canonicalFields": [],
+  "observedFields": [
+    {
+      "path": "metadata.region",
+      "valueKind": "string",
+      "operators": ["eq", "ne", "in", "notIn", "exists", "notExists"],
+      "valueSuggestions": true,
+      "occurrences": 125
+    }
+  ],
+  "observedFieldsTruncated": false
+}
+```
+
+Canonical fields come from the same registry used to validate trace queries. They don't consume `limit`. The canonical order follows that registry. `observedFields` contains top-level string `metadata.<key>` paths found on qualifying current root spans. These fields are ordered by `occurrences` descending, then by path. Nested metadata, keys containing `.`, empty keys, non-string values, and oversized paths are omitted.
+
+`predicateScope` selects the local predicate grammar. It isn't an authorization scope:
+
+| `predicateScope` | Example returned path              | Query usage                               |
+| ---------------- | ---------------------------------- | ----------------------------------------- |
+| `trace`          | `environment` or `metadata.region` | Root `where` predicate                    |
+| `spans`          | `model`                            | Inside `spans.some` or `spans.none`       |
+| `scores`         | `scorerId`                         | Inside `scores.some` or `scores.none`     |
+| `feedback`       | `feedbackType`                     | Inside `feedback.some` or `feedback.none` |
+
+A global field picker can request all four scopes in parallel and qualify display labels locally. Every returned path is directly accepted by `queryTraces()` in its matching scope. `metadata` by itself isn't a field. A user interface can offer manual metadata-key entry separately.
+
+After a user selects one field with `valueSuggestions: true`, call `getTraceQueryValues()`:
+
+```typescript
+const abortController = new AbortController()
+const suggestions = await mastraClient.getTraceQueryValues(
+  {
+    timeRange,
+    predicateScope: 'trace',
+    path: 'metadata.region',
+    search: 'west',
+    limit: 25,
+  },
+  { signal: abortController.signal },
+)
+```
+
+```json
+{
+  "values": [
+    { "value": "eu-west-1", "count": 82 },
+    { "value": "us-west-2", "count": 43 }
+  ],
+  "valuesTruncated": false
+}
+```
+
+Discovery returns string values only. Missing values, empty strings, and strings larger than 4,096 UTF-8 bytes are omitted. Values are ordered by `count` descending, then by value. Suggestions are advisory: `queryTraces()` continues to accept valid manual literals that discovery doesn't return.
+
+Value suggestions are available for these canonical fields:
+
+| Scope    | Fields                                                                        |
+| -------- | ----------------------------------------------------------------------------- |
+| Trace    | `entityName`, `entityType`, `environment`, `status`                           |
+| Spans    | `name`, `spanType`, `model`, `provider`, `status`, `entityType`, `entityName` |
+| Scores   | `scorerId`, `scorerVersion`, `scoreSource`                                    |
+| Feedback | `feedbackType`, `feedbackSource`                                              |
+
+Each executable top-level string `metadata.<key>` field also supports value suggestions in the `trace` scope. Identifiers, timestamps, durations, numeric score or feedback values, comments, errors, and version IDs don't. The fields response still includes canonical fields with `valueSuggestions: false`. The values endpoint rejects those paths with `422 TRACE_QUERY_INVALID`.
+
+Both discovery requests require a half-open time range of at most 31 days. They use the same current-record semantics as `queryTraces()`: qualifying completed roots satisfy `from <= startedAt < to`, and related values come only from current records joined to those roots by `traceId`. Discovery doesn't accept or apply a draft `where` predicate.
+
+`search` defaults to the empty string, is trimmed, and matches case-insensitive literal substrings. Characters such as `%` and `_` have no wildcard meaning. An empty search returns the most frequent results. `limit` defaults to 25 and has a maximum of 100. Both endpoints fetch one extra result to set their truncation flag, but don't provide a cursor. When a flag is `true`, refine `search`. It doesn't imply that a next page is available. No matches return an empty array and `false` truncation.
+
+If discovery exceeds its execution timeout, the route returns `504 TRACE_QUERY_EXECUTION_TIMEOUT`. If the backend exceeds a memory or resource budget, it returns `503 TRACE_QUERY_RESOURCE_LIMIT`. Neither failure returns partial suggestions or sets a truncation flag. Truncation only means a complete ranking was cut to the requested response limit.
+
+ClickHouse discovery requests default to a 5-second timeout and a 256 MiB per-query memory limit. Configure these with `observability.traceQuery.discovery.timeoutMs` and `observability.traceQuery.discovery.memoryLimitBytes` on `ClickhouseStoreVNext`. Discovery falls back to `observability.traceQuery.timeoutMs` when its timeout isn't configured, without changing ordinary `queryTraces()` execution limits.
+
+Both routes require `observability:read` and use the configured observability storage boundary. Don't send organization or project authorization fields in the request. Treat discovered paths, values, and counts as observability data.
+
 ## Request fields
 
-| Field       | Required | Description                                                                                                                                         |
-| ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `timeRange` | Yes      | Trace start-time boundary. `from` is inclusive, `to` is exclusive, and the range can span at most 31 days. Both values must be ISO timestamps.      |
-| `where`     | No       | Recursive trace predicate. Supports scalar conditions and `spans.some`, `spans.none`, `scores.some`, and `scores.none`.                             |
-| `group`     | No       | Set to `{ by: ['threadId'] }` to return distinct non-null thread IDs.                                                                               |
-| `orderBy`   | No       | One item ordering ungrouped results by `startedAt` or `endedAt`, in `asc` or `desc` order. Defaults to `startedAt desc`. Not accepted with `group`. |
-| `page`      | No       | `{ limit, after }`. `limit` defaults to 100 and has a maximum of 1000. Pass the opaque `page.next` value as `after`.                                |
+### Trace queries
+
+| Field       | Required | Description                                                                                                                                                                     |
+| ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `timeRange` | Yes      | Trace start-time boundary. `from` is inclusive and `to` is exclusive. Both values must be ISO timestamps, `from` must be earlier than `to`, and the range can't exceed 31 days. |
+| `where`     | No       | Recursive trace predicate. Supports scalar conditions and `spans`, `scores`, and `feedback` `some` or `none` clauses.                                                           |
+| `orderBy`   | No       | One item ordering results by `startedAt` or `endedAt`, in `asc` or `desc` order. Defaults to `startedAt desc`.                                                                  |
+| `page`      | No       | `{ limit, after }`. `limit` defaults to 100 and has a maximum of 1000. Pass the opaque `page.next` value as `after`.                                                            |
+
+### Thread queries
 
-Unknown fields are rejected. The request can't select a projection, declare joins, or control authorization. Request bodies are limited to 256 KiB.
+| Field    | Required | Description                                                                                                                                         |
+| -------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `traces` | Yes      | Eligible trace selection containing `timeRange` and an optional trace `where` predicate.                                                            |
+| `where`  | No       | Recursive thread predicate composed with boolean operators and `traces.some` or `traces.none`. Each quantifier contains a complete trace predicate. |
+| `page`   | No       | `{ limit, after }`. Thread identities always use fixed ordinal `threadId` ascending order. Pass the opaque `page.next` value as `after`.            |
+
+Unknown fields are rejected. Requests can't select a projection, declare joins, request counts or measures, or control authorization. Request bodies are limited to 256 KiB.
 
 ## Query limits
 
 The planner rejects a query before storage execution when it exceeds any of these limits:
 
-| Input                                     | Maximum           |
-| ----------------------------------------- | ----------------- |
-| Root `timeRange`                          | 31 days           |
-| Predicate nesting depth                   | 12 levels         |
-| Predicate nodes                           | 100               |
-| Related `spans` and `scores` clauses      | 8 total           |
-| Values in one `in` or `notIn` set         | 100               |
-| Comparison literals and membership values | 1,000 total       |
-| String literal                            | 4,096 UTF-8 bytes |
-| Raw predicate path                        | 128 UTF-8 bytes   |
-| `page.limit`                              | 1,000             |
-| HTTP request body                         | 256 KiB           |
+| Input                                                       | Maximum           |
+| ----------------------------------------------------------- | ----------------- |
+| Trace selection `timeRange`                                 | 31 days           |
+| Predicate nesting depth                                     | 12 levels         |
+| Predicate nodes                                             | 100               |
+| Related `traces`, `spans`, `scores`, and `feedback` clauses | 8 total           |
+| Values in one `in` or `notIn` set                           | 100               |
+| Comparison literals and membership values                   | 1,000 total       |
+| String literal                                              | 4,096 UTF-8 bytes |
+| Raw predicate path                                          | 128 UTF-8 bytes   |
+| `page.limit`                                                | 1,000             |
+| HTTP request body                                           | 256 KiB           |
 
 Each comparison literal counts as one literal. Each member of an `in` or `notIn` set also counts as one literal, even when the set is within its per-set limit.
 
@@ -271,7 +447,7 @@ const messageTrace = {
 
 The key must name one top-level property. Empty keys and nested paths are rejected. Metadata keys aren't trimmed, so leading and trailing whitespace remains part of the exact key identity. When metadata duplicates a canonical trace field, such as `resourceId`, `threadId`, or `environment`, prefer the canonical field because it uses the dedicated storage column. The `metadata.<key>` form remains available when you specifically need the value from the metadata object. Metadata and canonical values may differ.
 
-Metadata fields aren't available for grouping or field discovery.
+Metadata fields aren't available for grouping. Trace-query discovery returns executable top-level string metadata fields observed in the selected time range.
 
 ### Filter by feedback
 
@@ -336,43 +512,40 @@ An ungrouped query returns only lightweight completed traces:
 }
 ```
 
-A grouped query returns distinct non-null thread IDs in ascending order:
+A thread query returns distinct non-null thread IDs in ordinal ascending order:
 
-```typescript
-const result = await mastraClient.queryTraces({
-  timeRange: {
-    from: '2026-08-01T00:00:00.000Z',
-    to: '2026-08-08T00:00:00.000Z',
-  },
-  group: { by: ['threadId'] },
-})
-// { groups: [{ threadId: 'thread-123' }], page: { next: null } }
+```json
+{
+  "threads": [{ "threadId": "thread-123" }],
+  "page": { "next": null }
+}
 ```
 
 Related evidence isn't embedded in either response. Use the trace-detail and branch APIs to load spans after selecting a result.
 
 ## Pagination and errors
 
-Ordering is deterministic. Ungrouped ordering appends `traceId` ascending as a tie-breaker. Grouped queries always order by `threadId` ascending.
+Ordering is deterministic. Trace ordering appends `traceId` ascending as a tie-breaker. Thread queries always use raw ordinal `threadId` ascending order. Callers can't override it.
 
-Cursors are bound to the accepted normalized query shape and ordering. Reusing a cursor after changing the time range, predicates, grouping, or ordering returns `409`. A malformed cursor returns `400`.
+Cursors are bound to the operation, accepted normalized query, authorization state, and ordering. Reusing a cursor after changing the trace selection, predicates, or ordering returns `409`. Trace and thread cursors aren't interchangeable. A malformed cursor returns `400`.
 
 Cursor pagination is deterministic, but it isn't a database snapshot. Traces or replacement signals written between page requests can change later pages.
 
-PostgreSQL and ClickHouse stop an advanced trace query after 15 seconds by default and return `504` when the database timeout is exceeded. Set `traceQueryTimeoutMs` in the store's vNext observability configuration to an integer from 1 through 300,000 milliseconds to change the timeout. DuckDB doesn't currently provide query-scoped timeout or cancellation through its driver wrapper, so this `504` guarantee doesn't apply to DuckDB.
+PostgreSQL and ClickHouse stop advanced trace and thread queries after 15 seconds by default and return `504` when the database timeout is exceeded. Set `traceQueryTimeoutMs` in the store's vNext observability configuration to an integer from 1 through 300,000 milliseconds to change the timeout. DuckDB doesn't currently provide query-scoped timeout or cancellation through its driver wrapper, so this `504` guarantee doesn't apply to DuckDB.
 
-| Status | Meaning                                                                                                                               |
-| ------ | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `400`  | Malformed JSON or malformed cursor.                                                                                                   |
-| `409`  | The cursor doesn't match the query.                                                                                                   |
-| `413`  | The request body exceeds 256 KiB.                                                                                                     |
-| `422`  | The JSON is well formed, but the request is structurally or semantically invalid. The response includes stable issue codes and paths. |
-| `501`  | The configured observability store doesn't support advanced trace queries.                                                            |
-| `504`  | A PostgreSQL or ClickHouse query exceeded its configured database execution timeout.                                                  |
+| Status | Meaning                                                                                                                                                                                                                                                  |
+| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `400`  | Malformed JSON or malformed cursor.                                                                                                                                                                                                                      |
+| `409`  | The cursor doesn't match the query.                                                                                                                                                                                                                      |
+| `413`  | The request body exceeds 256 KiB.                                                                                                                                                                                                                        |
+| `422`  | The JSON is well formed, but the request is structurally or semantically invalid. The response includes stable issue codes and paths. Discovery validation uses `TRACE_QUERY_INVALID`.                                                                   |
+| `501`  | The installed Core or configured observability store doesn't support the requested operation. Discovery returns `TRACE_QUERY_DISCOVERY_UNSUPPORTED` unless Core provides the discovery contract and the store implements both field and value discovery. |
+| `503`  | Discovery exceeded a backend memory or resource budget and returned `TRACE_QUERY_RESOURCE_LIMIT`.                                                                                                                                                        |
+| `504`  | A PostgreSQL or ClickHouse query exceeded its configured database execution timeout. Discovery returns `TRACE_QUERY_EXECUTION_TIMEOUT`.                                                                                                                  |
 
 ## Limitations
 
-The endpoint returns completed traces only. It doesn't support running traces, custom projections, embedded evidence, summaries, aggregations, grouping by fields other than `threadId`, or conditions over an entire group.
+Both operations consider completed traces only. They don't support running traces, custom projections, embedded evidence, summaries, aggregations, counts, measures, or custom grouping.
 
 ## Related
 

package/.docs/reference/pubsub/redis-streams.md

@@ -55,6 +55,36 @@ export const mastra = new Mastra({
 })
 ```
 
+### Redis Cluster
+
+Pass `cluster` instead of `url`/`redisOptions` to connect to a Redis Cluster (for example, AWS ElastiCache with cluster mode enabled). The options are forwarded to `createCluster()` from `redis`.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { RedisStreamsPubSub } from '@mastra/redis-streams'
+
+export const mastra = new Mastra({
+  pubsub: new RedisStreamsPubSub({
+    cluster: {
+      rootNodes: [{ url: 'redis://node-1:6379' }, { url: 'redis://node-2:6379' }],
+    },
+  }),
+})
+```
+
+### Bring your own client
+
+To control client construction yourself (TLS, credential providers, and so on), pass an unconnected `redis` client as `client`. The pubsub uses it as its writer and calls `client.duplicate()` for each subscription's blocking reader, so every connection stays distinct. The pubsub owns the client's lifecycle (it connects on first use and quits it on `close()`), so don't share it with the rest of your app.
+
+```typescript
+import { RedisStreamsPubSub } from '@mastra/redis-streams'
+import { createClient } from 'redis'
+
+const pubsub = new RedisStreamsPubSub({
+  client: createClient({ url: process.env.REDIS_URL, socket: { tls: true } }),
+})
+```
+
 ## Constructor parameters
 
 **url** (`string`): Redis connection URL. Falls back to redisOptions.url. (Default: `redis://localhost:6379`)
@@ -65,6 +95,10 @@ export const mastra = new Mastra({
 
 **redisOptions** (`RedisClientOptions`): Options passed to the underlying redis client for advanced configuration.
 
+**cluster** (`RedisClusterOptions`): Connect to a Redis Cluster. Options are passed to createCluster() from redis. Mutually exclusive with url, redisOptions, and client.
+
+**client** (`RedisClientType | RedisClusterType`): A pre-configured, unconnected redis client (standalone or cluster) used as the writer; readers are created with client.duplicate(). The pubsub owns its lifecycle (connects lazily, quits on close()). Mutually exclusive with url, redisOptions, and cluster.
+
 **maxStreamLength** (`number`): Approximate maximum number of entries kept per stream. Set to 0 to disable trimming. (Default: `10000`)
 
 **streamIdleTtlMs** (`number`): Idle expiry in milliseconds: a sliding TTL refreshed on every write (publish, nack retry, group re-creation). Each write resets it, so an actively-written stream never expires mid-flight; a stream left idle for the full duration is deleted by Redis automatically. Note that only writes refresh the TTL — a consumer slowly draining a backlog does not — so set it well above the longest expected gap between writes on a live topic. This is a backstop, not the primary cleanup — clearTopic handles normal end-of-lifecycle deletion; this only bounds memory for streams that never reach a clearTopic call (e.g. a crashed run). Must be a non-negative integer. Defaults to 0 (disabled). (Default: `0`)

package/.docs/reference/rag/vector-databases.md

@@ -248,6 +248,34 @@ await store.upsert({
 })
 ```
 
+**Weaviate**:
+
+```ts
+import { WeaviateVector } from '@mastra/weaviate'
+
+const store = new WeaviateVector({
+  id: 'weaviate-vector',
+  httpHost: process.env.WEAVIATE_HOST,
+  httpPort: 443,
+  httpSecure: true,
+  grpcHost: process.env.WEAVIATE_GRPC_HOST,
+  grpcPort: 443,
+  grpcSecure: true,
+  apiKey: process.env.WEAVIATE_API_KEY,
+})
+
+await store.createIndex({
+  indexName: 'myCollection',
+  dimension: 1536,
+})
+
+await store.upsert({
+  indexName: 'myCollection',
+  vectors: embeddings,
+  metadata: chunks.map(chunk => ({ text: chunk.text })),
+})
+```
+
 **Cloudflare**:
 
 ```ts
@@ -317,6 +345,29 @@ await store.upsert({
 
 For detailed setup instructions and best practices, see the [official Elasticsearch documentation](https://www.elastic.co/docs/solutions/search/get-started).
 
+**Azure AI Search**:
+
+```ts
+import { AzureAISearchVector } from '@mastra/azure-ai-search'
+
+const store = new AzureAISearchVector({
+  id: 'azure-search-vectors',
+  endpoint: process.env.AZURE_AI_SEARCH_ENDPOINT!,
+  credential: process.env.AZURE_AI_SEARCH_CREDENTIAL!,
+})
+
+await store.createIndex({
+  indexName: 'my-collection',
+  dimension: 1536,
+})
+
+await store.upsert({
+  indexName: 'my-collection',
+  vectors: embeddings,
+  metadata: chunks.map(chunk => ({ text: chunk.text })),
+})
+```
+
 **Couchbase**:
 
 ```ts
@@ -534,6 +585,17 @@ Namespace names must:
 
 - Example: `_namespace` isn't valid (starts with underscore)
 
+**Weaviate**:
+
+Index names map to Weaviate collections, which:
+
+- Are capitalized by Weaviate (the first letter is upper-cased)
+- Should contain only letters, numbers, and the `_` character
+- Must start with a letter, since only the first character is upper-cased (a leading digit or symbol stays invalid)
+- Preserve the original Mastra index name in the collection description, so `listIndexes()` and `describeIndex()` return the name you supplied
+- Example: `my_collection` is stored as `My_collection` and returned as `my_collection`
+- Example: `123_collection` isn't valid (starts with a digit)
+
 **Cloudflare**:
 
 Index names must:
@@ -587,6 +649,17 @@ Index names must:
 - Example: `myindex-` isn't valid (ends with hyphen)
 - Example: `MyIndex` isn't valid (contains uppercase letters)
 
+**Azure AI Search**:
+
+Index names must:
+
+- Use only lowercase letters, numbers, dashes (`-`), and underscore (`_`) characters
+- Not start or end with a dash
+- Be between 2 and 128 characters long
+- Example: `my-index-123` and `my_index` are valid
+- Example: `MyIndex` isn't valid (contains uppercase letters)
+- Example: `my-index-` isn't valid (ends with a dash)
+
 ### Upserting Embeddings
 
 After creating an index, you can store embeddings along with their basic metadata:

package/.docs/reference/storage/retention.md

@@ -6,11 +6,37 @@
 
 Because storage grows without bound by default, Mastra provides an opt-in, age-based retention system. Declare per-table `maxAge` policies in the `retention` config, then call `storage.prune()` to delete rows older than their configured age. Unconfigured data is kept forever, so behavior doesn't change until you opt in.
 
-`prune()` deletes rows. It caps growth and is safe to run against large tables (batched, bounded, resumable, cancellable). It never reclaims disk: on SQLite/libSQL the freed pages are reused by future writes so the file stops growing, but handing disk back to the OS (for example a `VACUUM`) is left to the underlying database and the operator to manage.
+`prune()` deletes rows in bounded batches. Runs are resumable and cancellable, so you can limit how much work each maintenance window performs. Pruning doesn't reclaim disk space by itself. Use the database-specific maintenance guidance below when you need to return freed space to the operating system.
 
 Retention covers **growth tables** only: tables that accumulate rows unbounded as a side effect of normal operation (conversation history, telemetry, job and run records, schedule fire history, event feeds). User-authored artifacts and config (agents, skills, workspaces, prompt blocks, datasets, schedule definitions, channel installations, and so on) grow with user intent and are edited or deleted explicitly, so they're not valid retention keys.
 
-The reference implementations are [libSQL](https://mastra.ai/integrations/databases/libsql), [PostgreSQL](https://mastra.ai/integrations/databases/postgresql), and [MongoDB](https://mastra.ai/integrations/databases/mongodb). Other adapters keep rows forever until they implement retention.
+Storage adapters use the shared core retention contract for `prune()`, or a database-native mechanism when that better matches the backend.
+
+| Adapter              | Mechanism               | Retention support                                                                                                                                                                      |
+| -------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| libSQL               | `prune()`               | All supported growth domains                                                                                                                                                           |
+| PostgreSQL           | `prune()`               | All supported growth domains. V-next observability drops expired partitions or chunks                                                                                                  |
+| MongoDB              | `prune()` or native TTL | All supported growth domains. Native TTL indexes are also available                                                                                                                    |
+| DuckDB               | `prune()`               | Observability spans, metrics, logs, scores, and feedback                                                                                                                               |
+| MySQL                | `prune()`               | Observability spans                                                                                                                                                                    |
+| Microsoft SQL Server | `prune()`               | Observability spans                                                                                                                                                                    |
+| Oracle Database      | `prune()`               | Observability spans and logs                                                                                                                                                           |
+| Amazon Aurora DSQL   | `prune()`               | Observability spans                                                                                                                                                                    |
+| Google Cloud Spanner | `prune()`               | Observability spans, plus metrics when metrics storage is enabled                                                                                                                      |
+| ClickHouse           | Native TTL              | Observability spans, metrics, logs, scores, and feedback. When all five signals have finite retention, deletion-request records expire after the longest signal retention plus 30 days |
+
+## Storage-specific maintenance
+
+| Adapter           | Maintenance guidance                                                                                                                            |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| SQLite and libSQL | Freed pages are reused by future writes, which stops the database file from growing. Reclaiming disk space requires database-level maintenance. |
+| DuckDB            | For file-backed stores, run `CHECKPOINT` after pruning to reclaim deleted rows in storage. DuckDB's `VACUUM` doesn't reclaim deleted rows.      |
+
+## Schedule pruning
+
+Run `prune()` from a scheduler or maintenance worker, not from application startup or shutdown hooks. For deployments that share a database, prefer a single active scheduler or worker for pruning.
+
+Prefer lower-traffic periods when pruning large tables. Use `maxBatches`, `maxRows`, and `pauseMs` to bound each run, and pass an `AbortSignal` when the maintenance process needs to stop promptly. These recommendations apply to adapters that expose `prune()`. ClickHouse applies its native time to live (TTL) policy within the database.
 
 ## Usage example
 
@@ -94,7 +120,8 @@ Each domain specifies its age-prunable tables and the timestamp column that anch
 > - Experiments prune as whole units: an aged experiment's result rows are deleted together with it (results cascade with their parent), so a run is never left partially deleted. Retention doesn't have a separate `results` key.
 > - For `schedules`, the growth table is the fire history (`schedule_triggers`, one row per fire): schedule definitions are config and aren't pruned.
 > - On PostgreSQL, timestamp anchors use the timezone-aware mirror columns (for example `createdAtZ`, `completedAtZ`).
-> - LibSQL and PostgreSQL support all domains above except `harness`, which PostgreSQL doesn't implement. MongoDB supports all except `threadState` and `harness`.
+> - DuckDB observability stores append-only events for all five signals. Its `spans` policy uses the event `timestamp` column rather than `startedAt`.
+> - LibSQL and PostgreSQL support all domains above except `harness`, which PostgreSQL doesn't implement. MongoDB supports all except `threadState` and `harness`. DuckDB, MySQL, Microsoft SQL Server, Oracle Database, Amazon Aurora DSQL, and Google Cloud Spanner currently support retention only in their `observability` domains, with the signal coverage shown in the support matrix.
 > - The v-next PostgreSQL observability domain stores signal events in day-partitioned tables (`spans`, `metrics`, `logs`, `scores`, `feedback`). For it, `prune()` drops whole day partitions (or TimescaleDB chunks) that are entirely older than the cutoff instead of deleting rows: effective level of detail is one day, and a partition is only dropped once its entire day is past `maxAge`. `PruneResult.deleted` reports the number of rows in the dropped partitions.
 
 ## Methods
@@ -109,7 +136,7 @@ Deletes rows older than their configured `maxAge` across every domain that has a
 
 Pass `options.retention` to replace the configured policies for that call only: for example to skip a domain (keep chat history) or prune more aggressively than the standing config. The store's configured `retention` is unchanged.
 
-Anchor-column indexes are created lazily on the first `prune()` call for each table with a policy (never at `init()`) so deployments that don't configure retention pay no extra index write or disk overhead. The first prune of an existing large table pays a one-time index build. Subsequent prunes reuse the index.
+Adapters that use anchor-column indexes create them lazily on the first `prune()` call for each table with a policy (never at `init()`) so deployments that don't configure retention pay no extra index write or disk overhead. The first prune of an existing large table pays a one-time index build. Subsequent prunes reuse the index. DuckDB uses its built-in zone maps instead of creating retention indexes.
 
 ```typescript
 const results = await storage.prune({
@@ -177,6 +204,31 @@ async function retentionTick() {
 
 You can also cancel a long-running prune with an `AbortSignal`: the loop stops between batches and returns partial results with `done: false`, so the next run resumes cleanly.
 
+## ClickHouse native TTL
+
+ClickHouse observability storage uses native table TTLs instead of `prune()`. Configure retention as days per signal. `init()` applies the TTLs to new and existing tables and skips `ALTER TABLE` statements when the configured TTL is already present.
+
+For deployments that need to update TTL configuration without running the full initialization path, call `applyRetention()` on the v-next observability store:
+
+```typescript
+import { ObservabilityStorageClickhouseVNext } from '@mastra/clickhouse'
+
+const observability = new ObservabilityStorageClickhouseVNext({
+  client,
+  retention: {
+    tracing: 30,
+    logs: 7,
+    metrics: 14,
+    scores: 90,
+    feedback: 60,
+  },
+})
+
+await observability.applyRetention()
+```
+
+Deletion requests are retained long enough to keep enforcing erasure after signal rows expire. Mastra applies a TTL to `mastra_deletion_requests` only when tracing, logs, metrics, scores, and feedback all have finite retention. The deletion-request TTL is the longest of those periods plus 30 days. For example, if score retention is the longest period at 90 days, deletion requests expire after 120 days. When any signal is unbounded, deletion requests remain unbounded because trace deletion requests cover rows across all five signals.
+
 ## MongoDB TTL indexes (alternative to prune)
 
 MongoDB offers native [TTL (Time-To-Live) indexes](https://www.mongodb.com/docs/manual/core/index-ttl/) that automatically delete expired documents without requiring manual `prune()` calls. This is a database-level feature that runs as a background thread.

package/.docs/reference/streaming/agents/stream.md

@@ -104,7 +104,7 @@ const stream = await agent.stream('message for agent')
 
 **options.structuredOutput.fallbackValue** (`<S extends ZodTypeAny>`): Fallback value to use when schema validation fails and errorStrategy is 'fallback'.
 
-**options.structuredOutput.instructions** (`string`): Additional instructions for the structured output model.
+**options.structuredOutput.instructions** (`string`): Additional instructions for the structured output model. With jsonPromptInjection and no structuring model, this text is injected into the prompt in place of the serialized schema.
 
 **options.structuredOutput.jsonPromptInjection** (`boolean | 'system' | 'inline' | 'auto'`): Controls how the JSON schema reaches the model. Set to 'auto' to use native structured output when supported and inline prompt injection otherwise.
 

package/.docs/reference/tools/mcp-server.md

@@ -10,34 +10,6 @@ Note that if you only need to use your tools or agents directly within your Mast
 
 It supports both [stdio (subprocess) and SSE (HTTP) MCP transports](https://modelcontextprotocol.io/docs/concepts/transports).
 
-## Operate a remote Mastra server
-
-Use `MastraApiMCPServer` to give MCP clients the Mastra server operations from the `mastra api` CLI. It reads the target server's API schema when it starts and only registers operations supported by that server. Factory commands and routes outside this catalog aren't exposed.
-
-```typescript
-import { Mastra } from '@mastra/core/mastra'
-import { MastraApiMCPServer } from '@mastra/mcp'
-
-const operations = await MastraApiMCPServer.create({
-  url: 'https://my-mastra-server.example.com',
-  headers: {
-    Authorization: `Bearer ${process.env.MASTRA_API_TOKEN}`,
-  },
-})
-
-export const mastra = new Mastra({
-  mcpServers: { operations },
-})
-```
-
-Tool names follow the CLI command hierarchy. For example, `mastra api workflow run start` becomes `workflow_run_start`.
-
-The server can expose 60 tools across agents, workflows, tools, MCP servers, memory threads, working memory, traces, logs, metrics, scores, datasets, experiments, and Trace Intelligence. Each tool uses the input schema returned by the target server. Trace list and get tools also support the CLI's `verbose` option.
-
-The server uses stateless MCP transport. Read operations, mutations, and destructive operations have separate MCP tool annotations. Agent, workflow, experiment, and tool execution are marked as potentially destructive because they can invoke operations that delete or overwrite data. These annotations are hints for MCP clients, not authorization checks. Each tool call sends one request to the target API and doesn't retry mutations.
-
-Use `headers` to authenticate the API schema request. For tool calls, the MCP caller's bearer token replaces the configured `Authorization` header. You can also set `apiPrefix`, `timeoutMs`, `id`, `name`, and `version`.
-
 ## Constructor
 
 To create a new `MCPServer`, you need to provide some basic information about your server, the tools it will offer, and optionally, any agents you want to expose as tools.