@mastra/core 1.7.0 → 1.8.0

package/dist/docs/references/docs-server-middleware.md

@@ -0,0 +1,225 @@
+# Middleware
+
+Mastra servers can execute custom middleware functions before or after an API route handler is invoked. This is useful for things like authentication, logging, injecting request-specific context or adding CORS headers.
+
+A middleware receives the [Hono](https://hono.dev) `Context` (`c`) and a `next` function. If it returns a `Response` the request is short-circuited. Calling `next()` continues processing the next middleware or route handler.
+
+```typescript
+import { Mastra } from '@mastra/core'
+
+export const mastra = new Mastra({
+  server: {
+    middleware: [
+      {
+        handler: async (c, next) => {
+          // Example: Add authentication check
+          const authHeader = c.req.header('Authorization')
+          if (!authHeader) {
+            return new Response('Unauthorized', { status: 401 })
+          }
+
+          await next()
+        },
+        path: '/api/*',
+      },
+      // Add a global request logger
+      async (c, next) => {
+        console.log(`${c.req.method} ${c.req.url}`)
+        await next()
+      },
+    ],
+  },
+})
+```
+
+To attach middleware to a single route pass the `middleware` option to `registerApiRoute`:
+
+```typescript
+registerApiRoute('/my-custom-route', {
+  method: 'GET',
+  middleware: [
+    async (c, next) => {
+      console.log(`${c.req.method} ${c.req.url}`)
+      await next()
+    },
+  ],
+  handler: async c => {
+    const mastra = c.get('mastra')
+    return c.json({ message: 'Hello, world!' })
+  },
+})
+```
+
+## Common examples
+
+### Using `RequestContext`
+
+You can populate `RequestContext` dynamically in server middleware by extracting information from the request. In this example, the `temperature-unit` is set based on the Cloudflare `CF-IPCountry` header to ensure responses match the user's locale.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { RequestContext } from '@mastra/core/request-context'
+import { testWeatherAgent } from './agents/test-weather-agent'
+
+export const mastra = new Mastra({
+  agents: { testWeatherAgent },
+  server: {
+    middleware: [
+      async (context, next) => {
+        const country = context.req.header('CF-IPCountry')
+        const requestContext = context.get('requestContext')
+
+        requestContext.set('temperature-unit', country === 'US' ? 'fahrenheit' : 'celsius')
+
+        await next()
+      },
+    ],
+  },
+})
+```
+
+### Authentication
+
+```typescript
+{
+  handler: async (c, next) => {
+    const authHeader = c.req.header('Authorization');
+    if (!authHeader || !authHeader.startsWith('Bearer ')) {
+      return new Response('Unauthorized', { status: 401 });
+    }
+
+    // Validate token here
+    await next();
+  },
+  path: '/api/*',
+}
+```
+
+### Authorization (User Isolation)
+
+Authentication verifies who the user is. Authorization controls what they can access. Without authorization middleware, an authenticated user could access other users' threads by guessing IDs or manipulating the `resourceId` parameter.
+
+Mastra provides reserved context keys that, when set by middleware, take precedence over client-provided values. The server automatically enforces these keys across memory and agent endpoints:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MASTRA_RESOURCE_ID_KEY } from '@mastra/core/request-context'
+
+export const mastra = new Mastra({
+  server: {
+    auth: {
+      authenticateToken: async token => {
+        // Your auth logic returns the user
+        return verifyToken(token) // { id: 'user-123', ... }
+      },
+    },
+    middleware: [
+      {
+        path: '/api/*',
+        handler: async (c, next) => {
+          const requestContext = c.get('requestContext')
+          const user = requestContext.get('user')
+
+          if (!user) {
+            return c.json({ error: 'Unauthorized' }, 401)
+          }
+
+          // Force all API operations to use this user's ID
+          // This takes precedence over any client-provided resourceId
+          requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id)
+
+          return next()
+        },
+      },
+    ],
+  },
+})
+```
+
+With this middleware, the server automatically:
+
+- **Filters thread listing** to only return threads owned by the user
+- **Validates thread access** and returns 403 if accessing another user's thread
+- **Forces thread creation** to use the authenticated user's ID
+- **Validates message operations** including deletion, ensuring messages belong to owned threads
+
+Even if a client passes `?resourceId=other-user-id`, the middleware-set value takes precedence. Attempts to access threads or messages owned by other users will return a 403 error.
+
+#### Using `MASTRA_THREAD_ID_KEY`
+
+You can also set `MASTRA_THREAD_ID_KEY` to override the client-provided thread ID:
+
+```typescript
+import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY } from '@mastra/core/request-context'
+
+// Force operations to use a specific thread
+requestContext.set(MASTRA_THREAD_ID_KEY, validatedThreadId)
+```
+
+This is useful when you want to restrict operations to a specific thread that you've validated through other means.
+
+### CORS support
+
+```typescript
+{
+  handler: async (c, next) => {
+    c.header('Access-Control-Allow-Origin', '*');
+    c.header(
+      'Access-Control-Allow-Methods',
+      'GET, POST, PUT, DELETE, OPTIONS',
+    );
+    c.header(
+      'Access-Control-Allow-Headers',
+      'Content-Type, Authorization',
+    );
+
+    if (c.req.method === 'OPTIONS') {
+      return new Response(null, { status: 204 });
+    }
+
+    await next();
+  },
+}
+```
+
+### Request logging
+
+```typescript
+{
+  handler: async (c, next) => {
+    const start = Date.now();
+    await next();
+    const duration = Date.now() - start;
+    console.log(`${c.req.method} ${c.req.url} - ${duration}ms`);
+  },
+}
+```
+
+### Special Mastra headers
+
+When integrating with Mastra Cloud or custom clients the following headers can be inspected by middleware to tailor behavior:
+
+```typescript
+{
+  handler: async (c, next) => {
+    const isFromMastraCloud = c.req.header('x-mastra-cloud') === 'true';
+    const clientType = c.req.header('x-mastra-client-type');
+    const isStudio =
+      c.req.header('x-studio') === 'true';
+
+    if (isFromMastraCloud) {
+      // Special handling
+    }
+    await next();
+  },
+}
+```
+
+- `x-mastra-cloud`: request originates from Mastra Cloud
+- `x-mastra-client-type`: identifies the client SDK, e.g. `js` or `python`
+- `x-studio`: request triggered from Studio
+
+# Related
+
+- [Request Context](https://mastra.ai/docs/server/request-context)
+- [Reserved Keys](https://mastra.ai/docs/server/request-context)

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

@@ -0,0 +1,471 @@
+# Request Context
+
+Agents, tools, and workflows can all accept `RequestContext` as a parameter, making request-specific values available to the underlying primitives.
+
+## 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.
+
+> **Note:** **Note:** `RequestContext` is primarily used for passing data into specific requests. It's distinct from agent memory, which handles conversation history and state persistence across multiple calls.
+
+## Setting values
+
+Pass `requestContext` into an agent, network, workflow, or tool call to make values available to all underlying primitives during execution. Use `.set()` to define values before making the call.
+
+The `.set()` method takes two arguments:
+
+1. **key**: The name used to identify the value.
+2. **value**: The data to associate with that key.
+
+```typescript
+import { RequestContext } from '@mastra/core/request-context'
+
+export type UserTier = {
+  'user-tier': 'enterprise' | 'pro'
+}
+
+const requestContext = new RequestContext<UserTier>()
+requestContext.set('user-tier', 'enterprise')
+
+const agent = mastra.getAgent('weatherAgent')
+await agent.generate("What's the weather in London?", {
+  requestContext,
+})
+
+const routingAgent = mastra.getAgent('routingAgent')
+routingAgent.network("What's the weather in London?", {
+  requestContext,
+})
+
+const run = await mastra.getWorkflow('weatherWorkflow').createRun()
+await run.start({
+  inputData: {
+    location: 'London',
+  },
+  requestContext,
+})
+await run.resume({
+  resumeData: {
+    city: 'New York',
+  },
+  requestContext,
+})
+
+await weatherTool.execute({ location: 'London' }, { requestContext })
+```
+
+### Setting values based on request headers
+
+You can populate `requestContext` dynamically in server middleware by extracting information from the request. In this example, the `temperature-unit` is set based on the Cloudflare `CF-IPCountry` header to ensure responses match the user's locale.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { RequestContext } from '@mastra/core/request-context'
+import { testWeatherAgent } from './agents/test-weather-agent'
+
+export const mastra = new Mastra({
+  agents: { testWeatherAgent },
+  server: {
+    middleware: [
+      async (context, next) => {
+        const country = context.req.header('CF-IPCountry')
+        const requestContext = context.get('requestContext')
+
+        requestContext.set('temperature-unit', country === 'US' ? 'fahrenheit' : 'celsius')
+
+        await next()
+      },
+    ],
+  },
+})
+```
+
+> **Info:** Visit [Middleware](https://mastra.ai/docs/server/middleware) for how to use server middleware.
+
+## Accessing values with agents
+
+You can access the `requestContext` argument from any supported configuration options in agents. These functions can be sync or `async`. Use the `.get()` method to read values from `requestContext`.
+
+```typescript
+export type UserTier = {
+  'user-tier': 'enterprise' | 'pro'
+}
+
+export const weatherAgent = new Agent({
+  id: 'weather-agent',
+  name: 'Weather Agent',
+  instructions: async ({ requestContext }) => {
+    const userTier = requestContext.get('user-tier') as UserTier['user-tier']
+
+    if (userTier === 'enterprise') {
+    }
+  },
+  model: ({ requestContext }) => {},
+  tools: ({ requestContext }) => {},
+  memory: ({ requestContext }) => {},
+})
+```
+
+You can also use `requestContext` with other options like `agents`, `workflows`, `scorers`, `inputProcessors`, and `outputProcessors`.
+
+### Dynamic instructions
+
+Agent instructions can be provided as an async function, enabling you to resolve prompts dynamically at runtime. Combined with `requestContext`, this enables patterns like:
+
+- **Personalization**: Tailor instructions based on user attributes, preferences, or tier
+- **Localization**: Adjust tone, language, or behavior based on locale
+- **A/B testing**: Serve different prompt variants for experimentation
+- **External prompt management**: Fetch prompts from registry services without redeploying
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+export const dynamicAgent = new Agent({
+  id: 'dynamic-agent',
+  name: 'Dynamic Agent',
+  instructions: async ({ requestContext }) => {
+    const userTier = requestContext?.get('user-tier')
+    const locale = requestContext?.get('locale')
+
+    // Personalize based on user tier
+    const basePrompt =
+      userTier === 'enterprise'
+        ? 'You are a premium support agent. Provide detailed, thorough responses with technical depth.'
+        : 'You are a helpful assistant. Be concise and friendly.'
+
+    // Localize behavior
+    const localeInstructions = locale === 'ja' ? 'Respond in Japanese using formal keigo.' : ''
+
+    return `${basePrompt} ${localeInstructions}`.trim()
+  },
+  model: 'openai/gpt-5.1',
+})
+```
+
+#### Fetching from a prompt registry
+
+If your organization uses a prompt registry service for central prompt management, you can fetch instructions at runtime. This allows you to update prompts without redeploying, run experiments with variants, and track prompt usage across your agents.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+
+// Your prompt registry client
+import { promptRegistry } from '../lib/prompt-registry'
+
+export const registryAgent = new Agent({
+  id: 'registry-agent',
+  name: 'Registry Agent',
+  instructions: async ({ requestContext }) => {
+    const prompt = await promptRegistry.getPrompt({
+      promptId: 'customer-support-agent',
+      // Pass context for variant selection or tracking
+      variant: requestContext?.get('experiment-variant'),
+      userId: requestContext?.get('user-id'),
+    })
+
+    return prompt.content
+  },
+  model: 'openai/gpt-5.1',
+})
+```
+
+> **Info:** Visit [Agent](https://mastra.ai/reference/agents/agent) for a full list of configuration options.
+
+## Accessing values from workflow steps
+
+You can access the `requestContext` argument from a workflow step's `execute` function. This function can be sync or async. Use the `.get()` method to read values from `requestContext`.
+
+```typescript
+export type UserTier = {
+  'user-tier': 'enterprise' | 'pro'
+}
+
+const stepOne = createStep({
+  id: 'step-one',
+  execute: async ({ requestContext }) => {
+    const userTier = requestContext.get('user-tier') as UserTier['user-tier']
+
+    if (userTier === 'enterprise') {
+    }
+  },
+})
+```
+
+> **Info:** Visit [createStep()](https://mastra.ai/reference/workflows/step) for a full list of configuration options.
+
+## 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`.
+
+```typescript
+export type UserTier = {
+  'user-tier': 'enterprise' | 'pro'
+}
+
+export const weatherTool = createTool({
+  id: 'weather-tool',
+  execute: async (inputData, context) => {
+    const userTier = context?.requestContext?.get('user-tier') as UserTier['user-tier'] | undefined
+
+    if (userTier === 'enterprise') {
+    }
+  },
+})
+```
+
+> **Info:** Visit [createTool()](https://mastra.ai/reference/tools/create-tool) for a full list of configuration options.
+
+## Reserved keys
+
+Mastra reserves special context keys for security purposes. When set by middleware, these keys take precedence over client-provided values. The server automatically validates ownership and returns 403 errors when users attempt to access resources they don't own.
+
+```typescript
+import { MASTRA_RESOURCE_ID_KEY, MASTRA_THREAD_ID_KEY } from '@mastra/core/request-context'
+
+// In middleware: force memory operations to use authenticated user's ID
+requestContext.set(MASTRA_RESOURCE_ID_KEY, user.id)
+
+// In middleware: set validated thread ID
+requestContext.set(MASTRA_THREAD_ID_KEY, threadId)
+```
+
+| Key                      | Purpose                                                                                                                                          |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `MASTRA_RESOURCE_ID_KEY` | Forces all memory operations to use this resource ID. The server validates that accessed threads belong to this resource and returns 403 if not. |
+| `MASTRA_THREAD_ID_KEY`   | Forces thread operations to use this thread ID, overriding client-provided values                                                                |
+
+These keys are used to implement user isolation in multi-tenant applications. See [Authorization middleware](https://mastra.ai/docs/server/middleware) for usage examples.
+
+## 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())
+  }
+}
+```
+
+## Schema validation
+
+Use `requestContextSchema` to define a Zod schema that validates request context values at runtime. This catches missing or invalid context values early, provides clear error messages, and gives you type inference within your component.
+
+### Agent schema validation
+
+When you define `requestContextSchema` on an agent, the context is validated at the start of `generate()` or `stream()`. If validation fails, the agent throws a `MastraError` before any LLM calls are made.
+
+```typescript
+import { Agent } from '@mastra/core/agent'
+import { z } from 'zod'
+
+export const validatedAgent = new Agent({
+  id: 'validated-agent',
+  name: 'Validated Agent',
+  requestContextSchema: z.object({
+    userId: z.string(),
+    apiKey: z.string(),
+  }),
+  instructions: ({ requestContext }) => {
+    // Access all values as a typed object
+    const { userId, apiKey } = requestContext.all
+    // { userId: string; apiKey: string }
+
+    // Or retrieve individual values with .get()
+    const id = requestContext.get('userId')
+    // string
+
+    return `You are helping user ${userId}`
+  },
+  model: 'openai/gpt-4o',
+})
+```
+
+When validation fails, the error includes the agent ID and details about which fields failed:
+
+```text
+Request context validation failed for agent 'validated-agent':
+- apiKey: Required
+```
+
+### Tool schema validation
+
+When you define `requestContextSchema` on a tool, the context is validated before `execute()` runs. Unlike agents, tools return a validation error object instead of throwing:
+
+```typescript
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+
+export const validatedTool = createTool({
+  id: 'validated-tool',
+  description: 'A tool that requires authenticated context',
+  inputSchema: z.object({
+    query: z.string(),
+  }),
+  requestContextSchema: z.object({
+    userId: z.string(),
+  }),
+  execute: async (inputData, context) => {
+    // Access all values as a typed object
+    const { userId } = context.requestContext?.all ?? {}
+    // { userId: string }
+
+    // Or retrieve individual values with .get()
+    const id = context.requestContext?.get('userId')
+    // string | undefined
+
+    return { result: `Processed for ${userId}` }
+  },
+})
+```
+
+When validation fails, the tool returns an error object instead of throwing:
+
+```json
+{
+  "error": true,
+  "message": "Request context validation failed for validated-tool. Please fix the following errors and try again:\n- userId: Required\n\nProvided context: {}"
+}
+```
+
+### Workflow schema validation
+
+When you define `requestContextSchema` on a workflow, the context is validated at the start of `run.start()`. If validation fails, the workflow throws an error before any steps execute.
+
+```typescript
+import { createWorkflow, createStep } from '@mastra/core/workflows'
+import { z } from 'zod'
+
+// Define schema once and share between workflow and steps
+const workflowContextSchema = z.object({
+  tenantId: z.string(),
+})
+
+const step1 = createStep({
+  id: 'step-1',
+  inputSchema: z.object({ message: z.string() }),
+  outputSchema: z.object({ result: z.string() }),
+  // Add schema to step for type inference
+  requestContextSchema: workflowContextSchema,
+  execute: async ({ inputData, requestContext }) => {
+    // Access all values as a typed object
+    const { tenantId } = requestContext.all
+    // { tenantId: string }
+
+    // Or retrieve individual values with .get()
+    const id = requestContext.get('tenantId')
+    // string
+
+    return { result: `Processed for tenant ${tenantId}` }
+  },
+})
+
+export const validatedWorkflow = createWorkflow({
+  id: 'validated-workflow',
+  inputSchema: z.object({ message: z.string() }),
+  outputSchema: z.object({ result: z.string() }),
+  requestContextSchema: workflowContextSchema,
+})
+  .then(step1)
+  .commit()
+```
+
+When validation fails, the workflow throws an error:
+
+```text
+Request context validation failed for workflow 'validated-workflow':
+- tenantId: Required
+```
+
+Steps can also define their own `requestContextSchema` for step-level validation. Step validation runs before the step's `execute()` function.
+
+### Validation behavior
+
+| Component | Property               | Validation timing                  | On failure            |
+| --------- | ---------------------- | ---------------------------------- | --------------------- |
+| Agent     | `requestContextSchema` | Start of `generate()` / `stream()` | Throws `MastraError`  |
+| Tool      | `requestContextSchema` | Before `execute()`                 | Returns error object  |
+| Workflow  | `requestContextSchema` | Start of `run.start()`             | Throws `Error`        |
+| Step      | `requestContextSchema` | Before step `execute()`            | Step fails with error |
+
+### Best practices
+
+**Match your middleware**: Define the same required fields in your schema that your middleware sets. This ensures the contract between middleware and components is explicit and validated.
+
+```typescript
+// Middleware sets these fields
+requestContext.set('userId', user.id)
+requestContext.set('tenantId', tenant.id)
+
+// Schema validates they exist
+requestContextSchema: z.object({
+  userId: z.string(),
+  tenantId: z.string(),
+})
+```
+
+**Use optional fields for conditional context**: Use `.optional()` for values that may not always be present.
+
+```typescript
+requestContextSchema: z.object({
+  userId: z.string(), // Always required
+  experimentVariant: z.string().optional(), // May not be set
+})
+```
+
+**Handle tool validation errors**: Since tools return error objects instead of throwing, check for errors in your agent or workflow logic when tool execution is critical.
+
+## Testing with Studio presets
+
+When developing locally, you can define named presets in a JSON file and load them into Studio with the [`--request-context-presets`](https://mastra.ai/reference/cli/mastra) CLI flag. This adds a dropdown to the request context editor in Studio so you can quickly switch between configurations without manually editing JSON each time.
+
+```bash
+mastra dev --request-context-presets ./presets.json
+```
+
+```json
+{
+  "development": { "userId": "dev-user", "env": "development" },
+  "production": { "userId": "prod-user", "env": "production" }
+}
+```
+
+When you select a preset from the dropdown, the JSON editor populates with that preset's values. Editing the JSON manually switches the dropdown back to "Custom".
+
+## Related
+
+- [Agent Request Context](https://mastra.ai/docs/agents/overview)
+- [Workflow Request Context](https://mastra.ai/docs/workflows/overview)
+- [Server Middleware](https://mastra.ai/docs/server/middleware)
+- [Authorization Middleware](https://mastra.ai/docs/server/middleware)