@mastra/mcp-docs-server 1.2.2 → 1.2.3-alpha.11

package/.docs/reference/{harness → agent-controller}/session.md

@@ -1,26 +1,26 @@
 # Session class
 
-> **Beta:** The `Harness` feature is in beta stage and subject to breaking changes in minor versions until it graduates from its beta status.
+> **Beta:** The `AgentController` feature is in beta stage and subject to breaking changes in minor versions until it graduates from its beta status.
 
-A `Session` owns all the state tied to a single conversation. The [`Harness`](https://mastra.ai/reference/harness/harness-class) is the shared host — agents, storage, config, the thread lock, and the event bus — while the `Session` holds everything that is per-conversation: identity, the active thread binding and reads, mode and model selection, run and abort state, the live agent stream, tool suspensions, follow-ups, approvals, permission grants, token usage, and the display-state snapshot.
+A `Session` owns all the state tied to a single conversation. The [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class) is the shared host — agents, storage, config, the thread lock, and the event bus — while the `Session` holds everything that is per-conversation: identity, the active thread binding and reads, mode and model selection, run and abort state, the live agent stream, tool suspensions, follow-ups, approvals, permission grants, token usage, and the display-state snapshot.
 
-Access the session through `harness.session`.
+Access the session through `agentController.session`.
 
-For a conceptual introduction, see the [Harness overview](https://mastra.ai/docs/harness/overview).
+For a conceptual introduction, see the [AgentController overview](https://mastra.ai/docs/agent-controller/overview).
 
 ## Usage example
 
 ```typescript
-// Read per-conversation state through harness.session
-const modeId = harness.session.mode.get()
-const modelId = harness.session.model.get()
-const threadId = harness.session.thread.getId()
-const grants = harness.session.getGrants()
+// Read per-conversation state through agentController.session
+const modeId = agentController.session.mode.get()
+const modelId = agentController.session.model.get()
+const threadId = agentController.session.thread.getId()
+const grants = agentController.session.getGrants()
 
 // Render from the coalesced display-state snapshot
-harness.subscribe(event => {
+agentController.subscribe(event => {
   if (event.type === 'display_state_changed') {
-    render(harness.session.displayState.get())
+    render(agentController.session.displayState.get())
   }
 })
 ```
@@ -47,11 +47,11 @@ The session is organized into sub-objects, each owning one domain of per-convers
 
 **approval** (`SessionApproval`): The pending tool-approval gate. See approval methods below.
 
-**displayState** (`SessionDisplayState`): The canonical HarnessDisplayState snapshot a UI renders from. See display-state methods below.
+**displayState** (`SessionDisplayState`): The canonical AgentControllerDisplayState snapshot a UI renders from. See display-state methods below.
 
-**state** (`SessionState<TState>`): The schema-validated, session-owned Harness state. See state methods below.
+**state** (`SessionState<TState>`): The schema-validated, session-owned AgentController state. See state methods below.
 
-**browser** (`MastraBrowser | undefined`): The browser automation instance for this session. Set at creation via createSession, or from the Harness config default. Undefined when no browser is configured.
+**browser** (`MastraBrowser | undefined`): The browser automation instance for this session. Set at creation via createSession, or from the AgentController config default. Undefined when no browser is configured.
 
 ## Methods
 
@@ -64,7 +64,7 @@ Session-scoped grants auto-approve tools without prompting. Grants are ephemeral
 Grant a tool category for the current session. Tools in this category are auto-approved.
 
 ```typescript
-harness.session.grantCategory('edit')
+agentController.session.grantCategory('edit')
 ```
 
 #### `grantTool(toolName)`
@@ -72,7 +72,7 @@ harness.session.grantCategory('edit')
 Grant a specific tool for the current session.
 
 ```typescript
-harness.session.grantTool('mastra_workspace_execute_command')
+agentController.session.grantTool('mastra_workspace_execute_command')
 ```
 
 #### `getGrants()`
@@ -80,7 +80,7 @@ harness.session.grantTool('mastra_workspace_execute_command')
 Return the currently granted categories and tools.
 
 ```typescript
-const grants = harness.session.getGrants()
+const grants = agentController.session.getGrants()
 // { categories: string[], tools: string[] }
 ```
 
@@ -91,9 +91,9 @@ const grants = harness.session.getGrants()
 Respond to a pending tool approval request, raised by a `tool_approval_required` event. Pass `always_allow_category` to also grant the tool's whole category for the rest of the session.
 
 ```typescript
-harness.session.respondToToolApproval({ decision: 'approve' })
-harness.session.respondToToolApproval({ decision: 'decline' })
-harness.session.respondToToolApproval({ decision: 'always_allow_category' })
+agentController.session.respondToToolApproval({ decision: 'approve' })
+agentController.session.respondToToolApproval({ decision: 'decline' })
+agentController.session.respondToToolApproval({ decision: 'always_allow_category' })
 ```
 
 ### Run control
@@ -103,7 +103,7 @@ harness.session.respondToToolApproval({ decision: 'always_allow_category' })
 Return the run ID of the in-flight run, or `null` when idle. Prefers the live stream's active run, falling back to the last stored run ID.
 
 ```typescript
-const runId = harness.session.getCurrentRunId()
+const runId = agentController.session.getCurrentRunId()
 ```
 
 #### `abortRun()`
@@ -111,7 +111,7 @@ const runId = harness.session.getCurrentRunId()
 Abort the in-flight run: aborts the live stream, requests abort on the run, and clears parked tool suspensions.
 
 ```typescript
-harness.session.abortRun()
+agentController.session.abortRun()
 ```
 
 ### Token usage
@@ -121,7 +121,7 @@ harness.session.abortRun()
 Return a copy of the running token-usage tally for the active thread.
 
 ```typescript
-const usage = harness.session.getTokenUsage()
+const usage = agentController.session.getTokenUsage()
 // { promptTokens, completionTokens, totalTokens, ... }
 ```
 
@@ -134,7 +134,7 @@ const usage = harness.session.getTokenUsage()
 Return the stable session identifier.
 
 ```typescript
-const sessionId = harness.session.identity.getId()
+const sessionId = agentController.session.identity.getId()
 ```
 
 ### `session.identity.getOwnerId()`
@@ -142,7 +142,7 @@ const sessionId = harness.session.identity.getId()
 Return the stable owner identifier for the session.
 
 ```typescript
-const ownerId = harness.session.identity.getOwnerId()
+const ownerId = agentController.session.identity.getOwnerId()
 ```
 
 ### `session.identity.getResourceId()`
@@ -150,7 +150,7 @@ const ownerId = harness.session.identity.getOwnerId()
 Return the current resource ID.
 
 ```typescript
-const resourceId = harness.session.identity.getResourceId()
+const resourceId = agentController.session.identity.getResourceId()
 ```
 
 ### `session.identity.getDefaultResourceId()`
@@ -158,21 +158,21 @@ const resourceId = harness.session.identity.getResourceId()
 Return the resource ID the session was created with.
 
 ```typescript
-const defaultResourceId = harness.session.identity.getDefaultResourceId()
+const defaultResourceId = agentController.session.identity.getDefaultResourceId()
 ```
 
-To change the resource ID, use [`harness.setResourceId()`](https://mastra.ai/reference/harness/harness-class), which also tears down the active thread. The session `id` and `ownerId` are not affected by resource switches.
+To change the resource ID, use [`agentController.setResourceId()`](https://mastra.ai/reference/agent-controller/agent-controller-class), which also tears down the active thread. The session `id` and `ownerId` are not affected by resource switches.
 
 ## Thread
 
-`session.thread` owns the active thread binding plus thread and message reads. Thread lifecycle (create, switch, clone, delete, rename) lives on the [`Harness`](https://mastra.ai/reference/harness/harness-class) because it coordinates the shared thread lock and event bus.
+`session.thread` owns the active thread binding plus thread and message reads. Thread lifecycle (create, switch, clone, delete, rename) lives on the [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class) because it coordinates the shared thread lock and event bus.
 
 ### `session.thread.getId()`
 
 Return the active thread ID, or `null` when no thread is bound.
 
 ```typescript
-const threadId = harness.session.thread.getId()
+const threadId = agentController.session.thread.getId()
 ```
 
 ### `session.thread.list(options?)`
@@ -180,9 +180,9 @@ const threadId = harness.session.thread.getId()
 List threads from storage. By default only threads for the current resource are returned, and transient forked subagent threads are hidden.
 
 ```typescript
-const threads = await harness.session.thread.list()
-const allThreads = await harness.session.thread.list({ allResources: true })
-const everything = await harness.session.thread.list({ includeForkedSubagents: true })
+const threads = await agentController.session.thread.list()
+const allThreads = await agentController.session.thread.list({ allResources: true })
+const everything = await agentController.session.thread.list({ includeForkedSubagents: true })
 ```
 
 ### `session.thread.getById({ threadId })`
@@ -190,7 +190,7 @@ const everything = await harness.session.thread.list({ includeForkedSubagents: t
 Return a single thread by ID, or `null` if it doesn't exist.
 
 ```typescript
-const thread = await harness.session.thread.getById({ threadId: 'thread-abc123' })
+const thread = await agentController.session.thread.getById({ threadId: 'thread-abc123' })
 ```
 
 ### `session.thread.listActiveMessages(options?)`
@@ -198,7 +198,7 @@ const thread = await harness.session.thread.getById({ threadId: 'thread-abc123'
 Retrieve messages for the active thread. Returns an empty array when no thread is bound.
 
 ```typescript
-const messages = await harness.session.thread.listActiveMessages({ limit: 50 })
+const messages = await agentController.session.thread.listActiveMessages({ limit: 50 })
 ```
 
 ### `session.thread.listMessages({ threadId, limit? })`
@@ -206,7 +206,7 @@ const messages = await harness.session.thread.listActiveMessages({ limit: 50 })
 Retrieve messages for a specific thread.
 
 ```typescript
-const messages = await harness.session.thread.listMessages({ threadId: 'thread-abc123' })
+const messages = await agentController.session.thread.listMessages({ threadId: 'thread-abc123' })
 ```
 
 ### `session.thread.firstUserMessage({ threadId })`
@@ -214,7 +214,9 @@ const messages = await harness.session.thread.listMessages({ threadId: 'thread-a
 Retrieve the first user message for a thread, or `null` if none.
 
 ```typescript
-const firstMsg = await harness.session.thread.firstUserMessage({ threadId: 'thread-abc123' })
+const firstMsg = await agentController.session.thread.firstUserMessage({
+  threadId: 'thread-abc123',
+})
 ```
 
 ### `session.thread.firstUserMessages({ threadIds })`
@@ -222,7 +224,7 @@ const firstMsg = await harness.session.thread.firstUserMessage({ threadId: 'thre
 Retrieve the first user message for many threads at once, returned as a map.
 
 ```typescript
-const firstByThread = await harness.session.thread.firstUserMessages({
+const firstByThread = await agentController.session.thread.firstUserMessages({
   threadIds: ['thread-a', 'thread-b'],
 })
 ```
@@ -232,9 +234,9 @@ const firstByThread = await harness.session.thread.firstUserMessages({
 Read, write, and remove per-thread settings stored on the active thread's metadata.
 
 ```typescript
-await harness.session.thread.setSetting({ key: 'omThreshold', value: 0.8 })
-const value = await harness.session.thread.getSetting({ key: 'omThreshold' })
-await harness.session.thread.deleteSetting({ key: 'omThreshold' })
+await agentController.session.thread.setSetting({ key: 'omThreshold', value: 0.8 })
+const value = await agentController.session.thread.getSetting({ key: 'omThreshold' })
+await agentController.session.thread.deleteSetting({ key: 'omThreshold' })
 ```
 
 ## Mode
@@ -246,15 +248,15 @@ await harness.session.thread.deleteSetting({ key: 'omThreshold' })
 Return the active mode ID.
 
 ```typescript
-const modeId = harness.session.mode.get()
+const modeId = agentController.session.mode.get()
 ```
 
 ### `session.mode.resolve()`
 
-Return the full `HarnessMode` object for the active mode, resolved against the harness's configured modes.
+Return the full `AgentControllerMode` object for the active mode, resolved against the agentController's configured modes.
 
 ```typescript
-const mode = harness.session.mode.resolve()
+const mode = agentController.session.mode.resolve()
 ```
 
 ### `session.mode.switch({ modeId })`
@@ -262,7 +264,7 @@ const mode = harness.session.mode.resolve()
 Switch to a different mode. Aborts any in-progress generation, saves the current model to the outgoing mode, loads the incoming mode's model, and emits `mode_changed` and `model_changed` events.
 
 ```typescript
-await harness.session.mode.switch({ modeId: 'build' })
+await agentController.session.mode.switch({ modeId: 'build' })
 ```
 
 ## Model
@@ -274,7 +276,7 @@ await harness.session.mode.switch({ modeId: 'build' })
 Return the active model ID.
 
 ```typescript
-const modelId = harness.session.model.get()
+const modelId = agentController.session.model.get()
 ```
 
 ### `session.model.displayName()`
@@ -282,7 +284,7 @@ const modelId = harness.session.model.get()
 Return a short display name for the active model: the last segment of the model ID (for example, `claude-sonnet-4` from `anthropic/claude-sonnet-4`). Returns `'unknown'` when no model is selected.
 
 ```typescript
-const name = harness.session.model.displayName()
+const name = agentController.session.model.displayName()
 ```
 
 ### `session.model.hasSelection()`
@@ -290,37 +292,37 @@ const name = harness.session.model.displayName()
 Check whether a model is currently selected.
 
 ```typescript
-if (harness.session.model.hasSelection()) {
+if (agentController.session.model.hasSelection()) {
   // Ready to send messages
 }
 ```
 
 ### `session.model.switch({ modelId, scope?, modeId? })`
 
-Switch the active model. When `scope` is `'thread'` (the default), the model ID is persisted as the per-mode model so it's restored when switching back. Reports the selection to the harness's `modelUseCountTracker` and emits a `model_changed` event.
+Switch the active model. When `scope` is `'thread'` (the default), the model ID is persisted as the per-mode model so it's restored when switching back. Reports the selection to the agentController's `modelUseCountTracker` and emits a `model_changed` event.
 
 ```typescript
 // Set for the current session only
-await harness.session.model.switch({
+await agentController.session.model.switch({
   modelId: 'anthropic/claude-sonnet-4-6',
   scope: 'global',
 })
 
 // Persist to the current thread (default)
-await harness.session.model.switch({ modelId: 'anthropic/claude-sonnet-4-6' })
+await agentController.session.model.switch({ modelId: 'anthropic/claude-sonnet-4-6' })
 ```
 
 ## Observational Memory
 
-The observational-memory model selection, grouped by role under `session.om.observer` and `session.om.reflector`. Both roles expose the same methods. Reads return the value from session state when set, falling back to the harness's `omConfig` defaults.
+The observational-memory model selection, grouped by role under `session.om.observer` and `session.om.reflector`. Both roles expose the same methods. Reads return the value from session state when set, falling back to the agentController's `omConfig` defaults.
 
 ### `session.om.observer.modelId()` / `session.om.reflector.modelId()`
 
 Return the role's model ID, or `undefined` when neither session state nor `omConfig` provides one.
 
 ```typescript
-const observer = harness.session.om.observer.modelId()
-const reflector = harness.session.om.reflector.modelId()
+const observer = agentController.session.om.observer.modelId()
+const reflector = agentController.session.om.reflector.modelId()
 ```
 
 ### `session.om.observer.threshold()` / `session.om.reflector.threshold()`
@@ -328,8 +330,8 @@ const reflector = harness.session.om.reflector.modelId()
 Return the role's threshold in tokens (observation threshold for the observer, reflection threshold for the reflector), or `undefined` when unset.
 
 ```typescript
-const observationThreshold = harness.session.om.observer.threshold()
-const reflectionThreshold = harness.session.om.reflector.threshold()
+const observationThreshold = agentController.session.om.observer.threshold()
+const reflectionThreshold = agentController.session.om.reflector.threshold()
 ```
 
 ### `session.om.observer.switchModel({ modelId })` / `session.om.reflector.switchModel({ modelId })`
@@ -337,16 +339,20 @@ const reflectionThreshold = harness.session.om.reflector.threshold()
 Switch the role's model. Persists the setting to thread metadata and emits an `om_model_changed` event.
 
 ```typescript
-await harness.session.om.observer.switchModel({ modelId: 'anthropic/claude-haiku-4-5' })
-await harness.session.om.reflector.switchModel({ modelId: 'anthropic/claude-haiku-4-5' })
+await agentController.session.om.observer.switchModel({
+  modelId: 'anthropic/claude-haiku-4-5',
+})
+await agentController.session.om.reflector.switchModel({
+  modelId: 'anthropic/claude-haiku-4-5',
+})
 ```
 
 ### `session.om.observer.resolvedModel()` / `session.om.reflector.resolvedModel()`
 
-Resolve the role's model ID to a model instance via the harness's `resolveModel`, or `undefined` when no model ID is set or no resolver is configured.
+Resolve the role's model ID to a model instance via the agentController's `resolveModel`, or `undefined` when no model ID is set or no resolver is configured.
 
 ```typescript
-const observerModel = harness.session.om.observer.resolvedModel()
+const observerModel = agentController.session.om.observer.resolvedModel()
 ```
 
 ## Permissions
@@ -358,7 +364,7 @@ const observerModel = harness.session.om.observer.resolvedModel()
 Return the current permission rules, or empty rules (`{ categories: {}, tools: {} }`) when none are set.
 
 ```typescript
-const rules = harness.session.permissions.getRules()
+const rules = agentController.session.permissions.getRules()
 // { categories: { execute: 'ask' }, tools: { dangerous_tool: 'deny' } }
 ```
 
@@ -367,7 +373,7 @@ const rules = harness.session.permissions.getRules()
 Set the approval policy (`'allow' | 'ask' | 'deny'`) for a tool category. Resolves once the change is persisted to session state.
 
 ```typescript
-await harness.session.permissions.setForCategory({ category: 'execute', policy: 'ask' })
+await agentController.session.permissions.setForCategory({ category: 'execute', policy: 'ask' })
 ```
 
 ### `session.permissions.setForTool({ toolName, policy })`
@@ -375,7 +381,7 @@ await harness.session.permissions.setForCategory({ category: 'execute', policy:
 Set the approval policy for a specific tool. Per-tool policies take precedence over category policies. Resolves once persisted.
 
 ```typescript
-await harness.session.permissions.setForTool({ toolName: 'dangerous_tool', policy: 'deny' })
+await agentController.session.permissions.setForTool({ toolName: 'dangerous_tool', policy: 'deny' })
 ```
 
 ## Subagents
@@ -387,7 +393,7 @@ await harness.session.permissions.setForTool({ toolName: 'dangerous_tool', polic
 Return the subagent model ID, preferring the per-`agentType` value when one is given, then the global subagent model, or `null` when neither is set.
 
 ```typescript
-const modelId = harness.session.subagents.model.get({ agentType: 'explore' })
+const modelId = agentController.session.subagents.model.get({ agentType: 'explore' })
 ```
 
 ### `session.subagents.model.set({ modelId, agentType? })`
@@ -396,10 +402,10 @@ Set the subagent model ID. Pass an `agentType` to set a per-type override, or om
 
 ```typescript
 // Set the global subagent model
-await harness.session.subagents.model.set({ modelId: 'anthropic/claude-sonnet-4-6' })
+await agentController.session.subagents.model.set({ modelId: 'anthropic/claude-sonnet-4-6' })
 
 // Set a per-type override
-await harness.session.subagents.model.set({
+await agentController.session.subagents.model.set({
   modelId: 'anthropic/claude-haiku-4-5',
   agentType: 'explore',
 })
@@ -414,8 +420,8 @@ await harness.session.subagents.model.set({
 Return the stored run ID and trace ID for the current run, or `null` when idle.
 
 ```typescript
-const runId = harness.session.run.getRunId()
-const traceId = harness.session.run.getTraceId()
+const runId = agentController.session.run.getRunId()
+const traceId = agentController.session.run.getTraceId()
 ```
 
 ### `session.run.isRunning()`
@@ -423,7 +429,7 @@ const traceId = harness.session.run.getTraceId()
 Return whether a run is currently in progress.
 
 ```typescript
-if (harness.session.run.isRunning()) {
+if (agentController.session.run.isRunning()) {
   // A run is active
 }
 ```
@@ -437,7 +443,7 @@ if (harness.session.run.isRunning()) {
 Return the run ID active on the live stream, or `null` when no stream is open.
 
 ```typescript
-const runId = harness.session.stream.activeRunId()
+const runId = agentController.session.stream.activeRunId()
 ```
 
 ### `session.stream.isActive()`
@@ -445,7 +451,7 @@ const runId = harness.session.stream.activeRunId()
 Return whether the stream currently has an active run.
 
 ```typescript
-if (harness.session.stream.isActive()) {
+if (agentController.session.stream.isActive()) {
   // The current thread's stream is producing output
 }
 ```
@@ -459,7 +465,7 @@ if (harness.session.stream.isActive()) {
 Return whether any tool is currently suspended.
 
 ```typescript
-if (harness.session.suspensions.hasPending()) {
+if (agentController.session.suspensions.hasPending()) {
   // At least one interactive tool is waiting for a response
 }
 ```
@@ -469,10 +475,10 @@ if (harness.session.suspensions.hasPending()) {
 Return whether a specific tool call is suspended.
 
 ```typescript
-const waiting = harness.session.suspensions.has({ toolCallId: event.toolCallId })
+const waiting = agentController.session.suspensions.has({ toolCallId: event.toolCallId })
 ```
 
-Resume a suspended tool with [`harness.respondToToolSuspension()`](https://mastra.ai/reference/harness/harness-class).
+Resume a suspended tool with [`agentController.respondToToolSuspension()`](https://mastra.ai/reference/agent-controller/agent-controller-class).
 
 ## Follow-ups
 
@@ -483,7 +489,7 @@ Resume a suspended tool with [`harness.respondToToolSuspension()`](https://mastr
 Return the number of queued follow-ups.
 
 ```typescript
-const queued = harness.session.followUps.count()
+const queued = agentController.session.followUps.count()
 ```
 
 ### `session.followUps.isEmpty()`
@@ -491,7 +497,7 @@ const queued = harness.session.followUps.count()
 Return whether the follow-up queue is empty.
 
 ```typescript
-if (!harness.session.followUps.isEmpty()) {
+if (!agentController.session.followUps.isEmpty()) {
   // Messages are waiting to be processed
 }
 ```
@@ -505,7 +511,7 @@ if (!harness.session.followUps.isEmpty()) {
 Return whether a tool is currently awaiting an approval decision.
 
 ```typescript
-if (harness.session.approval.isArmed()) {
+if (agentController.session.approval.isArmed()) {
   // Show the approval prompt
 }
 ```
@@ -514,14 +520,14 @@ Respond with [`session.respondToToolApproval()`](#respondtotoolapproval-decision
 
 ## Display state
 
-`session.displayState` owns the canonical `HarnessDisplayState` snapshot a UI renders from, and the reducer that keeps it in sync with every harness event.
+`session.displayState` owns the canonical `AgentControllerDisplayState` snapshot a UI renders from, and the reducer that keeps it in sync with every agentController event.
 
 ### `session.displayState.get()`
 
-Return the current `HarnessDisplayState` snapshot for UI rendering.
+Return the current `AgentControllerDisplayState` snapshot for UI rendering.
 
 ```typescript
-const displayState = harness.session.displayState.get()
+const displayState = agentController.session.displayState.get()
 ```
 
 ### `session.displayState.restoreTasks(tasks)`
@@ -529,21 +535,21 @@ const displayState = harness.session.displayState.get()
 Restore the task portion of the snapshot after a UI replays persisted task tool history. This is a pure update of the snapshot and does not emit an event, so re-render explicitly after calling it.
 
 ```typescript
-harness.session.displayState.restoreTasks(replayedTasks)
+agentController.session.displayState.restoreTasks(replayedTasks)
 ```
 
-After every event the harness emits `display_state_changed`, so high-frequency events such as `message_update`, `tool_update`, and `tool_input_delta` are coalesced into the next snapshot. Subscribe with [`harness.subscribe()`](https://mastra.ai/reference/harness/harness-class) and read the latest snapshot from `session.displayState.get()`.
+After every event the agentController emits `display_state_changed`, so high-frequency events such as `message_update`, `tool_update`, and `tool_input_delta` are coalesced into the next snapshot. Subscribe with [`agentController.subscribe()`](https://mastra.ai/reference/agent-controller/agent-controller-class) and read the latest snapshot from `session.displayState.get()`.
 
 ## State
 
-`session.state` owns the schema-validated Harness state for the conversation. It holds the current snapshot, validates updates against the `stateSchema` passed to the Harness, serializes concurrent writes, and emits a `state_changed` event on every change.
+`session.state` owns the schema-validated AgentController state for the conversation. It holds the current snapshot, validates updates against the `stateSchema` passed to the AgentController, serializes concurrent writes, and emits a `state_changed` event on every change.
 
 ### `session.state.get()`
 
 Return a readonly copy of the current state snapshot.
 
 ```typescript
-const state = harness.session.state.get()
+const state = agentController.session.state.get()
 ```
 
 ### `session.state.set(updates)`
@@ -551,7 +557,7 @@ const state = harness.session.state.get()
 Merge a partial update into the state. Updates are queued so concurrent calls apply in order, validated against the schema, and emit `state_changed` with the changed keys.
 
 ```typescript
-await harness.session.state.set({ yolo: true })
+await agentController.session.state.set({ yolo: true })
 ```
 
 ### `session.state.update(updater)`
@@ -559,7 +565,7 @@ await harness.session.state.set({ yolo: true })
 Run an updater against the current snapshot and apply its result atomically within the write queue. Use this for read-modify-write changes that must see the latest state. The updater returns `updates` to merge, optional `events` to emit, and a `result` value that `update()` resolves to.
 
 ```typescript
-const added = await harness.session.state.update(current => ({
+const added = await agentController.session.state.update(current => ({
   updates: { count: (current.count ?? 0) + 1 },
   result: (current.count ?? 0) + 1,
 }))
@@ -574,13 +580,13 @@ Sessions carry scoping tags (e.g. `{ projectPath }`) seeded at creation and stam
 Return a copy of the session's scoping tags. Empty object when the session is unscoped.
 
 ```typescript
-const tags = harness.session.getTags()
+const tags = agentController.session.getTags()
 // { projectPath: '/my/project' }
 ```
 
 ## Related
 
-- [Harness class](https://mastra.ai/reference/harness/harness-class)
-- [Harness overview](https://mastra.ai/docs/harness/overview)
-- [Threads and state](https://mastra.ai/docs/harness/threads-and-state)
-- [Tool approvals](https://mastra.ai/docs/harness/tool-approvals)
+- [AgentController class](https://mastra.ai/reference/agent-controller/agent-controller-class)
+- [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)

package/.docs/reference/agents/channels.md

@@ -2,7 +2,7 @@
 
 **Added in:** `@mastra/core@1.22.0`
 
-Channels connect agents to messaging platforms. Configure them via the `channels` property on the `Agent` constructor. See the [Channels guide](https://mastra.ai/docs/agents/channels) for concepts and platform setup instructions.
+Channels connect agents to messaging platforms. Configure them via the `channels` property on the `Agent` constructor. The object you pass is a `ChannelConfig`. See the [Channels guide](https://mastra.ai/docs/agents/channels) for concepts and platform setup instructions.
 
 ## Usage example
 
@@ -27,6 +27,8 @@ export const supportAgent = new Agent({
 
 ## Parameters
 
+The `channels` property accepts a `ChannelConfig` object with the following fields:
+
 **adapters** (`Record<string, Adapter | ChannelAdapterConfig>`): Platform adapters keyed by name (e.g. \`slack\`, \`discord\`). Pass an \`Adapter\` directly for defaults, or a \`ChannelAdapterConfig\` object to customize per-adapter options.
 
 **handlers** (`ChannelHandlers`): Override default message handlers for DMs, mentions, and subscribed threads.