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

package/.docs/guides/guide/signal-provider.md

@@ -0,0 +1,217 @@
+# Building a signal provider
+
+In this guide, you'll build a signal provider that polls an external service on an interval and pushes a notification into an agent thread whenever a watched resource changes. You'll learn how to extend the `SignalProvider` base class, track subscriptions, emit notifications from a poll loop, and register the provider on an agent.
+
+The example watches build pipelines in a fake CI service, but the pattern applies to any pull-based source: an issue tracker, a status API, a queue, or your own backend.
+
+> **Alpha:** Signal providers are in alpha. Breaking changes may occur without a major version bump until the API is stable.
+
+## Prerequisites
+
+- Node.js `v22.13.0` or later installed
+- An API key from a supported [Model Provider](https://mastra.ai/models)
+- An existing Mastra project. Follow the [installation guide](https://mastra.ai/guides/getting-started/quickstart) if needed.
+
+This guide also assumes you understand [signals](https://mastra.ai/docs/agents/signals) at a high level. For the full API surface, see the [`SignalProvider` reference](https://mastra.ai/reference/signals/signal-provider).
+
+## Add notification storage
+
+A signal provider pushes [notification signals](https://mastra.ai/docs/agents/signals) into threads, and notifications require a storage adapter that supports the notifications domain. Configure storage on your Mastra instance.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { LibSQLStore } from '@mastra/libsql'
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({
+    url: 'file:./mastra.db',
+  }),
+})
+```
+
+LibSQL, PostgreSQL, and MongoDB all support notification records. Without notification storage, the provider's `notify()` calls throw at runtime.
+
+## Create the external service client
+
+Real providers call an external API. To keep this guide self-contained, create a small fake CI client that returns a build status for a pipeline. Swap this for your real API client later.
+
+```typescript
+export type BuildStatus = {
+  id: string
+  pipeline: string
+  status: 'passed' | 'failed' | 'running'
+}
+
+// Returns a random status so you can see notifications fire while testing.
+export async function fetchBuildStatus(pipeline: string): Promise<BuildStatus> {
+  const states: BuildStatus['status'][] = ['passed', 'failed', 'running']
+  const status = states[Math.floor(Math.random() * states.length)]!
+  return { id: `build_${Date.now()}`, pipeline, status }
+}
+```
+
+This client returns a random status each call. When you wire in a real API, only this file changes.
+
+## Build the signal provider
+
+Extend `SignalProvider`, implement the abstract `id` field, set a `pollInterval`, and override `poll()`. The base class calls `poll()` on the interval with every active subscription. Emit a notification only for the builds you care about.
+
+```typescript
+import { SignalProvider } from '@mastra/core/signals'
+import type { SignalProviderTarget, SignalSubscription } from '@mastra/core/signals'
+import { fetchBuildStatus } from './ci-client'
+
+export class CiSignals extends SignalProvider<'ci-signals'> {
+  readonly id = 'ci-signals' as const
+  readonly pollInterval = 10_000 // poll every 10 seconds
+
+  // Public API so callers can subscribe a thread to a pipeline.
+  watch(target: SignalProviderTarget, pipeline: string): SignalSubscription {
+    return this.subscribe(target, pipeline)
+  }
+
+  unwatch(target: SignalProviderTarget, pipeline: string): boolean {
+    return this.unsubscribe(target, pipeline)
+  }
+
+  async poll(subscriptions: SignalSubscription[]): Promise<void> {
+    for (const sub of subscriptions) {
+      const build = await fetchBuildStatus(sub.externalResourceId)
+      if (build.status !== 'failed') continue
+
+      await this.notify(
+        {
+          source: this.id,
+          kind: 'ci-status',
+          priority: 'high',
+          summary: `Build failed for ${sub.externalResourceId}`,
+          payload: build,
+          dedupeKey: `${this.id}:${sub.externalResourceId}:${build.id}`,
+        },
+        { resourceId: sub.resourceId, threadId: sub.threadId },
+      )
+    }
+  }
+}
+```
+
+A few things to note:
+
+- `subscribe()` and `unsubscribe()` are protected on the base class. Wrap them in your own public methods (`watch` / `unwatch`) so callers can manage subscriptions.
+- `externalResourceId` is any provider-specific string. Here it's the pipeline name; a GitHub provider might use `"github:owner/repo#123"`.
+- `notify()` forwards a notification signal to the connected agent's thread. It throws if the provider was never registered on an agent.
+- `dedupeKey` prevents storing the same failure twice.
+
+## Register the provider on an agent
+
+Pass the provider to the agent through `signals`. The agent connects it and starts the poll loop automatically.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { CiSignals } from '../signals/ci-signals'
+
+export const ciSignals = new CiSignals()
+
+export const devAgent = new Agent({
+  id: 'dev-agent',
+  name: 'Dev Agent',
+  instructions: 'Help the user triage CI build failures.',
+  model: 'openai/gpt-5.5',
+  signals: [ciSignals],
+})
+```
+
+Register the agent with Mastra and add the storage from the first step.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { LibSQLStore } from '@mastra/libsql'
+import { devAgent } from './agents/dev-agent'
+
+export const mastra = new Mastra({
+  agents: { devAgent },
+  storage: new LibSQLStore({
+    url: 'file:./mastra.db',
+  }),
+})
+```
+
+## Subscribe a thread
+
+A provider only polls resources that a thread is watching. Subscribe a thread to a pipeline so `poll()` has something to check.
+
+```typescript
+import { ciSignals } from './agents/dev-agent'
+
+ciSignals.watch({ resourceId: 'user_123', threadId: 'thread_456' }, 'acme/app:main')
+```
+
+Run this once after the agent is registered, for example from a setup script or an API route. The subscription lives in the provider's in-memory registry, so re-subscribe after a restart.
+
+## Test the signal provider
+
+Start the dev server:
+
+**npm**:
+
+```bash
+npm run dev
+```
+
+**pnpm**:
+
+```bash
+pnpm run dev
+```
+
+**Yarn**:
+
+```bash
+yarn dev
+```
+
+**Bun**:
+
+```bash
+bun run dev
+```
+
+Make sure a thread is subscribed, then watch the logs. The fake client returns a random status each poll, so within a few cycles you'll see a failed build trigger a notification for the subscribed thread.
+
+To see the agent react to the notification, subscribe to the thread and stream it:
+
+```typescript
+const subscription = await devAgent.subscribeToThread({
+  resourceId: 'user_123',
+  threadId: 'thread_456',
+})
+
+for await (const chunk of subscription.stream) {
+  console.log(chunk)
+}
+```
+
+When a build fails, the model receives the notification as context:
+
+```xml
+<notification source="ci-signals" type="ci-status" priority="high" status="delivered">Build failed for acme/app:main</notification>
+```
+
+Output is non-deterministic because the fake client randomizes status and the model phrases its reply freely, so the exact wording will vary.
+
+## Next steps
+
+You can extend this signal provider to:
+
+- Replace `fetchBuildStatus()` with a real API client.
+- Persist subscriptions so they survive a restart, then rehydrate them in [`start()`](https://mastra.ai/reference/signals/signal-provider).
+- Add a [webhook](https://mastra.ai/docs/agents/signal-providers) entry point with [`handleWebhook()`](https://mastra.ai/reference/signals/signal-provider) for push-based sources.
+- Expose `subscribe` and `unsubscribe` tools with [`getTools()`](https://mastra.ai/reference/signals/signal-provider) so the agent can manage its own subscriptions.
+- Use [`dedupeKey` and `coalesceKey`](https://mastra.ai/reference/agents/agent) when notifications need deduplication or batching.
+
+Learn more:
+
+- [Building signal providers](https://mastra.ai/docs/agents/signal-providers)
+- [Signals](https://mastra.ai/docs/agents/signals)
+- [`SignalProvider` reference](https://mastra.ai/reference/signals/signal-provider)
+- [`WebhookSignalProvider` reference](https://mastra.ai/reference/signals/webhook-signal-provider)

package/.docs/guides/migrations/upgrade-to-v1/tracing.md

@@ -127,7 +127,7 @@ Key changes:
 3. Use explicit `configs:` with `MastraStorageExporter`, `MastraPlatformExporter`, and `SensitiveDataFilter`
 4. Export types change from string literals (`'otlp'`) to exporter class instances (`new OtelExporter()`)
 
-See the [exporters documentation](https://mastra.ai/docs/observability/tracing/overview) for all available exporters.
+See the [exporters documentation](https://mastra.ai/docs/observability/integrations/overview) for all available exporters.
 
 ### From AI Tracing
 
@@ -292,7 +292,7 @@ To migrate, follow the "From OTEL-based Telemetry" section above. For detailed c
 
 The automatic detection of instrumentation files in `/mastra` (with `.ts`, `.js`, or `.mjs` extensions) has been removed. Custom instrumentation is no longer supported through separate files.
 
-To migrate, use the built-in exporter system or implement custom exporters using the `ObservabilityExporter` interface. See the [exporters documentation](https://mastra.ai/docs/observability/tracing/overview) for details.
+To migrate, use the built-in exporter system or implement custom exporters using the `ObservabilityExporter` interface. See the [exporters documentation](https://mastra.ai/docs/observability/integrations/overview) for details.
 
 ### `instrumentation.mjs` files
 
@@ -352,14 +352,14 @@ No separate instrumentation files or special startup flags required.
 
 If you were using OTEL-based telemetry with specific providers in 0.x, here's how to configure them in v1:
 
-| Provider                                                  | Exporter          | Guide                                                                      | Reference                                                                           |
-| --------------------------------------------------------- | ----------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
-| Arize AX, Arize Phoenix                                   | **Arize**         | [Guide](https://mastra.ai/docs/observability/tracing/exporters/arize)      | [Reference](https://mastra.ai/reference/observability/tracing/exporters/arize)      |
-| Braintrust                                                | **Braintrust**    | [Guide](https://mastra.ai/docs/observability/tracing/exporters/braintrust) | [Reference](https://mastra.ai/reference/observability/tracing/exporters/braintrust) |
-| Langfuse                                                  | **Langfuse**      | [Guide](https://mastra.ai/docs/observability/tracing/exporters/langfuse)   | [Reference](https://mastra.ai/reference/observability/tracing/exporters/langfuse)   |
-| LangSmith                                                 | **LangSmith**     | [Guide](https://mastra.ai/docs/observability/tracing/exporters/langsmith)  | [Reference](https://mastra.ai/reference/observability/tracing/exporters/langsmith)  |
-| Dash0, Laminar, New Relic, SigNoz, Traceloop, Custom OTEL | **OpenTelemetry** | [Guide](https://mastra.ai/docs/observability/tracing/exporters/otel)       | [Reference](https://mastra.ai/reference/observability/tracing/exporters/otel)       |
-| LangWatch                                                 | \<coming soon>    | -                                                                          | -                                                                                   |
+| Provider                                                  | Exporter          | Guide                                                                           | Reference                                                                           |
+| --------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
+| Arize AX, Arize Phoenix                                   | **Arize**         | [Guide](https://mastra.ai/docs/observability/integrations/exporters/arize)      | [Reference](https://mastra.ai/reference/observability/tracing/exporters/arize)      |
+| Braintrust                                                | **Braintrust**    | [Guide](https://mastra.ai/docs/observability/integrations/exporters/braintrust) | [Reference](https://mastra.ai/reference/observability/tracing/exporters/braintrust) |
+| Langfuse                                                  | **Langfuse**      | [Guide](https://mastra.ai/docs/observability/integrations/exporters/langfuse)   | [Reference](https://mastra.ai/reference/observability/tracing/exporters/langfuse)   |
+| LangSmith                                                 | **LangSmith**     | [Guide](https://mastra.ai/docs/observability/integrations/exporters/langsmith)  | [Reference](https://mastra.ai/reference/observability/tracing/exporters/langsmith)  |
+| Dash0, Laminar, New Relic, SigNoz, Traceloop, Custom OTEL | **OpenTelemetry** | [Guide](https://mastra.ai/docs/observability/integrations/exporters/otel)       | [Reference](https://mastra.ai/reference/observability/tracing/exporters/otel)       |
+| LangWatch                                                 | \<coming soon>    | -                                                                               | -                                                                                   |
 
 ### Installation
 
@@ -415,4 +415,4 @@ yarn add @mastra/otel-exporter@latest
 bun add @mastra/otel-exporter@latest
 ```
 
-Plus the required protocol package for your provider (see [OTEL guide](https://mastra.ai/docs/observability/tracing/exporters/otel)).
+Plus the required protocol package for your provider (see [OTEL guide](https://mastra.ai/docs/observability/integrations/exporters/otel)).

package/.docs/reference/agents/agent.md

@@ -141,6 +141,35 @@ The model receives this as:
 <user name="Devin" from="slack">Can we simplify the API surface?</user>
 ```
 
+Use `ifActive.attributes` and `ifIdle.attributes` when the message should carry different context depending on whether the thread is currently running:
+
+```typescript
+agent.sendMessage(
+  {
+    contents: 'Also cover the edge cases.',
+    attributes: { source: 'chat' },
+  },
+  {
+    resourceId: 'user-123',
+    threadId: 'thread-abc',
+    ifActive: { attributes: { delivery: 'while-active' } },
+    ifIdle: { attributes: { delivery: 'new-message' } },
+  },
+)
+```
+
+When the thread is active, the model sees:
+
+```xml
+<user source="chat" delivery="while-active">Also cover the edge cases.</user>
+```
+
+When the thread is idle, the model sees:
+
+```xml
+<user source="chat" delivery="new-message">Also cover the edge cases.</user>
+```
+
 The UI sees the message contents and can also read `attributes` and `metadata` off the signal message for custom rendering (e.g. showing user names, avatars, or platform badges).
 
 ### `sendMessage(message, options)`
@@ -149,18 +178,43 @@ Sends a user message to an active run or memory thread. Use this when the active
 
 **message** (`string | Array<TextPart | FilePart> | { contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }`): User-authored input. Bare strings and parts without attributes are sent to the model as normal user input. When \`attributes\` are present, Mastra renders the message as a \`\<user>\` XML element with the attributes included.
 
+**options** (`object`): Targeting and delivery behavior for the message.
+
 **options.runId** (`string`): Run ID to target directly. Use this when you already know the active run ID.
 
 **options.resourceId** (`string`): Resource ID for the memory thread. Required with \`threadId\` for thread-targeted messages.
 
 **options.threadId** (`string`): Thread ID to target. Required with \`resourceId\` for thread-targeted messages.
 
+**options.ifActive** (`object`): Controls what happens when the target thread is active.
+
 **options.ifActive.behavior** (`'deliver' | 'persist' | 'discard'`): Controls what happens when the target thread is active. Defaults to \`deliver\`.
 
+**options.ifActive.attributes** (`Record<string, string | number | boolean>`): Attributes merged into the message when Mastra accepts it while the target thread is active.
+
+**options.ifIdle** (`object`): Controls what happens when the target thread is idle.
+
 **options.ifIdle.behavior** (`'wake' | 'persist' | 'discard'`): Controls what happens when the target thread is idle. Defaults to \`wake\`.
 
 **options.ifIdle.streamOptions** (`AgentExecutionOptions`): Options for the stream that starts when \`ifIdle.behavior\` is \`wake\`. Mastra uses the top-level \`resourceId\` and \`threadId\` for memory context.
 
+**options.ifIdle.attributes** (`Record<string, string | number | boolean>`): Attributes merged into the message when Mastra accepts it while the target thread is idle.
+
+Set `ifIdle.behavior` to `wake` and pass `ifIdle.streamOptions` when an idle thread should start a new stream with custom execution options:
+
+```typescript
+agent.sendMessage('Continue with the next step.', {
+  resourceId: 'user-123',
+  threadId: 'thread-abc',
+  ifIdle: {
+    behavior: 'wake',
+    streamOptions: {
+      maxSteps: 3,
+    },
+  },
+})
+```
+
 Returns `{ accepted: true, runId: string, signal: CreatedAgentSignal, persisted?: Promise<void> }`. `persisted` is only present for `persist` behavior and resolves when Mastra finishes writing the message to memory.
 
 ### `queueMessage(message, options)`
@@ -182,20 +236,78 @@ Sends a signal to an active run or memory thread.
 
 **signal** (`{ type: 'user' | 'state' | 'reactive' | 'notification' | 'user-message' | 'system-reminder'; tagName?: string; contents: string | Array<TextPart | FilePart>; attributes?: Record<string, JSONValue>; metadata?: Record<string, unknown>; providerOptions?: ProviderMetadata }`): Signal context to send to the thread. \`type\` is the semantic signal category. \`tagName\` controls the XML tag the model sees. For example, \`{ type: 'notification', tagName: 'github-review' }\` renders as \`\<github-review>...\</github-review>\`. Legacy \`user-message\` and \`system-reminder\` payloads are still accepted and normalized. Unknown \`type\` values are rejected; use \`tagName\` for custom XML tags.
 
+**options** (`object`): Targeting and delivery behavior for the signal.
+
 **options.runId** (`string`): Run ID to target directly. Use this when you already know the active run ID.
 
 **options.resourceId** (`string`): Resource ID for the memory thread. Required with \`threadId\` for thread-targeted signals.
 
 **options.threadId** (`string`): Thread ID to target. Required with \`resourceId\` for thread-targeted signals.
 
+**options.ifActive** (`object`): Controls what happens when the target thread is active.
+
 **options.ifActive.behavior** (`'deliver' | 'persist' | 'discard'`): Controls what happens when the target thread is active. Defaults to \`deliver\`.
 
+**options.ifActive.attributes** (`Record<string, string | number | boolean>`): Attributes merged into the signal when Mastra accepts it while the target thread is active.
+
+**options.ifIdle** (`object`): Controls what happens when the target thread is idle.
+
 **options.ifIdle.behavior** (`'wake' | 'persist' | 'discard'`): Controls what happens when the target thread is idle. Defaults to \`wake\`.
 
 **options.ifIdle.streamOptions** (`AgentExecutionOptions`): Options for the stream that starts when \`ifIdle.behavior\` is \`wake\`. Mastra uses the top-level \`resourceId\` and \`threadId\` for memory context.
 
+**options.ifIdle.attributes** (`Record<string, string | number | boolean>`): Attributes merged into the signal when Mastra accepts it while the target thread is idle.
+
 Returns `{ accepted: true, runId: string, signal: CreatedAgentSignal, persisted?: Promise<void> }`. `persisted` is only present for `persist` behavior and resolves when Mastra finishes writing the signal to memory.
 
+### `sendStateSignal(state, options)`
+
+Sends named, thread-scoped state context to an active run or memory thread. Use this when an external producer owns durable context that changes over time, such as browser state, editor state, or watcher output.
+
+```typescript
+const result = await agent.sendStateSignal(
+  {
+    id: 'browser',
+    mode: 'snapshot',
+    cacheKey: 'browser:https://example.com:3-tabs',
+    contents: 'Browser is open on https://example.com with 3 tabs.',
+    value: {
+      activeUrl: 'https://example.com',
+      tabCount: 3,
+      open: true,
+    },
+  },
+  {
+    resourceId: 'user-123',
+    threadId: 'thread-abc',
+  },
+)
+```
+
+**state** (`object`): State signal to send to the thread.
+
+**state.id** (`string`): State lane name, such as \`browser\` or \`editor\`.
+
+**state.cacheKey** (`string`): Producer-owned key Mastra uses to skip duplicate state for the same lane and mode.
+
+**state.contents** (`string | Array<TextPart | FilePart>`): LLM-facing representation of the state.
+
+**state.mode** (`'snapshot' | 'delta'`): Whether the state is an authoritative snapshot or a change event. Defaults to \`snapshot\`.
+
+**state.value** (`unknown`): Structured snapshot value for \`mode: 'snapshot'\`.
+
+**state.delta** (`unknown`): Structured change value for \`mode: 'delta'\`.
+
+**state.attributes** (`Record<string, string | number | boolean>`): Attributes rendered on the state signal tag.
+
+**state.metadata** (`Record<string, unknown>`): Application metadata stored with the state signal.
+
+**state.tagName** (`string`): XML tag name shown to the model. Defaults to \`state\`.
+
+**options** (`object`): Targeting and delivery behavior for the state signal. Accepts the same options as \`sendSignal()\`.
+
+Returns `{ accepted: true, runId: string, signal: CreatedAgentSignal, persisted?: Promise<void>, skipped?: false }` when Mastra accepts new state. Returns `{ accepted: true, skipped: true, reason: 'unchanged' }` when the same `cacheKey` and mode are already current for the state lane.
+
 ### `sendNotificationSignal(notification, options)`
 
 Creates or coalesces a notification inbox record, resolves the notification delivery policy, and sends a notification signal when the decision is immediate.
@@ -216,6 +328,8 @@ const result = await agent.sendNotificationSignal(
 )
 ```
 
+**notification** (`object`): Notification inbox record to create or coalesce.
+
 **notification.source** (`string`): External system that produced the notification, such as \`github\`, \`slack\`, or \`email\`.
 
 **notification.kind** (`string`): Notification kind within the source, such as \`ci-status\`, \`mention\`, or \`direct-message\`.
@@ -234,20 +348,52 @@ const result = await agent.sendNotificationSignal(
 
 **notification.metadata** (`Record<string, unknown>`): Application metadata stored on the inbox record.
 
+**options** (`object`): Target thread and wake-up behavior for the notification.
+
 **options.resourceId** (`string`): Resource ID for the notification inbox and target memory thread.
 
 **options.threadId** (`string`): Thread ID for the notification inbox and target memory thread.
 
+**options.ifIdle** (`object`): Controls what happens when the target thread is idle.
+
 **options.ifIdle.streamOptions** (`AgentExecutionOptions`): Options for the stream that starts when an immediate notification wakes an idle thread.
 
 Returns `{ accepted: true, record: NotificationRecord, decision: NotificationDeliveryDecision, runId?: string, signal?: CreatedAgentSignal, persisted?: Promise<void> }`. `record` is the stored inbox record. `decision` is the delivery-policy result. `signal` and `runId` are present when ingress emits a signal immediately, including the immediate summary emitted for active high-priority notifications. `persisted` is present when the emitted signal is persisted without waking an idle thread.
 
 Default delivery is priority-aware. `urgent` notifications deliver immediately. `high` notifications deliver immediately when the thread is idle; when the thread is active, Mastra emits a summary immediately and keeps `deliverAt` for later full delivery when the thread is idle. `medium` notifications deliver immediately when idle and batch into summaries when active. `low` notifications batch into summaries in both active and idle threads; idle low-priority summaries reach subscribers without waking the model loop. For the full flow, visit [Signals](https://mastra.ai/docs/agents/signals).
 
+Configure `notifications.deliveryPolicy` on the agent when some notifications should wait for a different dispatch window or summary rollup:
+
+```typescript
+export const supportAgent = new Agent({
+  id: 'support-agent',
+  name: 'Support Agent',
+  instructions: 'Help the user triage updates.',
+  model: 'openai/gpt-5.5',
+  notifications: {
+    deliveryPolicy: {
+      priorities: {
+        urgent: 'deliver',
+      },
+      decide: ({ record }) => {
+        if (record.priority === 'low') {
+          return {
+            action: 'summarize',
+            summaryAt: new Date(Date.now() + 30 * 60 * 1000),
+          }
+        }
+      },
+    },
+  },
+})
+```
+
 ### `subscribeToThread(options)`
 
 Subscribes to raw stream chunks for a memory thread. Use this before calling `sendMessage()`, `queueMessage()`, or `sendSignal()` when you need to render stream output, observe signal echoes, or abort the active run.
 
+**options** (`object`): Thread subscription target.
+
 **options.resourceId** (`string`): Resource ID for the memory thread.
 
 **options.threadId** (`string`): Thread ID to subscribe to.
@@ -282,8 +428,6 @@ Returns an `AgentThreadSubscription` object with these members:
 
 **transform** (`ToolPayloadTransformPolicy`): Shared policy for transforming tool payloads before display streams or user-visible transcript messages receive them. Use per-tool \`transform\` on \`createTool()\` for tool-local rules.
 
-**notifications** (`{ deliveryPolicy?: NotificationDeliveryPolicyConfig }`): Notification delivery configuration for \`sendNotificationSignal()\`. \`deliveryPolicy\` can define \`decide\`, \`sources\`, \`priorities\`, or \`default\` rules that return \`deliver\`, \`queue\`, \`defer\`, \`summarize\`, \`persist\`, or \`discard\` decisions.
-
 **workflows** (`Record<string, Workflow> | ({ requestContext: RequestContext }) => Record<string, Workflow> | Promise<Record<string, Workflow>>`): Workflows that the agent can execute. Can be static or dynamically resolved.
 
 **defaultOptions** (`AgentExecutionOptions | ({ requestContext: RequestContext }) => AgentExecutionOptions | Promise<AgentExecutionOptions>`): Default options used when calling \`stream()\` and \`generate()\`.
@@ -298,6 +442,10 @@ Returns an `AgentThreadSubscription` object with these members:
 
 **memory** (`MastraMemory | ({ requestContext: RequestContext }) => MastraMemory | Promise<MastraMemory>`): Memory module used for storing and retrieving stateful context.
 
+**notifications** (`object`): Notification delivery configuration for durable notification signals.
+
+**notifications.deliveryPolicy** (`NotificationDeliveryPolicyConfig`): Controls how notification records are delivered. Configure a default decision, per-priority decisions, per-source decisions, or a custom \`decide()\` function.
+
 **voice** (`CompositeVoice`): Voice settings for speech input and output.
 
 **inputProcessors** (`(Processor | ProcessorWorkflow)[] | ({ requestContext: RequestContext }) => (Processor | ProcessorWorkflow)[] | Promise<(Processor | ProcessorWorkflow)[]>`): Input processors that can modify or validate messages before they are processed by the agent. Can be individual Processor objects or workflows created with \`createWorkflow()\` using ProcessorStepSchema.

package/.docs/reference/client-js/agents.md

@@ -245,10 +245,14 @@ Returns `{ accepted: true, runId: string }`.
 
 **ifActive.behavior** (`'deliver' | 'persist' | 'discard'`): Controls what happens when the target thread is active. Defaults to \`deliver\`.
 
+**ifActive.attributes** (`Record<string, string | number | boolean>`): Attributes merged into the signal when Mastra accepts it while the target thread is active.
+
 **ifIdle.behavior** (`'wake' | 'persist' | 'discard'`): Controls what happens when the target thread is idle. Defaults to \`wake\`.
 
 **ifIdle.streamOptions** (`Omit<AgentExecutionOptions, 'messages'>`): Options for the stream that starts when \`ifIdle.behavior\` is \`wake\`.
 
+**ifIdle.attributes** (`Record<string, string | number | boolean>`): Attributes merged into the signal when Mastra accepts it while the target thread is idle.
+
 ### `subscribeToThread()`
 
 Subscribe to raw stream chunks for a memory thread. Use this to render output from a thread that may be started or continued by `sendMessage()`, `queueMessage()`, `sendSignal()`, or server-side notification dispatch.

package/.docs/reference/core/mastra-class.md

@@ -27,6 +27,24 @@ export const mastra = new Mastra({
 })
 ```
 
+Enable scheduled notification dispatch when deferred notification records and notification summaries should be delivered automatically through the workflow scheduler:
+
+```typescript
+export const mastra = new Mastra({
+  agents: { supportAgent },
+  storage,
+  notifications: {
+    dispatch: {
+      enabled: true,
+      cron: '*/1 * * * *',
+      batchSize: 100,
+    },
+  },
+})
+```
+
+`notifications.dispatch.enabled` registers an internal workflow with the default cron `*/1 * * * *`. The dispatcher reads due notification records from storage, groups summaries by `agentId`, `resourceId`, and `threadId`, and emits signals through the agent thread runtime. It isn't a user-facing entrypoint.
+
 ## Constructor parameters
 
 Visit the [Configuration reference](https://mastra.ai/reference/configuration) for detailed documentation on all available configuration options.
@@ -67,6 +85,16 @@ Visit the [Configuration reference](https://mastra.ai/reference/configuration) f
 
 **memory** (`Record<string, MastraMemory>`): Memory instances to register. These can be referenced by stored agents and resolved at runtime. Structured as a key-value pair, with keys being the registry key and values being memory instances. (Default: `{}`)
 
+**notifications** (`object`): Runtime configuration for notification signal dispatch.
+
+**notifications.dispatch** (`NotificationDispatchConfig`): Scheduled dispatch configuration for deferred notifications and notification summaries. Dispatch is enabled by default.
+
+**notifications.dispatch.enabled** (`boolean`): Set to \`false\` to opt out of automatic scheduled notification dispatch.
+
+**notifications.dispatch.cron** (`string`): Cron schedule used by the internal notification dispatcher workflow.
+
+**notifications.dispatch.batchSize** (`number`): Maximum number of due notification records to process per dispatch run.
+
 **versions** (`VersionOverrides`): Global version overrides for sub-agent delegation. When a supervisor agent delegates to a sub-agent, these overrides determine which stored version of that sub-agent to use instead of the code-defined default. Requires the editor package to be configured. See \[Sub-agent versioning]\(/docs/editor/overview#sub-agent-versioning) for details.
 
 **versions.agents** (`Record<string, VersionSelector>`): A map of agent IDs to their version selectors. Each selector can target a specific version by ID or by publication status.

package/.docs/reference/harness/harness-class.md

@@ -2,7 +2,7 @@
 
 **Added in:** `@mastra/core@1.5.0`
 
-> **Warning:** The `Harness` class is in alpha stage and subject to change. It won't follow semantic versioning guarantees until it graduates from experimental status. Use with caution and expect breaking changes in minor versions.
+> **Alpha:** The `Harness` class is in alpha stage and subject to change. It won't follow semantic versioning guarantees until it graduates from experimental status. Use with caution and expect breaking changes in minor versions.
 >
 > [Mastra Code](https://code.mastra.ai/) is the flagship implementation of the `Harness` class, showcasing how it can be used to build a powerful terminal-based coding agent with multi-model support, persistent conversations, and built-in tools.
 

package/.docs/reference/index.md

@@ -220,6 +220,9 @@ The Reference section provides documentation of Mastra's API, including paramete
 - [NestJS Adapter](https://mastra.ai/reference/server/nestjs-adapter)
 - [registerApiRoute()](https://mastra.ai/reference/server/register-api-route)
 - [Server Routes](https://mastra.ai/reference/server/routes)
+- [createNotificationInboxTool()](https://mastra.ai/reference/signals/create-notification-inbox-tool)
+- [SignalProvider](https://mastra.ai/reference/signals/signal-provider)
+- [WebhookSignalProvider](https://mastra.ai/reference/signals/webhook-signal-provider)
 - [Overview](https://mastra.ai/reference/storage/overview)
 - [Aurora DSQL Storage](https://mastra.ai/reference/storage/dsql)
 - [ClickHouse Storage](https://mastra.ai/reference/storage/clickhouse)

package/.docs/reference/observability/tracing/bridges/datadog.md

@@ -155,7 +155,7 @@ const mastra = new Mastra({
 
 The DatadogBridge requires `dd-trace` to be initialized before any other imports so its auto-instrumentation can patch HTTP, database, and framework libraries at load time.
 
-See the [DatadogBridge Guide](https://mastra.ai/docs/observability/tracing/bridges/datadog) for complete setup instructions, including dd-trace initialization, bundler externals, and agent configuration.
+See the [DatadogBridge Guide](https://mastra.ai/docs/observability/integrations/bridges/datadog) for complete setup instructions, including dd-trace initialization, bundler externals, and agent configuration.
 
 ## Span mapping
 
@@ -206,6 +206,6 @@ The bridge reads configuration from these environment variables:
 
 ## Related
 
-- [DatadogBridge Guide](https://mastra.ai/docs/observability/tracing/bridges/datadog) - Setup guide with examples
+- [DatadogBridge Guide](https://mastra.ai/docs/observability/integrations/bridges/datadog) - Setup guide with examples
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview) - General tracing concepts
 - [DatadogExporter Reference](https://mastra.ai/reference/observability/tracing/exporters/datadog) - LLM Observability only, no `dd-trace` APM

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

@@ -118,7 +118,7 @@ const mastra = new Mastra({
 
 The OtelBridge requires an active OpenTelemetry SDK to function. The bridge reads from OTEL's ambient context.
 
-See the [OtelBridge Guide](https://mastra.ai/docs/observability/tracing/bridges/otel) for complete setup instructions, including how to configure OTEL instrumentation and run your application.
+See the [OtelBridge Guide](https://mastra.ai/docs/observability/integrations/bridges/otel) for complete setup instructions, including how to configure OTEL instrumentation and run your application.
 
 ## Tags support
 
@@ -148,6 +148,6 @@ This format ensures compatibility with all OTEL-compatible backends and collecto
 
 ## Related
 
-- [OtelBridge Guide](https://mastra.ai/docs/observability/tracing/bridges/otel): Setup guide with examples
+- [OtelBridge Guide](https://mastra.ai/docs/observability/integrations/bridges/otel): Setup guide with examples
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview): General tracing concepts
 - [OtelExporter Reference](https://mastra.ai/reference/observability/tracing/exporters/otel): OTEL exporter for sending traces

package/.docs/reference/observability/tracing/configuration.md

@@ -194,7 +194,7 @@ Shuts down all observability instances and clears the registry.
 
 - [Tracing Overview](https://mastra.ai/docs/observability/tracing/overview): Concepts and usage guide
 - [Sampling Strategies](https://mastra.ai/docs/observability/tracing/overview): Sampling configuration details
-- [Multi-Config Setup](https://mastra.ai/docs/observability/tracing/overview): Using multiple configurations
+- [Multi-Config Setup](https://mastra.ai/docs/observability/config): Using multiple configurations
 
 ### Reference
 

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

@@ -136,6 +136,6 @@ Tags are stored using the OpenInference `tag.tags` attribute:
 
 ## Related
 
-- [ArizeExporter Documentation](https://mastra.ai/docs/observability/tracing/exporters/arize)
+- [ArizeExporter Documentation](https://mastra.ai/docs/observability/integrations/exporters/arize)
 - [Phoenix Documentation](https://docs.arize.com/phoenix)
 - [Arize AX Documentation](https://docs.arize.com/)

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

@@ -117,6 +117,6 @@ Tags are stored using the OpenInference `tag.tags` attribute:
 
 ## Related
 
-- [ArthurExporter Documentation](https://mastra.ai/docs/observability/tracing/exporters/arthur)
+- [ArthurExporter Documentation](https://mastra.ai/docs/observability/integrations/exporters/arthur)
 - [Arthur Engine documentation](https://docs.arthur.ai/)
 - [Arthur Engine repository](https://github.com/arthur-ai/arthur-engine)