@mastra/mcp-docs-server 1.1.42 → 1.1.43

package/.docs/docs/agents/signals.md

@@ -97,7 +97,7 @@ The behavior options are:
 - `ifIdle.behavior: 'persist'`: Save the signal or message to memory without starting a stream.
 - `ifIdle.behavior: 'discard'`: Ignore the signal or message while the thread is idle.
 
-Pass `ifIdle.streamOptions` when the idle wake-up stream needs options such as model settings, tools, or runtime context. You do not need to repeat `memory.resource` or `memory.thread`; Mastra uses the top-level `resourceId` and `threadId` for the thread.
+Pass `ifIdle.streamOptions` when the idle wake-up stream needs options such as model settings, tools, or runtime context. You don't need to repeat `memory.resource` or `memory.thread`; Mastra uses the top-level `resourceId` and `threadId` for the thread.
 
 ```typescript
 agent.sendMessage('Continue with the next step.', {
@@ -143,6 +143,10 @@ The model receives the signal as context like this:
 
 Use XML-safe `tagName` and attribute names. They can contain letters, numbers, underscores, periods, and hyphens. They must start with a letter or underscore.
 
+### Storage support
+
+Notification inbox storage is available in the storage adapters that support richer memory and signal workflows: [libSQL](https://mastra.ai/reference/storage/libsql), [PostgreSQL](https://mastra.ai/reference/storage/postgresql), and [MongoDB](https://mastra.ai/reference/storage/mongodb). These adapters expose notification records through `getStore('notifications')`.
+
 ## Send processor context
 
 Processors can send reactive signals during a run. A processor should inspect the chat history, react to a specific trigger, and avoid sending the same context more than once.
@@ -220,7 +224,224 @@ When the agent is idle:
 <user source="chat" delivery="new-message">Also cover the edge cases.</user>
 ```
 
