@mastra/mcp-docs-server 1.2.13-alpha.0 → 1.2.13-alpha.11

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

@@ -53,14 +53,12 @@ const agent = new Agent({
   id: 'my-agent',
   name: 'my-agent',
   model: 'openai/gpt-5-nano',
-  processors: {
-    input: [
-      new RegexFilterProcessor({
-        presets: ['pii', 'secrets'],
-        strategy: 'block',
-      }),
-    ],
-  },
+  inputProcessors: [
+    new RegexFilterProcessor({
+      presets: ['pii', 'secrets'],
+      strategy: 'block',
+    }),
+  ],
 })
 ```
 
@@ -80,6 +78,8 @@ const agent = new Agent({
 
 **phase** (`'input' | 'output' | 'all'`): Phases to apply the filter. 'input' filters input messages. 'output' filters output stream and result. 'all' filters both. (Default: `'all'`)
 
+**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`)
+
 ## Returns
 
 **id** (`'regex-filter'`): Processor identifier.
@@ -106,4 +106,76 @@ When the `block` strategy is active (default), `RegexFilterProcessor` throws a `
 | --------- | ------------------------------------------------ | ---------------------------------------------- |
 | `pii`     | Emails, phone numbers, SSNs, credit card numbers | `[EMAIL]`, `[PHONE]`, `[SSN]`, `[CREDIT_CARD]` |
 | `secrets` | API keys, bearer tokens, AWS access keys         | `[API_KEY]`, `[BEARER_TOKEN]`, `[AWS_KEY]`     |
-| `urls`    | HTTP/HTTPS URLs                                  | `[URL]`                                        |
+| `urls`    | HTTP/HTTPS URLs                                  | `[URL]`                                        |
+
+## Redaction behavior
+
+Every rule is matched independently, so two rules can claim text that overlaps. A card number written without separators matches both `phone` and `credit-card`, for example. Overlapping matches are combined into a single region and replaced once, using the replacement of the longest match.
+
+```typescript
+const filter = new RegexFilterProcessor({
+  presets: ['pii'],
+  strategy: 'redact',
+})
+
+// "Charge 4111111111111111 today" becomes "Charge [CREDIT_CARD] today"
+```
+
+A replacement string can reference capture groups with `$1` or `$&`. Those references resolve for a single match whose pattern also matches the matched text on its own. In a combined region, or for a rule anchored on its surroundings with a lookbehind or lookahead, the replacement string is inserted as written. The region is redacted either way.
+
+## Redaction reporting
+
+The `redact` strategy rewrites text in place, so nothing downstream can tell what changed. Assign `onViolation` to record it. The processor calls it once per redacted message, message part, or stream chunk, and offsets are relative to that piece of text. Async callbacks are awaited, and errors are caught so an unavailable audit sink can't fail the request.
+
+```typescript
+import { RegexFilterProcessor, type RegexRedactionDetail } from '@mastra/core/processors'
+
+const filter = new RegexFilterProcessor({
+  presets: ['pii'],
+  strategy: 'redact',
+})
+
+filter.onViolation = async ({ detail }) => {
+  const redaction = detail as RegexRedactionDetail
+
+  for (const entry of redaction.redactions) {
+    await auditLog.write({
+      phase: redaction.phase,
+      messageId: redaction.messageId,
+      rule: entry.rule,
+      offset: entry.index,
+      length: entry.length,
+    })
+  }
+}
+```
+
+The callback is awaited, including in `processOutputStream`, where it runs for every chunk that contains a match. Keep the callback fast, or hand the work to a queue, so a slow audit sink doesn't stall a streaming response. With no callback attached, the `redact` path stays synchronous.
+
+The `block` strategy reports through the same callback. There the processor runner invokes it when it catches the `TripWire`, so `detail` holds the tripwire metadata described under [Error behavior](#error-behavior) rather than the shape below.
+
+`detail` for a redaction is a `RegexRedactionDetail`:
+
+**strategy** (`'redact'`): Distinguishes a redaction report from the block strategy payload.
+
+**phase** (`'processInput' | 'processOutputStream' | 'processOutputResult'`): Processor method that applied the redactions.
+
+**messageId** (`string`): Id of the message the text came from. Absent for stream chunks.
+
+**partIndex** (`number`): Index of the redacted part in the message's parts array, which also contains non-text parts. Absent for string content and stream chunks.
+
+**redactions** (`RegexRedaction[]`): Redactions in the order they appear in the text.
+
+**redactions.rule** (`string`): Name of the rule whose replacement was used.
+
+**redactions.index** (`number`): Start offset of the redacted span in the text.
+
+**redactions.length** (`number`): Length of the redacted span.
+
+**redactions.replacement** (`string`): Text that replaced the span.
+
+**redactions.overlappingRules** (`string[]`): Names of all rules that matched this span, set only when more than one overlapped.
+
+**redactions.value** (`string`): The text that was redacted. Set only when includeRedactedValues is enabled.
+
+Values are left out by default. An audit trail that copies the data it protects widens the exposure it was added to narrow. Set `includeRedactedValues` only when the destination is as protected as the original, and note that the `block` strategy also withholds matched text from its `TripWire` metadata for the same reason.

package/.docs/reference/processors/token-limiter-processor.md

@@ -44,12 +44,26 @@ const processor = new TokenLimiterProcessor({
 
 **processInputStep** (`(args: ProcessInputStepArgs) => Promise<void>`): Prunes messages at each step of the agentic loop (including tool call continuations) to keep the conversation within the token limit. Mutates the messageList directly by removing oldest messages first while preserving system messages.
 
-**processOutputStream** (`(args: { part: ChunkType; streamParts: ChunkType[]; state: Record<string, any>; abort: (reason?: string) => never }) => Promise<ChunkType | null>`): Processes streaming output parts to limit token count during streaming
+**processOutputStream** (`(args: ProcessOutputStreamArgs) => Promise<ChunkType | null>`): Processes streaming output parts to limit token count during streaming. Only text and object parts count against the limit and can be withheld; lifecycle, reasoning and tool parts always pass through.
 
 **processOutputResult** (`(args: { messages: MastraDBMessage[]; abort: (reason?: string) => never }) => Promise<MastraDBMessage[]>`): Processes final output results to limit token count in non-streaming scenarios
 
 **getMaxTokens** (`() => number`): Get the maximum token limit
 
+## Output stream behavior
+
+As an output processor, only parts that carry generated output count against the limit: `text-delta` and `object`. Lifecycle parts (such as `step-start`), reasoning deltas, response metadata, and tool parts (`tool-call`, `tool-result`) are neither counted nor withheld, so tool calls always reach the agentic loop and get executed.
+
+With the default `truncate` strategy, the first time output is withheld the processor emits a transient `data-token-limit-reached` part on the stream:
+
+```typescript
+for await (const part of stream.fullStream) {
+  if (part.type === 'data-token-limit-reached') {
+    console.log('output truncated at', part.data.limit, 'tokens')
+  }
+}
+```
+
 ## Error behavior
 
 When used as an input processor (both `processInput` and `processInputStep`), `TokenLimiterProcessor` throws a `TripWire` error in the following cases:

package/.docs/reference/project-structure.md

@@ -44,7 +44,7 @@ Mastra recommends organizing your code into the following folders:
 
 Mastra has two special folder conventions:
 
-- `src/mastra/agents/<name>`: You can define an agent by file convention instead of constructing it in code. Learn more in the [File-based Agents](https://mastra.ai/docs/getting-started/file-based-agents) docs.
+- `src/mastra/agents/<name>`: You can define an agent by file convention instead of constructing it in code. Learn more in the [File-based Agents](https://mastra.ai/docs/getting-started/develop) docs.
 - `src/mastra/public`: Contents are copied into the `.build/output` directory during the build process, making them available for serving at runtime.
 
 ### Top-level files

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/docs/rag/retrieval)
+- [Hybrid Vector Search](https://mastra.ai/guides/rag/retrieval)
 - [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)

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

@@ -188,6 +188,8 @@ export const mastra = new Mastra({
 
 **default** (`MastraCompositeStore`): Default storage adapter. Domains not explicitly specified in domains will use this storage's domains as fallbacks.
 
+**editor** (`MastraCompositeStore`): Storage adapter for Editor-owned domains, including agents, prompt blocks, scorers, MCP clients and servers, workspaces, and skills. Takes precedence over default storage but not explicit domain overrides.
+
 **disableInit** (`boolean`): When true, automatic initialization is disabled. You must call init() explicitly.
 
 **domains** (`object`): Individual domain overrides. Each domain can come from a different storage adapter. These take precedence over both editor and default storage. Set a domain to false to disable it entirely; a disabled domain does not fall back to editor or default.

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

@@ -214,7 +214,7 @@ const stream = await agent.stream('message for agent')
 
 **options.tracingOptions.tags** (`string[]`): Tags to apply to this trace. String labels for categorizing and filtering traces.
 
-**options.versions** (`VersionOverrides`): Per-invocation version overrides for sub-agent delegation. Merged on top of Mastra instance-level versions and propagated automatically through sub-agent calls via requestContext. Requires the editor package. See Sub-agent versioning.
+**options.versions** (`VersionOverrides`): Per-invocation version overrides for sub-agent delegation. Merged on top of Mastra instance-level versions and propagated automatically through sub-agent calls via requestContext. Requires the editor package. See Editor versioning.
 
 **options.versions.agents** (`Record<string, VersionSelector>`): A map of agent IDs to their version selectors.
 

package/.docs/reference/tools/isolated-vm-transport.md

@@ -34,7 +34,7 @@ yarn add @mastra/isolated-vm
 bun add @mastra/isolated-vm
 ```
 
