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

package/.docs/docs/agents/agent-approval.md

@@ -90,6 +90,20 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
+#### Explaining a decline
+
+`declineToolCall()`, `declineToolCallGenerate()`, and `declineNetworkToolCall()` accept an optional `reason`. The reason is returned to the model in place of the tool result, so the model can adjust instead of retrying blindly. It's also stored on the tool call's `approval` metadata, so it's still there when the conversation is recalled.
+
+```typescript
+const declined = await agent.declineToolCall({
+  runId: stream.runId,
+  toolCallId,
+  reason: 'Reading other users PII is not allowed, ask the user for their own email instead',
+})
+```
+
+Without a `reason`, the model receives the default message `Tool call was not approved by the user`.
+
 #### Conditional approval with a function
 
 Instead of a boolean, `requireToolApproval` accepts a function that decides per tool call. It receives the `toolName`, the `args` the model passed, the `requestContext`, and the `workspace`. Return `true` to require approval for that call, or `false` to allow it. This lets you gate approval at runtime, for example, only for tools whose name matches a pattern:

package/.docs/docs/agents/code-mode.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.38.0`
 
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 Code mode lets an agent run multi-tool computations in an isolated sandbox and return the result as a single, more accurate response.
 
@@ -134,7 +134,7 @@ The generated code for `sales_code` can't call an inventory tool, and the revers
 
 ## Remote sandboxes
 
-By default, code mode uses a transport that writes the program to the host filesystem and runs `node` against it. That works for `LocalSandbox`, which shares the host, but not for remote sandboxes that run in their own micro-VM (such as [E2B](https://mastra.ai/reference/workspace/e2b-sandbox)), where the host paths don't exist.
+By default, code mode uses a transport that writes the program to the host filesystem and runs `node` against it. That works for `LocalSandbox`, which shares the host, but not for remote sandboxes that run in their own micro-VM (such as [E2B](https://mastra.ai/integrations/sandboxes/e2b)), where the host paths don't exist.
 
 Remote sandboxes need a transport that writes the program into the sandbox filesystem. For E2B, pass the included `E2BCodeModeTransport` as the second argument to `createCodeMode`:
 
@@ -164,9 +164,24 @@ const { tool, instructions } = createCodeMode(
 
 `isolated-vm` is a native addon, and on Node.js 20 and later the host process must be started with the `--no-node-snapshot` flag. See the [IsolatedVmCodeModeTransport reference](https://mastra.ai/reference/tools/isolated-vm-transport) for setup details.
 
+When the host can't install native addons or set Node.js flags, which is common on serverless platforms, use [`QuickJsCodeModeTransport`](https://mastra.ai/reference/tools/quickjs-transport) from `@mastra/quickjs` instead. It gives the same in-process boundary using a QuickJS runtime compiled to WebAssembly, at the cost of slower execution:
+
+```typescript
+import { createCodeMode } from '@mastra/core/tools'
+import { QuickJsCodeModeTransport } from '@mastra/quickjs'
+
+const { tool, instructions } = createCodeMode(
+  { tools }, // no sandbox needed
+  new QuickJsCodeModeTransport({ memoryLimitMb: 128 }),
+)
+```
+
+See [Choosing a transport](https://mastra.ai/reference/tools/quickjs-transport) for a side-by-side comparison.
+
 ## Related
 
 - [createCodeMode() reference](https://mastra.ai/reference/tools/create-code-mode)
 - [IsolatedVmCodeModeTransport reference](https://mastra.ai/reference/tools/isolated-vm-transport)
+- [QuickJsCodeModeTransport reference](https://mastra.ai/reference/tools/quickjs-transport)
 - [Tools](https://mastra.ai/docs/agents/using-tools)
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)

package/.docs/docs/agents/networks.md

@@ -4,7 +4,7 @@
 
 > **Deprecated:** Agent networks are deprecated and will be removed in a future major release. [Supervisor agents](https://mastra.ai/docs/capabilities/subagents) using `agent.stream()` or `agent.generate()` are now the recommended approach. It provides the same multi-agent coordination with better control, a simpler API, and easier debugging.
 >
-> See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
+> See the [migration guide](https://mastra.ai/reference/migrations/network-to-supervisor) to upgrade.
 
 A **routing agent** uses an LLM to interpret a request and decide which primitives (subagents, workflows, or tools) to call, in what order, and with what data.
 
@@ -181,4 +181,4 @@ Requirements for automatic resumption:
 ## Related
 
 - [Supervisor agents](https://mastra.ai/docs/capabilities/subagents)
-- [Migration: `.network()` to supervisor agents](https://mastra.ai/guides/migrations/network-to-supervisor)
+- [Migration: `.network()` to supervisor agents](https://mastra.ai/reference/migrations/network-to-supervisor)

package/.docs/docs/agents/overview.md

@@ -211,10 +211,10 @@ Once your agent is running, use this table to find the right page for what you w
 | Build agents that correct their work                           | [Rubric scorer](https://mastra.ai/docs/capabilities/subagents)         |
 | Swap instructions or models based on request context           | [Dynamic configuration](https://mastra.ai/docs/server/request-context) |
 | Add speech-to-text or text-to-speech                           | [Voice](https://mastra.ai/guides/voice/overview)                       |
-| Connect to Slack, Discord, or Telegram                         | [Channels](https://mastra.ai/docs/capabilities/channels/overview)      |
+| Connect to Slack, Discord, or Telegram                         | [Channels](https://mastra.ai/docs/capabilities/channels)               |
 
 ## Multi-agent systems
 
 A multi-agent system uses multiple agents to solve a task that's too broad or too specialized for a single agent. Instead of building one agent with dozens of tools and a long instruction set, you split responsibilities across focused agents and let a coordinator bring results together.
 
-Read the [conceptual overview of multi-agent systems](https://mastra.ai/guides/concepts/multi-agent-systems) to learn how you can apply different patterns with Mastra.
+Read the [conceptual overview of multi-agent systems](https://mastra.ai/docs/guides/multi-agent-systems) to learn how you can apply different patterns with Mastra.

package/.docs/docs/agents/processors.md

@@ -432,7 +432,7 @@ See the [`ProviderHistoryCompat` reference](https://mastra.ai/reference/processo
 
 ## Response caching
 
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 Response caching skips the LLM call and replays a previously cached response when an agent receives an identical request. Use it to reduce latency and avoid paying for repeated calls.
 
@@ -544,7 +544,7 @@ This means the cache key is derived from the resolved `LanguageModelV2Prompt` Ma
 
 When you don't supply `key`, the processor derives one deterministically from the inputs that change the LLM's response at this step: `agentId`, `stepNumber` (so each step in a tool loop has its own cache entry), `scope`, model identity (`provider`, `modelId`, spec version), and the resolved `prompt` (post-memory + post-processors). Any change to these inputs automatically invalidates the cache.
 
-Multimodal prompts are included too. Image and file parts reach the key by value: a URL contributes its full href, and inline binary data (`Uint8Array`, `ArrayBuffer`) contributes a digest of its bytes. Two requests that differ only in which image they reference therefore get different cache entries.
+Multimodal prompts are included too. Image and file parts reach the key by value: the key includes a URL's full href, and a digest of the bytes for inline binary data (`Uint8Array`, `ArrayBuffer`). Requests that differ only in which image they reference therefore get different cache entries.
 
 #### Customize the cache key
 
@@ -664,7 +664,7 @@ export class SteeringReminderProcessor implements Processor {
 }
 ```
 
