@mastra/mcp-docs-server 1.2.17-alpha.13 → 1.2.17-alpha.16

package/.docs/reference/file-based-agents/workspace.md

@@ -4,9 +4,9 @@
 
 > **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
-A [workspace](https://mastra.ai/docs/workspace/sandbox) assembles capabilities such as filesystem access and command execution. The configured backends determine which tools are available. File-based agents get a default workspace automatically when discovered through `mastra dev` or `mastra build`. This default includes filesystem access and command execution, so agents can read and write files and run shell commands without extra configuration.
+A [workspace](https://mastra.ai/docs/sandbox/overview) assembles capabilities such as filesystem access and command execution. The configured backends determine which tools are available. File-based agents get a default workspace automatically when discovered through `mastra dev` or `mastra build`. This default includes filesystem access and command execution, so agents can read and write files and run shell commands without extra configuration.
 
-Use this page for the file-based convention. For workspace providers, tools, search, lifecycle, and sandbox details, see [Sandbox](https://mastra.ai/docs/workspace/sandbox).
+Use this page for the file-based convention. For workspace providers, tools, search, lifecycle, and sandbox details, see [Sandbox](https://mastra.ai/docs/sandbox/overview).
 
 ## Default workspace
 
@@ -65,7 +65,7 @@ Customize the workspace when the default local directory isn't enough. Common re
 - Add workspace search with BM25 or vector search.
 - Share one workspace across multiple agents.
 
-For provider patterns and runtime behavior, see the [sandbox guide](https://mastra.ai/docs/workspace/sandbox) and [workspace search](https://mastra.ai/docs/workspace/search).
+For provider patterns and runtime behavior, see the [sandbox guide](https://mastra.ai/docs/sandbox/overview) and [workspace search](https://mastra.ai/docs/sandbox/search).
 
 ## Runtime boundary
 

package/.docs/reference/index.md

@@ -211,6 +211,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.getThreadById()](https://mastra.ai/reference/memory/getThreadById)
 - [.listThreads()](https://mastra.ai/reference/memory/listThreads)
 - [.recall()](https://mastra.ai/reference/memory/recall)
+- [.settled()](https://mastra.ai/reference/memory/settled)
 - [.summarizeThread()](https://mastra.ai/reference/memory/summarizeThread)
 - [AgentNetwork to .network()](https://mastra.ai/reference/migrations/agentnetwork)
 - [AI SDK v4 to v5](https://mastra.ai/reference/migrations/ai-sdk-v4-to-v5)

package/.docs/reference/manual-install.md

@@ -157,7 +157,7 @@ If you prefer not to use our automatic CLI tool, you can set up your project you
    })
    ```
 
-   > **Note:** We've shortened and simplified the `weatherTool` example here. You can see the complete weather tool under [Giving an Agent a Tool](https://mastra.ai/docs/agents/using-tools).
+   > **Note:** We've shortened and simplified the `weatherTool` example here. You can see the complete weather tool under [Giving an Agent a Tool](https://mastra.ai/docs/agents/tools).
 
 5. Create a `weather-agent.ts` file:
 
@@ -244,7 +244,7 @@ If you prefer not to use our automatic CLI tool, you can set up your project you
 
 - [Review the project structure](https://mastra.ai/reference/project-structure): Understand how `src/mastra/` files map to agents, tools, workflows, storage, and configuration.
 - [Test your agent in Studio](https://mastra.ai/docs/studio/overview): Open the local Studio UI and run the weather agent.
-- [Use tools with agents](https://mastra.ai/docs/agents/using-tools): Replace the example weather tool with a real tool that calls an API or service.
+- [Use tools with agents](https://mastra.ai/docs/agents/tools): Replace the example weather tool with a real tool that calls an API or service.
 - [Add memory](https://mastra.ai/docs/memory/overview): Persist conversation history and user-specific context.
-- [Configure storage](https://mastra.ai/docs/storage/overview): Add a persistent storage adapter for memory, workflows, observability, and other runtime state.
+- [Configure storage](https://mastra.ai/docs/storage): Add a persistent storage adapter for memory, workflows, observability, and other runtime state.
 - [Build and deploy](https://mastra.ai/docs/deployment/overview): Build the Mastra server and deploy it to a hosting platform.

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

@@ -145,4 +145,5 @@ export const agent = new Agent({
 - [listThreads](https://mastra.ai/reference/memory/listThreads)
 - [deleteMessages](https://mastra.ai/reference/memory/deleteMessages)
 - [cloneThread](https://mastra.ai/reference/memory/cloneThread)
+- [settled](https://mastra.ai/reference/memory/settled)
 - [Clone Utility Methods](https://mastra.ai/reference/memory/clone-utilities)

package/.docs/reference/memory/settled.md

@@ -0,0 +1,57 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Memory.settled()
+
+The `.settled()` method resolves once all background work the `Memory` instance started has finished. Some memory work continues after an agent run returns:
+
+- Observational memory cycles (buffered observation and reflection, including the nested agent runs they spawn)
+- Vector cleanup started by `deleteThread()` and `deleteMessages()`
+
+Await this method before closing a storage connection you own. Without it, background statements can run against a closed connection.
+
+The method is declared on the base memory class, so it's also available on the `MastraMemory` instance returned by `agent.getMemory()`.
+
+## Usage example
+
+```typescript
+await agent.generate('Hello', {
+  memory: { thread: 'thread-123', resource: 'user-456' },
+})
+
+await memory.settled()
+await store.close()
+```
+
+## Parameters
+
+This method takes no parameters.
+
+## Returns
+
+**void** (`Promise<void>`): A promise that resolves when all background memory work has finished. Background work that fails does not reject this promise.
+
+## Extended usage example
+
+Test suites and short-lived processes are the most common places to need this, since they close the store immediately after a run finishes.
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { PostgresStore } from '@mastra/pg'
+
+const store = new PostgresStore({ connectionString })
+const memory = new Memory({ storage: store })
+
+// ... run your agent ...
+
+// Wait for observational memory and vector cleanup to finish before closing.
+await memory.settled()
+await store.close()
+```
+
+> **Note:** `settled()` joins the work that had started by the time you called it, plus any work that work enqueues. It does not prevent new work from starting afterwards, so call it once the agent runs you care about have returned.
+
+## Related
+
+- [Memory Class Reference](https://mastra.ai/reference/memory/memory-class)
+- [Observational Memory](https://mastra.ai/docs/memory/observational-memory)
+- [deleteMessages](https://mastra.ai/reference/memory/deleteMessages)

package/.docs/reference/migrations/network-to-supervisor.md

@@ -255,9 +255,9 @@ const stream = await supervisorAgent.stream('Research AI in education', {
 
 ## See also
 
-- [Supervisor Agents](https://mastra.ai/docs/capabilities/subagents)
+- [Supervisor Agents](https://mastra.ai/docs/subagents)
 - [Agent Networks](https://mastra.ai/docs/agents/networks)
 - [Agent.stream() Reference](https://mastra.ai/reference/streaming/agents/stream)
 - [Agent.generate() Reference](https://mastra.ai/reference/agents/generate)
-- [Agent Approval](https://mastra.ai/docs/agents/agent-approval)
+- [Agent Approval](https://mastra.ai/docs/agents/human-in-the-loop)
 - [Guide: Research Coordinator](https://mastra.ai/blog/build-a-research-coordinator-with-supervisor-agents)

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

@@ -112,4 +112,4 @@ Reserve workspace file tools such as `mastra_workspace_read_file` for explicit f
 
 - [ToolSearchProcessor](https://mastra.ai/reference/processors/tool-search-processor)
 - [Processors](https://mastra.ai/docs/agents/processors)
-- [Workspace Skills](https://mastra.ai/docs/workspace/skills)
+- [Workspace Skills](https://mastra.ai/docs/sandbox/skills)

package/.docs/reference/processors/tool-call-filter.md

@@ -2,7 +2,9 @@
 
 # ToolCallFilter
 
-The `ToolCallFilter` is an **input processor** that filters out tool calls and their results from the message history before sending to the model. This is useful when you want to exclude specific tool interactions from context or remove all tool calls entirely.
+The `ToolCallFilter` is an **input processor** that filters out tool calls and their results from the prompt sent to the model. This is useful when you want to exclude specific tool interactions from context or remove all tool calls entirely.
+
+Filtering happens in the `processLLMRequest` hook, which runs after the message list is converted to a model prompt. Changes are transient: they affect only what's sent to the model on that call. Stored messages, memory, and UI history keep their original tool calls and results.
 
 ## Usage example
 
@@ -44,13 +46,11 @@ const filterWithCompactToolHistory = new ToolCallFilter({
 
 **name** (`string`): Processor display name set to 'ToolCallFilter'
 
-**processInput** (`(args: { messages: MastraDBMessage[]; messageList: MessageList; abort: (reason?: string) => never; requestContext?: RequestContext }) => Promise<MessageList | MastraDBMessage[]>`): Processes input messages to filter out tool calls and their results based on configuration
-
-**processInputStep** (`(args: ProcessInputStepArgs) => Promise<ProcessInputStepResult>`): Processes agent loop step input when filterAfterToolSteps is configured. Returns no changes when step filtering is disabled
+**processLLMRequest** (`(args: ProcessLLMRequestArgs) => Promise<ProcessLLMRequestResult | undefined>`): Filters tool calls and results out of the model prompt before it is sent to the provider. Returns undefined when nothing is filtered. Changes are transient and are not persisted to the message list or memory
 
 ## Step filtering
 
-By default, `ToolCallFilter` filters only the initial input before the agent loop starts. Set `filterAfterToolSteps` to also filter during each loop step.
+By default, `ToolCallFilter` filters tool calls from history but leaves tool calls made during the current agent loop in place. Set `filterAfterToolSteps` to also filter tool calls produced by the current loop.
 
 `filterAfterToolSteps` counts tool-producing steps. For example, `filterAfterToolSteps: 2` keeps tool calls and results from the two most recent tool-producing steps and filters older tool calls and results. Non-tool text remains in context.
 
@@ -64,9 +64,9 @@ const filter = new ToolCallFilter({
 
 ## Preserve compact model output
 
-Set `preserveModelOutput: true` to retain compact `toModelOutput` history for completed tool results that the filter removes. This keeps the model-facing output as text in the prompt while removing the raw `toolInvocation.args` and raw `toolInvocation.result` payloads.
+Set `preserveModelOutput: true` to retain compact `toModelOutput` history for tool results that the filter removes. The removed tool call and result are replaced with a single text part in the prompt, so the model still sees the output while the raw tool arguments are dropped.
 
-Only completed tool results with `providerMetadata.mastra.modelOutput` are preserved. Tool calls, incomplete results, and results without stored model output are still filtered.
+Tool results without model output that can be represented as text are removed entirely.
 
 ```typescript
 const filter = new ToolCallFilter({

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

@@ -277,4 +277,4 @@ const agent = new Agent({
 ## Related
 
 - [Processors](https://mastra.ai/docs/agents/processors)
-- [Using Tools](https://mastra.ai/docs/agents/using-tools)
+- [Using Tools](https://mastra.ai/docs/agents/tools)

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/develop) 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/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/pubsub/lease-provider.md

@@ -2,7 +2,7 @@
 
 # LeaseProvider
 
-`LeaseProvider` is the distributed leasing contract, separate from event delivery ([`PubSub`](https://mastra.ai/reference/pubsub/base)). Mastra's [signals layer](https://mastra.ai/docs/long-running-agents/signals) uses it to elect a single owner across multiple processes (for example, serverless invocations) for a resource, most commonly a thread key. The owner is the process that wakes and runs the agent stream, so other processes route follow-up work to it instead of starting a competing run.
+`LeaseProvider` is the distributed leasing contract, separate from event delivery ([`PubSub`](https://mastra.ai/reference/pubsub/base)). Mastra's [signals layer](https://mastra.ai/docs/harness/signals) uses it to elect a single owner across multiple processes (for example, serverless invocations) for a resource, most commonly a thread key. The owner is the process that wakes and runs the agent stream, so other processes route follow-up work to it instead of starting a competing run.
 
 Leasing is a distinct concern from pub/sub. A backend implements `LeaseProvider` only when it can actually coordinate a lock, such as Redis via atomic `SET`/Lua, or an in-memory map for single-process. Backends that can't lease omit it; the signals runtime feature-detects the capability and falls back to a no-op provider, preserving single-process behavior.
 
@@ -129,5 +129,5 @@ 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): Uses leasing to coordinate agent runs in serverless and multi-instance deployments
+- [Signals](https://mastra.ai/docs/harness/signals): The runtime that uses leasing to coordinate thread execution across processes
+- [Channels](https://mastra.ai/docs/channels): Uses leasing to coordinate agent runs in serverless and multi-instance deployments

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

@@ -131,7 +131,7 @@ When a subscriber calls `nack`, the event is republished with an incremented `de
 
 ## Distributed leasing
 
-`RedisStreamsPubSub` implements the [`LeaseProvider`](https://mastra.ai/reference/pubsub/lease-provider) contract on top of the same Redis connection. The [signals runtime](https://mastra.ai/docs/long-running-agents/signals) uses it to elect a single owner (usually per thread key) so that across instances only one process wakes and runs the agent, and others route follow-up work to the holder. This is what makes signals work on serverless and multi-instance deployments; without a shared lease, each instance would start its own competing run.
+`RedisStreamsPubSub` implements the [`LeaseProvider`](https://mastra.ai/reference/pubsub/lease-provider) contract on top of the same Redis connection. The [signals runtime](https://mastra.ai/docs/harness/signals) uses it to elect a single owner (usually per thread key) so that across instances only one process wakes and runs the agent, and others route follow-up work to the holder. This is what makes signals work on serverless and multi-instance deployments; without a shared lease, each instance would start its own competing run.
 
 Lease keys are namespaced under the same `keyPrefix` as topics, as `<keyPrefix>:lease:<key>`. All operations are atomic: `acquireLease` uses `SET NX PX` and refreshes its own TTL idempotently, while `releaseLease`, `renewLease`, and `transferLease` use Lua scripts that check ownership before mutating, so a concurrent renewal from another owner is never clobbered.
 

package/.docs/reference/rag/graph-rag.md

@@ -9,10 +9,7 @@ The `GraphRAG` class implements a graph-based approach to retrieval augmented ge
 ```typescript
 import { GraphRAG } from '@mastra/rag'
 
-const graphRag = new GraphRAG({
-  dimension: 1536,
-  threshold: 0.7,
-})
+const graphRag = new GraphRAG(1536, 0.7)
 
 // Create the graph from chunks and embeddings
 graphRag.createGraph(documentChunks, embeddings)
@@ -88,13 +85,79 @@ Returns an array of `RankedNode` objects, where each node contains:
 
 **score** (`number`): Combined relevance score from graph traversal
 
+### `serialize`
+
+Returns a JSON-safe snapshot of the graph so it can be persisted and restored later instead of rebuilt with `createGraph`.
+
+```typescript
+serialize(): GraphRAGSnapshot
+```
+
+#### Returns
+
+Returns a `GraphRAGSnapshot` object containing:
+
+**version** (`number`): Snapshot format version, used to reject snapshots this version of the class can't load
+
+**dimension** (`number`): Dimension of the embedding vectors the graph was built with
+
+**threshold** (`number`): Similarity threshold the graph was built with
+
+**nodes** (`GraphNode[]`): All nodes in the graph, each including its full embedding
+
+**edges** (`GraphEdge[]`): All edges in the graph
+
+The snapshot is a deep copy, so mutating it doesn't affect the graph it came from. Every node carries its full embedding, so snapshots are large: a 1,000-node graph built with 1536-dimension embeddings serializes to about 20 MB of JSON. Size your storage column accordingly.
+
+### `deserialize`
+
+Rebuilds a `GraphRAG` instance from a snapshot produced by `serialize`.
+
+```typescript
+static deserialize(snapshot: GraphRAGSnapshot): GraphRAG
+```
+
+#### Parameters
+
+**snapshot** (`GraphRAGSnapshot`): A snapshot previously returned by serialize
+
+Throws if the snapshot version is unsupported, if a node embedding doesn't match the snapshot dimension, or if an edge references a node that isn't in the snapshot. A bad snapshot therefore fails at load time instead of during a later query.
+
+## Persisting a graph
+
+Building a graph is O(n²) in the number of chunks, so rebuilding it on every process start is wasteful. Serialize the graph once and store the snapshot wherever you already keep state. A snapshot is plain JSON, so any store works (a file, a blob column, a key-value cache), and `GraphRAG` doesn't depend on a storage backend.
+
+```typescript
+import { readFile, writeFile } from 'node:fs/promises'
+import { GraphRAG } from '@mastra/rag'
+import type { GraphRAGSnapshot } from '@mastra/rag'
+
+const SNAPSHOT_PATH = './docs-graph.json'
+
+async function loadOrBuildGraph() {
+  try {
+    const snapshot = JSON.parse(await readFile(SNAPSHOT_PATH, 'utf8')) as GraphRAGSnapshot
+    return GraphRAG.deserialize(snapshot)
+  } catch {
+    // No usable snapshot yet, so build the graph from scratch
+  }
+
+  const graphRag = new GraphRAG(1536, 0.7)
+  graphRag.createGraph(documentChunks, embeddings)
+
+  await writeFile(SNAPSHOT_PATH, JSON.stringify(graphRag.serialize()))
+
+  return graphRag
+}
+```
+
+A snapshot reflects the chunks it was built from and isn't updated incrementally. When the underlying documents change, build the graph again and store a new snapshot.
+
 ## Advanced example
 
 ```typescript
-const graphRag = new GraphRAG({
-  dimension: 1536,
-  threshold: 0.8, // Stricter similarity threshold
-})
+// Stricter similarity threshold
+const graphRag = new GraphRAG(1536, 0.8)
 
 // Create graph from chunks and embeddings
 graphRag.createGraph(documentChunks, embeddings)

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

@@ -8,7 +8,7 @@
 
 `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).
+For usage patterns and concepts, see [Schedules](https://mastra.ai/docs/harness/schedules).
 
 ## Usage example
 

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

@@ -402,7 +402,7 @@ Contains output from workflow step execution, used primarily for usage tracking
 
 ## Background task chunks
 
-Emitted when a tool call is dispatched as a [background task](https://mastra.ai/docs/long-running-agents/background-tasks) and `streamUntilIdle()` is used.
+Emitted when a tool call is dispatched as a [background task](https://mastra.ai/docs/harness/background-tasks) and `streamUntilIdle()` is used.
 
 ### background-task-started
 
@@ -614,7 +614,7 @@ Contains monitoring and observability data from agent execution. Can include wor
 
 ### goal
 
-Emitted on every evaluation of an agent [goal](https://mastra.ai/docs/long-running-agents/goals). Consumers use this to render judge progress and the result mid-run. A goal that has no judge model configured produces no `goal` chunk.
+Emitted on every evaluation of an agent [goal](https://mastra.ai/docs/harness/goals). Consumers use this to render judge progress and the result mid-run. A goal that has no judge model configured produces no `goal` chunk.
 
 **type** (`"goal"`): Chunk type identifier
 

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

@@ -80,7 +80,7 @@ const stream = await agent.stream('message for agent')
 
 **options.onError** (`({ error }: { error: Error | string }) => Promise<void> | void`): Callback function called when an error occurs during streaming.
 
-**options.onAbort** (`(event: any) => Promise<void> | void`): Callback function called when the stream is aborted.
+**options.onAbort** (`(event: { steps: any[]; text?: string }) => Promise<void> | void`): Callback function called when the stream is aborted. steps contains the steps that completed before the abort, and text contains the assistant text streamed so far for the step that was in flight.
 
 **options.abortSignal** (`AbortSignal`): Signal object that allows you to abort the agent's execution. When the signal is aborted, all ongoing operations will be terminated, including any in-flight subagent runs the agent delegated to.
 
@@ -178,6 +178,8 @@ const stream = await agent.stream('message for agent')
 
 **options.savePerStep** (`boolean`): Save messages incrementally after each stream step completes (default: false).
 
+**options.persistPartialOnAbort** (`boolean`): Save the assistant text that was streamed before an abort to memory (default: false). Only text emitted before the abort is persisted; output a provider keeps producing after cancellation is discarded, and nothing is saved when no text was streamed.
+
 **options.requireToolApproval** (`boolean`): When true, all tool calls require explicit approval before execution. The stream will emit tool-call-approval chunks and pause until approveToolCall() or declineToolCall() is called.
 
 **options.autoResumeSuspendedTools** (`boolean`): When true, automatically resumes suspended tools when the user sends a new message on the same thread. The agent extracts resumeData from the user's message based on the tool's resumeSchema. Requires memory to be configured.
@@ -301,8 +303,9 @@ const stream = await agent.stream('Tell me a story', {
   onError: ({ error }) => {
     console.error('Streaming error:', error)
   },
-  onAbort: event => {
-    console.log('Stream aborted:', event)
+  onAbort: ({ steps, text }) => {
+    console.log('Stream aborted after', steps.length, 'steps')
+    console.log('Partial text:', text)
   },
 })
 
@@ -399,4 +402,4 @@ Responses WebSocket connections run one response at a time. Mastra rejects overl
 
 - [Generating responses](https://mastra.ai/docs/agents/overview)
 - [Streaming responses](https://mastra.ai/docs/agents/overview)
-- [Agent Approval](https://mastra.ai/docs/agents/agent-approval)
+- [Agent Approval](https://mastra.ai/docs/agents/human-in-the-loop)

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

@@ -101,7 +101,7 @@ for await (const chunk of stream.fullStream) {
 
 ## Related
 
-- [Background tasks](https://mastra.ai/docs/long-running-agents/background-tasks)
+- [Background tasks](https://mastra.ai/docs/harness/background-tasks)
 - [`Agent.stream()` reference](https://mastra.ai/reference/streaming/agents/stream)
 - [backgroundTasks configuration reference](https://mastra.ai/reference/configuration)
 - [Stream chunk types](https://mastra.ai/reference/streaming/ChunkType)

package/.docs/reference/tools/ask-user-tool.md

@@ -4,7 +4,7 @@
 
 A built-in, agent-agnostic tool that asks the user a question and waits for their response. The tool supports free-text questions, single-select prompts, and multi-select prompts.
 
-The tool pauses through the native [tool suspension](https://mastra.ai/docs/agents/agent-approval) primitive: it calls `suspend()` with the question payload, which makes the agent emit a `tool-call-suspended` event and persist run state. Resume the run with `agent.resumeStream(answer, { runId })`.
+The tool pauses through the native [tool suspension](https://mastra.ai/docs/agents/human-in-the-loop) primitive: it calls `suspend()` with the question payload, which makes the agent emit a `tool-call-suspended` event and persist run state. Resume the run with `agent.resumeStream(answer, { runId })`.
 
 When executed outside an agent run (no `suspend` available), the tool returns a readable fallback string containing the question and choices.
 

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

@@ -126,4 +126,4 @@ export const codeModeTool = createCodeModeTool({
 
 - [Code mode](https://mastra.ai/docs/agents/code-mode)
 - [createTool()](https://mastra.ai/reference/tools/create-tool)
-- [Sandbox](https://mastra.ai/docs/workspace/sandbox)
+- [Sandbox](https://mastra.ai/docs/sandbox/overview)

package/.docs/reference/tools/create-tool.md

@@ -519,8 +519,8 @@ These annotations follow the [MCP specification](https://spec.modelcontextprotoc
 
 ## Related
 
-- [MCP Overview](https://mastra.ai/docs/mcp/overview)
-- [Using Tools with Agents](https://mastra.ai/docs/agents/using-tools)
-- [Agent Approval](https://mastra.ai/docs/agents/agent-approval)
-- [Tool Streaming](https://mastra.ai/docs/agents/using-tools)
+- [MCP Overview](https://mastra.ai/docs/connections/mcp)
+- [Using Tools with Agents](https://mastra.ai/docs/agents/tools)
+- [Agent Approval](https://mastra.ai/docs/agents/human-in-the-loop)
+- [Tool Streaming](https://mastra.ai/docs/agents/tools)
 - [Request Context](https://mastra.ai/docs/server/request-context)

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

@@ -168,6 +168,51 @@ const fetchUserData = createTool({
 })
 ```
 
+#### Where `authInfo` comes from
+
+When an MCP server is served by a Mastra server, `extra.authInfo` is populated from the principal resolved by `server.auth`. Nothing extra is required:
+
+```typescript
+export const mastra = new Mastra({
+  mcpServers: { myServer },
+  server: {
+    auth: new MastraJwtAuth({ secret: process.env.JWT_SECRET! }),
+  },
+})
+```
+
+The authenticated user is mapped to `authInfo` as:
+
+| `authInfo` field | Value                                                                      |
+| ---------------- | -------------------------------------------------------------------------- |
+| `token`          | The bearer token or session cookie value used for the request              |
+| `clientId`       | The first present of `user.id`, `user.sub`, `user.userId`, `user.email`    |
+| `scopes`         | `user.scopes`, `user.scope`, or `user.permissions`, normalized to an array |
+| `extra.user`     | The full user object returned by the auth provider                         |
+
+If your own middleware performs the verification, set `server.mcpOptions.setRequestAuth` to build `authInfo` yourself. The hook replaces the default mapping and applies to both the streamable HTTP and SSE transports:
+
+```typescript
+export const mastra = new Mastra({
+  mcpServers: { myServer },
+  server: {
+    middleware: [verifyBearerToken], // stores the payload on the request context
+    mcpOptions: {
+      setRequestAuth: (req, requestContext) => {
+        const payload = requestContext.get('bearerPayload')
+        req.auth = {
+          token: payload.token,
+          clientId: payload.sub,
+          scopes: payload.scope.split(' '),
+        }
+      },
+    },
+  },
+})
+```
+
+Leaving `req.auth` unset inside the hook opts the request out of auth info entirely.
+
 ## Methods
 
 These are the functions you can call on an `MCPServer` instance to control its behavior and get information.
@@ -929,7 +974,7 @@ Notification methods (`resources.notifyListChanged()`, `prompts.notifyListChange
 
 ## Examples
 
-For a practical example of packaging a stdio server, see [Publish a stdio server package](https://mastra.ai/docs/mcp/overview).
+For a practical example of packaging a stdio server, see [Publish a stdio server package](https://mastra.ai/docs/connections/mcp).
 
 The example at the beginning of this page also demonstrates how to instantiate `MCPServer` with both tools and agents.
 
@@ -1663,7 +1708,7 @@ const server = new MCPServer({
 })
 ```
 
-Link a tool to its app resource by setting `mcp._meta.ui.resourceUri` in `createTool()` to the matching `ui://` URI. The server normalizes this metadata for older hosts when listing tools. Visit [MCP Apps](https://mastra.ai/docs/mcp/overview) for the full app bridge API and usage patterns.
+Link a tool to its app resource by setting `mcp._meta.ui.resourceUri` in `createTool()` to the matching `ui://` URI. The server normalizes this metadata for older hosts when listing tools. Visit [MCP Apps](https://mastra.ai/docs/connections/mcp) for the full app bridge API and usage patterns.
 
 ## Related information
 

package/.docs/reference/tools/submit-plan-tool.md

@@ -4,7 +4,7 @@
 
 A built-in, agent-agnostic tool that submits an implementation plan for user review. The agent writes a plan to a markdown file and passes the file path to this tool. The tool suspends the run until the user approves or rejects the plan.
 
-The tool pauses through the native [tool suspension](https://mastra.ai/docs/agents/agent-approval) primitive: it calls `suspend({ path })`, which makes the agent emit a `tool-call-suspended` event. The host reads the plan file and presents it to the user. It then resumes with an approval or rejection.
+The tool pauses through the native [tool suspension](https://mastra.ai/docs/agents/human-in-the-loop) primitive: it calls `suspend({ path })`, which makes the agent emit a `tool-call-suspended` event. The host reads the plan file and presents it to the user. It then resumes with an approval or rejection.
 
 When executed outside an agent run (no `suspend` available), the tool returns a readable fallback string containing the file path.
 

package/.docs/reference/tools/task-tools.md

@@ -2,11 +2,11 @@
 
 # Task tools
 
-Four built-in, agent-agnostic tools that manage a structured task list for an agent run. The task list is persisted in the thread-scoped `threadState` storage domain and projected onto the agent [state-signal](https://mastra.ai/docs/long-running-agents/signals) lane so it survives [observational-memory](https://mastra.ai/docs/memory/observational-memory) truncation.
+Four built-in, agent-agnostic tools that manage a structured task list for an agent run. The task list is persisted in the thread-scoped `threadState` storage domain and projected onto the agent [state-signal](https://mastra.ai/docs/harness/signals) lane so it survives [observational-memory](https://mastra.ai/docs/memory/observational-memory) truncation.
 
 Task tracking requires a memory-backed thread (`threadId` + `resourceId`). Without memory the tools return an error explaining that task tracking requires agent memory.
 
-The recommended setup is [`TaskSignalProvider`](https://mastra.ai/reference/signals/task-signal-provider), which bundles all four tools and the `TaskStateProcessor` in a single registration. See [Built-in tools](https://mastra.ai/docs/agents/using-tools) for the conceptual guide.
+The recommended setup is [`TaskSignalProvider`](https://mastra.ai/reference/signals/task-signal-provider), which bundles all four tools and the `TaskStateProcessor` in a single registration. See [Built-in tools](https://mastra.ai/docs/agents/tools) for the conceptual guide.
 
 ## Usage example
 

package/.docs/reference/vectors/vectorize.md

@@ -90,13 +90,13 @@ Lists all metadata field indexes for an index.
 
 ### `updateVector()`
 
-Updates a vector or metadata for a specific ID within an index.
+Updates the vector and optionally the metadata for a specific ID within an index. Vectorize has no partial-update operation, so `update.vector` is required. Metadata-only updates aren't supported and throw an error.
 
 **indexName** (`string`): Name of the index containing the ID to update
 
 **id** (`string`): Unique identifier of the vector or metadata to update
 
-**update** (`{ vector?: number[]; metadata?: Record<string, any>; }`): Object containing the vector and/or metadata to update
+**update** (`{ vector: number[]; metadata?: Record<string, any>; }`): Object containing the new vector values, and optionally the metadata to update. The vector values are required
 
 ### `deleteVector()`
 
@@ -106,6 +106,16 @@ Deletes a vector and its associated metadata for a specific ID within an index.
 
 **id** (`string`): Unique identifier of the vector and metadata to delete
 
+### `deleteVectors()`
+
+Deletes multiple vectors and their associated metadata by ID. Vectorize has no filtered-delete operation, so deleting by metadata filter isn't supported and throws an error.
+
+**indexName** (`string`): Name of the index containing the vectors to delete
+
+**ids** (`string[]`): Unique identifiers of the vectors to delete. Must contain at least one ID, and cannot be combined with filter
+
+**filter** (`Record<string, any>`): Not supported by Vectorize. Passing a filter throws an error
+
 ## Response types
 
 Query results are returned in this format:

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

@@ -31,7 +31,7 @@ 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).
+Use HTTPS URLs in production. See [Security recommendations](https://mastra.ai/docs/auth/workers).
 
 The orchestration worker sends step execution requests to:
 
@@ -41,7 +41,7 @@ ${MASTRA_STEP_EXECUTION_URL}/workflows/:workflowId/runs/:runId/steps/execute
 
 ### `MASTRA_WORKER_AUTH_TOKEN`
 
-A bearer token sent by the orchestration worker when calling the API's step execution endpoint. The API's configured auth provider must recognize this token. See [Worker authentication](https://mastra.ai/docs/server/auth/workers).
+A bearer token sent by the orchestration worker when calling the API's step execution endpoint. The API's configured auth provider must recognize this token. See [Worker authentication](https://mastra.ai/docs/auth/workers).
 
 ```text
 MASTRA_WORKER_AUTH_TOKEN=sk-worker-secret-token

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

@@ -356,4 +356,4 @@ Set `WORKSPACE_PATH` in your environment to an absolute path like `/home/user/my
 
 - [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem)
 - [Workspace class](https://mastra.ai/reference/workspace/workspace-class)
-- [Sandbox](https://mastra.ai/docs/workspace/sandbox)
+- [Sandbox](https://mastra.ai/docs/sandbox/overview)

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

@@ -123,10 +123,11 @@ await sandbox.start()
 // Spawn a background process
 const handle = await sandbox.processes.spawn('node server.js')
 
-// Read output, send stdin, kill
+// Read output, send stdin, signal EOF, and wait for completion
 console.log(handle.stdout)
 await handle.sendStdin('input\n')
-await handle.kill()
+await handle.closeStdin()
+await handle.wait()
 ```
 
 When native isolation is enabled (`seatbelt` or `bwrap`), spawned processes are also wrapped with the same isolation backend.
@@ -223,4 +224,4 @@ This separation prevents sandboxed processes from reading or modifying their own
 - [SandboxProcessManager reference](https://mastra.ai/reference/workspace/process-manager)
 - [WorkspaceSandbox Interface](https://mastra.ai/reference/workspace/sandbox)
 - [Workspace Class](https://mastra.ai/reference/workspace/workspace-class)
-- [Sandbox](https://mastra.ai/docs/workspace/sandbox)
+- [Sandbox](https://mastra.ai/docs/sandbox/overview)