@mastra/mcp-docs-server 1.2.15-alpha.13 → 1.2.15-alpha.19

package/.docs/docs/agents/agent-approval.md

@@ -90,6 +90,20 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
+#### Explaining a decline
+
+`declineToolCall()`, `declineToolCallGenerate()`, and `declineNetworkToolCall()` accept an optional `reason`. The reason is returned to the model in place of the tool result, so the model can adjust instead of retrying blindly. It's also stored on the tool call's `approval` metadata, so it's still there when the conversation is recalled.
+
+```typescript
+const declined = await agent.declineToolCall({
+  runId: stream.runId,
+  toolCallId,
+  reason: 'Reading other users PII is not allowed, ask the user for their own email instead',
+})
+```
+
+Without a `reason`, the model receives the default message `Tool call was not approved by the user`.
+
 #### Conditional approval with a function
 
 Instead of a boolean, `requireToolApproval` accepts a function that decides per tool call. It receives the `toolName`, the `args` the model passed, the `requestContext`, and the `workspace`. Return `true` to require approval for that call, or `false` to allow it. This lets you gate approval at runtime, for example, only for tools whose name matches a pattern:

package/.docs/docs/agents/code-mode.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.38.0`
 
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 Code mode lets an agent run multi-tool computations in an isolated sandbox and return the result as a single, more accurate response.
 
@@ -164,9 +164,24 @@ const { tool, instructions } = createCodeMode(
 
 `isolated-vm` is a native addon, and on Node.js 20 and later the host process must be started with the `--no-node-snapshot` flag. See the [IsolatedVmCodeModeTransport reference](https://mastra.ai/reference/tools/isolated-vm-transport) for setup details.
 
+When the host can't install native addons or set Node.js flags, which is common on serverless platforms, use [`QuickJsCodeModeTransport`](https://mastra.ai/reference/tools/quickjs-transport) from `@mastra/quickjs` instead. It gives the same in-process boundary using a QuickJS runtime compiled to WebAssembly, at the cost of slower execution:
+
+```typescript
+import { createCodeMode } from '@mastra/core/tools'
+import { QuickJsCodeModeTransport } from '@mastra/quickjs'
+
+const { tool, instructions } = createCodeMode(
+  { tools }, // no sandbox needed
+  new QuickJsCodeModeTransport({ memoryLimitMb: 128 }),
+)
+```
+
+See [Choosing a transport](https://mastra.ai/reference/tools/quickjs-transport) for a side-by-side comparison.
+
 ## Related
 
 - [createCodeMode() reference](https://mastra.ai/reference/tools/create-code-mode)
 - [IsolatedVmCodeModeTransport reference](https://mastra.ai/reference/tools/isolated-vm-transport)
+- [QuickJsCodeModeTransport reference](https://mastra.ai/reference/tools/quickjs-transport)
 - [Tools](https://mastra.ai/docs/agents/using-tools)
 - [Workspace overview](https://mastra.ai/docs/workspace/overview)

package/.docs/docs/agents/processors.md

@@ -432,7 +432,7 @@ See the [`ProviderHistoryCompat` reference](https://mastra.ai/reference/processo
 
 ## Response caching
 
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 Response caching skips the LLM call and replays a previously cached response when an agent receives an identical request. Use it to reduce latency and avoid paying for repeated calls.
 
@@ -544,7 +544,7 @@ This means the cache key is derived from the resolved `LanguageModelV2Prompt` Ma
 
 When you don't supply `key`, the processor derives one deterministically from the inputs that change the LLM's response at this step: `agentId`, `stepNumber` (so each step in a tool loop has its own cache entry), `scope`, model identity (`provider`, `modelId`, spec version), and the resolved `prompt` (post-memory + post-processors). Any change to these inputs automatically invalidates the cache.
 
-Multimodal prompts are included too. Image and file parts reach the key by value: a URL contributes its full href, and inline binary data (`Uint8Array`, `ArrayBuffer`) contributes a digest of its bytes. Two requests that differ only in which image they reference therefore get different cache entries.
+Multimodal prompts are included too. Image and file parts reach the key by value: the key includes a URL's full href, and a digest of the bytes for inline binary data (`Uint8Array`, `ArrayBuffer`). Requests that differ only in which image they reference therefore get different cache entries.
 
 #### Customize the cache key
 
@@ -664,7 +664,7 @@ export class SteeringReminderProcessor implements Processor {
 }
 ```
 