-A transient signal still appears in the prompt for the current call, so the model sees it near the latest turn. It's not retained, so re-sending it each turn keeps a single fresh copy in context instead of an accumulating history, and it never appears in stored thread history. Because nothing is written, it also keeps a stable prompt cache prefix across turns.
+A transient signal is still in the prompt for the current call, so the model sees it near the latest turn. It's not retained, so re-sending it each turn keeps a single fresh copy in context instead of an accumulating history, and stored thread history never includes it. Because nothing is written, it also keeps a stable prompt cache prefix across turns.
 
 ### Emit custom stream events
 

package/.docs/docs/agents/using-tools.md

@@ -353,7 +353,7 @@ Agent-level and per-execution hooks merge per key: passing only `beforeToolCall`
 
 Tools support lifecycle hooks that allow you to monitor different stages of tool execution during streaming. These hooks are particularly useful for logging or analytics.
 
-For generic `writer` API usage, see [Streaming](https://mastra.ai/guides/concepts/streaming).
+For generic `writer` API usage, see [Streaming](https://mastra.ai/docs/guides/streaming).
 
 ### Available Hooks
 

package/.docs/docs/browser/overview.md

@@ -6,10 +6,10 @@ Browser support enables agents to move through websites, interact with page elem
 
 Mastra supports three SDK providers and one CLI provider:
 
-- [**AgentBrowser**](https://mastra.ai/docs/browser/agent-browser): A Playwright-based provider with accessibility-first element targeting. Best for general web automation and scraping.
-- [**Stagehand**](https://mastra.ai/docs/browser/stagehand): A Browserbase provider with AI-powered element detection. Best for complex interactions that benefit from natural language selectors.
-- [**FirecrawlBrowser**](https://mastra.ai/docs/browser/firecrawl): A Firecrawl Browser Sandbox provider that runs AgentBrowser tools against hosted browser sessions. Best for running automation on hosted browser sessions without managing local browser infrastructure.
-- [**BrowserViewer**](https://mastra.ai/docs/browser/browser-viewer): A CLI provider that launches Chrome and injects CDP URLs into CLI tools like agent-browser, browser-use, and browse. Best for workspace agents that drive browsers through shell commands.
+- [**AgentBrowser**](https://mastra.ai/integrations/browsers/agent-browser): A Playwright-based provider with accessibility-first element targeting. Best for general web automation and scraping.
+- [**Stagehand**](https://mastra.ai/integrations/browsers/stagehand): A Browserbase provider with AI-powered element detection. Best for complex interactions that benefit from natural language selectors.
+- [**FirecrawlBrowser**](https://mastra.ai/integrations/browsers/firecrawl): A Firecrawl Browser Sandbox provider that runs AgentBrowser tools against hosted browser sessions. Best for running automation on hosted browser sessions without managing local browser infrastructure.
+- [**BrowserViewer**](https://mastra.ai/integrations/browsers/browser-viewer): A CLI provider that launches Chrome and injects CDP URLs into CLI tools like agent-browser, browser-use, and browse. Best for workspace agents that drive browsers through shell commands.
 - [**Browser recording (alpha)**](https://mastra.ai/docs/browser/recording): An opt-in tool layer that saves browser sessions as Motion-JPEG AVI videos with optional captions.
 
 ## When to use browser
@@ -178,10 +178,10 @@ const browser = new AgentBrowser({
 
 ## Next steps
 
-- [AgentBrowser](https://mastra.ai/docs/browser/agent-browser)
-- [Stagehand](https://mastra.ai/docs/browser/stagehand)
-- [Firecrawl](https://mastra.ai/docs/browser/firecrawl)
+- [AgentBrowser](https://mastra.ai/integrations/browsers/agent-browser)
+- [Stagehand](https://mastra.ai/integrations/browsers/stagehand)
+- [Firecrawl](https://mastra.ai/integrations/browsers/firecrawl)
 - [Browser recording (alpha)](https://mastra.ai/docs/browser/recording)
-- [BrowserViewer](https://mastra.ai/docs/browser/browser-viewer)
+- [BrowserViewer](https://mastra.ai/integrations/browsers/browser-viewer)
 - [MastraBrowser reference](https://mastra.ai/reference/browser/mastra-browser)
 - 📹 [Mastra browser capabilities workshop](https://www.youtube.com/watch?v=E9KFsZEnQO8\&t=5s)

package/.docs/docs/browser/recording.md

@@ -1,12 +1,12 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Browser recording (beta)
+# Browser recording
 
 **Added in:** `@mastra/core@1.43.0`
 
 Browser recording adds two opt-in tools that let an agent save a browser session as a Motion-JPEG AVI video. The agent can also add short captions while it works.
 
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 ## When to use browser recording
 
@@ -115,6 +115,6 @@ Use shorter recordings when possible. Long browser sessions produce larger files
 
 ## Next steps
 
-- [AgentBrowser](https://mastra.ai/docs/browser/agent-browser)
-- [Stagehand](https://mastra.ai/docs/browser/stagehand)
+- [AgentBrowser](https://mastra.ai/integrations/browsers/agent-browser)
+- [Stagehand](https://mastra.ai/integrations/browsers/stagehand)
 - [Browser overview](https://mastra.ai/docs/browser/overview)

package/.docs/docs/capabilities/{channels/overview.md → channels.md}

@@ -8,14 +8,15 @@ Channels connect agents to messaging and collaboration platforms like Slack, Mic
 
 Start with the page for your platform:
 
-- [Slack](https://mastra.ai/docs/capabilities/channels/slack)
-- [Microsoft Teams](https://mastra.ai/docs/capabilities/channels/teams)
-- [Discord](https://mastra.ai/docs/capabilities/channels/discord)
-- [Telegram](https://mastra.ai/docs/capabilities/channels/telegram)
-- [WhatsApp](https://mastra.ai/docs/capabilities/channels/whatsapp)
-- [iMessage](https://mastra.ai/docs/capabilities/channels/imessage)
+- [Slack](https://mastra.ai/integrations/channels/slack)
+- [Microsoft Teams](https://mastra.ai/integrations/channels/teams)
+- [Discord](https://mastra.ai/integrations/channels/discord)
+- [Telegram](https://mastra.ai/integrations/channels/telegram)
+- [WhatsApp](https://mastra.ai/integrations/channels/whatsapp)
+- [iMessage](https://mastra.ai/integrations/channels/imessage)
+- [GitHub](https://mastra.ai/integrations/channels/github)
 
-[More](https://mastra.ai/docs/capabilities/channels/other-adapters) lists additional platforms. Mastra channels work with compatible [Chat SDK adapters](https://chat-sdk.dev/adapters) beyond the platforms listed here, and the same Mastra configuration pattern applies across adapters.
+[Other adapters](#other-adapters) lists additional platforms. Mastra channels work with compatible [Chat SDK adapters](https://chat-sdk.dev/adapters) beyond the platforms listed here, and the same Mastra configuration pattern applies across adapters.
 
 ## When to use channels
 
@@ -274,6 +275,68 @@ export const mastra = new Mastra({
 
 Vercel's managed Redis integration and Upstash Redis both work well. For more on when a distributed pub/sub is needed, see the [PubSub guide](https://mastra.ai/docs/server/pubsub) and the [`RedisStreamsPubSub` reference](https://mastra.ai/reference/pubsub/redis-streams).
 
+## Other adapters
+
+Mastra channels use Chat SDK adapters, so the platform guides aren't the full list of supported platforms. Use any Chat SDK platform adapter that exports an adapter factory compatible with `channels.adapters`.
+
+### Adapter catalog
+
+The [Chat SDK adapter catalog](https://chat-sdk.dev/adapters) is the canonical source for available adapters. The list below is a snapshot and may not always be up to date.
+
+At the time of writing, Chat SDK lists adapters for:
+
+- AgentPhone
+- Baileys WhatsApp
+- Discord
+- GitHub
+- Google Chat
+- iMessage
+- Kapso
+- Lark / Feishu
+- Linear
+- Liveblocks
+- Matrix
+- Mattermost
+- Messenger
+- Novu
+- Resend
+- Sendblue
+- Telegram
+- Twilio
+- Velt
+- Web
+- Webex
+- WeChat
+- WhatsApp Business Cloud
+- X
+- Zalo
+- Zernio
+
+Check the adapter's docs for its package name, credential variables, webhook requirements, and platform-specific behavior.
+
+### Use the same Mastra wiring
+
+The Mastra side of each Chat SDK adapter follows the same setup. Install the adapter package and add its factory to `channels.adapters`. Then configure the platform credentials and point its webhook to the generated Mastra route.
+
+Use one of the platform guides as a reference for the Mastra wiring:
+
+- [Discord](https://mastra.ai/integrations/channels/discord)
+- [Microsoft Teams](https://mastra.ai/integrations/channels/teams)
+- [Slack](https://mastra.ai/integrations/channels/slack)
+- [Telegram](https://mastra.ai/integrations/channels/telegram)
+- [WhatsApp](https://mastra.ai/integrations/channels/whatsapp)
+
+### Check the adapter docs
+
+Before wiring a new adapter into Mastra, check the adapter docs for:
+
+- Attachment, card, and rich message support.
+- Credential environment variables.
+- Required platform permissions or scopes.
+- Whether regular messages require long-running listeners or polling.
+- Whether the platform needs separate routes for setup, events, or interactions.
+- Webhook verification behavior.
+
 ## Related
 
 - [Channels reference](https://mastra.ai/reference/agents/channels)

package/.docs/docs/capabilities/subagents.md

@@ -16,7 +16,7 @@ Common use cases:
 - Multi-step tasks that need different expertise at each stage
 - Tasks where you need fine-grained control over delegation behavior
 
-> **Note:** A parent agent that coordinates subagents is often called a supervisor. The supervisor pattern is one approach to building multi-agent systems in Mastra. For other patterns, read the [conceptual overview](https://mastra.ai/guides/concepts/multi-agent-systems).
+> **Note:** A parent agent that coordinates subagents is often called a supervisor. The supervisor pattern is one approach to building multi-agent systems in Mastra. For other patterns, read the [conceptual overview](https://mastra.ai/docs/guides/multi-agent-systems).
 
 ## Quickstart
 
@@ -113,7 +113,7 @@ The `context` object includes:
 
 ### Request context at the delegation boundary
 
-Each delegation receives a request context whose entries are shallowly copied from the parent run, excluding run-scoped identity keys. Setting or deleting entries during the subagent run does not affect the parent's context. Set entries on `context.requestContext` in `onDelegationStart` to pass values to the delegated run:
+Each delegation receives a request context whose entries are shallowly copied from the parent run, excluding run-scoped identity keys. Setting or deleting entries during the subagent run doesn't affect the parent's context. Set entries on `context.requestContext` in `onDelegationStart` to pass values to the delegated run:
 
 ```typescript
 const stream = await parentAgent.stream('Research AI trends', {
@@ -134,6 +134,9 @@ Called after a delegation finishes. Use it to inspect results or provide feedbac
 
 - `context.bail()`: Stop the parent agent's loop immediately
 - Return `{ feedback: '...' }`: Add feedback that gets saved to the parent agent's memory and is visible to subsequent iterations
+- Return `{ resultText: '...' }`: Replace the tool result text the parent model sees for this delegation, within the current run
+
+Use `resultText` when the subagent's own result would mislead the parent immediately. For example, a subagent that stops on a tool-calls step returns empty text, which the parent model reads as a successful but empty delegation. Unlike `feedback`, which only reaches the model on the next turn, `resultText` changes what the parent reasons on right away.
 
 ```typescript
 const stream = await parentAgent.stream('Research AI trends', {
@@ -450,5 +453,5 @@ Version overrides propagate automatically through delegation. See [Subagent vers
 - [Agent.generate() reference](https://mastra.ai/reference/agents/generate)
 - [Agent approval](https://mastra.ai/docs/agents/agent-approval)
 - [Memory in multi-agent systems](https://mastra.ai/docs/memory/overview)
-- [Concept: Multi-agent systems](https://mastra.ai/guides/concepts/multi-agent-systems)
+- [Concept: Multi-agent systems](https://mastra.ai/docs/guides/multi-agent-systems)
 - 📹 [Mastra supervisor agents workshop](https://www.youtube.com/watch?v=FNb2fL9WhQg\&t=1872s)

package/.docs/docs/datasets/running-experiments.md

@@ -206,6 +206,55 @@ The `experiment.run.finished` event is awaited before Mastra persists the final
 
 The exported event types are `ExperimentEvent`, `ExperimentRunStartedEvent`, `ExperimentItemCompletedEvent`, and `ExperimentRunFinishedEvent`. Use the discriminated `type` field to narrow an event before reading event-specific properties.
 
+## Lifecycle hooks
+
+Use lifecycle hooks to prepare state before a target runs and clean it up afterwards. This is useful when an item can't be evaluated against an empty environment. A run might need a fixture file copied into the agent's workspace, or a sandbox provisioned before the agent can touch it.
+
+Hooks run at two levels. `beforeAll` and `afterAll` run once per experiment, and `beforeEach` and `afterEach` run once per item:
+
+```typescript
+const summary = await dataset.startExperiment({
+  targetType: 'agent',
+  targetId: 'document-agent',
+  scorers: ['accuracy'],
+  beforeAll: async ({ experimentId }) => {
+    await createWorkspace(experimentId)
+  },
+  beforeEach: async ({ item }) => {
+    await copyFixture(item.metadata?.fixture)
+  },
+  afterEach: async ({ item, result }) => {
+    await clearWorkspaceFiles(item.id)
+  },
+  afterAll: async ({ summary }) => {
+    await deleteWorkspace(summary.experimentId)
+  },
+})
+```
+
+Every hook can be async. Each one receives the `experimentId`, the `mastra` instance, and the run-level `signal`, so long-running setup can be cancelled along with the experiment. The per-item hooks also receive `item`. The teardown hooks receive the result they follow: `afterEach` receives the item's `result` including scores, and `afterAll` receives the `summary` that's about to be returned.
+
+The item passed to hooks exposes `id`, `input`, `groundTruth`, and `metadata`. Fields that control execution, such as tool mocks and scorer selection, aren't exposed, so a hook can't change how the item runs.
+
+### Hook failures
+
+Each hook has a different consequence when it throws, based on how much of the run depends on it:
+
+| Hook         | On failure                                                                       |
+| ------------ | -------------------------------------------------------------------------------- |
+| `beforeAll`  | Fails the experiment. No items run.                                              |
+| `beforeEach` | Fails that item with `EXPERIMENT_ITEM_BEFORE_EACH_FAILED`. Other items continue. |
+| `afterEach`  | Logged. The item's recorded outcome doesn't change.                              |
+| `afterAll`   | Logged. The returned summary doesn't change.                                     |
+
+When `beforeAll` fails, the experiment is marked failed and the `experiment.run.finished` event is still emitted before the error propagates.
+
+When `beforeEach` fails, the target and its scorers are skipped for that item, since the item's preconditions were never met. `afterEach` is also skipped for that item, on the basis that setup which didn't finish owns its own cleanup.
+
+Teardown failures are logged rather than propagated. By the time `afterEach` runs, the target has already produced a real result, and discarding it because cleanup was untidy would lose the data the experiment was run to collect.
+
+`afterAll` runs on every exit path, including when the experiment fails, when `beforeAll` fails, and when an [event observer](#observe-experiment-events) fails, so teardown isn't skipped when something goes wrong. It runs at most once per experiment.
+
 ## Tool mocks
 
 When an experiment runs an agent that calls side-effecting tools, attach static tool mocks to individual dataset items to make the run deterministic. During the experiment, a mocked tool returns its declared output instead of executing. Tools without a mock on the item run live by default.

package/.docs/docs/deployment/cloud-providers.md

@@ -12,12 +12,12 @@ Mastra provides a platform to deploy your server to the cloud. Read the [Mastra
 
 The following guides show how to deploy Mastra to specific cloud providers:
 
-- [Amazon Bedrock AgentCore](https://mastra.ai/guides/deployment/aws-bedrock-agentcore)
-- [Amazon EC2](https://mastra.ai/guides/deployment/amazon-ec2)
-- [AWS Lambda](https://mastra.ai/guides/deployment/aws-lambda)
-- [Azure App Services](https://mastra.ai/guides/deployment/azure-app-services)
-- [Cloudflare](https://mastra.ai/guides/deployment/cloudflare)
-- [Digital Ocean](https://mastra.ai/guides/deployment/digital-ocean)
-- [Kubernetes](https://mastra.ai/guides/deployment/kubernetes)
-- [Netlify](https://mastra.ai/guides/deployment/netlify)
-- [Vercel](https://mastra.ai/guides/deployment/vercel)
+- [Amazon Bedrock AgentCore](https://mastra.ai/integrations/deploy/aws-bedrock-agentcore)
+- [Amazon EC2](https://mastra.ai/integrations/deploy/amazon-ec2)
+- [AWS Lambda](https://mastra.ai/integrations/deploy/aws-lambda)
+- [Azure App Services](https://mastra.ai/integrations/deploy/azure-app-services)
+- [Cloudflare](https://mastra.ai/integrations/deploy/cloudflare)
+- [Digital Ocean](https://mastra.ai/integrations/deploy/digital-ocean)
+- [Kubernetes](https://mastra.ai/integrations/deploy/kubernetes)
+- [Netlify](https://mastra.ai/integrations/deploy/netlify)
+- [Vercel](https://mastra.ai/integrations/deploy/vercel)

package/.docs/docs/deployment/overview.md

@@ -43,14 +43,14 @@ Mastra applications can be deployed to cloud providers and serverless platforms.
 
 Use this option for auto-scaling, minimal infrastructure management, or when you're already using one of these platforms.
 
-- [Amazon EC2](https://mastra.ai/guides/deployment/amazon-ec2)
-- [AWS Lambda](https://mastra.ai/guides/deployment/aws-lambda)
-- [Azure App Services](https://mastra.ai/guides/deployment/azure-app-services)
-- [Cloudflare](https://mastra.ai/guides/deployment/cloudflare)
-- [Digital Ocean](https://mastra.ai/guides/deployment/digital-ocean)
-- [Kubernetes](https://mastra.ai/guides/deployment/kubernetes)
-- [Netlify](https://mastra.ai/guides/deployment/netlify)
-- [Vercel](https://mastra.ai/guides/deployment/vercel)
+- [Amazon EC2](https://mastra.ai/integrations/deploy/amazon-ec2)
+- [AWS Lambda](https://mastra.ai/integrations/deploy/aws-lambda)
+- [Azure App Services](https://mastra.ai/integrations/deploy/azure-app-services)
+- [Cloudflare](https://mastra.ai/integrations/deploy/cloudflare)
+- [Digital Ocean](https://mastra.ai/integrations/deploy/digital-ocean)
+- [Kubernetes](https://mastra.ai/integrations/deploy/kubernetes)
+- [Netlify](https://mastra.ai/integrations/deploy/netlify)
+- [Vercel](https://mastra.ai/integrations/deploy/vercel)
 
 ### Sandbox
 
@@ -72,7 +72,7 @@ Use these guides when adding Mastra to an existing Next.js or Astro application.
 
 Mastra workflows run using the built-in execution engine by default. For production workloads requiring managed infrastructure, workflows can also be deployed to specialized platforms like [Inngest](https://www.inngest.com) that provide step memoization, automatic retries, and real-time monitoring.
 
-Visit the [Workflow Runners guide](https://mastra.ai/docs/deployment/workflow-runners) for execution options and the [Inngest deployment guide](https://mastra.ai/guides/deployment/inngest) for setup instructions.
+Visit the [Workflow Runners guide](https://mastra.ai/docs/deployment/workflow-runners) for execution options and the [Inngest deployment guide](https://mastra.ai/integrations/deploy/inngest) for setup instructions.
 
 ## Workers
 

package/.docs/docs/deployment/sandbox.md

@@ -17,9 +17,9 @@ Sandboxes have provider-enforced runtime caps and expire. For production hosting
 
 The deployer works with any workspace sandbox that supports networking (public port URLs):
 
-- [Vercel Sandbox](https://mastra.ai/reference/workspace/vercel-sandbox) (`@mastra/vercel`)
-- [E2B](https://mastra.ai/reference/workspace/e2b-sandbox) (`@mastra/e2b`)
-- [Daytona](https://mastra.ai/reference/workspace/daytona-sandbox) (`@mastra/daytona`)
+- [Vercel Sandbox](https://mastra.ai/integrations/sandboxes/vercel) (`@mastra/vercel`)
+- [E2B](https://mastra.ai/integrations/sandboxes/e2b) (`@mastra/e2b`)
+- [Daytona](https://mastra.ai/integrations/sandboxes/daytona) (`@mastra/daytona`)
 
 Provider authors can add support by implementing the optional `networking` capability on [`WorkspaceSandbox`](https://mastra.ai/reference/workspace/sandbox).
 

package/.docs/docs/deployment/web-framework.md

@@ -4,16 +4,16 @@
 
 When Mastra is integrated with a web framework, it deploys alongside your application using the framework's standard deployment process. Follow the instructions below to ensure your Mastra integration deploys correctly.
 
-> **Warning:** If you're deploying to a cloud provider, remove any usage of [LibSQLStore](https://mastra.ai/reference/storage/libsql) from your Mastra configuration. LibSQLStore requires filesystem access and isn't compatible with serverless platforms.
+> **Warning:** If you're deploying to a cloud provider, remove any usage of [LibSQLStore](https://mastra.ai/integrations/databases/libsql) from your Mastra configuration. LibSQLStore requires filesystem access and isn't compatible with serverless platforms.
 
 Integration guides:
 
-- [With Next.js](https://mastra.ai/guides/getting-started/next-js)
-- [With Astro](https://mastra.ai/guides/getting-started/astro)
+- [With Next.js](https://mastra.ai/integrations/frameworks/next-js)
+- [With Astro](https://mastra.ai/integrations/frameworks/astro)
 
 ## With Next.js on Vercel
 
-If you've integrated Mastra with Next.js [by following our guide](https://mastra.ai/guides/getting-started/next-js) and plan to deploy to Vercel, add `serverExternalPackages: ["@mastra/*"]` to your `next.config.ts`:
+If you've integrated Mastra with Next.js [by following our guide](https://mastra.ai/integrations/frameworks/next-js) and plan to deploy to Vercel, add `serverExternalPackages: ["@mastra/*"]` to your `next.config.ts`:
 
 ```typescript
 import type { NextConfig } from 'next'
@@ -27,7 +27,7 @@ export default nextConfig
 
 ## With Astro on Vercel
 
-If you've integrated Mastra with Astro [by following our guide](https://mastra.ai/guides/getting-started/astro) and plan to deploy to Vercel, add the Vercel adapter and server output to your `astro.config.mjs`:
+If you've integrated Mastra with Astro [by following our guide](https://mastra.ai/integrations/frameworks/astro) and plan to deploy to Vercel, add the Vercel adapter and server output to your `astro.config.mjs`:
 
 ```javascript
 import { defineConfig } from 'astro/config'
@@ -41,7 +41,7 @@ export default defineConfig({
 
 ## With Astro on Netlify
 
-If you've integrated Mastra with Astro [by following our guide](https://mastra.ai/guides/getting-started/astro) and plan to deploy to Netlify, add the Netlify adapter and server output to your `astro.config.mjs`:
+If you've integrated Mastra with Astro [by following our guide](https://mastra.ai/integrations/frameworks/astro) and plan to deploy to Netlify, add the Netlify adapter and server output to your `astro.config.mjs`:
 
 ```javascript
 import { defineConfig } from 'astro/config'

package/.docs/docs/deployment/workers.md

@@ -2,7 +2,7 @@
 
 # Workers
 
-> **Beta:** This feature is in beta. The API is stable enough for production use, but some details may change. See [known limitations](#known-limitations) for current gaps.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable. See [known limitations](#known-limitations) for current gaps.
 
 Workers handle background processing outside the request-response cycle. Workflow step execution, cron-based scheduling, and long-running tool calls all run in workers, keeping the API responsive.
 

package/.docs/docs/deployment/workflow-runners.md

@@ -8,10 +8,10 @@ Mastra [workflows](https://mastra.ai/docs/workflows/overview) can be executed us
 
 Inngest is a developer platform for running background workflows without managing infrastructure. Mastra workflows can be deployed to Inngest, which provides step memoization, automatic retries, real-time monitoring, and suspend/resume capabilities.
 
-Visit the [Inngest deployment guide](https://mastra.ai/guides/deployment/inngest) for setup instructions and the [Inngest workflow example](https://github.com/mastra-ai/mastra/tree/main/examples/inngest) for a complete implementation.
+Visit the [Inngest deployment guide](https://mastra.ai/integrations/deploy/inngest) for setup instructions and the [Inngest workflow example](https://github.com/mastra-ai/mastra/tree/main/examples/inngest) for a complete implementation.
 
 ## Temporal
 
 Temporal is a durable execution platform for orchestrating long-running workflows. Mastra workflows can run on Temporal workers, with each `createStep` mapped to a Temporal activity for automatic retries and durable state.
 
-The `@mastra/temporal` package is experimental and not ready for production use. Visit the [Temporal deployment guide](https://mastra.ai/guides/deployment/temporal) for setup instructions.
+The `@mastra/temporal` package is experimental and not ready for production use. Visit the [Temporal deployment guide](https://mastra.ai/integrations/deploy/temporal) for setup instructions.

package/.docs/docs/getting-started/develop.md

@@ -138,7 +138,7 @@ See the [project structure reference](https://mastra.ai/reference/project-struct
 
 ## File-based agents
 
-> **Beta:** File-based agents are in beta and may change before they're stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 >
 > File-based discovery only runs through `mastra dev` or `mastra build`. If your app imports `mastra` directly, including through a web framework or server adapter, file-based agents aren't discovered. Register those agents in code or run Mastra as a separate server.
 

package/.docs/docs/harness/agent-controller.md

@@ -2,7 +2,7 @@
 
 # AgentController
 
-> **Beta:** The [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class) feature is in beta stage and subject to breaking changes in minor versions until it graduates from its beta status.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 `AgentController` is a shared runtime host for interactive agent applications. It coordinates modes, models, storage, workspaces, tool approvals, subagents, and channels. Each user or active task works through an isolated [`Session`](https://mastra.ai/reference/agent-controller/session).
 
@@ -343,11 +343,52 @@ Point each platform webhook at the controller-specific route:
 
 Each external chat thread maps to one controller Session and Mastra thread. By default, new sessions use a resource ID derived from the adapter's chat-thread ID, prefixed with `channel:`. Use `resolveResourceId` to map direct messages to an existing application user or choose another memory owner. The callback only affects new threads; an existing thread keeps its stored resource ID.
 
-Channel sessions are created by the controller rather than by your code, so `onSessionStart` is where you configure them. It runs once per session, after the session is bound to its mapped thread and before the first message is handled. Use it to apply a model, memory settings, or session state that a channel session would otherwise miss. Later messages in the same thread reuse the session and don't call it again. Errors are logged and swallowed so a session that can't be configured still answers the message.
+Channel sessions are created by the controller rather than by your code, so `onSessionStart` is where you configure them. It runs once per session, after the session is bound to its mapped thread and before the first message is handled. A channel session starts with controller defaults, so this is where you set its model and memory settings. Later messages in the same thread reuse the session and don't call it again. Errors are logged and swallowed so a session that can't be configured still answers the message.
+
+### Authorize and route channel sessions
+
+`onSessionStart` runs after the session exists and swallows errors, so it can't refuse a request. Use `resolveSession` when your host decides whether a session may exist. It replaces the built-in session creation and runs before any session exists. Throwing refuses the request before the controller creates a session or calls the model. Mastra logs the refusal and leaves the chat thread silent, so your authorization message never reaches the channel.
+
+```typescript
+channels: {
+  adapters: { slack: createSlackAdapter() },
+  resolveSession: async ({ controller, thread, requestContext }) => {
+    const install = await installs.authorize(requestContext.get('teamId'))
+
+    return controller.createSession({
+      resourceId: thread.resourceId,
+      scope: install.id,
+      ownerId: controller.id,
+      requestContext,
+    })
+  },
+}
+```
+
+Create the session under `thread.resourceId`. A session can only bind threads it owns, so use `resolveResourceId` if you want a different owner for the mapped thread. Sessions are get-or-create per `resourceId` and `scope`, so pass `scope` when one thread needs separate sessions per install or principal.
+
+Failures that aren't refusals (a storage outage, a bug in your resolver's dependencies) still post an error to the thread, so a broken bot doesn't look like a silent one. If you need to tell them apart in your own code, a refusal is a `ChannelSessionRejectedError` with the original error as its `cause`.
+
+`resolveSession` also runs when a user answers an approval card, with that action's request context, so a shared install revalidates the person approving rather than trusting the person who sent the original message.
+
+### Handle stale approvals
+
+An approval gate lives in memory, so every approval answered after a restart is stale. Mastra never runs the tool for a stale action. Use `onStaleToolApproval` to settle the attempt the user answered, instead of dropping it:
+
+```typescript
+channels: {
+  adapters: { slack: createSlackAdapter() },
+  onStaleToolApproval: async ({ decision, toolCallId, runId, memory }) => {
+    await runs.markInterrupted({ runId, toolCallId, decision, threadId: memory.thread })
+  },
+}
+```
+
+`runId` is the run the approval card was rendered for, which is the attempt the user answered and the one you settle against after a restart. The session's own run is passed separately as `currentRunId`, and is usually `null` or a different run by then.
 
 Controller channel sessions and auto-approval state are held in memory, so use a long-lived server. Pending approvals and live Session state don't survive process restarts. Adapters that can't render approval controls automatically run tools without an approval prompt so the run doesn't remain suspended.
 
-See [Channels](https://mastra.ai/docs/capabilities/channels/overview) for adapter setup and platform-specific webhook configuration.
+See [Channels](https://mastra.ai/docs/capabilities/channels) for adapter setup and platform-specific webhook configuration.
 
 ## Connect a UI
 
@@ -373,4 +414,4 @@ Subscriptions are isolated by Session. Events from another Session on the same c
 - [Agents](https://mastra.ai/docs/agents/overview)
 - [Workspace](https://mastra.ai/docs/workspace/overview)
 - [Observational memory](https://mastra.ai/docs/memory/observational-memory)
-- [Channels](https://mastra.ai/docs/capabilities/channels/overview)
+- [Channels](https://mastra.ai/docs/capabilities/channels)

package/.docs/docs/harness/overview.md

@@ -4,12 +4,10 @@
 
 A harness lets an agent pursue long-running, complex goals while keeping its work durable, visible, and steerable. It preserves progress across retries and interruptions, while giving people and other systems a way to inspect progress, add context, approve actions, redirect the agent, or stop it.
 
-In Mastra, harness refers to a set of capabilities for managing an agent beyond a single uninterrupted run. You can adopt these capabilities individually or combine them as needed.
-
-[`AgentController`](https://mastra.ai/docs/harness/agent-controller) is a harness designed for interactive agent applications. It extends the base [`Agent`](https://mastra.ai/docs/agents/overview) loop with isolated sessions for each user or task, persistent threads and state, switchable modes and models, tool permissions and approvals, subagent orchestration, and streams for events and display state.
-
 Agent harnesses are useful wherever work continues over time. Common examples include coding agents that carry changes through CI and review, software factories that coordinate many tasks in parallel, SRE agents that adapt as incidents evolve, and go-to-market agents that respond as accounts, signals, and conversations change.
 
+In Mastra, harness refers to a set of capabilities for managing an agent beyond a single uninterrupted run. You can adopt these capabilities individually or combine them as needed.
+
 ## When to use a harness
 
 Choose a starting point based on what the agent needs. You may use one capability or several.