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

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

@@ -1,23 +1,23 @@
-# Harness class
+# AgentController 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.
 
-The `Harness` class orchestrates multiple agent modes, shared state, memory, and storage. It provides a control layer that a TUI or other UI can drive to manage threads, switch models and modes, send messages, handle tool approvals, and track events.
+The `AgentController` class orchestrates multiple agent modes, shared state, memory, and storage. It provides a control layer that a TUI or other UI can drive to manage threads, switch models and modes, send messages, handle tool approvals, and track events.
 
-Per-conversation state — identity, the active thread, mode and model selection, run state, grants, and the display snapshot — lives on the [`Session`](https://mastra.ai/reference/harness/session), accessed through `harness.session`.
+Per-conversation state — identity, the active thread, mode and model selection, run state, grants, and the display snapshot — lives on the [`Session`](https://mastra.ai/reference/agent-controller/session), accessed 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
 
-Import the `Harness` class and create a new instance with your agent, storage backend, and modes:
+Import the `AgentController` class and create a new instance with your agent, storage backend, and modes:
 
 ```typescript
-import { Harness } from '@mastra/core/harness'
+import { AgentController } from '@mastra/core/agent-controller'
 import { LibSQLStore } from '@mastra/libsql'
 import { z } from 'zod'
 
-const harness = new Harness({
+const agentController = new AgentController({
   id: 'my-coding-agent',
   agent: myAgent,
   storage: new LibSQLStore({ url: 'file:./data.db' }),
@@ -35,20 +35,20 @@ const harness = new Harness({
   ],
 })
 
-harness.subscribe(event => {
+agentController.subscribe(event => {
   if (event.type === 'message_update') {
     renderMessage(event.message)
   }
 })
 
-await harness.init()
-await harness.selectOrCreateThread()
-await harness.sendMessage({ content: 'Hello!' })
+await agentController.init()
+await agentController.selectOrCreateThread()
+await agentController.sendMessage({ content: 'Hello!' })
 ```
 
 ## Constructor parameters
 
-**id** (`string`): Unique identifier for this harness instance.
+**id** (`string`): Unique identifier for this agentController instance.
 
 **resourceId** (`string`): Resource ID for grouping threads (e.g., project identifier). Threads are scoped to this resource ID. Defaults to \`id\`.
 
@@ -60,13 +60,13 @@ await harness.sendMessage({ content: 'Hello!' })
 
 **memory** (`MastraMemory`): Memory configuration shared across all modes. Propagated to mode agents that don't have their own memory.
 
-**modes** (`HarnessMode[]`): Available agent modes. At least one mode is required. When a top-level \`agent\` is provided, each mode layers its own instructions and tool overrides on top of the shared agent.
+**modes** (`AgentControllerMode[]`): Available agent modes. At least one mode is required. When a top-level \`agent\` is provided, each mode layers its own instructions and tool overrides on top of the shared agent.
 
 **modes.id** (`string`): Unique identifier for this mode (e.g., \`"plan"\`, \`"build"\`).
 
 **modes.name** (`string`): Human-readable name for display.
 
-**modes.default** (`boolean`): Whether this is the default mode when the harness starts. Deprecated in favor of \`metadata.default\` or the top-level \`defaultModeId\`.
+**modes.default** (`boolean`): Whether this is the default mode when the agentController starts. Deprecated in favor of \`metadata.default\` or the top-level \`defaultModeId\`.
 
 **modes.defaultModelId** (`string`): Default model ID for this mode (e.g., \`"anthropic/claude-sonnet-4-20250514"\`). Used when no per-mode model has been explicitly selected.
 
@@ -98,7 +98,7 @@ await harness.sendMessage({ content: 'Hello!' })
 
 **browser** (`MastraBrowser | ((ctx) => MastraBrowser)`): Browser automation instance or a dynamic factory function. When omitted, each session created via createSession can provide its own browser.
 
-**subagents** (`HarnessSubagent[]`): Subagent definitions. When provided, the harness creates a built-in \`subagent\` tool that parent agents can call to spawn focused subagents.
+**subagents** (`AgentControllerSubagent[]`): Subagent definitions. When provided, the agentController creates a built-in \`subagent\` tool that parent agents can call to spawn focused subagents.
 
 **subagents.id** (`string`): Unique identifier for this subagent type (e.g., \`"explore"\`, \`"execute"\`).
 
@@ -110,7 +110,7 @@ await harness.sendMessage({ content: 'Hello!' })
 
 **subagents.tools** (`ToolsInput`): Tools this subagent has direct access to.
 
-**subagents.allowedHarnessTools** (`string[]`): Tool IDs from the harness's shared \`tools\` config. Merged with \`tools\` above to let subagents use a subset of harness tools.
+**subagents.allowedAgentControllerTools** (`string[]`): Tool IDs from the agentController's shared \`tools\` config. Merged with \`tools\` above to let subagents use a subset of agentController tools.
 
 **subagents.allowedWorkspaceTools** (`string[]`): Workspace tool names the subagent is allowed to use. Uses the exposed names (after any renames via workspace tool config). When set, workspace tools not in this list are hidden from the model. Non-workspace tools are never affected. When omitted, all workspace tools are visible.
 
@@ -120,17 +120,17 @@ await harness.sendMessage({ content: 'Hello!' })
 
 **subagents.stopWhen** (`LoopOptions['stopWhen']`): Optional stop condition for the spawned subagent.
 
-**subagents.forked** (`boolean`): When \`true\`, calls to this subagent default to forked mode: the subagent runs on a clone of the parent thread, reusing the parent agent’s instructions, tools, and model so the prompt-cache prefix stays intact. Requires \`memory\` to be configured. The subagent definition’s own \`instructions\`, \`tools\`, \`allowedHarnessTools\`, \`allowedWorkspaceTools\`, \`defaultModelId\`, \`maxSteps\`, and \`stopWhen\` are ignored in forked mode. Callers can still override per-invocation via \`forked: false\` in the \`subagent\` tool input. See the \[Forked subagents]\(#forked-subagents) section below for full semantics.
+**subagents.forked** (`boolean`): When \`true\`, calls to this subagent default to forked mode: the subagent runs on a clone of the parent thread, reusing the parent agent’s instructions, tools, and model so the prompt-cache prefix stays intact. Requires \`memory\` to be configured. The subagent definition’s own \`instructions\`, \`tools\`, \`allowedAgentControllerTools\`, \`allowedWorkspaceTools\`, \`defaultModelId\`, \`maxSteps\`, and \`stopWhen\` are ignored in forked mode. Callers can still override per-invocation via \`forked: false\` in the \`subagent\` tool input. See the \[Forked subagents]\(#forked-subagents) section below for full semantics.
 
 **resolveModel** (`(modelId: string) => MastraLanguageModel`): Converts a model ID string (e.g., \`"anthropic/claude-sonnet-4"\`) to a language model instance. Used by subagents and observational memory model resolution.
 
-**omConfig** (`HarnessOMConfig`): Default configuration for observational memory (observer/reflector model IDs and thresholds).
+**omConfig** (`AgentControllerOMConfig`): Default configuration for observational memory (observer/reflector model IDs and thresholds).
 
-**disableBuiltinTools** (`BuiltinToolId[]`): Built-in harness tool IDs to remove from the \`harnessBuiltIn\` toolset. Valid values are \`ask\_user\`, \`submit\_plan\`, \`task\_write\`, \`task\_update\`, \`task\_complete\`, \`task\_check\`, and \`subagent\`.
+**disableBuiltinTools** (`BuiltinToolId[]`): Built-in tool IDs to remove from the \`controllerBuiltIn\` toolset. Valid values are \`ask\_user\`, \`submit\_plan\`, \`task\_write\`, \`task\_update\`, \`task\_complete\`, \`task\_check\`, and \`subagent\`.
 
 **heartbeatHandlers** (`HeartbeatHandler[]`): Periodic background tasks started during \`init()\`. Use for gateway sync, cache refresh, and similar tasks.
 
-**idGenerator** (`() => string`): Custom ID generator for Harness-managed IDs such as threads and mode-run identifiers. (Default: `timestamp + random string`)
+**idGenerator** (`() => string`): Custom ID generator for AgentController-managed IDs such as threads and mode-run identifiers. (Default: `timestamp + random string`)
 
 **modelAuthChecker** (`ModelAuthChecker`): Custom auth checker for model providers. Return \`true\`/\`false\` to override the default environment variable check, or \`undefined\` to fall back to defaults.
 
@@ -152,7 +152,7 @@ await harness.sendMessage({ content: 'Hello!' })
 
 ## Properties
 
-**id** (`string`): Harness identifier, set at construction.
+**id** (`string`): AgentController identifier, set at construction.
 
 **session** (`Session`): The per-conversation state for the active conversation: identity, the active thread binding and reads, mode and model selection, run and abort state, the live stream, tool suspensions, follow-ups, approvals, permission grants, token usage, and the display-state snapshot. See the Session reference for the full API.
 
@@ -162,24 +162,24 @@ await harness.sendMessage({ content: 'Hello!' })
 
 #### `init()`
 
-Initialize the harness. Loads storage, initializes a static workspace (dynamic factory workspaces are resolved per-session during `createSession`), propagates memory and workspace to mode agents, and starts heartbeat handlers. Call this before using the harness.
+Initialize the agentController. Loads storage, initializes a static workspace (dynamic factory workspaces are resolved per-session during `createSession`), propagates memory and workspace to mode agents, and starts heartbeat handlers. Call this before using the agentController.
 
 ```typescript
-await harness.init()
+await agentController.init()
 ```
 
 #### `createSession({ id, ownerId, resourceId?, tags?, workspace?, browser?, requestContext? })`
 
-Create a new, fully-wired `Session` and bring it online. The session starts in the default mode with the seeded model, connects to the Harness's shared machinery (agent, storage/lock, config catalog), and has a current thread (the most recent thread for the resource, or a freshly created one). Call `init()` once before creating sessions so shared storage is ready.
+Create a new, fully-wired `Session` and bring it online. The session starts in the default mode with the seeded model, connects to the AgentController's shared machinery (agent, storage/lock, config catalog), and has a current thread (the most recent thread for the resource, or a freshly created one). Call `init()` once before creating sessions so shared storage is ready.
 
-The Harness owns no session of its own — every consumer creates its own session and drives all work through it. In a server or multiplayer setting, each request, thread, or user gets its own session, isolated from every other: independent event bus, mode, model, state, and current thread.
+The AgentController owns no session of its own — every consumer creates its own session and drives all work through it. In a server or multiplayer setting, each request, thread, or user gets its own session, isolated from every other: independent event bus, mode, model, state, and current thread.
 
 `id` and `ownerId` are required — they mirror `SessionRecord.id` and `SessionRecord.ownerId` and are stable for the life of the session. `resourceId` is optional and defaults to `config.resourceId` then `config.id`.
 
-Each session owns its own `Workspace` and `Browser` instance. When `workspace` is omitted, the Harness resolves its configured workspace (a static instance or a dynamic factory) and passes it to the session. Pass a `workspace` override to give a specific session a different workspace than the Harness default. The workspace is initialized during session creation; `workspace_ready` and `workspace_status_changed` events are emitted on the session bus after `init()` completes, and late subscribers receive a replay of the last workspace status.
+Each session owns its own `Workspace` and `Browser` instance. When `workspace` is omitted, the AgentController resolves its configured workspace (a static instance or a dynamic factory) and passes it to the session. Pass a `workspace` override to give a specific session a different workspace than the AgentController default. The workspace is initialized during session creation; `workspace_ready` and `workspace_status_changed` events are emitted on the session bus after `init()` completes, and late subscribers receive a replay of the last workspace status.
 
 ```typescript
-const session = await harness.createSession({
+const session = await agentController.createSession({
   id: 'session-xyz',
   ownerId: 'user-123',
 })
@@ -188,7 +188,7 @@ const session = await harness.createSession({
 You can also override the resource:
 
 ```typescript
-const session = await harness.createSession({
+const session = await agentController.createSession({
   id: 'session-xyz',
   ownerId: 'user-123',
   resourceId: 'project-abc',
@@ -198,7 +198,7 @@ const session = await harness.createSession({
 Override the workspace and browser for a specific session:
 
 ```typescript
-const session = await harness.createSession({
+const session = await agentController.createSession({
   id: 'session-xyz',
   ownerId: 'user-123',
   workspace: myWorkspace,
@@ -208,14 +208,14 @@ const session = await harness.createSession({
 
 `tags` scopes initial thread selection: a thread is a resume candidate only when its metadata matches every provided tag. This lets worktrees sharing a resourceId each resume their own thread (via a `projectPath` tag).
 
-Switching the resource ID via `harness.setResourceId()` changes only the resource ID, not `id` or `ownerId`. Read them through `session.identity.getId()` and `session.identity.getOwnerId()`.
+Switching the resource ID via `agentController.setResourceId()` changes only the resource ID, not `id` or `ownerId`. Read them through `session.identity.getId()` and `session.identity.getOwnerId()`.
 
 #### `selectOrCreateThread()`
 
 Select the most recent thread for the current resource, or create one if none exist. Loads thread metadata and acquires a thread lock.
 
 ```typescript
-const thread = await harness.selectOrCreateThread()
+const thread = await agentController.selectOrCreateThread()
 ```
 
 #### `destroy()`
@@ -223,7 +223,7 @@ const thread = await harness.selectOrCreateThread()
 Stop all heartbeat handlers and clean up resources.
 
 ```typescript
-await harness.destroy()
+await agentController.destroy()
 ```
 
 #### `removeHeartbeat({ id })`
@@ -231,7 +231,7 @@ await harness.destroy()
 Remove a specific heartbeat handler by ID. Calls the handler's `shutdown()` callback if defined.
 
 ```typescript
-await harness.removeHeartbeat({ id: 'gateway-sync' })
+await agentController.removeHeartbeat({ id: 'gateway-sync' })
 ```
 
 #### `stopHeartbeats()`
@@ -239,7 +239,7 @@ await harness.removeHeartbeat({ id: 'gateway-sync' })
 Stop and remove all heartbeat handlers.
 
 ```typescript
-await harness.stopHeartbeats()
+await agentController.stopHeartbeats()
 ```
 
 #### `getCurrentAgent()`
@@ -247,7 +247,7 @@ await harness.stopHeartbeats()
 Return the fully-configured Agent for the current mode with runtime services (storage, memory, workspace, pubsub, telemetry) propagated.
 
 ```typescript
-const agent = harness.getCurrentAgent()
+const agent = agentController.getCurrentAgent()
 ```
 
 #### `getResolvedMemory()`
@@ -255,7 +255,7 @@ const agent = harness.getCurrentAgent()
 Return the resolved memory instance, or `null` if no memory is configured.
 
 ```typescript
-const memory = await harness.getResolvedMemory()
+const memory = await agentController.getResolvedMemory()
 ```
 
 #### `getMastra()`
@@ -263,15 +263,15 @@ const memory = await harness.getResolvedMemory()
 Return the internal `Mastra` instance, or `undefined` before `init()`. Useful for scorer registration, observability access, and eval tooling.
 
 ```typescript
-const mastra = harness.getMastra()
+const mastra = agentController.getMastra()
 ```
 
 #### `getWorkspace()`
 
-Return the Harness-level workspace if it is a static `Workspace` instance. Dynamic factory workspaces are not resolved here — use [`resolveWorkspace()`](#resolveworkspace-session-requestcontext-) to resolve a factory against a session's request context.
+Return the AgentController-level workspace if it is a static `Workspace` instance. Dynamic factory workspaces are not resolved here — use [`resolveWorkspace()`](#resolveworkspace-session-requestcontext-) to resolve a factory against a session's request context.
 
 ```typescript
-const workspace = harness.getWorkspace()
+const workspace = agentController.getWorkspace()
 ```
 
 #### `resolveWorkspace({ session, requestContext? })`
@@ -279,31 +279,31 @@ const workspace = harness.getWorkspace()
 Eagerly resolve and cache the workspace. For dynamic workspaces (factory function), this triggers the factory against the given session's request context and caches the result so `getWorkspace()` returns it. Returns the resolved workspace or `undefined` if none is configured.
 
 ```typescript
-const workspace = await harness.resolveWorkspace({ session })
+const workspace = await agentController.resolveWorkspace({ session })
 ```
 
 ```typescript
 // With an explicit request context
 const requestContext = new RequestContext()
-const workspace = await harness.resolveWorkspace({ session, requestContext })
+const workspace = await agentController.resolveWorkspace({ session, requestContext })
 ```
 
 #### `hasWorkspace()`
 
-Whether a workspace is configured on this Harness (static instance or dynamic factory). Sessions without an explicit workspace override fall back to this.
+Whether a workspace is configured on this AgentController (static instance or dynamic factory). Sessions without an explicit workspace override fall back to this.
 
 ```typescript
-if (harness.hasWorkspace()) {
+if (agentController.hasWorkspace()) {
   // ...
 }
 ```
 
 #### `isWorkspaceReady()`
 
-Whether the Harness-level static workspace has been initialized. Dynamic factory workspaces are resolved and initialized per-session during `createSession`, so this returns `false` for factory configs until a session is created.
+Whether the AgentController-level static workspace has been initialized. Dynamic factory workspaces are resolved and initialized per-session during `createSession`, so this returns `false` for factory configs until a session is created.
 
 ```typescript
-if (harness.isWorkspaceReady()) {
+if (agentController.isWorkspaceReady()) {
   // ...
 }
 ```
@@ -312,24 +312,24 @@ if (harness.isWorkspaceReady()) {
 
 #### `listModes()`
 
-Return all configured `HarnessMode` instances.
+Return all configured `AgentControllerMode` instances.
 
 ```typescript
-const modes = harness.listModes()
+const modes = agentController.listModes()
 ```
 
-To read the active mode, use [`session.mode.get()`](https://mastra.ai/reference/harness/session); to resolve it to a full `HarnessMode`, use [`session.mode.resolve()`](https://mastra.ai/reference/harness/session).
+To read the active mode, use [`session.mode.get()`](https://mastra.ai/reference/agent-controller/session); to resolve it to a full `AgentControllerMode`, use [`session.mode.resolve()`](https://mastra.ai/reference/agent-controller/session).
 
 ### Models
 
-To read the active model ID, use [`session.model.get()`](https://mastra.ai/reference/harness/session); for a short display name, use [`session.model.displayName()`](https://mastra.ai/reference/harness/session); to check whether a model is selected, use [`session.model.hasSelection()`](https://mastra.ai/reference/harness/session).
+To read the active model ID, use [`session.model.get()`](https://mastra.ai/reference/agent-controller/session); for a short display name, use [`session.model.displayName()`](https://mastra.ai/reference/agent-controller/session); to check whether a model is selected, use [`session.model.hasSelection()`](https://mastra.ai/reference/agent-controller/session).
 
 #### `getCurrentModelAuthStatus()`
 
 Check if the current model's provider has authentication configured. Uses `modelAuthChecker` if provided, falling back to environment variable checks from the provider registry.
 
 ```typescript
-const status = await harness.getCurrentModelAuthStatus()
+const status = await agentController.getCurrentModelAuthStatus()
 // { hasAuth: true, apiKeyEnvVar: 'ANTHROPIC_API_KEY' }
 ```
 
@@ -338,20 +338,20 @@ const status = await harness.getCurrentModelAuthStatus()
 Retrieve all available models from the provider registry, including their authentication status and use counts.
 
 ```typescript
-const models = await harness.listAvailableModels()
+const models = await agentController.listAvailableModels()
 // [{ id, provider, modelName, hasApiKey, apiKeyEnvVar, useCount }]
 ```
 
 ### Threads
 
-The harness owns thread lifecycle transitions — creating, switching, cloning, renaming, and deleting threads — because they coordinate the shared thread lock and emit events. The active thread binding and thread/message reads live on [`session.thread`](https://mastra.ai/reference/harness/session).
+The agentController owns thread lifecycle transitions — creating, switching, cloning, renaming, and deleting threads — because they coordinate the shared thread lock and emit events. The active thread binding and thread/message reads live on [`session.thread`](https://mastra.ai/reference/agent-controller/session).
 
 #### `createThread({ title? })`
 
 Create a new thread. Initializes thread metadata, saves it to storage, acquires a thread lock, and emits a `thread_created` event.
 
 ```typescript
-const thread = await harness.createThread({ title: 'New conversation' })
+const thread = await agentController.createThread({ title: 'New conversation' })
 ```
 
 #### `switchThread({ threadId })`
@@ -359,17 +359,17 @@ const thread = await harness.createThread({ title: 'New conversation' })
 Switch to a different thread. Aborts any in-progress operations, acquires a lock on the new thread, releases the lock on the previous thread, loads the thread's metadata, and emits a `thread_changed` event.
 
 ```typescript
-await harness.switchThread({ threadId: 'thread-abc123' })
+await agentController.switchThread({ threadId: 'thread-abc123' })
 ```
 
-To list threads from storage, use [`session.thread.list()`](https://mastra.ai/reference/harness/session). By default it returns only threads for the current resource and hides transient [forked subagent](#forked-subagents) threads; pass `includeForkedSubagents: true` to opt back into seeing them — e.g. for a debug panel.
+To list threads from storage, use [`session.thread.list()`](https://mastra.ai/reference/agent-controller/session). By default it returns only threads for the current resource and hides transient [forked subagent](#forked-subagents) threads; pass `includeForkedSubagents: true` to opt back into seeing them — e.g. for a debug panel.
 
 #### `renameThread({ title })`
 
 Update the title of the current thread.
 
 ```typescript
-await harness.renameThread({ title: 'Updated title' })
+await agentController.renameThread({ title: 'Updated title' })
 ```
 
 #### `cloneThread({ sourceThreadId?, title?, resourceId? })`
@@ -378,10 +378,10 @@ Clone an existing thread and switch to the clone. Copies all messages, acquires
 
 ```typescript
 // Clone the current thread
-const cloned = await harness.cloneThread()
+const cloned = await agentController.cloneThread()
 
 // Clone a specific thread with a custom title
-const cloned = await harness.cloneThread({
+const cloned = await agentController.cloneThread({
   sourceThreadId: 'thread-abc123',
   title: 'Alternative approach',
 })
@@ -389,14 +389,14 @@ const cloned = await harness.cloneThread({
 
 See [`Memory.cloneThread()`](https://mastra.ai/reference/memory/cloneThread) for details on what gets cloned.
 
-To read the current resource ID, use [`session.identity.getResourceId()`](https://mastra.ai/reference/harness/session).
+To read the current resource ID, use [`session.identity.getResourceId()`](https://mastra.ai/reference/agent-controller/session).
 
 #### `setResourceId({ resourceId })`
 
 Set the resource ID and clear the current thread.
 
 ```typescript
-harness.setResourceId({ resourceId: 'project-xyz' })
+agentController.setResourceId({ resourceId: 'project-xyz' })
 ```
 
 #### `getKnownResourceIds()`
@@ -404,7 +404,7 @@ harness.setResourceId({ resourceId: 'project-xyz' })
 Return the distinct resource IDs that have threads in storage.
 
 ```typescript
-const resourceIds = await harness.getKnownResourceIds()
+const resourceIds = await agentController.getKnownResourceIds()
 ```
 
 #### `getSession()`
@@ -412,7 +412,7 @@ const resourceIds = await harness.getKnownResourceIds()
 Return current session information including thread ID, mode ID, and the list of threads.
 
 ```typescript
-const session = await harness.getSession()
+const session = await agentController.getSession()
 // { currentThreadId, currentModeId, threads }
 ```
 
@@ -420,24 +420,24 @@ const session = await harness.getSession()
 
 #### `sendMessage({ content, files?, requestContext? })`
 
-Send a message to the current agent. Creates a thread if none exists, builds a `RequestContext` and toolsets, and streams the agent's response. Handles tool calls, approvals, and errors automatically. If you provide `requestContext`, the harness forwards it to tools and subagents during the run.
+Send a message to the current agent. Creates a thread if none exists, builds a `RequestContext` and toolsets, and streams the agent's response. Handles tool calls, approvals, and errors automatically. If you provide `requestContext`, the agentController forwards it to tools and subagents during the run.
 
 ```typescript
-await harness.sendMessage({ content: 'Explain the authentication flow' })
+await agentController.sendMessage({ content: 'Explain the authentication flow' })
 ```
 
-Reading messages is owned by [`session.thread`](https://mastra.ai/reference/harness/session): use `listActiveMessages()` for the active thread, `listMessages({ threadId })` for a specific thread, and `firstUserMessage({ threadId })` / `firstUserMessages({ threadIds })` for thread previews.
+Reading messages is owned by [`session.thread`](https://mastra.ai/reference/agent-controller/session): use `listActiveMessages()` for the active thread, `listMessages({ threadId })` for a specific thread, and `firstUserMessage({ threadId })` / `firstUserMessages({ threadIds })` for thread previews.
 
 ### Memory
 
-The `memory` property bundles thread management operations into a single namespace. `memory.createThread`, `memory.switchThread`, and `memory.renameThread` delegate to the corresponding Harness lifecycle methods documented above; `memory.listThreads` delegates to [`session.thread.list()`](https://mastra.ai/reference/harness/session).
+The `memory` property bundles thread management operations into a single namespace. `memory.createThread`, `memory.switchThread`, and `memory.renameThread` delegate to the corresponding AgentController lifecycle methods documented above; `memory.listThreads` delegates to [`session.thread.list()`](https://mastra.ai/reference/agent-controller/session).
 
 #### `memory.deleteThread({ threadId })`
 
-Delete a thread and all its messages from storage. If the deleted thread is the currently active thread, the thread lock is released and the harness clears its active thread. Emits a `thread_deleted` event.
+Delete a thread and all its messages from storage. If the deleted thread is the currently active thread, the thread lock is released and the agentController clears its active thread. Emits a `thread_deleted` event.
 
 ```typescript
-await harness.memory.deleteThread({ threadId: 'thread-abc123' })
+await agentController.memory.deleteThread({ threadId: 'thread-abc123' })
 ```
 
 ### Flow control
@@ -447,7 +447,7 @@ await harness.memory.deleteThread({ threadId: 'thread-abc123' })
 Abort any in-progress generation.
 
 ```typescript
-harness.abort()
+agentController.abort()
 ```
 
 #### `steer({ content, requestContext? })`
@@ -455,7 +455,7 @@ harness.abort()
 Steer the agent mid-stream by injecting an instruction into the current generation.
 
 ```typescript
-harness.steer({ content: 'Focus on security implications' })
+agentController.steer({ content: 'Focus on security implications' })
 ```
 
 #### `followUp({ content, requestContext? })`
@@ -463,12 +463,12 @@ harness.steer({ content: 'Focus on security implications' })
 Queue a follow-up message to be sent after the current generation completes. If no operation is running, sends the message immediately.
 
 ```typescript
-harness.followUp({ content: 'Now apply those changes' })
+agentController.followUp({ content: 'Now apply those changes' })
 ```
 
 ### Tool approvals
 
-Responding to a pending tool approval is owned by the session — see [`session.respondToToolApproval()`](https://mastra.ai/reference/harness/session). The harness owns the permission _policy_ that decides when approval is required, documented under [Permissions](#permissions) below.
+Responding to a pending tool approval is owned by the session — see [`session.respondToToolApproval()`](https://mastra.ai/reference/agent-controller/session). The agentController owns the permission _policy_ that decides when approval is required, documented under [Permissions](#permissions) below.
 
 ### Tool suspensions and plans
 
@@ -479,11 +479,11 @@ Respond to a pending tool suspension. Interactive built-in tools such as `ask_us
 Provide `toolCallId` to select which suspension to resume. It is required when more than one tool is suspended at the same time (for example, parallel `ask_user` calls). When omitted, it resolves to the sole pending suspension.
 
 ```typescript
-harness.subscribe(event => {
+agentController.subscribe(event => {
   if (event.type === 'tool_suspended' && event.toolName === 'ask_user') {
     const { question } = event.suspendPayload as { question: string }
     // Show `question` to the user, then resume the tool with their answer.
-    harness.respondToToolSuspension({
+    agentController.respondToToolSuspension({
       toolCallId: event.toolCallId,
       resumeData: 'Yes, proceed with the refactor',
     })
@@ -494,7 +494,7 @@ harness.subscribe(event => {
 For multi-select questions, pass the selected option labels as a string array.
 
 ```typescript
-harness.respondToToolSuspension({
+agentController.respondToToolSuspension({
   toolCallId: event.toolCallId,
   resumeData: ['Add tests', 'Update docs'],
 })
@@ -504,14 +504,14 @@ harness.respondToToolSuspension({
 
 The `submit_plan` built-in tool pauses via the native tool-suspension primitive, so it surfaces through the same `tool_suspended` event as other interactive tools. Resume it with [`respondToToolSuspension`](#respondtotoolsuspension-resumedata-toolcallid-requestcontext-), passing a `resumeData` object with `action` (`'approved'` or `'rejected'`) and an optional `feedback` string.
 
-On approval, the Harness automatically switches to its default (execution) mode. On rejection, the plan-mode run resumes so the agent can revise and submit again.
+On approval, the AgentController automatically switches to its default (execution) mode. On rejection, the plan-mode run resumes so the agent can revise and submit again.
 
 ```typescript
-harness.respondToToolSuspension({
+agentController.respondToToolSuspension({
   toolCallId: event.toolCallId,
   resumeData: { action: 'approved' },
 })
-harness.respondToToolSuspension({
+agentController.respondToToolSuspension({
   toolCallId: event.toolCallId,
   resumeData: { action: 'rejected', feedback: 'Needs more detail' },
 })
@@ -524,7 +524,7 @@ harness.respondToToolSuspension({
 Resolve a tool's category using the configured `toolCategoryResolver`.
 
 ```typescript
-const category = harness.getToolCategory({ toolName: 'mastra_workspace_write_file' })
+const category = agentController.getToolCategory({ toolName: 'mastra_workspace_write_file' })
 // 'edit'
 ```
 
@@ -535,7 +535,7 @@ const category = harness.getToolCategory({ toolName: 'mastra_workspace_write_fil
 Load observational memory records for the current thread and emit an `om_status` event with reconstructed progress.
 
 ```typescript
-await harness.loadOMProgress()
+await agentController.loadOMProgress()
 ```
 
 #### `getObservationalMemoryRecord()`
@@ -543,7 +543,7 @@ await harness.loadOMProgress()
 Return the full `ObservationalMemoryRecord` for the current thread and resource, or `null` if no thread is selected or no record exists.
 
 ```typescript
-const record = await harness.getObservationalMemoryRecord()
+const record = await agentController.getObservationalMemoryRecord()
 
 if (record) {
   console.log(record.activeObservations)
@@ -552,7 +552,7 @@ if (record) {
 }
 ```
 
-The observer/reflector model selection and observation/reflection thresholds live on the Session under [`session.om`](https://mastra.ai/reference/harness/session), grouped by role. Read them with `session.om.observer.modelId()` / `session.om.reflector.modelId()` and `session.om.observer.threshold()` / `session.om.reflector.threshold()`, and change a role's model with `session.om.observer.switchModel()` / `session.om.reflector.switchModel()`.
+The observer/reflector model selection and observation/reflection thresholds live on the Session under [`session.om`](https://mastra.ai/reference/agent-controller/session), grouped by role. Read them with `session.om.observer.modelId()` / `session.om.reflector.modelId()` and `session.om.observer.threshold()` / `session.om.reflector.threshold()`, and change a role's model with `session.om.observer.switchModel()` / `session.om.reflector.switchModel()`.
 
 ### Forked subagents
 
@@ -560,11 +560,11 @@ By default, a subagent runs with a fresh context — it doesn't see the parent c
 
 #### Enabling forked mode
 
-Set `forked: true` either on the `HarnessSubagent` definition (per-type default) or on each `subagent` tool call (per-invocation override):
+Set `forked: true` either on the `AgentControllerSubagent` definition (per-type default) or on each `subagent` tool call (per-invocation override):
 
 ```typescript
 // Per-type default — every call to this subagent forks unless overridden.
-const subagents: HarnessSubagent[] = [
+const subagents: AgentControllerSubagent[] = [
   {
     id: 'collaborator',
     name: 'Collaborator',
@@ -579,10 +579,10 @@ The model can also pass `forked: true` (or `forked: false`) per-invocation in th
 
 #### Semantics and constraints
 
-- **Memory required.** Forked mode calls `memory.cloneThread` to create the fork, so the harness must have `memory` configured and an active parent thread. Calls without those return a structured error rather than throwing.
-- **Parent agent reused.** The fork runs through the parent agent's `stream(...)` call. The parent's instructions, tools, model, `maxSteps`, and `stopWhen` apply. The subagent definition's `instructions`, `tools`, `allowedHarnessTools`, `allowedWorkspaceTools`, `defaultModelId`, `maxSteps`, and `stopWhen` are ignored in forked mode — this is what preserves the prompt-cache prefix.
-- **Toolsets inherited, recursive forks blocked at runtime.** Forks inherit the parent's toolsets verbatim (`ask_user`, `submit_plan`, user-configured harness tools, _including the `subagent` tool itself_) so the LLM request prefix — system prompt + tool list + tool schemas + tool descriptions — stays byte-identical to the parent's. This is what preserves the prompt cache. The `subagent` entry is kept on the model side but its `execute` is replaced inside the fork with a stub that returns a non-error "tool unavailable inside a forked subagent" message: nested forks are blocked at the runtime layer without perturbing the cached prefix.
-- **Fork threads are tagged.** Each fork thread is created with `metadata.forkedSubagent === true` and `metadata.parentThreadId === <parent>`. By default, [`session.thread.list()`](https://mastra.ai/reference/harness/session) hides these so they don't show up in user-facing thread pickers / startup flows. Pass `includeForkedSubagents: true` to see them in admin / debug tooling.
+- **Memory required.** Forked mode calls `memory.cloneThread` to create the fork, so the agentController must have `memory` configured and an active parent thread. Calls without those return a structured error rather than throwing.
+- **Parent agent reused.** The fork runs through the parent agent's `stream(...)` call. The parent's instructions, tools, model, `maxSteps`, and `stopWhen` apply. The subagent definition's `instructions`, `tools`, `allowedAgentControllerTools`, `allowedWorkspaceTools`, `defaultModelId`, `maxSteps`, and `stopWhen` are ignored in forked mode — this is what preserves the prompt-cache prefix.
+- **Toolsets inherited, recursive forks blocked at runtime.** Forks inherit the parent's toolsets verbatim (`ask_user`, `submit_plan`, user-configured agentController tools, _including the `subagent` tool itself_) so the LLM request prefix — system prompt + tool list + tool schemas + tool descriptions — stays byte-identical to the parent's. This is what preserves the prompt cache. The `subagent` entry is kept on the model side but its `execute` is replaced inside the fork with a stub that returns a non-error "tool unavailable inside a forked subagent" message: nested forks are blocked at the runtime layer without perturbing the cached prefix.
+- **Fork threads are tagged.** Each fork thread is created with `metadata.forkedSubagent === true` and `metadata.parentThreadId === <parent>`. By default, [`session.thread.list()`](https://mastra.ai/reference/agent-controller/session) hides these so they don't show up in user-facing thread pickers / startup flows. Pass `includeForkedSubagents: true` to see them in admin / debug tooling.
 - **Save-queue flushed before clone.** The agent stream batches message saves through a debounced `SaveQueueManager`, so the parent's latest user / assistant turn may not be on disk yet when the subagent tool call fires. The fork tool flushes pending saves first via the `flushMessages` callback on `AgentToolExecutionContext` before cloning, so the fork actually carries the latest turn. Flush failures are non-fatal — the clone still runs.
 - **Parent thread untouched.** All subagent activity (messages, OM writes) lands on the fork. The parent thread is never appended to during a forked subagent run.
 
@@ -596,24 +596,24 @@ Forked mode trades isolation for context inheritance. If the subagent should run
 
 Register an event listener. Returns an unsubscribe function.
 
-Use this method for all consumers — UI, Server-Sent Events (SSE), terminal UI (TUI), bridge rendering, audit logs, debugging, analytics, and deterministic replay. For display rendering, watch for the `display_state_changed` event and read the latest snapshot from [`session.displayState.get()`](https://mastra.ai/reference/harness/session). 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.
+Use this method for all consumers — UI, Server-Sent Events (SSE), terminal UI (TUI), bridge rendering, audit logs, debugging, analytics, and deterministic replay. For display rendering, watch for the `display_state_changed` event and read the latest snapshot from [`session.displayState.get()`](https://mastra.ai/reference/agent-controller/session). 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.
 
 ```typescript
 // Render from the coalesced display-state snapshot:
-const unsubscribe = harness.subscribe(event => {
+const unsubscribe = agentController.subscribe(event => {
   if (event.type === 'display_state_changed') {
-    render(harness.session.displayState.get())
+    render(agentController.session.displayState.get())
   }
 })
 
-// Render an initial frame before the next harness event:
-render(harness.session.displayState.get())
+// Render an initial frame before the next agentController event:
+render(agentController.session.displayState.get())
 ```
 
 To handle raw events directly, switch on `event.type`:
 
 ```typescript
-const unsubscribe = harness.subscribe(event => {
+const unsubscribe = agentController.subscribe(event => {
   switch (event.type) {
     case 'message_update':
       renderMessage(event.message)
@@ -633,7 +633,7 @@ unsubscribe()
 
 ## Events
 
-The harness emits events through registered listeners. The following table lists the available event types:
+The agentController emits events through registered listeners. The following table lists the available event types:
 
 | Event type                 | Description                                                                                                                                                                                                                                                                               |
 | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -642,7 +642,7 @@ The harness emits events through registered listeners. The following table lists
 | `thread_changed`           | The active thread changed.                                                                                                                                                                                                                                                                |
 | `thread_created`           | A new thread was created.                                                                                                                                                                                                                                                                 |
 | `thread_deleted`           | A thread was deleted.                                                                                                                                                                                                                                                                     |
-| `state_changed`            | Harness state was updated.                                                                                                                                                                                                                                                                |
+| `state_changed`            | AgentController state was updated.                                                                                                                                                                                                                                                        |
 | `agent_start`              | The agent started processing.                                                                                                                                                                                                                                                             |
 | `agent_end`                | The agent finished processing.                                                                                                                                                                                                                                                            |
 | `message_start`            | A new message started streaming.                                                                                                                                                                                                                                                          |
@@ -690,13 +690,13 @@ The harness emits events through registered listeners. The following table lists
 | `task_updated`             | A task list was updated.                                                                                                                                                                                                                                                                  |
 | `goal_evaluation`          | A goal evaluation completed (when native agent goals are configured).                                                                                                                                                                                                                     |
 | `shell_output`             | A tool emitted shell output (stdout or stderr).                                                                                                                                                                                                                                           |
-| `display_state_changed`    | The canonical `HarnessDisplayState` snapshot changed. Read it from [`session.displayState.get()`](https://mastra.ai/reference/harness/session).                                                                                                                                           |
+| `display_state_changed`    | The canonical `AgentControllerDisplayState` snapshot changed. Read it from [`session.displayState.get()`](https://mastra.ai/reference/agent-controller/session).                                                                                                                          |
 
-The harness also emits low-level streaming content chunks — `text`, `thinking`, `tool_call`, `tool_result`, `image`, and `file`. These are the raw pieces that get assembled into messages; most UIs render from `message_update` (or read the [`session.displayState`](https://mastra.ai/reference/harness/session) snapshot) rather than subscribing to them directly.
+The agentController also emits low-level streaming content chunks — `text`, `thinking`, `tool_call`, `tool_result`, `image`, and `file`. These are the raw pieces that get assembled into messages; most UIs render from `message_update` (or read the [`session.displayState`](https://mastra.ai/reference/agent-controller/session) snapshot) rather than subscribing to them directly.
 
 ## Built-in tools
 
-The harness provides built-in tools to agents in every mode:
+The agentController provides built-in tools to agents in every mode:
 
 | Tool            | Description                                                                                                                                                                                          |
 | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -715,11 +715,11 @@ The `ask_user` tool accepts `options` for choice prompts. Set `selectionMode` to
 The following example demonstrates a multi-select response handler. The tool pauses through the `tool_suspended` event, the UI reads `selectionMode` from `event.suspendPayload`, lets the user choose multiple options, then returns a string array with `respondToToolSuspension()`.
 
 ```typescript
-harness.subscribe(event => {
+agentController.subscribe(event => {
   if (event.type === 'tool_suspended' && event.toolName === 'ask_user') {
     const { selectionMode } = event.suspendPayload as { selectionMode?: string }
     if (selectionMode === 'multi_select') {
-      harness.respondToToolSuspension({
+      agentController.respondToToolSuspension({
         toolCallId: event.toolCallId,
         resumeData: ['Add tests', 'Update docs'],
       })
@@ -730,7 +730,7 @@ harness.subscribe(event => {
 
 ## Related
 
-- [Session class](https://mastra.ai/reference/harness/session)
-- [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)
+- [Session class](https://mastra.ai/reference/agent-controller/session)
+- [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)