@mastra/core 1.0.0-beta.21 → 1.0.0-beta.22

package/dist/docs/observability/{13-reference.md → 15-reference.md}

@@ -1,6 +1,6 @@
 # Observability API Reference
 
-> API reference for observability - 7 entries
+> API reference for observability - 8 entries
 
 
 ---
@@ -144,6 +144,118 @@ This format ensures compatibility with all OTEL-compatible backends and collecto
 
 ---
 
+## Reference: DatadogExporter
+
+> Datadog LLM Observability exporter for Tracing
+
+Sends Tracing data to Datadog's LLM Observability product for monitoring and analytics.
+
+## Constructor
+
+```typescript
+new DatadogExporter(config: DatadogExporterConfig)
+```
+
+## DatadogExporterConfig
+
+```typescript
+interface DatadogExporterConfig extends BaseExporterConfig {
+  apiKey?: string;
+  mlApp?: string;
+  site?: string;
+  service?: string;
+  env?: string;
+  agentless?: boolean;
+  integrationsEnabled?: boolean;
+}
+```
+
+Extends `BaseExporterConfig`, which includes:
+- `logger?: IMastraLogger` - Logger instance
+- `logLevel?: LogLevel | 'debug' | 'info' | 'warn' | 'error'` - Log level (default: INFO)
+
+## Methods
+
+### exportTracingEvent
+
+```typescript
+async exportTracingEvent(event: TracingEvent): Promise<void>
+```
+
+Exports a tracing event to Datadog LLM Observability.
+
+### shutdown
+
+```typescript
+async shutdown(): Promise<void>
+```
+
+Flushes pending data and shuts down the exporter. Cancels any pending cleanup timers and disables LLM Observability.
+
+## Usage
+
+### Zero-Config (using environment variables)
+
+```typescript
+import { DatadogExporter } from "@mastra/datadog";
+
+// Reads from DD_LLMOBS_ML_APP, DD_API_KEY, DD_SITE, DD_ENV
+const exporter = new DatadogExporter();
+```
+
+### Explicit Configuration
+
+```typescript
+import { DatadogExporter } from "@mastra/datadog";
+
+const exporter = new DatadogExporter({
+  mlApp: "my-llm-app",
+  apiKey: process.env.DD_API_KEY,
+  site: "datadoghq.com",
+  env: "production",
+});
+```
+
+### With Local Datadog Agent
+
+```typescript
+const exporter = new DatadogExporter({
+  mlApp: "my-llm-app",
+  agentless: false, // Use local Datadog Agent
+  env: "production",
+});
+```
+
+## Span Mapping
+
+Mastra span types are mapped to Datadog LLMObs span kinds:
+
+| Mastra SpanType | Datadog Kind |
+|-----------------|--------------|
+| `AGENT_RUN` | `agent` |
+| `MODEL_GENERATION` | `workflow` |
+| `MODEL_STEP` | `llm` |
+| `TOOL_CALL` | `tool` |
+| `MCP_TOOL_CALL` | `tool` |
+| `WORKFLOW_RUN` | `workflow` |
+| All other types | `task` |
+
+All unmapped span types (including `MODEL_CHUNK`, `WORKFLOW_STEP`, `GENERIC`, and future span types) automatically default to `task`.
+
+## Environment Variables
+
+The exporter reads configuration from these environment variables:
+
+| Variable | Description |
+|----------|-------------|
+| `DD_API_KEY` | Datadog API key |
+| `DD_LLMOBS_ML_APP` | ML application name |
+| `DD_SITE` | Datadog site |
+| `DD_ENV` | Environment name |
+| `DD_LLMOBS_AGENTLESS_ENABLED` | Set to 'false' or '0' to use local agent |
+
+---
+
 ## Reference: SensitiveDataFilter
 
 > API reference for the SensitiveDataFilter processor
