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

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

@@ -1,161 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Session
-
-A [`Session`](https://mastra.ai/reference/agent-controller/session) holds the live state of an AgentController. It identifies the user and active thread, along with the selected mode and model. It also stores permission grants, queued follow-ups, token usage, application state, and the display snapshot.
-
-You reach it through `agentController.session`.
-
-## What the Session tracks
-
-The Session is the live state of a single user's interaction with the AgentController.
-
-It answers who owns the session and which thread is bound. It also identifies the selected mode and model while tracking approvals, queued or running work, application state, and the snapshot to render.
-
-A session has one active thread at a time but can list, switch between, and clone many threads over its lifetime. Anything that describes the current state lives here. The AgentController owns the shared infrastructure every session runs on.
-
-Each session has its own identity and state. One AgentController can therefore serve many users at once, with a separate `resourceId` and Session preventing mode, grant, or active-thread data from leaking between users.
-
-Calling `createSession` with the same `resourceId` returns the existing session (get-or-create), so a resource always resumes its own session.
-
-The rest of this page walks through the Session's state. Each part is a focused sub-object on `agentController.session`:
-
-- **Who and where**: [Identity](#identity) sets the stable session `id`, `ownerId`, and resource the session belongs to, and [Thread](#thread) tracks the currently bound thread.
-- **How the agent behaves**: [Mode and model](#mode-and-model) controls which agent profile and model are active, and [Permission grants](#permission-grants) records what the user has approved to run without prompting.
-- **What's happening right now**: [Run state](#run-state) reflects the in-flight generation, and [Follow-ups](#follow-ups) holds messages queued to send when it finishes.
-- **What you store and render**: [State](#state) holds your application's structured data, and [Display state](#display-state) is the single snapshot your UI renders from.
-
-The AgentController performs actions that change this state, switching threads, modes, or models, because those operations coordinate shared infrastructure and emit events. The Session is where you read the result. The sections below note this split where it matters.
-
-## Identity
-
-`session.identity` holds three stable identifiers for the conversation: a session `id`, an `ownerId`, and the resource ID. Threads are scoped to a resource ID, so this is what groups a conversation's threads together:
-
-```typescript
-const sessionId = agentController.session.identity.getId()
-const ownerId = agentController.session.identity.getOwnerId()
-const resourceId = agentController.session.identity.getResourceId()
-const threadId = agentController.session.thread.getId()
-```
-
-The session `id` and `ownerId` are stable for the life of the session, they don't change when the resource ID is switched. They mirror the `id` and `ownerId` fields on `SessionRecord` in storage, so storage layers can key sessions by a stable identifier rather than the mutable resource ID.
-
-The resource ID is set when creating a session via [`agentController.createSession()`](https://mastra.ai/reference/agent-controller/agent-controller-class) and defaults to the agentController `id`. See [Resource IDs](https://mastra.ai/docs/agent-controller/threads-and-state) for how it scopes threads.
-
-## Thread
-
-`session.thread` owns the active thread binding and read access to threads and messages. The AgentController performs lifecycle transitions; the Session reads the result:
-
-```typescript
-// Lifecycle transitions live on the AgentController
-await agentController.switchThread({ threadId: 'thread-abc123' })
-
-// Reads live on the Session
-const threads = await agentController.session.thread.list()
-const messages = await agentController.session.thread.listActiveMessages()
-```
-
-See [Threads and state](https://mastra.ai/docs/agent-controller/threads-and-state) for the full lifecycle.
-
-## Mode and model
-
-The AgentController defines the available modes in `config.modes`. The Session tracks which mode and model are _currently_ selected:
-
-```typescript
-// Switch mode (aborts the run, emits events)
-await agentController.session.mode.switch({ modeId: 'build' })
-
-// Read the current selection (Session state)
-const modeId = agentController.session.mode.get()
-const mode = agentController.session.mode.resolve()
-const modelId = agentController.session.model.get()
-```
-
-See [Modes](https://mastra.ai/docs/agent-controller/modes) for how modes carry their own model.
-
-## Permission grants
-
-The AgentController owns permission _policy_, which categories or tools require approval. The Session owns the _grants_ a user makes during the conversation. A grant lets a tool run for the rest of the session without prompting again:
-
-```typescript
-// Grant a category or tool for the rest of the session
-agentController.session.grantCategory('edit')
-agentController.session.grantTool('mastra_workspace_execute_command')
-
-// Inspect current grants
-const grants = agentController.session.getGrants()
-```
-
-Grants are intentionally in-memory and reset when the session restarts. See [Tool approvals](https://mastra.ai/docs/agent-controller/tool-approvals) for the approval flow.
-
-## Run state
-
-`session.run` tracks the in-flight generation: whether a run is active, its run and trace IDs, and the abort signal. Use it to reflect run status in your UI:
-
-```typescript
-if (agentController.session.run.isRunning()) {
-  // show a stop button
-}
-
-// Abort the active run (AgentController orchestration clears related state)
-agentController.abort()
-```
-
-## Follow-ups
-
-A user may want to add to the conversation while the agent is still working. Instead of dropping or interrupting those messages, the Session queues them on `session.followUps` and sends them when the current run finishes:
-
-```typescript
-const queued = agentController.session.followUps.count()
-```
-
-Queue a follow-up with `agentController.followUp({ content })`. To redirect the agent mid-run instead of waiting, use `agentController.steer({ content })`. Both build on [signals](https://mastra.ai/docs/long-running-agents/signals).
-
-## State
-
-`session.state` holds the conversation's application state, structured values that agents and the UI share, such as model preferences, feature flags, or progress.
-
-The AgentController defines the shape with a `stateSchema`. The Session owns the live snapshot and validates updates against that schema. Every write emits `state_changed`:
-
-```typescript
-const state = agentController.session.state.get()
-await agentController.session.state.set({ theme: 'light' })
-```
-
-See [Threads and state](https://mastra.ai/docs/agent-controller/threads-and-state) for defining a schema.
-
-## Display state
-
-A conversation emits fine-grained events for streamed tokens and tool activity. Other events cover pending approvals, task updates, and token usage.
-
-Subscribing to each event type and reassembling the current picture yourself is tedious and error-prone.
-
-`session.displayState` does that work for you.
-
-It's a reducer-maintained snapshot.
-
-The Session keeps one `AgentControllerDisplayState` object and folds every agentController event into it as it happens, so the snapshot always reflects the latest state.
-
-It captures everything a UI needs to render. The snapshot shows whether the agent is running, what it's streaming, and which tools or subagents are active. It also includes pending approvals, the current task list, token usage, and queued follow-ups.
-
-Because it's a single object, you can drive an entire UI from one place: read the current snapshot with `get()`, and re-render whenever the AgentController emits `display_state_changed` (fired after every other event):
-
-```typescript
-const snapshot = agentController.session.displayState.get()
-
-// Re-render from the snapshot on every change
-agentController.subscribe(event => {
-  if (event.type === 'display_state_changed') {
-    render(agentController.session.displayState.get())
-  }
-})
-```
-
-This is the recommended pattern for most UIs. Subscribe to individual typed events only when you need to react to a specific transition rather than re-render the whole view. Visit the [Session reference](https://mastra.ai/reference/agent-controller/session) for the full list of sub-objects and method signatures.
-
-## Related
-
-- [AgentController overview](https://mastra.ai/docs/agent-controller/overview)
-- [Threads and state](https://mastra.ai/docs/agent-controller/threads-and-state)
-- [Tool approvals](https://mastra.ai/docs/agent-controller/tool-approvals)
-- [Session reference](https://mastra.ai/reference/agent-controller/session)

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

@@ -1,110 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Subagents
-
-Subagents let a parent agent delegate focused tasks to child agents with constrained tools and instructions. The AgentController auto-generates a `subagent` built-in tool that the parent model can call to spawn any configured subagent type. Reach for a subagent when a task needs a different toolset or instruction set than the parent agent, when you want to isolate a subtask's messages from the parent thread, or when the parent should delegate to a cheaper or faster model for specific work.
-
-## Quickstart
-
-Define subagent types in the AgentController constructor:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { AgentController } from '@mastra/core/agent-controller'
-
-const agent = new Agent({
-  id: 'assistant',
-  name: 'assistant',
-  instructions: 'Use subagents when a focused task needs a narrower toolset.',
-  model: 'openai/gpt-5.6-sol',
-})
-
-const agentController = new AgentController({
-  id: 'with-subagents',
-  agent,
-  modes: [{ id: 'default', name: 'Default', metadata: { default: true } }],
-  subagents: [
-    {
-      id: 'explore',
-      name: 'Explore',
-      description: 'Reads files and gathers context without making changes.',
-      instructions: 'You are a read-only exploration agent.',
-      allowedWorkspaceTools: ['read_file', 'list_directory', 'grep_search'],
-      defaultModelId: 'anthropic/claude-haiku-4-5',
-      maxSteps: 30,
-    },
-    {
-      id: 'execute',
-      name: 'Execute',
-      description: 'Makes changes to files and runs commands.',
-      instructions: 'You are an execution agent.',
-      allowedWorkspaceTools: ['read_file', 'write_file', 'execute_command'],
-      defaultModelId: 'anthropic/claude-sonnet-4-6',
-    },
-  ],
-})
-```
-
-The parent agent can then call the auto-generated `subagent` tool with a `task` description and optional `agentType`.
-
-When you define a subagent, give its `description` and `instructions` a clear, narrow scope. The `description` is what the parent model reads to decide _when_ to delegate, so state the single job the subagent is for and, by implication, what it's not for, "Reads files and gathers context without making changes" tells the parent to reach for it during exploration and to handle edits elsewhere. The `instructions` then keep the child agent inside that job. A subagent scoped to one task with a focused toolset stays predictable and is easier for the parent to route to. A broadly described subagent invites the parent to over-delegate and blurs the boundary between types. Pair the narrow scope with `allowedWorkspaceTools` so the subagent can only do what its description promises.
-
-For the full list of subagent configuration options, see [`AgentController` reference](https://mastra.ai/reference/agent-controller/agent-controller-class).
-
-## Forked subagents
-
-A default subagent starts with a fresh context: it can't see the parent conversation, so you pass everything it needs in the `task` description. That's the right model for self-contained work, but it has two costs. The subagent has no access to what's already happened, and it builds a brand-new request prefix, a different system prompt and tool schemas, so it can't reuse the parent's prompt cache.
-
-**Forked subagents** solve both. Instead of a fresh agent, a fork clones the parent thread and runs the parent agent itself, so it sees the full conversation history and keeps the same system prompt and tool schemas as the parent. The identical prefix means the model's prompt cache still hits, which makes context-heavy delegation cheaper and faster.
-
-Use a fork when the subtask depends on the conversation so far, prior messages, earlier tool results, or the parent's tool environment, and you want to run it without paying to rebuild that context. Use a default subagent when the task is self-contained and benefits from a narrower toolset or a tighter system prompt, or alternatively a cheaper model.
-
-Enable forked mode per-type:
-
-```typescript
-const collaborator = {
-  id: 'collaborator',
-  name: 'Collaborator',
-  description: 'Continues the conversation in a fork.',
-  forked: true,
-}
-```
-
-Or per-invocation via the `subagent` tool's `forked` input parameter, which overrides the type's default.
-
-### Forked mode semantics
-
-Because a fork reuses the parent agent to keep the prompt prefix stable, the subagent's own definition is mostly set aside:
-
-- Memory must be configured on the AgentController, since forking clones the parent thread.
-
-Without it, the fork call returns an error.
-
-- The fork runs with the parent agent's instructions, tools, and model. The subagent definition's own `instructions`, `tools`, and `defaultModelId` are ignored, and a per-invocation `modelId` is ignored too.
-- Only the subagent definition's `description` still matters: it's what the parent model reads to decide when to delegate.
-- Fork threads are tagged with `metadata.forkedSubagent === true` and hidden from `session.thread.list()` by default.
-- Recursive forks are blocked at runtime: the inherited `subagent` tool is disabled inside a fork to prevent infinite nesting.
-
-## Subagent model management
-
-Set a global or per-type subagent model at runtime:
-
-```typescript
-// Global subagent model
-await agentController.session.subagents.model.set({ modelId: 'anthropic/claude-sonnet-4-6' })
-
-// Per-type override
-await agentController.session.subagents.model.set({
-  modelId: 'anthropic/claude-haiku-4-5',
-  agentType: 'explore',
-})
-
-// Read current model
-const modelId = agentController.session.subagents.model.get({ agentType: 'explore' })
-```
-
-## Related
-
-- [AgentController overview](https://mastra.ai/docs/agent-controller/overview)
-- [Tool approvals and permissions](https://mastra.ai/docs/agent-controller/tool-approvals)
-- [API reference](https://mastra.ai/reference/agent-controller/agent-controller-class)

package/.docs/docs/agent-controller/threads-and-state.md

@@ -1,148 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Threads and state
-
-Threads and state are how an AgentController conversation survives beyond a single exchange. A **thread** is the persistent record of a conversation, its messages and metadata, saved to storage so a user can close the app and resume the same conversation later, or switch between several conversations. **State** is structured data attached to the conversation, values like model preferences, feature flags, or progress, that agents and your UI read and write as the conversation runs.
-
-The thread and state work together: the thread is the message history, and state is the shared scratchpad alongside it.
-
-Both persist across mode switches, model changes, and restarts, so nothing is lost when a user switches from plan mode to build mode or reopens the app the next day.
-
-Thread _lifecycle_ transitions, create, switch, clone, delete, live on the AgentController because they coordinate the shared thread lock and emit events. The active thread binding and thread/message _reads_ live on the [`Session`](https://mastra.ai/docs/agent-controller/session) as `agentController.session.thread`.
-
-## Threads
-
-A thread holds one conversation's full message history. The AgentController binds the Session to one active thread at a time. Messages you send and the agent's replies are appended to that thread and saved to storage. Threads let users resume a past conversation or keep several conversations side by side, or alternatively branch one into alternatives.
-
-### Creating and selecting threads
-
-On startup, call `selectOrCreateThread()` to resume the most recent thread or create a new one:
-
-```typescript
-await agentController.init()
-const thread = await agentController.selectOrCreateThread()
-```
-
-Create a thread explicitly with a title:
-
-```typescript
-const thread = await agentController.createThread({ title: 'New conversation' })
-```
-
-### Switching threads
-
-Switch to an existing thread.
-
-The agentController aborts any in-progress generation and acquires a lock on the new thread, plus emits a `thread_changed` event:
-
-```typescript
-await agentController.switchThread({ threadId: 'thread-abc123' })
-```
-
-### Listing threads
-
-List threads for the current resource. Forked subagent threads are hidden by default:
-
-```typescript
-const threads = await agentController.session.thread.list()
-
-// Include all resources
-const allThreads = await agentController.session.thread.list({ allResources: true })
-```
-
-### Cloning threads
-
-Clone a thread to create a branch of the conversation. The agentController copies all messages and switches to the clone:
-
-```typescript
-const cloned = await agentController.cloneThread({ title: 'Alternative approach' })
-```
-
-### Thread locking
-
-Pass a `threadLock` to the AgentController constructor to prevent concurrent access from multiple processes. The lock is acquired before any thread operation and released on switch or delete:
-
-```typescript
-const agentController = new AgentController({
-  id: 'my-agent',
-  threadLock: {
-    acquire: async threadId => {
-      /* acquire lock or throw */
-    },
-    release: async threadId => {
-      /* release lock */
-    },
-  },
-})
-```
-
-## State
-
-Where a thread stores the conversation's messages, state stores structured values that describe the conversation but aren't messages, model preferences, feature flags, UI settings, or progress markers. Agents can read and update state during a run, and your UI can react to changes, so state is how the agent and the interface stay in sync on shared facts. You define its shape with a schema, and every update is validated against that schema before it's applied.
-
-### Defining a state schema
-
-Pass a `stateSchema` (Standard JSON Schema) to validate state and extract defaults:
-
-```typescript
-import { Agent } from '@mastra/core/agent'
-import { AgentController } from '@mastra/core/agent-controller'
-import { z } from 'zod'
-
-const agent = new Agent({
-  id: 'assistant',
-  name: 'assistant',
-  instructions: 'Help the user manage a stateful session.',
-  model: 'openai/gpt-5.6-sol',
-})
-
-const agentController = new AgentController({
-  id: 'stateful-agent',
-  agent,
-  modes: [{ id: 'default', name: 'Default', metadata: { default: true } }],
-  stateSchema: z.object({
-    currentModelId: z.string().optional(),
-    theme: z.enum(['light', 'dark']).default('dark'),
-  }),
-})
-```
-
-### Reading and writing state
-
-State is owned by the [`Session`](https://mastra.ai/docs/agent-controller/session) as `agentController.session.state`:
-
-```typescript
-// Read the current state snapshot
-const state = agentController.session.state.get()
-
-// Update state — validates against schema and emits state_changed
-await agentController.session.state.set({ theme: 'light' })
-```
-
-State changes emit a `state_changed` event with the new state and the set of changed keys.
-
-## Resource IDs
-
-Threads are scoped to a resource ID, which groups a conversation's threads by project, user, or workspace. Set it on the AgentController constructor; it defaults to the agentController `id` when omitted:
-
-```typescript
-const agentController = new AgentController({
-  id: 'my-agent',
-  resourceId: 'project-xyz',
-})
-```
-
-The resource ID is part of a conversation's identity, so you read it from the Session:
-
-```typescript
-const resourceId = agentController.session.identity.getResourceId()
-```
-
-The session also has a stable `id` and `ownerId` (read with `session.identity.getId()` and `session.identity.getOwnerId()`). Unlike the resource ID, these don't change when you switch resources, see [Session identity](https://mastra.ai/docs/agent-controller/session) for details.
-
-## Related
-
-- [AgentController overview](https://mastra.ai/docs/agent-controller/overview)
-- [Session](https://mastra.ai/docs/agent-controller/session)
-- [Modes](https://mastra.ai/docs/agent-controller/modes)
-- [API reference](https://mastra.ai/reference/agent-controller/agent-controller-class)

package/.docs/docs/agent-controller/tool-approvals.md

@@ -1,147 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Tool approvals and permissions
-
-The AgentController provides a permission system that controls which tools require user approval before execution.
-
-You can configure policies at the category level or per-tool, and grant session-wide exceptions for trusted tools.
-
-This gives agents with access to destructive or sensitive tools, file writes, command execution, API calls, a human-in-the-loop checkpoint before those tools run.
-
-## Permission policies
-
-Policies control tool behavior:
-
-- `allow`: The tool runs without prompting
-- `ask`: The tool pauses and emits a `tool_approval_required` event; the user must approve or decline
-- `deny`: The tool is blocked from execution
-
-### Setting policies
-
-Set policies per-category or per-tool. Per-tool policies take precedence over category policies:
-
-```typescript
-// Category-level: all execute tools require approval
-await agentController.session.permissions.setForCategory({ category: 'execute', policy: 'ask' })
-
-// Tool-level: this specific tool is always blocked
-await agentController.session.permissions.setForTool({ toolName: 'dangerous_tool', policy: 'deny' })
-```
-
-### Tool categories
-
-The `toolCategoryResolver` maps tool names to categories. Pass it to the AgentController constructor:
-
-```typescript
-const agentController = new AgentController({
-  id: 'my-agent',
-  toolCategoryResolver: toolName => {
-    if (toolName.includes('write') || toolName.includes('delete')) return 'edit'
-    if (toolName.includes('execute')) return 'execute'
-    return 'read'
-  },
-})
-```
-
-Built-in categories are `read`, `edit`, `execute`, `mcp`, and `other`.
-
-## Responding to approval requests
-
-When a tool's policy is `ask`, the AgentController emits a `tool_approval_required` event. Your UI should display a prompt and call `session.respondToToolApproval()`:
-
-```typescript
-agentController.subscribe(event => {
-  if (event.type === 'tool_approval_required') {
-    // Show approval UI...
-    agentController.session.respondToToolApproval({ decision: 'approve' })
-  }
-})
-```
-
-The `decision` field accepts `'approve'`, `'decline'`, or `'always_allow_category'`. When `always_allow_category` is used, the tool's category is granted for the rest of the session. Future tools in the same category are auto-approved.
-
-```typescript
-agentController.session.respondToToolApproval({ decision: 'always_allow_category' })
-```
-
-## Session grants
-
-The AgentController owns permission _policy_ (which categories require approval). The [`Session`](https://mastra.ai/docs/agent-controller/session) owns the _grants_ a user makes during a conversation. Grant a category or tool for the rest of the session so it runs without further prompting:
-
-```typescript
-// Grant all edit tools for this session
-agentController.session.grantCategory('edit')
-
-// Grant a specific tool
-agentController.session.grantTool('mastra_workspace_execute_command')
-
-// Check current grants
-const grants = agentController.session.getGrants()
-// { categories: ['edit'], tools: ['mastra_workspace_execute_command'] }
-```
-
-## Tool suspensions
-
-Interactive built-in tools (`ask_user`, `submit_plan`) use the native tool-suspension primitive instead of the approval flow. They emit a `tool_suspended` event with `toolCallId`, `toolName`, and `suspendPayload`. Resume with `respondToToolSuspension()`:
-
-```typescript
-agentController.subscribe(event => {
-  if (event.type === 'tool_suspended' && event.toolName === 'ask_user') {
-    const { question } = event.suspendPayload as { question: string }
-    // Show question to user, then resume:
-    agentController.respondToToolSuspension({
-      toolCallId: event.toolCallId,
-      resumeData: 'User response here',
-    })
-  }
-})
-```
-
-### Plan approval
-
-The `submit_plan` tool suspends via the same mechanism. Resume with an `action` field:
-
-```typescript
-// Approve the plan
-agentController.respondToToolSuspension({
-  toolCallId: event.toolCallId,
-  resumeData: { action: 'approved' },
-})
-
-// Reject with feedback
-agentController.respondToToolSuspension({
-  toolCallId: event.toolCallId,
-  resumeData: { action: 'rejected', feedback: 'Needs more detail' },
-})
-```
-
-## Built-in tools
-
-The AgentController provides these built-in tools to agents in every mode:
-
-| Tool            | Description                                                         |
-| --------------- | ------------------------------------------------------------------- |
-| `ask_user`      | Ask the user a question (free text, single-select, or multi-select) |
-| `submit_plan`   | Submit a plan for user review and approval                          |
-| `task_write`    | Create or replace a structured task list                            |
-| `task_update`   | Update one tracked task by ID                                       |
-| `task_complete` | Mark one tracked task completed                                     |
-| `task_check`    | Check task list completion status                                   |
-| `subagent`      | Spawn a focused subagent (requires `subagents` config)              |
-
-Disable specific built-in tools with `disableBuiltinTools`:
-
-```typescript
-const agentController = new AgentController({
-  id: 'no-plans',
-  disableBuiltinTools: ['submit_plan'],
-})
-```
-
-## Related
-
-- [AgentController overview](https://mastra.ai/docs/agent-controller/overview)
-- [Session](https://mastra.ai/docs/agent-controller/session)
-- [Subagents](https://mastra.ai/docs/agent-controller/subagents)
-- [Agent approval](https://mastra.ai/docs/agents/agent-approval)
-- [API reference](https://mastra.ai/reference/agent-controller/agent-controller-class)