@mastra/mcp-docs-server 1.2.13 → 1.2.14-alpha.3

package/.docs/reference/agents/network.md

@@ -4,7 +4,7 @@
 
 The `.network()` method enables multi-agent collaboration and routing. This method accepts messages and optional execution options.
 
-> **Deprecated:** The `.network()` primitive has been deprecated and will be removed in a future major release. Use [supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) with `agent.stream()` or `agent.generate()` instead. See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
+> **Deprecated:** The `.network()` primitive has been deprecated and will be removed in a future major release. Use [supervisor agents](https://mastra.ai/docs/capabilities/subagents) with `agent.stream()` or `agent.generate()` instead. See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
 
 ## Usage example
 

package/.docs/reference/ai-sdk/handle-network-stream.md

@@ -2,7 +2,7 @@
 
 # handleNetworkStream()
 
-> **Deprecated:** Agent networks are deprecated and will be removed in a future release. Use [supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) with `agent.stream()` or `agent.generate()` instead. See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
+> **Deprecated:** Agent networks are deprecated and will be removed in a future release. Use [supervisor agents](https://mastra.ai/docs/capabilities/subagents) with `agent.stream()` or `agent.generate()` instead. See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
 
 Framework-agnostic handler for streaming network execution in AI SDK-compatible format. Use this function directly when you need to handle network streaming outside Hono or Mastra's own [apiRoutes](https://mastra.ai/docs/server/custom-api-routes) feature.
 

package/.docs/reference/ai-sdk/network-route.md

@@ -2,7 +2,7 @@
 
 # networkRoute()
 
-> **Deprecated:** Agent networks are deprecated and will be removed in a future release. Use [supervisor agents](https://mastra.ai/docs/agents/supervisor-agents) with `agent.stream()` or `agent.generate()` instead. See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
+> **Deprecated:** Agent networks are deprecated and will be removed in a future release. Use [supervisor agents](https://mastra.ai/docs/capabilities/subagents) with `agent.stream()` or `agent.generate()` instead. See the [migration guide](https://mastra.ai/guides/migrations/network-to-supervisor) to upgrade.
 
 Creates a network route handler for streaming network execution using the AI SDK format. This function registers an HTTP `POST` endpoint that accepts messages, executes an agent network, and streams the response back to the client in AI SDK-compatible format. Agent networks allow a routing agent to delegate tasks to other agents. You have to use it inside a [custom API route](https://mastra.ai/docs/server/custom-api-routes).
 

package/.docs/reference/cli/create-mastra.md

@@ -195,7 +195,7 @@ Invalid input is rejected before templates are fetched or files are created.
 
 **-l, --llm \<provider>** (`string`): Managed agent-harness provider: openai, anthropic, google, or xai.
 
-**-k, --llm-api-key \<key>** (`string`): Write the selected provider API key to the generated .env file.
+**-k, --llm-api-key \<key>** (`string`): Write the selected provider API key to the generated .env file when automatic provider setup succeeds.
 
 **--no-skills** (`boolean`): Skip automatic Mastra skills installation.
 

package/.docs/reference/editor/versioning.md

@@ -54,7 +54,7 @@ See the [Client SDK agents reference](https://mastra.ai/reference/client-js/agen
 
 ## Sub-agent versioning
 
-Version overrides propagate through [supervisor-agent delegation](https://mastra.ai/docs/agents/supervisor-agents) in request context. Define selectors at three levels:
+Version overrides propagate through [supervisor-agent delegation](https://mastra.ai/docs/capabilities/subagents) in request context. Define selectors at three levels:
 
 1. `Mastra` instance `versions`: Defaults for every invocation
 2. Server request-body `versions`: Per-request values added to request context

package/.docs/reference/evals/rubric.md

@@ -111,5 +111,5 @@ The `reason` summarizes the result and lists each criterion with its verdict, so
 ## Related
 
 - [isTaskComplete on stream()](https://mastra.ai/reference/streaming/agents/stream)
-- [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents)
+- [Supervisor agents](https://mastra.ai/docs/capabilities/subagents)
 - [createScorer](https://mastra.ai/reference/evals/create-scorer)

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

@@ -4,7 +4,7 @@
 
 Mastra configures [observability](https://mastra.ai/docs/observability/overview) from an `observability.ts` file directly under `src/mastra/`. The file default-exports an `Observability` instance that sets up tracing, logging, metrics, and feedback for the project.
 
-Use this page for the file-based convention. For the signal model, exporters, storage, and multi-config setup, see [Observability overview](https://mastra.ai/docs/observability/overview) and [Observability configuration](https://mastra.ai/docs/observability/config).
+Use this page for the file-based convention. For the signal model, exporters, storage, and multi-config setup, see the [observability overview](https://mastra.ai/docs/observability/overview) and [observability configuration](https://mastra.ai/docs/observability/overview).
 
 ## Quickstart
 
@@ -25,7 +25,7 @@ export default new Observability({
 
 ## Observability and storage
 
-`observability.ts` configures which signals are collected and where they're exported. [`storage.ts`](https://mastra.ai/reference/file-based-agents/storage) configures the project store that can persist observability records. For storage support by signal, see [Observability storage](https://mastra.ai/docs/observability/storage).
+`observability.ts` configures which signals are collected and where they're exported. [`storage.ts`](https://mastra.ai/reference/file-based-agents/storage) configures the project store that can persist observability records. For storage support by signal, see [observability signal support](https://mastra.ai/docs/observability/overview).
 
 ## Precedence with code
 

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

@@ -23,7 +23,7 @@ Mastra registers the store before file-based agents and workflows, so storage-de
 
 ## Production backends
 
-`storage.ts` can export any Mastra storage adapter, such as LibSQL, PostgreSQL, or MongoDB. For setup patterns, provider support, and schema details, see [storage overview](https://mastra.ai/docs/storage/overview), [observability storage](https://mastra.ai/docs/observability/storage), and the [storage reference](https://mastra.ai/reference/storage/overview).
+`storage.ts` can export any Mastra storage adapter, such as LibSQL, PostgreSQL, or MongoDB. For setup patterns, provider support, and schema details, see [storage overview](https://mastra.ai/docs/storage/overview), [observability signal support](https://mastra.ai/docs/observability/overview), and the [storage reference](https://mastra.ai/reference/storage/overview).
 
 ## Precedence with code
 

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

@@ -4,7 +4,7 @@
 
 A file-based agent can declare **subagents**, specialist child agents it delegates to. The parent model sees each subagent as a delegation tool named after the subagent directory and calls that tool to hand off a task. The subagent's result returns to the parent conversation.
 
-Use this page for the file-based convention. For broader delegation patterns, hooks, memory isolation, tool approval propagation, and scoring, see [Supervisor agents](https://mastra.ai/docs/agents/supervisor-agents).
+Use this page for the file-based convention. For broader delegation patterns, hooks, memory isolation, tool approval propagation, and scoring, see [Supervisor agents](https://mastra.ai/docs/capabilities/subagents).
 
 ## Quickstart
 

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

@@ -51,7 +51,7 @@ The file-based convention only controls where the tool lives and how it's regist
 - Use `toModelOutput` when the model should see a different shape than the raw value returned from `execute`.
 - Use `requireApproval` when a tool needs human confirmation before execution.
 
-See the [`createTool()` reference](https://mastra.ai/reference/tools/create-tool) for all options and [tool approval](https://mastra.ai/docs/agent-controller/tool-approvals) for the approval flow.
+See the [`createTool()` reference](https://mastra.ai/reference/tools/create-tool) for all options and [tool approval](https://mastra.ai/docs/harness/agent-controller) for the approval flow.
 
 ## Runtime boundary
 

package/.docs/reference/observability/tracing/configuration.md

@@ -196,7 +196,7 @@ Shuts down all observability instances and clears the registry.
 
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview): Concepts and usage guide
 - [Sampling Strategies](https://mastra.ai/docs/observability/tracing/overview): Sampling configuration details
-- [Multi-Config Setup](https://mastra.ai/docs/observability/config): Using multiple configurations
+- [Multi-Config Setup](https://mastra.ai/docs/observability/overview): Using multiple configurations
 
 ### Reference
 

package/.docs/reference/observability/tracing/exporters/confident-ai.md

@@ -0,0 +1,138 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# DeepEvalExporter
+
+Sends Tracing data to [Confident AI](https://www.confident-ai.com/) for evaluation and observability. Exported by `@mastra/deepeval`, which builds on the DeepEval SDK.
+
+See [Confident AI exporter](https://mastra.ai/docs/observability/integrations/exporters/confident-ai) for setup and usage.
+
+## Constructor
+
+```typescript
+new DeepEvalExporter(config?: DeepEvalExporterConfig)
+```
+
+## `DeepEvalExporterConfig`
+
+```typescript
+interface DeepEvalExporterConfig extends BaseExporterConfig {
+  apiKey?: string
+  environment?: string
+  name?: string
+  tags?: string[]
+  metadata?: Record<string, any>
+  threadId?: string
+  userId?: string
+  testCaseId?: string
+  turnId?: string
+  metricCollection?: string
+  traceMetricCollection?: string
+  llmMetricCollection?: string
+  agentMetricCollection?: string
+  toolMetricCollectionMap?: Record<string, string>
+  prompt?: Prompt
+  debug?: boolean
+  traceCaptureSink?: (trace: Trace) => void
+}
+```
+
+Extends `BaseExporterConfig`, which includes:
+
+- `logger?: IMastraLogger` - Logger instance
+- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Log level (default: INFO)
+
+**apiKey** (`string`): Confident AI API key. Falls back to the CONFIDENT\_API\_KEY env var. The exporter disables itself when no key is found.
+
+**environment** (`string`): Trace environment. Falls back to CONFIDENT\_TRACE\_ENVIRONMENT, then 'development'.
+
+**name** (`string`): Trace name applied to every trace. Defaults to the Mastra serviceName.
+
+**tags** (`string[]`): Tags applied to every trace.
+
+**metadata** (`Record<string, any>`): Metadata applied to every trace.
+
+**threadId** (`string`): Thread ID applied to every trace. A threadId in the root span metadata overrides it per request.
+
+**userId** (`string`): User ID applied to every trace. A userId in the root span metadata overrides it per request.
+
+**testCaseId** (`string`): Test case ID applied to every trace. A testCaseId in the root span metadata overrides it per request.
+
+**turnId** (`string`): Turn ID applied to every trace. A turnId in the root span metadata overrides it per request.
+
+**metricCollection** (`string`): Trace-level metric collection.
+
+**traceMetricCollection** (`string`): Trace-level metric collection. Takes precedence over metricCollection.
+
+**llmMetricCollection** (`string`): Metric collection applied to LLM spans.
+
+**agentMetricCollection** (`string`): Metric collection applied to agent spans.
+
+**toolMetricCollectionMap** (`Record<string, string>`): Metric collection applied per tool name.
+
+**prompt** (`Prompt`): Confident AI managed prompt linkage attached to LLM spans.
+
+**debug** (`boolean`): Logs exporter configuration and export errors to the console.
+
+**traceCaptureSink** (`(trace: Trace) => void`): Receives completed traces locally instead of posting them to Confident AI. Use for offline evaluation.
+
+**logLevel** (`'debug' | 'info' | 'warn' | 'error'`): Logger level (default: 'info')
+
+## Methods
+
+### `exportTracingEvent`
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Exports a tracing event to Confident AI. Builds the trace tree from the Mastra span stream and posts the trace when the root span ends.
+
+### `flush`
+
+```typescript
+async flush(): Promise<void>
+```
+
+Waits for any in-flight trace posts to settle without shutting down the exporter.
+
+### `shutdown`
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Finalizes any open traces and flushes pending posts.
+
+## Usage
+
+### Zero-Config (using environment variables)
+
+```typescript
+import { DeepEvalExporter } from '@mastra/deepeval'
+
+// Reads from CONFIDENT_API_KEY, CONFIDENT_TRACE_ENVIRONMENT
+const exporter = new DeepEvalExporter()
+```
+
+### Explicit Configuration
+
+```typescript
+import { DeepEvalExporter } from '@mastra/deepeval'
+
+const exporter = new DeepEvalExporter({
+  apiKey: process.env.CONFIDENT_API_KEY,
+  environment: 'production',
+})
+```
+
+## Span type mapping
+
+| Mastra span type                                                       | Confident AI span type |
+| ---------------------------------------------------------------------- | ---------------------- |
+| `AGENT_RUN`, `WORKFLOW_RUN`                                            | `AGENT`                |
+| `MODEL_GENERATION`                                                     | `LLM`                  |
+| `TOOL_CALL`, `MCP_TOOL_CALL`, `PROVIDER_TOOL_CALL`, `CLIENT_TOOL_CALL` | `TOOL`                 |
+| `RAG_EMBEDDING`, `RAG_VECTOR_OPERATION`                                | `RETRIEVER`            |
+| All other exported span types                                          | `CUSTOM`               |
+
+Event spans (for example `MODEL_CHUNK`) are dropped.

package/.docs/reference/observability/tracing/interfaces.md

@@ -396,6 +396,14 @@ interface ModelGenerationAttributes {
   /** Model provider (e.g., 'openai', 'anthropic') */
   provider?: string
 
+  /**
+   * Definitions of the tools made available to the model for this generation
+   * (name, description, and JSON-schema parameters), captured once per
+   * generation. Per-step tool names live on MODEL_INFERENCE spans as
+   * `availableTools`.
+   */
+  tools?: ModelToolDefinition[]
+
   /** Type of result/output this model call produced */
   resultType?: 'tool_selection' | 'response_generation' | 'reasoning' | 'planning'
 
@@ -429,6 +437,27 @@ interface ModelGenerationAttributes {
 }
 ```
 
+### `ModelToolDefinition`
+
+Serialized definition of one tool made available to the model, attached to `MODEL_GENERATION` spans so observability exporters can surface tool schemas.
+
+```typescript
+interface ModelToolDefinition {
+  /** Tool type: 'function' for standard tools, or the provider tool type (e.g. 'provider-defined') */
+  type: string
+
+  name: string
+
+  description?: string
+
+  /** JSON schema of the tool's input parameters (function tools) */
+  parameters?: Record<string, unknown>
+
+  /** Provider tool id (e.g. 'anthropic.web_search_20250305') for provider-defined tools */
+  id?: string
+}
+```
+
 ### `ModelStepAttributes`
 
 Model Step attributes - for a single model execution within a generation.

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

@@ -291,6 +291,8 @@ provider.stopPolling()
 
 Handle an incoming webhook request. Override to parse the payload and match it to subscriptions. Then emit notification signals. See [`WebhookSignalProvider`](https://mastra.ai/reference/signals/webhook-signal-provider) for a ready-to-use implementation.
 
+Call this method from an application-defined HTTP endpoint after verifying the webhook request.
+
 ```typescript
 async handleWebhook(request) {
   const payload = request.body as { repo: string, event: string }

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

@@ -1660,7 +1660,7 @@ const server = new MCPServer({
 })
 ```
 
-Link a tool to its app resource by setting `_meta.ui.resourceUri` on the tool to the matching `ui://` URI. The server auto-normalizes this metadata when registering tools. Visit [MCP Apps](https://mastra.ai/docs/mcp/mcp-apps) for the full app bridge API and usage patterns.
+Link a tool to its app resource by setting `_meta.ui.resourceUri` on the tool to the matching `ui://` URI. The server auto-normalizes this metadata when registering tools. Visit [MCP Apps](https://mastra.ai/docs/mcp/overview) for the full app bridge API and usage patterns.
 
 ## Related information
 

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

@@ -90,4 +90,4 @@ Pass an object to `agent.resumeStream()`:
 - **Rejected with feedback:** The tool returns the feedback and asks the model to revise the plan and submit again.
 - **Rejected without feedback:** The tool tells the model to wait for the user's next message before revising.
 
-When used inside an [AgentController](https://mastra.ai/docs/agent-controller/overview), plan approval triggers an automatic mode switch from the planning mode to the default execution mode. See [Modes](https://mastra.ai/docs/agent-controller/modes) for details.
+When used inside an [AgentController](https://mastra.ai/docs/harness/agent-controller), plan approval switches from the current mode to the mode configured by `transitionsTo`. When no `transitionsTo` is configured, the controller switches to its resolved default mode. See [Modes](https://mastra.ai/docs/harness/agent-controller) for details.

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

@@ -143,14 +143,14 @@ const sandbox = new RailwaySandbox({
 
 Use one stable checkpoint name for each independent filesystem. Don't share a checkpoint name across unrelated sessions or projects.
 
-### Derived sandbox checkpoints
+### Cloned sandbox checkpoints
 
-Use `derive({ checkpointName })` when a configured `RailwaySandbox` acts as the template for a sandbox fleet:
+Use `clone({ checkpointName })` when a configured `RailwaySandbox` acts as the template for a sandbox fleet:
 
 ```typescript
 const template = new RailwaySandbox({ idleTimeoutMinutes: 30 })
 
-const sessionSandbox = template.derive({
+const sessionSandbox = template.clone({
   id: 'session-42',
   checkpointName: 'project-session-42',
 })
@@ -158,7 +158,7 @@ const sessionSandbox = template.derive({
 await sessionSandbox.start()
 ```
 
-A derived sandbox uses the checkpoint passed to `derive()`. If no override is passed, it inherits the template sandbox's `checkpointName`.
+A cloned sandbox uses the checkpoint passed to `clone()`. If no override is passed, it inherits the template sandbox's `checkpointName`.
 
 ### Streaming output
 
@@ -226,7 +226,7 @@ const result = await sandbox.executeCommand('cat', ['/tmp/state.txt'])
 
 **fork** (`(options?) => Promise<RailwaySandbox>`): Clone this running sandbox into a new, independent RailwaySandbox. The returned sandbox is already started and reattached to the forked Railway sandbox. Accepts optional id, idleTimeoutMinutes, networkIsolation, and env overrides. Throws SandboxNotReadyError if this sandbox has not been started.
 
-**derive** (`(options?) => RailwaySandbox`): Construct an unstarted sibling sandbox that inherits credentials and defaults. Accepts optional id, sandboxId, env, idleTimeoutMinutes, and checkpointName overrides. The derived sandbox uses options.checkpointName when set, otherwise it inherits the template checkpointName.
+**clone** (`(options?) => RailwaySandbox`): Construct an unstarted sibling sandbox that inherits credentials and defaults. Accepts optional id, sandboxId, env, idleTimeoutMinutes, and checkpointName overrides. The cloned sandbox uses options.checkpointName when set, otherwise it inherits the template checkpointName.
 
 ## Background processes
 

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 1.2.14-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [[`89200ba`](https://github.com/mastra-ai/mastra/commit/89200bafa05444bb7949b363ce7b743e29867561), [`c950138`](https://github.com/mastra-ai/mastra/commit/c950138e72e4f317a40187e3800588731ab790ce), [`063c8b2`](https://github.com/mastra-ai/mastra/commit/063c8b2eb14e4e5ca021779bc33e8c3c031c8604), [`f4e964c`](https://github.com/mastra-ai/mastra/commit/f4e964cad57057301d6bed5c55bcdd730175b941), [`1f7bbd7`](https://github.com/mastra-ai/mastra/commit/1f7bbd7785a8d230aad02454ecabeb4a0b2cc96f), [`e47ff36`](https://github.com/mastra-ai/mastra/commit/e47ff36945720f4ee4caa09f6e83514d7d188608), [`fb9a6ac`](https://github.com/mastra-ai/mastra/commit/fb9a6ac11c9560518742ece60b49d6b062845fd3), [`aa2cec8`](https://github.com/mastra-ai/mastra/commit/aa2cec8501f634d51c2f3ebfb3dd3aa7af8d2ca2), [`2adf8eb`](https://github.com/mastra-ai/mastra/commit/2adf8eb4a70ed2b6cff2dd39281496ea0e025fac), [`8264611`](https://github.com/mastra-ai/mastra/commit/8264611510e421b818bc7395dc2ae4d9c2d518b2), [`44fc98b`](https://github.com/mastra-ai/mastra/commit/44fc98b9d1242aa87a3ab44bdce9e9f12c44d8c9), [`0f2ef41`](https://github.com/mastra-ai/mastra/commit/0f2ef4118da022e4f30dac4e9856cc3a8c97671c)]:
+  - @mastra/core@1.57.0-alpha.1
+
+## 1.2.14-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [[`c8002da`](https://github.com/mastra-ai/mastra/commit/c8002da7775c468e2965b6ff5f82045450fa8cb9)]:
+  - @mastra/core@1.56.1-alpha.0
+
 ## 1.2.13
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.13",
+  "version": "1.2.14-alpha.3",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,7 +28,7 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.56.0",
+    "@mastra/core": "1.57.0-alpha.1",
     "@mastra/mcp": "^1.15.1"
   },
   "devDependencies": {
@@ -47,7 +47,7 @@
     "vitest": "4.1.10",
     "@internal/types-builder": "0.0.95",
     "@internal/lint": "0.0.120",
-    "@mastra/core": "1.56.0"
+    "@mastra/core": "1.57.0-alpha.1"
   },
   "homepage": "https://mastra.ai",
   "repository": {

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

@@ -1,111 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Channels
-
-Channels connect an AgentController to messaging platforms like Slack, Discord, and Telegram, so a controller-backed session runs inside a chat thread. Inbound platform messages route into a controller [`Session`](https://mastra.ai/docs/agent-controller/session), and the agent's output renders back to the platform with native streaming. The response can also include tool approval cards and typing status.
-
-AgentController channels use the same channel layer as [agent channels](https://mastra.ai/docs/capabilities/channels/overview). The adapters and configuration shape are shared. Both channel types also use the same rendering pipeline.
-
-Message routing differs by channel type. Agent channels route messages straight into the agent loop. With AgentController channels, messages enter a durable session that tracks the active mode, model, permission grants, and state across the whole conversation.
-
-## Configure a controller
-
-Pass a `channels` configuration to the AgentController constructor. It accepts the same shape as the [`Agent` channels option](https://mastra.ai/docs/capabilities/channels/overview):
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { AgentController } from '@mastra/core/agent-controller'
-import { createSlackAdapter } from '@chat-adapter/slack'
-import { LibSQLStore } from '@mastra/libsql'
-
-const agent = new Agent({
-  id: 'assistant',
-  name: 'assistant',
-  instructions: 'Help the user plan and complete tasks.',
-  model: 'anthropic/claude-sonnet-4-6',
-})
-
-export const agentController = new AgentController({
-  id: 'my-agent-controller',
-  agent,
-  storage: new LibSQLStore({ url: 'file:./data.db' }),
-  modes: [
-    {
-      id: 'plan',
-      name: 'Plan',
-      metadata: { default: true },
-      instructions: 'Reason about changes before making them.',
-    },
-    { id: 'build', name: 'Build', instructions: 'Implement the approved plan.' },
-  ],
-  channels: {
-    adapters: {
-      slack: createSlackAdapter(),
-    },
-  },
-})
-```
-
-Register the controller on the Mastra instance. Mastra registers the webhook routes and initializes the channel layer:
-
-```typescript
-import { Mastra } from '@mastra/core'
-import { LibSQLStore } from '@mastra/libsql'
-import { agentController } from './agent-controller'
-
-export const mastra = new Mastra({
-  agentControllers: { agentController },
-  storage: new LibSQLStore({
-    url: process.env.DATABASE_URL,
-  }),
-})
-```
-
-## Webhook routes
-
-Controller channel webhooks follow the same pattern as agent channels, under an `agent-controllers` path:
-
-```text
-/api/agent-controllers/<CONTROLLER_ID>/channels/<PLATFORM>/webhook
-```
-
-For example, a Slack adapter on a controller with the `my-agent-controller` ID uses:
-
-```text
-/api/agent-controllers/my-agent-controller/channels/slack/webhook
-```
-
-Point the platform's webhook, event, or interactions URL to this path. See [Webhook routes](https://mastra.ai/docs/capabilities/channels/overview) for local tunneling and platform setup.
-
-## One session per chat thread
-
-Each chat thread maps to one durable controller session. The first message in a Slack or Discord thread creates a Mastra thread and a controller session keyed to it. Every later message in that chat thread reuses both. The session carries the active mode, model, permission grants, and state for the life of the conversation, as with a session driven from a terminal or web UI.
-
-By default the session key derives from the platform and the external thread ID (`channel:slack:<THREAD_ID>`). Pass `resolveResourceId` in the channels configuration to control the mapping yourself.
-
-Avoid mapping multiple active chat threads to one session. A session works on one Mastra thread at a time, and a message arriving from a different chat thread rebinds the session to that thread, which cancels any run still in flight on the previous one.
-
-## Tool approvals
-
-Tools that require approval render as interactive cards with Approve and Deny buttons, the same as [agent channel tool approvals](https://mastra.ai/docs/capabilities/channels/overview). The controller run pauses at the session's approval gate until a user acts on the card, then resumes and streams the continuation back to the thread.
-
-These behaviors follow from routing approvals through the session:
-
-- A new message in the thread while an approval is pending declines that approval, the same as sending a new message in a terminal session. The new message supersedes the pending ask.
-- On adapters that can't render approval buttons (`toolDisplay: 'text'`), tools run without approval prompts so runs can't stall on a card nobody can act on.
-
-See [Tool approvals and permissions](https://mastra.ai/docs/agent-controller/tool-approvals) for policies, categories, and session grants.
-
-## Limits
-
-- Adapters can be constructed manually with the same configuration. The managed connect flow (`mastra.channels.slack.connect(...)`) also supports controller-owned installations: call it with an options object (`connect({ id, name })`) to connect a controller that has no registered agent. Adapters without controller support must still be constructed manually.
-- Controller sessions are in-memory objects, so channels-backed controllers need a long-lived server. Serverless deployment isn't supported for controller channels. Agent channels support it as described in [Serverless deployment](https://mastra.ai/docs/capabilities/channels/overview).
-- Pending tool approvals don't survive a server restart. An approval card acted on after a restart is ignored as stale.
-- Mode switching from chat (for example, a `/mode` slash command) isn't available yet.
-
-## Related
-
-- [Channels overview](https://mastra.ai/docs/capabilities/channels/overview)
-- [Session](https://mastra.ai/docs/agent-controller/session)
-- [Tool approvals and permissions](https://mastra.ai/docs/agent-controller/tool-approvals)
-- [Channels reference](https://mastra.ai/reference/agents/channels)