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

package/.docs/models/providers/subconscious.md

@@ -0,0 +1,71 @@
+# ![Subconscious logo](https://models.dev/logos/subconscious.svg)Subconscious
+
+Access 1 Subconscious model through Mastra's model router. Authentication is handled automatically using the `SUBCONSCIOUS_API_KEY` environment variable.
+
+Learn more in the [Subconscious documentation](https://docs.subconscious.dev).
+
+```bash
+SUBCONSCIOUS_API_KEY=your-api-key
+```
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+
+const agent = new Agent({
+  id: "my-agent",
+  name: "My Agent",
+  instructions: "You are a helpful assistant",
+  model: "subconscious/subconscious/tim-qwen3.6-27b"
+});
+
+// Generate a response
+const response = await agent.generate("Hello!");
+
+// Stream a response
+const stream = await agent.stream("Tell me a story");
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+> **Info:** Mastra uses the OpenAI-compatible `/chat/completions` endpoint. Some provider-specific features may not be available. Check the [Subconscious documentation](https://docs.subconscious.dev) for details.
+
+## Models
+
+| Model                                       | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| ------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `subconscious/subconscious/tim-qwen3.6-27b` | 8K      |       |           |       |       |       | —          | —           |
+
+## Advanced configuration
+
+### Custom headers
+
+```typescript
+const agent = new Agent({
+  id: "custom-agent",
+  name: "custom-agent",
+  model: {
+    url: "https://api.subconscious.dev/v1",
+    id: "subconscious/subconscious/tim-qwen3.6-27b",
+    apiKey: process.env.SUBCONSCIOUS_API_KEY,
+    headers: {
+      "X-Custom-Header": "value"
+    }
+  }
+});
+```
+
+### Dynamic model selection
+
+```typescript
+const agent = new Agent({
+  id: "dynamic-agent",
+  name: "Dynamic Agent",
+  model: ({ requestContext }) => {
+    const useAdvanced = requestContext.task === "complex";
+    return useAdvanced
+      ? "subconscious/subconscious/tim-qwen3.6-27b"
+      : "subconscious/subconscious/tim-qwen3.6-27b";
+  }
+});
+```

package/.docs/models/providers/synthetic.md

@@ -1,6 +1,6 @@
 # ![Synthetic logo](https://models.dev/logos/synthetic.svg)Synthetic
 
-Access 8 Synthetic models through Mastra's model router. Authentication is handled automatically using the `SYNTHETIC_API_KEY` environment variable.
+Access 10 Synthetic models through Mastra's model router. Authentication is handled automatically using the `SYNTHETIC_API_KEY` environment variable.
 
 Learn more in the [Synthetic documentation](https://synthetic.new/pricing).
 
@@ -37,11 +37,13 @@ for await (const chunk of stream) {
 | `synthetic/hf:MiniMaxAI/MiniMax-M3`                           | 524K    |       |           |       |       |       | $0.60      | $1          |
 | `synthetic/hf:moonshotai/Kimi-K2.6`                           | 262K    |       |           |       |       |       | $0.95      | $4          |
 | `synthetic/hf:nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-NVFP4` | 262K    |       |           |       |       |       | $0.30      | $1          |
-| `synthetic/hf:openai/gpt-oss-120b`                            | 128K    |       |           |       |       |       | $0.10      | $0.10       |
-| `synthetic/hf:Qwen/Qwen3.5-397B-A17B`                         | 262K    |       |           |       |       |       | $0.60      | $3          |
-| `synthetic/hf:zai-org/GLM-4.7`                                | 200K    |       |           |       |       |       | $0.55      | $2          |
-| `synthetic/hf:zai-org/GLM-4.7-Flash`                          | 197K    |       |           |       |       |       | $0.06      | $0.40       |
+| `synthetic/hf:openai/gpt-oss-120b`                            | 131K    |       |           |       |       |       | $0.10      | $0.10       |
+| `synthetic/hf:Qwen/Qwen3.5-397B-A17B`                         | 262K    |       |           |       |       |       | $0.60      | $4          |
+| `synthetic/hf:Qwen/Qwen3.6-27B`                               | 262K    |       |           |       |       |       | $0.45      | $4          |
+| `synthetic/hf:zai-org/GLM-4.7`                                | 203K    |       |           |       |       |       | $0.45      | $2          |
+| `synthetic/hf:zai-org/GLM-4.7-Flash`                          | 197K    |       |           |       |       |       | $0.10      | $0.50       |
 | `synthetic/hf:zai-org/GLM-5.1`                                | 197K    |       |           |       |       |       | $1         | $3          |
+| `synthetic/hf:zai-org/GLM-5.2`                                | 524K    |       |           |       |       |       | $1         | $4          |
 
 ## Advanced configuration
 
@@ -71,7 +73,7 @@ const agent = new Agent({
   model: ({ requestContext }) => {
     const useAdvanced = requestContext.task === "complex";
     return useAdvanced
-      ? "synthetic/hf:zai-org/GLM-5.1"
+      ? "synthetic/hf:zai-org/GLM-5.2"
       : "synthetic/hf:MiniMaxAI/MiniMax-M3";
   }
 });

package/.docs/models/providers/xiaomi.md

@@ -34,8 +34,8 @@ for await (const chunk of stream) {
 
 | Model                             | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
 | --------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
-| `xiaomi/mimo-v2.5`                | 1.0M    |       |           |       |       |       | $0.40      | $2          |
-| `xiaomi/mimo-v2.5-pro`            | 1.0M    |       |           |       |       |       | $1         | $3          |
+| `xiaomi/mimo-v2.5`                | 1.0M    |       |           |       |       |       | $0.14      | $0.28       |
+| `xiaomi/mimo-v2.5-pro`            | 1.0M    |       |           |       |       |       | $0.43      | $0.87       |
 | `xiaomi/mimo-v2.5-pro-ultraspeed` | 1.0M    |       |           |       |       |       | $1         | $3          |
 
 ## Advanced configuration

package/.docs/models/providers.md

@@ -106,6 +106,7 @@ Direct access to individual AI model providers. Each provider offers unique mode
 - [STACKIT](https://mastra.ai/models/providers/stackit)
 - [StepFun](https://mastra.ai/models/providers/stepfun)
 - [StepFun AI](https://mastra.ai/models/providers/stepfun-ai)
+- [Subconscious](https://mastra.ai/models/providers/subconscious)
 - [submodel](https://mastra.ai/models/providers/submodel)
 - [Synthetic](https://mastra.ai/models/providers/synthetic)
 - [Tencent Coding Plan (China)](https://mastra.ai/models/providers/tencent-coding-plan)

package/.docs/reference/agent-controller/agent-controller-class.md

@@ -128,7 +128,7 @@ await agentController.sendMessage({ content: 'Hello!' })
 
 **disableBuiltinTools** (`BuiltinToolId[]`): Built-in tool IDs to remove from the \`controllerBuiltIn\` toolset. Valid values are \`ask\_user\`, \`submit\_plan\`, \`task\_write\`, \`task\_update\`, \`task\_complete\`, \`task\_check\`, and \`subagent\`.
 
-**heartbeatHandlers** (`HeartbeatHandler[]`): Periodic background tasks started during \`init()\`. Use for gateway sync, cache refresh, and similar tasks.
+**intervalHandlers** (`IntervalHandler[]`): Periodic background tasks started during \`init()\`. Use for gateway sync, cache refresh, and similar tasks.
 
 **idGenerator** (`() => string`): Custom ID generator for AgentController-managed IDs such as threads and mode-run identifiers. (Default: `timestamp + random string`)
 
@@ -162,7 +162,7 @@ await agentController.sendMessage({ content: 'Hello!' })
 
 #### `init()`
 
-Initialize the agentController. Loads storage, initializes a static workspace (dynamic factory workspaces are resolved per-session during `createSession`), propagates memory and workspace to mode agents, and starts heartbeat handlers. Call this before using the agentController.
+Initialize the agentController. Loads storage, initializes a static workspace (dynamic factory workspaces are resolved per-session during `createSession`), propagates memory and workspace to mode agents, and starts interval handlers. Call this before using the agentController.
 
 ```typescript
 await agentController.init()
@@ -220,26 +220,26 @@ const thread = await agentController.selectOrCreateThread()
 
 #### `destroy()`
 
-Stop all heartbeat handlers and clean up resources.
+Stop all interval handlers and clean up resources.
 
 ```typescript
 await agentController.destroy()
 ```
 
-#### `removeHeartbeat({ id })`
+#### `removeInterval({ id })`
 
-Remove a specific heartbeat handler by ID. Calls the handler's `shutdown()` callback if defined.
+Remove a specific interval handler by ID. Calls the handler's `shutdown()` callback if defined.
 
 ```typescript
-await agentController.removeHeartbeat({ id: 'gateway-sync' })
+await agentController.removeInterval({ id: 'gateway-sync' })
 ```
 
-#### `stopHeartbeats()`
+#### `stopIntervals()`
 
-Stop and remove all heartbeat handlers.
+Stop and remove all interval handlers.
 
 ```typescript
-await agentController.stopHeartbeats()
+await agentController.stopIntervals()
 ```
 
 #### `getCurrentAgent()`

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/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

@@ -28,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)
@@ -211,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.

package/CHANGELOG.md

@@ -1,5 +1,48 @@
 # @mastra/mcp-docs-server
 
+## 1.2.3-alpha.12
+
+### Patch Changes
+
+- Updated dependencies [[`b33c77d`](https://github.com/mastra-ai/mastra/commit/b33c77d5293f14a794f3ec38dc947a6676de2764), [`1009f77`](https://github.com/mastra-ai/mastra/commit/1009f772aa40016b49267c8566d0c29f6a16aa3c), [`23c31de`](https://github.com/mastra-ai/mastra/commit/23c31de96ed8153402dcf092ac84b27a0c3638c1), [`0368766`](https://github.com/mastra-ai/mastra/commit/0368766744c7ea3df4d6059e2cc15f7bdf55f5a6), [`65a66db`](https://github.com/mastra-ai/mastra/commit/65a66dbe249a0d92d828c605b955e73a983cf3b0), [`2866f04`](https://github.com/mastra-ai/mastra/commit/2866f04953edb78c1637fa45cc53abe24122edcb)]:
+  - @mastra/core@1.48.0-alpha.6
+  - @mastra/mcp@1.12.1-alpha.0
+
+## 1.2.3-alpha.10
+
+### Patch Changes
+
+- Updated dependencies [[`1917c53`](https://github.com/mastra-ai/mastra/commit/1917c53b19dac43926f29c496893b0686462dca4), [`58e287b`](https://github.com/mastra-ai/mastra/commit/58e287b1edaf978b13745a1795989cad3826e82b)]:
+  - @mastra/core@1.48.0-alpha.5
+
+## 1.2.3-alpha.8
+
+### Patch Changes
+
+- Updated dependencies [[`705ba98`](https://github.com/mastra-ai/mastra/commit/705ba98726d388a596e896225f237907ca6807a9), [`e62c108`](https://github.com/mastra-ai/mastra/commit/e62c108409dfd6a6cac0a48ec39c5cc81d24fd52), [`bfbbb01`](https://github.com/mastra-ai/mastra/commit/bfbbb01bd845ba54cdc0c678c277d08a7cb847e4)]:
+  - @mastra/core@1.48.0-alpha.4
+
+## 1.2.3-alpha.7
+
+### Patch Changes
+
+- Updated dependencies [[`cdd5f93`](https://github.com/mastra-ai/mastra/commit/cdd5f939cefa67390629704dce92563ccbf492b2), [`1b8728a`](https://github.com/mastra-ai/mastra/commit/1b8728a57fd844205a452b0b4216d20ff60c784a), [`213feb8`](https://github.com/mastra-ai/mastra/commit/213feb87bfdd1d8ec00ea660e218f9bcfcb34e7b)]:
+  - @mastra/core@1.48.0-alpha.3
+
+## 1.2.3-alpha.5
+
+### Patch Changes
+
+- Updated dependencies [[`e420b3c`](https://github.com/mastra-ai/mastra/commit/e420b3c3ffc98bbc5b791897ea390bb47af99696)]:
+  - @mastra/core@1.48.0-alpha.2
+
+## 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "1.2.3-alpha.1",
+  "version": "1.2.3-alpha.12",
   "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/mcp": "^1.12.0",
-    "@mastra/core": "1.48.0-alpha.0"
+    "@mastra/mcp": "^1.12.1-alpha.0",
+    "@mastra/core": "1.48.0-alpha.6"
   },
   "devDependencies": {
     "@hono/node-server": "^1.19.11",
@@ -45,9 +45,9 @@
     "tsx": "^4.22.4",
     "typescript": "^6.0.3",
     "vitest": "4.1.8",
-    "@internal/types-builder": "0.0.84",
     "@internal/lint": "0.0.109",
-    "@mastra/core": "1.48.0-alpha.0"
+    "@internal/types-builder": "0.0.84",
+    "@mastra/core": "1.48.0-alpha.6"
   },
   "homepage": "https://mastra.ai",
   "repository": {