-Top-level `attributes` always apply. The selected branch's `attributes` are merged into them at delivery time. The `delivery` name shown above is not a special Mastra API field. It is a custom attribute name used for this example, you can add any attribute names that suit your use case.
+Top-level `attributes` always apply. The selected branch's `attributes` are merged into them at delivery time. The `delivery` name shown above isn't a special Mastra API field. It's a custom attribute name used for this example. Add any attribute names that suit your use case.
+
+## State signals
+
+State signals expose named, thread-scoped context lanes. Use them for durable context that changes over time, such as browser state, editor state, or a background watcher result.
+
+Each state signal needs:
+
+- `id`: The state lane name, such as `browser`.
+- `cacheKey`: A producer-owned key for deduping the current state.
+- `mode`: `snapshot` for an authoritative state copy, or `delta` for a change event.
+
+Use `sendStateSignal()` when an external producer detects a state change.
+
+```typescript
+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_456',
+  },
+)
+```
+
+When Mastra accepts a state signal, it stores compact tracking metadata on the thread. The metadata records the lane's current `cacheKey`, current mode, version, last signal id, and last snapshot signal id. If a producer sends the same `cacheKey` and mode again while that state is still current, Mastra skips the duplicate.
+
+State signal fields have separate roles:
+
+- `contents`: The representation the model reads.
+- `value`: The structured snapshot for `mode: 'snapshot'`.
+- `delta`: The structured change for `mode: 'delta'`.
+- `metadata.state`: The runtime tracking envelope with `id`, `mode`, `cacheKey`, `version`, and `threadId`.
+
+Use `computeStateSignal()` when a processor owns a state lane. Mastra calls it once per model input step after `processInputStep()`. If the processor omits `id`, Mastra uses the processor id as the state lane id. Set `stateId` when the public state lane should differ from the processor id.
+
+```typescript
+import type { ComputeStateSignalArgs, Processor } from '@mastra/core/processors'
+
+export const browserStateProcessor: Processor = {
+  id: 'browser-state',
+  stateId: 'browser',
+  computeStateSignal(args: ComputeStateSignalArgs) {
+    const browser = readCurrentBrowserState()
+    const previous = readMostRecentBrowserState(args.activeStateSignals)
+    const changed = previous ? diffBrowserState(previous, browser) : browser
+    const shouldRefreshSnapshot = Boolean(args.lastSnapshot && !args.contextWindow.hasSnapshot)
+
+    if (previous && Object.keys(changed).length === 0 && !shouldRefreshSnapshot) {
+      return
+    }
+
+    const isDelta = Boolean(previous && !shouldRefreshSnapshot)
+
+    return {
+      mode: isDelta ? 'delta' : 'snapshot',
+      cacheKey: stableBrowserStateCacheKey(browser),
+      contents: isDelta ? describeBrowserDelta(changed) : describeBrowserSnapshot(browser),
+      value: browser,
+      ...(isDelta ? { delta: changed } : {}),
+    }
+  },
+}
+```
+
+Mastra passes `lastSnapshot` and `deltasSinceSnapshot` into `computeStateSignal()`. It resolves them from message history when the current message list doesn't contain the latest snapshot. The processor still owns merge and diff logic.
+
+`contextWindow.hasSnapshot` tells the processor whether the active message window already contains a snapshot for this state lane. If it's `false`, return a fresh `snapshot` so the model sees the current state even after older state messages are trimmed from the context window.
+
+The built-in browser context processor emits state under the `browser` id with snapshot and delta modes.
+
+## Notification signals
+
+Notification signals represent external events such as GitHub activity, email, Slack mentions, CI status, incidents, recordings, or direct messages. Use `agent.sendNotificationSignal()` when the event should create a durable inbox record.
+
+Notification delivery has two phases:
+
+- **Ingress**: `agent.sendNotificationSignal()` stores a notification record, then resolves the agent's delivery policy.
+- **Dispatch**: Mastra consumes due records stamped with `deliverAt` or `summaryAt` and emits full notification or summary signals.
+
+A notification record stores the source, kind, priority, summary, payload, resource id, thread id, agent id, coalescing keys, and delivery metadata. The delivery decision controls what happens after ingress:
+
+- `deliver` or `queue`: Emit a full `<notification>` signal and mark the record `delivered`.
+- `defer`: Keep the record `pending` with `deliverAt`.
+- `summarize`: Keep the record `pending` with `summaryAt`, or emit an immediate summary when the policy requests it.
+- `persist`: Keep the record `pending` in the inbox without scheduled delivery.
+- `discard`: Mark the record `discarded` and emit no signal.
+
+The default delivery policy is priority-aware:
+
+| Priority | Active thread                                                                                            | Idle thread                                                                                     |
+| -------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `urgent` | Deliver a full notification immediately                                                                  | Deliver a full notification immediately                                                         |
+| `high`   | Emit a summary immediately, keep `deliverAt`, then deliver the full notification when the thread is idle | Deliver a full notification immediately                                                         |
+| `medium` | Batch with `summaryAt` and later deliver one notification summary                                        | Deliver a full notification immediately                                                         |
+| `low`    | Batch with `summaryAt` and later deliver one notification summary                                        | Batch with `summaryAt` and later deliver one notification summary without waking the model loop |
+
+```typescript
+await agent.sendNotificationSignal(
+  {
+    source: 'github',
+    kind: 'ci-status',
+    priority: 'high',
+    summary: 'CI failed on main: 3 tests failed.',
+    payload: {
+      repository: 'acme/app',
+      branch: 'main',
+    },
+    dedupeKey: 'github:acme/app:main:ci',
+  },
+  {
+    resourceId: 'user_123',
+    threadId: 'thread_456',
+  },
+)
+```
+
+The model receives full notifications as context:
+
+```xml
+<notification source="github" type="ci-status" priority="high" status="delivered">CI failed on main: 3 tests failed.</notification>
+```
+
+Notification summaries tell the model that inbox records are waiting:
+
+```xml
+<notification-summary pending="10">github: 3, email: 5, slack: 2</notification-summary>
+```
+
+When Mastra emits a summary, it clears `summaryAt` and sets `summarySignalId` on each summarized record. The records stay pending and readable. When Mastra emits a full notification, it sets `deliveredSignalId` and marks the record `delivered`. If the inbox tool reads a notification first, it can inject the full notification signal and mark the record `seen`, which prevents duplicate full delivery.
+
+Configure a delivery policy 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),
+          }
+        }
+      },
+    },
+  },
+})
+```
+
+Enable scheduled dispatch at the Mastra level so deferred notifications and summary rollups are delivered through the existing 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.
+
+### Notification inbox tool
+
+Use `createNotificationInboxTool()` to give agents one tool for inbox actions instead of many CRUD tools.
+
+```typescript
+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 }),
+  },
+})
+```
+
+The tool id is `notification-inbox`. It supports these actions:
+
+- `list`: List notifications for the current thread.
+- `read`: Deliver readable full notification signals into the chat when possible, then mark records `seen`.
+- `markSeen`: Mark one record `seen`.
+- `dismiss`: Mark one record `dismissed`.
+- `archive`: Mark one record `archived`.
+- `search`: Search notification summaries in the current thread.
+
+The tool uses the current `threadId` from the tool execution context unless one is provided. Use `read` after a `<notification-summary>` signal when the agent needs the full records behind the summary. The `read` result reports how many notifications will be delivered; it doesn't use normal tool output as the main context channel for the notification contents.
+
+`sendNotificationSignal()` requires a storage domain with `notifications` support. LibSQL supports notifications. Other storage adapters need matching notification domain support before they can store notification records.
+
+Use `sendSignal({ type: 'notification' })` only for lower-level notification-shaped context that should bypass inbox storage.
 
 ## Compatibility
 
@@ -229,7 +450,7 @@ Mastra still accepts legacy signal payloads such as `type: 'user-message'` and `
 - `type: 'user-message'`: Normalizes to `type: 'user'` and `tagName: 'user'`
 - `type: 'system-reminder'`: Normalizes to `type: 'reactive'` and `tagName: 'system-reminder'`
 
