@mastra/mcp-docs-server 1.2.15-alpha.1 → 1.2.15-alpha.10

package/.docs/reference/storage/retention.md

@@ -92,7 +92,7 @@ Each domain declares which of its tables can be age-pruned and which timestamp c
 > - Experiments prune as whole units: an aged experiment's result rows are deleted together with it (results cascade with their parent), so a run is never left partially deleted. Retention doesn't have a separate `results` key.
 > - For `schedules`, the growth table is the fire history (`schedule_triggers`, one row per fire): schedule definitions are config and aren't pruned.
 > - On PostgreSQL, timestamp anchors use the timezone-aware mirror columns (for example `createdAtZ`, `completedAtZ`).
-> - LibSQL supports all domains above; PostgreSQL and MongoDB support all except `threadState` and `harness`, which they don't implement.
+> - LibSQL and PostgreSQL support all domains above except `harness`, which PostgreSQL doesn't implement. MongoDB supports all except `threadState` and `harness`.
 > - The v-next PostgreSQL observability domain stores signal events in day-partitioned tables (`spans`, `metrics`, `logs`, `scores`, `feedback`). For it, `prune()` drops whole day partitions (or TimescaleDB chunks) that are entirely older than the cutoff instead of deleting rows: effective level of detail is one day, and a partition is only dropped once its entire day is past `maxAge`. `PruneResult.deleted` reports the number of rows in the dropped partitions.
 
 ## Methods

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

@@ -66,7 +66,7 @@ const stream = await agent.stream('message for agent')
 
 **options.delegation** (`DelegationConfig`): Configuration for subagent delegation. Use this to control and monitor when the agent delegates tasks to other agents, including the ability to modify, reject delegations, and provide feedback to guide the supervisor.
 
-**options.delegation.onDelegationStart** (`(context: DelegationStartContext) => DelegationStartResult | void | Promise<DelegationStartResult | void>`): Called before delegating to a subagent. Use this to modify the delegation parameters or reject the delegation entirely.
+**options.delegation.onDelegationStart** (`(context: DelegationStartContext) => DelegationStartResult | void | Promise<DelegationStartResult | void>`): Called before delegating to a subagent. Use this to modify the delegation parameters, reject the delegation entirely, or mutate context.requestContext to add entries to the subagent run's request context.
 
 **options.delegation.onDelegationComplete** (`(context: DelegationCompleteContext) => { feedback?: string } | void | Promise<{ feedback?: string } | void>`): Called after a subagent delegation completes. The context includes a bail() method to stop further execution, and you can return { feedback } to guide the supervisor's next action. Feedback is saved to supervisor memory as an assistant message.
 

package/.docs/reference/tools/bedrock-kb-tool.md

