@mastra/mcp-docs-server 1.1.45 → 1.1.46-alpha.1

package/.docs/reference/observability/tracing/exporters/cloud-exporter.md

@@ -231,7 +231,7 @@ const customExporter = new CloudExporter({
 ### Documentation
 
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview): Complete guide
-- [Exporters](https://mastra.ai/docs/observability/tracing/overview): Exporter concepts
+- [Exporters](https://mastra.ai/docs/observability/integrations/overview): Exporter concepts
 
 ### Other Exporters
 

package/.docs/reference/observability/tracing/exporters/console-exporter.md

@@ -120,7 +120,7 @@ const exporterWithLogger = new ConsoleExporter({
 ### Documentation
 
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview): Complete guide
-- [Exporters](https://mastra.ai/docs/observability/tracing/overview): Exporter concepts
+- [Exporters](https://mastra.ai/docs/observability/integrations/overview): Exporter concepts
 
 ### Other Exporters
 

package/.docs/reference/observability/tracing/exporters/default-exporter.md

@@ -165,7 +165,7 @@ const customExporter = new DefaultExporter({
 ### Documentation
 
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview): Complete guide
-- [Exporters](https://mastra.ai/docs/observability/tracing/overview): Exporter concepts
+- [Exporters](https://mastra.ai/docs/observability/integrations/overview): Exporter concepts
 
 ### Other Exporters
 

package/.docs/reference/observability/tracing/exporters/mastra-platform-exporter.md

@@ -248,7 +248,7 @@ The original `CloudExporter` is preserved unchanged so dashboards or alert rules
 ### Documentation
 
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview): Complete guide
-- [Exporters](https://mastra.ai/docs/observability/tracing/overview): Exporter concepts
+- [Exporters](https://mastra.ai/docs/observability/integrations/overview): Exporter concepts
 
 ### Other Exporters
 

package/.docs/reference/observability/tracing/exporters/mastra-storage-exporter.md

@@ -179,7 +179,7 @@ The original `DefaultExporter` is preserved unchanged so dashboards or alert rul
 ### Documentation
 
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview): Complete guide
-- [Exporters](https://mastra.ai/docs/observability/tracing/overview): Exporter concepts
+- [Exporters](https://mastra.ai/docs/observability/integrations/overview): Exporter concepts
 
 ### Other Exporters
 

package/.docs/reference/observability/tracing/exporters/otel.md

@@ -198,6 +198,6 @@ Tags are stored as a JSON-stringified array in the `mastra.tags` span attribute
 
 ## Related
 
-- [OtelExporter Guide](https://mastra.ai/docs/observability/tracing/exporters/otel): Setup guide with provider configurations
-- [OtelBridge](https://mastra.ai/docs/observability/tracing/bridges/otel): For bidirectional OTEL context integration
+- [OtelExporter Guide](https://mastra.ai/docs/observability/integrations/exporters/otel): Setup guide with provider configurations
+- [OtelBridge](https://mastra.ai/docs/observability/integrations/bridges/otel): For bidirectional OTEL context integration
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview): General tracing concepts

package/.docs/reference/observability/tracing/span-filtering.md

@@ -92,4 +92,4 @@ If `spanFilter` throws an error, Mastra keeps the span and logs the error to avo
 
 - [Tracing overview](https://mastra.ai/docs/observability/tracing/overview) for setup and concepts
 - [Configuration API](https://mastra.ai/reference/observability/tracing/configuration) for `ObservabilityInstanceConfig`
-- [Sensitive data filter](https://mastra.ai/docs/observability/tracing/processors/sensitive-data-filter) for redacting span data
+- [Sensitive data filter](https://mastra.ai/docs/observability/integrations/processors/sensitive-data-filter) for redacting span data

package/.docs/reference/pubsub/base.md

@@ -75,6 +75,8 @@ await pubsub.publish('my-topic', {
 
 Registers a callback to receive events published to a topic. When `options.group` is set, subscribers in the same group compete for messages and each event is delivered to one member. Without a group, every subscriber receives every event.
 
+Pass `options.batch` to opt in to batched delivery. The callback signature is unchanged: a batch of N events is delivered as N consecutive `cb(event, ack, nack)` calls in publish order. Batching is honored only when the backend's [`supportsNativeBatching`](#properties) is `true`; other backends ignore the option and deliver events one at a time.
+
 ```typescript
 await pubsub.subscribe('my-topic', (event, ack, nack) => {
   console.log(event)
@@ -135,6 +137,8 @@ await pubsub.subscribeFromOffset('my-topic', 42, event => {
 
 **supportedModes** (`ReadonlyArray<"pull" | "push">`): Delivery modes the implementation supports. Defaults to \`\["pull"]\`.
 
+**supportsNativeBatching** (`boolean`): Whether the implementation honors \`options.batch\` on \`subscribe()\`. Defaults to \`false\`. Backends that integrate batching internally override this and return \`true\`.
+
 ## Types
 
 ### `Event`
@@ -157,6 +161,26 @@ await pubsub.subscribeFromOffset('my-topic', 42, event => {
 
 **group** (`string`): When set, subscribers with the same group compete for messages and each event is delivered to one member. When omitted, every subscriber receives every event.
 
+**batch** (`SubscribeBatchOptions`): Opt in to batched delivery for this subscription. When omitted, events are delivered one at a time. Honored only by backends where \`supportsNativeBatching\` is \`true\`.
+
+### `SubscribeBatchOptions`
+
+Per-subscription batching policy. The callback signature does not change; a batch of N events becomes N consecutive callback invocations in publish order.
+
+**maxSize** (`number`): Maximum events held before forcing a flush.
+
+**maxWaitMs** (`number`): Maximum time in milliseconds the oldest event may sit in the buffer. The timer starts when the buffer transitions from empty to non-empty.
+
+**minIntervalMs** (`number`): Minimum time in milliseconds between consecutive batch deliveries. Even when \`maxSize\` or \`maxWaitMs\` would fire, the buffer holds until this interval has elapsed since the last delivery.
+
+**isImmediate** (`(event: Event) => boolean`): When it returns \`true\` for an event, the buffer flushes immediately on publish, subject to \`minIntervalMs\`. A per-event escape hatch.
+
+**coalesce** (`(events: Event[]) => Event[]`): Applied to the queued batch before delivery to drop superseded events. Must return a subset of its input by reference identity; returning freshly constructed \`Event\` objects is a contract violation and discards the whole batch. Ordering of kept events is preserved.
+
+**maxBufferSize** (`number`): Maximum events the buffer may hold before overflow handling kicks in. Events flagged immediate are never dropped on overflow. (Default: `256`)
+
+**overflow** (`"drop-oldest" | "drop-newest" | "coalesce-or-drop-oldest"`): Overflow strategy when the buffer exceeds \`maxBufferSize\`. \`coalesce-or-drop-oldest\` runs \`coalesce\` first, then drops oldest if still over budget. (Default: `coalesce-or-drop-oldest`)
+
 ### `EventCallback`
 
 The callback signature for subscribers: `(event: Event, ack?: () => Promise<void>, nack?: () => Promise<void>) => void`.

package/.docs/reference/pubsub/caching-pubsub.md

@@ -4,6 +4,8 @@
 
 Use it to build resumable streams on top of a transport that does not keep history, such as [`EventEmitterPubSub`](https://mastra.ai/reference/pubsub/event-emitter). Transports that already persist events, such as [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams), do not need this wrapper.
 
+`CachingPubSub` is transparent to batching: `subscribe()` forwards `options.batch` to the inner pub/sub, and `supportsNativeBatching` mirrors the inner's value. Wrapping an inner that does not support batching results in unbatched delivery even when `options.batch` is passed.
+
 ## Usage example
 
 Wrap an inner pub/sub and provide a server cache to store events.
@@ -38,6 +40,10 @@ const pubsub = withCaching(new EventEmitterPubSub(), new InMemoryServerCache())
 
 **options** (`CachingPubSubOptions`): Optional configuration.
 
+## Properties
+
+**supportsNativeBatching** (`boolean`): Mirrors the inner pub/sub. Returns \`true\` only when the wrapped implementation supports batching.
+
 ## Methods
 
 `CachingPubSub` implements the [`PubSub`](https://mastra.ai/reference/pubsub/base) contract. It overrides the replay methods to read cached events. The methods below describe the caching behavior.

package/.docs/reference/pubsub/event-emitter.md

@@ -29,14 +29,26 @@ const emitter = new EventEmitter()
 const pubsub = new EventEmitterPubSub(emitter)
 ```
 
+To surface batched-delivery errors, pass a logger:
+
+```typescript
+import { EventEmitterPubSub } from '@mastra/core/events'
+
+const pubsub = new EventEmitterPubSub(undefined, { logger })
+```
+
 ## Constructor parameters
 
 **existingEmitter** (`EventEmitter`): An existing Node.js EventEmitter to use for delivery. When omitted, a new EventEmitter is created.
 
+**options** (`EventEmitterPubSubOptions`): Optional configuration.
+
 ## Properties
 
 **supportedModes** (`ReadonlyArray<"pull" | "push">`): Returns \`\["pull", "push"]\`. The emitter can serve a pull-style worker or push events directly to listeners.
 
+**supportsNativeBatching** (`boolean`): Returns \`true\`. Subscribers can opt in to batched delivery with \`options.batch\`.
+
 ## Methods
 
 `EventEmitterPubSub` implements the [`PubSub`](https://mastra.ai/reference/pubsub/base) contract. The methods below have behavior specific to this implementation.
@@ -45,6 +57,8 @@ const pubsub = new EventEmitterPubSub(emitter)
 
 Registers a callback for a topic. Without `options.group`, every subscriber receives every event. With a group, events are distributed round-robin across members of that group.
 
+Pass `options.batch` to opt in to batched delivery. See [Batching](#batching) below.
+
 ```typescript
 await pubsub.subscribe('workflow.events', (event, ack, nack) => {
   console.log(event)
@@ -69,4 +83,25 @@ await pubsub.close()
 
 ## Redelivery
 
-When a grouped subscriber calls `nack`, the event is redelivered to the group after a short delay, and its `deliveryAttempt` count increases. Calling `ack` clears the tracking for that event. Fan-out subscribers receive no-op `ack` and `nack` functions, since each event reaches every subscriber once.
+When a grouped subscriber calls `nack`, the event is redelivered to the group after a short delay, and its `deliveryAttempt` count increases. Calling `ack` clears the tracking for that event. Fan-out subscribers receive no-op `ack` and `nack` functions, since each event reaches every subscriber once.
+
+## Batching
+
+`EventEmitterPubSub` honors `options.batch` natively. When a subscriber opts in, events are held in a per-subscriber in-memory buffer and delivered as consecutive callback invocations once a flush condition is met. Both fan-out and group subscribers can batch. See [`SubscribeBatchOptions`](https://mastra.ai/reference/pubsub/base) for the full policy.
+
+```typescript
+await pubsub.subscribe(
+  'workflow.events',
+  event => {
+    console.log(event)
+  },
+  {
+    batch: {
+      maxSize: 10, // flush once 10 events have queued
+      maxWaitMs: 500, // ...or after 500ms, whichever comes first
+    },
+  },
+)
+```
+
+The buffer is in-memory and per-process, so batched state is not persisted and does not survive a restart. A flush triggered by `maxWaitMs` is best-effort: if a step such as a throwing `coalesce` fails, the error is surfaced through the configured `logger` rather than thrown. `flush()` drains every batched subscriber buffer before resolving.

package/.docs/reference/signals/create-notification-inbox-tool.md

@@ -0,0 +1,67 @@
+# createNotificationInboxTool()
+
+**Added in:** `@mastra/core@1.39.0`
+
+`createNotificationInboxTool()` creates a Mastra tool that lets an agent inspect and manage notification inbox records for the current thread.
+
+Use this tool with durable notification signals. For sending notification records, see [`Agent.sendNotificationSignal()`](https://mastra.ai/reference/agents/agent).
+
+## Usage example
+
+The following example adds the inbox tool to an agent.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createNotificationInboxTool } from '@mastra/core/notifications'
+
+const notificationsStorage = await storage.getStore('notifications')
+
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support Agent',
+  instructions: 'Help the user triage updates.',
+  model: 'openai/gpt-5.5',
+  tools: {
+    notificationInbox: createNotificationInboxTool({ storage: notificationsStorage }),
+  },
+})
+```
+
+## Parameters
+
+**options** (`object`): Tool configuration.
+
+**options.storage** (`NotificationsStorage`): Notification storage domain returned by \`storage.getStore('notifications')\`.
+
+## Tool input
+
+The generated tool has the id `notification-inbox` and accepts these input fields.
+
+**action** (`'list' | 'read' | 'markSeen' | 'dismiss' | 'archive' | 'search'`): Inbox action to perform.
+
+**threadId** (`string`): Thread ID to inspect. Defaults to the current agent thread when available.
+
+**id** (`string`): Notification ID. Required for \`markSeen\`, \`dismiss\`, and \`archive\`. Optional for \`read\`.
+
+**status** (`'pending' | 'delivered' | 'seen' | 'dismissed' | 'archived' | 'discarded'`): Status filter for list, read, or search actions.
+
+**priority** (`'low' | 'medium' | 'high' | 'urgent'`): Priority filter for list, read, or search actions.
+
+**source** (`string`): Source filter for list, read, or search actions.
+
+**query** (`string`): Search query. Required when \`action\` is \`search\`.
+
+**limit** (`number`): Maximum number of notifications to return. Must be a positive integer.
+
+## Actions
+
+| Action     | Description                                                                             |
+| ---------- | --------------------------------------------------------------------------------------- |
+| `list`     | Returns matching notifications.                                                         |
+| `read`     | Delivers readable notification contents as signals and marks delivered records as seen. |
+| `markSeen` | Marks one notification as seen.                                                         |
+| `dismiss`  | Marks one notification as dismissed.                                                    |
+| `archive`  | Marks one notification as archived.                                                     |
+| `search`   | Searches notifications by query and optional filters.                                   |
+
+When `read` finds pending or delivered notifications, the tool delivers their contents as notification signals instead of returning the full contents as normal tool output. Use this after a `<notification-summary>` signal when the agent needs the full records behind the summary.

package/.docs/reference/signals/signal-provider.md

@@ -0,0 +1,406 @@
+# SignalProvider
+
+**Added in:** `@mastra/core@1.39.0`
+
+Abstract base class for building signal providers. A signal provider monitors external sources (APIs, webhooks, event streams) and pushes notification signals into agent threads through a built-in subscription registry.
+
+Signal providers aren't processors by default. Providers that need to intercept agent execution return processors from `getInputProcessors()` or `getOutputProcessors()`. Providers that expose agent-callable tools return them from `getTools()`.
+
+For a ready-to-use webhook-based provider, see [`WebhookSignalProvider`](https://mastra.ai/reference/signals/webhook-signal-provider).
+
+## Usage example
+
+Polling provider that checks an API every 30 seconds:
+
+```typescript
+import { SignalProvider } from '@mastra/core/signals'
+import type { SignalSubscription } from '@mastra/core/signals'
+
+class SlackSignals extends SignalProvider<'slack-signals'> {
+  readonly id = 'slack-signals'
+  readonly pollInterval = 30_000
+
+  async poll(subscriptions: SignalSubscription[]) {
+    for (const sub of subscriptions) {
+      const messages = await fetchSlackMessages(sub.externalResourceId)
+      if (messages.length > 0) {
+        await this.notify(
+          {
+            source: 'slack',
+            kind: 'new-messages',
+            summary: `${messages.length} new messages in ${sub.externalResourceId}`,
+          },
+          { threadId: sub.threadId, resourceId: sub.resourceId },
+        )
+      }
+    }
+  }
+}
+```
+
+Register with an agent:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+const agent = new Agent({
+  signals: [new SlackSignals()],
+})
+```
+
+The agent calls `connect(this)`, registers any processors or tools the provider returns, and starts polling.
+
+## Constructor parameters
+
+`SignalProvider` is abstract. Subclasses call `super()` with no arguments.
+
+## Properties
+
+**id** (`TId extends string`): Unique identifier for this provider. Subclasses must implement this as a readonly property.
+
+**name** (`string`): Human-readable display name for the provider.
+
+**pollInterval** (`number`): Poll interval in milliseconds. When set, the framework calls \`poll()\` on this interval. Leave \`undefined\` or \`0\` for webhook-only providers.
+
+**isConnected** (`boolean`): Whether this provider is connected to an agent. Returns \`true\` after \`connect()\` is called. Used internally to skip re-wiring during \`Agent.\_\_fork()\`.
+
+## Methods
+
+### Connection
+
+#### `connect(agent)`
+
+Called by the Agent constructor. Establishes the bidirectional link so the provider can send signals back to the agent. Override to run additional setup after the link is established. Always call `super.connect(agent)`.
+
+```typescript
+class MySignals extends SignalProvider<'my-signals'> {
+  readonly id = 'my-signals'
+
+  override connect(agent) {
+    super.connect(agent)
+    // additional setup after agent link is established
+  }
+}
+```
+
+#### `__registerMastra(mastra)`
+
+Called when the provider's agent is registered with a Mastra instance. Override to access storage or other Mastra services. Always call `super.__registerMastra(mastra)`.
+
+```typescript
+override __registerMastra(mastra) {
+  super.__registerMastra(mastra)
+  // this.mastra is now available
+}
+```
+
+### Processor and tool integration
+
+#### `getInputProcessors()`
+
+Return input processors this provider needs to be registered with the agent. Override when your provider intercepts agent input steps (for example, injecting context hints or detecting tool calls).
+
+```typescript
+getInputProcessors() {
+  return [this]
+}
+```
+
+Returns: `InputProcessorOrWorkflow[]`
+
+#### `getOutputProcessors()`
+
+Return output processors this provider needs to be registered with the agent. Override when your provider intercepts agent output steps.
+
+```typescript
+getOutputProcessors() {
+  return [this]
+}
+```
+
+Returns: `OutputProcessorOrWorkflow[]`
+
+#### `getTools()`
+
+Return tools this provider exposes to the agent. Override when your provider adds agent-callable tools such as subscribe or unsubscribe commands.
+
+```typescript
+getTools() {
+  return {
+    subscribe_pr: createTool({ /* ... */ }),
+    unsubscribe_pr: createTool({ /* ... */ }),
+  }
+}
+```
+
+Returns: `Record<string, unknown>`
+
+### Subscription tracking
+
+#### `subscribe(target, externalResourceId, metadata?)`
+
+Subscribe a thread to an external resource. This is a protected method — call it from within your provider implementation.
+
+```typescript
+const sub = this.subscribe(
+  { threadId: 'thread-1', resourceId: 'user-1' },
+  'github:mastra-ai/mastra#123',
+  { pr: 123 },
+)
+```
+
+Returns: `SignalSubscription` — the created subscription, or the existing one with merged metadata.
+
+**target** (`SignalProviderTarget`): The thread to subscribe. Must include \`threadId\` and \`resourceId\`.
+
+**externalResourceId** (`string`): Provider-specific identifier for the external resource (for example, \`"github:owner/repo#123"\`).
+
+**metadata** (`Record<string, unknown>`): Additional data to store with the subscription. Merged into existing metadata on duplicate subscribes.
+
+#### `unsubscribe(target, externalResourceId)`
+
+Remove a subscription.
+
+```typescript
+const removed = this.unsubscribe(
+  { threadId: 'thread-1', resourceId: 'user-1' },
+  'github:mastra-ai/mastra#123',
+)
+```
+
+Returns: `boolean` — `true` if removed, `false` if no matching subscription existed.
+
+#### `getSubscriptions()`
+
+Return all active subscriptions for this provider.
+
+```typescript
+const allSubs = this.getSubscriptions()
+```
+
+Returns: `SignalSubscription[]`
+
+#### `getSubscriptionsForResource(externalResourceId)`
+
+Return all subscriptions for a specific external resource.
+
+```typescript
+const subs = this.getSubscriptionsForResource('github:mastra-ai/mastra#123')
+for (const sub of subs) {
+  await this.notify(
+    { source: 'my-provider', kind: 'update', summary: 'Resource updated' },
+    { threadId: sub.threadId, resourceId: sub.resourceId },
+  )
+}
+```
+
+Returns: `SignalSubscription[]`
+
+#### `getSubscriptionsForThread(target)`
+
+Return all subscriptions for a specific thread.
+
+```typescript
+const subs = this.getSubscriptionsForThread({
+  threadId: 'thread-1',
+  resourceId: 'user-1',
+})
+```
+
+Returns: `SignalSubscription[]`
+
+#### `hasSubscription(target, externalResourceId)`
+
+Check whether a subscription exists.
+
+```typescript
+if (this.hasSubscription(target, 'github:mastra-ai/mastra#123')) {
+  // already subscribed
+}
+```
+
+Returns: `boolean`
+
+#### `unsubscribeAll(target)`
+
+Remove all subscriptions for a thread.
+
+```typescript
+const removed = this.unsubscribeAll({
+  threadId: 'thread-1',
+  resourceId: 'user-1',
+})
+```
+
+Returns: `number` — count of removed subscriptions.
+
+#### `subscriptionCount`
+
+Total number of active subscriptions for this provider.
+
+```typescript
+if (this.subscriptionCount === 0) {
+  // nothing to poll
+}
+```
+
+Returns: `number`
+
+### Polling
+
+#### `poll(subscriptions)`
+
+Called on each poll cycle with all active subscriptions. Override to check external sources and emit notifications. The framework prevents overlapping poll cycles — if a `poll()` call takes longer than `pollInterval`, the next cycle is skipped.
+
+```typescript
+async poll(subscriptions: SignalSubscription[]) {
+  for (const sub of subscriptions) {
+    const events = await checkExternalSource(sub.externalResourceId)
+    for (const event of events) {
+      await this.notify(
+        { source: 'my-provider', kind: event.type, summary: event.message },
+        { threadId: sub.threadId, resourceId: sub.resourceId },
+      )
+    }
+  }
+}
+```
+
+#### `startPolling()`
+
+Start the polling timer. Called by the Agent after `connect()`. Idempotent — calling multiple times has no effect.
+
+```typescript
+provider.startPolling()
+```
+
+#### `stopPolling()`
+
+Stop the polling timer.
+
+```typescript
+provider.stopPolling()
+```
+
+### Webhooks
+
+#### `handleWebhook(request)`
+
+Handle an incoming webhook request. Override to parse the payload, match it to subscriptions, and emit notification signals. See [`WebhookSignalProvider`](https://mastra.ai/reference/signals/webhook-signal-provider) for a ready-to-use implementation.
+
+```typescript
+async handleWebhook(request) {
+  const payload = request.body as { repo: string, event: string }
+  const subs = this.getSubscriptionsForResource(payload.repo)
+
+  for (const sub of subs) {
+    await this.notify(
+      { source: 'github', kind: payload.event, summary: `Event on ${payload.repo}` },
+      { threadId: sub.threadId, resourceId: sub.resourceId },
+    )
+  }
+
+  return { status: 200, body: { matched: subs.length } }
+}
+```
+
+Returns: `Promise<{ status?: number; body?: unknown }>`
+
+### Lifecycle
+
+#### `start()`
+
+Called after `connect()` to run async initialization. Override when setup requires the agent or Mastra instance to be available.
+
+```typescript
+async start() {
+  await this.loadInitialState()
+}
+```
+
+#### `stop()`
+
+Called on shutdown. The default implementation stops polling and clears all subscriptions.
+
+```typescript
+provider.stop()
+```
+
+### Notifications
+
+#### `notify(notification, target)`
+
+Send a notification signal to the connected agent. This is a protected convenience wrapper around `agent.sendNotificationSignal()`.
+
+```typescript
+await this.notify(
+  {
+    source: 'my-provider',
+    kind: 'pr-updated',
+    summary: 'PR #123 was updated',
+    priority: 'high',
+    payload: { prNumber: 123 },
+  },
+  { threadId: 'thread-1', resourceId: 'user-1' },
+)
+```
+
+**notification** (`object`): The notification payload.
+
+**notification.source** (`string`): Identifier for the notification source.
+
+**notification.kind** (`string`): Type of event (for example, \`"pr-updated"\`, \`"new-message"\`).
+
+**notification.summary** (`string`): Human-readable summary of the event.
+
+**notification.priority** (`"high" | "medium" | "low"`): Notification priority.
+
+**notification.payload** (`unknown`): Arbitrary data attached to the notification.
+
+**target** (`SignalProviderTarget`): The thread to notify. Must include \`threadId\` and \`resourceId\`.
+
+## Types
+
+### `SignalSubscription`
+
+The subscription object returned by `subscribe()`.
+
+**id** (`string`): Unique identifier for the subscription.
+
+**providerId** (`string`): The provider that owns this subscription.
+
+**threadId** (`string`): The thread receiving signals.
+
+**resourceId** (`string`): The resource owning the thread.
+
+**externalResourceId** (`string`): Provider-specific identifier for the external resource (for example, \`"github:owner/repo#123"\`).
+
+**subscribedAt** (`Date`): When the subscription was created.
+
+**metadata** (`Record<string, unknown>`): Provider-specific metadata stored with the subscription.
+
+### `SignalProviderTarget`
+
+Identifies a specific agent thread.
+
+**threadId** (`string`): The thread to target.
+
+**resourceId** (`string`): The resource owning the thread.
+
+**agentId** (`string`): Agent identifier.
+
+## Type guard
+
+### `isSignalProvider(obj)`
+
+Runtime check for `SignalProvider` instances.
+
+```typescript
+import { isSignalProvider } from '@mastra/core/signals'
+
+if (isSignalProvider(obj)) {
+  obj.connect(agent)
+}
+```
+
+Returns: `boolean`