-`isolated-vm` is a native addon. It ships prebuilt binaries for common platforms, so installation usually needs no extra setup. A C++ toolchain is only needed on platforms without a matching prebuild, where it falls back to compiling from source.
+`isolated-vm` is a native addon. It provides prebuilt binaries for common platforms, so installation usually needs no extra setup. A C++ toolchain is only needed on platforms without a matching prebuild, where it falls back to compiling from source.
 
 On Node.js 20 and later, the host process must be started with the `--no-node-snapshot` flag, otherwise creating an isolate crashes the process. The constructor throws an error when the flag is missing. Pass the flag when starting your server, or set it through `NODE_OPTIONS`:
 

package/.docs/reference/vectors/mongodb.md

@@ -109,7 +109,7 @@ Waits for an index to become ready after creation. Useful when you need to ensur
 
 ### `upsert()`
 
-Adds or updates vectors and their metadata in the collection. On a bring-your-own index this requires `allowWrites: true` at `createIndex()` time — BYO collections are read-only by default.
+Adds or updates vectors and their metadata in the collection. On a bring-your-own index, this requires `allowWrites: true` at `createIndex()` time because BYO collections are read-only by default.
 
 **indexName** (`string`): Name of the collection to insert into
 
@@ -148,12 +148,12 @@ Provisions an Atlas Search (BM25/full-text) index on the collection backing an i
 **Managed vs. bring-your-own collections:**
 
 - For a **managed** index (created without `collectionName`), `createIndex()` already provisions a _dynamic_ full-text index named `${collectionName}_search_index` (covering all string fields). `createSearchIndex()` is therefore only needed when you want a **field-restricted** mapping or a **custom index name**.
