@mastra/mcp-docs-server 1.1.27 → 1.1.28-alpha.1

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

@@ -71,18 +71,40 @@ The six processor methods run at different points in the agent execution lifecyc
 ## Interface definition
 
 ```typescript
-interface Processor<TId extends string = string> {
+interface Processor<TId extends string = string, TTripwireMetadata = unknown> {
   readonly id: TId
   readonly name?: string
+  readonly description?: string
+  /** Index of this processor in the workflow (set at runtime when combining processors). */
+  processorIndex?: number
+  /** When true, processOutputStream also receives `data-*` chunks. Default: false. */
+  processDataParts?: boolean
+
+  processInput?(
+    args: ProcessInputArgs<TTripwireMetadata>,
+  ): Promise<ProcessInputResult> | ProcessInputResult
+
+  processInputStep?(
+    args: ProcessInputStepArgs<TTripwireMetadata>,
+  ):
+    | Promise<ProcessInputStepResult | MessageList | MastraDBMessage[] | undefined | void>
+    | ProcessInputStepResult
+    | MessageList
+    | MastraDBMessage[]
+    | void
+    | undefined
 
-  processInput?(args: ProcessInputArgs): Promise<ProcessInputResult> | ProcessInputResult
-  processInputStep?(args: ProcessInputStepArgs): ProcessorMessageResult
   processAPIError?(
-    args: ProcessAPIErrorArgs,
+    args: ProcessAPIErrorArgs<TTripwireMetadata>,
   ): Promise<ProcessAPIErrorResult | void> | ProcessAPIErrorResult | void
-  processOutputStream?(args: ProcessOutputStreamArgs): Promise<ChunkType | null | undefined>
-  processOutputStep?(args: ProcessOutputStepArgs): ProcessorMessageResult
-  processOutputResult?(args: ProcessOutputResultArgs): ProcessorMessageResult
+
+  processOutputStream?(
+    args: ProcessOutputStreamArgs<TTripwireMetadata>,
+  ): Promise<ChunkType | null | undefined>
+
+  processOutputStep?(args: ProcessOutputStepArgs<TTripwireMetadata>): ProcessorMessageResult
+
+  processOutputResult?(args: ProcessOutputResultArgs<TTripwireMetadata>): ProcessorMessageResult
 }
 ```
 