@@ -0,0 +1,117 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# createBedrockKBTool()
+
+The `createBedrockKBTool()` function creates a tool that retrieves relevant documents from an Amazon Bedrock Knowledge Base. It supports both managed search configuration and agentic retrieval (query decomposition and managed reranking) with automatic fallback to standard retrieval.
+
+## Usage example
+
+```typescript
+import { createBedrockKBTool } from '@mastra/rag'
+
+const kbTool = createBedrockKBTool({
+  knowledgeBaseId: 'YOUR_KB_ID',
+  region: 'us-west-2',
+  numberOfResults: 5,
+  useAgenticRetrieval: true,
+})
+```
+
+### With an Agent
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { createBedrockKBTool } from '@mastra/rag'
+
+const kbTool = createBedrockKBTool({
+  knowledgeBaseId: 'YOUR_KB_ID',
+})
+
+const agent = new Agent({
+  name: 'KnowledgeAssistant',
+  instructions: 'Use the knowledge base tool to answer questions.',
+  model: myModel,
+  tools: { kb: kbTool },
+})
+```
+
+## Parameters
+
+**knowledgeBaseId** (`string`): The ID of the Amazon Bedrock Knowledge Base to query.
+
+**region** (`string`): AWS region where the Knowledge Base is deployed. Defaults to AWS\_REGION environment variable or us-east-1.
+
+**numberOfResults** (`number`): Maximum number of results to return. Defaults to 5.
+
+**useAgenticRetrieval** (`boolean`): Use AgenticRetrieveStream for complex queries with query decomposition and managed reranking. Falls back to standard Retrieve on failure. Defaults to true (disable with USE\_AGENTIC\_RETRIEVAL=false env var).
+
+**userId** (`string`): Default AWS user ID for document-level access control. A userId in the Mastra request context takes precedence.
+
+## Input Schema
+
+The tool accepts the following input when called by an agent:
+
+**queryText** (`string`): The search query to find relevant documents in the knowledge base.
+
+## Output Schema
+
+The tool returns an object with:
+
+**results** (`BedrockKBResult[]`): Array of retrieval results. Standard retrieval includes source and score when Bedrock provides them; agentic retrieval may omit those fields.
+
+### BedrockKBResult
+
+| Field      | Type                      | Description                                                                                                                           |
+| ---------- | ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `content`  | `string`                  | The text content of the retrieved passage.                                                                                            |
+| `source`   | `string \| undefined`     | The source URI when Bedrock provides one. Agentic retrieval only includes this field when the result metadata contains `_source_uri`. |
+| `score`    | `number \| undefined`     | The relevance score returned by standard retrieval. The agentic API doesn't return a score for result items.                          |
+| `metadata` | `Record<string, unknown>` | Additional metadata from the retrieval result.                                                                                        |
+
+## Retrieval Modes
+
+### Agentic Retrieval (default)
+
+When `useAgenticRetrieval` is `true` (default), the tool uses `AgenticRetrieveStreamCommand` which:
+
+- Decomposes complex queries into sub-queries
+- Retrieves across multiple passes
+- Applies managed reranking for better results
+
+If agentic retrieval fails (e.g., older SDK, permissions), it automatically falls back to standard managed retrieval.
+
+### Standard Managed Retrieval
+
+When `useAgenticRetrieval` is `false`, the tool uses `RetrieveCommand` with `managedSearchConfiguration` for direct single-pass retrieval.
+
+## User-based access control
+
+Set `userId` in the Mastra request context to forward it as the Bedrock `userContext.userId`. This supports knowledge bases that enforce document-level access control. The request context value overrides the default `userId` configured on the tool.
+
+```typescript
+import { RequestContext } from '@mastra/core/request-context'
+
+const requestContext = new RequestContext()
+requestContext.set('userId', 'user-123')
+
+await agent.generate('Find my private documents', { requestContext })
+```
+
+## Required IAM Permissions
+
+```json
+{
+  "Version": "2012-10-17",
+  "Statement": [
+    {
+      "Effect": "Allow",
+      "Action": ["bedrock:Retrieve", "bedrock:AgenticRetrieveStream"],
+      "Resource": "arn:aws:bedrock:*:*:knowledge-base/*"
+    }
+  ]
+}
+```
+
+## SDK Requirements
+
+- `@aws-sdk/client-bedrock-agent-runtime` >= 3.1000 (AgenticRetrieveStreamCommand requires \~3.1000+)

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

@@ -37,6 +37,8 @@ Each server in the `servers` map is configured using the `MastraMCPServerDefinit
 
 **env** (`Record<string, string>`): For Stdio servers: Environment variables to set for the command.
 
+**inheritDefaultEnv** (`boolean`): For Stdio servers: Whether the subprocess environment starts from the MCP SDK's default inherited environment. The default is a curated whitelist, not the full process environment: on POSIX it inherits HOME, LOGNAME, PATH, SHELL, TERM, and USER; on Windows it inherits APPDATA, HOMEDRIVE, HOMEPATH, LOCALAPPDATA, PATH, PROCESSOR\_ARCHITECTURE, SYSTEMDRIVE, SYSTEMROOT, TEMP, USERNAME, and USERPROFILE. When set to false, only the variables explicitly listed in env are passed to the subprocess. Note that a subprocess without PATH may fail to spawn commands that are not absolute paths. (Default: `true`)
+
 **url** (`URL`): For HTTP servers (Streamable HTTP or SSE): The URL of the server.
 
 **requestInit** (`RequestInit`): For HTTP servers: Request configuration for the fetch API.
