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

package/.docs/reference/agents/listSuspendedRuns.md

@@ -0,0 +1,91 @@
+# Agent.listSuspendedRuns()
+
+**Added in:** `@mastra/core@1.43.0`
+
+The `.listSuspendedRuns()` method lists suspended agent runs from workflow snapshot storage: runs waiting on a tool call requiring [approval](https://mastra.ai/docs/agents/agent-approval), or on a tool that called `suspend()`. Because discovery is backed by storage rather than in-memory state, it works after a server restart and across multiple server instances.
+
+Pass the returned `runId` to [`resumeStream()`](https://mastra.ai/docs/agents/agent-approval), `approveToolCall()`, or `declineToolCall()` to continue the run.
+
+The filter contract mirrors the workflow run listing APIs (`listWorkflowRuns`), plus the agent-level `threadId` filter.
+
+## Usage example
+
+Discover the pending run for a conversation and continue it. Check `requiresApproval` to pick the right continuation — `approveToolCall()` / `declineToolCall()` for approval suspensions, `resumeStream()` with resume data for `suspend()`-based suspensions:
+
+```typescript
+const { runs } = await agent.listSuspendedRuns({
+  threadId: 'thread-123',
+  resourceId: 'user-456',
+})
+
+const run = runs[0]
+const toolCall = run?.toolCalls[0]
+
+if (run && toolCall) {
+  const stream = toolCall.requiresApproval
+    ? await agent.approveToolCall({ runId: run.runId, toolCallId: toolCall.toolCallId })
+    : await agent.resumeStream({ name: 'San Francisco' }, { runId: run.runId })
+}
+```
+
+## Parameters
+
+**options** (`AgentListSuspendedRunsOptions`): Filters and pagination for scoping the results. (Default: `{}`)
+
+**options.threadId** (`string`): Only return runs that belong to this memory thread.
+
+**options.resourceId** (`string`): Only return runs that belong to this memory resource.
+
+**options.fromDate** (`Date`): Only return runs created at or after this date.
+
+**options.toDate** (`Date`): Only return runs created at or before this date.
+
+**options.perPage** (`number`): Number of items per page. Pagination is applied when both perPage and page are provided; otherwise all matching runs are returned.
+
+**options.page** (`number`): Zero-indexed page number.
+
+## Returns
+
+**result** (`Promise<AgentListSuspendedRunsResult>`): A promise that resolves to the matching runs and the total count before pagination.
+
+```typescript
+interface AgentListSuspendedRunsResult {
+  runs: AgentRun[]
+  /** Total number of matching runs, before pagination */
+  total: number
+}
+
+interface AgentRun {
+  /** Run ID accepted by resumeStream(), approveToolCall(), and declineToolCall() */
+  runId: string
+  status: 'suspended'
+  threadId?: string
+  resourceId?: string
+  /** When the run suspended */
+  suspendedAt: Date
+  /** Suspended tool calls awaiting approval or resume data */
+  toolCalls: AgentRunToolCall[]
+}
+
+interface AgentRunToolCall {
+  toolCallId?: string
+  toolName?: string
+  /** Arguments the model supplied (approval suspensions only) */
+  args?: unknown
+  /** True when the run is waiting on a tool-call approval */
+  requiresApproval: boolean
+  /** The tool-defined suspend payload when the tool called suspend() */
+  suspendPayload?: unknown
+}
+```
+
+## Discovery scope
+
+Results are scoped to runs started by the agent you call `listSuspendedRuns()` on: snapshots persist the owning agent's id, so runs started by other agents on the same Mastra instance are not returned. In [supervisor setups](https://mastra.ai/docs/agents/agent-approval) the supervisor sees its outer run — the one to resume — while a subagent's inner run is only visible from the subagent itself. Filter by `threadId` and `resourceId` to scope results to one conversation.
+
+Run snapshots are only persisted while a run is waiting on input and are deleted when it finishes, so suspended runs are the only runs discoverable from storage. Suspended runs only survive restarts when the Mastra instance has a persistent [storage provider](https://mastra.ai/docs/memory/storage) configured. With the default in-memory store, snapshots are lost on restart.
+
+## Related
+
+- [Agent approval](https://mastra.ai/docs/agents/agent-approval)
+- [Storage](https://mastra.ai/docs/memory/storage)

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

@@ -0,0 +1,65 @@
+# ChannelProvider
+
+`ChannelProvider` is the interface that platform integrations implement to connect agents to a messaging platform. A provider owns the full lifecycle of an integration: app provisioning and OAuth, webhook routing and event handling, adapter creation and agent wiring, and credential management.
+
+Register providers on the `Mastra` constructor under `channels`, keyed by an id you choose. Each provider's routes are merged into the server's API routes automatically, and `initialize()` runs during Mastra startup.
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { SlackProvider } from '@mastra/slack'
+
+export const mastra = new Mastra({
+  channels: {
+    slack: new SlackProvider({
+      refreshToken: process.env.SLACK_REFRESH_TOKEN!,
+      baseUrl: process.env.MASTRA_BASE_URL,
+    }),
+  },
+})
+```
+
+The provider's `baseUrl` is the public URL the platform sends webhooks and events to. In production this is your deployed Mastra server URL. For local development, the platform can't reach `http://localhost:4111`, so run a tunnel (such as [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) or [ngrok](https://ngrok.com/)) and point `baseUrl` at the tunnel URL (for example `https://abc123.trycloudflare.com`) so events reach your local dev process.
+
+[`SlackProvider`](https://mastra.ai/reference/channels/slack-provider) is the first built-in implementation. Build a custom provider by implementing this interface.
+
+## Properties
+
+**id** (`string`): Unique identifier for this channel type, for example 'slack' or 'discord'. Used as the key when routing events and looking the provider up from Mastra.
+
+## Methods
+
+**getRoutes** (`() => ApiRoute[]`): Returns the API routes for this channel (OAuth, webhooks, events). These are merged into the server's apiRoutes automatically.
+
+**initialize** (`() => Promise<void>`): Called during Mastra initialization after all agents are registered. Use it for async setup such as restoring active installations. Does not provision new apps.
+
+**configure** (`(credentials: Record<string, unknown> | null) => void | Promise<void>`): Provides or clears platform credentials at runtime. Pass null to clear credentials and delete stored tokens.
+
+**getInfo** (`() => ChannelPlatformInfo`): Returns discovery metadata for the editor UI: platform name, configuration status, and the connect options schema.
+
+**connect** (`(agentId: string, options?: Record<string, unknown>) => Promise<ChannelConnectResult>`): Connects an agent to the platform. Returns a discriminated result describing the authorization flow required to finish the connection.
+
+**disconnect** (`(agentId: string) => Promise<void>`): Disconnects an agent from the platform. Deletes the platform app and cleans up stored state.
+
+**listInstallations** (`() => Promise<ChannelInstallationInfo[]>`): Lists active installations for this platform. Returns public info only, never secrets.
+
+## Accessing a provider
+
+Access a registered provider through the `channels` getter, keyed by the id you registered it under. The getter is typed from the constructor config, so `mastra.channels.slack` is the concrete provider with its full method surface.
+
+```typescript
+await mastra.channels.slack.configure({ refreshToken })
+```
+
+When the key is only known at runtime, look the provider up by string id instead. `getChannelProvider` takes the concrete type as a generic, and `getChannelProviders` returns every registered provider keyed by id.
+
+```typescript
+import type { SlackProvider } from '@mastra/slack'
+
+const slack = mastra.getChannelProvider<SlackProvider>('slack')
+const all = mastra.getChannelProviders()
+```
+
+## Related
+
+- [SlackProvider](https://mastra.ai/reference/channels/slack-provider)
+- [Channels](https://mastra.ai/docs/agents/channels)

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/client-js/agents.md

@@ -362,6 +362,27 @@ response.processDataStream({
 })
 ```
 
+### `listSuspendedRuns()`
+
+List suspended runs for the agent from storage — runs waiting on a tool-call approval or on a tool that suspended. Discovery is backed by storage, so it works after a server restart and across server instances. Pass the returned `runId` to `approveToolCall()`, `declineToolCall()`, or `resumeStream()`.
+
+```typescript
+const { runs, total } = await agent.listSuspendedRuns({
+  threadId: 'thread-456',
+  resourceId: 'user-123',
+})
+
+if (runs[0]) {
+  console.log(runs[0].toolCalls) // [{ toolCallId, toolName, args, requiresApproval }]
+  await agent.approveToolCall({
+    runId: runs[0].runId,
+    toolCallId: runs[0].toolCalls[0].toolCallId,
+  })
+}
+```
+
+Accepts optional filters (`threadId`, `resourceId`, `fromDate`, `toDate`) and pagination (`perPage`, `page`). Returns `{ runs, total }`, where `total` is the number of matching runs before pagination. See [`Agent.listSuspendedRuns()`](https://mastra.ai/reference/agents/listSuspendedRuns) for details on the returned run shape.
+
 ### `approveToolCall()`
 
 Approve a pending tool call and return a continuation stream. Use this when you are rendering the resumed chunks from the approval response.

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)
@@ -26,6 +28,7 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [.listAgents()](https://mastra.ai/reference/agents/listAgents)
 - [.listScorers()](https://mastra.ai/reference/agents/listScorers)
 - [.listSkills()](https://mastra.ai/reference/agents/listSkills)
+- [.listSuspendedRuns()](https://mastra.ai/reference/agents/listSuspendedRuns)
 - [.listTools()](https://mastra.ai/reference/agents/listTools)
 - [.listWorkflows()](https://mastra.ai/reference/agents/listWorkflows)
 - [.network()](https://mastra.ai/reference/agents/network)
@@ -54,6 +57,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 +170,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 +212,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/observability/metrics/automatic-metrics.md

@@ -13,7 +13,7 @@ Metrics are extracted from spans when they end. The observability layer inspects
 Two conditions must be true for a metric to reach storage:
 
 1. `MastraStorageExporter` is configured as an exporter.
-2. The storage backend supports metrics (ClickHouse or DuckDB).
+2. The storage backend supports metrics (ClickHouse, DuckDB, or Postgres v-next with the observability domain enabled).
 
 If metrics aren't available, see [troubleshooting](#troubleshooting).
 
@@ -116,7 +116,7 @@ When you spot a spike in latency or token usage on the Metrics dashboard, correl
 
 - **Observability is configured**: Verify that your `Mastra` instance has an `observability` config with at least one exporter.
 - **`MastraStorageExporter` or `MastraPlatformExporter` is present**: Other exporters (Datadog, Langfuse, etc.) don't surface metrics in Mastra. `MastraStorageExporter` is required for the local Studio dashboard, and `MastraPlatformExporter` is required to view metrics in Mastra platform.
-- **Storage supports metrics**: Metrics require an OLAP-capable store (ClickHouse or DuckDB). Row-oriented databases (PostgreSQL, LibSQL, MSSQL) and document stores (MongoDB) aren't supported for metrics.
+- **Storage supports metrics**: Metrics require an analytics-capable store (ClickHouse, DuckDB, or Postgres v-next with the observability domain enabled). Other row-oriented databases (LibSQL, MSSQL) and document stores (MongoDB) aren't supported for metrics.
 - **Sampling isn't 0%**: If sampling probability is `0` or strategy is `never`, all spans become no-ops and no metrics are extracted.
 
 ### Duration metrics are missing

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.