@mastra/mcp-docs-server 1.2.15-alpha.9 → 1.2.15

package/.docs/reference/processors/regex-filter-processor.md

@@ -43,6 +43,24 @@ const filter = new RegexFilterProcessor({
 })
 ```
 
+Raise the streaming carryover window for long custom matches (e.g. a fixed-length secret or a value that only matches once its closing delimiter arrives):
+
+```typescript
+import { RegexFilterProcessor } from '@mastra/core/processors'
+
+const filter = new RegexFilterProcessor({
+  rules: [
+    {
+      name: 'armored-key',
+      pattern: /-----BEGIN KEY-----[A-Z]+-----END KEY-----/g,
+      replacement: '[KEY]',
+    },
+  ],
+  strategy: 'redact',
+  streamCarryoverSize: 256,
+})
+```
+
 Attach to an agent:
 
 ```typescript
@@ -80,6 +98,8 @@ const agent = new Agent({
 
 **includeRedactedValues** (`boolean`): Include the text that was redacted in each report entry. Off by default, because the values are the data the processor removes. (Default: `false`)
 
+**streamCarryoverSize** (`number`): Trailing characters the streaming redact path holds back between chunks, so a match split across a chunk boundary is redacted whole. The default covers every built-in preset with a wide margin. Raise it for custom rules whose matches stay invisible to the rule until they complete, such as a fixed-length secret or a value with a closing delimiter, when such a match can be longer than the window. (Default: `128`)
+
 ## Returns
 
 **id** (`'regex-filter'`): Processor identifier.

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

@@ -2,6 +2,8 @@
 
 # ResponseCache
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 `ResponseCache` is an input processor that caches LLM responses on the request/response boundary inside the agentic loop. It hooks into `processLLMRequest` for cache lookup and short-circuits on a hit. It uses `processLLMResponse` to write the completed response.
 
 The cache key is derived from the resolved `LanguageModelV2Prompt` Mastra is about to send to the model (i.e. _after_ memory has loaded and earlier input processors have transformed the prompt) so two users with different memory contexts produce different cache keys. Each step in an agentic tool loop is independently cached.

package/.docs/reference/processors/tool-search-processor.md

@@ -29,6 +29,8 @@ const toolSearch = new ToolSearchProcessor({
 
 **options.tools** (`Record<string, Tool>`): All tools that can be searched and loaded dynamically. These tools are not immediately available to the agent — they must be discovered via search and loaded on demand.
 
+**options.includeResolvedTools** (`boolean`): Also make the tools the agent resolved for this request (MCP tools requiring the caller's credentials, or anything returned by a dynamic tools function) searchable, and withhold them from the prompt until the agent loads them. The meta-tools are never withheld. Request-resolved tools are indexed per request, so each request searches and loads its own tool instances.
+
 **options.search** (`{ topK?: number; minScore?: number; autoLoad?: boolean }`): Configuration for the search behavior.
 
 **options.search.topK** (`number`): Maximum number of tools to return in search results.
@@ -120,7 +122,37 @@ The `phase` value describes where the filter is being applied:
 - `load`: Blocks `load_tool` from loading disallowed tools.
 - `active`: Hides already-loaded tools from the current request if they're no longer allowed.
 
-If the hook throws or rejects, `ToolSearchProcessor` treats the tool as disallowed for that request. The hook may run for every matching search candidate, so keep async policy checks cheap or cached. The `search_tools` meta-tool is always available. `load_tool` is available unless `search.autoLoad` is enabled. Tools passed directly through the agent or `processInputStep` remain available unless you filter them outside `ToolSearchProcessor`.
+If the hook throws or rejects, `ToolSearchProcessor` treats the tool as disallowed for that request. The hook may run for every matching search candidate, so keep async policy checks cheap or cached. The `search_tools` meta-tool is always available. `load_tool` is available unless `search.autoLoad` is enabled. Tools passed directly through the agent or `processInputStep` remain available unless you filter them outside `ToolSearchProcessor`, or enable `includeResolvedTools`.
+
+## Searching request-resolved tools
+
+The `tools` option is fixed at construction, so you can't list tools that only exist per request (MCP tools that need the caller's credentials, or anything returned by a dynamic `tools` function). By default those tools bypass search and occupy prompt space on every turn.
+
+Set `includeResolvedTools: true` to index them for the request and withhold them from the prompt until the agent loads them:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { ToolSearchProcessor } from '@mastra/core/processors'
+
+const toolSearch = new ToolSearchProcessor({
+  tools: staticTools,
+  includeResolvedTools: true,
+})
+
+const agent = new Agent({
+  id: 'mcp-agent',
+  name: 'mcp-agent',
+  instructions: 'Search for a tool when you need a capability you do not have.',
+  model: 'openai/gpt-5.6-sol',
+  // Resolved per request, then searchable alongside staticTools
+  tools: async ({ requestContext }) => mcpClient.getTools(requestContext.get('userToken')),
+  inputProcessors: [toolSearch],
+})
+```
+
+Each request is indexed on its own, so a tool loaded by one caller never resolves to another caller's instance of the same tool name.
+
+This option applies to every tool resolved for the request, including memory, workspace, skill, and browser tools. Only the `search_tools` and `load_tool` meta-tools stay in the prompt, so any tool the agent relies on implicitly must be found through search before it can be called.
 
 ## Extended usage example
 

package/.docs/reference/pubsub/lease-provider.md

@@ -130,4 +130,4 @@ When the configured pub/sub backend doesn't implement `LeaseProvider`, the runti
 - [PubSub](https://mastra.ai/reference/pubsub/base): The event delivery contract, separate from leasing
 - [RedisStreamsPubSub](https://mastra.ai/reference/pubsub/redis-streams): The built-in backend that implements `LeaseProvider`
 - [Signals](https://mastra.ai/docs/long-running-agents/signals): The runtime that uses leasing to coordinate thread execution across processes
-- [Channels](https://mastra.ai/docs/capabilities/channels/overview): Uses leasing to coordinate agent runs in serverless and multi-instance deployments
+- [Channels](https://mastra.ai/docs/capabilities/channels): Uses leasing to coordinate agent runs in serverless and multi-instance deployments

package/.docs/{guides → reference}/rag/chunking-and-embedding.md

@@ -5,7 +5,9 @@
 Before processing, create a MDocument instance from your content. You can initialize it from different formats:
 
 ```ts
-const docFromText = MDocument.fromText('Your plain text content...')
+import { MDocument } from '@mastra/rag'
+
+const doc = MDocument.fromText('Your plain text content...')
 const docFromHTML = MDocument.fromHTML('<html>Your HTML content...</html>')
 const docFromMarkdown = MDocument.fromMarkdown('# Your Markdown content...')
 const docFromJSON = MDocument.fromJSON(`{ "key": "value" }`)
@@ -59,7 +61,7 @@ For markdown documents where preserving the semantic relationships between secti
 const chunks = await doc.chunk({
   strategy: 'semantic-markdown',
   joinThreshold: 500,
-  modelName: 'gpt-3.5-turbo',
+  modelName: 'gpt-5',
 })
 ```
 
@@ -129,51 +131,46 @@ const { embeddings } = await embedMany({
 
 ## Example: Complete pipeline
 
-Here's an example showing document processing and embedding generation with both providers:
+Here's an example showing document processing, embedding generation, and vector storage:
 
 ```ts
-import { embedMany } from 'ai'
-
+import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
+import { PgVector } from '@mastra/pg'
 import { MDocument } from '@mastra/rag'
+import { embedMany } from 'ai'
 
-// Initialize document
 const doc = MDocument.fromText(`
   Climate change poses significant challenges to global agriculture.
   Rising temperatures and changing precipitation patterns affect crop yields.
 `)
 
-// Create chunks
 const chunks = await doc.chunk({
   strategy: 'recursive',
   maxSize: 256,
   overlap: 50,
 })
 
-// Generate embeddings with OpenAI
-import { ModelRouterEmbeddingModel } from '@mastra/core/llm'
-
 const { embeddings } = await embedMany({
   model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
   values: chunks.map(chunk => chunk.text),
 })
 
-// OR
+const vectorStore = new PgVector({
+  id: 'pg-vector',
+  connectionString: process.env.POSTGRES_CONNECTION_STRING,
+})
 
-// Generate embeddings with Cohere
-const { embeddings } = await embedMany({
-  model: 'cohere/embed-english-v3.0',
-  values: chunks.map(chunk => chunk.text),
+await vectorStore.createIndex({
+  indexName: 'embeddings',
+  dimension: 1536,
 })
 
-// Store embeddings in your vector database
 await vectorStore.upsert({
   indexName: 'embeddings',
   vectors: embeddings,
 })
 ```
 
-##
-
 For more examples of different chunking strategies and embedding configurations, see:
 
 - [Chunk Reference](https://mastra.ai/reference/rag/chunk)
@@ -181,5 +178,5 @@ For more examples of different chunking strategies and embedding configurations,
 
 For more details on vector databases and embeddings, see:
 
-- [Vector Databases](https://mastra.ai/guides/rag/vector-databases)
+- [Vector Databases](https://mastra.ai/reference/rag/vector-databases)
 - [Embedding API Reference](https://mastra.ai/reference/rag/embeddings)

package/.docs/reference/rag/database-config.md

@@ -275,5 +275,5 @@ const vectorTool = createVectorQueryTool({
 ## Related
 
 - [createVectorQueryTool()](https://mastra.ai/reference/tools/vector-query-tool)
-- [Hybrid Vector Search](https://mastra.ai/guides/rag/retrieval)
+- [Hybrid Vector Search](https://mastra.ai/reference/rag/retrieval)
 - [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)

package/.docs/{guides/rag/graph-rag.md → reference/rag/graph-rag-guide.md}

@@ -14,7 +14,7 @@ GraphRAG is particularly effective when:
 - Understanding connections between concepts is important
 - Simple vector similarity misses important contextual relationships
 
-For straightforward semantic search without relationship traversal, use [standard retrieval methods](https://mastra.ai/guides/rag/retrieval).
+For straightforward semantic search without relationship traversal, use [standard retrieval methods](https://mastra.ai/reference/rag/retrieval).
 
 ## How GraphRAG works
 

package/.docs/reference/rag/metadata-filters.md

@@ -2,7 +2,7 @@
 
 # Metadata filters
 
-Mastra provides a unified metadata filtering syntax across all vector stores, based on MongoDB/Sift query syntax. Each vector store translates these filters into their native format.
+Mastra provides a unified metadata filtering syntax across all vector stores, based on MongoDB/Sift query syntax. Each vector store translates these filters into its native query format. For example, PgVector uses PostgreSQL JSONB predicates, while OracleDB stores metadata as Oracle JSON and compiles filters to `JSON_VALUE`, `JSON_EXISTS`, `REGEXP_LIKE`, and `LIKE` predicates with bound values.
 
 ## Basic example
 
@@ -34,11 +34,11 @@ const results = await store.query({
 
 ### Array Operators
 
-`$in`Matches any value in array{ category: { $in: \["A", "B"] } }Supported by: All except Couchbase`$nin`Matches none of the values{ status: { $nin: \["deleted", "archived"] } }Supported by: All except Couchbase`$all`Matches arrays containing all elements{ tags: { $all: \["urgent", "high"] } }Supported by: Astra, Pinecone, Upstash, MongoDB`$elemMatch`Matches array elements meeting criteria{ scores: { $elemMatch: { $gt: 80 } } }Supported by: libSQL, PgVector, MongoDB
+`$in`Matches any value in array{ category: { $in: \["A", "B"] } }Supported by: All except Couchbase`$nin`Matches none of the values{ status: { $nin: \["deleted", "archived"] } }Supported by: All except Couchbase`$all`Matches arrays containing all elements{ tags: { $all: \["urgent", "high"] } }Supported by: Astra, Pinecone, Upstash, MongoDB, OracleDB`$elemMatch`Matches array elements meeting criteria{ scores: { $elemMatch: { $gt: 80 } } }Supported by: libSQL, PgVector, MongoDB, OracleDB
 
 ### Logical Operators
 
-`$and`Logical AND{ $and: \[{ price: { $gt: 100 } }, { stock: { $gt: 0 } }] }Supported by: All except Vectorize, Couchbase`$or`Logical OR{ $or: \[{ status: "active" }, { priority: "high" }] }Supported by: All except Vectorize, Couchbase`$not`Logical NOT{ price: { $not: { $lt: 100 } } }Supported by: Astra, Qdrant, Upstash, PgVector, libSQL, MongoDB`$nor`Logical NOR{ $nor: \[{ status: "deleted" }, { archived: true }] }Supported by: Qdrant, Upstash, PgVector, libSQL, MongoDB
+`$and`Logical AND{ $and: \[{ price: { $gt: 100 } }, { stock: { $gt: 0 } }] }Supported by: All except Vectorize, Couchbase`$or`Logical OR{ $or: \[{ status: "active" }, { priority: "high" }] }Supported by: All except Vectorize, Couchbase`$not`Logical NOT{ price: { $not: { $lt: 100 } } }Supported by: Astra, Qdrant, Upstash, PgVector, libSQL, MongoDB, OracleDB`$nor`Logical NOR{ $nor: \[{ status: "deleted" }, { archived: true }] }Supported by: Qdrant, Upstash, PgVector, libSQL, MongoDB, OracleDB
 
 ### Element Operators
 
@@ -46,7 +46,7 @@ const results = await store.query({
 
 ### Custom Operators
 
-`$contains`Text contains substring{ description: { $contains: "sale" } }Supported by: Upstash, libSQL, PgVector`$regex`Regular expression match{ name: { $regex: "^test" } }Supported by: Qdrant, PgVector, Upstash, MongoDB`$size`Array length check{ tags: { $size: { $gt: 2 } } }Supported by: Astra, libSQL, PgVector, MongoDB`$geo`Geospatial query{ location: { $geo: { type: "radius", ... } } }Supported by: Qdrant`$datetime`Datetime range query{ created: { $datetime: { range: { gt: "2024-01-01" } } } }Supported by: Qdrant`$hasId`Vector ID existence check{ $hasId: \["id1", "id2"] }Supported by: Qdrant`$hasVector`Vector existence check{ $hasVector: true }Supported by: Qdrant
+`$contains`Text contains substring{ description: { $contains: "sale" } }Supported by: Upstash, libSQL, PgVector, OracleDB`$regex`Regular expression match{ name: { $regex: "^test" } }Supported by: Qdrant, PgVector, Upstash, MongoDB, OracleDB`$size`Array length check{ tags: { $size: 3 } }Supported by: Astra, libSQL, PgVector, MongoDB, OracleDB`$geo`Geospatial query{ location: { $geo: { type: "radius", ... } } }Supported by: Qdrant`$datetime`Datetime range query{ created: { $datetime: { range: { gt: "2024-01-01" } } } }Supported by: Qdrant`$hasId`Vector ID existence check{ $hasId: \["id1", "id2"] }Supported by: Qdrant`$hasVector`Vector existence check{ $hasVector: true }Supported by: Qdrant
 
 ## Common rules and restrictions
 
@@ -124,6 +124,14 @@ const results = await store.query({
 - Empty arrays in conditions are handled gracefully
 - Metadata is stored in a JSONB column for efficient querying
 
+### OracleDB
+
+- Metadata is stored as Oracle JSON alongside each `VECTOR` row
+- Scalar comparisons use `JSON_VALUE`, while array, existence, and element-match checks use `JSON_EXISTS`
+- `$regex` uses Oracle `REGEXP_LIKE`; string `$contains` uses case-insensitive `LIKE`
+- Nested fields are supported with dot notation and are converted to quoted Oracle JSON paths
+- User-provided metadata values are bound as parameters instead of interpolated into SQL
+
 ### PgVector
 
 - Full support for PostgreSQL's native JSON querying capabilities
@@ -211,6 +219,7 @@ const results = await store.query({
 - [Cloudflare Vectorize](https://mastra.ai/reference/vectors/vectorize)
 - [libSQL](https://mastra.ai/reference/vectors/libsql)
 - [MongoDB](https://mastra.ai/reference/vectors/mongodb)
+- [OracleDB](https://mastra.ai/reference/vectors/oracledb)
 - [PgStore](https://mastra.ai/reference/vectors/pg)
 - [Pinecone](https://mastra.ai/reference/vectors/pinecone)
 - [Qdrant](https://mastra.ai/reference/vectors/qdrant)

package/.docs/{guides → reference}/rag/overview.md

@@ -63,11 +63,11 @@ This example shows the essentials. Initialize a document and create chunks, then
 
 ## Document processing
 
-The basic building block of RAG is document processing. Documents can be chunked using strategies (recursive, sliding window, etc.) and enriched with metadata. See the [chunking and embedding doc](https://mastra.ai/guides/rag/chunking-and-embedding).
+The basic building block of RAG is document processing. Documents can be chunked using strategies (recursive, sliding window, etc.) and enriched with metadata. See the [chunking and embedding doc](https://mastra.ai/reference/rag/chunking-and-embedding).
 
 ## Vector storage
 
-Mastra supports multiple vector stores for embedding persistence and similarity search, including pgvector, Pinecone, Qdrant, and MongoDB. See the [vector database doc](https://mastra.ai/guides/rag/vector-databases).
+Mastra supports multiple vector stores for embedding persistence and similarity search, including pgvector, OracleDB, Pinecone, Qdrant, and MongoDB. See the [vector database doc](https://mastra.ai/reference/rag/vector-databases).
 
 ## More resources
 

package/.docs/{guides → reference}/rag/retrieval.md

@@ -436,6 +436,23 @@ export const ragAgent = new Agent({
 })
 ```
 
+**OracleDB**:
+
+```ts
+import { ORACLEDB_PROMPT } from '@mastra/oracledb'
+
+export const ragAgent = new Agent({
+  id: 'rag-agent',
+  name: 'RAG Agent',
+  model: 'openai/gpt-5.6-sol',
+  instructions: `
+  Process queries using the provided context. Structure responses to be concise and relevant.
+  ${ORACLEDB_PROMPT}
+  `,
+  tools: { vectorQueryTool },
+})
+```
+
 **S3Vectors**:
 
 ```ts
@@ -517,4 +534,4 @@ The re-ranked results combine vector similarity with semantic understanding to i
 
 For more details about re-ranking, see the [rerank()](https://mastra.ai/reference/rag/rerankWithScorer) method.
 
-For graph-based retrieval that follows connections between chunks, see the [GraphRAG](https://mastra.ai/guides/rag/graph-rag) documentation.
+For graph-based retrieval that follows connections between chunks, see the [GraphRAG](https://mastra.ai/reference/rag/graph-rag-guide) documentation.

package/.docs/{guides → reference}/rag/vector-databases.md

@@ -78,6 +78,35 @@ await store.upsert({
 
 PostgreSQL with the pgvector extension is a good solution for teams already using PostgreSQL who want to minimize infrastructure complexity. For detailed setup instructions and best practices, see the [official pgvector repository](https://github.com/pgvector/pgvector).
 
+**OracleDB**:
+
+```ts
+import { OracleVector } from '@mastra/oracledb'
+
+const store = new OracleVector({
+  id: 'oracle-vector',
+  user: process.env.ORACLE_DATABASE_USER,
+  password: process.env.ORACLE_DATABASE_PASSWORD,
+  connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
+})
+
+await store.createIndex({
+  indexName: 'myCollection',
+  dimension: 1536,
+  indexConfig: { type: 'none' },
+})
+
+await store.upsert({
+  indexName: 'myCollection',
+  vectors: embeddings,
+  metadata: chunks.map(chunk => ({ text: chunk.text })),
+})
+```
+
+### Using Oracle Database Vector Search
+
+OracleDB stores embeddings in native `VECTOR` columns and metadata in Oracle JSON. Exact search is the default; HNSW and IVF indexes can be configured for tuned deployments.
+
 **Pinecone**:
 
 ```ts
@@ -378,7 +407,7 @@ await store.createIndex({
 
 The dimension size must match the output dimension of your chosen embedding model. Common dimension sizes are:
 
-- `OpenAI text-embedding-3-small`: 1536 dimensions (or custom, e.g., 256)
+- OpenAI `text-embedding-3-small`: 1536 dimensions (or custom, e.g., 256)
 - `Cohere embed-multilingual-v3`: 1024 dimensions
 - `VoyageAI voyage-3.5`: 1024 dimensions (or custom: 256, 512, 1024, 2048)
 - `Google gemini-embedding-001`: 768 dimensions (or custom)
@@ -410,6 +439,18 @@ Index names must:
 - Example: `my_index_123` is valid
 - Example: `my-index` is not valid (contains hyphen)
 
+**OracleDB**:
+
+Index names are logical Mastra names. OracleDB maps each logical index to a physical Oracle table internally.
+
+Logical index names must:
+
+- Be non-empty
+- Be 512 characters or fewer
+- Be stable for the lifetime of the vector index
+- Example: `my_collection_123` is valid
+- Example: `customer-support/docs:v1` is valid and is mapped to a safe Oracle table name
+
 **Pinecone**:
 
 Index names must:

package/.docs/reference/schedules/overview.md

@@ -4,6 +4,8 @@
 
 **Added in:** `@mastra/core@1.50.0`
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 `mastra.schedules` is the CRUD service for persisted cron schedules. Use it to create, list, update, pause, resume, manually run, and delete schedules for agents or workflows.
 
 For usage patterns and concepts, see [Schedules](https://mastra.ai/docs/long-running-agents/schedules).

package/.docs/reference/server/create-route.md

@@ -72,10 +72,36 @@ handler: async params => {
 
 ## Return value
 
-Returns a `ServerRoute` object that can be registered with an adapter.
+Returns a `ServerRoute` object that can be registered with an adapter or passed to `server.apiRoutes` on the `Mastra` instance.
 
 ## Examples
 
+### Register through `server.apiRoutes`
+
+Routes created with `createRoute()` can be passed to `server.apiRoutes`. The adapter registers them with runtime validation, typed handler parameters, and generated OpenAPI metadata. See [Custom API routes](https://mastra.ai/docs/server/custom-api-routes) for details.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { createRoute } from '@mastra/server/server-adapter'
+import { z } from 'zod'
+
+const createItemRoute = createRoute({
+  method: 'POST',
+  path: '/items',
+  responseType: 'json',
+  bodySchema: z.object({
+    name: z.string(),
+  }),
+  handler: async ({ name }) => ({ id: 'new-id', name }),
+})
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [createItemRoute],
+  },
+})
+```
+
 ### GET route with path params
 
 ```typescript

package/.docs/reference/server/register-api-route.md

@@ -22,6 +22,8 @@ registerApiRoute("/items/:itemId", { ... })
 
 Custom route paths can't start with the server's configured `apiPrefix` (default: `/api`), as that prefix is reserved for built-in Mastra routes. If you set a custom `apiPrefix`, only that prefix is reserved. For example, with `apiPrefix: '/mastra/api'`, paths like `/api/my-endpoint` are allowed.
 
+> **Warning:** The default auth configuration protects `/api/*` and treats `/api`, `/api/auth/*` as public. When you change `apiPrefix`, those defaults no longer match and built-in routes fall outside the protected pattern. Update `server.auth.protected` and `server.auth.public` to reference the new prefix, and update any client code (including `MastraClient` `apiPrefix`) that hits `/api/*`.
+
 ### options
 
 **method** (`'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'ALL'`): HTTP method for the route

package/.docs/reference/signals/create-notification-inbox-tool.md

@@ -4,6 +4,8 @@
 
 **Added in:** `@mastra/core@1.39.0`
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 `createNotificationInboxTool()` creates a Mastra tool that lets an agent inspect and manage notification inbox records for the current thread.
 
 Use this tool with durable notification signals. For sending notification records, see [`Agent.sendNotificationSignal()`](https://mastra.ai/reference/agents/agent).

package/.docs/reference/signals/signal-provider.md

@@ -4,6 +4,8 @@
 
 **Added in:** `@mastra/core@1.39.0`
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 Abstract base class for building signal providers. A signal provider monitors external sources (APIs, webhooks, event streams) and pushes notification signals into agent threads through a built-in subscription registry.
 
 Signal providers aren't processors by default. Providers that need to intercept agent execution return processors from `getInputProcessors()` or `getOutputProcessors()`. Providers that expose agent-callable tools return them from `getTools()`.

package/.docs/reference/signals/task-signal-provider.md

@@ -2,6 +2,8 @@
 
 # TaskSignalProvider
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 Bundles the built-in task tools (`task_write`, `task_update`, `task_complete`, `task_check`) and the `TaskStateProcessor` behind a single agent registration. Use it to add a structured, durable task list to an agent without wiring the tools and processor separately.
 
 Extends [`SignalProvider`](https://mastra.ai/reference/signals/signal-provider). The task list is stored in the thread-scoped `tasks` storage domain (the source of truth) and projected onto the agent state-signal lane by the processor, so it survives observational-memory truncation without invalidating the prompt cache.

package/.docs/reference/signals/webhook-signal-provider.md

@@ -4,6 +4,8 @@
 
 **Added in:** `@mastra/core@1.39.0`
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 Concrete signal provider for push-based event delivery. Routes incoming webhook payloads to subscribed agent threads by matching the payload against a configurable resource ID extractor.
 
 Extends [`SignalProvider`](https://mastra.ai/reference/signals/signal-provider) with public subscription management and a built-in `handleWebhook()` implementation.

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

@@ -338,7 +338,7 @@ const storage = new MastraCompositeStore({
 
 Observability data can quickly overwhelm general-purpose databases in production. A single agent interaction can generate hundreds of spans, and high-traffic applications can produce thousands of traces per day.
 
-**[ClickHouse](https://mastra.ai/reference/storage/clickhouse)** is recommended for production observability because it's optimized for high-volume, write-heavy analytics workloads. Use composite storage to route observability to ClickHouse while keeping other data in your primary database:
+**[ClickHouse](https://mastra.ai/integrations/databases/clickhouse)** is recommended for production observability because it's optimized for high-volume, write-heavy analytics workloads. Use composite storage to route observability to ClickHouse while keeping other data in your primary database:
 
 ```typescript
 import { MastraCompositeStore } from '@mastra/core/storage'
@@ -360,7 +360,7 @@ const storage = new MastraCompositeStore({
 })
 ```
 
-> **Note:** `ObservabilityStorageClickhouseVNext` is the current observability domain implementation. The legacy `ObservabilityStorageClickhouse` class is also exported and remains supported for projects that haven't migrated. See the [ClickHouse storage reference](https://mastra.ai/reference/storage/clickhouse) for details.
+> **Note:** `ObservabilityStorageClickhouseVNext` is the current observability domain implementation. The legacy `ObservabilityStorageClickhouse` class is also exported and remains supported for projects that haven't migrated. See the [ClickHouse storage reference](https://mastra.ai/integrations/databases/clickhouse) for details.
 
 ### Replicated ClickHouse for multi-replica clusters
 
@@ -392,6 +392,6 @@ const storage = new MastraCompositeStore({
 })
 ```
 
-Don't set `replication` on ClickHouse Cloud. Cloud rewrites `MergeTree` to `SharedMergeTree` server-side. See the [ClickHouse storage reference](https://mastra.ai/reference/storage/clickhouse) for the full config shape and operator notes.
+Don't set `replication` on ClickHouse Cloud. Cloud rewrites `MergeTree` to `SharedMergeTree` server-side. See the [ClickHouse storage reference](https://mastra.ai/integrations/databases/clickhouse) for the full config shape and operator notes.
 
-> **Info:** This approach is also required when using storage providers that don't support observability (like Convex, DynamoDB, or Cloudflare). See the [MastraStorageExporter documentation](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage) for the full list of supported providers.
+> **Note:** This approach is also required when using storage providers that don't support observability (like Convex, DynamoDB, or Cloudflare). See the [MastraStorageExporter documentation](https://mastra.ai/docs/observability/integrations/exporters/mastra-storage) for the full list of supported providers.

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

@@ -8,7 +8,7 @@ Storage grows without bound by default. Retention is an opt-in, age-based cleanu
 
 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/reference/storage/libsql), [PostgreSQL](https://mastra.ai/reference/storage/postgresql), and [MongoDB](https://mastra.ai/reference/storage/mongodb). Other adapters keep rows forever until they implement retention.
+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.
 
 ## Usage example
 
@@ -238,11 +238,11 @@ Handing that free space back to the OS is a separate concern that Mastra doesn't
 
 For MongoDB, deleted documents are reused by future insertions. To reclaim disk space, run [`db.runCommand({ compact: "collection_name" })`](https://www.mongodb.com/docs/manual/reference/command/compact/) during a maintenance window.
 
-> **LibSQL and Turso:** [Turso Cloud](https://mastra.ai/reference/storage/libsql) manages storage compaction for you, so there's nothing to reclaim manually. This applies only to self-hosted libSQL files.
+> **LibSQL and Turso:** [Turso Cloud](https://mastra.ai/integrations/databases/libsql) manages storage compaction for you, so there's nothing to reclaim manually. This applies only to self-hosted libSQL files.
 
 ## Related
 
-- [libSQL storage](https://mastra.ai/reference/storage/libsql)
-- [PostgreSQL storage](https://mastra.ai/reference/storage/postgresql)
+- [libSQL storage](https://mastra.ai/integrations/databases/libsql)
+- [PostgreSQL storage](https://mastra.ai/integrations/databases/postgresql)
 - [Composite storage](https://mastra.ai/reference/storage/composite)
 - [Storage overview](https://mastra.ai/reference/storage/overview)

package/.docs/reference/streaming/ChunkType.md

@@ -310,7 +310,7 @@ Signals the completion of a processing step.
 
 **payload.messageId** (`string`): Optional message identifier
 
-**payload.stepResult** (`object`): Step execution result with reason, warnings, and continuation info
+**payload.stepResult** (`object`): Step execution result with reason, warnings, and continuation info. rawReason holds the provider's own finish reason when it reports one.
 
 **payload.output** (`object`): Output information including usage statistics
 
@@ -334,13 +334,13 @@ Contains raw data from the provider.
 
 ### finish
 
-Stream has completed successfully.
+Stream has completed.
 
 **type** (`"finish"`): Chunk type identifier
 
 **payload** (`FinishPayload`): Completion information
 
-**payload.stepResult** (`object`): Step execution result
+**payload.stepResult** (`object`): Step execution result. reason holds the normalized finish reason, and rawReason holds the provider's own finish reason when it reports one. A reason of "error" means the run failed.
 
 **payload.output** (`object`): Output information including usage
 

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

@@ -10,7 +10,7 @@ The `.stream()` method enables real-time streaming of responses from an agent wi
 const stream = await agent.stream('message for agent')
 ```
 
-> **Info:** **Model Compatibility**: This method is designed for V2 models. V1 models should use the [`.streamLegacy()`](https://mastra.ai/reference/streaming/agents/streamLegacy) method. The framework automatically detects your model version and will throw an error if there's a mismatch.
+> **Note:** **Model Compatibility**: This method is designed for V2 models. V1 models should use the [`.streamLegacy()`](https://mastra.ai/reference/streaming/agents/streamLegacy) method. The framework automatically detects your model version and will throw an error if there's a mismatch.
 
 ## Parameters
 

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

@@ -2,7 +2,7 @@
 
 # Agent.streamLegacy() (Legacy)
 
-> **Warning:** **Deprecated**: This method is deprecated and only works with V1 models. For V2 models, use the new [`.stream()`](https://mastra.ai/reference/streaming/agents/stream) method instead. See the [migration guide](https://mastra.ai/guides/migrations/vnext-to-standard-apis) for details on upgrading.
+> **Warning:** **Deprecated**: This method is deprecated and only works with V1 models. For V2 models, use the new [`.stream()`](https://mastra.ai/reference/streaming/agents/stream) method instead. See the [migration guide](https://mastra.ai/reference/migrations/vnext-to-standard-apis) for details on upgrading.
 
 The `.streamLegacy()` method is the legacy version of the agent streaming API, used for real-time streaming of responses from V1 model agents. This method accepts messages and optional streaming options.
 
@@ -152,7 +152,7 @@ await agent.streamLegacy('message for agent', {
 
 ## Migration to new API
 
-> **Info:** The new `.stream()` method offers enhanced capabilities including AI SDK v5+ compatibility, better structured output handling, and improved callback system. See the [migration guide](https://mastra.ai/guides/migrations/vnext-to-standard-apis) for detailed migration instructions.
+> **Note:** The new `.stream()` method offers enhanced capabilities including AI SDK v5+ compatibility, better structured-output handling, and improved callback system. See the [migration guide](https://mastra.ai/reference/migrations/vnext-to-standard-apis) for detailed migration instructions.
 
 ### Quick Migration Example
 
@@ -180,7 +180,7 @@ const result = await agent.stream('message', {
 
 ## Related
 
-- [Migration Guide](https://mastra.ai/guides/migrations/vnext-to-standard-apis)
+- [Migration Guide](https://mastra.ai/reference/migrations/vnext-to-standard-apis)
 - [New .stream() method](https://mastra.ai/reference/streaming/agents/stream)
 - [Generating responses](https://mastra.ai/docs/agents/overview)
 - [Streaming responses](https://mastra.ai/docs/agents/overview)

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

@@ -32,7 +32,7 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
-> **Info:** `streamUntilIdle()` requires both a [`BackgroundTaskManager`](https://mastra.ai/reference/configuration) and a [memory](https://mastra.ai/docs/memory/overview) backend. Without either, it uses a plain `agent.stream()` call.
+> **Note:** `streamUntilIdle()` requires both a [`BackgroundTaskManager`](https://mastra.ai/reference/configuration) and a [memory](https://mastra.ai/docs/memory/overview) backend. Without either, it uses a plain `agent.stream()` call.
 
 ## Parameters
 

package/.docs/reference/tools/create-code-mode.md

@@ -4,6 +4,8 @@
 
 **Added in:** `@mastra/core@1.38.0`
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 The `createCodeMode()` function returns a tool and generated instructions that let an agent run multi-tool computations as one TypeScript function. The generated code runs in a workspace sandbox, and each `external_*` call runs the real tool on the host with validation, request context, and tracing.
 
 For a conceptual overview, see [Code mode](https://mastra.ai/docs/agents/code-mode).
@@ -62,7 +64,7 @@ export const shopAgent = new Agent({
 
 **config.id** (`string`): The generated tool id.
 
-**transport** (`CodeModeTransport`): Optional transport implementation used to run the generated code in the sandbox. The default transport uses stdio JSON-RPC over the workspace sandbox process API. Transports that declare requiresSandbox: false (such as IsolatedVmCodeModeTransport) run without a sandbox.
+**transport** (`CodeModeTransport`): Optional transport implementation used to run the generated code in the sandbox. The default transport uses stdio JSON-RPC over the workspace sandbox process API. Transports that declare requiresSandbox: false (such as IsolatedVmCodeModeTransport and QuickJsCodeModeTransport) run without a sandbox.
 
 ## Returns