-Existing stored signal rows and older clients continue to load through the compatibility layer.
+Existing stored signal rows and older clients continue to load through the compatibility layer. New clients call the message routes when the server supports them; React's thread signal path falls back to the legacy `/signals` route when it detects an older server.
 
 > **Note:** Visit [Agent signals reference](https://mastra.ai/reference/agents/agent) for the full message, signal, and subscription types.
 
@@ -264,11 +485,8 @@ const subscription = await agent.subscribeToThread({
   threadId: 'thread_456',
 })
 
-await agent.sendSignal({
-  signal: {
-    type: 'user-message',
-    contents: 'Show the shorter version.',
-  },
+await agent.sendMessage({
+  message: 'Show the shorter version.',
   resourceId: 'user_123',
   threadId: 'thread_456',
 })
@@ -307,7 +525,9 @@ Use heartbeats together with client-side reconnect logic. Heartbeats reduce idle
 - [`Agent.queueMessage()`](https://mastra.ai/reference/agents/agent)
 - [`Agent.sendSignal()`](https://mastra.ai/reference/agents/agent)
 - [`Agent.subscribeToThread()`](https://mastra.ai/reference/agents/agent)
-- [Server agent routes](https://mastra.ai/reference/server/routes)
+- [`client.getAgent().sendMessage()`](https://mastra.ai/reference/client-js/agents)
+- [`client.getAgent().queueMessage()`](https://mastra.ai/reference/client-js/agents)
 - [`client.getAgent().sendSignal()`](https://mastra.ai/reference/client-js/agents)
+- [Server agent routes](https://mastra.ai/reference/server/routes)
 - [`client.getAgent().subscribeToThread()`](https://mastra.ai/reference/client-js/agents)
 - [`client.getAgent().sendToolApproval()`](https://mastra.ai/reference/client-js/agents)

package/.docs/docs/build-with-ai/skills.md

@@ -32,6 +32,8 @@ bun x skills add mastra-ai/skills
 
 Mastra skills work with any coding agent that supports the [Skills standard](https://agentskills.io/), including Claude Code, Cursor, Codex, OpenCode, and others.
 
+They're also available on [GitHub](https://github.com/mastra-ai/skills).
+
 ## Update skill
 
 To update to the latest version of the Mastra skill, run:
@@ -58,6 +60,4 @@ yarn dlx skills update mastra
 
 ```bash
 bun x skills update mastra
-```
-
-They're also available on [GitHub](https://github.com/mastra-ai/skills).
+```

package/.docs/docs/editor/overview.md

@@ -149,16 +149,17 @@ The `editor.agent` namespace also exposes `getById`, `list`, `listResolved`, and
 
 The same operations are available over HTTP through the Mastra server. Use these when you want to manage stored agents from a separate service or from a non-TypeScript client:
 
-| Method   | Path                                   | Description                                                      |
-| -------- | -------------------------------------- | ---------------------------------------------------------------- |
-| `GET`    | `/stored/agents`                       | List all stored agents.                                          |
-| `POST`   | `/stored/agents`                       | Create a stored agent.                                           |
-| `GET`    | `/stored/agents/:storedAgentId`        | Get a stored agent by ID.                                        |
-| `PATCH`  | `/stored/agents/:storedAgentId`        | Update a stored agent.                                           |
-| `DELETE` | `/stored/agents/:storedAgentId`        | Delete a stored agent.                                           |
-| `POST`   | `/stored/agents/:storedAgentId/export` | Export a stored agent's override as a deterministic JSON config. |
-
-The export endpoint returns only the fields the agent's [`editor` config](https://mastra.ai/reference/agents/agent) allows, so the output matches the per-agent file the code source writes to disk. The Client SDK wraps these endpoints with `client.listStoredAgents()`, `client.createStoredAgent()`, `client.getStoredAgent()`, and `client.getStoredAgent(id).export()`. Version management endpoints live under `/stored/agents/:storedAgentId/versions`, see [version management](https://mastra.ai/reference/client-js/agents) for the full list.
+| Method   | Path                                       | Description                                                      |
+| -------- | ------------------------------------------ | ---------------------------------------------------------------- |
+| `GET`    | `/stored/agents`                           | List all stored agents.                                          |
+| `POST`   | `/stored/agents`                           | Create a stored agent.                                           |
+| `GET`    | `/stored/agents/:storedAgentId`            | Get a stored agent by ID.                                        |
+| `PATCH`  | `/stored/agents/:storedAgentId`            | Update a stored agent.                                           |
+| `DELETE` | `/stored/agents/:storedAgentId`            | Delete a stored agent.                                           |
+| `GET`    | `/stored/agents/:storedAgentId/dependents` | List agents that reference this agent as a sub-agent.            |
+| `POST`   | `/stored/agents/:storedAgentId/export`     | Export a stored agent's override as a deterministic JSON config. |
+
+The dependents endpoint helps warn before deleting or unsharing an agent that other agents depend on: `dependents` lists caller-readable agents by `id` and `name`, while `hiddenCount` aggregates cross-workspace references the caller cannot read (surfaced only when the target is public). The export endpoint returns only the fields the agent's [`editor` config](https://mastra.ai/reference/agents/agent) allows, so the output matches the per-agent file the code source writes to disk. The Client SDK wraps these endpoints with `client.listStoredAgents()`, `client.createStoredAgent()`, `client.getStoredAgent()`, `client.getStoredAgent(id).dependents()`, and `client.getStoredAgent(id).export()`. Version management endpoints live under `/stored/agents/:storedAgentId/versions`, see [version management](https://mastra.ai/reference/client-js/agents) for the full list.
 
 ### Automated experimentation
 

package/.docs/docs/getting-started/build-with-ai.md

@@ -40,6 +40,43 @@ In addition to documentation access, the [MCP Docs Server](https://mastra.ai/doc
 
 Learn how to use the [MCP Docs Server](https://mastra.ai/docs/build-with-ai/mcp-docs-server).
 
+## Mastra CLI
+
+The [Mastra CLI](https://mastra.ai/reference/cli/mastra) gives your coding agent a direct line to your Mastra runtime. Agents can invoke agents, run workflows, execute tools, inspect memory, run evals, and query traces and logs.
+
+**npm**:
+
+```bash
+npm install mastra@latest -g
+```
+
+**pnpm**:
+
+```bash
+pnpm add mastra@latest -g
+```
+
+**Yarn**:
+
+```bash
+yarn global add mastra@latest
+```
+
+**Bun**:
+
+```bash
+bun add mastra@latest --global
+```
+
+For example, your coding agent can run an agent, then pull traces to inspect the results:
+
+```bash
+mastra api --url http://localhost:4111 agent run weather-agent '{"messages":"What is the weather in London?"}'
+mastra api --url http://localhost:4111 trace list
+```
+
+See the [CLI commands reference](https://mastra.ai/reference/cli/mastra) for the full list of available commands.
+
 ## Embedded package docs
 
 Mastra packages ship with embedded documentation in `dist/docs`. When you install a Mastra package, your AI agent can read these files directly from `node_modules` to understand the package's APIs and patterns.

package/.docs/docs/mastra-platform/observability.md

@@ -105,25 +105,25 @@ After your project is publishing traces, logs, or scores to Mastra Platform Obse
 **npm**:
 
 ```bash
-npx mastra api trace list --pretty
+npx mastra api trace list
 ```
 
 **pnpm**:
 
 ```bash
-pnpm dlx mastra api trace list --pretty
+pnpm dlx mastra api trace list
 ```
 
 **Yarn**:
 
 ```bash
-yarn dlx mastra api trace list --pretty
+yarn dlx mastra api trace list
 ```
 
 **Bun**:
 
 ```bash
-bun x mastra api trace list --pretty
+bun x mastra api trace list
 ```
 
 For observability commands, the CLI targets the hosted observability API and can infer credentials from your project environment. See the [`mastra api` CLI reference](https://mastra.ai/reference/cli/mastra) for available observability commands, filtering, pagination, credential resolution, and direct `curl` examples.

package/.docs/docs/memory/multi-user-threads.md

@@ -135,7 +135,7 @@ const memory = new Memory({
 
 The model reads identity from the `<turn>` tag on the current message and from prior tagged messages brought back through `lastMessages`.
 
-### With observational memory (recommended)
+### With Observational Memory (recommended)
 
 [Observational Memory](https://mastra.ai/docs/memory/observational-memory) (OM) extracts per-user facts into a background log without burning the agent's tool budget. The default Observer model reads `<turn>` tags natively and produces named attribution like `Alice stated her favorite color is teal.` and `Bob asked for QA sign-off before publish.`
 

package/.docs/docs/memory/working-memory.md

@@ -393,6 +393,33 @@ const response = await agent.generate('What do you know about me?', {
 })
 ```
 
+## Opt in to state signals (experimental)
+
+By default, working memory reaches the model as part of the system message. You can opt into delivering it as a [state signal](https://mastra.ai/docs/agents/signals) instead by setting `useStateSignals: true`:
+
+```typescript
+const memory = new Memory({
+  storage: new LibSQLStore({ url: 'file:./mastra.db' }),
+  options: {
+    workingMemory: {
+      enabled: true,
+      template: '# User\n- name:\n- location:',
+      useStateSignals: true, // experimental: deliver as state signal
+    },
+  },
+})
+```
+
+What changes:
+
+- **Storage is identical.** The same resource/thread `workingMemory` field is read and written.
+- **The tool is the same shape, exposed under a new name.** Writes still flow through the same underlying tool; on this path it is registered as `setWorkingMemory` (instead of `updateWorkingMemory`). The rename keeps legacy strip filters from removing tool-call parts so they persist as a normal audit trail and the next model step picks the new value up automatically.
+- **Delivery only.** Instead of folding into the system prompt, `Memory` auto-attaches a `WorkingMemoryStateProcessor` that emits the current working memory as a `state` signal with `stateId: 'working-memory'`.
+
+You inherit the standard state-signal benefits: thread-scoped tracking metadata, `cacheKey` dedup so identical snapshots are only emitted once, and `contextWindow.hasSnapshot` re-injection when an older snapshot rolls out of the window.
+
+The default (`useStateSignals: false`) keeps the existing system-message behavior unchanged. `useStateSignals` is not supported with template working memory `version: 'vnext'`.
+
 ## Examples
 
 - [Working memory with template](https://github.com/mastra-ai/mastra/tree/main/examples/memory-with-template)

package/.docs/docs/observability/metrics/querying.md

@@ -78,7 +78,7 @@ The `@mastra/client-js` SDK wraps the same routes as `mastraClient.getMetricAggr
 ```bash
 mastra api metric aggregate \
   '{"name":["mastra_agent_duration_ms"],"aggregation":"avg"}' \
-  --url http://localhost:4111 --pretty
+  --url http://localhost:4111
 ```
 
 By default the CLI targets hosted Mastra observability (`https://observability.mastra.ai`). Pass `--url http://localhost:4111` to query a local `mastra dev` server. See [`mastra api metric aggregate`](https://mastra.ai/reference/cli/mastra) and the surrounding entries for the full command list.

package/.docs/docs/server/pubsub.md

@@ -0,0 +1,124 @@
+# PubSub
+
+Mastra uses a publish/subscribe (pub/sub) system as its internal event bus. Components publish events to named topics, and other components subscribe to those topics to react. The backend you configure decides how far those events travel: within one process, across processes on one host, or across separate instances.
+
+You set the backend once on the `Mastra` instance, and the rest of the system uses it without changes. By default, Mastra uses an in-process backend that needs no setup.
+
+## How Mastra uses PubSub
+
+Several built-in systems publish and subscribe to events through the same pub/sub bus:
+
+- **Workflow execution**: The scheduler publishes a `workflow.start` event, and a long-lived worker consumes it to run the workflow. Step and lifecycle events flow over pub/sub during execution.
+- **Scheduled workflows**: The scheduler dispatches due runs by publishing to the workflow topic. See [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows).
+- **Background tasks**: A task manager dispatches work to a worker group and fans task lifecycle updates out to subscribers, which is how background task streams stay live. See [Background task streaming](https://mastra.ai/docs/streaming/background-task-streaming).
+- **Agent signals**: Sending a signal to an active agent run publishes an event on a thread topic, so a run executing in another process receives the signal.
+- **Resumable streams**: Stream chunks are published per run, so a client that reconnects can replay what it missed.
+
+Because these systems run on one bus, the backend you choose applies to all of them at once.
+
+## Delivery modes
+
+Backends deliver events in one of two modes, defined by the [`PubSub`](https://mastra.ai/reference/pubsub/base) contract:
+
+- **Pull**: Consumers read from the backend on their own, which Mastra does with a long-lived worker loop. Distributed backends such as [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams) use this mode.
+- **Push**: Events arrive without the consumer asking, either in process or over HTTP. The default [`EventEmitterPubSub`](https://mastra.ai/reference/pubsub/event-emitter) delivers this way in process.
+
+Subscribers can also opt into work distribution. A group of subscribers that share a consumer group split the events between them, so each event is handled once. Subscribers without a group each receive every event, which fans the stream out to all of them.
+
+## Default backend
+
+When you do not set the `pubsub` option, Mastra uses [`EventEmitterPubSub`](https://mastra.ai/reference/pubsub/event-emitter). It delivers events in process using a Node.js [`EventEmitter`](https://nodejs.org/api/events.html#class-eventemitter), so it works without any external service.
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+// No pubsub option: Mastra uses EventEmitterPubSub
+export const mastra = new Mastra({})
+```
+
+Because it runs in process, events are not persisted and do not reach other processes. The default suits a single instance, which covers most applications.
+
+## Choosing a backend
+
+Set the `pubsub` option on the `Mastra` instance to choose a backend. Each backend implements the same [`PubSub`](https://mastra.ai/reference/pubsub/base) contract, so the rest of your application does not change.
+
+The deciding question is where the subscriber runs.
+
+| Backend                                                                       | Scope                        | Mode          | Package                       |
+| ----------------------------------------------------------------------------- | ---------------------------- | ------------- | ----------------------------- |
+| [`EventEmitterPubSub`](https://mastra.ai/reference/pubsub/event-emitter)      | Single process               | Pull and push | `@mastra/core`                |
+| [`UnixSocketPubSub`](https://mastra.ai/reference/pubsub/unix-socket-pubsub)   | Multiple processes, one host | Push          | `@mastra/core`                |
+| [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams)      | Distributed, multiple hosts  | Pull          | `@mastra/redis-streams`       |
+| [`GoogleCloudPubSub`](https://mastra.ai/reference/pubsub/google-cloud-pubsub) | Distributed, multiple hosts  | Pull          | `@mastra/google-cloud-pubsub` |
+
+### Multiple processes on one host
+
+Use [`UnixSocketPubSub`](https://mastra.ai/reference/pubsub/unix-socket-pubsub) when several processes on the same machine need to share a stream. It delivers events over a Unix domain socket and elects one process as a broker. If the broker exits, the remaining processes elect a new one.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { UnixSocketPubSub } from '@mastra/core/events'
+
+export const mastra = new Mastra({
+  pubsub: new UnixSocketPubSub('/tmp/mastra/events.sock'),
+})
+```
+
+### Distributed deployments
+
+Use a distributed backend when you run more than one instance or host, so every instance receives the same events. This matters whenever a request handled by one instance must reach work running on another. For example, sending a signal to an agent run requires the signal event to cross the process boundary to the instance that owns the run. With the in-process default, that instance never receives the event.
+
+Both backends below deliver across processes and hosts and persist events for redelivery.
+
+The following example uses [Redis Streams](https://redis.io/docs/latest/develop/data-types/streams/):
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { RedisStreamsPubSub } from '@mastra/redis-streams'
+
+export const mastra = new Mastra({
+  pubsub: new RedisStreamsPubSub({
+    url: 'redis://localhost:6379',
+  }),
+})
+```
+
+The following example uses [Google Cloud Pub/Sub](https://cloud.google.com/pubsub/docs):
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { GoogleCloudPubSub } from '@mastra/google-cloud-pubsub'
+
+export const mastra = new Mastra({
+  pubsub: new GoogleCloudPubSub({
+    projectId: 'my-project',
+  }),
+})
+```
+
+## Resumable streams
+
+Resumable streams let a client reconnect and replay events it missed, which requires the backend to keep recent history. Distributed backends such as [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams) persist events, so they support replay on their own.
+
+In-process delivery does not keep history. To add replay on top of [`EventEmitterPubSub`](https://mastra.ai/reference/pubsub/event-emitter), wrap it in [`CachingPubSub`](https://mastra.ai/reference/pubsub/caching-pubsub), which records published events per topic so a late or reconnecting subscriber can catch up before continuing with live events.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { CachingPubSub, EventEmitterPubSub } from '@mastra/core/events'
+import { InMemoryServerCache } from '@mastra/core/cache'
+
+const cache = new InMemoryServerCache()
+
+export const mastra = new Mastra({
+  pubsub: new CachingPubSub(new EventEmitterPubSub(), cache),
+})
+```
+
+> **Note:** Visit the [PubSub reference](https://mastra.ai/reference/pubsub/base) for the full delivery contract and the configuration options for each backend.
+
+## Related
+
+- [PubSub reference](https://mastra.ai/reference/pubsub/base)
+- [Mastra class](https://mastra.ai/reference/core/mastra-class)
+- [Background task streaming](https://mastra.ai/docs/streaming/background-task-streaming)
+- [Scheduled workflows](https://mastra.ai/docs/workflows/scheduled-workflows)

package/.docs/docs/studio/auth.md

@@ -46,6 +46,26 @@ Setting [`server.auth`](https://mastra.ai/reference/configuration) does two thin
 
 Studio detects available capabilities by calling the `GET /api/auth/capabilities` endpoint. The response tells Studio which login methods to render and, if the user is already authenticated, includes their user info and permissions.
 
+## Pass a token through the URL
+
+When another application embeds or links to Studio, it can hand over an authorization token through the `auth_header` URL parameter. This is useful when an external host already holds a token and wants to open an authenticated Studio session without showing the login screen.
+
+The `auth_header` value always populates the `Authorization` request header. The parameter sets that one header only, so include any scheme prefix the server expects in the value, such as `Bearer`.
+
+Open Studio with the token in the query string:
+
+```text
+https://your-studio-host/?auth_header=Bearer%20your-token
+```
+
+Studio handles the token as follows:
+
+- It reads `auth_header` once on load and sends the value as the `Authorization` header on every API request in that session.
+- It removes `auth_header` from the address bar while preserving other query parameters and the hash.
+- It keeps the token in memory only and never writes it to local storage, so the token stays transient and does not persist across page reloads.
+
+The token rides in a URL parameter, so the host application is responsible for how that URL is generated and transmitted. URL parameters can be exposed through browser history, referrer headers, and server access logs.
+
 ## Role-based access control
 
 RBAC lets you control what each user can see and do inside Studio. It's separate from authentication: `server.auth` handles who the user is, while `server.rbac` handles what they can do.