@mastra/mcp-docs-server 1.2.15-alpha.9 → 1.2.15

package/.docs/reference/tools/isolated-vm-transport.md

@@ -2,7 +2,7 @@
 
 # IsolatedVmCodeModeTransport
 
-> **Beta:** This feature is in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 The `IsolatedVmCodeModeTransport` class runs [Code mode](https://mastra.ai/docs/agents/code-mode) programs in an in-process V8 isolate, backed by [isolated-vm](https://github.com/laverdet/isolated-vm). The isolate is the execution boundary, so no workspace sandbox is required: the program has no filesystem, network, process, or module access. Its only capabilities are the `external_*` functions, which call back into the real tools on the host.
 

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

@@ -244,6 +244,57 @@ const res = await agent.stream(prompt, {
 })
 ```
 
+### `listToolDefinitions()`
+
+Returns every server's tools as plain, serializable definitions, grouped by server name and keyed by the server's own tool name (without the `serverName_toolName` namespacing that `listTools()` applies).
+
+Unlike `listTools()`, the result contains no functions or references to a live client, so it can be passed through `JSON.stringify` and cached in Redis, a database, or a build artifact. Each definition holds the data from the MCP `tools/list` response (name, description, input schema, output schema, annotations, and `_meta`), plus the server name, version, and instructions captured at discovery time.
+
+```typescript
+const definitions = await mcp.listToolDefinitions()
+
+await cache.set('mcp-tools', JSON.stringify(definitions))
+```
+
+### `listToolDefinitionsWithErrors()`
+
+Like `listToolDefinitions()`, but also returns per-server errors for servers that failed to connect. Use this when caching a catalog, so you don't persist a partial manifest that omits a server that was down at discovery time.
+
+```typescript
+const { definitions, errors } = await mcp.listToolDefinitionsWithErrors()
+
+if (Object.keys(errors).length === 0) {
+  await cache.set('mcp-tools', JSON.stringify(definitions))
+}
+```
+
+### `toolFromDefinition()`
+
+Rebuilds a single executable tool from a cached definition. No connection is opened here. The client connects lazily, the first time the tool is executed.
+
+The returned tool behaves exactly like one from `listTools()`, with the same strict-mode metadata, approval policy, structured content handling, tool error handling, and reconnect behavior.
+
+```typescript
+const definitions = JSON.parse(await cache.get('mcp-tools'))
+
+const tool = await mcp.toolFromDefinition({
+  serverName: 'weather',
+  definition: definitions.weather.getForecast,
+})
+```
+
+### `toolsFromDefinitions()`
+
+Rebuilds an entire cached catalog into a namespaced tool map, without connecting. This is the cached counterpart to `listTools()`. It produces the same `serverName_toolName` keys, so you can reconstruct an agent's tool map on a cold start, and connections only open for the servers whose tools are actually called.
+
+Servers present in the catalog but no longer configured on the client are skipped, so a stale cached manifest degrades gracefully.
+
+```typescript
+const definitions = JSON.parse(await cache.get('mcp-tools'))
+
+new Agent({ id: 'agent', tools: await mcp.toolsFromDefinitions({ definitions }) })
+```
+
 ### `getServerInstructions()`
 
 Returns the instructions currently known for each configured MCP server. Servers that haven't connected yet, or don't advertise instructions, return `undefined`.

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

@@ -929,7 +929,7 @@ Notification methods (`resources.notifyListChanged()`, `prompts.notifyListChange
 
 ## Examples
 
-For practical examples of setting up and deploying an MCPServer, see the [Publishing an MCP Server guide](https://mastra.ai/guides/guide/publishing-mcp-server).
+For a practical example of packaging a stdio server, see [Publish a stdio server package](https://mastra.ai/docs/mcp/overview).
 
 The example at the beginning of this page also demonstrates how to instantiate `MCPServer` with both tools and agents.
 

package/.docs/reference/tools/quickjs-transport.md

@@ -0,0 +1,92 @@
+> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
+
+# QuickJsCodeModeTransport
+
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
+The `QuickJsCodeModeTransport` class runs [Code mode](https://mastra.ai/docs/agents/code-mode) programs in an in-process [QuickJS](https://bellard.org/quickjs/) runtime compiled to WebAssembly. The runtime is the execution boundary, so no workspace sandbox is required: the program has no filesystem, network, process, or module access. Its only capabilities are the `external_*` functions, which call back into the real tools on the host.
+
+Unlike [`IsolatedVmCodeModeTransport`](https://mastra.ai/reference/tools/isolated-vm-transport), this transport installs no native binaries and needs no Node.js flags, so it runs on serverless platforms that disallow both. The tradeoff is speed: see [Choosing a transport](#choosing-a-transport).
+
+## Installation
+
+**npm**:
+
+```bash
+npm install @mastra/quickjs
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/quickjs
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/quickjs
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/quickjs
+```
+
+The package contains the WebAssembly module, so installing it copies files and runs nothing else.
+
+## Usage
+
+Pass the transport as the second argument to `createCodeMode()`. No `sandbox` is needed:
+
+```typescript
+import { createCodeMode } from '@mastra/core/tools'
+import { QuickJsCodeModeTransport } from '@mastra/quickjs'
+
+const { tool, instructions } = createCodeMode(
+  { tools: { getTopProducts, getProductRatings } },
+  new QuickJsCodeModeTransport({ memoryLimitMb: 128 }),
+)
+```
+
+## Constructor parameters
+
+**options** (`QuickJsCodeModeTransportOptions`): Configuration for the QuickJS runtime.
+
+**options.memoryLimitMb** (`number`): Runtime heap limit in MiB. A program that exceeds the limit is terminated and the tool returns an error result.
+
+**options.maxStackSizeBytes** (`number`): Runtime stack limit in bytes. A program that exceeds the limit, usually through runaway recursion, is terminated and the tool returns an error result.
+
+**options.module** (`QuickJSWASMModule`): A preloaded QuickJS WebAssembly module. Supply one to control when the module is loaded, or to share a single module across transports. Loaded on first run when omitted.
+
+## Choosing a transport
+
+All three transports enforce the same allow-list, tool validation, and tracing on the host. They differ in what the program itself can reach and what the host has to provide.
+
+|                     | `StdioCodeModeTransport`       | `IsolatedVmCodeModeTransport`                | `QuickJsCodeModeTransport`  |
+| ------------------- | ------------------------------ | -------------------------------------------- | --------------------------- |
+| Isolation boundary  | Workspace sandbox              | V8 isolate                                   | QuickJS WebAssembly runtime |
+| Requires a sandbox  | Yes                            | No                                           | No                          |
+| Native binary       | Node.js runtime in the sandbox | Yes                                          | No                          |
+| Node.js flags       | None                           | `--no-node-snapshot` on Node.js 20 and later | None                        |
+| Runs in the browser | No                             | No                                           | Yes                         |
+| Execution speed     | Fastest                        | Fast                                         | Slowest                     |
+
+Choose `QuickJsCodeModeTransport` when the host can't install native addons or set Node.js flags, which is common on serverless platforms. Choose `IsolatedVmCodeModeTransport` when the host allows both and programs do heavy computation.
+
+The speed difference is in the program body, not the tool calls. QuickJS interprets rather than JIT-compiles, so a compute-heavy loop can run tens of times slower than in a V8 isolate, while a program that mostly awaits `external_*` calls performs about the same because the time goes to the tools. Code Mode programs are usually the second kind.
+
+## How it works
+
+Each run creates a fresh QuickJS runtime with its own heap. TypeScript is stripped on the host with [ts-blank-space](https://github.com/bloomberg/ts-blank-space), which erases type annotations without a native compiler, then the program is evaluated inside the runtime. Every `external_*` call crosses the boundary as JSON strings in both directions, so no host object references leak into model-authored code.
+
+An `external_*` call returns a pending promise to the program and hands control straight back to the host, so many calls can be in flight at once and `Promise.all` behaves as expected.
+
+The `timeout` configured on `createCodeMode()` applies to both asynchronous hangs and synchronous infinite loops, and the runtime is disposed after every run.
+
+## Related
+
+- [Code mode](https://mastra.ai/docs/agents/code-mode)
+- [createCodeMode() reference](https://mastra.ai/reference/tools/create-code-mode)
+- [IsolatedVmCodeModeTransport reference](https://mastra.ai/reference/tools/isolated-vm-transport)

package/.docs/reference/vectors/chroma.md

@@ -4,7 +4,7 @@
 
 The ChromaVector class provides vector search using [Chroma](https://docs.trychroma.com/docs/overview/getting-started), an open-source embedding database. It offers efficient vector search with metadata filtering and hybrid search capabilities.
 
-> **Info:**
+> **Note:**
 >
 > **Chroma Cloud**
 >

package/.docs/reference/vectors/convex.md

@@ -36,7 +36,7 @@ bun add @mastra/convex@latest
 
 ## Convex setup
 
-Before using `ConvexVector`, you need to set up the Convex schema and storage handler. See [Convex Storage Setup](https://mastra.ai/reference/storage/convex) for setup instructions.
+Before using `ConvexVector`, you need to set up the Convex schema and storage handler. See [Convex Storage Setup](https://mastra.ai/integrations/databases/convex) for setup instructions.
 
 ## Constructor options
 
@@ -419,6 +419,6 @@ Use an external vector database when you need runtime-defined index creation at
 
 ## Related
 
-- [Convex Storage](https://mastra.ai/reference/storage/convex)
+- [Convex Storage](https://mastra.ai/integrations/databases/convex)
 - [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)
 - [Convex Documentation](https://docs.convex.dev/)

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/integrations/databases/oracledb)
+- [Metadata Filters](https://mastra.ai/reference/rag/metadata-filters)
+- [Vector databases](https://mastra.ai/reference/rag/vector-databases)

package/.docs/reference/workers/overview.md

@@ -2,6 +2,8 @@
 
 # Workers
 
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
+
 For usage patterns and deployment topologies, see [Workers](https://mastra.ai/docs/deployment/workers).
 
 ## Environment variables
@@ -75,13 +77,13 @@ Executes background tool calls dispatched by agents.
 
 A deployment running all worker types requires a storage backend that implements the `workflows`, `backgroundTasks`, and `schedules` domains. The `schedules` domain is specifically required by the SchedulerWorker. If you don't use scheduled workflows, backends without it can still support orchestration and background tasks. The following backends support all three:
 
-| Backend    | Package                                                          |
-| ---------- | ---------------------------------------------------------------- |
-| PostgreSQL | [`@mastra/pg`](https://mastra.ai/reference/storage/postgresql)   |
-| LibSQL     | [`@mastra/libsql`](https://mastra.ai/reference/storage/libsql)   |
-| MySQL      | `@mastra/mysql`                                                  |
-| MongoDB    | [`@mastra/mongodb`](https://mastra.ai/reference/storage/mongodb) |
-| Spanner    | [`@mastra/spanner`](https://mastra.ai/reference/storage/spanner) |
-| Convex     | [`@mastra/convex`](https://mastra.ai/reference/storage/convex)   |
+| Backend    | Package                                                               |
+| ---------- | --------------------------------------------------------------------- |
+| PostgreSQL | [`@mastra/pg`](https://mastra.ai/integrations/databases/postgresql)   |
+| LibSQL     | [`@mastra/libsql`](https://mastra.ai/integrations/databases/libsql)   |
+| MySQL      | `@mastra/mysql`                                                       |
+| MongoDB    | [`@mastra/mongodb`](https://mastra.ai/integrations/databases/mongodb) |
+| Spanner    | [`@mastra/spanner`](https://mastra.ai/integrations/databases/spanner) |
+| Convex     | [`@mastra/convex`](https://mastra.ai/integrations/databases/convex)   |
 
 Other storage backends (Upstash, DynamoDB, Cloudflare D1, ClickHouse, Redis) support workflows and some worker features, but are missing the `schedules` domain. They can still be used for orchestration and background task workers if you don't deploy the scheduler.

package/.docs/reference/workflows/dynamic-workflow-definition.md

@@ -2,7 +2,7 @@
 
 # Dynamic workflow definition
 
-> **Beta:** Dynamic workflows are in beta. Breaking changes may occur without a major version bump until the API is stable.
+> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
 
 A 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.
 
@@ -132,6 +132,8 @@ Tool entries accept the same optional `description` and `options` fields as agen
 
 A `mapping` entry reshapes data. Its `mapConfig` is a JSON string that encodes an object. Each key becomes a key in the step output, and each descriptor defines one source.
 
+When you call [`Mastra.addDynamicWorkflow()`](https://mastra.ai/reference/core/addDynamicWorkflow) directly, `mapConfig` also accepts the object itself. Mastra encodes it to a JSON string before registering and storing the definition, so the persisted row is the same either way. A stored definition always carries the JSON string form.
+
 | Descriptor                             | Description                               |
 | -------------------------------------- | ----------------------------------------- |
 | `{ "value": ... }`                     | A constant JSON value                     |

package/.docs/reference/workflows/run-methods/timeTravel.md

@@ -150,6 +150,7 @@ const result = await run.timeTravel({
 - When re-executing a workflow, the workflow loads the existing snapshot from storage (if available)
 - Step results before the target step are reconstructed from the snapshot or provided context
 - Execution begins from the specified step with the provided or reconstructed input data
+- If a step that precedes the target in the current workflow definition has no recorded entry in the snapshot (for example, the step was renamed since the run was recorded, or the run never reached it), `timeTravel` rejects with a descriptive error before anything executes and the stored snapshot is left unchanged
 - The workflow continues to completion from that point forward
 - Time travel can be used on workflows that haven't been run yet by providing custom context or input data for the step to start from.
 

package/.docs/reference/workflows/workflow.md

@@ -127,6 +127,24 @@ export const testWorkflow = createWorkflow({
 
 **options.pruneSnapshot** (`(params: { snapshot: WorkflowRunState; workflowStatus: WorkflowRunStatus }) => WorkflowRunState`): Optional hook to transform the workflow snapshot immediately before it is persisted. Must return JSON-serializable data and preserve everything the workflow needs to resume (suspended step suspendPayloads, suspendedPaths, executionPath, etc.). Used internally by agent runs to keep snapshots minimal; user workflows persist full snapshots by default.
 
+**options.onStart** (`(info: WorkflowStartCallbackInfo) => void | Promise<void>`): Callback awaited before a run starts executing, and before any step runs. Fires only on initial start, not on resume, restart, or time travel. Unlike onFinish and onError, errors thrown here are propagated: they reject the start() or stream() call and the run never executes, so this can be used as a pre-flight gate such as a quota check. The run record created by createRun() stays at status pending.
+
+**options.onStart.runId** (`string`): The workflow run ID
+
+**options.onStart.workflowId** (`string`): The workflow identifier
+
+**options.onStart.resourceId** (`string`): Resource or user identifier for multi-tenant scenarios
+
+**options.onStart.getInitData** (`() => any`): Returns the initial workflow input data
+
+**options.onStart.state** (`Record<string, any>`): The initial workflow state
+
+**options.onStart.requestContext** (`RequestContext`): The request context for the run
+
+**options.onStart.mastra** (`Mastra`): The Mastra instance, when the workflow is registered
+
+**options.onStart.logger** (`IMastraLogger`): The Mastra logger
+
 **options.onFinish** (`(result: WorkflowFinishCallbackResult) => void | Promise<void>`): Callback invoked when workflow completes with any status (success, failed, suspended, tripwire). Receives the workflow result including status, output, error, and step results. Errors thrown in this callback are caught and logged, not propagated.
 
 **options.onFinish.status** (`WorkflowRunStatus`): The workflow status: 'success', 'failed', 'suspended', or 'tripwire'

package/.docs/reference/workspace/local-sandbox.md

@@ -64,7 +64,7 @@ Configuration options for native OS sandboxing (used with `isolation: 'seatbelt'
 
 **readWritePaths** (`string[]`): Additional paths to allow read-write access beyond the workspace directory.
 
-**seatbeltProfilePath** (`string`): Path to a custom seatbelt profile file (macOS only). If the file exists, it's used; if not, a default profile is generated and written to this path.
+**seatbeltProfilePath** (`string`): Path to a custom seatbelt profile file (macOS only). If you wrote the file, it's used exactly as written: Mastra doesn't add mounted paths to it, so the profile must already allow every path you mount. If the file doesn't exist, a default profile is generated and written to this path, and that generated profile allows mounted paths. Mastra marks the profiles it generates, so a later run regenerates them instead of reading them back as your own. To edit a generated profile and keep your edits, delete its marker comment: the file then counts as yours, and mounted paths are no longer added to it.
 
 **bwrapArgs** (`string[]`): Additional arguments to pass to bwrap (Linux only).
 

package/.docs/reference/workspace/platform-filesystem.md

@@ -4,9 +4,9 @@
 
 Stores files in a Mastra Platform workspace bucket. Each Mastra Platform environment can have one bucket, and `PlatformFilesystem` gives agents `read`, `write`, `list`, `delete`, and `move` operations against it.
 
-Related providers: [`S3Filesystem`](https://mastra.ai/reference/workspace/s3-filesystem) for direct S3 access, [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) for local directories.
+Related providers: [`S3Filesystem`](https://mastra.ai/integrations/file-storage/amazon-s3) for direct S3 access, [`LocalFilesystem`](https://mastra.ai/reference/workspace/local-filesystem) for local directories.
 
-> **Info:** For interface details, see [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem).
+> **Note:** For interface details, see [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem).
 
 ## Installation
 
@@ -181,5 +181,5 @@ try {
 ## Related
 
 - [PlatformSandbox reference](https://mastra.ai/reference/workspace/platform-sandbox)
-- [S3Filesystem reference](https://mastra.ai/reference/workspace/s3-filesystem)
+- [S3Filesystem reference](https://mastra.ai/integrations/file-storage/amazon-s3)
 - [WorkspaceFilesystem interface](https://mastra.ai/reference/workspace/filesystem)