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

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)
@@ -54,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)
@@ -165,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)
@@ -209,6 +211,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [CachingPubSub](https://mastra.ai/reference/pubsub/caching-pubsub)
 - [EventEmitterPubSub](https://mastra.ai/reference/pubsub/event-emitter)
 - [GoogleCloudPubSub](https://mastra.ai/reference/pubsub/google-cloud-pubsub)
+- [LeaseProvider](https://mastra.ai/reference/pubsub/lease-provider)
 - [PubSub](https://mastra.ai/reference/pubsub/base)
 - [RedisStreamsPubSub](https://mastra.ai/reference/pubsub/redis-streams)
 - [UnixSocketPubSub](https://mastra.ai/reference/pubsub/unix-socket-pubsub)

package/.docs/reference/pubsub/lease-provider.md

@@ -0,0 +1,131 @@
+# LeaseProvider
+
+`LeaseProvider` is the distributed leasing contract, separate from event delivery ([`PubSub`](https://mastra.ai/reference/pubsub/base)). Mastra's [signals layer](https://mastra.ai/docs/agents/signals) uses it to elect a single owner across multiple processes (for example, serverless invocations) for a given resource, most commonly a thread key. The owner is the process that wakes and runs the agent stream, so other processes route follow-up work to it instead of starting a competing run.
+
+Leasing is a distinct concern from pub/sub. A backend implements `LeaseProvider` only when it can genuinely coordinate a lock, such as Redis via atomic `SET`/Lua, or an in-memory map for single-process. Backends that cannot lease omit it; the signals runtime feature-detects the capability and falls back to a no-op provider, preserving single-process behavior.
+
+The built-in [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams) implements `LeaseProvider`, which is what enables signals to coordinate across instances in distributed and serverless deployments.
+
+## Usage example
+
+You don't construct a `LeaseProvider` directly. Configure a pub/sub backend that implements it (such as `RedisStreamsPubSub`) on the `Mastra` constructor, and the signals runtime uses it automatically for cross-process coordination.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { RedisStreamsPubSub } from '@mastra/redis-streams'
+
+export const mastra = new Mastra({
+  // RedisStreamsPubSub implements both PubSub and LeaseProvider
+  pubsub: new RedisStreamsPubSub({
+    url: process.env.REDIS_URL,
+  }),
+})
+```
+
+To implement leasing in a custom backend, implement the methods below. The signals runtime detects the capability structurally (so it works across package boundaries) and only uses it when all methods are present.
+
+```typescript
+import { PubSub } from '@mastra/core/events'
+import type { LeaseProvider } from '@mastra/core/events'
+
+export class CustomPubSub extends PubSub implements LeaseProvider {
+  async acquireLease(key: string, owner: string, ttlMs: number) {
+    // Atomically claim the lease, or report the current holder.
+    return { acquired: true, owner }
+  }
+
+  // ...getLeaseOwner, releaseLease, renewLease, transferLease
+}
+```
+
+## Methods
+
+### Leasing
+
+#### `acquireLease(key, owner, ttlMs)`
+
+Atomically tries to acquire a lease on a key. Returns `{ acquired: true, owner }` if the caller claimed the lease, or `{ acquired: false, owner }` where `owner` is the current holder, so the caller can route follow-up work to them. The same owner can call `acquireLease` idempotently to renew or re-claim.
+
+```typescript
+const result = await pubsub.acquireLease('thread:abc', runId, 15000)
+
+if (result.acquired) {
+  // This process owns the thread, so wake and run the agent.
+} else {
+  // result.owner holds the lease, so route the signal to them.
+}
+```
+
+Returns: `Promise<{ acquired: boolean; owner?: string }>`
+
+**key** (`string`): The lease key, such as a thread key.
+
+**owner** (`string`): Identifier for the owner, such as a \`runId\`. The same owner can call \`acquireLease\` idempotently to renew or release.
+
+**ttlMs** (`number`): Time-to-live in milliseconds for the lease.
+
+#### `getLeaseOwner(key)`
+
+Reads the current owner of a lease, or `undefined` if no lease is held.
+
+```typescript
+const owner = await pubsub.getLeaseOwner('thread:abc')
+```
+
+Returns: `Promise<string | undefined>`
+
+#### `releaseLease(key, owner)`
+
+Releases a lease. This is a no-op if the caller is not the current owner: implementations check ownership atomically before releasing, so a concurrent renewal by another owner is never clobbered.
+
+```typescript
+await pubsub.releaseLease('thread:abc', runId)
+```
+
+Returns: `Promise<void>`
+
+#### `renewLease(key, owner, ttlMs)`
+
+Renews an existing lease owned by `owner`, extending its TTL. Returns `true` if the renewal succeeded and the caller still owns the lease, or `false` if the lease was lost (TTL expired or another owner took it).
+
+```typescript
+const stillOwned = await pubsub.renewLease('thread:abc', runId, 15000)
+
+if (!stillOwned) {
+  // Lost the lease, so stop renewing and let the new owner take over.
+}
+```
+
+Returns: `Promise<boolean>`
+
+#### `transferLease(key, fromOwner, toOwner, ttlMs)`
+
+Atomically hands a held lease from `fromOwner` to `toOwner`, refreshing its TTL, without releasing the key in between. This is the gap-free primitive used when one owner finishes but a follow-up owner must take over the same key immediately, for example when a thread run completes and a queued follow-up run drains on the same thread. A naive release-then-acquire would briefly leave the key empty, letting a racing process win the freed lease and start a competing run.
+
+Returns `true` if `fromOwner` still held the lease and ownership moved to `toOwner`, or `false` if the lease was already lost, in which case the caller should fall back to a fresh `acquireLease`.
+
+```typescript
+const transferred = await pubsub.transferLease('thread:abc', currentRunId, nextRunId, 15000)
+
+if (!transferred) {
+  // Lease was lost, so acquire fresh instead.
+  await pubsub.acquireLease('thread:abc', nextRunId, 15000)
+}
+```
+
+Returns: `Promise<boolean>`
+
+> **Warning:** Backends that cannot perform the transfer atomically must still implement it as a best-effort `releaseLease(fromOwner)` followed by `acquireLease(toOwner)`, and document that the swap is non-atomic, since a racing process can win the key in the gap. Keeping the method required means callers have a single code path and atomicity is an explicit per-backend decision.
+
+## Capability detection
+
+The signals runtime detects `LeaseProvider` structurally rather than with `instanceof`, so detection works even when a separately published backend resolves a different copy of `@mastra/core`. A value is treated as a `LeaseProvider` when it exposes all five methods (`acquireLease`, `getLeaseOwner`, `releaseLease`, `renewLease`, `transferLease`).
+
+When the configured pub/sub backend does not implement `LeaseProvider`, the runtime falls back to an always-win no-op provider. Every caller wins its own lease race, and release, renew, and transfer are inert, which preserves the expected single-process behavior.
+
+## Related
+
+- [PubSub](https://mastra.ai/reference/pubsub/base): The event delivery contract, separate from leasing
+- [RedisStreamsPubSub](https://mastra.ai/reference/pubsub/redis-streams): The built-in backend that implements `LeaseProvider`
+- [Signals](https://mastra.ai/docs/agents/signals): The runtime that uses leasing to coordinate thread runs across processes
+- [Channels](https://mastra.ai/docs/agents/channels): Uses leasing to coordinate agent runs in serverless and multi-instance deployments

package/.docs/reference/pubsub/redis-streams.md

@@ -1,6 +1,6 @@
 # RedisStreamsPubSub
 
-`RedisStreamsPubSub` is a [`PubSub`](https://mastra.ai/reference/pubsub/base) implementation backed by [Redis Streams](https://redis.io/docs/latest/develop/data-types/streams/). It delivers events across processes and hosts, with persistence, consumer groups, and redelivery on failure.
+`RedisStreamsPubSub` is a [`PubSub`](https://mastra.ai/reference/pubsub/base) implementation backed by [Redis Streams](https://redis.io/docs/latest/develop/data-types/streams/). It delivers events across processes and hosts, with persistence, consumer groups, and redelivery on failure. It also implements [`LeaseProvider`](https://mastra.ai/reference/pubsub/lease-provider), so the signals layer can elect a single owner per resource across instances, which is what lets signals coordinate runs in distributed and serverless deployments.
 
 Use it for distributed deployments where several services share an event stream. For single-process delivery, use [`EventEmitterPubSub`](https://mastra.ai/reference/pubsub/event-emitter). For Google Cloud, use [`GoogleCloudPubSub`](https://mastra.ai/reference/pubsub/google-cloud-pubsub).
 
@@ -105,4 +105,12 @@ await pubsub.close()
 
 ## Redelivery and reclaim
 
-When a subscriber calls `nack`, the event is republished with an incremented `deliveryAttempt` and the original is acknowledged. Once an event reaches `maxDeliveryAttempts`, it's dropped instead of redelivered. Separately, each subscription periodically reclaims events that an earlier consumer in the group read but never acknowledged, controlled by `reclaimIntervalMs` and `reclaimIdleMs`.
+When a subscriber calls `nack`, the event is republished with an incremented `deliveryAttempt` and the original is acknowledged. Once an event reaches `maxDeliveryAttempts`, it's dropped instead of redelivered. Separately, each subscription periodically reclaims events that an earlier consumer in the group read but never acknowledged, controlled by `reclaimIntervalMs` and `reclaimIdleMs`.
+
+## Distributed leasing
+
+`RedisStreamsPubSub` implements the [`LeaseProvider`](https://mastra.ai/reference/pubsub/lease-provider) contract on top of the same Redis connection. The [signals runtime](https://mastra.ai/docs/agents/signals) uses it to elect a single owner (usually per thread key) so that across instances only one process wakes and runs the agent, and others route follow-up work to the holder. This is what makes signals work on serverless and multi-instance deployments; without a shared lease, each instance would start its own competing run.
+
+Lease keys are namespaced under the same `keyPrefix` as topics, as `<keyPrefix>:lease:<key>`. All operations are atomic: `acquireLease` uses `SET NX PX` and refreshes its own TTL idempotently, while `releaseLease`, `renewLease`, and `transferLease` use Lua scripts that check ownership before mutating, so a concurrent renewal from another owner is never clobbered.
+
+You don't call these methods directly. Configuring `RedisStreamsPubSub` as the `pubsub` backend is enough for the runtime to detect and use the capability. See [`LeaseProvider`](https://mastra.ai/reference/pubsub/lease-provider) for the full method contract.

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @mastra/mcp-docs-server
 
+## 1.2.3-alpha.2
+
+### Patch Changes
+
+- Updated dependencies [[`95857bc`](https://github.com/mastra-ai/mastra/commit/95857bcd6669da7193f503e803f0d72a2bd66be6), [`8e9c0fb`](https://github.com/mastra-ai/mastra/commit/8e9c0fb48fd58da2efcdff2cf1202ee41092c315)]:
+  - @mastra/core@1.48.0-alpha.1
+
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.2",
+  "version": "1.2.3-alpha.3",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -29,7 +29,7 @@
     "local-pkg": "^1.1.2",
     "zod": "^4.4.3",
     "@mastra/mcp": "^1.12.0",
-    "@mastra/core": "1.47.0"
+    "@mastra/core": "1.48.0-alpha.1"
   },
   "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.109",
     "@internal/types-builder": "0.0.84",
-    "@mastra/core": "1.47.0"
+    "@internal/lint": "0.0.109",
+    "@mastra/core": "1.48.0-alpha.1"
   },
   "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