@mastra/mcp-docs-server 1.1.41-alpha.0 → 1.1.42-alpha.10

package/.docs/reference/processors/token-limiter-processor.md

@@ -81,7 +81,7 @@ import { TokenLimiterProcessor } from '@mastra/core/processors'
 export const agent = new Agent({
   name: 'context-limited-agent',
   instructions: 'You are a helpful assistant',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   memory: new Memory({
     /* ... */
   }),
@@ -102,7 +102,7 @@ import { TokenLimiterProcessor } from '@mastra/core/processors'
 export const agent = new Agent({
   name: 'multi-step-agent',
   instructions: 'You are a helpful research assistant with access to tools',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   inputProcessors: [
     new TokenLimiterProcessor({ limit: 8000 }), // Applied at every step
   ],
@@ -125,7 +125,7 @@ import { TokenLimiterProcessor } from '@mastra/core/processors'
 export const agent = new Agent({
   name: 'response-limited-agent',
   instructions: 'You are a helpful assistant',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   outputProcessors: [
     new TokenLimiterProcessor({
       limit: 1000,

package/.docs/reference/processors/tool-call-filter.md

@@ -90,7 +90,7 @@ import { ToolCallFilter } from '@mastra/core/processors'
 export const agent = new Agent({
   name: 'filtered-agent',
   instructions: 'You are a helpful assistant',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   tools: {
     searchDatabase,
     sendEmail,
@@ -115,7 +115,7 @@ import { ToolCallFilter } from '@mastra/core/processors'
 export const agent = new Agent({
   name: 'no-tools-context-agent',
   instructions: 'You are a helpful assistant',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   tools: {
     searchDatabase,
     sendEmail,

package/.docs/reference/processors/tool-search-processor.md

@@ -35,6 +35,8 @@ const toolSearch = new ToolSearchProcessor({
 
 **options.ttl** (`number`): Time-to-live for thread state in milliseconds. After this duration of inactivity, thread state will be cleaned up. Set to 0 to disable cleanup.
 
+**options.filter** (`(args: ToolSearchFilterArgs) => boolean | Promise<boolean>`): Optional request-aware hook for hiding tools from search results, blocking tool loading, or hiding already-loaded tools for the current request.
+
 ## Returns
 
 **id** (`string`): Processor identifier set to 'tool-search'
@@ -43,6 +45,35 @@ const toolSearch = new ToolSearchProcessor({
 
 **processInputStep** (`(args: ProcessInputStepArgs) => Promise<ProcessInputStepResult>`): Processes each step to inject search/load meta-tools and any previously loaded tools into the agent's tool set.
 
+## Request-aware filtering
+
+Use `filter` to apply request-specific policy to dynamic tools. The hook receives the resolved tool ID as `toolName`, the tool, request context, and phase. `toolName` is the ID returned by `search_tools`, which may differ from the key used in the `tools` object.
+
+```typescript
+import { ToolSearchProcessor } from '@mastra/core/processors'
+
+const toolSearch = new ToolSearchProcessor({
+  tools: allTools,
+  filter: ({ toolName, requestContext, phase }) => {
+    const plan = requestContext?.get('plan')
+
+    if (phase === 'search') {
+      return true
+    }
+
+    return plan === 'pro' || !toolName.startsWith('premium_')
+  },
+})
+```
+
+The `phase` value describes where the filter is being applied:
+
+- `search`: Filters results returned by `search_tools`.
+- `load`: Blocks `load_tool` from loading disallowed tools.
+- `active`: Hides already-loaded tools from the current request if they are no longer allowed.
+
+If the hook throws or rejects, `ToolSearchProcessor` treats the tool as disallowed for that request. The hook may run for every matching search candidate, so keep async policy checks cheap or cached. The meta-tools `search_tools` and `load_tool` are always available. Tools passed directly through the agent or `processInputStep` remain available unless you filter them outside `ToolSearchProcessor`.
+
 ## Extended usage example
 
 ```typescript
@@ -70,7 +101,7 @@ const agent = new Agent({
   name: 'dynamic-tools-agent',
   instructions:
     'You are a helpful assistant with access to many tools. Use search_tools to find relevant tools, then load_tool to make them available.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   inputProcessors: [toolSearch],
 })
 ```
@@ -91,7 +122,7 @@ import { ToolSearchProcessor, TokenLimiter } from '@mastra/core/processors'
 
 const agent = new Agent({
   name: 'my-agent',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   inputProcessors: [
     new ToolSearchProcessor({
       tools: allTools,

package/.docs/reference/processors/unicode-normalizer.md

@@ -43,7 +43,7 @@ export const agent = new Agent({
   id: 'normalized-agent',
   name: 'normalized-agent',
   instructions: 'You are a helpful assistant',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   inputProcessors: [
     new UnicodeNormalizer({
       stripControlChars: true,

package/.docs/reference/processors/working-memory-processor.md

@@ -67,7 +67,7 @@ const storage = new PostgresStorage({
 export const agent = new Agent({
   name: 'personalized-agent',
   instructions: 'You are a helpful assistant that remembers user preferences',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   inputProcessors: [
     new WorkingMemory({
       storage,

package/.docs/reference/rag/rerank.md

@@ -16,7 +16,7 @@ function rerank(
 ```typescript
 import { rerank } from '@mastra/rag'
 
-const model = 'openai/gpt-5.4'
+const model = 'openai/gpt-5.5'
 
 const rerankedResults = await rerank(vectorSearchResults, 'How do I deploy to production?', model, {
   weights: {

package/.docs/reference/server/nestjs-adapter.md

@@ -114,7 +114,7 @@ import { Mastra } from '@mastra/core/mastra'
             greeter: {
               name: 'greeter',
               description: 'Greets the user',
-              model: config.get('MASTRA_MODEL', '__OPENAI_MODEL_MINI__'),
+              model: config.get('MASTRA_MODEL', 'openai/gpt-5-mini'),
             },
           },
         }),

package/.docs/reference/server/routes.md

@@ -4,15 +4,20 @@ Server adapters register these routes when you call `server.init()`. All routes
 
 ## Agents
 
-| Method | Path                                         | Description                                      |
-| ------ | -------------------------------------------- | ------------------------------------------------ |
-| `GET`  | `/api/agents`                                | List all agents                                  |
-| `GET`  | `/api/agents/:agentId`                       | Get agent by ID (supports version query params)  |
-| `POST` | `/api/agents/:agentId/generate`              | Generate agent response                          |
-| `POST` | `/api/agents/:agentId/stream`                | Stream agent response                            |
-| `POST` | `/api/agents/:agentId/resume-stream`         | Resume a suspended agent stream with custom data |
-| `GET`  | `/api/agents/:agentId/tools`                 | List agent tools                                 |
-| `POST` | `/api/agents/:agentId/tools/:toolId/execute` | Execute agent tool                               |
+| Method | Path                                         | Description                                                             |
+| ------ | -------------------------------------------- | ----------------------------------------------------------------------- |
+| `GET`  | `/api/agents`                                | List all agents                                                         |
+| `GET`  | `/api/agents/:agentId`                       | Get agent by ID (supports version query params)                         |
+| `POST` | `/api/agents/:agentId/generate`              | Generate agent response                                                 |
+| `POST` | `/api/agents/:agentId/stream`                | Stream agent response                                                   |
+| `POST` | `/api/agents/:agentId/send-message`          | Send a user message to an active or idle thread                         |
+| `POST` | `/api/agents/:agentId/queue-message`         | Queue a user message for the next thread turn                           |
+| `POST` | `/api/agents/:agentId/signals`               | Send a lower-level signal to an active or idle thread                   |
+| `POST` | `/api/agents/:agentId/threads/subscribe`     | Subscribe to a thread stream                                            |
+| `POST` | `/api/agents/:agentId/send-tool-approval`    | Approve or decline a tool call and resume through a thread subscription |
+| `POST` | `/api/agents/:agentId/resume-stream`         | Resume a suspended agent stream with custom data                        |
+| `GET`  | `/api/agents/:agentId/tools`                 | List agent tools                                                        |
+| `POST` | `/api/agents/:agentId/tools/:toolId/execute` | Execute agent tool                                                      |
 
 ### Get agent query parameters
 
@@ -68,6 +73,100 @@ GET /api/agents/my-agent?versionId=abc123
 }
 ```
 
+### Agent message routes
+
+Use `POST /api/agents/:agentId/send-message` to send a user message to the active agent loop or wake an idle thread. Use `POST /api/agents/:agentId/queue-message` when the active run should finish before Mastra starts a follow-up run.
+
+Both routes accept the same request body:
+
+```typescript
+{
+  message: string | Array<TextPart | FilePart> | {
+    contents: string | Array<TextPart | FilePart>;
+    attributes?: Record<string, JSONValue>;
+    metadata?: Record<string, unknown>;
+    providerOptions?: ProviderMetadata;
+  };
+  runId?: string;
+  resourceId?: string;
+  threadId?: string;
+  ifActive?: {
+    behavior?: 'deliver' | 'persist' | 'discard';
+    attributes?: Record<string, string | number | boolean>;
+  };
+  ifIdle?: {
+    behavior?: 'wake' | 'persist' | 'discard';
+    streamOptions?: Omit<AgentExecutionOptions, 'messages'>;
+    attributes?: Record<string, string | number | boolean>;
+  };
+}
+```
+
+When `runId` is omitted, `resourceId` and `threadId` are required. `ifIdle` only applies to thread-targeted requests, not run-targeted requests.
+
+#### Send a message
+
+```bash
+curl -X POST http://localhost:4111/api/agents/supportAgent/send-message \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "message": {
+      "contents": "Show the shorter version.",
+      "attributes": { "sentFrom": "web" }
+    },
+    "resourceId": "user_123",
+    "threadId": "thread_456"
+  }'
+```
+
+#### Queue a message
+
+```bash
+curl -X POST http://localhost:4111/api/agents/supportAgent/queue-message \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "message": "Also check whether the tests need updates.",
+    "resourceId": "user_123",
+    "threadId": "thread_456"
+  }'
+```
+
+Both routes return:
+
+```typescript
+{
+  accepted: true;
+  runId: string;
+  signal?: CreatedAgentSignal;
+}
+```
+
+### Subscription tool approval routes
+
+Use `POST /api/agents/:agentId/send-tool-approval` when the client already has an active thread subscription. The route resumes the run and returns a JSON acknowledgement. Resumed stream chunks are delivered through `POST /api/agents/:agentId/threads/subscribe`.
+
+The route accepts this request body:
+
+```typescript
+{
+  resourceId: string;
+  threadId: string;
+  toolCallId: string;
+  approved: boolean;
+  requestContext?: Record<string, unknown>;
+}
+```
+
+The route returns:
+
+```typescript
+{
+  accepted: true;
+  runId: string;
+  toolCallId?: string;
+}
+```
+
 ## Workflows
 
 | Method | Path                                      | Description                     |

package/.docs/reference/storage/dsql.md

@@ -241,7 +241,7 @@ export const dsqlAgent = new Agent({
   name: 'DSQL Agent',
   instructions:
     'You are an AI agent with the ability to automatically recall memories from previous interactions.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   memory: new Memory({
     storage: new DSQLStore({
       id: 'dsql-agent-storage',

package/.docs/reference/storage/mongodb.md

@@ -206,7 +206,7 @@ export const mongodbAgent = new Agent({
   name: 'mongodb-agent',
   instructions:
     'You are an AI agent with the ability to automatically recall memories from previous interactions.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   memory: new Memory({
     storage: new MongoDBStore({
       uri: process.env.MONGODB_URI!,

package/.docs/reference/storage/postgresql.md

@@ -332,7 +332,7 @@ export const pgAgent = new Agent({
   name: 'PG Agent',
   instructions:
     'You are an AI agent with the ability to automatically recall memories from previous interactions.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   memory: new Memory({
     storage: new PostgresStore({
       id: 'pg-agent-storage',

package/.docs/reference/storage/redis.md

@@ -181,7 +181,7 @@ export const redisAgent = new Agent({
   name: 'Redis Agent',
   instructions:
     'You are an AI agent with the ability to automatically recall memories from previous interactions.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   memory: new Memory({
     storage: new RedisStore({
       id: 'redis-agent-storage',

package/.docs/reference/storage/spanner.md

@@ -122,6 +122,11 @@ The storage adapter creates the following tables, all using the GoogleSQL dialec
 - `mastra_prompt_blocks` / `mastra_prompt_block_versions`: prompt block records and versioned content snapshots (template content, rules, request-context schema)
 - `mastra_scorer_definitions` / `mastra_scorer_definition_versions`: scorer definition records and versioned config snapshots (judge instructions, model, score range, preset config, default sampling)
 - `mastra_schedules` / `mastra_schedule_triggers`: cron-driven workflow schedules and trigger history, consumed by Mastra's built-in `WorkflowScheduler`
+- `mastra_workspaces` / `mastra_workspace_versions`: workspace records and versioned configuration snapshots (filesystem, sandbox, mounts, search, skills, tools)
+- `mastra_datasets` / `mastra_dataset_items` / `mastra_dataset_versions`: evaluation datasets, SCD-2 versioned items, and version snapshots
+- `mastra_experiments` / `mastra_experiment_results`: experiment runs and their per-item results
+- `mastra_favorites`: per-user favorites for agents and skills, with denormalized `favoriteCount` maintained on the parent record
+- `mastra_channel_installations` / `mastra_channel_config`: multi-platform channel installations and per-platform configuration
 - `mastra_ai_spans`: AI tracing spans for observability (per-trace and per-span records, used to power the Studio traces UI)
 
 Tables are created with `STRING(MAX)` for text and JSON payloads, `INT64`, `FLOAT64`, `BOOL`, and `TIMESTAMP`.

package/.docs/reference/storage/upstash.md

@@ -103,7 +103,7 @@ export const upstashAgent = new Agent({
   name: 'Upstash Agent',
   instructions:
     'You are an AI agent with the ability to automatically recall memories from previous interactions.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   memory: new Memory({
     storage: new UpstashStore({
       id: 'upstash-agent-storage',

package/.docs/reference/streaming/agents/stream.md

@@ -322,7 +322,7 @@ await agent.stream('message for agent', {
       sentiment: z.enum(['positive', 'negative', 'neutral']),
       confidence: z.number(),
     }),
-    model: 'openai/gpt-5.4',
+    model: 'openai/gpt-5.5',
     errorStrategy: 'warn',
   },
   // Output processors for streaming response validation

package/.docs/reference/templates/overview.md

@@ -175,7 +175,7 @@ Include a `.env.example` file with all required environment variables:
 # LLM provider API keys (choose one or more)
 OPENAI_API_KEY=your_openai_api_key_here
 ANTHROPIC_API_KEY=your_anthropic_api_key_here
-GOOGLE_GENERATIVE_AI_API_KEY=your_google_api_key_here
+GOOGLE_API_KEY=your_google_api_key_here
 
 # Other service API keys as needed
 OTHER_SERVICE_API_KEY=your_api_key_here
@@ -192,7 +192,7 @@ import { Agent } from '@mastra/core/agent'
 
 const agent = new Agent({
   name: 'example-agent',
-  model: 'openai/gpt-5.4', // or other provider strings
+  model: 'openai/gpt-5.5', // or other provider strings
   instructions: 'Your agent instructions here',
 })
 ```
@@ -233,7 +233,7 @@ Detailed explanation of the template's functionality and use case.
 
 - `OPENAI_API_KEY`: Your OpenAI API key. Get one at [OpenAI Platform](https://platform.openai.com/api-keys)
 - `ANTHROPIC_API_KEY`: Your Anthropic API key. Get one at [Anthropic Console](https://console.anthropic.com/settings/keys)
-- `GOOGLE_GENERATIVE_AI_API_KEY`: Your Google AI API key. Get one at [Google AI Studio](https://makersuite.google.com/app/apikey)
+- `GOOGLE_API_KEY`: Your Google AI API key. Get one at [Google AI Studio](https://makersuite.google.com/app/apikey)
 - `OTHER_API_KEY`: Description of what this key is for
 
 ## Usage

package/.docs/reference/tools/mcp-client.md

@@ -53,6 +53,10 @@ Each server in the `servers` map is configured using the `MastraMCPServerDefinit
 
 **enableServerLogs** (`boolean`): Whether to enable logging for this server. (Default: `true`)
 
+**forwardInstructions** (`boolean`): Whether to append instructions advertised by this MCP server to an agent's system prompt when the agent uses this server's tools. Disabled by default; enable it only for servers you trust, since the instructions are injected into the agent's system prompt. (Default: `false`)
+
+**instructionsMaxLength** (`number`): Maximum number of server instruction characters to append to an agent's system prompt. (Default: `512`)
+
 **requireToolApproval** (`boolean | (params: RequireToolApprovalContext) => boolean | Promise<boolean>`): Require human approval before executing tools from this server. When set to \`true\`, all tools require approval. When set to a function, the function is called with the tool name, arguments, request context, and any tool annotations advertised by the server to dynamically decide whether approval is needed.
 
 ## Tool approval
@@ -123,6 +127,36 @@ Per the MCP specification, **clients MUST consider tool annotations to be untrus
 
 The same annotations are also exposed on the tools returned by `listTools()` and `listToolsets()` under `tool.mcp.annotations`, so you can inspect them when wiring tools into an agent.
 
+## Server instructions
+
+When an MCP server advertises instructions during initialization, `MCPClient` stores them for that server. Forwarding those instructions into an agent's system prompt is **opt-in**: set `forwardInstructions: true` on a server to have agents that use its tools (via `listTools()` or `listToolsets()`) receive its instructions automatically.
+
+The guidance is grouped by server name and truncated to `instructionsMaxLength` characters per server.
+
+```typescript
+const mcp = new MCPClient({
+  servers: {
+    db: {
+      url: new URL('http://localhost:3000/mcp'),
+      forwardInstructions: true,
+      instructionsMaxLength: 512,
+    },
+  },
+})
+
+const agent = new Agent({
+  id: 'db-agent',
+  name: 'DB Agent',
+  instructions: 'Help with database changes.',
+  model,
+  tools: await mcp.listTools(),
+})
+```
+
+When `forwardInstructions` is omitted (the default), instructions are still cached and can be inspected via [`getServerInstructions()`](#getserverinstructions), but are not added to any agent's system prompt.
+
+> **Security note:** server instructions are forwarded verbatim (subject only to length truncation) into the agent's system prompt. A malicious or compromised MCP server can use them to inject instructions the agent will treat as trusted system guidance. Only enable `forwardInstructions` for servers you trust, and prefer reviewing instructions with `getServerInstructions()` before forwarding instructions from third-party servers.
+
 ## Methods
 
 ### `listTools()`
@@ -143,6 +177,23 @@ const res = await agent.stream(prompt, {
 })
 ```
 
+### `getServerInstructions()`
+
+Returns the instructions currently known for each configured MCP server. Servers that have not connected yet, or do not advertise instructions, return `undefined`.
+
+```typescript
+getServerInstructions(): Record<string, string | undefined>
+```
+
+Example:
+
+```typescript
+await mcp.listTools()
+
+const instructionsByServer = mcp.getServerInstructions()
+console.log(instructionsByServer.db)
+```
+
 ### `disconnect()`
 
 Disconnects from all MCP servers and cleans up resources.
@@ -839,7 +890,7 @@ const agent = new Agent({
   id: 'multi-tool-agent',
   name: 'Multi-tool Agent',
   instructions: 'You have access to multiple tool servers.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   tools: await mcp.listTools(),
 })
 
@@ -890,7 +941,7 @@ const agent = new Agent({
   id: 'multi-tool-agent',
   name: 'Multi-tool Agent',
   instructions: 'You help users check stocks and weather.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 })
 
 // Later, configure MCP with user-specific settings

package/.docs/reference/tools/mcp-server.md

@@ -22,7 +22,7 @@ const myAgent = new Agent({
   name: 'MyExampleAgent',
   description: 'A generalist to help with basic questions.',
   instructions: 'You are a helpful assistant.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
 })
 
 const weatherTool = createTool({
@@ -67,6 +67,8 @@ The constructor accepts an `MCPServerConfig` object with the following propertie
 
 **instructions** (`string`): Optional instructions describing how to use the server and its features.
 
+**mapAuthInfoToUser** (`({ authInfo, extra, requestContext }) => unknown | null | undefined | Promise<unknown | null | undefined>`): Maps MCP transport auth data from \`extra.authInfo\` into the \`user\` value used by Mastra FGA checks. Use this when an OAuth-protected MCP server is registered on a Mastra instance with an FGA provider.
+
 **repository** (`Repository`): Optional repository information for the server's source code.
 
 **releaseDate** (`string`): Optional release date of this server version (ISO 8601 string). Defaults to the time of instantiation if not provided.
@@ -1097,6 +1099,36 @@ Whatever you set on `req.auth` in your HTTP middleware becomes available as `con
 req.auth = { ... }  →  context?.mcp?.extra?.authInfo.extra = { ... }
 ```
 
+### Map auth data for FGA
+
+When an `MCPServer` is registered on a Mastra instance with a fine-grained authorization (FGA) provider, Mastra checks `requestContext.get('user')` before listing or calling tools. HTTP MCP transports pass authenticated data as `extra.authInfo`, so use `mapAuthInfoToUser` to set the user shape expected by your FGA provider.
+
+```typescript
+const server = new MCPServer({
+  id: 'my-server',
+  name: 'My Server',
+  version: '1.0.0',
+  tools: { getUserData },
+  mapAuthInfoToUser: ({ authInfo }) => {
+    const user = authInfo as {
+      extra?: {
+        userId?: string
+        organizationMembershipId?: string
+      }
+    }
+
+    if (!user.extra?.userId) {
+      return null
+    }
+
+    return {
+      id: user.extra.userId,
+      organizationMembershipId: user.extra.organizationMembershipId,
+    }
+  },
+})
+```
+
 ### Setting Up Authentication Middleware
 
 To pass data to your tools, populate `req.auth` on the Node.js request object in your HTTP server middleware before calling `server.startHTTP()`.

package/.docs/reference/tools/vector-query-tool.md

@@ -142,7 +142,7 @@ const queryTool = createVectorQueryTool({
   indexName: 'documentation',
   model: new ModelRouterEmbeddingModel('openai/text-embedding-3-small'),
   reranker: {
-    model: 'openai/gpt-5.4',
+    model: 'openai/gpt-5.5',
     options: {
       weights: {
         semantic: 0.5, // Semantic relevance weight

package/.docs/reference/vectors/libsql.md

@@ -277,7 +277,7 @@ export const libsqlAgent = new Agent({
   name: 'libSQL Agent',
   instructions:
     'You are an AI agent with the ability to automatically recall memories from previous interactions.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   memory: new Memory({
     storage: new LibSQLStore({
       id: 'libsql-agent-storage',

package/.docs/reference/vectors/mongodb.md

@@ -263,7 +263,7 @@ export const mongodbAgent = new Agent({
   name: 'mongodb-agent',
   instructions:
     'You are an AI agent with the ability to automatically recall memories from previous interactions.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   memory: new Memory({
     storage: new MongoDBStore({
       id: 'mongodb-storage',

package/.docs/reference/vectors/pg.md

@@ -26,6 +26,8 @@ The PgVector class provides vector search using [PostgreSQL](https://www.postgre
 
 **pgPoolOptions** (`PoolConfig`): Additional pg pool configuration options
 
+**disableInit** (`boolean`): When true, automatic DDL (schema, extension, table, and index creation) inside \`createIndex\` is skipped. Useful for CI/CD pipelines where schema and indexes are managed separately and the runtime database role lacks DDL privileges. Can also be enabled with the \`MASTRA\_DISABLE\_STORAGE\_INIT\` environment variable. (Default: `false`)
+
 ## Constructor examples
 
 ### Connection String
@@ -399,7 +401,7 @@ export const pgAgent = new Agent({
   name: 'PG Agent',
   instructions:
     'You are an AI agent with the ability to automatically recall memories from previous interactions.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   memory: new Memory({
     storage: new PostgresStore({
       id: 'pg-agent-storage',

package/.docs/reference/vectors/upstash.md

@@ -265,7 +265,7 @@ export const upstashAgent = new Agent({
   name: 'Upstash Agent',
   instructions:
     'You are an AI agent with the ability to automatically recall memories from previous interactions.',
-  model: 'openai/gpt-5.4',
+  model: 'openai/gpt-5.5',
   memory: new Memory({
     storage: new UpstashStore({
       id: 'upstash-agent-storage',

package/.docs/reference/voice/google-gemini-live.md

@@ -242,7 +242,9 @@ The GeminiLiveVoice class emits the following events:
 
 **speaking** (`event`): Emitted with audio metadata. Callback receives { audioData?: Int16Array, sampleRate?: number }.
 
-**writing** (`event`): Emitted when transcribed text is available. Callback receives { text: string, role: 'assistant' | 'user' }.
+**writing** (`event`): Emitted when transcribed text is available. Callback receives { text: string, role: 'assistant' | 'user' }. On native-audio models the assistant transcript is driven by the server's \`output\_audio\_transcription\` channel rather than \`modelTurn.parts.text\`.
+
+**thinking** (`event`): Emitted on native-audio models with the model's chain-of-thought / reasoning text from \`modelTurn.parts.text\`. Callback receives { text: string }. Does not fire on non-native-audio models, where \`modelTurn.parts.text\` is the spoken response and is emitted as \`writing\` instead.
 
 **session** (`event`): Emitted on session state changes. Callback receives { state: 'connecting' | 'connected' | 'disconnected' | 'disconnecting' | 'updated', config?: object }.
 
@@ -254,7 +256,18 @@ The GeminiLiveVoice class emits the following events:
 
 **error** (`event`): Emitted when an error occurs. Callback receives { message: string, code?: string, details?: unknown }.
 
-**interrupt** (`event`): Interrupt events. Callback receives { type: 'user' | 'model', timestamp: number }.
+**interrupt** (`event`): Emitted on barge-in when the user starts speaking over an in-flight model response. The server cancels any further audio for the current turn. Callback receives { type: 'user', timestamp: number }.
+
+## Native-audio behavior
+
+Native-audio Gemini Live models — any model whose ID contains `native-audio`, such as `gemini-2.5-flash-native-audio-preview-12-2025` — split text output across two channels:
+
+- The model's spoken reply is delivered as audio plus an `output_audio_transcription` transcript and surfaced as `writing` with `role: 'assistant'`.
+- The model's internal reasoning is delivered as `modelTurn.parts.text` and surfaced as `thinking`.
+
+On non-native-audio models there is no `output_audio_transcription` channel, so `modelTurn.parts.text` is the spoken response itself and is emitted as `writing`; the `thinking` event does not fire.
+
+Input transcription, output transcription, and barge-in detection (`realtime_input_config.activity_handling = 'START_OF_ACTIVITY_INTERRUPTS'`) are enabled automatically in the setup payload — no extra configuration is required.
 
 ## Available models