@@ -1305,6 +1417,18 @@ interface TracingOptions {
    * Note: Tags are only applied to the root span of a trace.
    */
   tags?: string[];
+
+  /**
+   * When true, input data will be hidden from all spans in this trace.
+   * Useful for protecting sensitive data from being logged.
+   */
+  hideInput?: boolean;
+
+  /**
+   * When true, output data will be hidden from all spans in this trace.
+   * Useful for protecting sensitive data from being logged.
+   */
+  hideOutput?: boolean;
 }
 ```
 

package/dist/docs/processors/01-reference.md

@@ -87,6 +87,7 @@ import { Agent } from "@mastra/core/agent";
 import { LanguageDetector } from "@mastra/core/processors";
 
 export const agent = new Agent({
+  id: "multilingual-agent",
   name: "multilingual-agent",
   instructions: "You are a helpful assistant",
   model: "openai/gpt-5.1",
@@ -827,6 +828,25 @@ const processor = new TokenLimiterProcessor({
 
 ## Returns
 
+## Error behavior
+
+When used as an input processor, `TokenLimiterProcessor` throws a `TripWire` error in the following cases:
+
+- **Empty messages**: If there are no messages to process, a TripWire is thrown because you cannot send an LLM request with no messages.
+- **System messages exceed limit**: If system messages alone exceed the token limit, a TripWire is thrown because you cannot send an LLM request with only system messages and no user/assistant messages.
+
+```typescript
+import { TripWire } from "@mastra/core/agent";
+
+try {
+  await agent.generate("Hello");
+} catch (error) {
+  if (error instanceof TripWire) {
+    console.log("Token limit error:", error.message);
+  }
+}
+```
+
 ## Extended usage example
 
 ### As an input processor (limit context window)
@@ -907,6 +927,7 @@ import { Agent } from "@mastra/core/agent";
 import { UnicodeNormalizer } from "@mastra/core/processors";
 
 export const agent = new Agent({
+  id: "normalized-agent",
   name: "normalized-agent",
   instructions: "You are a helpful assistant",
   model: "openai/gpt-5.1",
@@ -1039,10 +1060,12 @@ import { PgVector } from "@mastra/pg";
 import { openai } from "@ai-sdk/openai";
 
 const storage = new PostgresStorage({
+  id: 'pg-storage',
   connectionString: process.env.DATABASE_URL,
 });
 
 const vector = new PgVector({
+  id: 'pg-vector',
   connectionString: process.env.DATABASE_URL,
 });
 

package/dist/docs/rag/01-overview.md

@@ -1,7 +1,7 @@
 > Overview of Retrieval-Augmented Generation (RAG) in Mastra, detailing its capabilities for enhancing LLM outputs with relevant context.
 
 > **Code References:**
-- `ModelRouterEmbeddingModel`: dist/llm/index.d.ts → dist/chunk-FT7DFPAL.js:4790
+- `ModelRouterEmbeddingModel`: dist/llm/index.d.ts → dist/chunk-YYNZEEOO.js:4790
 
 # RAG (Retrieval-Augmented Generation) in Mastra
 

package/dist/docs/rag/02-chunking-and-embedding.md

@@ -51,7 +51,6 @@ const chunks = await doc.chunk({
   minSize: 50,
   overlap: 0,
   sentenceEnders: ["."],
-  keepSeparator: true,
 });
 ```
 

package/dist/docs/rag/03-vector-databases.md

@@ -12,6 +12,7 @@ After generating embeddings, you need to store them in a database that supports
 import { MongoDBVector } from "@mastra/mongodb";
 
 const store = new MongoDBVector({
+  id: 'mongodb-vector',
   uri: process.env.MONGODB_URI,
   dbName: process.env.MONGODB_DATABASE,
 });
