@mastra/mcp-docs-server 1.2.14-alpha.1 → 1.2.14-alpha.4

package/.docs/reference/workflows/workflow-methods/tool.md

@@ -0,0 +1,43 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# Workflow\.tool()
+
+The `.tool()` method adds a tool as a declarative step. The tool's own input and output schemas apply, so the previous step's output must satisfy the tool's input schema. Use `.map()` to transform the data if they don't match.
+
+Unlike wrapping a tool with `createStep()`, `.tool()` records a declarative entry in the workflow graph. This makes the workflow portable: the same graph can be serialized and persisted as a [stored workflow](https://mastra.ai/docs/workflows/stored-workflows).
+
+## Usage example
+
+```typescript
+workflow.tool(testTool).commit();
+```
+
+## Parameters
+
+**toolOrId** (`Tool | string`): A tool instance, or the ID of a tool registered on the Mastra instance. When passing an ID, the tool is resolved from the registry at execution time.
+
+**options** (`{ retries?: number, scorers?: DynamicArgument<MastraScorers>, metadata?: StepMetadata }`): Step-level retry count, scorers, and metadata for the tool step.
+
+**stepOptions** (`{ id?: string }`): The step's call-site ID within the workflow. Defaults to the tool's ID. Set this when the same tool appears more than once in one workflow.
+
+## Returns
+
+**workflow** (`Workflow`): The workflow instance for method chaining
+
+## Referencing a tool by ID
+
+Pass a string to reference a registered tool without importing it. The tool must be registered on the Mastra instance when the workflow runs:
+
+```typescript
+workflow.tool("lookup-customer", { retries: 2 }).commit();
+```
+
+## Persisting tool steps
+
+Workflows built with `.tool()` serialize to the same declarative entries that [stored workflows](https://mastra.ai/docs/workflows/stored-workflows) use. Only `retries` and `metadata` round-trip through storage. A function-valued `scorers` option throws an error when the workflow is stored.
+
+## Related
+
+- [Agents and Tools](https://mastra.ai/docs/workflows/agents-and-tools)
+- [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows)
+- [Workflow.agent()](https://mastra.ai/reference/workflows/workflow-methods/agent)

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.4
+
+### Patch Changes
+
+- Updated dependencies [[`810c7e7`](https://github.com/mastra-ai/mastra/commit/810c7e74929989d8b8b5db52cd3af22cd0998af4), [`f9f9884`](https://github.com/mastra-ai/mastra/commit/f9f98848ee194dc71a787a709ec430b065cdc41b), [`e0904dc`](https://github.com/mastra-ai/mastra/commit/e0904dc538792e54e1806b70172e5900ac49bff4), [`64d6781`](https://github.com/mastra-ai/mastra/commit/64d67814bccddd314f7e09643243821e57cb87b6), [`c848e65`](https://github.com/mastra-ai/mastra/commit/c848e655a64ff10331a8ceafafe7f18e70a0f092), [`0494489`](https://github.com/mastra-ai/mastra/commit/049448906e4c3d2d615bbe865b073a0d890ddb7c), [`8d1aeb8`](https://github.com/mastra-ai/mastra/commit/8d1aeb8acf7c20c4bb8e4d8e4bdc6569c83ac561), [`83065bf`](https://github.com/mastra-ai/mastra/commit/83065bfee9e47c3c6f09132a9034501f6cfb69cf), [`01b162f`](https://github.com/mastra-ai/mastra/commit/01b162fe435295881aa7ea55f1759407ad5175ad)]:
+  - @mastra/core@1.57.0-alpha.2
+
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.14-alpha.1",
+  "version": "1.2.14-alpha.4",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
     "@mastra/mcp": "^1.15.1",
-    "@mastra/core": "1.56.1-alpha.0"
+    "@mastra/core": "1.57.0-alpha.2"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.14",
@@ -45,9 +45,9 @@
     "tsx": "^4.23.1",
     "typescript": "^6.0.3",
     "vitest": "4.1.10",
-    "@internal/types-builder": "0.0.95",
     "@internal/lint": "0.0.120",
-    "@mastra/core": "1.56.1-alpha.0"
+    "@internal/types-builder": "0.0.95",
+    "@mastra/core": "1.57.0-alpha.2"
   },
   "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)

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

@@ -1,147 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Modes
-
-Modes define the different behaviors an AgentController can run. Each mode layers its own instructions and tool overrides on top of a shared backing agent, so the same agent can act as a planner in one mode and an executor in another. The AgentController keeps exactly one mode active at a time and carries the thread and state across switches, plus handles the transition between them.
-
-Every AgentController needs at least one mode, the `modes` array is required, and the AgentController throws at construction if it's empty. A single-purpose AgentController still defines one mode. Multiple modes are how you give a session more than one behavior to switch between.
-
-A mode supplies three things that change how the agent behaves:
-
-- **Instructions**: layered on top of the backing agent's own instructions while the mode is active.
-- **Tools**: either replacing or adding to the backing agent's tools (see [Mode tool overrides](#mode-tool-overrides)).
-- **Model**: an optional `defaultModelId` to bootstrap model selection when the session enters the mode.
-
-Because every mode shares the same backing agent, thread, and state, switching modes changes how the agent behaves without losing conversation context.
-
-## Quickstart
-
-Import the `AgentController` class and create a new instance with your agent and modes:
-
-```typescript
-import { AgentController } from '@mastra/core/agent-controller'
-import { myAgent } from './agents'
-
-const agentController = new AgentController({
-  id: 'multi-mode',
-  agent: myAgent,
-  modes: [
-    {
-      id: 'plan',
-      name: 'Plan',
-      metadata: { default: true },
-      instructions: 'Reason about the task before making changes.',
-    },
-    { id: 'build', name: 'Build', instructions: 'Implement the approved plan.' },
-  ],
-})
-
-await agentController.init()
-```
-
-## Defining modes
-
-Each mode requires an `id`. When a top-level `agent` is provided, modes layer instructions and tool overrides on the shared agent. Each mode can also specify a `defaultModelId` to bootstrap model selection:
-
-```typescript
-import { AgentController } from '@mastra/core/agent-controller'
-
-const agentController = new AgentController({
-  id: 'multi-mode',
-  agent: myAgent,
-  modes: [
-    {
-      id: 'plan',
-      name: 'Plan',
-      metadata: { default: true },
-      defaultModelId: 'anthropic/claude-sonnet-4-6',
-      instructions: 'Reason about the task before making changes.',
-    },
-    {
-      id: 'build',
-      name: 'Build',
-      defaultModelId: 'anthropic/claude-sonnet-4-6',
-      instructions: 'Implement the approved plan.',
-    },
-  ],
-})
-```
-
-### Mode tool overrides
-
-Modes support two strategies for tool configuration. Use `tools` to replace the backing agent's tools entirely, or `additionalTools` to layer extra tools on top:
-
-```typescript
-// Replace — agent sees only these tools in plan mode
-const planMode = { id: 'plan', tools: { planTool } }
-
-// Augment — agent keeps its own tools plus these
-const buildMode = { id: 'build', additionalTools: { deployTool } }
-```
-
-You can't set both `tools` and `additionalTools` on the same mode.
-
-### Restricting tool visibility
-
-`tools` and `additionalTools` control which tools are **added** to a mode's run, they don't hide the backing agent's own tools. To restrict which of those tools the model can actually see and call, set `availableTools`:
-
-```typescript
-const reviewMode = {
-  id: 'review',
-  name: 'Review',
-  // Only these tools are visible to the model in this mode.
-  availableTools: ['view', 'find_files', 'search_content'],
-}
-```
-
-`availableTools` is a per-mode visibility allowlist that matches each tool by its final exposed name:
-
-- **`undefined`** (default): no mode-level restriction: every tool is visible.
-- **`[]`**: no tools are available for this mode.
-- A denied tool stays hidden even when the list includes it. Per-tool and per-category `deny` rules in your permission config always take precedence.
-
-Workspace tools use the same list as every other tool, reference them by their exposed names (`view`, `write_file`, `find_files`, etc.). Visibility is enforced at LLM-call time, so the model never sees, and can't attempt to call, a tool outside the allowlist.
-
-### Mode transitions
-
-A mode can declare a `transitionsTo` target. When the `submit_plan` built-in tool runs in that mode, the AgentController transitions to the target mode on approval:
-
-```typescript
-const planMode = {
-  id: 'plan',
-  name: 'Plan',
-  transitionsTo: 'build',
-  instructions: 'Reason about the task and submit a plan.',
-}
-```
-
-On plan approval, the AgentController automatically switches to `build` mode. On rejection, the agent remains in `plan` mode to revise.
-
-## Switching modes
-
-The active mode lives on the Session, so call `agentController.session.mode.switch()` to change it. The switch aborts any in-progress generation and saves the current model to the outgoing mode, plus emits a `mode_changed` event. It then resolves the incoming mode's model and, when one resolves, applies it and emits a `model_changed` event:
-
-```typescript
-await agentController.session.mode.switch({ modeId: 'build' })
-```
-
-## Querying modes
-
-The AgentController exposes the full mode catalog, while the Session tracks which mode is active. Use `agentController.listModes()` to read every configured mode, `agentController.session.mode.get()` for the active mode ID, and `agentController.session.mode.resolve()` for the active mode's full definition:
-
-```typescript
-// List all configured modes
-const modes = agentController.listModes()
-
-// Get the current mode ID
-const modeId = agentController.session.mode.get()
-
-// Get the full mode object
-const mode = agentController.session.mode.resolve()
-```
-
-## Related
-
-- [AgentController overview](https://mastra.ai/docs/agent-controller/overview)
-- [Threads and state](https://mastra.ai/docs/agent-controller/threads-and-state)
-- [API reference](https://mastra.ai/reference/agent-controller/agent-controller-class)

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

@@ -1,136 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# AgentController overview
-
-> **Beta:** The `AgentController` feature is in beta stage and subject to breaking changes in minor versions until it graduates from its beta status.
-
-The AgentController is a session controller for building interactive agent applications.
-
-It handles the runtime concerns between your UI and the agent loop. These include conversation threads, mode switches, and persistent state. It also gates tool execution with approvals and coordinates subagents. You can focus on what your agent does rather than how to wire it together.
-
-An AgentController exposes a [`Session`](https://mastra.ai/docs/agent-controller/session), the per-conversation runtime state that tracks the active mode, model, thread binding, permission grants, follow-up queue, and token usage. The AgentController is the shared host. The Session is the conversation running inside it. In a multi-user host, the same AgentController can back many Sessions at once.
-
-[Mastra Code](https://code.mastra.ai/) is the flagship AgentController implementation. It's a terminal-based coding agent with multi-model support, persistent conversations, and plan-then-execute workflows.
-
-## What you can build
-
-The AgentController gives you the runtime pieces to release interactive agent applications. Each outcome below maps to a capability you can use today:
-
-- **Resume a conversation exactly where the user left off.** Persistent [threads and state](https://mastra.ai/docs/agent-controller/threads-and-state) reload the active mode, model, and progress across restarts, so a coding agent or assistant picks up mid-task instead of starting over.
-- **Gate destructive actions behind human approval.** [Tool approvals and permission policies](https://mastra.ai/docs/agent-controller/tool-approvals) let you require confirmation for risky operations like file writes or deployments, while trusted tools run automatically.
-- **Move a task through distinct phases without losing context.** [Modes](https://mastra.ai/docs/agent-controller/modes) switch the agent's instructions, tools, and model on the same thread, so you can build a plan-then-execute coding agent or a research-then-draft assistant.
-- **Let users pick the right model for each step.** Per-mode [model management](https://mastra.ai/reference/agent-controller/agent-controller-class) switches models at runtime and tracks usage, which powers copilot UIs where users trade speed for capability.
-- **Delegate focused work to child agents.** [Subagents](https://mastra.ai/docs/agent-controller/subagents) run subtasks with constrained tools and can fork the parent conversation, so a research mode can spin off web search or code review without polluting the main thread.
-- **Drive a live UI from agent activity.** The [event system](https://mastra.ai/docs/agent-controller/session) emits typed events and coalesced display snapshots, so your TUI or web app reflects message updates, mode changes, and pending approvals in real time.
-- **Run long-lived autonomous agents.** Structured task lists, interval handlers, and observational memory keep background task runners on track and let them learn across threads.
-
-## When to use the AgentController
-
-Use the AgentController when your application needs:
-
-- Multiple agent modes that share one conversation thread (e.g., plan → build → review)
-- A control layer between your UI and the agent loop (model switching, state persistence, thread management)
-- Tool approval flows and permission policies for human-in-the-loop gating
-- Subagent orchestration to delegate focused subtasks with constrained tools
-- Session continuity with persistent threads, state, and observational memory across restarts
-
-You could assemble all of this yourself on top of the [Agent class](https://mastra.ai/docs/agents/overview), which exposes the full agent loop, tools, and memory. The AgentController provides opinionated defaults for an ongoing session where the agent acts as a collaborator rather than a one-shot endpoint. Reach for the Agent class directly when you want full control or a request-response call. Reach for the AgentController when you want the collaborative-session model without building the runtime around it.
-
-## Key capabilities
-
-- **Session**: Per-conversation state: active thread, mode, model, grants, follow-ups, token usage, and the display snapshot: accessed through `agentController.session`. See [Session](https://mastra.ai/docs/agent-controller/session).
-- **Modes**: Define distinct agent personalities (instructions, tools, model) and switch between them without losing conversation context. See [Modes](https://mastra.ai/docs/agent-controller/modes).
-- **Threads and state**: Persist conversations and structured state across sessions, users, and mode switches. See [Threads and state](https://mastra.ai/docs/agent-controller/threads-and-state).
-- **Subagents**: Spawn focused child agents with constrained tools for subtasks, optionally forking the parent conversation. See [Subagents](https://mastra.ai/docs/agent-controller/subagents).
-- **Tool approvals and permissions**: Configure which tools require user confirmation and grant session-wide exceptions, plus handle interactive tool suspension. See [Tool approvals](https://mastra.ai/docs/agent-controller/tool-approvals).
-- **Model management**: Switch models per-mode at runtime, track usage, and resolve gateway-backed models through Mastra's [model router](https://mastra.ai/models).
-- **Follow-ups and steering**: Queue messages while the agent is running, or inject mid-stream instructions to redirect the agent. Built on [signals](https://mastra.ai/docs/long-running-agents/signals).
-- **Event system**: Subscribe to typed events (message updates, mode changes, tool approvals) or coalesced `AgentControllerDisplayState` snapshots to drive your UI. See [Events](https://mastra.ai/reference/agent-controller/agent-controller-class).
-- **Observational memory**: Automatic summarization and reflection across threads for long-running agent sessions. See [Observational memory](https://mastra.ai/docs/memory/observational-memory).
-
-## Quickstart
-
-Import the `AgentController` class and create a new instance with an agent, storage backend, and modes:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { AgentController } from '@mastra/core/agent-controller'
-import { LibSQLStore } from '@mastra/libsql'
-
-const agent = new Agent({
-  id: 'assistant',
-  name: 'assistant',
-  instructions: 'Help the user plan and complete tasks.',
-  model: 'openai/gpt-5.6-sol',
-})
-
-const agentController = new AgentController({
-  id: 'my-agent',
-  agent,
-  storage: new LibSQLStore({ id: 'agent-storage', 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.' },
-  ],
-})
-
-agentController.subscribe(event => {
-  if (event.type === 'message_update') {
-    console.log(event.message)
-  }
-})
-
-await agentController.init()
-await agentController.selectOrCreateThread()
-await agentController.sendMessage({ content: 'Hello!' })
-```
-
-Visit the [AgentController reference](https://mastra.ai/reference/agent-controller/agent-controller-class) for the full constructor parameters and method signatures.
-
-## Architecture
-
-The AgentController sits between your application layer and the underlying agent loop:
-
-```text
-┌───────────────────────────────────────┐
-│         Your App (TUI/Web/API)        │
-└───────────────────────────────────────┘
-      │  commands              ▲  events
-      ▼                        │
-┌───────────────────────────────────────┐
-│            AgentController             │
-│ Config · storage · threads            │
-│ permissions · subagents · events      │
-│                                       │
-│  ┌─────────────────────────────────┐  │
-│  │     agentController.session     │  │
-│  │ identity · thread · mode        │  │
-│  │ model · run · grants            │  │
-│  │ display state                   │  │
-│  └─────────────────────────────────┘  │
-└───────────────────────────────────────┘
-                   │
-                   ▼
-┌───────────────────────────────────────┐
-│         Agent + Memory + Tools        │
-└───────────────────────────────────────┘
-```
-
-Your app sends commands, send a message, switch mode, approve a tool call, and receives typed events such as `message_update` and `tool_approval_required`.
-
-The AgentController manages the lifecycle internally. It persists threads and routes requests to the correct mode agent. It also enforces permissions and emits events as state changes.
-
-## Next steps
-
-- [Session](https://mastra.ai/docs/agent-controller/session): The per-conversation state on an AgentController
-- [Modes](https://mastra.ai/docs/agent-controller/modes): Define and switch between agent personalities
-- [Threads and state](https://mastra.ai/docs/agent-controller/threads-and-state): Manage persistent conversations
-- [Subagents](https://mastra.ai/docs/agent-controller/subagents): Delegate focused subtasks
-- [Tool approvals and permissions](https://mastra.ai/docs/agent-controller/tool-approvals): Human-in-the-loop gating
-- [API reference](https://mastra.ai/reference/agent-controller/agent-controller-class): Full constructor and method docs
-- 📹 [Mastra AgentController harness workshop](https://www.youtube.com/watch?v=tV1pSleP-LM)