-- For a **bring-your-own** index (created with `collectionName`), `createIndex()` does **not** auto-create any full-text index — enabling `textQuery()`/`hybridQuery()` on a caller-owned operational collection is **opt-in**. Call `createSearchIndex()` explicitly to provision the (billable) text index; until you do, `textQuery()`/`hybridQuery()` throw a clear error rather than querying a non-existent index.
+- For a **bring-your-own** index (created with `collectionName`), `createIndex()` doesn't auto-create any full-text index. Enabling `textQuery()`/`hybridQuery()` on a caller-owned operational collection is opt-in. Call `createSearchIndex()` explicitly to provision the (billable) text index. Until you do, `textQuery()`/`hybridQuery()` throw a clear error rather than querying a non-existent index.
 
 Naming:
 
-- When `fields` is provided **without** an explicit `searchIndexName`, the field-mapped index is created under a **distinct** default name (`${collectionName}_${indexName}_search_fields_index`, unique per logical index) so it does not collide with — and get silently ignored by — a managed collection's auto-created dynamic index. This distinct index is persisted as the text-search index, so `textQuery()`/`hybridQuery()` use the restricted mapping automatically.
-- When `searchIndexName` is provided, that exact name is used and persisted. `textQuery()`/`hybridQuery()` resolve the persisted name automatically; you can also override the name per call via their `searchIndexName` / `textSearchIndexName` parameters.
+- When `fields` is provided **without** an explicit `searchIndexName`, the field-mapped index is created under a **distinct** default name (`${collectionName}_${indexName}_search_fields_index`, unique per logical index) so it doesn't collide with a managed collection's auto-created dynamic index and get silently ignored. This distinct index is persisted as the text-search index, so `textQuery()`/`hybridQuery()` use the restricted mapping automatically.
+- When `searchIndexName` is provided, that exact name is used and persisted. `textQuery()`/`hybridQuery()` resolve the persisted name automatically. You can also override the name per call via their `searchIndexName` / `textSearchIndexName` parameters.
 
 **indexName** (`string`): Name of the Mastra index whose collection will have the search index
 
@@ -170,7 +170,7 @@ await store.createSearchIndex({
 })
 ```
 
-> **Note:** The field-mapped index name includes the logical `indexName`, so two logical indexes on the same collection get distinct text indexes. Recreating the _same_ logical index with different `fields` still requires dropping the existing index first (`IndexAlreadyExists`).
+The field-mapped index name includes the logical `indexName`, so two logical indexes on the same collection get distinct text indexes. Recreating the _same_ logical index with different `fields` still requires dropping the existing index first (`IndexAlreadyExists`).
 
 ### `waitForSearchIndexReady()`
 
@@ -193,7 +193,7 @@ await store.waitForSearchIndexReady({ indexName: 'precedents' })
 
 Runs a full-text (BM25) search against an Atlas Search index. By default it targets the text-search index recorded for this index (set by `createSearchIndex()`, or the dynamic `${collectionName}_search_index` auto-created by `createIndex()`). Pass `searchIndexName` to target a specific index for this call.
 
-**Note:** metadata filters here (like `hybridQuery()`) are applied via a `$match` stage. For the vector branch of `hybridQuery()`, filters on fields not declared via `filterFields` at index creation are transparently materialised as candidate `_id`s (the same fallback `query()` uses), so undeclared-field filters do not error.
+Metadata filters here (like `hybridQuery()`) are applied via a `$match` stage. For the vector branch of `hybridQuery()`, filters on fields not declared via `filterFields` at index creation are transparently materialised as candidate `_id`s (the same fallback `query()` uses), so undeclared-field filters don't error.
 
 **indexName** (`string`): Name of the Mastra index to search
 
@@ -220,7 +220,7 @@ const results = await store.textQuery({
 
 ### `hybridQuery()`
 
-Runs a hybrid search that fuses vector similarity and full-text results using MongoDB's server-side `$rankFusion` (requires MongoDB >= 8.0; generally available from 8.1, and on 8.0.x it may need a MongoDB support case to enable — it runs where enabled, e.g. Atlas 8.0.x). A full-text search index must exist: it is auto-created for managed indexes, but for a bring-your-own collection you must call `createSearchIndex()` first (opt-in).
+Runs a hybrid search that fuses vector similarity and full-text results using MongoDB's server-side `$rankFusion`. It requires MongoDB >= 8.0 and is generally available from 8.1. On 8.0.x, it may need a MongoDB support case to enable, and it runs where enabled, such as Atlas 8.0.x. A full-text search index must exist: it's auto-created for managed indexes, but for a bring-your-own collection you must call `createSearchIndex()` first (opt-in).
 
 **indexName** (`string`): Name of the Mastra index to search
 
@@ -253,7 +253,7 @@ const results = await store.hybridQuery({
 })
 ```
 
-**Note:** `hybridQuery()` requires MongoDB >= 8.0 for the `$rankFusion` stage (generally available from 8.1; on 8.0.x it may need a MongoDB support case to enable, and runs where enabled, such as Atlas 8.0.x). If you're running an older version, or `$rankFusion` is not enabled on your 8.0.x deployment, use `query()` and `textQuery()` separately and merge the results client-side.
+`hybridQuery()` requires MongoDB >= 8.0 for the `$rankFusion` stage. The stage is generally available from 8.1. On 8.0.x, it may need a MongoDB support case to enable and runs where enabled, such as Atlas 8.0.x. If you're running an older version, or `$rankFusion` isn't enabled on your 8.0.x deployment, use `query()` and `textQuery()` separately and merge the results client-side.
 
 ### `describeIndex()`
 