@@ -144,6 +145,7 @@ await store.upsert({
 import { AstraVector } from "@mastra/astra";
 
 const store = new AstraVector({
+  id: 'astra-vector',
   token: process.env.ASTRA_DB_TOKEN,
   endpoint: process.env.ASTRA_DB_ENDPOINT,
   keyspace: process.env.ASTRA_DB_KEYSPACE,
@@ -170,7 +172,7 @@ import { LibSQLVector } from "@mastra/core/vector/libsql";
 
 const store = new LibSQLVector({
   id: 'libsql-vector',
-  connectionUrl: process.env.DATABASE_URL,
+  url: process.env.DATABASE_URL,
   authToken: process.env.DATABASE_AUTH_TOKEN, // Optional: for Turso cloud databases
 });
 
@@ -217,6 +219,7 @@ await store.upsert({
 import { CloudflareVector } from "@mastra/vectorize";
 
 const store = new CloudflareVector({
+  id: 'cloudflare-vector',
   accountId: process.env.CF_ACCOUNT_ID,
   apiToken: process.env.CF_API_TOKEN,
 });
@@ -238,7 +241,7 @@ await store.upsert({
 ```ts title="vector-store.ts"
 import { OpenSearchVector } from "@mastra/opensearch";
 
-const store = new OpenSearchVector({ url: process.env.OPENSEARCH_URL });
+const store = new OpenSearchVector({ id: "opensearch", node: process.env.OPENSEARCH_URL });
 
 await store.createIndex({
   indexName: "my-collection",
@@ -259,7 +262,7 @@ await store.upsert({
 ```ts title="vector-store.ts"
 import { ElasticSearchVector } from "@mastra/elasticsearch";
 
-const store = new ElasticSearchVector({ url: process.env.ELASTICSEARCH_URL });
+const store = new ElasticSearchVector({ id: 'elasticsearch-vector', url: process.env.ELASTICSEARCH_URL });
 
 await store.createIndex({
   indexName: "my-collection",
@@ -280,6 +283,7 @@ await store.upsert({
 import { CouchbaseVector } from "@mastra/couchbase";
 
 const store = new CouchbaseVector({
+  id: 'couchbase-vector',
   connectionString: process.env.COUCHBASE_CONNECTION_STRING,
   username: process.env.COUCHBASE_USERNAME,
   password: process.env.COUCHBASE_PASSWORD,
@@ -331,6 +335,7 @@ For detailed setup instructions and best practices, see the [official LanceDB do
 import { S3Vectors } from "@mastra/s3vectors";
 
 const store = new S3Vectors({
+  id: 's3-vectors',
   vectorBucketName: "my-vector-bucket",
   clientConfig: {
     region: "us-east-1",
@@ -373,7 +378,7 @@ The dimension size must match the output dimension of your chosen embedding mode
 - Cohere embed-multilingual-v3: 1024 dimensions
 - Google text-embedding-004: 768 dimensions (or custom)
 
-important
+> **Note:**
 Index dimensions cannot be changed after creation. To use a different model, delete and recreate the index with the new dimension size.
 
 ### Naming Rules for Databases
@@ -537,7 +542,7 @@ The upsert operation:
 
 Vector stores support rich metadata (any JSON-serializable fields) for filtering and organization. Since metadata is stored with no fixed schema, use consistent field naming to avoid unexpected query results.
 
-important
+> **Note:**
 Metadata is crucial for vector storage - without it, you'd only have numerical embeddings with no way to return the original text or filter results. Always store at least the source text as metadata.
 
 ```ts

package/dist/docs/rag/04-retrieval.md

@@ -171,7 +171,7 @@ The Vector Query Tool supports database-specific configurations that enable you
 > **Note:**
 These configurations are for **query-time options** like namespaces, performance tuning, and filtering—not for database connection setup. 
 
-Connection credentials (URLs, auth tokens) are configured when you instantiate the vector store class (e.g., `new LibSQLVector({ connectionUrl: '...' })`).
+Connection credentials (URLs, auth tokens) are configured when you instantiate the vector store class (e.g., `new LibSQLVector({ url: '...' })`).
 
 ```ts
 import { createVectorQueryTool } from "@mastra/rag";
@@ -258,11 +258,10 @@ requestContext.set("databaseConfig", {
   },
 });
 
-await pineconeQueryTool.execute({
-  context: { queryText: "search query" },
-  mastra,
-  requestContext,
-});
+await pineconeQueryTool.execute(
+  { queryText: "search query" },
+  { mastra, requestContext }
+);
 ```
 
 For detailed configuration options and advanced usage, see the [Vector Query Tool Reference](https://mastra.ai/reference/v1/tools/vector-query-tool).

package/dist/docs/rag/06-reference.md

@@ -129,11 +129,10 @@ whereDocument: { "$contains": "API documentation" }
       }
     });
 
-    await vectorTool.execute({
-      context: { queryText: 'search query' },
-      mastra,
-      requestContext
-    });
+    await vectorTool.execute(
+      { queryText: 'search query' },
+      { mastra, requestContext }
+    );
     ```
 
   

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

@@ -1,12 +1,12 @@
-> Configure the Mastra server with custom settings for port, timeout, CORS, and more.
+> Overview of the Mastra server, covering HTTP endpoints, middleware, authentication, and client integration.
 
-# Server Configuration
+# Server Overview
 
-When deploying your Mastra application to production, it runs as an HTTP server that exposes your agents, workflows, and other functionality as API endpoints. This page covers how to configure and customize the server for a production environment.
+Mastra runs as an HTTP server that exposes your agents, workflows, and other functionality as API endpoints. The server handles request routing, middleware execution, authentication, and streaming responses.
 
 > **Note:**
 
-This page covers the `server` configuration options passed to the `Mastra` constructor. For running Mastra with your own HTTP server (Hono, Express, etc.), see [Server Adapters](https://mastra.ai/docs/v1/server/server-adapters).
+This page covers the [`server`](https://mastra.ai/reference/v1/configuration#server-options) configuration options passed to the `Mastra` constructor. For running Mastra with your own HTTP server (Hono, Express, etc.), visit [Server Adapters](https://mastra.ai/docs/v1/server/server-adapters).
 
 ## Server architecture
 
@@ -14,21 +14,15 @@ Mastra uses [Hono](https://hono.dev) as its underlying HTTP server framework. Wh
 
 The server provides:
 
-- API endpoints for all registered agents
-- API endpoints for all registered workflows
-- Custom API route support
-- Custom middleware support
-- Configuration of timeout
-- Configuration of port
-- Configuration of body limit
+- API endpoints for all registered agents and workflows
+- Custom API routes and middleware
+- Authentication with multiple providers
+- Request context for dynamic configuration
+- Stream data redaction for secure responses
 
-See the [Middleware](https://mastra.ai/docs/v1/server/middleware) and
-[Custom API Routes](https://mastra.ai/docs/v1/server/custom-api-routes) pages for details on
-adding additional server behaviour.
+## Configuration
 
-## Server configuration
-
-You can configure server `port`, `host`, `studioBase`, and `timeout` in the Mastra instance.
+Configure the server by passing a `server` object to the `Mastra` constructor:
 
 ```typescript title="src/mastra/index.ts"
 import { Mastra } from "@mastra/core";
@@ -37,17 +31,33 @@ export const mastra = new Mastra({
   server: {
     port: 3000, // Defaults to 4111
     host: "0.0.0.0", // Defaults to 'localhost'
-    studioBase: "/my-mastra-studio", // Sub-path for the studio (optional)
-    timeout: 10000, // Defaults to 3 * 60 * 1000 (3 minutes)
   },
 });
 ```
 
-The `studioBase` option allows you to host Mastra Studio on a sub-path of your existing application. For example, with `studioBase: "/my-mastra-studio"`, the studio will be available at `http://your-host:port/my-mastra-studio` instead of the root.
+> **Note:**
+
+Visit the [configuration reference](https://mastra.ai/reference/v1/configuration#server-options) for a full list of available server options.
+
+## Server features
+
+- **[Middleware](https://mastra.ai/docs/v1/server/middleware)**: Intercept requests for authentication, logging, CORS, or injecting request-specific context.
+- **[Custom API Routes](https://mastra.ai/docs/v1/server/custom-api-routes)**: Extend the server with your own HTTP endpoints that have access to the Mastra instance.
+- **[Request Context](https://mastra.ai/docs/v1/server/request-context)**: Pass request-specific values to agents, tools, and workflows based on runtime conditions.
+- **[Server Adapters](https://mastra.ai/docs/v1/server/server-adapters)**: Run Mastra with Express, Hono, or your own HTTP server instead of the generated server.
+- **[Custom Adapters](https://mastra.ai/docs/v1/server/custom-adapters)**: Build adapters for frameworks not officially supported.
+- **[Mastra Client SDK](https://mastra.ai/docs/v1/server/mastra-client)**: Type-safe client for calling agents, workflows, and tools from browser or server environments.
+- **[Authentication](https://mastra.ai/docs/v1/server/auth)**: Secure endpoints with JWT, Clerk, Supabase, Firebase, Auth0, or WorkOS.
+
+## Stream data redaction
+
+When streaming agent responses, the HTTP layer redacts system prompts, tool definitions, API keys, and similar data from each chunk before sending it to clients. This is enabled by default.
+
+This behavior is only configurable by using [server adapters](https://mastra.ai/docs/v1/server/server-adapters#stream-data-redaction). For server adapters, stream data redaction is enabled by default, too.
 
 ## TypeScript configuration
 
-Mastra requires `module` and `moduleResolution` values that support modern Node.js versions. Older settings like `CommonJS` or `node` are incompatible with Mastra’s packages and will cause resolution errors.
+Mastra requires `module` and `moduleResolution` settings compatible with modern Node.js. Legacy options like `CommonJS` or `node` are not supported.
 
 ```json {4-5} title="tsconfig.json"
 {
@@ -64,31 +74,4 @@ Mastra requires `module` and `moduleResolution` values that support modern Node.
   },
   "include": ["src/**/*"]
 }
-```
-
-> This TypeScript configuration is optimized for Mastra projects, using modern module resolution and strict type checking.
-
-## CORS configuration
-
-Mastra allows you to configure CORS (Cross-Origin Resource Sharing) settings for your server.
-
-```typescript title="src/mastra/index.ts"
-import { Mastra } from "@mastra/core";
-
-export const mastra = new Mastra({
-  server: {
-    cors: {
-      origin: ["https://example.com"], // Allow specific origins or '*' for all
-      allowMethods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
-      allowHeaders: ["Content-Type", "Authorization"],
-      credentials: false,
-    },
-  },
-});
-```
-
-## Stream data redaction
-
-When streaming agent responses, the HTTP streaming layer redacts system prompts, tool definitions, API keys, and similar data from each chunk before sending it to clients. This is enabled by default.
-
-If you're using server adapters directly, you can configure redaction behavior. See [Stream data redaction](https://mastra.ai/docs/v1/server/server-adapters#stream-data-redaction) in the Server Adapters docs.
+```

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

@@ -8,9 +8,12 @@ A custom adapter translates between Mastra's route definitions and your framewor
 
 > **Note:**
 
-For Hono or Express, use the provided adapters instead:
+Use any of these prebuilt server adapters:
+
 - [@mastra/hono](https://mastra.ai/reference/v1/server/hono-adapter)
 - [@mastra/express](https://mastra.ai/reference/v1/server/express-adapter)
+- [@mastra/fastify](https://mastra.ai/reference/v1/server/fastify-adapter)
+- [@mastra/koa](https://mastra.ai/reference/v1/server/koa-adapter)
 
 ## Abstract class
 
@@ -289,7 +292,7 @@ constructor(options: {
 }
 ```
 
-See [Server Adapters](https://mastra.ai/docs/v1/server/server-adapters#constructor-options) for full documentation on each option.
+See [Server Adapters](https://mastra.ai/docs/v1/server/server-adapters) for full documentation on each option.
 
 ## Full example
 

package/dist/docs/server/04-request-context.md

@@ -6,7 +6,7 @@ Agents, tools, and workflows can all accept `RequestContext` as a parameter, mak
 
 ## When to use `RequestContext`
 
-Use `RequestContext` when a primitive’s behavior should change based on runtime conditions. For example, you might switch models or storage backends based on user attributes, or adjust instructions and tool selection based on language.
+Use `RequestContext` when a primitive's behavior should change based on runtime conditions. For example, you might switch models or storage backends based on user attributes, or adjust instructions and tool selection based on language.
 
 > **Note:**
 
@@ -57,12 +57,10 @@ await run.resume({
   requestContext,
 });
 
-await weatherTool.execute({
-  context: {
-    location: "London",
-  },
-  requestContext,
-});
+await weatherTool.execute(
+  { location: "London" },
+  { requestContext },
+);
 ```
 
 ### Setting values based on request headers
@@ -152,7 +150,7 @@ Visit [createStep()](https://mastra.ai/reference/v1/workflows/step) for a full l
 
 ## Accessing values with tools
 
-You can access the `requestContext` argument from a tool’s `execute` function. This function is `async`. Use the `.get()` method to read values from `requestContext`.
+You can access the `requestContext` argument from a tool's `execute` function. This function is `async`. Use the `.get()` method to read values from `requestContext`.
 
 ```typescript title="src/mastra/tools/weather-tool.ts"
 export type UserTier = {
@@ -161,8 +159,8 @@ export type UserTier = {
 
 export const weatherTool = createTool({
   id: "weather-tool",
-  execute: async ({ requestContext }) => {
-    const userTier = requestContext.get("user-tier") as UserTier["user-tier"];
+  execute: async (inputData, context) => {
+    const userTier = context?.requestContext?.get("user-tier") as UserTier["user-tier"] | undefined;
 
     if (userTier === "enterprise") {}
   },
@@ -173,9 +171,50 @@ export const weatherTool = createTool({
 
 Visit [createTool()](https://mastra.ai/reference/v1/tools/create-tool) for a full list of configuration options.
 
+## TypeScript support
+
+When you provide a type parameter to `RequestContext`, all methods are fully typed:
+
+```typescript
+import { RequestContext } from "@mastra/core/request-context";
+
+type MyContext = {
+  userId: string;
+  maxTokens: number;
+  isPremium: boolean;
+};
+
+const ctx = new RequestContext<MyContext>();
+
+// set() enforces correct value types
+ctx.set("userId", "user-123");   // ✓ valid
+ctx.set("maxTokens", 4096);      // ✓ valid
+ctx.set("maxTokens", "wrong");   // ✗ TypeScript error: expected number
+
+// get() returns the correct type automatically
+const tokens = ctx.get("maxTokens"); // inferred as number
+const id = ctx.get("userId");        // inferred as string
+
+// keys() returns typed keys
+for (const key of ctx.keys()) {
+  // key is "userId" | "maxTokens" | "isPremium"
+}
+
+// entries() supports type narrowing
+for (const [key, value] of ctx.entries()) {
+  if (key === "maxTokens") {
+    // TypeScript knows value is number here
+    console.log(value.toFixed(2));
+  }
+  if (key === "userId") {
+    // TypeScript knows value is string here
+    console.log(value.toUpperCase());
+  }
+}
+```
+
 ## Related
 
 - [Agent Request Context](https://mastra.ai/docs/v1/agents/overview#using-requestcontext)
 - [Workflow Request Context](../workflows/overview#using-requestcontext)
-- [Tool Request Context](../mcp/overview#using-requestcontext)
 - [Server Middleware](https://mastra.ai/docs/v1/server/middleware)

package/dist/docs/server/05-custom-api-routes.md

@@ -17,7 +17,7 @@ export const mastra = new Mastra({
         method: "GET",
         handler: async (c) => {
           const mastra = c.get("mastra");
-          const agents = await mastra.getAgent("my-agent");
+          const agent = await mastra.getAgent("my-agent");
 
           return c.json({ message: "Custom route" });
         },

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

@@ -102,7 +102,7 @@ const testAgent = async () => {
 
 > **Note:**
 
-Visit [.generate()](https://mastra.ai/reference/v1/client-js/agents#generate-response) for more information.
+Visit [.generate()](https://mastra.ai/reference/v1/client-js/agents#generate) for more information.
 
 ## Streaming responses
 
@@ -137,7 +137,7 @@ const testAgent = async () => {
 
 > **Note:**
 
-Visit [.stream()](https://mastra.ai/reference/v1/client-js/agents#stream-response) for more information.
+Visit [.stream()](https://mastra.ai/reference/v1/client-js/agents#stream) for more information.
 
 ## Configuration options