-A transient signal still appears in the prompt for the current call, so the model sees it near the latest turn. It's not retained, so re-sending it each turn keeps a single fresh copy in context instead of an accumulating history, and it never appears in stored thread history. Because nothing is written, it also keeps a stable prompt cache prefix across turns.
+A transient signal is still in the prompt for the current call, so the model sees it near the latest turn. It's not retained, so re-sending it each turn keeps a single fresh copy in context instead of an accumulating history, and stored thread history never includes it. Because nothing is written, it also keeps a stable prompt cache prefix across turns.
 
 ### Emit custom stream events
 

package/.docs/docs/browser/recording.md

@@ -1,12 +1,12 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Browser recording (beta)
+# Browser recording
 
 **Added in:** `@mastra/core@1.43.0`
 
 Browser recording adds two opt-in tools that let an agent save a browser session as a Motion-JPEG AVI video. The agent can also add short captions while it works.
 
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 ## When to use browser recording
 

package/.docs/docs/capabilities/subagents.md

@@ -113,7 +113,7 @@ The `context` object includes:
 
 ### Request context at the delegation boundary
 
-Each delegation receives a request context whose entries are shallowly copied from the parent run, excluding run-scoped identity keys. Setting or deleting entries during the subagent run does not affect the parent's context. Set entries on `context.requestContext` in `onDelegationStart` to pass values to the delegated run:
+Each delegation receives a request context whose entries are shallowly copied from the parent run, excluding run-scoped identity keys. Setting or deleting entries during the subagent run doesn't affect the parent's context. Set entries on `context.requestContext` in `onDelegationStart` to pass values to the delegated run:
 
 ```typescript
 const stream = await parentAgent.stream('Research AI trends', {
@@ -134,6 +134,9 @@ Called after a delegation finishes. Use it to inspect results or provide feedbac
 
 - `context.bail()`: Stop the parent agent's loop immediately
 - Return `{ feedback: '...' }`: Add feedback that gets saved to the parent agent's memory and is visible to subsequent iterations
+- Return `{ resultText: '...' }`: Replace the tool result text the parent model sees for this delegation, within the current run
+
+Use `resultText` when the subagent's own result would mislead the parent immediately. For example, a subagent that stops on a tool-calls step returns empty text, which the parent model reads as a successful but empty delegation. Unlike `feedback`, which only reaches the model on the next turn, `resultText` changes what the parent reasons on right away.
 
 ```typescript
 const stream = await parentAgent.stream('Research AI trends', {

package/.docs/docs/datasets/running-experiments.md

@@ -206,6 +206,55 @@ The `experiment.run.finished` event is awaited before Mastra persists the final
 
 The exported event types are `ExperimentEvent`, `ExperimentRunStartedEvent`, `ExperimentItemCompletedEvent`, and `ExperimentRunFinishedEvent`. Use the discriminated `type` field to narrow an event before reading event-specific properties.
 
+## Lifecycle hooks
+
+Use lifecycle hooks to prepare state before a target runs and clean it up afterwards. This is useful when an item can't be evaluated against an empty environment. A run might need a fixture file copied into the agent's workspace, or a sandbox provisioned before the agent can touch it.
+
+Hooks run at two levels. `beforeAll` and `afterAll` run once per experiment, and `beforeEach` and `afterEach` run once per item:
+
+```typescript
+const summary = await dataset.startExperiment({
+  targetType: 'agent',
+  targetId: 'document-agent',
+  scorers: ['accuracy'],
+  beforeAll: async ({ experimentId }) => {
+    await createWorkspace(experimentId)
+  },
+  beforeEach: async ({ item }) => {
+    await copyFixture(item.metadata?.fixture)
+  },
+  afterEach: async ({ item, result }) => {
+    await clearWorkspaceFiles(item.id)
+  },
+  afterAll: async ({ summary }) => {
+    await deleteWorkspace(summary.experimentId)
+  },
+})
+```
+
+Every hook can be async. Each one receives the `experimentId`, the `mastra` instance, and the run-level `signal`, so long-running setup can be cancelled along with the experiment. The per-item hooks also receive `item`. The teardown hooks receive the result they follow: `afterEach` receives the item's `result` including scores, and `afterAll` receives the `summary` that's about to be returned.
+
+The item passed to hooks exposes `id`, `input`, `groundTruth`, and `metadata`. Fields that control execution, such as tool mocks and scorer selection, aren't exposed, so a hook can't change how the item runs.
+
+### Hook failures
+
+Each hook has a different consequence when it throws, based on how much of the run depends on it:
+
+| Hook         | On failure                                                                       |
+| ------------ | -------------------------------------------------------------------------------- |
+| `beforeAll`  | Fails the experiment. No items run.                                              |
+| `beforeEach` | Fails that item with `EXPERIMENT_ITEM_BEFORE_EACH_FAILED`. Other items continue. |
+| `afterEach`  | Logged. The item's recorded outcome doesn't change.                              |
+| `afterAll`   | Logged. The returned summary doesn't change.                                     |
+
+When `beforeAll` fails, the experiment is marked failed and the `experiment.run.finished` event is still emitted before the error propagates.
+
+When `beforeEach` fails, the target and its scorers are skipped for that item, since the item's preconditions were never met. `afterEach` is also skipped for that item, on the basis that setup which didn't finish owns its own cleanup.
+
+Teardown failures are logged rather than propagated. By the time `afterEach` runs, the target has already produced a real result, and discarding it because cleanup was untidy would lose the data the experiment was run to collect.
+
+`afterAll` runs on every exit path, including when the experiment fails, when `beforeAll` fails, and when an [event observer](#observe-experiment-events) fails, so teardown isn't skipped when something goes wrong. It runs at most once per experiment.
+
 ## Tool mocks
 
 When an experiment runs an agent that calls side-effecting tools, attach static tool mocks to individual dataset items to make the run deterministic. During the experiment, a mocked tool returns its declared output instead of executing. Tools without a mock on the item run live by default.

package/.docs/docs/deployment/workers.md

@@ -2,7 +2,7 @@
 
 # Workers
 
-> **Beta:** This feature is in beta. The API is stable enough for production use, but some details may change. See [known limitations](#known-limitations) for current gaps.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable. See [known limitations](#known-limitations) for current gaps.
 
 Workers handle background processing outside the request-response cycle. Workflow step execution, cron-based scheduling, and long-running tool calls all run in workers, keeping the API responsive.
 

package/.docs/docs/getting-started/develop.md

@@ -138,7 +138,7 @@ See the [project structure reference](https://mastra.ai/reference/project-struct
 
 ## File-based agents
 
-> **Beta:** File-based agents are in beta and may change before they're stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 >
 > File-based discovery only runs through `mastra dev` or `mastra build`. If your app imports `mastra` directly, including through a web framework or server adapter, file-based agents aren't discovered. Register those agents in code or run Mastra as a separate server.
 

package/.docs/docs/harness/agent-controller.md

@@ -2,7 +2,7 @@
 
 # AgentController
 
-> **Beta:** The [`AgentController`](https://mastra.ai/reference/agent-controller/agent-controller-class) feature is in beta stage and subject to breaking changes in minor versions until it graduates from its beta status.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 `AgentController` is a shared runtime host for interactive agent applications. It coordinates modes, models, storage, workspaces, tool approvals, subagents, and channels. Each user or active task works through an isolated [`Session`](https://mastra.ai/reference/agent-controller/session).
 
@@ -343,7 +343,48 @@ Point each platform webhook at the controller-specific route:
 
 Each external chat thread maps to one controller Session and Mastra thread. By default, new sessions use a resource ID derived from the adapter's chat-thread ID, prefixed with `channel:`. Use `resolveResourceId` to map direct messages to an existing application user or choose another memory owner. The callback only affects new threads; an existing thread keeps its stored resource ID.
 
-Channel sessions are created by the controller rather than by your code, so `onSessionStart` is where you configure them. It runs once per session, after the session is bound to its mapped thread and before the first message is handled. Use it to apply a model, memory settings, or session state that a channel session would otherwise miss. Later messages in the same thread reuse the session and don't call it again. Errors are logged and swallowed so a session that can't be configured still answers the message.
+Channel sessions are created by the controller rather than by your code, so `onSessionStart` is where you configure them. It runs once per session, after the session is bound to its mapped thread and before the first message is handled. A channel session starts with controller defaults, so this is where you set its model and memory settings. Later messages in the same thread reuse the session and don't call it again. Errors are logged and swallowed so a session that can't be configured still answers the message.
+
+### Authorize and route channel sessions
+
+`onSessionStart` runs after the session exists and swallows errors, so it can't refuse a request. Use `resolveSession` when your host decides whether a session may exist. It replaces the built-in session creation and runs before any session exists. Throwing refuses the request before the controller creates a session or calls the model. Mastra logs the refusal and leaves the chat thread silent, so your authorization message never reaches the channel.
+
+```typescript
+channels: {
+  adapters: { slack: createSlackAdapter() },
+  resolveSession: async ({ controller, thread, requestContext }) => {
+    const install = await installs.authorize(requestContext.get('teamId'))
+
+    return controller.createSession({
+      resourceId: thread.resourceId,
+      scope: install.id,
+      ownerId: controller.id,
+      requestContext,
+    })
+  },
+}
+```
+
+Create the session under `thread.resourceId`. A session can only bind threads it owns, so use `resolveResourceId` if you want a different owner for the mapped thread. Sessions are get-or-create per `resourceId` and `scope`, so pass `scope` when one thread needs separate sessions per install or principal.
+
+Failures that aren't refusals (a storage outage, a bug in your resolver's dependencies) still post an error to the thread, so a broken bot doesn't look like a silent one. If you need to tell them apart in your own code, a refusal is a `ChannelSessionRejectedError` with the original error as its `cause`.
+
+`resolveSession` also runs when a user answers an approval card, with that action's request context, so a shared install revalidates the person approving rather than trusting the person who sent the original message.
+
+### Handle stale approvals
+
+An approval gate lives in memory, so every approval answered after a restart is stale. Mastra never runs the tool for a stale action. Use `onStaleToolApproval` to settle the attempt the user answered, instead of dropping it:
+
+```typescript
+channels: {
+  adapters: { slack: createSlackAdapter() },
+  onStaleToolApproval: async ({ decision, toolCallId, runId, memory }) => {
+    await runs.markInterrupted({ runId, toolCallId, decision, threadId: memory.thread })
+  },
+}
+```
+
+`runId` is the run the approval card was rendered for, which is the attempt the user answered and the one you settle against after a restart. The session's own run is passed separately as `currentRunId`, and is usually `null` or a different run by then.
 
 Controller channel sessions and auto-approval state are held in memory, so use a long-lived server. Pending approvals and live Session state don't survive process restarts. Adapters that can't render approval controls automatically run tools without an approval prompt so the run doesn't remain suspended.
 

package/.docs/docs/harness/overview.md

@@ -4,12 +4,10 @@
 
 A harness lets an agent pursue long-running, complex goals while keeping its work durable, visible, and steerable. It preserves progress across retries and interruptions, while giving people and other systems a way to inspect progress, add context, approve actions, redirect the agent, or stop it.
 
-In Mastra, harness refers to a set of capabilities for managing an agent beyond a single uninterrupted run. You can adopt these capabilities individually or combine them as needed.
-
-[`AgentController`](https://mastra.ai/docs/harness/agent-controller) is a harness designed for interactive agent applications. It extends the base [`Agent`](https://mastra.ai/docs/agents/overview) loop with isolated sessions for each user or task, persistent threads and state, switchable modes and models, tool permissions and approvals, subagent orchestration, and streams for events and display state.
-
 Agent harnesses are useful wherever work continues over time. Common examples include coding agents that carry changes through CI and review, software factories that coordinate many tasks in parallel, SRE agents that adapt as incidents evolve, and go-to-market agents that respond as accounts, signals, and conversations change.
 
+In Mastra, harness refers to a set of capabilities for managing an agent beyond a single uninterrupted run. You can adopt these capabilities individually or combine them as needed.
+
 ## When to use a harness
 
 Choose a starting point based on what the agent needs. You may use one capability or several.

package/.docs/docs/long-running-agents/durable-agents.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.45.0`
 
-> **Warning:** Durable agents are currently in **beta**. APIs may change in future releases.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 A durable agent wraps a regular [`Agent`](https://mastra.ai/docs/agents/overview) so the agentic loop runs inside a workflow. Events flow through [PubSub](https://mastra.ai/docs/server/pubsub), which means a client can disconnect and reconnect without missing chunks. The run state is persisted, so it survives process restarts.
 

package/.docs/docs/long-running-agents/goals.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.42.0`
 
-> **Beta:** The Goals feature is in beta stage and subject to breaking changes in minor versions until it graduates from its beta status.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 A goal is a durable, thread-scoped objective: a standing instruction the agent keeps working toward across loop iterations until a judge model decides it's satisfied or a run budget is exhausted.
 

package/.docs/docs/long-running-agents/schedules.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.50.0`
 
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 A schedule runs an agent on a cron cadence. On each fire, Mastra sends a prompt to the agent, either as a [signal](https://mastra.ai/docs/long-running-agents/signals) into a thread or as a threadless [`agent.generate()`](https://mastra.ai/reference/agents/generate) run. Use schedules for recurring agent work such as daily summaries, periodic checks, or scheduled nudges into a conversation.
 

package/.docs/docs/long-running-agents/signal-providers.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.39.0`
 
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 A signal provider monitors an external source, such as GitHub, Slack, continuous integration (CI), or your own API, and pushes [notification signals](https://mastra.ai/docs/long-running-agents/signals) into subscribed agent threads.
 

package/.docs/docs/long-running-agents/signals.md

@@ -4,7 +4,7 @@
 
 **Added in:** `@mastra/core@1.39.0`
 
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 Signals are a way to interact with an agent through a thread. Instead of starting every interaction with `agent.stream()`, subscribe to a thread and send messages or signals. Mastra either wakes the agent when the thread is idle or drops input into the running agent loop, or alternatively queues input for the next turn.
 

package/.docs/docs/memory/message-history.md

@@ -6,7 +6,7 @@ Message history is the most basic and important form of memory. It gives the LLM
 
 You can also retrieve message history to display past conversations in your UI.
 
-> **Info:** Each message belongs to a thread (the conversation) and a resource (the user or entity it's associated with). See [Threads and resources](#threads-and-resources) for more detail.
+> **Note:** Each message belongs to a thread (the conversation) and a resource (the user or entity it's associated with). See [Threads and resources](#threads-and-resources) for more detail.
 
 > **Warning:** When you use memory with a client application, send **only the new message** from the client instead of the full conversation history.
 >
@@ -113,7 +113,7 @@ await agent.stream('Hello', {
 })
 ```
 
-> **Info:** Threads and messages are created automatically when you call `agent.generate()` or `agent.stream()`, but you can also create them manually with [`createThread()`](https://mastra.ai/reference/memory/createThread) and [`saveMessages()`](https://mastra.ai/reference/memory/memory-class).
+> **Note:** Threads and messages are created automatically when you call `agent.generate()` or `agent.stream()`, but you can also create them manually with [`createThread()`](https://mastra.ai/reference/memory/createThread) and [`saveMessages()`](https://mastra.ai/reference/memory/memory-class).
 
 You can use this history in two ways:
 

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

@@ -186,7 +186,7 @@ When you deploy with Mastra Studio, set **Deployment → Service Name** to a sta
 
 ## Performance
 
-> **Info:** MastraPlatformExporter uses batching to optimize network usage. Events are buffered and sent in batches, reducing overhead while maintaining near real-time visibility.
+> **Note:** MastraPlatformExporter uses batching to optimize network usage. Events are buffered and sent in batches, reducing overhead while maintaining near real-time visibility.
 
 ### Batching behavior
 

package/.docs/docs/observability/integrations/exporters/otel.md

@@ -230,7 +230,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Info:** Get your Dash0 endpoint from your dashboard. It should be in the format `ingress.{region}.aws.dash0.com:4317`.
+> **Note:** Get your Dash0 endpoint from your dashboard. It should be in the format `ingress.{region}.aws.dash0.com:4317`.
 
 ### `SigNoz`
 
@@ -400,7 +400,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Info:** The Datadog Agent must be configured with OTLP ingestion enabled. Add the following to your `datadog.yaml`:
+> **Note:** The Datadog Agent must be configured with OTLP ingestion enabled. Add the following to your `datadog.yaml`:
 >
 > ```yaml
 > otlp_config:

package/.docs/docs/server/auth/auth0.md

@@ -200,7 +200,7 @@ export const createMastraClient = (accessToken: string) => {
 }
 ```
 
-> **Info:** The access token must be prefixed with `Bearer` in the Authorization header.
+> **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
 >
 > Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
 

package/.docs/docs/server/auth/clerk.md

@@ -61,7 +61,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Info:** The default `authorizeUser` method allows all authenticated users. To customize user authorization, provide a custom `authorizeUser` function when constructing the provider.
+> **Note:** The default `authorizeUser` method allows all authenticated users. To customize user authorization, provide a custom `authorizeUser` function when constructing the provider.
 >
 > Visit [MastraAuthClerk](https://mastra.ai/reference/auth/clerk) for all available configuration options.
 
@@ -105,7 +105,7 @@ export const mastraClient = new MastraClient({
 })
 ```
 
-> **Info:** The access token must be prefixed with `Bearer` in the Authorization header.
+> **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
 >
 > Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
 

package/.docs/docs/server/auth/firebase.md

@@ -200,7 +200,7 @@ export const createMastraClient = (idToken: string) => {
 }
 ```
 
-> **Info:** The ID token must be prefixed with `Bearer` in the Authorization header.
+> **Note:** The ID token must be prefixed with `Bearer` in the Authorization header.
 >
 > Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
 

package/.docs/docs/server/auth/okta.md

@@ -179,16 +179,35 @@ export const mastraClient = new MastraClient({
 
 ### Bearer token
 
-You can also pass an Okta access token as a Bearer token. The token is verified against Okta's JWKS endpoint:
+You can also pass an Okta token as a Bearer token. The token is verified against Okta's JWKS endpoint, and its `aud` claim must match the configured audience. The audience defaults to your client ID, and you can override it with the `audience` option or `OKTA_AUDIENCE`.
+
+Okta puts the client ID in the `aud` claim of **ID tokens**, so ID tokens work with the default. **Access tokens** carry the audience of the authorization server that issued them, so set the audience to match:
+
+- **Org authorization server** (the default, issuer `https://{domain}`): set the audience to `https://{domain}`.
+- **Custom authorization server** (issuer `https://{domain}/oauth2/{name}`): set the audience to the server's audience value from the Okta Admin Console, for example `api://default`.
+
+```env
+OKTA_AUDIENCE=https://dev-123456.okta.com
+```
+
+Pass an array to accept more than one audience, for example ID tokens from browsers and access tokens from service callers against the same provider:
+
+```typescript
+new MastraAuthOkta({
+  audience: ['your-client-id', 'https://dev-123456.okta.com'],
+})
+```
+
+> **Note:** `audience` applies only to Bearer tokens. The ID token exchanged during the SSO login flow is always verified against your client ID.
 
 ```typescript
 import { MastraClient } from '@mastra/client-js'
 
-export const createMastraClient = (accessToken: string) => {
+export const createMastraClient = (token: string) => {
   return new MastraClient({
     baseUrl: 'http://localhost:4111',
     headers: {
-      Authorization: `Bearer ${accessToken}`,
+      Authorization: `Bearer ${token}`,
     },
   })
 }
@@ -213,7 +232,7 @@ console.log(response)
 ```bash
 curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
   -H "Content-Type: application/json" \
-  -H "Authorization: Bearer <your-okta-access-token>" \
+  -H "Authorization: Bearer <your-okta-token>" \
   -d '{
     "messages": "Weather in London"
   }'
@@ -222,6 +241,7 @@ curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
 ## Troubleshooting
 
 - **401 on every request**: Verify your Okta domain, client ID, and client secret are correct. Check that the redirect URI in your Okta application matches `OKTA_REDIRECT_URI`.
+- **401 with `unexpected "aud" claim value` in the server logs**: The Bearer token's audience doesn't match the configured audience. This usually means you sent an access token while the audience is still the default client ID. Set `OKTA_AUDIENCE` to the audience of the authorization server that issued the token. See [Bearer token](#bearer-token).
 - **Cookies not sent cross-origin**: Set `credentials: "include"` in `MastraClient` and configure `server.cors` with your frontend origin and `credentials: true`.
 - **Session lost on restart**: Set `OKTA_COOKIE_PASSWORD` to a stable value (at least 32 characters). Without it, an auto-generated key is used that changes on each restart.
 - **RBAC returns empty permissions**: Verify `OKTA_API_TOKEN` is set and the token has permission to list user groups. Check that group names in `roleMapping` match your Okta group names exactly.

package/.docs/docs/server/auth/supabase.md

@@ -59,7 +59,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Info:** The default `authorizeUser` method checks the `isAdmin` column in the `users` table in the `public` schema. To customize user authorization, provide a custom `authorizeUser` function when constructing the provider.
+> **Note:** The default `authorizeUser` method checks the `isAdmin` column in the `users` table in the `public` schema. To customize user authorization, provide a custom `authorizeUser` function when constructing the provider.
 >
 > Visit [MastraAuthSupabase](https://mastra.ai/reference/auth/supabase) for all available configuration options.
 
@@ -101,7 +101,7 @@ export const mastraClient = new MastraClient({
 })
 ```
 
-> **Info:** The access token must be prefixed with `Bearer` in the Authorization header.
+> **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
 >
 > Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
 

package/.docs/docs/server/auth/workers.md

@@ -2,6 +2,8 @@
 
 # Workers
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 When workers run in separate processes from the API, they communicate over HTTP. The orchestration worker calls the API's step execution endpoint to run workflow steps on the API server. Push-mode PubSub brokers (like Google Cloud Pub/Sub in push mode) can also deliver events directly to the API's event endpoint. This is a distinct integration path from pull-mode workers, which pull events from the broker themselves. Both HTTP endpoints require authentication when an auth provider is configured.
 
 ## How it works

package/.docs/docs/server/auth/workos.md

@@ -221,7 +221,7 @@ export const createMastraClient = (accessToken: string) => {
 }
 ```
 
-> **Info:** The access token must be prefixed with `Bearer` in the Authorization header.
+> **Note:** The access token must be prefixed with `Bearer` in the Authorization header.
 >
 > Visit [Mastra Client SDK](https://mastra.ai/docs/server/mastra-client) for more configuration options.
 

package/.docs/docs/server/custom-adapters.md

@@ -6,7 +6,7 @@ Create a custom adapter when the prebuilt server adapters (Hono, Express, Fastif
 
 A custom adapter translates between Mastra's route definitions and your framework's routing system. You'll implement methods that register middleware, handle requests, and send responses using your framework's APIs.
 
-> **Info:** Use any of these prebuilt server adapters:
+> **Note:** Use any of these prebuilt server adapters:
 >
 > - [@mastra/hono](https://mastra.ai/reference/server/hono-adapter)
 > - [@mastra/express](https://mastra.ai/reference/server/express-adapter)

package/.docs/docs/server/mastra-client.md

@@ -149,7 +149,7 @@ const testAgent = async () => {
 }
 ```
 
-> **Info:** You can also call `.generate()` with an array of message objects that include `role` and `content`. Visit the [.generate() reference](https://mastra.ai/reference/client-js/agents) for more information.
+> **Note:** You can also call `.generate()` with an array of message objects that include `role` and `content`. Visit the [.generate() reference](https://mastra.ai/reference/client-js/agents) for more information.
 
 ## Streaming responses
 
@@ -175,7 +175,7 @@ const testAgent = async () => {
 }
 ```
 
-> **Info:** You can also call `.stream()` with an array of message objects that include `role` and `content`. Visit the [.stream() reference](https://mastra.ai/reference/client-js/agents) for more information.
+> **Note:** You can also call `.stream()` with an array of message objects that include `role` and `content`. Visit the [.stream() reference](https://mastra.ai/reference/client-js/agents) for more information.
 
 ## Configuration options
 

package/.docs/docs/server/mastra-server.md

@@ -4,7 +4,7 @@
 
 Mastra runs as an HTTP server that exposes your agents, workflows, and other functionality as API endpoints. The server handles request routing, middleware execution, authentication, and streaming responses.
 
-> **Info:** This page covers the [`server`](https://mastra.ai/reference/configuration) configuration options passed to the `Mastra` constructor. For running Mastra with your own HTTP server (Hono, Express, etc.), visit [Server Adapters](https://mastra.ai/docs/server/server-adapters).
+> **Note:** This page covers the [`server`](https://mastra.ai/reference/configuration) configuration options passed to the `Mastra` constructor. For running Mastra with your own HTTP server (Hono, Express, etc.), visit [Server Adapters](https://mastra.ai/docs/server/server-adapters).
 
 ## Server features
 

package/.docs/docs/workflows/dynamic-workflows.md

@@ -2,7 +2,7 @@
 
 # Dynamic workflows
 
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 Dynamic workflows are workflow definitions expressed as data instead of code. A definition is a JSON document that describes the workflow's schemas and step graph. Mastra validates the definition and registers it as a runnable workflow, then persists it in storage so it survives process restarts.
 

package/.docs/docs/workflows/overview.md

@@ -287,7 +287,7 @@ You can run workflows from agents, tools, the Mastra Client, or the command line
 const testWorkflow = mastra.getWorkflow('testWorkflow')
 ```
 
-> **Info:** `mastra.getWorkflow()` is preferred over a direct import for two reasons:
+> **Note:** `mastra.getWorkflow()` is preferred over a direct import for two reasons:
 >
 > 1. It provides access to the Mastra instance configuration (logger, telemetry, storage, registered agents, and vector stores)
 > 2. It provides full TypeScript type inference for workflow input and output schemas

package/.docs/guides/build-your-ui/ai-sdk-ui.md

@@ -55,7 +55,7 @@ Once you have your API routes set up, you can use them in the [`useChat()`](#use
 
 Run Mastra as a standalone server and connect your frontend (e.g. using Vite + React) to its API endpoints. You'll be using Mastra's [custom API routes](https://mastra.ai/docs/server/custom-api-routes) feature for this.
 
-> **Info:** Mastra's [**UI Dojo**](https://ui-dojo.mastra.ai/) is an example of this setup.
+> **Note:** Mastra's [**UI Dojo**](https://ui-dojo.mastra.ai/) is an example of this setup.
 
 You can use [`chatRoute()`](https://mastra.ai/reference/ai-sdk/chat-route), [`workflowRoute()`](https://mastra.ai/reference/ai-sdk/workflow-route), and [`networkRoute()`](https://mastra.ai/reference/ai-sdk/network-route) to create API routes that stream Mastra content in AI SDK-compatible format. Once implemented, you can use these API routes in [`useChat()`](#usechat).
 
@@ -1023,7 +1023,7 @@ export const mastra = new Mastra({
 })
 ```
 
-> **Info:** You can access this data in your tools via the `requestContext` parameter. See the [Request Context documentation](https://mastra.ai/docs/server/request-context) for more details.
+> **Note:** You can access this data in your tools via the `requestContext` parameter. See the [Request Context documentation](https://mastra.ai/docs/server/request-context) for more details.
 
 **Next.js**:
 
@@ -1383,7 +1383,7 @@ export function NestedAgentChat() {
 Key points:
 
 - Piping `fullStream` to `context.writer` creates `data-tool-agent` parts
-- Read `data-tool-agent-step` when you need the full payload for the nested step that just finished
+- Read `data-tool-agent-step` when you need the full payload for the nested step that finished
 - The `AgentDataPart` has `id` (on the part) and `data.text` (the current nested-agent text snapshot)
 - The tool still returns its own output after the stream completes
 

package/.docs/guides/build-your-ui/assistant-ui.md

@@ -4,7 +4,7 @@
 
 [Assistant UI](https://assistant-ui.com) is the TypeScript/React library for AI Chat. Built on shadcn/ui and Tailwind CSS, it enables developers to create beautiful, enterprise-grade chat experiences in minutes.
 
-> **Info:** For a full-stack integration approach where Mastra runs directly in your Next.js API routes, see the [Full-Stack Integration Guide](https://www.assistant-ui.com/docs/integrations/frameworks/mastra/full-stack) on Assistant UI's documentation site.
+> **Note:** For a full-stack integration approach where Mastra runs directly in your Next.js API routes, see the [Full-Stack Integration Guide](https://www.assistant-ui.com/docs/integrations/frameworks/mastra/full-stack) on Assistant UI's documentation site.
 
 Visit Mastra's [**"UI Dojo"**](https://ui-dojo.mastra.ai/) to see real-world examples of Assistant UI integrated with Mastra.