@@ -92,8 +114,71 @@ interface Processor<TId extends string = string> {
 
 **name** (`string`): Optional display name for the processor. Falls back to id if not provided.
 
+**description** (`string`): Optional human-readable description shown in tracing and Studio.
+
+**processorIndex** (`number`): Position of the processor in the combined processor list. Set at runtime by Mastra when processors are merged with memory, workspace, and per-call overrides. You do not set this yourself.
+
 **processDataParts** (`boolean`): When true, the processOutputStream method also receives \`data-\*\` chunks emitted by tools via writer.custom(). Defaults to false.
 
+## Message arguments
+
+Most processor methods receive both `messages` and `messageList`. They point to the same underlying conversation but expose it differently.
+
+### `messages` vs `messageList`
+
+- `messages`: A plain array of `MastraDBMessage` objects, scoped to the current stage. For `processInput` and `processInputStep` this excludes system messages. For `processOutputResult` and `processOutputStep` this includes the latest LLM response. The array is backed by `messageList`, so editing a message's `content.parts` in place is visible to downstream processors and to persistence.
+- `messageList`: The live `MessageList` instance backing the run. It exposes filtered views (input, response, remembered, all), multiple output formats (db, ui, core), and methods for mutating the conversation.
+
+Use `messages` when you only need to read, map over, or lightly edit fields on the current stage's messages. Use `messageList` when you need to:
+
+- Read messages from another stage, for example input messages while processing output.
+- Add, remove, or replace whole messages.
+- Convert to another format such as UI or core messages for a third-party API.
+
+`messages` is always derived from `messageList`, so mutating `messageList` is the canonical way to add, remove, or reorder messages. For in-place edits to a message's content (for example, rewriting `content.parts`), mutating `messages` directly is equivalent. If you return a new array from `messages`, Mastra reconciles it against `messageList` for the current stage.
+
+### Persistence
+
+When memory is enabled, only what ends up in `messageList` after all processors finish is persisted to storage. The two return styles are equivalent for persistence:
+
+- Mutating `messageList` directly (or returning the same `MessageList` instance) — recorded mutations are applied in place, so the saved conversation reflects your changes.
+- Returning a `MastraDBMessage[]` or `{ messages, systemMessages }` — Mastra reconciles the returned array against `messageList` for the current stage, removing missing messages and replacing system messages.
+
+Returning a different `MessageList` instance is an error; always mutate the one passed to your processor.
+
+### Reading text from a message
+
+`MastraDBMessage.content` is a structured object, not a string. The canonical way to read user or assistant text is `content.parts`:
+
+```typescript
+import type { MastraDBMessage } from '@mastra/core/memory'
+
+function getText(message: MastraDBMessage): string {
+  let text = ''
+
+  if (message.content.parts) {
+    for (const part of message.content.parts) {
+      if (part.type === 'text' && typeof part.text === 'string') {
+        text += part.text
+      }
+    }
+  }
+
+  // Fallback for legacy messages that only have the flattened `content` string
+  if (!text && typeof message.content.content === 'string') {
+    text = message.content.content
+  }
+
+  return text
+}
+```
+
+Key points:
+
+- `message.content.parts` is the primary source. A single message can contain multiple parts, including non-text parts such as tool calls, tool results, and file parts. Filter by `part.type === 'text'` before reading `part.text`.
+- `message.content.content` is a flattened string kept for backward compatibility. Use it only as a fallback when `parts` is empty or missing.
+- `message.content` itself is never a plain string on `MastraDBMessage`. Legacy `CoreMessage` shapes may be strings, but processors always receive `MastraDBMessage`.
+
 ## Methods
 
 ### `processInput`
@@ -114,7 +199,7 @@ processInput?(args: ProcessInputArgs): Promise<ProcessInputResult> | ProcessInpu
 
 **abort** (`(reason?: string, options?: { retry?: boolean; metadata?: unknown }) => never`): Function to abort processing. Throws a TripWire error that stops execution. Pass \`retry: true\` to request the LLM retry the step with feedback.
 
-**retryCount** (`number`): Number of times processors have triggered retry for this generation. Use this to limit retry attempts.
+**retryCount** (`number`): Number of times processors have triggered retry for this generation. Use this to limit retry attempts. Always passed by Mastra; starts at 0.
 
 **tracingContext** (`TracingContext`): Tracing context for observability.
 
@@ -137,7 +222,15 @@ The method can return one of three types:
 Processes input messages at each step of the agentic loop, before they're sent to the LLM. Unlike `processInput` which runs once at the start, this runs at every step including tool call continuations.
 
 ```typescript
-processInputStep?(args: ProcessInputStepArgs): ProcessorMessageResult;
+processInputStep?<TTripwireMetadata = unknown>(
+  args: ProcessInputStepArgs<TTripwireMetadata>,
+):
+  | Promise<ProcessInputStepResult | MessageList | MastraDBMessage[] | void | undefined>
+  | ProcessInputStepResult
+  | MessageList
+  | MastraDBMessage[]
+  | void
+  | undefined;
 ```
 
 #### Execution order in the agentic loop
@@ -175,7 +268,9 @@ processInputStep?(args: ProcessInputStepArgs): ProcessorMessageResult;
 
 **structuredOutput** (`StructuredOutputOptions`): Structured output configuration (schema, output mode). Return in result to modify.
 
-**abort** (`(reason?: string) => never`): Function to abort processing.
+**abort** (`(reason?: string, options?: { retry?: boolean; metadata?: unknown }) => never`): Function to abort processing. Throws a TripWire error that stops execution. Pass \`retry: true\` to request the LLM retry the step with feedback.
+
+**retryCount** (`number`): Current retry attempt count from \`ProcessorContext\`. Starts at \`0\`; use to cap processor-triggered retries.
 
 **tracingContext** (`TracingContext`): Tracing context for observability.
 
@@ -183,7 +278,14 @@ processInputStep?(args: ProcessInputStepArgs): ProcessorMessageResult;
 
 #### `ProcessInputStepResult`
 
-The method can return any combination of these properties:
+`processInputStep` can return several shapes:
+
+- **`ProcessInputStepResult` object** — override any combination of the properties below for this step (described next).
+- **`MessageList`** — return the same `messageList` instance to signal you mutated messages in place.
+- **`MastraDBMessage[]`** — return a transformed messages array; replaces the step's messages.
+- **`void` or `undefined`** — return nothing to leave the step unchanged.
+
+The object form can return any combination of these properties:
 
 **model** (`LanguageModelV2 | string`): Change the model for this step. Can be a model instance or router ID like 'openai/gpt-5.4'.
 
@@ -324,9 +426,11 @@ processOutputStream?(args: ProcessOutputStreamArgs): Promise<ChunkType | null |
 
 **streamParts** (`ChunkType[]`): All chunks seen so far in the stream.
 
-**state** (`Record<string, unknown>`): Mutable state object that persists across chunks within a single stream.
+**state** (`Record<string, unknown>`): Mutable per-processor state that persists across every chunk and every method call within a single request. A fresh state object is created for each new generate or stream call.
+
+**abort** (`(reason?: string, options?: { retry?: boolean; metadata?: unknown }) => never`): Function to abort the stream. Throws a TripWire error that ends the stream and emits a \`tripwire\` chunk. Pass \`retry: true\` to request another LLM attempt instead of ending.
 
-**abort** (`(reason?: string) => never`): Function to abort the stream.
+**retryCount** (`number`): Current retry attempt count from \`ProcessorContext\`. Starts at \`0\`; use to cap processor-triggered retries.
 
 **messageList** (`MessageList`): MessageList instance for accessing conversation history.
 
@@ -338,8 +442,13 @@ processOutputStream?(args: ProcessOutputStreamArgs): Promise<ChunkType | null |
 
 #### Return value
 
-- Return the `ChunkType` to emit it (possibly modified)
-- Return `null` or `undefined` to skip emitting the chunk
+`processOutputStream` returns `Promise<ChunkType | null | undefined>`.
+
+- Return the `ChunkType` to emit the chunk. Return the original `part` to emit it unchanged, or a new `ChunkType` to emit a modified chunk.
+- Return `null` to drop the chunk. Nothing is sent to the next processor or the client.
+- Return `undefined` (including implicit `undefined` from a `return;` statement or a method that falls off the end) to drop the chunk. `null` and `undefined` behave the same way.
+
+Dropping a chunk only affects that single chunk. The stream continues and the next chunk is still processed. To stop the stream entirely, call `abort()`.
 
 ***
 
@@ -361,7 +470,9 @@ processOutputResult?(args: ProcessOutputResultArgs): ProcessorMessageResult;
 
 **result** (`OutputResult`): Resolved generation result containing \`text\` (accumulated text), \`usage\` (token usage with inputTokens, outputTokens, totalTokens), \`finishReason\` (why generation ended), and \`steps\` (all LLM step results, each with toolCalls, toolResults, reasoning, sources, files, etc.).
 
-**abort** (`(reason?: string) => never`): Function to abort processing.
+**abort** (`(reason?: string, options?: { retry?: boolean; metadata?: unknown }) => never`): Function to abort processing. Throws a TripWire error that stops execution and emits a \`tripwire\` chunk.
+
+**retryCount** (`number`): Current retry attempt count from \`ProcessorContext\`. Starts at \`0\`; use to cap processor-triggered retries.
 
 **tracingContext** (`TracingContext`): Tracing context for observability.
 
@@ -393,11 +504,17 @@ processOutputStep?(args: ProcessOutputStepArgs): ProcessorMessageResult;
 
 **text** (`string`): Generated text from this step.
 
+**usage** (`LanguageModelUsage`): Token usage for the current step (\`inputTokens\`, \`outputTokens\`, \`totalTokens\`).
+
 **systemMessages** (`CoreMessage[]`): All system messages for read/modify access.
 
+**steps** (`StepResult[]`): All completed steps so far, including the current step.
+
+**state** (`Record<string, unknown>`): Per-processor state that persists across all method calls within this request. Shared with processOutputStream and processOutputResult.
+
 **abort** (`(reason?: string, options?: { retry?: boolean; metadata?: unknown }) => never`): Function to abort processing. Pass \`retry: true\` to request the LLM retry the step.
 
-**retryCount** (`number`): Number of times processors have triggered retry. Use this to limit retry attempts.
+**retryCount** (`number`): Number of times processors have triggered retry. Use this to limit retry attempts. Always passed by Mastra; starts at 0.
 
 **tracingContext** (`TracingContext`): Tracing context for observability.
 
@@ -413,7 +530,7 @@ processOutputStep?(args: ProcessOutputStepArgs): ProcessorMessageResult;
 #### Example: Quality guardrail with retry
 
 ```typescript
-import type { Processor } from '@mastra/core'
+import type { Processor } from '@mastra/core/processors'
 
 export class QualityGuardrail implements Processor {
   id = 'quality-guardrail'
@@ -473,7 +590,8 @@ const agent = new Agent({
 ### Basic input processor
 
 ```typescript
-import type { Processor, MastraDBMessage } from '@mastra/core'
+import type { Processor } from '@mastra/core/processors'
+import type { MastraDBMessage } from '@mastra/core/memory'
 
 export class LowercaseProcessor implements Processor {
   id = 'lowercase'
@@ -495,7 +613,11 @@ export class LowercaseProcessor implements Processor {
 ### Per-step processor with `processInputStep`
 
 ```typescript
-import type { Processor, ProcessInputStepArgs, ProcessInputStepResult } from '@mastra/core'
+import type {
+  Processor,
+  ProcessInputStepArgs,
+  ProcessInputStepResult,
+} from '@mastra/core/processors'
 
 export class DynamicModelProcessor implements Processor {
   id = 'dynamic-model'
@@ -528,7 +650,8 @@ export class DynamicModelProcessor implements Processor {
 ### Message transformer with `processInputStep`
 
 ```typescript
-import type { Processor, MastraDBMessage } from '@mastra/core'
+import type { Processor } from '@mastra/core/processors'
+import type { MastraDBMessage } from '@mastra/core/memory'
 
 export class ReasoningTransformer implements Processor {
   id = 'reasoning-transformer'
@@ -553,7 +676,9 @@ export class ReasoningTransformer implements Processor {
 ### Hybrid processor (input and output)
 
 ```typescript
-import type { Processor, MastraDBMessage, ChunkType } from '@mastra/core'
+import type { Processor } from '@mastra/core/processors'
+import type { MastraDBMessage } from '@mastra/core/memory'
+import type { ChunkType } from '@mastra/core/stream'
 
 export class ContentFilter implements Processor {
   id = 'content-filter'
@@ -579,7 +704,7 @@ export class ContentFilter implements Processor {
 
   async processOutputStream({ part, abort }): Promise<ChunkType | null> {
     if (part.type === 'text-delta') {
-      if (this.blockedWords.some(word => part.textDelta.includes(word))) {
+      if (this.blockedWords.some(word => part.payload.text.includes(word))) {
         abort('Blocked content detected in output')
       }
     }
@@ -591,7 +716,8 @@ export class ContentFilter implements Processor {
 ### Stream accumulator with state
 
 ```typescript
-import type { Processor, ChunkType } from '@mastra/core'
+import type { Processor } from '@mastra/core/processors'
+import type { ChunkType } from '@mastra/core/stream'
 
 export class WordCounter implements Processor {
   id = 'word-counter'
@@ -604,7 +730,7 @@ export class WordCounter implements Processor {
 
     // Count words in text chunks
     if (part.type === 'text-delta') {
-      const words = part.textDelta.split(/\s+/).filter(Boolean)
+      const words = part.payload.text.split(/\s+/).filter(Boolean)
       state.wordCount += words.length
     }
 
@@ -618,6 +744,142 @@ export class WordCounter implements Processor {
 }
 ```
 
+## State lifecycle
+
+Every processor receives a `state` object in `processOutputStream`, `processOutputStep`, `processOutputResult`, and `processAPIError`. State has three important properties:
+
+- **Per-processor**: Each processor gets its own `state` object, keyed by the processor's `id`. Two processors with different ids cannot read or overwrite each other's state.
+- **Per-request**: A fresh state object is created at the start of every `agent.generate()` or `agent.stream()` call. State does not leak between requests or between users.
+- **Shared across methods**: Within one request, the same `state` object is passed to `processOutputStream` (for every chunk), `processOutputStep` (after every LLM step), `processOutputResult` (once at the end), and `processAPIError` (when an LLM call fails). Accumulate data in `processOutputStream` and read it in `processOutputResult` or `processAPIError`.
+
+Initialize fields defensively on first access, because `state` starts as an empty object:
+
+```typescript
+import type { Processor } from '@mastra/core/processors'
+
+export class WordCounter implements Processor {
+  id = 'word-counter'
+
+  async processOutputStream({ part, state }) {
+    state.wordCount ??= 0
+    if (part.type === 'text-delta') {
+      state.wordCount += part.payload.text.split(/\s+/).filter(Boolean).length
+    }
+    return part
+  }
+}
+```
+
+## Aborting and tripwire chunks
+
+The `abort` function on each method throws a `TripWire` error that stops processing and emits a `tripwire` chunk on the output stream. Clients can detect the chunk to distinguish a blocked response from a normal finish.
+
+```typescript
+abort('Blocked content detected', { retry: false, metadata: { category: 'pii' } })
+```
+
+- `reason`: A human-readable explanation. Appears as `tripwire.payload.reason`.
+- `retry`: When `true`, the agent retries the same step with `reason` fed back as feedback. Retries only run when `maxProcessorRetries` is set on the agent or call; otherwise the request aborts. When `errorProcessors` are configured, `maxProcessorRetries` defaults to `10` for that call.
+- `metadata`: Optional structured data attached to the `tripwire` chunk for downstream consumers.
+
+The emitted `tripwire` chunk has the shape:
+
+```typescript
+type TripwireChunk = {
+  type: 'tripwire'
+  runId: string
+  from: 'AGENT'
+  payload: {
+    reason: string
+    retry?: boolean
+    metadata?: unknown
+    processorId: string
+  }
+}
+```
+
+In non-streaming calls (`agent.generate()`), the result exposes the same information as `result.tripwire` and `result.finishReason === 'other'`.
+
+## Emitting custom data chunks
+
+Processors with access to `writer` can stream custom `data-*` chunks to the client by calling `writer.custom(chunk)`. Tools can do the same through their own writer. This is the only way for a processor to emit content outside of normal text and tool chunks.
+
+```typescript
+await writer.custom({
+  type: 'data-moderation',
+  runId,
+  from: 'AGENT',
+  data: { level: 'warn', reason: 'Possibly unsafe' },
+})
+```
+
+By default, processors do **not** see `data-*` chunks in `processOutputStream` so they don't accidentally process tool telemetry or their own output. Opt in by setting `processDataParts: true` on the processor:
+
+```typescript
+class ModerationCollector implements Processor {
+  id = 'moderation-collector'
+  processDataParts = true
+
+  async processOutputStream({ part, state }) {
+    if (part.type === 'data-moderation') {
+      state.warnings ??= []
+      state.warnings.push(part.data)
+    }
+    return part
+  }
+}
+```
+
+The chunk `type` must start with `data-` to be treated as a custom data chunk. Returning `null` or `undefined` from `processOutputStream` still drops the chunk, so a processor can inspect, modify, or filter custom data the same way it filters text chunks.
+
+## Configuring processors on an agent
+
+Processors are attached to an agent through three arrays:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { PrefillErrorHandler } from '@mastra/core/processors'
+
+const agent = new Agent({
+  name: 'support-agent',
+  model: 'openai/gpt-5',
+  instructions: '...',
+  inputProcessors: [new ContentFilter(['secret'])],
+  outputProcessors: [new WordCounter()],
+  errorProcessors: [new PrefillErrorHandler()],
+  maxProcessorRetries: 3,
+})
+```
+
+- `inputProcessors`: Run before the LLM. Receives input messages.
+- `outputProcessors`: Run during or after the LLM response. Receives output chunks or messages.
+- `errorProcessors`: Run when the LLM API call throws. Receives the raw error.
+
+Each array also accepts a function so processors can be built per-request from `RequestContext`:
+
+```typescript
+new Agent({
+  // ...
+  inputProcessors: ({ requestContext }) => {
+    const blockedWords = requestContext.get('blockedWords') ?? []
+    return [new ContentFilter(blockedWords)]
+  },
+})
+```
+
+### Per-call overrides
+
+`agent.generate()` and `agent.stream()` accept `inputProcessors`, `outputProcessors`, `errorProcessors`, and `maxProcessorRetries`. When any processor array is set on the call, it **replaces** the matching array configured on the agent for that request. Memory, workspace, skill, channel, and browser processors that Mastra adds automatically are always preserved and run around your array.
+
+```typescript
+await agent.stream('Summarize this', {
+  outputProcessors: [new StreamFilter()],
+  maxProcessorRetries: 5,
+})
+```
+
+`maxProcessorRetries` passed on the call overrides the agent default. If neither is set, processor-requested retries are treated as aborts.
+
 ## Related
 
 - [Processors overview](https://mastra.ai/docs/agents/processors): Conceptual guide to processors

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

@@ -120,7 +120,7 @@ const stream = await agent.stream('message for agent')
 
 **options.memory.resource** (`string`): Identifier for the user or resource associated with the thread.
 
-**options.memory.options** (`MemoryConfig`): Configuration for memory behavior including lastMessages, readOnly, semanticRecall, and workingMemory.
+**options.memory.options** (`MemoryConfig`): Configuration for memory behavior including lastMessages, readOnly, semanticRecall, workingMemory, and filterIncompleteToolCalls.
 
 **options.onFinish** (`StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>`): Callback function called when streaming completes. Receives the final result.
 

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

@@ -0,0 +1,168 @@
+# ModalSandbox
+
+Executes commands in isolated [Modal](https://modal.com) cloud sandboxes. Provides secure, ephemeral environments backed by Modal's infrastructure.
+
+> **Info:** For interface details, see [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox).
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/modal
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/modal
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/modal
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/modal
+```
+
+## Usage
+
+Add a `ModalSandbox` to a workspace and assign it to an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Workspace } from '@mastra/core/workspace'
+import { ModalSandbox } from '@mastra/modal'
+
+const workspace = new Workspace({
+  sandbox: new ModalSandbox({
+    id: 'dev-sandbox',
+    baseImage: 'ubuntu:22.04',
+    timeoutMs: 60_000,
+  }),
+})
+
+const agent = new Agent({
+  id: 'dev-agent',
+  model: 'anthropic/claude-opus-4-6',
+  workspace,
+})
+```
+
+## Authentication
+
+Set Modal credentials via environment variables or constructor options:
+
+```bash
+MODAL_TOKEN_ID=ak-...
+MODAL_TOKEN_SECRET=as-...
+```
+
+Or pass them directly:
+
+```typescript
+const sandbox = new ModalSandbox({
+  tokenId: process.env.MODAL_TOKEN_ID,
+  tokenSecret: process.env.MODAL_TOKEN_SECRET,
+})
+```
+
+Get your credentials from the [Modal dashboard](https://modal.com/settings/tokens).
+
+## Constructor parameters
+
+**id** (`string`): Unique identifier / name for this sandbox. Used as the Modal sandbox name so the sandbox can be reconnected on subsequent start() calls. (Default: `Auto-generated`)
+
+**appName** (`string`): Modal App name to associate sandboxes with. (Default: `'mastra'`)
+
+**baseImage** (`string`): Docker image to use for the sandbox. (Default: `'ubuntu:22.04'`)
+
+**timeoutMs** (`number`): Wall-clock max lifetime in milliseconds. The sandbox is terminated when this expires, regardless of activity. Modal's maximum is 24 hours (86\_400\_000). (Default: `300000 (5 minutes)`)
+
+**env** (`Record<string, string>`): Environment variables baked into the sandbox at create time.
+
+**workdir** (`string`): Default working directory inside the sandbox.
+
+**tokenId** (`string`): Modal token ID. Falls back to MODAL\_TOKEN\_ID environment variable.
+
+**tokenSecret** (`string`): Modal token secret. Falls back to MODAL\_TOKEN\_SECRET environment variable.
+
+**instructions** (`string | function`): Custom instructions returned by getInstructions(). Pass a string to fully replace the default, or a function to extend it.
+
+**onStart** (`function`): Lifecycle hook called after the sandbox reaches running status.
+
+**onStop** (`function`): Lifecycle hook called before the sandbox stops.
+
+**onDestroy** (`function`): Lifecycle hook called before the sandbox is destroyed.
+
+## Properties
+
+**id** (`string`): Sandbox instance identifier.
+
+**name** (`string`): Provider name ('ModalSandbox')
+
+**provider** (`string`): Provider identifier ('modal')
+
+**status** (`ProviderStatus`): 'pending' | 'starting' | 'running' | 'stopping' | 'stopped' | 'destroying' | 'destroyed' | 'error'
+
+**modal** (`Sandbox`): The underlying Modal Sandbox instance. Throws SandboxNotReadyError if the sandbox has not been started.
+
+**processes** (`ModalProcessManager`): Background process manager. See \[SandboxProcessManager reference]\(/reference/workspace/process-manager).
+
+## Sandbox lifecycle
+
+- **`_start()`**: Attempts to reconnect to an existing running sandbox. If none is found, creates a sandbox from the latest snapshot (if available from a previous `_stop()`), or from the baseImage.
+- **`_stop()`**: Snapshots the filesystem, then terminates the sandbox. Snapshot is kept in memory on the same instance for future starts.
+- **`_destroy()`**: Terminates the sandbox and discards any snapshot.
+
+```typescript
+const sandbox = new ModalSandbox({
+  id: 'dev-sandbox',
+  baseImage: 'ubuntu:22.04',
+  timeoutMs: 300_000,
+})
+
+await sandbox._start()
+await sandbox.processes.spawn('npm install')
+await sandbox._stop()
+await sandbox._start()
+```
+
+## Background processes
+
+`ModalSandbox` includes a built-in process manager for spawning and managing background processes. Each `spawn()` call creates a new `ContainerProcess` via the Modal SDK's `Sandbox.exec()` API.
+
+```typescript
+const sandbox = new ModalSandbox({ id: 'dev-sandbox' })
+await sandbox._start()
+
+// Spawn a background process
+const handle = await sandbox.processes.spawn('node script.js', {
+  env: { PORT: '3000' },
+  onStdout: data => console.log(data),
+})
+
+// Wait for the process to complete
+const result = await handle.wait()
+console.log(result.exitCode)
+
+// Kill the process
+await handle.kill()
+```
+
+> **Note:** `sendStdin()` is not supported — the Modal JS SDK does not expose stdin on `Sandbox.exec()`.
+
+See [`SandboxProcessManager` reference](https://mastra.ai/reference/workspace/process-manager) for the full API.
+
+## Related
+
+- [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)
+- [WorkspaceSandbox interface](https://mastra.ai/reference/workspace/sandbox)
+- [E2BSandbox reference](https://mastra.ai/reference/workspace/e2b-sandbox)
+- [DaytonaSandbox reference](https://mastra.ai/reference/workspace/daytona-sandbox)
+- [Workspace overview](https://mastra.ai/docs/workspace/overview)

package/.docs/reference/workspace/process-manager.md

@@ -4,7 +4,7 @@
 
 Abstract base class for managing background processes in sandboxes. Provides methods to spawn processes, list them, get handles by PID, and kill them.
 
-[`BlaxelSandbox`](https://mastra.ai/reference/workspace/blaxel-sandbox), [`DaytonaSandbox`](https://mastra.ai/reference/workspace/daytona-sandbox), [`E2BSandbox`](https://mastra.ai/reference/workspace/e2b-sandbox), and [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) all include built-in process managers. You don't need to instantiate this class directly unless you're building a custom sandbox provider.
+[`BlaxelSandbox`](https://mastra.ai/reference/workspace/blaxel-sandbox), [`DaytonaSandbox`](https://mastra.ai/reference/workspace/daytona-sandbox), [`E2BSandbox`](https://mastra.ai/reference/workspace/e2b-sandbox), [`ModalSandbox`](https://mastra.ai/reference/workspace/modal-sandbox), and [`LocalSandbox`](https://mastra.ai/reference/workspace/local-sandbox) all include built-in process managers. You don't need to instantiate this class directly unless you're building a custom sandbox provider.
 
 ## Usage example
 

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @mastra/mcp-docs-server
 
+## 1.1.28-alpha.1
+
+### Patch Changes
+
+- Updated dependencies [[`733bf53`](https://github.com/mastra-ai/mastra/commit/733bf53d9352aedd3ef38c3d501edb275b65b43c), [`5405b3b`](https://github.com/mastra-ai/mastra/commit/5405b3b35325c5b8fb34fc7ac109bd2feb7bb6fe), [`c321127`](https://github.com/mastra-ai/mastra/commit/c3211275fc195de9ad1ead2746b354beb8eae6e8), [`a07bcef`](https://github.com/mastra-ai/mastra/commit/a07bcefea77c03d6d322caad973dca49b4b15fa1), [`b084a80`](https://github.com/mastra-ai/mastra/commit/b084a800db0f82d62e1fc3d6e3e3480da1ba5a53), [`82b7a96`](https://github.com/mastra-ai/mastra/commit/82b7a964169636c1d1e0c694fc892a213b0179d5), [`df97812`](https://github.com/mastra-ai/mastra/commit/df97812bd949dcafeb074b80ecab501724b49c3b), [`8bbe360`](https://github.com/mastra-ai/mastra/commit/8bbe36042af7fc4be0244dffd8913f6795179421), [`f6b8ba8`](https://github.com/mastra-ai/mastra/commit/f6b8ba8dbf533b7a8db90c72b6805ddc804a3a72), [`a07bcef`](https://github.com/mastra-ai/mastra/commit/a07bcefea77c03d6d322caad973dca49b4b15fa1)]:
+  - @mastra/core@1.28.0-alpha.0
+
 ## 1.1.27
 
 ### Patch Changes