@mastra/mcp-docs-server 1.1.39-alpha.6 → 1.1.39

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

@@ -0,0 +1,206 @@
+# Multi-user threads
+
+A single Mastra thread can be shared by multiple users, each with their own name and functional role. You carry speaker identity in the message body so the agent can tell users apart while reading from a single shared thread.
+
+## When to use multi-user threads
+
+Use multi-user threads when several people collaborate on the same subject through one agent:
+
+- Collaborative documents with editors, reviewers, and approvers
+- Group chats where one assistant serves many participants
+- Multi-stakeholder reviews where different roles have different authority
+
+## Share one `resourceId` across all participants
+
+A thread belongs to exactly one `resourceId`, so all participants on a shared thread need to pass the same value. Instead of using a user id (the default for single-user apps), key `resourceId` on the conversation itself — for example `doc_${docId}` for a shared document, or `room_${roomId}` for a group chat. With everyone pointing at the same `resourceId`, they read and write the same history.
+
+## Tag each user message with the speaker's identity
+
+The model needs to know who's talking on every turn. Since the message body is the one place that survives into history and back into context, wrap each user message in a small `<turn>` tag with the speaker's id, name, and role. The tag stays attached to the message, so when prior turns are recalled the model still sees who said what.
+
+Build the tag with a small helper. The example below is one way to do it — copy it into your project and adapt it to your shape of user data:
+
+```typescript
+export type Speaker = {
+  id: string
+  name: string
+  role: string
+}
+
+function escapeAttr(value: string) {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+}
+
+export function asUserTurn(speaker: Speaker, text: string) {
+  const id = escapeAttr(speaker.id)
+  const name = escapeAttr(speaker.name)
+  const role = escapeAttr(speaker.role)
+  return {
+    role: 'user' as const,
+    content: `<turn author_id="${id}" author_name="${name}" functional_role="${role}">
+${text}
+</turn>`,
+  }
+}
+```
+
+Teach the agent how to read the `<turn>` tag in its instructions. The agent must have `memory` configured so it can be called with a `thread` and `resource`:
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
+
+const memory = new Memory({
+  storage: new LibSQLStore({ url: 'file:./collab.db' }),
+  options: {
+    lastMessages: 20,
+  },
+})
+
+export const collabAgent = new Agent({
+  id: 'collab',
+  name: 'CollabAgent',
+  model: 'openai/gpt-5.4-mini',
+  memory,
+  instructions: `
+You are a collaborative document assistant. Multiple users talk to you in the SAME thread.
+
+Every user message is wrapped in a <turn> tag carrying the user's identity:
+
+  <turn author_id="u_alice" author_name="Alice" functional_role="editor">
+  ...message text...
+  </turn>
+
+Rules:
+1. Address users by their author_name.
+2. Respect functional_role: editors propose changes, reviewers approve.
+3. When attributing past statements, read author_name from the surrounding <turn> tag.
+4. Do not echo the <turn> tags back at users.
+  `.trim(),
+})
+```
+
+Call the agent with the wrapped message. Every participant shares the same `thread` and `resource`:
+
+```typescript
+import { asUserTurn } from './identity'
+
+const docResourceId = 'doc_42'
+const docThreadId = 'doc_42'
+
+const alice = { id: 'u_alice', name: 'Alice', role: 'editor' }
+const bob = { id: 'u_bob', name: 'Bob', role: 'reviewer' }
+
+await collabAgent.generate([asUserTurn(alice, 'My favorite color is teal.')], {
+  memory: { thread: docThreadId, resource: docResourceId },
+})
+
+await collabAgent.generate([asUserTurn(bob, 'I want QA sign-off before publish.')], {
+  memory: { thread: docThreadId, resource: docResourceId },
+})
+```
+
+The `<turn>` tag persists in the message body, so when history is recalled on later turns the model still sees who said what.
+
+## Combining with memory layers
+
+The user-tagging pattern composes with every memory layer. Pick the layer based on how long the conversation needs to remember per-user facts:
+
+- **Short conversations** (a single session, or a thread small enough to fit in `lastMessages`), or when you need a verbatim record of who said what: use [message history alone](#message-history-alone). The user tags in history are enough; no extra memory layer needed.
+- **Long-running threads** (conversations that outgrow `lastMessages`, where you need per-user facts to survive history eviction): use [observational memory](#with-observational-memory-recommended).
+- **Need a structured participants list, or your storage adapter doesn't support OM** (OM requires LibSQL, PG, or MongoDB): use [working memory](#with-working-memory).
+
+We recommend using observational memory or working memory, not both — they cover overlapping needs, and running both at once adds latency and token cost without much benefit.
+
+### Message history alone
+
+For short conversations, or when you need a verbatim record of who said what, the user tags in history are enough. `lastMessages` brings prior turns back into context with their attribution intact:
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
+
+const memory = new Memory({
+  storage: new LibSQLStore({ url: 'file:./collab.db' }),
+  options: {
+    lastMessages: 20,
+  },
+})
+```
+
+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)
+
+[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.`
+
+Prefer OM over working memory for multi-user threads when your storage supports it. OM extracts facts automatically, scales to any number of participants, and doesn't need template upkeep. Enable it with no overrides:
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
+
+const memory = new Memory({
+  storage: new LibSQLStore({ url: 'file:./collab.db' }),
+  options: {
+    lastMessages: 20,
+    observationalMemory: true,
+  },
+})
+```
+
+OM requires a storage adapter that supports it: `@mastra/libsql`, `@mastra/pg`, or `@mastra/mongodb`.
+
+> **Note:** If you switch the Observer to a weaker model and see facts collapse to a generic `User`, use [`observation.instruction`](https://mastra.ai/reference/memory/observational-memory) to teach the Observer how to read the `<turn>` tag.
+
+### With working memory
+
+Use working memory when OM isn't an option — for example, when your storage adapter doesn't support OM, or when you need a structured, deterministic participants list the agent can read and write on every turn.
+
+The default [working memory](https://mastra.ai/docs/memory/working-memory) template assumes one user per thread ("First Name", "Last Name", etc.). For multi-user threads, provide a template with a participants list:
+
+```typescript
+import { Memory } from '@mastra/memory'
+import { LibSQLStore } from '@mastra/libsql'
+
+const memory = new Memory({
+  storage: new LibSQLStore({ url: 'file:./collab.db' }),
+  options: {
+    lastMessages: 20,
+    workingMemory: {
+      enabled: true,
+      scope: 'thread',
+      template: `# Document Collaboration State
+
+## Participants
+<!-- One entry per known collaborator. Use author_id as the stable key. -->
+<!-- - **<author_name>** (<author_id>, <functional_role>): <their position> -->
+
+## Open Questions
+
+## Decisions
+`,
+    },
+  },
+})
+```
+
+Set `scope: 'thread'` so the participants list belongs to the document, not to any individual user. Add one instruction telling the agent to append new participants to the list whenever a new `author_id` shows up in a `<turn>`.
+
+For more on templates, see [Custom templates](https://mastra.ai/docs/memory/working-memory).
+
+## Security
+
+Set the `speaker` from your authenticated request context, never from the request body. If a client can choose its own `author_id`, one user can impersonate another. Use [Request Context](https://mastra.ai/docs/server/request-context) to read the verified user from your auth layer and build the `<turn>` tag on the server before calling the agent.
+
+## Related
+
+- [Working memory](https://mastra.ai/docs/memory/working-memory)
+- [Observational memory](https://mastra.ai/docs/memory/observational-memory)
+- [Share memory between agents](https://mastra.ai/docs/memory/overview)
+- [`Memory` reference](https://mastra.ai/reference/memory/memory-class)

package/.docs/docs/memory/observational-memory.md

@@ -88,7 +88,7 @@ const memory = new Memory({
   options: {
     observationalMemory: {
       model: 'google/gemini-2.5-flash',
-      activateAfterIdle: '5m',
+      activateAfterIdle: 'auto',
       activateOnProviderChange: true,
     },
   },
@@ -144,6 +144,28 @@ OM uses fast local token estimation for this thresholding work. Text is estimate
 
 The Observer can also see attachments in the history it reviews. OM keeps readable placeholders like `[Image #1: reference-board.png]` or `[File #1: floorplan.pdf]` in the transcript for readability, and forwards the actual attachment parts alongside the text. Image-like `file` parts are upgraded to image inputs for the Observer when possible, while non-image attachments are forwarded as file parts with normalized token counting. This applies to both normal thread observation and batched resource-scope observation.
 
+If your Observer model is text-only or its API rejects multimodal input, set `observation.observeAttachments` to `false` to drop attachments before they reach the Observer. The readable placeholders (`[Image #1: ...]`, `[File #1: ...]`) are kept in the transcript so the Observer can still reason about what was shared without receiving the binary payload. The same filter applies to tool results that contain image or file parts:
+
+```typescript
+new Agent({
+  name: 'assistant',
+  instructions: 'You are a helpful assistant.',
+  model: 'openai/gpt-5-mini',
+  memory: new Memory({
+    options: {
+      observationalMemory: {
+        observation: {
+          model: 'deepseek/deepseek-reasoner',
+          observeAttachments: false,
+        },
+      },
+    },
+  }),
+})
+```
+
+You can also pass an allowlist of mimeType globs (for example `['image/*']`) to forward only the kinds the Observer can handle.
+
 ```md
 Date: 2026-01-15
 
@@ -444,35 +466,48 @@ Reflection works similarly — the Reflector runs in the background when observa
 
 ### Settings
 
-| Setting                               | Default | What it controls                                                                                                                                                                                                                                                                                                              |
-| ------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `observation.bufferTokens`            | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens` — with the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).                                                                                                                                            |
-| `observation.bufferActivation`        | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history.                                                                                                                                         |
-| `observation.blockAfter`              | `1.2`   | Safety threshold as a multiplier of `messageTokens`. At `1.2`, synchronous observation is forced at 36k tokens (1.2 × 30k). Only matters if buffering can't keep up.                                                                                                                                                          |
-| `activateAfterIdle`                   | none    | Forces buffered observations to activate after a period of inactivity, even before `observation.messageTokens` is reached. Accepts a numeric millisecond value such as `300_000`, or duration strings like `"5m"` or `"1hr"`. Set this to your prompt cache TTL if you want activation to happen before the next cold prompt. |
-| `activateOnProviderChange`            | `false` | Forces buffered observations to activate when the next step uses a different `provider/model` than the one that produced the latest assistant step. Use this when switching providers or models would invalidate prompt cache reuse.                                                                                          |
-| `reflection.bufferActivation`         | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                                                                                                                                                          |
-| `reflection.activateAfterIdle`        | none    | Opts buffered reflections into idle activation. Reflections don't inherit top-level `activateAfterIdle`.                                                                                                                                                                                                                      |
-| `reflection.activateOnProviderChange` | `false` | Opts buffered reflections into provider-change activation. Reflections don't inherit top-level `activateOnProviderChange`.                                                                                                                                                                                                    |
-| `reflection.blockAfter`               | `1.2`   | Safety threshold for reflection, same logic as observation.                                                                                                                                                                                                                                                                   |
-
-If you're relying on prompt caching, set `activateAfterIdle` to match your cache TTL. That way, once a thread has been idle long enough for the cache to expire, the next request can activate buffered observations first and send a smaller compressed context window.
+| Setting                               | Default | What it controls                                                                                                                                                                                                                                                              |
+| ------------------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `observation.bufferTokens`            | `0.2`   | How often to buffer. `0.2` means every 20% of `messageTokens` — with the default 30k threshold, that's roughly every 6k tokens. Can also be an absolute token count (e.g. `5000`).                                                                                            |
+| `observation.bufferActivation`        | `0.8`   | How aggressively to clear the message window on activation. `0.8` means remove enough messages to keep only 20% of `messageTokens` remaining. Lower values keep more message history.                                                                                         |
+| `observation.blockAfter`              | `1.2`   | Safety threshold as a multiplier of `messageTokens`. At `1.2`, synchronous observation is forced at 36k tokens (1.2 × 30k). Only matters if buffering can't keep up.                                                                                                          |
+| `activateAfterIdle`                   | none    | Forces buffered observations to activate after a period of inactivity, even before `observation.messageTokens` is reached. Accepts a numeric millisecond value such as `300_000`, duration strings like `"5m"` or `"1hr"`, or `"auto"` for a provider-aware prompt cache TTL. |
+| `activateOnProviderChange`            | `false` | Forces buffered observations to activate when the next step uses a different `provider/model` than the one that produced the latest assistant step. Use this when switching providers or models would invalidate prompt cache reuse.                                          |
+| `reflection.bufferActivation`         | `0.5`   | When to start background reflection. `0.5` means reflection begins when observations reach 50% of the `observationTokens` threshold.                                                                                                                                          |
+| `reflection.activateAfterIdle`        | none    | Opts buffered reflections into idle activation. Reflections don't inherit top-level `activateAfterIdle`.                                                                                                                                                                      |
+| `reflection.activateOnProviderChange` | `false` | Opts buffered reflections into provider-change activation. Reflections don't inherit top-level `activateOnProviderChange`.                                                                                                                                                    |
+| `reflection.blockAfter`               | `1.2`   | Safety threshold for reflection, same logic as observation.                                                                                                                                                                                                                   |
+
+If you're relying on prompt caching, set `activateAfterIdle` to `"auto"` or to a specific cache TTL. That way, once a thread has been idle long enough for the cache to expire, the next request can activate buffered observations first and send a smaller compressed context window.
+
+With `"auto"`, Mastra chooses an idle activation TTL from the active model provider:
+
+| Provider                                                                                | Auto TTL  |
+| --------------------------------------------------------------------------------------- | --------- |
+| Anthropic, OpenRouter, unknown providers, xAI                                           | 5 minutes |
+| DeepSeek                                                                                | 1 hour    |
+| Google Gemini                                                                           | 24 hours  |
+| Groq                                                                                    | 2 hours   |
+| OpenAI with `providerOptions.openai.promptCacheRetention: "24h"`                        | 1 hour    |
+| OpenAI with `providerOptions.openai.promptCacheRetention: "in_memory"`                  | 5 minutes |
+| OpenAI `gpt-4*`, `gpt-5`, `gpt-5-*`, `gpt-5.1*`, `gpt-5.2*`, `gpt-5.3*`, and `gpt-5.4*` | 5 minutes |
+| Other OpenAI models                                                                     | 1 hour    |
 
 ```typescript
 const memory = new Memory({
   options: {
     observationalMemory: {
       model: 'google/gemini-2.5-flash',
-      activateAfterIdle: '5m',
+      activateAfterIdle: 'auto',
       activateOnProviderChange: true,
     },
   },
 })
 ```
 
-With a 5-minute prompt cache TTL, this activates buffered observations after 5 minutes of inactivity so the next uncached prompt uses compressed observations instead of a larger raw message window. If you prefer, `300_000` works the same way.
+With `"auto"`, this activates buffered observations based on the active provider's prompt cache behavior so the next uncached prompt uses compressed observations instead of a larger raw message window. If you prefer a fixed 5-minute TTL, use `"5m"` or `300_000`.
 
-Changing model or providers mid-thread will invalidate the prompt cache. If your agent can switch between providers or models mid-thread, `activateOnProviderChange: true` forces buffered observations to activate before the new provider runs. That avoids sending a large raw window to a provider that can't reuse the previous prompt cache.
+Changing models or providers mid-thread will invalidate the prompt cache. If your agent can switch between providers or models mid-thread, `activateOnProviderChange: true` forces buffered observations to activate before the new provider runs. That avoids sending a large raw window to a provider that can't reuse the previous prompt cache.
 
 ### Disabling
 
@@ -530,6 +565,7 @@ No manual migration needed. OM reads existing messages and observes them lazily
 - **[Message history](https://mastra.ai/docs/memory/message-history)**: High-fidelity record of the current conversation
 - **[Working memory](https://mastra.ai/docs/memory/working-memory)**: Small, structured state (JSON or markdown) for user preferences, names, goals
 - **[Semantic Recall](https://mastra.ai/docs/memory/semantic-recall)**: RAG-based retrieval of relevant past messages
+- **[Multi-user threads](https://mastra.ai/docs/memory/multi-user-threads)**: How OM attributes facts to individual users when several people share a single thread
 
 If you're using working memory to store conversation summaries or ongoing state that grows over time, OM is a better fit. Working memory is for small, structured data; OM is for long-running event logs. OM also manages message history automatically—the `messageTokens` setting controls how much raw history remains before observation runs.
 

package/.docs/docs/memory/overview.md

@@ -7,6 +7,7 @@ Mastra agents can be configured to store [message history](https://mastra.ai/doc
 - [Observational Memory](https://mastra.ai/docs/memory/observational-memory) (Recommended): Uses background agents to maintain a dense observation log that replaces raw message history as it grows. This keeps the context window small while preserving long-term memory.
 - [Working memory](https://mastra.ai/docs/memory/working-memory): Stores persistent, structured user data such as names, preferences, and goals.
 - [Semantic recall](https://mastra.ai/docs/memory/semantic-recall): Retrieves relevant past messages based on semantic meaning rather than exact keywords.
+- [Multi-user threads](https://mastra.ai/docs/memory/multi-user-threads): Share one thread between multiple users.
 
 If the combined memory exceeds the model's context limit, [memory processors](https://mastra.ai/docs/memory/memory-processors) can filter, trim, or prioritize content so the most relevant information is preserved.
 

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

@@ -130,7 +130,7 @@ Resource-scoped working memory requires specific storage adapters that support t
 
 ## Custom templates
 
-Templates guide the agent on what information to track and update in working memory. While a default template is used if none is provided, you'll typically want to define a custom template tailored to your agent's specific use case to ensure it remembers the most relevant information.
+Templates guide the agent on what information to track and update in working memory. While a default template is used if none is provided, you'll typically want to define a custom template tailored to your agent's specific use case to ensure it remembers the most relevant information. For threads shared by multiple users, see [Multi-user threads](https://mastra.ai/docs/memory/multi-user-threads).
 
 Here's an example of a custom template. In this example the agent will store the users name, location, timezone, etc as soon as the user sends a message containing any of the info:
 

package/.docs/docs/server/auth/fga.md

@@ -25,6 +25,7 @@ const mastra = new Mastra({
     auth: new MastraAuthWorkos({
       /* ... */
       fetchMemberships: true,
+      mapUserToResourceId: user => user.teamId,
     }),
     fga: new MastraFGAWorkos({
       resourceMapping: {
@@ -39,6 +40,9 @@ const mastra = new Mastra({
         [MastraFGAPermissions.MEMORY_WRITE]: 'update',
       },
     }),
+    storedResources: {
+      scope: true,
+    },
   },
 });
 ```
@@ -47,6 +51,8 @@ When using `MastraFGAWorkos`, set `fetchMemberships: true` on `MastraAuthWorkos`
 
 Use `thread` as the resource-mapping key for memory authorization. `MastraFGAWorkos` still accepts the legacy alias `memory`, but new configs should prefer `thread`.
 
+When `server.fga` is configured, Mastra enforces FGA on protected actions. If a protected action has no authenticated user, Mastra denies it. If `server.fga` is not configured, these FGA checks are skipped and Mastra keeps the previous behavior.
+
 ### Resource mapping
 
 The `resourceMapping` tells Mastra how to resolve FGA resource types and IDs from request context. Keys are Mastra resource types, values define the FGA resource type and how to derive the ID:
@@ -67,6 +73,7 @@ resourceMapping: {
 - `user` — the authenticated user
 - `resourceId` — the owning Mastra resource ID when available (for example, a thread's `resourceId`)
 - `requestContext` — the current request context for advanced tenant resolution
+- `metadata` — provider-specific metadata for the attempted action
 
 Return `undefined` from `deriveId()` to fall back to the original Mastra resource ID.
 
@@ -89,9 +96,43 @@ If no mapping exists for a permission, the original string is passed through.
 
 Use `validatePermissions()` to validate the full set of permissions Mastra may emit at startup. Use this when a provider requires every Mastra permission to have an explicit provider permission slug.
 
+### Stored resource scoping
+
+FGA authorizes access to a resource. It does not automatically filter stored records that live in shared storage. Enable stored resource scoping when the built-in stored resource APIs are used in a multi-tenant app.
+
+```typescript
+const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthWorkos({
+      /* ... */
+      mapUserToResourceId: user => user.teamId,
+    }),
+    storedResources: {
+      scope: true,
+    },
+  },
+});
+```
+
+With `scope: true`, Mastra reads `MASTRA_RESOURCE_ID_KEY` from the request context. `mapUserToResourceId()` sets this value after authentication. Stored resource handlers persist the scope in record metadata and filter list, read, update, publish, and delete operations by that scope.
+
+Use an object when the scope needs custom request logic:
+
+```typescript
+storedResources: {
+  scope: {
+    metadataKey: 'teamId',
+    resolve: ({ user }) => user.teamId,
+    requireScope: true,
+  },
+},
+```
+
+If `requireScope` is `true` or omitted, scoped stored resource routes fail when no scope can be resolved.
+
 ### Route policy coverage
 
-Mastra includes route-level FGA metadata for built-in resource routes, including agents, workflows, tools, MCP tools, memory threads, responses, and conversations. A route is checked when it has route-level `fga` metadata, when Mastra can derive built-in metadata for that route, or when the provider supplies metadata with `resolveRouteFGA()`.
+Mastra includes route-level FGA metadata for built-in resource routes, including agents, workflows, tools, MCP tools, memory threads, responses, conversations, and stored resources. Stored resource route coverage includes `/stored/agents`, `/stored/mcp-clients`, `/stored/prompt-blocks`, `/stored/scorers`, `/stored/skills`, and `/stored/workspaces`. A route is checked when it has route-level `fga` metadata, when Mastra can derive built-in metadata for that route, or when the provider supplies metadata with `resolveRouteFGA()`.
 
 To deny protected routes that do not resolve FGA metadata, configure route policy coverage on the FGA provider:
 
@@ -159,16 +200,20 @@ const fga = new MastraFGAWorkos({
 
 When an FGA provider is configured, Mastra automatically checks authorization at these lifecycle points:
 
-| Lifecycle point                        | Permission checked                             | Resource                               |
-| -------------------------------------- | ---------------------------------------------- | -------------------------------------- |
-| Agent execution (`generate`, `stream`) | `agents:execute`                               | `{ type: 'agent', id: agentId }`       |
-| Workflow execution                     | `workflows:execute`                            | `{ type: 'workflow', id: workflowId }` |
-| Tool execution                         | `tools:execute`                                | `{ type: 'tool', id: toolName }`       |
-| Thread/memory access                   | `memory:read`, `memory:write`, `memory:delete` | `{ type: 'thread', id: threadId }`     |
-| MCP tool execution                     | `tools:execute`                                | `{ type: 'tool', id: toolName }`       |
-| HTTP resource routes                   | Configured per route                           | Configured per route                   |
+| Lifecycle point                                                  | Permission checked                              | Resource type        | Resource ID                                                         |
+| ---------------------------------------------------------------- | ----------------------------------------------- | -------------------- | ------------------------------------------------------------------- |
+| Agent execution (`generate`, `stream`)                           | `agents:execute`                                | `agent`              | `agentId`                                                           |
+| Built-in workflow HTTP execution routes and `Workflow.execute()` | `workflows:execute`                             | `workflow`           | `workflowId`                                                        |
+| Standalone tool execution                                        | `tools:execute`                                 | `tool`               | `toolName`                                                          |
+| Agent tool execution                                             | `tools:execute`                                 | `tool`               | `${agentId}:${toolName}`                                            |
+| MCP tool execution                                               | `tools:execute`                                 | `tool`               | `JSON.stringify([serverName, toolName])`                            |
+| Thread and memory access                                         | `memory:read`, `memory:write`, `memory:delete`  | `thread`             | `threadId`                                                          |
+| Stored resource routes                                           | Stored resource permission for the route action | Stored resource type | Route record ID, or the stored-resource scope for collection routes |
+| HTTP resource routes                                             | Configured per route                            | Configured per route | Configured per route                                                |
+
+Direct SDK calls to `createRun().start()`, `resume()`, or `restart()` are not independently checked by core FGA in this release. Make those calls from a protected route or guard them in application code. Pass a `requestContext` with an authenticated user when invoking protected entry points directly.
 
-All checks are **no-ops when FGA is not configured**, maintaining backward compatibility.
+Core agent, internal workflow, tool, and memory checks also pass `requestContext` and action metadata to the FGA provider. Route checks pass `requestContext`. Thread checks pass the owning `resourceId` when available.
 
 ## Custom FGA provider
 

package/.docs/models/gateways/netlify.md

@@ -1,6 +1,6 @@
 # Netlify
 
-Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 68 models through Mastra's model router.
+Netlify AI Gateway provides unified access to multiple providers with built-in caching and observability. Access 69 models through Mastra's model router.
 
 Learn more in the [Netlify documentation](https://docs.netlify.com/build/ai-gateway/overview/).
 
@@ -61,6 +61,7 @@ ANTHROPIC_API_KEY=ant-...
 | `gemini/gemini-3.1-flash-lite-preview`      |
 | `gemini/gemini-3.1-pro-preview`             |
 | `gemini/gemini-3.1-pro-preview-customtools` |
+| `gemini/gemini-3.5-flash`                   |
 | `gemini/gemini-flash-latest`                |
 | `gemini/gemini-flash-lite-latest`           |
 | `openai/chat-latest`                        |

package/.docs/models/gateways/openrouter.md

@@ -1,6 +1,6 @@
 # ![OpenRouter logo](https://models.dev/logos/openrouter.svg)OpenRouter
 
-OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 356 models through Mastra's model router.
+OpenRouter aggregates models from multiple providers with enhanced features like rate limiting and failover. Access 357 models through Mastra's model router.
 
 Learn more in the [OpenRouter documentation](https://openrouter.ai/models).
 
@@ -126,6 +126,7 @@ ANTHROPIC_API_KEY=ant-...
 | `google/gemini-3.1-flash-lite-preview`                          |
 | `google/gemini-3.1-pro-preview`                                 |
 | `google/gemini-3.1-pro-preview-customtools`                     |
+| `google/gemini-3.5-flash`                                       |
 | `google/gemma-2-27b-it`                                         |
 | `google/gemma-3-12b-it`                                         |
 | `google/gemma-3-27b-it`                                         |

package/.docs/models/index.md

@@ -1,6 +1,6 @@
 # Model Providers
 
-Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 4182 models from 120 providers through a single API.
+Mastra provides a unified interface for working with LLMs across multiple providers, giving you access to 4195 models from 121 providers through a single API.
 
 ## Features
 

package/.docs/models/providers/deepinfra.md

@@ -38,8 +38,8 @@ for await (const chunk of stream) {
 | `deepinfra/deepseek-ai/DeepSeek-V3.2`                         | 164K    |       |           |       |       |       | $0.26      | $0.38       |
 | `deepinfra/deepseek-ai/DeepSeek-V4-Flash`                     | 1.0M    |       |           |       |       |       | $0.14      | $0.28       |
 | `deepinfra/deepseek-ai/DeepSeek-V4-Pro`                       | 66K     |       |           |       |       |       | $2         | $3          |
-| `deepinfra/google/gemma-4-26B-A4B-it`                         | 256K    |       |           |       |       |       | $0.07      | $0.34       |
-| `deepinfra/google/gemma-4-31B-it`                             | 256K    |       |           |       |       |       | $0.13      | $0.38       |
+| `deepinfra/google/gemma-4-26B-A4B-it`                         | 262K    |       |           |       |       |       | $0.07      | $0.34       |
+| `deepinfra/google/gemma-4-31B-it`                             | 262K    |       |           |       |       |       | $0.13      | $0.38       |
 | `deepinfra/meta-llama/Llama-3.1-70B-Instruct`                 | 131K    |       |           |       |       |       | $0.40      | $0.40       |
 | `deepinfra/meta-llama/Llama-3.1-70B-Instruct-Turbo`           | 131K    |       |           |       |       |       | $0.40      | $0.40       |
 | `deepinfra/meta-llama/Llama-3.1-8B-Instruct`                  | 131K    |       |           |       |       |       | $0.02      | $0.05       |

package/.docs/models/providers/fireworks-ai.md

@@ -1,6 +1,6 @@
 # ![Fireworks AI logo](https://models.dev/logos/fireworks-ai.svg)Fireworks AI
 
-Access 19 Fireworks AI models through Mastra's model router. Authentication is handled automatically using the `FIREWORKS_API_KEY` environment variable.
+Access 20 Fireworks AI models through Mastra's model router. Authentication is handled automatically using the `FIREWORKS_API_KEY` environment variable.
 
 Learn more in the [Fireworks AI documentation](https://fireworks.ai/docs/).
 
@@ -32,27 +32,28 @@ for await (const chunk of stream) {
 
 ## Models
 
-| Model                                                     | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
-| --------------------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
-| `fireworks-ai/accounts/fireworks/models/deepseek-v3p1`    | 164K    |       |           |       |       |       | $0.56      | $2          |
-| `fireworks-ai/accounts/fireworks/models/deepseek-v3p2`    | 160K    |       |           |       |       |       | $0.56      | $2          |
-| `fireworks-ai/accounts/fireworks/models/deepseek-v4-pro`  | 1.0M    |       |           |       |       |       | $2         | $3          |
-| `fireworks-ai/accounts/fireworks/models/glm-4p5`          | 131K    |       |           |       |       |       | $0.55      | $2          |
-| `fireworks-ai/accounts/fireworks/models/glm-4p5-air`      | 131K    |       |           |       |       |       | $0.22      | $0.88       |
-| `fireworks-ai/accounts/fireworks/models/glm-4p7`          | 198K    |       |           |       |       |       | $0.60      | $2          |
-| `fireworks-ai/accounts/fireworks/models/glm-5`            | 203K    |       |           |       |       |       | $1         | $3          |
-| `fireworks-ai/accounts/fireworks/models/glm-5p1`          | 203K    |       |           |       |       |       | $1         | $4          |
-| `fireworks-ai/accounts/fireworks/models/gpt-oss-120b`     | 131K    |       |           |       |       |       | $0.15      | $0.60       |
-| `fireworks-ai/accounts/fireworks/models/gpt-oss-20b`      | 131K    |       |           |       |       |       | $0.05      | $0.20       |
-| `fireworks-ai/accounts/fireworks/models/kimi-k2-instruct` | 128K    |       |           |       |       |       | $1         | $3          |
-| `fireworks-ai/accounts/fireworks/models/kimi-k2-thinking` | 256K    |       |           |       |       |       | $0.60      | $3          |
-| `fireworks-ai/accounts/fireworks/models/kimi-k2p5`        | 256K    |       |           |       |       |       | $0.60      | $3          |
-| `fireworks-ai/accounts/fireworks/models/kimi-k2p6`        | 262K    |       |           |       |       |       | $0.95      | $4          |
-| `fireworks-ai/accounts/fireworks/models/minimax-m2p1`     | 200K    |       |           |       |       |       | $0.30      | $1          |
-| `fireworks-ai/accounts/fireworks/models/minimax-m2p5`     | 197K    |       |           |       |       |       | $0.30      | $1          |
-| `fireworks-ai/accounts/fireworks/models/minimax-m2p7`     | 197K    |       |           |       |       |       | $0.30      | $1          |
-| `fireworks-ai/accounts/fireworks/models/qwen3p6-plus`     | 128K    |       |           |       |       |       | $0.50      | $3          |
-| `fireworks-ai/accounts/fireworks/routers/kimi-k2p5-turbo` | 256K    |       |           |       |       |       | —          | —           |
+| Model                                                      | Context | Tools | Reasoning | Image | Audio | Video | Input $/1M | Output $/1M |
+| ---------------------------------------------------------- | ------- | ----- | --------- | ----- | ----- | ----- | ---------- | ----------- |
+| `fireworks-ai/accounts/fireworks/models/deepseek-v3p1`     | 164K    |       |           |       |       |       | $0.56      | $2          |
+| `fireworks-ai/accounts/fireworks/models/deepseek-v3p2`     | 160K    |       |           |       |       |       | $0.56      | $2          |
+| `fireworks-ai/accounts/fireworks/models/deepseek-v4-flash` | 1.0M    |       |           |       |       |       | $0.14      | $0.28       |
+| `fireworks-ai/accounts/fireworks/models/deepseek-v4-pro`   | 1.0M    |       |           |       |       |       | $2         | $3          |
+| `fireworks-ai/accounts/fireworks/models/glm-4p5`           | 131K    |       |           |       |       |       | $0.55      | $2          |
+| `fireworks-ai/accounts/fireworks/models/glm-4p5-air`       | 131K    |       |           |       |       |       | $0.22      | $0.88       |
+| `fireworks-ai/accounts/fireworks/models/glm-4p7`           | 198K    |       |           |       |       |       | $0.60      | $2          |
+| `fireworks-ai/accounts/fireworks/models/glm-5`             | 203K    |       |           |       |       |       | $1         | $3          |
+| `fireworks-ai/accounts/fireworks/models/glm-5p1`           | 203K    |       |           |       |       |       | $1         | $4          |
+| `fireworks-ai/accounts/fireworks/models/gpt-oss-120b`      | 131K    |       |           |       |       |       | $0.15      | $0.60       |
+| `fireworks-ai/accounts/fireworks/models/gpt-oss-20b`       | 131K    |       |           |       |       |       | $0.05      | $0.20       |
+| `fireworks-ai/accounts/fireworks/models/kimi-k2-instruct`  | 128K    |       |           |       |       |       | $1         | $3          |
+| `fireworks-ai/accounts/fireworks/models/kimi-k2-thinking`  | 256K    |       |           |       |       |       | $0.60      | $3          |
+| `fireworks-ai/accounts/fireworks/models/kimi-k2p5`         | 256K    |       |           |       |       |       | $0.60      | $3          |
+| `fireworks-ai/accounts/fireworks/models/kimi-k2p6`         | 262K    |       |           |       |       |       | $0.95      | $4          |
+| `fireworks-ai/accounts/fireworks/models/minimax-m2p1`      | 200K    |       |           |       |       |       | $0.30      | $1          |
+| `fireworks-ai/accounts/fireworks/models/minimax-m2p5`      | 197K    |       |           |       |       |       | $0.30      | $1          |
+| `fireworks-ai/accounts/fireworks/models/minimax-m2p7`      | 197K    |       |           |       |       |       | $0.30      | $1          |
+| `fireworks-ai/accounts/fireworks/models/qwen3p6-plus`      | 128K    |       |           |       |       |       | $0.50      | $3          |
+| `fireworks-ai/accounts/fireworks/routers/kimi-k2p5-turbo`  | 256K    |       |           |       |       |       | —          | —           |
 
 ## Advanced configuration