@@ -276,15 +276,15 @@ interface IndexStats {
 Deletes a vector index. Behavior depends on how the index was created:
 
 - **Managed index** (created without `collectionName`): drops the entire collection and all its data.
-- **Bring-your-own index** (created with `collectionName`): drops the Atlas vectorSearch index **and**, if one was provisioned via `createSearchIndex()`, the companion full-text search index. The caller's operational collection and its documents are **preserved** — this store never drops a collection it did not create.
+- **Bring-your-own index** (created with `collectionName`): drops the Atlas vectorSearch index and, if one was provisioned via `createSearchIndex()`, the companion full-text search index. The caller's operational collection and its documents are preserved. This store never drops a collection it didn't create.
 
-The BYO classification is recorded durably when the index is created, so it is applied correctly even by a different process (e.g. an index created by a setup job and later deleted by a long-lived service). Always pass the **logical index name** (the `indexName` used at `createIndex`), not the physical collection name.
+The BYO classification is recorded durably when the index is created, so it's applied correctly even by a different process (e.g. an index created by a setup job and later deleted by a long-lived service). Always pass the **logical index name** (the `indexName` used at `createIndex`), not the physical collection name.
 
 **indexName** (`string`): Logical name of the index to delete
 
 ### `listIndexes()`
 
-Lists the **logical** Mastra index names (the `indexName` values passed to `createIndex`), not physical collection names. For a bring-your-own index whose data lives in an operational collection, the logical index name is returned — never the physical collection name — so the value can be passed straight back into `deleteIndex()` / `describeIndex()`. Managed indexes created before durable metadata was introduced are still discovered via their `${name}_vector_index` search index. The internal registry collection is never listed.
+Lists the **logical** Mastra index names (the `indexName` values passed to `createIndex`), not physical collection names. For a bring-your-own index whose data lives in an operational collection, the logical index name is returned instead of the physical collection name. The value can be passed straight back into `deleteIndex()` / `describeIndex()`. Managed indexes created before durable metadata was introduced are still discovered via their `${name}_vector_index` search index. The internal registry collection is never listed.
 
 Returns: `Promise<string[]>`
 
@@ -408,12 +408,12 @@ await store.createSearchIndex({ indexName: 'precedents', fields: ['note'] })
 
 - The collection must already exist and contain documents with an `embedding` field (or the custom `embeddingFieldPath` you configured)
 - The collection is never created or dropped when using `collectionName`
-- **A BYO index is read-only by default.** `upsert()`, `updateVector()`, `deleteVector()`, and `deleteVectors()` throw a clear error rather than mutating caller-owned operational documents. To let the store write embeddings into (or delete documents from) your collection, opt in explicitly with `createIndex({ ..., allowWrites: true })`. The policy is persisted and survives restarts; entries written by older versions without the flag are treated as read-only (fail closed).
+- **A BYO index is read-only by default.** `upsert()`, `updateVector()`, `deleteVector()`, and `deleteVectors()` throw a clear error rather than mutating caller-owned operational documents. To let the store write embeddings into (or delete documents from) your collection, opt in explicitly with `createIndex({ ..., allowWrites: true })`. The policy is persisted and survives restarts. Entries written by older versions without the flag are treated as read-only (fail closed).
 - Use `metadataMode: 'document'` when querying to retrieve the full source document as `metadata`
 - In `'document'` mode the embedding is omitted from `metadata` by default; pass `includeVector: true` to retain it (and also expose it as a top-level `vector`)
 - **Filtering in `'document'` mode operates on root document fields**, not a nested `metadata.` subdocument. `filter: { lane: 'fraud' }` matches the top-level `lane` field of your operational documents (in the default `'field'` mode, bare fields are rewritten to `metadata.<field>` for managed collections). Both the pushdown and `$match` fallback paths honor this.
 - **Native `ObjectId` `_id`s are supported.** Operational collections commonly key on `ObjectId`; query results coerce `_id` to a string (the `QueryResult.id` contract), and `deleteVector()`/`updateVector()`/`deleteVectors()` accept that string and match the underlying `ObjectId` document. Managed collections (string `_id`s) are unaffected.
-- Full-text and hybrid search on a BYO collection are **opt-in**: no full-text index is auto-created, so call `createSearchIndex()` before `textQuery()`/`hybridQuery()`. The full-text index builds asynchronously — call `waitForSearchIndexReady()` (or pass `waitUntilReady: true`) before an immediate text/hybrid query.
+- Full-text and hybrid search on a BYO collection are **opt-in**: no full-text index is auto-created, so call `createSearchIndex()` before `textQuery()`/`hybridQuery()`. The full-text index builds asynchronously. Call `waitForSearchIndexReady()` (or pass `waitUntilReady: true`) before an immediate text/hybrid query.
 - `deleteIndex()` on a BYO index drops the vector index (and the text index if one was created) but **preserves** the collection and its documents
 
 ## Best practices

package/.docs/reference/voice/livekit.md

@@ -4,7 +4,7 @@
 
 The `@mastra/livekit` package connects Mastra agents to the LiveKit Agents framework. LiveKit runs the audio pipeline (voice activity detection, speech-to-text, turn detection, text-to-speech, barge-in) and the package bridges reply generation to a Mastra agent's `stream()` call.
 
-See [Realtime voice](https://mastra.ai/docs/voice/realtime-voice) for setup and concepts.
+See [Realtime voice](https://mastra.ai/guides/voice/realtime-voice) for setup and concepts.
 
 The package has three entry points:
 
@@ -148,7 +148,7 @@ Returns: `VoiceTurnMessage[]`, where each entry is `{ role: 'system' | 'user' |
 
 ## `MastraLLM`
 
-A standard LiveKit LLM plugin (`llm.LLM`) backed by a Mastra agent. Use it when you build the `voice.AgentSession` yourself and want Mastra in the `llm` slot. [`createLiveKitWorker()`](#createlivekitworker) is the managed alternative. See [Use Mastra as the LLM component](https://mastra.ai/docs/voice/realtime-voice) for how to choose.
+A standard LiveKit LLM plugin (`llm.LLM`) backed by a Mastra agent. Use it when you build the `voice.AgentSession` yourself and want Mastra in the `llm` slot. [`createLiveKitWorker()`](#createlivekitworker) is the managed alternative. See [Use Mastra as the LLM component](https://mastra.ai/guides/voice/realtime-voice) for how to choose.
 
 With `remote`, the plugin streams each turn from your Mastra server over HTTP using Server-Sent Events (SSE). The agent loop, tools, and memory run server-side, and interrupting the agent aborts the server-side generation.
 
@@ -478,5 +478,5 @@ The metadata travels as a JSON string. `liveKitConnectionRoute()` and `dispatchV
 
 ## Related
 
-- [Realtime voice](https://mastra.ai/docs/voice/realtime-voice)
+- [Realtime voice](https://mastra.ai/guides/voice/realtime-voice)
 - [LiveKit Agents docs](https://docs.livekit.io/agents/)

package/.docs/reference/workers/overview.md

@@ -10,14 +10,14 @@ For usage patterns and deployment topologies, see [Workers](https://mastra.ai/do
 
 Controls which workers start in the current process.
 
-| Value                       | Behavior                                                              |
-| --------------------------- | --------------------------------------------------------------------- |
-| _(not set)_                 | Default workers are auto-created based on configuration               |
-| `"false"`                   | Disables all event processing. The process only serves HTTP requests. |
-| `"orchestration"`           | Only the orchestration worker starts                                  |
-| `"scheduler"`               | Only the scheduler worker starts                                      |
-| `"backgroundTasks"`         | Only the background task worker starts                                |
-| `"orchestration,scheduler"` | Multiple workers (comma-separated)                                    |
+| Value                       | Behavior                                                                                                                                                  |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| _(not set)_                 | Default workers are auto-created based on configuration                                                                                                   |
+| `"false"`                   | Disables worker event processing. The process serves HTTP requests and can still publish events to PubSub (e.g., workflow starts) without consuming them. |
+| `"orchestration"`           | Only the orchestration worker starts                                                                                                                      |
+| `"scheduler"`               | Only the scheduler worker starts                                                                                                                          |
+| `"backgroundTasks"`         | Only the background task worker starts                                                                                                                    |
+| `"orchestration,scheduler"` | Multiple workers (comma-separated)                                                                                                                        |
 
 Use this to run different worker types in separate containers from the same build artifact.
 
@@ -29,6 +29,8 @@ The base URL of the API server, used by the orchestration worker to execute work
 MASTRA_STEP_EXECUTION_URL=http://api:4111/api
 ```
 
+Use HTTPS URLs in production. See [Security recommendations](https://mastra.ai/docs/server/auth/workers).
+
 The orchestration worker sends step execution requests to:
 
 ```text

package/.docs/reference/workspace/platform-filesystem.md

@@ -4,7 +4,7 @@
 
 Stores files in a Mastra Platform workspace bucket. Each Mastra Platform environment can have one bucket, and `PlatformFilesystem` gives agents `read`, `write`, `list`, `delete`, and `move` operations against it.
 
-Use `PlatformFilesystem` when your agent runs on a Mastra Platform deployment and you want the filesystem to be backed by the platform-provisioned bucket. For direct S3 access, see [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem). For a local directory during development, see [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem).
+Related providers: [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem) for direct S3 access, [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) for local directories.
 
 > **Info:** For interface details, see [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem).
 
@@ -39,7 +39,7 @@ Configure the platform credentials. The access token, project ID, and bucket nam
 **.env file**:
 
 ```bash
-MASTRA_PLATFORM_SECRET_KEY=your-platform-secret-key
+MASTRA_PLATFORM_ACCESS_TOKEN=your-platform-access-token
 MASTRA_PROJECT_ID=your-project-id
 MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name
 ```
@@ -54,7 +54,7 @@ new PlatformFilesystem({
 })
 ```
 
-On a Mastra Platform deployment these variables are injected automatically, so the constructor can be called with no options.
+On a Mastra Platform deployment, `MASTRA_PLATFORM_ACCESS_TOKEN`, `MASTRA_PROJECT_ID`, and `MASTRA_PLATFORM_BUCKET_NAME` are injected automatically, so the constructor can be called with no options. For local development, `MASTRA_PLATFORM_ACCESS_TOKEN` can contain an `sk_` API token from your organization's settings page under **API Tokens**.
 
 ## Usage
 
@@ -116,7 +116,7 @@ await fs.writeFile('/analyses/repo.md', 'x') // throws WorkspaceReadOnlyError
 
 ## Constructor parameters
 
-**accessToken** (`string`): Platform secret key. Falls back to the MASTRA\_PLATFORM\_SECRET\_KEY environment variable (MASTRA\_PLATFORM\_ACCESS\_TOKEN is a deprecated fallback).
+**accessToken** (`string`): Platform access token. Falls back to the MASTRA\_PLATFORM\_ACCESS\_TOKEN environment variable.
 
 **projectId** (`string`): Platform project ID. Falls back to the MASTRA\_PROJECT\_ID environment variable.
 
@@ -157,7 +157,8 @@ Filesystem-specific errors match the standard workspace error types:
 Other Platform API failures raise `PlatformApiError`. Structured `{ error: { message, type } }` responses are parsed into `.code` (machine-readable kind) and `.proxyMessage` (human string):
 
 ```typescript
-import { FileNotFoundError, PlatformApiError } from '@mastra/platform-workspace'
+import { FileNotFoundError } from '@mastra/core/workspace'
+import { PlatformApiError } from '@mastra/platform-workspace'
 
 try {
   await fs.readFile('/missing.txt')
@@ -173,6 +174,8 @@ try {
 }
 ```
 
+`FileNotFoundError`, `FileExistsError`, and `WorkspaceReadOnlyError` are re-exports of the standard workspace error types from `@mastra/core/workspace`. `PlatformApiError` is specific to `@mastra/platform-workspace`.
+
 `code` and `proxyMessage` are `undefined` when the response body isn't JSON, for example an HTML 502 from a load balancer.
 
 ## Related

package/.docs/reference/workspace/platform-sandbox.md

@@ -2,9 +2,11 @@
 
 # PlatformSandbox
 
-Executes commands inside a Mastra Platform sandbox tied to a Platform environment. Sandboxes boot from a pre-built recipe checkpoint with Python 3, Node 22, TypeScript, tsx, and common build tooling already installed.
+Client for provisioning sandboxes in a Mastra Platform environment. Each `PlatformSandbox` instance owns one remote sandbox: `start()` provisions it, `executeCommand()` runs against it, and `destroy()` tears it down. Construct additional instances to own additional remote sandboxes. Use `clone()` to derive them from a configured template (see [Cloning](#cloning-for-a-fleet-of-sandboxes)).
 
-Use `PlatformSandbox` when your agent runs on a Mastra Platform deployment and you want the sandbox to be provisioned and managed by the platform. For self-hosted Railway sandboxes, see [`RailwaySandbox`](https://mastra.ai/reference/workspace/railway-sandbox). For a local sandbox during development, see [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox).
+Sandboxes boot from a pre-built recipe checkpoint with Python 3, Node 22, TypeScript, tsx, and common build tooling already installed. Pass a stable `id` to opt into [checkpoint recovery](#checkpoint-recovery) so a new sandbox boots from the previous one's filesystem.
+
+Related providers: [`RailwaySandbox`](https://mastra.ai/reference/workspace/railway-sandbox) for self-hosted Railway sandboxes, [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) for local sandboxes.
 
 > **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
 
@@ -39,7 +41,7 @@ Configure the platform credentials. The access token, project ID, and environmen
 **.env file**:
 
 ```bash
-MASTRA_PLATFORM_SECRET_KEY=your-platform-secret-key
+MASTRA_PLATFORM_ACCESS_TOKEN=your-platform-access-token
 MASTRA_PROJECT_ID=your-project-id
 MASTRA_ENVIRONMENT_ID=your-environment-id
 ```
@@ -54,7 +56,7 @@ new PlatformSandbox({
 })
 ```
 
-On a Mastra Platform deployment these variables are injected automatically, so the constructor can be called with no options.
+On a Mastra Platform deployment, `MASTRA_PLATFORM_ACCESS_TOKEN`, `MASTRA_PROJECT_ID`, and `MASTRA_ENVIRONMENT_ID` are injected automatically, so the constructor can be called with no options. For local development, `MASTRA_PLATFORM_ACCESS_TOKEN` can contain an `sk_` API token from your organization's settings page under **API Tokens**.
 
 ## Usage
 
@@ -103,7 +105,7 @@ The default `ISOLATED` mode allows outbound internet access only, with no privat
 
 ### Reattaching to a running sandbox
 
-Pass an existing `sandboxId` to reattach to a live sandbox instead of creating a new one. This is useful for stateful agents that resume between requests:
+Pass an existing `sandboxId` to reattach to a live sandbox instead of creating a new one:
 
 ```typescript
 const sandbox = new PlatformSandbox({
@@ -116,6 +118,42 @@ const result = await sandbox.executeCommand('cat', ['/workspace/state.json'])
 
 When `sandboxId` is set, `environmentId` isn't required because the sandbox already exists.
 
+### Checkpoint recovery
+
+The constructor `id` (explicit or auto-generated) is sent to the platform on `POST /sandbox` as an advisory recovery key:
+
+- If the platform recognises the `id` from a previous session, the new sandbox boots from the most recent checkpoint of that earlier sandbox's filesystem instead of the base recipe.
+- If the `id` isn't recognised, the platform starts a fresh sandbox from the base recipe. Auto-generated ids never match, so omitting `id` disables checkpoint recovery.
+
+Pass a stable `id` to preserve a sandbox's filesystem across sessions or across a `destroy()`/`start()` cycle:
+
+```typescript
+const sandbox = new PlatformSandbox({
+  id: `project-${projectId}`,
+})
+await sandbox.start() // Boots from the most recent checkpoint for this id, or fresh if unknown
+```
+
+Checkpoint recovery is coarser than `sandboxId` reattachment. Reattaching (via `sandboxId`) rejoins the exact live sandbox and its running processes. Checkpoint recovery constructs a brand new sandbox and restores its filesystem from the latest checkpoint the platform captured for the previous sandbox with that `id`. Running processes and any filesystem writes made after the last checkpoint aren't restored.
+
+Each `id` maps to one independent filesystem. Reusing the same `id` across unrelated sandboxes causes the platform to boot them from each other's checkpoint.
+
+### Cloning for a fleet of sandboxes
+
+`clone()` returns an independent sibling `PlatformSandbox` that inherits credentials and defaults (access token, project, environment, network isolation, timeout, instructions, env, idle timeout) with per-instance overrides. The returned sandbox is unstarted and provisions on its own `start()`, so `clone()` performs no I/O:
+
+```typescript
+const template = new PlatformSandbox({
+  networkIsolation: 'PRIVATE',
+  idleTimeoutMinutes: 30,
+})
+
+const perProject = template.clone({ id: `project-${projectId}` })
+await perProject.start()
+```
+
+Combine `clone()` with a stable `id` per clone to opt each clone into [checkpoint recovery](#checkpoint-recovery) independently.
+
 ### Executing commands
 
 `executeCommand` runs a command on the remote sandbox and returns its output. Pass `args` to have arguments safely shell-quoted:
@@ -135,7 +173,7 @@ console.log(result.exitCode)
 
 ## Constructor parameters
 
-**accessToken** (`string`): Platform secret key. Falls back to the MASTRA\_PLATFORM\_SECRET\_KEY environment variable (MASTRA\_PLATFORM\_ACCESS\_TOKEN is a deprecated fallback).
+**accessToken** (`string`): Platform access token. Falls back to the MASTRA\_PLATFORM\_ACCESS\_TOKEN environment variable.
 
 **projectId** (`string`): Platform project ID. Falls back to the MASTRA\_PROJECT\_ID environment variable.
 
@@ -153,7 +191,7 @@ console.log(result.exitCode)
 
 **instructions** (`string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)`): Custom instructions returned by getInstructions(). A string fully replaces the defaults; a function receives the defaults and can extend or customize them per-request.
 
-**id** (`string`): Unique identifier for this sandbox instance. (Default: `Auto-generated`)
+**id** (`string`): Unique identifier for this sandbox instance. Sent to the platform as an advisory recovery key: if the platform recognizes the id from a previous sandbox, the new sandbox boots from that sandbox's most recent checkpoint instead of the base recipe. Unknown ids fall through to a fresh sandbox. Auto-generated when omitted, which disables checkpoint recovery. (Default: `Auto-generated`)
 
 **fetch** (`typeof fetch`): Custom fetch implementation, mainly for testing.
 
@@ -169,6 +207,22 @@ console.log(result.exitCode)
 
 **processes** (`PlatformProcessManager`): Background process manager. See SandboxProcessManager reference.
 
+## Methods
+
+**start** (`() => Promise<void>`): Provision the remote sandbox, or reattach when sandboxId was passed to the constructor. Idempotent once the sandbox is running. A destroyed reattach target falls through to a fresh provision.
+
+**destroy** (`() => Promise<void>`): Tear down the remote sandbox and clear the cached exec lease. A subsequent start() provisions a fresh sandbox (or restores from checkpoint when a stable id is set).
+
+**stop** (`() => Promise<void>`): Alias for destroy().
+
+**executeCommand** (`(command: string, args?: string[], options?: ExecuteCommandOptions) => Promise<CommandResult>`): Run a command on the remote sandbox and return its stdout, stderr, exitCode, and executionTimeMs. command is a shell string, args are safely shell-quoted.
+
+**clone** (`(options?: SandboxCloneOptions) => PlatformSandbox`): Construct an unstarted sibling PlatformSandbox that inherits credentials and defaults with per-instance overrides (id, sandboxId, env, idleTimeoutMinutes). Performs no I/O. Use to build a fleet of independent sandboxes from one configured template.
+
+**getInfo** (`() => Promise<SandboxInfo>`): Return the sandbox's platform id, provider, status, createdAt, and metadata (sandboxId, providerResourceId, platformStatus).
+
+**getInstructions** (`(opts?: { requestContext?: RequestContext }) => string`): Return the sandbox instructions the workspace surfaces in tool descriptions. Honors the instructions constructor option; otherwise returns platform-default instructions that include the current remote sandbox id when running.
+
 ## Errors
 
 Platform API failures raise `PlatformApiError`. Structured `{ error: { message, type } }` responses are parsed into `.code` (machine-readable kind) and `.proxyMessage` (human string); the raw response body stays available on `.body`:
@@ -192,6 +246,28 @@ try {
 
 `code` and `proxyMessage` are `undefined` when the response body isn't JSON, for example an HTML 502 from a load balancer.
 
+`executeCommand` runs over the direct-exec data plane (a WebSocket to the Railway tcp-proxy) and can also throw two typed sandbox errors on unrecoverable failure:
+
+```typescript
+import { SandboxDestroyedError, SandboxExecTransportError } from '@mastra/platform-workspace'
+
+try {
+  await sandbox.executeCommand('pytest')
+} catch (err) {
+  if (err instanceof SandboxDestroyedError) {
+    // /exec-lease returned 410; the sandbox has been destroyed.
+    // The cached sandbox id and lease have already been cleared,
+    // so reusing the instance will reprovision on the next call.
+  } else if (err instanceof SandboxExecTransportError) {
+    // Both the initial WebSocket attempt and the built-in retry
+    // closed without an exit frame against a live sandbox.
+    console.error(err.closeCode, err.closeReason, err.wsEndpoint)
+  }
+}
+```
+
+`SandboxExecTransportError` carries diagnostic fields (`opened`, `closeCode`, `closeReason`, `wsEndpoint`, plus `sandboxId`, `command`, and `attempts`) so operators can distinguish a broken Railway data plane from a failed command.
+
 ## Related
 
 - [PlatformFilesystem reference](https://mastra.ai/reference/workspace/platform-filesystem)

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @mastra/mcp-docs-server
 
+## 1.2.13-alpha.10
+
+### Patch Changes
+
+- Updated dependencies [[`a19e5b7`](https://github.com/mastra-ai/mastra/commit/a19e5b79b76fffa92f9cf17e0e89c3fa714534e8), [`82201f7`](https://github.com/mastra-ai/mastra/commit/82201f75fae8e050a8de2df08b74875ee74c6b83), [`fb18da5`](https://github.com/mastra-ai/mastra/commit/fb18da56fc35689ae370621a8f10b5b0d8606e20), [`fb18da5`](https://github.com/mastra-ai/mastra/commit/fb18da56fc35689ae370621a8f10b5b0d8606e20), [`0a6598b`](https://github.com/mastra-ai/mastra/commit/0a6598bde80bde008986ad6616bed9632b9294cb), [`9e1dad8`](https://github.com/mastra-ai/mastra/commit/9e1dad8f7b1cab2bb7ade90e5b7561f24577b88a), [`2f43145`](https://github.com/mastra-ai/mastra/commit/2f4314504c03cbba280414ac81ba3197448ee6b0), [`34d34d8`](https://github.com/mastra-ai/mastra/commit/34d34d8c811df512fef4dd5459f79b7821be1866)]:
+  - @mastra/mcp@1.15.1-alpha.1
+  - @mastra/core@1.56.0-alpha.6
+
+## 1.2.13-alpha.9
+
+### Patch Changes
+
+- Updated dependencies [[`db4e6ff`](https://github.com/mastra-ai/mastra/commit/db4e6ff744503112eb64deeaf6c2b54bf26a54c7), [`6d19a65`](https://github.com/mastra-ai/mastra/commit/6d19a6517f5da3911023d446b7e2d5dad8adb1cb)]:
+  - @mastra/core@1.56.0-alpha.5
+
+## 1.2.13-alpha.7
+
+### Patch Changes
+
+- Updated dependencies [[`4844167`](https://github.com/mastra-ai/mastra/commit/4844167cff2d5ec5004e94edd34970833040fa3f), [`5faf93f`](https://github.com/mastra-ai/mastra/commit/5faf93f03e19daea394b9e2a923f2e4f833407f2), [`80ad891`](https://github.com/mastra-ai/mastra/commit/80ad891f8cd10379aa5b5af7510c763783b2ab56), [`c78aa4e`](https://github.com/mastra-ai/mastra/commit/c78aa4ecc422ba70476da73709c3e7d85edc71d6), [`a1cb98d`](https://github.com/mastra-ai/mastra/commit/a1cb98d11990b560b98482292a1f34aa1a2d9092), [`598ad82`](https://github.com/mastra-ai/mastra/commit/598ad82d41c41389a686338a1d0e50b7400e1938), [`1fd6aad`](https://github.com/mastra-ai/mastra/commit/1fd6aad1ea4a9d32f65efa832307c35e981a4c0a)]:
+  - @mastra/core@1.56.0-alpha.4
+  - @mastra/mcp@1.15.1-alpha.0
+
+## 1.2.13-alpha.5
+
+### Patch Changes
+
+- Updated dependencies [[`594f7b2`](https://github.com/mastra-ai/mastra/commit/594f7b28f5263fb9982fd50d95c471fb971ea984), [`311f943`](https://github.com/mastra-ai/mastra/commit/311f943bee60e8fdf5c84499ea50e884276c936c), [`0c89896`](https://github.com/mastra-ai/mastra/commit/0c8989673fb7d106837098398131e570c6023b68), [`23b4238`](https://github.com/mastra-ai/mastra/commit/23b423844ad0bcf2a502a68dd62866d6160f9f6d), [`e320a76`](https://github.com/mastra-ai/mastra/commit/e320a763feaf65c6be3cebecf746defcbde161b3), [`03b4918`](https://github.com/mastra-ai/mastra/commit/03b4918c80d188ce375334c393e131c6e94bd7eb), [`14ef73a`](https://github.com/mastra-ai/mastra/commit/14ef73a4bbd73e7808414816eb0628ce1d80b5d7), [`1d677d5`](https://github.com/mastra-ai/mastra/commit/1d677d5f99d7db403f7828585e8c25f299f72628), [`93e28ec`](https://github.com/mastra-ai/mastra/commit/93e28ecce9031c02397e0ae8406593e5c7a95883), [`729dab4`](https://github.com/mastra-ai/mastra/commit/729dab408faccfaef0cbb048e5a4338f9172847e), [`484003d`](https://github.com/mastra-ai/mastra/commit/484003d33ff59330c86b19863e4a38732d7e4155), [`933d291`](https://github.com/mastra-ai/mastra/commit/933d291146b789c19442ad206f94da3e4be90c64)]:
+  - @mastra/core@1.56.0-alpha.3
+
+## 1.2.13-alpha.4
+
+### Patch Changes
+
+- Updated dependencies [[`322daa6`](https://github.com/mastra-ai/mastra/commit/322daa6d90552909204044790d850958f6745fed), [`cadaa13`](https://github.com/mastra-ai/mastra/commit/cadaa1372e1077c8e85eb64c5499ba8803caa323), [`06000d7`](https://github.com/mastra-ai/mastra/commit/06000d73712911572e913b8a83339270296d0a22), [`3de0188`](https://github.com/mastra-ai/mastra/commit/3de0188bfaf9a9c09c95fe322b53838cf52c70b6)]:
+  - @mastra/core@1.56.0-alpha.2
+
+## 1.2.13-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [[`c5e56ff`](https://github.com/mastra-ai/mastra/commit/c5e56ff3bcabdf062708f2d48744fec304df6792), [`4e35a56`](https://github.com/mastra-ai/mastra/commit/4e35a56cdf8d74a5ff6d5eda01f2c1deaf6cc7be)]:
+  - @mastra/core@1.56.0-alpha.1
+
+## 1.2.13-alpha.1
+
+### Patch Changes
+
+- Updated dependencies [[`7f4e26d`](https://github.com/mastra-ai/mastra/commit/7f4e26dd57bd9b23c278ea21235ab823a3810a6c), [`b582f7f`](https://github.com/mastra-ai/mastra/commit/b582f7fa2f9c1f87d19efc63d344fbe5dda2608c), [`b582f7f`](https://github.com/mastra-ai/mastra/commit/b582f7fa2f9c1f87d19efc63d344fbe5dda2608c)]:
+  - @mastra/core@1.56.0-alpha.0
+
 ## 1.2.12
 
 ### Patch Changes