@@ -45,6 +47,8 @@ Each server in the `servers` map is configured using the `MastraMCPServerDefinit
 
 **fetch** (`MastraFetchLike`): For HTTP servers: Custom fetch implementation used for all network requests. Receives an optional third requestContext parameter containing request-scoped data (e.g., authentication cookies, bearer tokens) from the incoming request. When provided, this function will be used for all HTTP requests, allowing you to add dynamic authentication headers, forward request-scoped credentials to the MCP server, customize request behavior per-request, or intercept and modify requests/responses. When fetch is provided, requestInit, eventSourceInit, and authProvider become optional, as you can handle these concerns within your custom fetch function.
 
+**allowedHosts** (`string[]`): For HTTP servers: Opt-in allowlist of hosts the client may contact on behalf of this server. Each entry is matched against the URL host (hostname plus port when the URL carries a non-default port), for example "api.example.com" or "localhost:8080". Matching is exact and case-insensitive on the hostname; wildcards are not supported and the URL scheme is not checked. An empty array denies all requests. When unset, no restriction is applied. See the Security section below for enforcement details.
+
 **logger** (`LogHandler`): Optional additional handler for logging.
 
 **timeout** (`number`): Server-specific timeout in milliseconds.
@@ -159,6 +163,56 @@ When `forwardInstructions` is omitted (the default), instructions are still cach
 
 > **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.
 
+## Security
+
+### Subprocess environment for Stdio servers
+
+Stdio subprocesses don't inherit the full parent process environment. By default the subprocess environment starts from the MCP SDK's curated whitelist (POSIX: `HOME`, `LOGNAME`, `PATH`, `SHELL`, `TERM`, `USER`; Windows: `APPDATA`, `HOMEDRIVE`, `HOMEPATH`, `LOCALAPPDATA`, `PATH`, `PROCESSOR_ARCHITECTURE`, `SYSTEMDRIVE`, `SYSTEMROOT`, `TEMP`, `USERNAME`, `USERPROFILE`), merged with any variables you set in `env`. Sensitive variables such as API keys aren't inherited unless you pass them explicitly.
+
+For stricter isolation, set `inheritDefaultEnv: false` so only your configured `env` entries reach the subprocess:
+
+```typescript
+const mcp = new MCPClient({
+  servers: {
+    myTool: {
+      command: '/usr/local/bin/my-mcp-server',
+      inheritDefaultEnv: false,
+      env: { MY_TOOL_API_KEY: process.env.MY_TOOL_API_KEY! },
+    },
+  },
+})
+```
+
+Variables you place in `env` are forwarded verbatim, so treat server configurations that come from untrusted sources (for example, user-supplied config files) as untrusted input.
+
+### Restricting outbound hosts with `allowedHosts`
+
+When HTTP server URLs come from untrusted configuration, an attacker-controlled URL can point the client at internal services (server-side request forgery). Set `allowedHosts` on such servers to restrict which hosts the client will contact:
+
+```typescript
+const mcp = new MCPClient({
+  servers: {
+    remote: {
+      url: new URL(untrustedConfig.serverUrl),
+      allowedHosts: ['api.example.com'],
+    },
+  },
+})
+```
+
+Enforcement details:
+
+- On the default fetch path, requests to disallowed hosts, including every redirect hop, are blocked **before** they're sent. Redirects are followed manually (up to 5 hops) so each hop is validated, and the `Authorization` header isn't carried across hops to a different origin (any scheme, host, or port change drops it, matching standard fetch behavior).
+- When you supply a custom `fetch` (or a custom `eventSourceInit.fetch`), the initial URL is still checked before the request, but redirect hops are validated **after the fact** using `response.url`: the outbound hop may occur, and the response is discarded when its final URL points at a disallowed host. A hand-built `Response` with an empty `response.url` skips this post-hoc check.
+- OAuth requests made through `authProvider` (authorization server metadata discovery, token exchange, refresh) are also validated. If your authorization server runs on a different host than the MCP server, add that host to `allowedHosts` too.
+- A blocked host fails the connection with a clear error and is never retried by the reconnect logic.
+
+`allowedHosts` is intentionally minimal: it matches exact hosts and doesn't support wildcards or scheme checks. If you need richer policy (scheme checks, IP-range rules), supply a custom `fetch` implementation, which is invoked for every request the client makes.
+
+### Treat tool responses as untrusted input
+
+Tool results returned by MCP servers flow into your agent's context as model input. A malicious or compromised server can use tool output for prompt injection. The transport client doesn't sanitize tool responses: sanitization policy belongs at the agent layer, where Mastra's [input and output processors](https://mastra.ai/docs/agents/processors) let you inspect, transform, or block content before and after it reaches the model. Combine this with `requireToolApproval` and the `forwardInstructions` security note above when working with third-party servers.
+
 ## Methods
 
 ### `listTools()`

package/.docs/reference/vectors/oracledb.md

@@ -0,0 +1,347 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# OracleDB vector store
+
+`OracleVector` stores embeddings in Oracle Database `VECTOR` columns and exposes them through Mastra's vector interface. Each logical Mastra vector index is mapped to an Oracle vector table through a registry table, while metadata is stored as Oracle JSON for structured filtering.
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/oracledb@latest
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/oracledb@latest
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/oracledb@latest
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/oracledb@latest
+```
+
+## Usage
+
+```ts
+import { OracleVector } from '@mastra/oracledb'
+
+const vector = new OracleVector({
+  id: 'oracle-vector',
+  user: process.env.ORACLE_DATABASE_USER,
+  password: process.env.ORACLE_DATABASE_PASSWORD,
+  connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
+})
+
+await vector.createIndex({
+  indexName: 'memory_messages',
+  dimension: 1536,
+  metric: 'cosine',
+})
+
+await vector.upsert({
+  indexName: 'memory_messages',
+  vectors: [embedding],
+  metadata: [{ resource_id: 'user-1', thread_id: 'thread-1' }],
+})
+
+const results = await vector.query({
+  indexName: 'memory_messages',
+  queryVector,
+  topK: 5,
+  filter: { resource_id: 'user-1' },
+})
+```
+
+By default, `OracleVector` uses exact search with no approximate vector index. Configure IVF or HNSW when your dataset and latency requirements need approximate search.
+
+## Constructor options
+
+Pass Oracle connection options (`user`, `password`, `connectString`, `pool`, wallet options, or `externalAuth`) directly, or pass `poolManager` to share the pool used by `OracleStore`. The vector-specific options are:
+
+**id** (`string`): Unique identifier for this vector store instance.
+
+**poolManager** (`OraclePoolManager`): Shared Oracle pool manager. Use this to share one Oracle pool with OracleStore.
+
+**schemaName** (`string`): Oracle schema name used to qualify the vector registry and vector tables.
+
+**tablePrefix** (`string`): Prefix used for physical Oracle vector tables. (Default: `'MASTRA_VEC'`)
+
+**registryTableName** (`string`): Oracle table used to map Mastra logical index names to physical vector tables. (Default: `'MASTRA_VECTOR_INDEXES'`)
+
+**defaultIndexConfig** (`OracleVectorIndexConfig`): Default Oracle vector index configuration. (Default: `{ type: 'none', accuracy: 95 }`)
+
+**defaultMetadataIndexes** (`string[]`): Metadata fields to index automatically when vector tables are created. (Default: `['thread_id', 'resource_id', 'message_id', 'source_id']`)
+
+**defaultVectorFormat** (`'vector' | 'bit' | 'int8'`): Default Oracle vector format for dense, binary, and int8 embeddings. (Default: `'vector'`)
+
+**upsertBatchSize** (`number`): Number of vectors sent per Oracle executeMany call. The full upsert commits once after all batches succeed. (Default: `200`)
+
+## Constructor examples
+
+### Shared pool with OracleStore
+
+```ts
+import { OracleStore, OracleVector } from '@mastra/oracledb'
+
+const storage = new OracleStore({ id: 'oracle-storage', user, password, connectString })
+
+const vector = new OracleVector({
+  id: 'oracle-vector',
+  poolManager: storage.getPoolManager(),
+})
+```
+
+For Autonomous Database and mTLS connections, pass `walletLocation`, `walletPassword`, and `configDir` in the same constructor.
+
+## Methods
+
+### `createIndex()`
+
+Creates the registry row, physical Oracle vector table, metadata indexes, and optionally an Oracle vector index.
+
+**indexName** (`string`): Logical Mastra index name. The provider maps this to a valid Oracle table name internally.
+
+**dimension** (`number`): Vector dimension. This must match the embedding model output size.
+
+**metric** (`'cosine' | 'euclidean' | 'dotproduct' | 'hamming' | 'jaccard'`): Distance metric for similarity search. Binary vectors support hamming and jaccard. (Default: `cosine`)
+
+**vectorFormat** (`'vector' | 'bit' | 'int8'`): Oracle vector storage format. (Default: `vector`)
+
+**indexConfig** (`OracleVectorIndexConfig`): Oracle vector index configuration. none means exact search with no approximate vector index. (Default: `{ type: 'none', accuracy: 95 }`)
+
+**buildIndex** (`boolean`): Whether to build the Oracle vector index when indexConfig.type is ivf or hnsw. (Default: `true`)
+
+**metadataIndexes** (`string[]`): Metadata field names to index for faster JSON metadata filtering.
+
+#### `OracleVectorIndexConfig`
+
+**type** (`'none' | 'ivf' | 'hnsw'`): Oracle vector index type. (Default: `'none'`)
+
+**accuracy** (`number`): Target accuracy for approximate vector search. (Default: `95`)
+
+**ivf.neighborPartitions** (`number`): Oracle IVF neighbor partitions setting.
+
+**hnsw\.neighbors** (`number`): Oracle HNSW neighbor setting.
+
+**hnsw\.efConstruction** (`number`): Oracle HNSW build-time construction setting.
+
+#### Index configuration
+
+```ts
+await vector.createIndex({
+  indexName: 'support_articles',
+  dimension: 1536,
+  metric: 'cosine',
+  indexConfig: {
+    type: 'ivf',
+    accuracy: 95,
+    ivf: {
+      neighborPartitions: 32,
+    },
+  },
+})
+```
+
+The default is `indexConfig: { type: 'none' }`, which uses exact search and requires no approximate index tuning. Use IVF or HNSW only when your data volume and latency requirements justify approximate search. HNSW is configured with `indexConfig: { type: 'hnsw', hnsw: { neighbors, efConstruction } }` and requires Oracle Vector Pool memory, which `configureVectorMemory()` can allocate for local or self-managed databases.
+
+### `upsert()`
+
+**indexName** (`string`): Name of the index to upsert vectors into.
+
+**vectors** (`number[][]`): Array of embedding vectors.
+
+**metadata** (`Record<string, any>[]`): Metadata stored as Oracle JSON. Must align by position with vectors.
+
+**ids** (`string[]`): Optional vector IDs. IDs are generated when omitted.
+
+### `query()`
+
+**indexName** (`string`): Name of the index to query.
+
+**queryVector** (`number[]`): Query vector.
+
+**topK** (`number`): Number of results to return. (Default: `10`)
+
+**filter** (`Record<string, any>`): Mastra metadata filter translated to Oracle JSON predicates.
+
+**includeVector** (`boolean`): Whether to include the vector in each result. (Default: `false`)
+
+**minScore** (`number`): Minimum similarity score threshold. (Default: `-1`)
+
+**queryMode** (`'exact' | 'approx'`): Oracle query mode. Exact search is used by default when no approximate vector index is configured.
+
+**targetAccuracy** (`number`): Target accuracy for approximate Oracle vector queries.
+
+### `listIndexes()`
+
+Returns the logical Mastra index names recorded in the Oracle vector registry table.
+
+### `describeIndex()`
+
+Returns Oracle index metadata, including the physical table name, dimension, vector count, metric, index type, vector format, and configured accuracy.
+
+### `deleteIndex()`
+
+Deletes the Oracle vector table and removes the registry entry for the logical index.
+
+### `updateVector()`
+
+Update vectors by ID or metadata filter. Either `id` or `filter` must be provided, but not both. The `update` object may include `vector`, `metadata`, or both.
+
+```ts
+await vector.updateVector({
+  indexName: 'support_articles',
+  id: 'doc-1',
+  update: { metadata: { status: 'reviewed' } },
+})
+```
+
+### `deleteVector()`
+
+Deletes a single vector by ID.
+
+### `deleteVectors()`
+
+Deletes multiple vectors by IDs or by metadata filter. Either `ids` or `filter` must be provided, but not both.
+
+### `buildIndex()`
+
+Builds an Oracle vector index for an existing logical index. If the resolved index type is `none`, this method is a no-op.
+
+### `rebuildIndex()`
+
+Drops and recreates the Oracle vector index for an existing logical index, typically after changing approximate-index tuning.
+
+### Index diagnostics
+
+Use `getIndexStatus({ indexName })` to inspect Oracle catalog status, and `indexAccuracyQuery({ indexName, queryVector, topK, targetAccuracy })` to run `DBMS_VECTOR.INDEX_ACCURACY_QUERY` for approximate indexes.
+
+### `configureVectorMemory()`
+
+Allocates Oracle Vector Pool memory, which HNSW indexes require. This calls `ALTER SYSTEM SET VECTOR_MEMORY_SIZE`, so it requires a privileged connection such as `SYSDBA` or `SYSTEM`.
+
+**size** (`string`): Vector pool size, as an integer optionally followed by K, M, or G (for example "512M").
+
+**scope** (`'MEMORY' | 'SPFILE' | 'BOTH'`): Oracle ALTER SYSTEM scope. Use 'SPFILE' or 'BOTH' so the setting survives a database restart. (Default: `'MEMORY'`)
+
+### `disconnect()`
+
+Closes the Oracle pool when `OracleVector` created the pool manager. If you provide `pool` or `poolManager`, you own that lifecycle.
+
+## Metadata filters
+
+`OracleVector` accepts Mastra's standard metadata filter syntax. Filters are translated into Oracle JSON predicates with bound values:
+
+- scalar comparisons use `JSON_VALUE`
+- array, existence, and element-match checks use `JSON_EXISTS`
+- regex filters use `REGEXP_LIKE`
+- string contains filters use case-insensitive `LIKE`
+
+```ts
+const results = await vector.query({
+  indexName: 'memory_messages',
+  queryVector,
+  topK: 5,
+  filter: {
+    resource_id: 'user-1',
+    tags: { $contains: 'support' },
+    score: { $gte: 0.8 },
+    $or: [{ source: 'docs' }, { source: 'tickets' }],
+  },
+})
+```
+
+Metadata is stored as native Oracle JSON, so the rows are also readable directly with standard Oracle JDBC tools such as DBeaver and SQL Developer.
+
+Use `ORACLEDB_PROMPT` when an agent should generate Oracle-compatible metadata filters for `createVectorQueryTool()`:
+
+```ts
+import { Agent } from '@mastra/core/agent'
+import { createVectorQueryTool } from '@mastra/rag'
+import { fastembed } from '@mastra/fastembed'
+import { ORACLEDB_PROMPT } from '@mastra/oracledb'
+
+const vectorQueryTool = createVectorQueryTool({
+  vectorStoreName: 'oracle',
+  indexName: 'support_articles',
+  model: fastembed,
+  enableFilter: true,
+})
+
+export const ragAgent = new Agent({
+  id: 'oracle-rag-agent',
+  name: 'Oracle RAG Agent',
+  model: 'openai/gpt-5.6-sol',
+  instructions: `
+Use the retrieval tool when you need source context.
+Available metadata fields: resource_id, thread_id, source, category, tags.
+${ORACLEDB_PROMPT}
+`,
+  tools: { vectorQueryTool },
+})
+```
+
+## Response types
+
+Query results are returned in this format:
+
+```ts
+interface QueryResult {
+  id: string
+  score: number
+  metadata: Record<string, any>
+  vector?: number[]
+}
+```
+
+## Usage example
+
+```ts
+import { Agent } from '@mastra/core/agent'
+import { Memory } from '@mastra/memory'
+import { fastembed } from '@mastra/fastembed'
+import { OracleStore, OracleVector } from '@mastra/oracledb'
+
+const storage = new OracleStore({
+  id: 'oracle-storage',
+  user: process.env.ORACLE_DATABASE_USER,
+  password: process.env.ORACLE_DATABASE_PASSWORD,
+  connectString: process.env.ORACLE_DATABASE_CONNECT_STRING,
+})
+
+const vector = new OracleVector({
+  id: 'oracle-vector',
+  poolManager: storage.getPoolManager(),
+})
+
+export const oracleAgent = new Agent({
+  id: 'oracle-agent',
+  name: 'Oracle Agent',
+  instructions: 'You are an assistant with OracleDB-backed memory and semantic recall.',
+  model: 'openai/gpt-5.6-sol',
+  memory: new Memory({
+    storage,
+    vector,
+    embedder: fastembed,
+    options: {
+      semanticRecall: { topK: 3, messageRange: 2 },
+    },
+  }),
+})
+```
+
+## Related
+
+- [OracleDB storage](https://mastra.ai/reference/storage/oracledb)
+- [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)
+- [Vector databases](https://mastra.ai/guides/rag/vector-databases)

package/.docs/reference/voice/google.md

@@ -109,7 +109,17 @@ Converts speech to text using Google Cloud Speech-to-Text service. Supports both
 
 Pass `v2: true` to use the Cloud Speech-to-Text v2 API, which supports additional audio formats like AAC-in-MP4 (iOS Safari).
 
+The v2 `recognize` call is IAM-authorized and does not accept API-key-only authentication. Configure service account credentials on the `listeningModel` (or set `GOOGLE_APPLICATION_CREDENTIALS`) and set `GOOGLE_CLOUD_PROJECT` so the recognizer path can be resolved, even when `vertexAI` is not enabled.
+
 ```typescript
+import { GoogleVoice } from '@mastra/voice-google'
+
+// v2 listen() requires service account credentials, not just GOOGLE_API_KEY.
+// Set GOOGLE_CLOUD_PROJECT so the recognizer path can be resolved.
+const voice = new GoogleVoice({
+  listeningModel: { keyFilename: process.env.GOOGLE_APPLICATION_CREDENTIALS },
+})
+
 const transcript = await voice.listen(iosSafariAacStream, {
   v2: true,
   config: {
@@ -118,6 +128,8 @@ const transcript = await voice.listen(iosSafariAacStream, {
 })
 ```
 
+> **Note:** `listen({ v2: true })` fails with `PERMISSION_DENIED` on `speech.recognizers.recognize` when only `GOOGLE_API_KEY` is set. An API-key request carries no OAuth identity, so granting `roles/speech.client` to a user account does not help — the role must be granted to the service account presented in the request. This applies regardless of the `vertexAI` setting; `speak()` and v1 `listen()` still work with an API key alone.
+
 **audioStream** (`NodeJS.ReadableStream`): Audio stream to transcribe
 
 **options** (`GoogleListenOptionsV2`): v2 recognition options
@@ -162,7 +174,7 @@ The Google Voice provider supports two authentication methods:
 
 ### Standard Mode (API Key)
 
-Uses a Google Cloud API key for authentication. Suitable for development and basic use cases.
+Uses a Google Cloud API key for authentication. Covers `speak()` and v1 `listen()`. It does not cover `listen({ v2: true })`, which is IAM-authorized and requires service account credentials (see [v2](#v2)).
 
 ```typescript
 // Using environment variable (GOOGLE_API_KEY)
@@ -238,6 +250,8 @@ For Speech-to-Text:
 
 - `roles/speech.client` - Speech-to-Text Client
 
+Grant `roles/speech.client` to the service account whose credentials the request presents (via `keyFilename`, `credentials`, or `GOOGLE_APPLICATION_CREDENTIALS`). This role is required for `listen({ v2: true })` specifically, not only for Vertex AI mode. Granting it to a user account has no effect on API-key-only requests, which carry no identity to authorize.
+
 #### OAuth Scopes
 
 For synchronous Text-to-Speech synthesis:
@@ -269,6 +283,8 @@ For long-audio Text-to-Speech operations:
 
 6. The `listen()` method supports various recognition configurations through the Google Cloud Speech-to-Text API.
 
-7. Available voices can be filtered by language code using the `getSpeakers()` method.
+7. `listen({ v2: true })` requires service account credentials and `GOOGLE_CLOUD_PROJECT`; it fails with `PERMISSION_DENIED` when only `GOOGLE_API_KEY` is set. `speak()` and v1 `listen()` work with an API key alone.
+
+8. Available voices can be filtered by language code using the `getSpeakers()` method.
 
-8. Vertex AI mode provides enterprise features including IAM control, audit logs, and project-level billing.
+9. Vertex AI mode provides enterprise features including IAM control, audit logs, and project-level billing.

package/.docs/reference/workflows/{stored-workflow-definition.md → dynamic-workflow-definition.md}

@@ -1,12 +1,12 @@
 > Discover all available pages from the documentation index: https://mastra.ai/llms.txt
 
-# Stored workflow definition
+# Dynamic workflow definition
 
-> **Beta:** Stored workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Dynamic workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.
 
-A stored workflow definition is a JSON-compatible `StoredWorkflowGraph` accepted by [`Mastra.addStoredWorkflow()`](https://mastra.ai/reference/core/addStoredWorkflow), the stored-workflow server routes, and the Client SDK workflows API.
+A dynamic workflow definition is a JSON-compatible `DynamicWorkflowGraph` accepted by [`Mastra.addDynamicWorkflow()`](https://mastra.ai/reference/core/addDynamicWorkflow), the stored-workflow server routes, and the Client SDK workflows API.
 
-See [Stored workflows](https://mastra.ai/docs/workflows/stored-workflows) for a complete setup and usage example.
+See [Dynamic workflows](https://mastra.ai/docs/workflows/dynamic-workflows) for a complete setup and usage example.
 
 ## Definition fields
 
@@ -286,7 +286,7 @@ Validation errors include a dotted path, such as `graph.2.steps.0`, that identif
 
 ## Related
 
-- [Use stored workflows](https://mastra.ai/docs/workflows/stored-workflows)
-- [`Mastra.addStoredWorkflow()`](https://mastra.ai/reference/core/addStoredWorkflow)
-- [`Mastra.addStoredWorkflows()`](https://mastra.ai/reference/core/addStoredWorkflows)
+- [Use dynamic workflows](https://mastra.ai/docs/workflows/dynamic-workflows)
+- [`Mastra.addDynamicWorkflow()`](https://mastra.ai/reference/core/addDynamicWorkflow)
+- [`Mastra.addDynamicWorkflows()`](https://mastra.ai/reference/core/addDynamicWorkflows)
 - [Client SDK workflows API](https://mastra.ai/reference/client-js/workflows)