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

package/.docs/reference/channels/slack-provider.md

@@ -0,0 +1,226 @@
+# SlackProvider
+
+`SlackProvider` is the managed path for connecting agents to Slack. Register it on `Mastra.channels` and it provisions Slack apps via the Manifest API, runs the OAuth install flow, rotates configuration tokens, and routes Slack events to your agents. Use it when you want Mastra to own app creation and installation. For the lower-level path where you create the Slack app and configure scopes and webhooks yourself, use [`createSlackAdapter`](https://mastra.ai/docs/agents/channels) on the agent's `channels.adapters` instead.
+
+## Usage example
+
+Register the provider on the `Mastra` constructor. The refresh token is single-use and rotates on startup; the resulting access tokens are persisted to `Mastra.storage`.
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { SlackProvider } from '@mastra/slack'
+
+export const mastra = new Mastra({
+  storage,
+  channels: {
+    slack: new SlackProvider({
+      refreshToken: process.env.SLACK_APP_CONFIG_REFRESH_TOKEN,
+      baseUrl: process.env.MASTRA_BASE_URL,
+    }),
+  },
+})
+```
+
+When credentials aren't available at construction time (for example, entered through the Editor UI or loaded from a vault), construct the provider without them and call [`configure()`](#configurecredentials) later:
+
+```typescript
+const slack = new SlackProvider()
+
+await slack.configure({
+  refreshToken: process.env.SLACK_APP_CONFIG_REFRESH_TOKEN,
+})
+```
+
+## Constructor parameters
+
+`SlackProviderConfig` combines Slack-specific fields, Slack-adapter overrides (`toolDisplay`, `streaming`, `typingStatus`), and a curated subset of [`ChannelConfig`](https://mastra.ai/reference/agents/channels) options (such as `handlers`, `inlineMedia`, and `state`) forwarded to every connected agent. All fields are optional.
+
+**refreshToken** (`string`): Slack App Configuration refresh token, used for automatic token rotation. Single-use; each rotation returns a new pair. Can also be provided later via \`configure()\`. If omitted, the provider starts unconfigured and cannot create apps until \`configure()\` is called or tokens are loaded from storage. Generate it under "Your App Configuration Tokens" at api.slack.com/apps.
+
+**token** (`string`): Slack App Configuration access token for programmatic app creation. Optional, because the provider rotates to a fresh token on startup using \`refreshToken\`.
+
+**baseUrl** (`string`): Public base URL for webhook and OAuth callbacks. Required when calling \`connect()\` to create apps. Can also be set via \`setBaseUrl()\` or auto-detected from the Mastra server config. For local development, use a tunnel such as \`cloudflared\`.
+
+**encryptionKey** (`string`): Encryption key for sensitive stored data (client secret, signing secret, bot token). Use a 32+ character random string. Can be set via the \`MASTRA\_ENCRYPTION\_KEY\` env var. If omitted, secrets are stored in plaintext (not recommended for production).
+
+**storage** (`ChannelsStorage`): Custom storage for installations. Defaults to Mastra's \`ChannelsStorage\` from the global storage. Throws if no persistent storage is available.
+
+**redirectPath** (`string`): Path to redirect to after OAuth completion. (Default: `"/"`)
+
+**onInstall** (`(installation: SlackInstallation) => Promise<void>`): Called when a workspace successfully installs the app.
+
+**streaming** (`StreamingConfig | false`): Stream agent text deltas to Slack as they're generated. Pass \`{ updateIntervalMs }\` to customize the post-and-edit interval, or \`false\` to buffer text until step-finish. Disabling streaming restricts \`toolDisplay\` to static modes. (Default: `true`)
+
+**toolDisplay** (`ToolDisplay`): How tool calls are rendered in Slack: \`'cards'\`, \`'text'\`, \`'timeline'\`, \`'grouped'\`, \`'hidden'\`, or a function. \`'hidden'\` suppresses tool call/result rendering entirely. \`'timeline'\` and \`'grouped'\` require streaming. With \`streaming: false\`, only static modes are available and the default is \`'cards'\`. (Default: `'grouped'`)
+
+**typingStatus** (`boolean | TypingStatusFn`): Show a typing indicator while the agent works. Set \`false\` to disable, or pass a function to return custom status text per stream chunk (return \`undefined\` to fall back to the default for that chunk). (Default: `true`)
+
+**waitUntil** (`WaitUntilFn`): Returns a \`waitUntil\` for the current Slack webhook request. Required on serverless runtimes where Hono can't bridge the platform's \`ExecutionContext\` (Vercel, AWS Lambda). Without it, the invocation freezes after the 200 ack and kills the run mid-flight. Pass the bare \`waitUntil(promise)\` from your platform SDK (for example, \`@vercel/functions\`). Cloudflare Workers and Netlify users typically don't need this.
+
+**resolveWaitUntil** (`WaitUntilResolver`): Resolve \`waitUntil\` from the request's Hono \`Context\` when the runtime exposes it through the request and core's default doesn't cover it. Resolution order: \`waitUntil\` → \`resolveWaitUntil\` → core default.
+
+**handlers** (`ChannelHandlers`): Override built-in event handlers (\`onDirectMessage\`, \`onMention\`). Forwarded to \`AgentChannels\` for every agent connected via this provider.
+
+**inlineMedia** (`ChannelConfig['inlineMedia']`): Which media types to send inline to the model.
+
+**inlineLinks** (`ChannelConfig['inlineLinks']`): Promote URLs in message text to file parts.
+
+**threadContext** (`ChannelConfig['threadContext']`): Fetch recent thread messages from Slack when the agent joins mid-conversation.
+
+**tools** (`ChannelConfig['tools']`): Whether to include channel tools (\`add\_reaction\`, \`remove\_reaction\`).
+
+**state** (`ChannelConfig['state']`): State adapter for message deduplication, locking, and subscriptions. Defaults to the \`MastraStateAdapter\` backed by the Mastra instance's configured storage, so subscriptions persist across restarts.
+
+**chatOptions** (`ChannelConfig['chatOptions']`): Additional options passed directly to the Chat SDK.
+
+**logger** (`SlackAdapterConfig['logger']`): Logger forwarded to the underlying \`SlackAdapter\`. Defaults to the adapter's \`ConsoleLogger\`.
+
+## Methods
+
+### Agent connections
+
+#### `connect(agentId, options?)`
+
+Creates a new Slack app for the agent via the Manifest API and returns an OAuth result with the authorization URL to redirect the user to. Requires `baseUrl` to be set. If a pending installation already exists for the agent, returns its existing authorization URL instead of creating a duplicate app.
+
+```typescript
+const result = await slack.connect('support-agent', {
+  name: 'Support Bot',
+})
+
+// Redirect the user to result.authorizationUrl to install the app
+```
+
+Returns: `Promise<ChannelConnectResult>`
+
+```typescript
+interface ChannelConnectResult {
+  type: 'oauth'
+  installationId: string
+  authorizationUrl: string
+}
+```
+
+`SlackConnectOptions` is serializable and can be stored for stored agents:
+
+**name** (`string`): Display name for the Slack bot. Defaults to the agent name, then the agent ID.
+
+**description** (`string`): Bot description shown in Slack. Defaults to "{name} - Powered by Mastra".
+
+**iconUrl** (`string`): URL to a square image (min 512x512) for the app icon. Downloaded and uploaded to Slack automatically.
+
+**manifest** (`(defaults: SlackAppManifest) => SlackAppManifest`): Customize the Slack app manifest before it is sent to the Manifest API. Receives the default manifest and returns the final one. Use it for custom scopes, additional events, or interactivity settings.
+
+**redirectUrl** (`string`): URL to redirect to after successful OAuth completion. Defaults to the provider's \`redirectPath\` or \`/\`.
+
+#### `disconnect(agentId)`
+
+Disconnects an agent from Slack by deleting its app and removing the installation from storage.
+
+```typescript
+await slack.disconnect('support-agent')
+```
+
+Returns: `Promise<void>`
+
+#### `getInstallation(agentId)`
+
+Returns the Slack installation for an agent, or `null` if none exists.
+
+```typescript
+const installation = await slack.getInstallation('support-agent')
+```
+
+Returns: `Promise<SlackInstallation | null>`
+
+#### `listInstallations()`
+
+Lists all Slack installations (public info only), including active and pending.
+
+```typescript
+const installations = await slack.listInstallations()
+```
+
+Returns: `Promise<ChannelInstallationInfo[]>`
+
+### Configuration
+
+#### `configure(credentials)`
+
+Provides or clears Slack App Configuration credentials at runtime. Use this when credentials aren't available at construction time. Pass `null` to clear credentials and delete stored tokens.
+
+```typescript
+// Provide credentials (persists to storage immediately)
+await slack.configure({ refreshToken: 'xoxe-1-...' })
+
+// Clear credentials and stored tokens
+await slack.configure(null)
+```
+
+Returns: `Promise<void>`
+
+#### `setBaseUrl(baseUrl)`
+
+Sets the public base URL used for webhook and OAuth callbacks. Use this when the URL isn't known at construction time and can't be auto-detected from the server config.
+
+```typescript
+slack.setBaseUrl('https://abc123.trycloudflare.com')
+```
+
+#### `initialize()`
+
+Recreates a `SlackAdapter` for each active installation in storage and injects `AgentChannels` into the corresponding agent so it receives Slack events on startup. Does not auto-provision new apps; use `connect()` to create one. Mastra calls this automatically, so you rarely call it directly.
+
+```typescript
+await slack.initialize()
+```
+
+Returns: `Promise<void>`
+
+## Default manifest
+
+When `connect()` builds a Slack app, the generated manifest requests a default set of bot scopes and event subscriptions. Override them with the `manifest` option on `connect()`.
+
+| Default bot scopes  | Default bot events |
+| ------------------- | ------------------ |
+| `chat:write`        | `app_mention`      |
+| `chat:write.public` | `message.channels` |
+| `im:write`          | `message.groups`   |
+| `channels:history`  | `message.im`       |
+| `channels:read`     | `message.mpim`     |
+| `groups:history`    |                    |
+| `groups:read`       |                    |
+| `im:history`        |                    |
+| `im:read`           |                    |
+| `mpim:history`      |                    |
+| `mpim:read`         |                    |
+| `app_mentions:read` |                    |
+| `users:read`        |                    |
+| `reactions:write`   |                    |
+| `files:read`        |                    |
+| `assistant:write`   |                    |
+
+## Accessing the provider
+
+Access the registered provider through the typed `channels` getter, keyed by the id you registered it under:
+
+```typescript
+const result = await mastra.channels.slack.connect('support-agent')
+```
+
+When the key is only known at runtime, look it up by string id and pass the concrete type:
+
+```typescript
+const slack = mastra.getChannelProvider<SlackProvider>('slack')
+const result = await slack.connect('support-agent')
+```
+
+## Storage requirement
+
+`SlackProvider` requires persistent storage on `Mastra` to encrypt and persist installations and rotating configuration tokens. The constructor throws if no persistent storage is available and no custom `storage` is passed.
+
+## Related
+
+- [ChannelProvider](https://mastra.ai/reference/channels/channel-provider): the interface `SlackProvider` implements
+- [Channels](https://mastra.ai/docs/agents/channels): concepts, platform setup, and the `createSlackAdapter` path
+- [Channels reference](https://mastra.ai/reference/agents/channels): the `channels` config on the `Agent` constructor

package/.docs/reference/index.md

@@ -4,6 +4,8 @@ The Reference section provides documentation of Mastra's API, including paramete
 
 - [AcpAgent](https://mastra.ai/reference/acp/acp-agent)
 - [createACPTool()](https://mastra.ai/reference/acp/create-acp-tool)
+- [AgentController Class](https://mastra.ai/reference/agent-controller/agent-controller-class)
+- [Session Class](https://mastra.ai/reference/agent-controller/session)
 - [Agent Class](https://mastra.ai/reference/agents/agent)
 - [Channels](https://mastra.ai/reference/agents/channels)
 - [createInngestAgent()](https://mastra.ai/reference/agents/inngest-agent)
@@ -45,6 +47,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [Better Auth](https://mastra.ai/reference/auth/better-auth)
 - [Clerk](https://mastra.ai/reference/auth/clerk)
 - [Firebase](https://mastra.ai/reference/auth/firebase)
+- [Google](https://mastra.ai/reference/auth/google)
 - [JSON Web Token](https://mastra.ai/reference/auth/jwt)
 - [Okta](https://mastra.ai/reference/auth/okta)
 - [Supabase](https://mastra.ai/reference/auth/supabase)
@@ -53,6 +56,8 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [BrowserViewer](https://mastra.ai/reference/browser/browser-viewer)
 - [MastraBrowser Class](https://mastra.ai/reference/browser/mastra-browser)
 - [StagehandBrowser](https://mastra.ai/reference/browser/stagehand-browser)
+- [ChannelProvider](https://mastra.ai/reference/channels/channel-provider)
+- [SlackProvider](https://mastra.ai/reference/channels/slack-provider)
 - [create-mastra](https://mastra.ai/reference/cli/create-mastra)
 - [mastra](https://mastra.ai/reference/cli/mastra)
 - [Agent Builder API](https://mastra.ai/reference/client-js/agent-builder)
@@ -164,8 +169,6 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.startExperimentAsync()](https://mastra.ai/reference/datasets/startExperimentAsync)
 - [.update()](https://mastra.ai/reference/datasets/update)
 - [.updateItem()](https://mastra.ai/reference/datasets/updateItem)
-- [Harness Class](https://mastra.ai/reference/harness/harness-class)
-- [Session Class](https://mastra.ai/reference/harness/session)
 - [API Reference](https://mastra.ai/reference/mastra-platform/api)
 - [Cloned Thread Utilities](https://mastra.ai/reference/memory/clone-utilities)
 - [Memory Class](https://mastra.ai/reference/memory/memory-class)

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @mastra/mcp-docs-server
 
+## 1.2.3-alpha.0
+
+### Patch Changes
+
+- Updated dependencies [[`b9a2961`](https://github.com/mastra-ai/mastra/commit/b9a2961c1be81e3639c0879e58588c26dd0ae866), [`1274eb3`](https://github.com/mastra-ai/mastra/commit/1274eb3a9508f579ceb3187fbce34408222d4b71), [`1274eb3`](https://github.com/mastra-ai/mastra/commit/1274eb3a9508f579ceb3187fbce34408222d4b71), [`9566d27`](https://github.com/mastra-ai/mastra/commit/9566d27ead3d95bdbe5a69e5a082a68222829cf2)]:
+  - @mastra/core@1.48.0-alpha.0
+
+## 1.2.2
+
+### Patch Changes
+
+- Updated dependencies [[`86623c1`](https://github.com/mastra-ai/mastra/commit/86623c1adf7d22de32cc916dda17f4155184db36), [`023766f`](https://github.com/mastra-ai/mastra/commit/023766f44d59b30a50f3a381e33eddde8ab56c00), [`0200e75`](https://github.com/mastra-ai/mastra/commit/0200e7552d02d4221cd6040bf4eddf189a97a156), [`7c9dd77`](https://github.com/mastra-ai/mastra/commit/7c9dd77bd18cb8dc72797e25f1a0fbdc71a11347), [`7f9ae70`](https://github.com/mastra-ai/mastra/commit/7f9ae70826b047e5a66218f9e92f20e54a2d791f), [`a0509c7`](https://github.com/mastra-ai/mastra/commit/a0509c731a08aa3ed626557c5338126362856f57), [`06e0d63`](https://github.com/mastra-ai/mastra/commit/06e0d63d42bc2a202e18bc091f3781f409f5e6fb), [`bf3fe49`](https://github.com/mastra-ai/mastra/commit/bf3fe49f9467dbbdb8f9eaf74e0f7971ffb19559), [`01caf93`](https://github.com/mastra-ai/mastra/commit/01caf93d71ae2c1e65f49735cafb531975187426), [`438a971`](https://github.com/mastra-ai/mastra/commit/438a9715c8b4398e5eaf8914a1f19dc8a85dc1de), [`9990965`](https://github.com/mastra-ai/mastra/commit/999096571635a83b42ef40841fd7028cfa630779), [`77518cc`](https://github.com/mastra-ai/mastra/commit/77518ccb5bb8cc684875081e64213dc85cffdbee), [`fbeda0c`](https://github.com/mastra-ai/mastra/commit/fbeda0c0f35def07e6837936dd3a003b2b7c5172), [`8a68844`](https://github.com/mastra-ai/mastra/commit/8a688443013816105a09f89c6afa34b5ff13e26d), [`bb2a13b`](https://github.com/mastra-ai/mastra/commit/bb2a13bb4b32e6bb807200fe7b18ae8fa4322118), [`24ceaea`](https://github.com/mastra-ai/mastra/commit/24ceaea0bdd8609cabbab764380608ca6621a194), [`a73cd1a`](https://github.com/mastra-ai/mastra/commit/a73cd1a62a5e4ca023dcc39ba150029f4f1f74c1), [`c0ffa3c`](https://github.com/mastra-ai/mastra/commit/c0ffa3c897ccd326de880df734740a7f0681a18f), [`462a769`](https://github.com/mastra-ai/mastra/commit/462a769da61850862ca1be3d74134d33078ee6a7), [`0504bf5`](https://github.com/mastra-ai/mastra/commit/0504bf5e8cffc571a4b343326178de371e6f859b), [`0b5cc47`](https://github.com/mastra-ai/mastra/commit/0b5cc4726dc18d9a685a27520db39ff1b36bb89a), [`87f38a3`](https://github.com/mastra-ai/mastra/commit/87f38a3de03e24731f2dd6f8ed6a60b6722b85a1), [`d5fa3cd`](https://github.com/mastra-ai/mastra/commit/d5fa3cda1788c3cb93a361a3c6ec47de6ba21e98), [`fe98ef2`](https://github.com/mastra-ai/mastra/commit/fe98ef2e66dbfcbd7d645c88c9ee1e67b458a136), [`6ccf67b`](https://github.com/mastra-ai/mastra/commit/6ccf67bf075753754927a57bc2e1734ba2c820c5), [`793ea0f`](https://github.com/mastra-ai/mastra/commit/793ea0f52f831178837f21c83af6af93bf4ce638), [`825d8de`](https://github.com/mastra-ai/mastra/commit/825d8def9fa64c2bcc3d8dd6b49e09342c3ac5c7), [`507a5c4`](https://github.com/mastra-ai/mastra/commit/507a5c461bdc3136ad80744c0efbb55ce1f18f97), [`5afe423`](https://github.com/mastra-ai/mastra/commit/5afe423e4badf040f1b0d4525183a856fcb8146e), [`307573b`](https://github.com/mastra-ai/mastra/commit/307573b9ff3149b70c79540dbc86f1319b180f29), [`79b3626`](https://github.com/mastra-ai/mastra/commit/79b3626f8d647307eb07c8da14c9073c2699719d), [`c2c1d7b`](https://github.com/mastra-ai/mastra/commit/c2c1d7bb61d2602955f14ed3952f807c2d6eb576), [`86623c1`](https://github.com/mastra-ai/mastra/commit/86623c1adf7d22de32cc916dda17f4155184db36), [`1505c07`](https://github.com/mastra-ai/mastra/commit/1505c07603f6346bae12aa82f140e8b88ffea9ab), [`f328049`](https://github.com/mastra-ai/mastra/commit/f3280498c324afd2a8d36cd828f5b9f94a2dddc1), [`e545228`](https://github.com/mastra-ai/mastra/commit/e54522856934a5dc030b7b6385771e3548020d59), [`3eb852e`](https://github.com/mastra-ai/mastra/commit/3eb852e5435bc908b800193498103dc724f455b0), [`ffa09e7`](https://github.com/mastra-ai/mastra/commit/ffa09e772a5c92270eabe2090fc42d45bd8ec4b7), [`8c9f1c0`](https://github.com/mastra-ai/mastra/commit/8c9f1c0361d89066f9bcd14a2f69e761b01766c8), [`461a7c5`](https://github.com/mastra-ai/mastra/commit/461a7c501449295287f4f0ee4b0b42344f39fcf8), [`4211472`](https://github.com/mastra-ai/mastra/commit/4211472a5a2bd319c60cd2e42d9109c3eef7ac1c), [`9e45902`](https://github.com/mastra-ai/mastra/commit/9e4590208e745055cecca202e2db0e5c65e17d3c), [`5c0df77`](https://github.com/mastra-ai/mastra/commit/5c0df776c40efa420f8c07a2f3ee66010296618e), [`e940f09`](https://github.com/mastra-ai/mastra/commit/e940f099ef5d18b403e6f2b4937e086a4da857b1)]:
+  - @mastra/core@1.47.0
+
+## 1.2.2-alpha.12
+
+### Patch Changes
+
+- Updated dependencies [[`8a68844`](https://github.com/mastra-ai/mastra/commit/8a688443013816105a09f89c6afa34b5ff13e26d)]:
+  - @mastra/core@1.47.0-alpha.7
+
+## 1.2.2-alpha.10
+
+### Patch Changes
+
+- Updated dependencies [[`0200e75`](https://github.com/mastra-ai/mastra/commit/0200e7552d02d4221cd6040bf4eddf189a97a156), [`06e0d63`](https://github.com/mastra-ai/mastra/commit/06e0d63d42bc2a202e18bc091f3781f409f5e6fb), [`438a971`](https://github.com/mastra-ai/mastra/commit/438a9715c8b4398e5eaf8914a1f19dc8a85dc1de), [`77518cc`](https://github.com/mastra-ai/mastra/commit/77518ccb5bb8cc684875081e64213dc85cffdbee), [`bb2a13b`](https://github.com/mastra-ai/mastra/commit/bb2a13bb4b32e6bb807200fe7b18ae8fa4322118), [`a73cd1a`](https://github.com/mastra-ai/mastra/commit/a73cd1a62a5e4ca023dcc39ba150029f4f1f74c1), [`0b5cc47`](https://github.com/mastra-ai/mastra/commit/0b5cc4726dc18d9a685a27520db39ff1b36bb89a), [`87f38a3`](https://github.com/mastra-ai/mastra/commit/87f38a3de03e24731f2dd6f8ed6a60b6722b85a1), [`d5fa3cd`](https://github.com/mastra-ai/mastra/commit/d5fa3cda1788c3cb93a361a3c6ec47de6ba21e98), [`fe98ef2`](https://github.com/mastra-ai/mastra/commit/fe98ef2e66dbfcbd7d645c88c9ee1e67b458a136), [`793ea0f`](https://github.com/mastra-ai/mastra/commit/793ea0f52f831178837f21c83af6af93bf4ce638), [`507a5c4`](https://github.com/mastra-ai/mastra/commit/507a5c461bdc3136ad80744c0efbb55ce1f18f97), [`79b3626`](https://github.com/mastra-ai/mastra/commit/79b3626f8d647307eb07c8da14c9073c2699719d)]:
+  - @mastra/core@1.47.0-alpha.6
+
 ## 1.2.2-alpha.8
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.2-alpha.9",
+  "version": "1.2.3-alpha.1",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -28,8 +28,8 @@
     "jsdom": "^26.1.0",
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
-    "@mastra/core": "1.47.0-alpha.5",
-    "@mastra/mcp": "^1.12.0"
+    "@mastra/mcp": "^1.12.0",
+    "@mastra/core": "1.48.0-alpha.0"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -45,9 +45,9 @@
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
     "vitest": "4.1.8",
-    "@internal/lint": "0.0.108",
-    "@internal/types-builder": "0.0.83",
-    "@mastra/core": "1.47.0-alpha.5"
+    "@internal/types-builder": "0.0.84",
+    "@internal/lint": "0.0.109",
+    "@mastra/core": "1.48.0-alpha.0"
   },
   "homepage": "https://mastra.ai",
   "repository": {

package/.docs/docs/harness/overview.md

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

package/.docs/docs/harness/session.md

@@ -1,143 +0,0 @@
-# Session
-
-A [`Session`](https://mastra.ai/reference/harness/session) holds the live state of a Harness: who the session is for, which thread is active, the selected mode and model, permission grants, queued follow-ups, token usage, application state, and the display snapshot. You reach it through `harness.session`.
-
-## What the Session tracks
-
-The Session is the live state of a single user's interaction with the Harness. It answers "what is true right now": who the session belongs to, which thread is currently bound, which mode and model are selected, what the user has approved, what's queued or running, the 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 Harness owns the shared infrastructure every session runs on.
-
-Because each session has its own identity and state, one Harness can serve many users at once — each backed by its own Session — without one session's mode, grants, or active thread leaking into another.
-
-The rest of this page walks through the Session's state. Each part is a focused sub-object on `harness.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 Harness 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 = harness.session.identity.getId()
-const ownerId = harness.session.identity.getOwnerId()
-const resourceId = harness.session.identity.getResourceId()
-const threadId = harness.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 [`harness.createSession()`](https://mastra.ai/reference/harness/harness-class) and defaults to the harness `id`. See [Resource IDs](https://mastra.ai/docs/harness/threads-and-state) for how it scopes threads.
-
-## Thread
-
-`session.thread` owns the active thread binding and read access to threads and messages. The Harness performs lifecycle transitions; the Session reads the result:
-
-```typescript
-// Lifecycle transitions live on the Harness
-await harness.switchThread({ threadId: 'thread-abc123' })
-
-// Reads live on the Session
-const threads = await harness.session.thread.list()
-const messages = await harness.session.thread.listActiveMessages()
-```
-
-See [Threads and state](https://mastra.ai/docs/harness/threads-and-state) for the full lifecycle.
-
-## Mode and model
-
-The Harness 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 harness.session.mode.switch({ modeId: 'build' })
-
-// Read the current selection (Session state)
-const modeId = harness.session.mode.get()
-const mode = harness.session.mode.resolve()
-const modelId = harness.session.model.get()
-```
-
-See [Modes](https://mastra.ai/docs/harness/modes) for how modes carry their own model.
-
-## Permission grants
-
-The Harness 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
-harness.session.grantCategory('edit')
-harness.session.grantTool('mastra_workspace_execute_command')
-
-// Inspect current grants
-const grants = harness.session.getGrants()
-```
-
-Grants are intentionally in-memory and reset when the session restarts. See [Tool approvals](https://mastra.ai/docs/harness/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 (harness.session.run.isRunning()) {
-  // show a stop button
-}
-
-// Abort the active run (Harness orchestration clears related state)
-harness.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 = harness.session.followUps.count()
-```
-
-Queue a follow-up with `harness.followUp({ content })`. To redirect the agent mid-run instead of waiting, use `harness.steer({ content })`. Both build on [signals](https://mastra.ai/docs/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 Harness defines the shape with a `stateSchema`; the Session owns the live snapshot, validates updates against the schema, and emits `state_changed` on every write:
-
-```typescript
-const state = harness.session.state.get()
-await harness.session.state.set({ theme: 'light' })
-```
-
-See [Threads and state](https://mastra.ai/docs/harness/threads-and-state) for defining a schema.
-
-## Display state
-
-A conversation emits many fine-grained events: tokens streaming in, tools starting and finishing, approvals pending, tasks updating, token usage climbing. 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 `HarnessDisplayState` object and folds every harness event into it as it happens, so the snapshot always reflects the latest state. It captures everything a UI needs to render: whether the agent is running and what it's streaming, which tools and subagents are active, anything waiting on the user such as approvals, the current task list, and running totals like 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 Harness emits `display_state_changed` (fired after every other event):
-
-```typescript
-const snapshot = harness.session.displayState.get()
-
-// Re-render from the snapshot on every change
-harness.subscribe(event => {
-  if (event.type === 'display_state_changed') {
-    render(harness.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.
-
-> **Note:** Visit the [Session reference](https://mastra.ai/reference/harness/session) for the full list of sub-objects and method signatures.
-
-## Related
-
-- [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 reference](https://mastra.ai/reference/harness/session)