@mastra/mcp-docs-server 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

package/.docs/reference/ai-sdk/to-ai-sdk-stream.md

@@ -0,0 +1,231 @@
+# toAISdkStream()
+
+Converts Mastra streams (agent, network, or workflow) to AI SDK-compatible streams. Use this function when you need to manually transform Mastra streams for use with AI SDK's `createUIMessageStream()` and `createUIMessageStreamResponse()`.
+
+This is useful when building custom streaming endpoints outside Mastra's provided route helpers such as [`chatRoute()`](https://mastra.ai/reference/ai-sdk/chat-route) or [`workflowRoute()`](https://mastra.ai/reference/ai-sdk/workflow-route).
+
+## Usage example
+
+Next.js App Router example:
+
+```typescript
+import { mastra } from '../../mastra'
+import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'
+import { toAISdkStream } from '@mastra/ai-sdk'
+
+export async function POST(req: Request) {
+  const { messages } = await req.json()
+  const myAgent = mastra.getAgent('weatherAgent')
+  const stream = await myAgent.stream(messages)
+
+  const uiMessageStream = createUIMessageStream({
+    originalMessages: messages,
+    execute: async ({ writer }) => {
+      for await (const part of toAISdkStream(stream, { from: 'agent' })) {
+        await writer.write(part)
+      }
+    },
+  })
+
+  return createUIMessageStreamResponse({
+    stream: uiMessageStream,
+  })
+}
+```
+
+> **Tip:** Pass `messages` to `originalMessages` in `createUIMessageStream()` to avoid duplicated assistant messages in the UI. See [Troubleshooting: Repeated Assistant Messages](https://ai-sdk.dev/docs/troubleshooting/repeated-assistant-messages) for details.
+
+## Parameters
+
+The first parameter is the Mastra stream to convert. It can be one of:
+
+- `MastraModelOutput` - An agent stream from `agent.stream()`
+- `MastraAgentNetworkStream` - A network stream from `agent.network()`
+- `MastraWorkflowStream` or `WorkflowRunOutput` - A workflow stream
+
+The second parameter is an options object:
+
+**from:** (`'agent' | 'network' | 'workflow'`): The type of Mastra stream being converted. (Default: `'agent'`)
+
+**lastMessageId?:** (`string`): (Agent only) The ID of the last message in the conversation.
+
+**sendStart?:** (`boolean`): (Agent only) Whether to send start events in the stream. (Default: `true`)
+
+**sendFinish?:** (`boolean`): (Agent only) Whether to send finish events in the stream. (Default: `true`)
+
+**sendReasoning?:** (`boolean`): (Agent only) Whether to include reasoning-delta chunks in the stream. Set to true to stream reasoning content from models that support extended thinking. (Default: `false`)
+
+**sendSources?:** (`boolean`): (Agent only) Whether to include source citations in the output. (Default: `false`)
+
+**includeTextStreamParts?:** (`boolean`): (Workflow only) Whether to include text stream parts in the output. (Default: `true`)
+
+**messageMetadata?:** (`(options: { part: UIMessageStreamPart }) => Record<string, unknown> | undefined`): (Agent only) A function that receives the current stream part and returns metadata to attach to start and finish chunks.
+
+**onError?:** (`(error: unknown) => string`): (Agent only) A function to handle errors during stream conversion. Receives the error and should return a string representation.
+
+## Examples
+
+### Converting a workflow stream
+
+```typescript
+import { mastra } from '../../mastra'
+import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'
+import { toAISdkStream } from '@mastra/ai-sdk'
+
+export async function POST(req: Request) {
+  const { input } = await req.json()
+  const workflow = mastra.getWorkflow('myWorkflow')
+  const run = workflow.createRun()
+  const stream = await run.stream({ inputData: input })
+
+  const uiMessageStream = createUIMessageStream({
+    execute: async ({ writer }) => {
+      for await (const part of toAISdkStream(stream, { from: 'workflow' })) {
+        await writer.write(part)
+      }
+    },
+  })
+
+  return createUIMessageStreamResponse({
+    stream: uiMessageStream,
+  })
+}
+```
+
+### Converting a network stream
+
+```typescript
+import { mastra } from '../../mastra'
+import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'
+import { toAISdkStream } from '@mastra/ai-sdk'
+
+export async function POST(req: Request) {
+  const { messages } = await req.json()
+  const routingAgent = mastra.getAgent('routingAgent')
+  const stream = await routingAgent.network(messages)
+
+  const uiMessageStream = createUIMessageStream({
+    execute: async ({ writer }) => {
+      for await (const part of toAISdkStream(stream, { from: 'network' })) {
+        await writer.write(part)
+      }
+    },
+  })
+
+  return createUIMessageStreamResponse({
+    stream: uiMessageStream,
+  })
+}
+```
+
+### Converting an agent stream with reasoning enabled
+
+```typescript
+import { mastra } from '../../mastra'
+import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'
+import { toAISdkStream } from '@mastra/ai-sdk'
+
+export async function POST(req: Request) {
+  const { messages } = await req.json()
+  const reasoningAgent = mastra.getAgent('reasoningAgent')
+  const stream = await reasoningAgent.stream(messages, {
+    providerOptions: {
+      openai: { reasoningEffort: 'high' },
+    },
+  })
+
+  const uiMessageStream = createUIMessageStream({
+    originalMessages: messages,
+    execute: async ({ writer }) => {
+      for await (const part of toAISdkStream(stream, {
+        from: 'agent',
+        sendReasoning: true,
+      })) {
+        await writer.write(part)
+      }
+    },
+  })
+
+  return createUIMessageStreamResponse({
+    stream: uiMessageStream,
+  })
+}
+```
+
+### Using messageMetadata
+
+```typescript
+import { mastra } from '../../mastra'
+import { createUIMessageStream, createUIMessageStreamResponse } from 'ai'
+import { toAISdkStream } from '@mastra/ai-sdk'
+
+export async function POST(req: Request) {
+  const { messages } = await req.json()
+  const myAgent = mastra.getAgent('weatherAgent')
+  const stream = await myAgent.stream(messages)
+
+  const uiMessageStream = createUIMessageStream({
+    originalMessages: messages,
+    execute: async ({ writer }) => {
+      for await (const part of toAISdkStream(stream, {
+        from: 'agent',
+        messageMetadata: ({ part }) => ({
+          timestamp: Date.now(),
+          partType: part.type,
+        }),
+      })) {
+        await writer.write(part)
+      }
+    },
+  })
+
+  return createUIMessageStreamResponse({
+    stream: uiMessageStream,
+  })
+}
+```
+
+### Client-side stream transformation
+
+If you're using the Mastra client SDK (`@mastra/client-js`) on the client side and want to convert streams to AI SDK format:
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+import { createUIMessageStream } from 'ai'
+import { toAISdkStream } from '@mastra/ai-sdk'
+import type { ChunkType, MastraModelOutput } from '@mastra/core/stream'
+
+const client = new MastraClient({
+  baseUrl: 'http://localhost:4111',
+})
+
+const agent = client.getAgent('weatherAgent')
+const response = await agent.stream('What is the weather in Tokyo?')
+
+// Convert the client SDK stream to a ReadableStream<ChunkType>
+const chunkStream = new ReadableStream<ChunkType>({
+  async start(controller) {
+    await response.processDataStream({
+      onChunk: async chunk => {
+        controller.enqueue(chunk)
+      },
+    })
+    controller.close()
+  },
+})
+
+// Transform to AI SDK format
+const uiMessageStream = createUIMessageStream({
+  execute: async ({ writer }) => {
+    for await (const part of toAISdkStream(chunkStream as unknown as MastraModelOutput, {
+      from: 'agent',
+    })) {
+      await writer.write(part)
+    }
+  },
+})
+
+for await (const part of uiMessageStream) {
+  console.log(part)
+}
+```

package/.docs/reference/ai-sdk/to-ai-sdk-v4-messages.md

@@ -0,0 +1,79 @@
+# toAISdkV4Messages()
+
+Converts messages from various input formats to AI SDK V4 UI message format. This function accepts messages in multiple formats (strings, AI SDK V4/V5 messages, Mastra DB messages, etc.) and normalizes them to the AI SDK V4 `UIMessage` format, which is suitable for use with AI SDK UI components like `useChat()`.
+
+## Usage example
+
+```typescript
+import { toAISdkV4Messages } from '@mastra/ai-sdk'
+import { useChat } from 'ai/react' // AI SDK V4
+
+// Stored messages from your database, memory or API
+const storedMessages = [
+  { id: '1', role: 'user', parts: [{ type: 'text', text: 'Hello' }] },
+  { id: '2', role: 'assistant', parts: [{ type: 'text', text: 'Hi there!' }] },
+]
+
+export default function Chat() {
+  const { messages } = useChat({
+    initialMessages: toAISdkV4Messages(storedMessages),
+  })
+
+  return (
+    <div>
+      {messages.map(message => (
+        <div key={message.id}>
+          {message.role}: {message.content}
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+## Parameters
+
+**messages:** (`MessageListInput`): Messages to convert. Can be a string, array of strings, a single message object, or an array of message objects in any supported format.
+
+## Returns
+
+Returns an array of AI SDK V4 `UIMessage` objects with the following structure:
+
+**id:** (`string`): Unique message identifier.
+
+**role:** (`'user' | 'assistant' | 'system'`): The role of the message sender.
+
+**content:** (`string`): Text content of the message.
+
+**parts:** (`UIMessagePart[]`): Array of UI parts including text, tool-invocation, file, reasoning, source, and step markers.
+
+**createdAt:** (`Date`): Message creation timestamp.
+
+**toolInvocations?:** (`ToolInvocation[]`): Array of tool invocations for assistant messages.
+
+**experimental\_attachments?:** (`Attachment[]`): File attachments on the message.
+
+**metadata?:** (`Record<string, unknown>`): Custom metadata attached to the message.
+
+## Examples
+
+### Converting simple text messages
+
+```typescript
+import { toAISdkV4Messages } from '@mastra/ai-sdk'
+
+const messages = toAISdkV4Messages(['Hello', 'How can I help you today?'])
+// Returns array of UIMessage objects with user role and content string
+```
+
+### Loading messages with Mastra client
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+import { toAISdkV4Messages } from '@mastra/ai-sdk'
+
+const client = new MastraClient()
+
+const { messages } = await client.listThreadMessages('thread-id', { agentId: 'myAgent' })
+const uiMessages = toAISdkV4Messages(messages)
+```

package/.docs/reference/ai-sdk/to-ai-sdk-v5-messages.md

@@ -0,0 +1,76 @@
+# toAISdkV5Messages()
+
+Converts messages from various input formats to AI SDK V5 (and later) UI message format. This function accepts messages in multiple formats (strings, AI SDK V4/V5 messages, Mastra DB messages, etc.) and normalizes them to the AI SDK V5+ `UIMessage` format, which is suitable for use with AI SDK UI components like `useChat()`.
+
+## Usage example
+
+```typescript
+import { toAISdkV5Messages } from '@mastra/ai-sdk/ui'
+import { useChat } from 'ai/react'
+
+// Stored messages from your database, memory or API
+const storedMessages = [
+  { id: '1', role: 'user', content: 'Hello', parts: [{ type: 'text', text: 'Hello' }] },
+  {
+    id: '2',
+    role: 'assistant',
+    content: 'Hi there!',
+    parts: [{ type: 'text', text: 'Hi there!' }],
+  },
+]
+
+export default function Chat() {
+  const { messages } = useChat({
+    initialMessages: toAISdkV5Messages(storedMessages),
+  })
+
+  return (
+    <div>
+      {messages.map(message => (
+        <div key={message.id}>
+          {message.role}: {message.parts.map(part => (part.type === 'text' ? part.text : null))}
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+## Parameters
+
+**messages:** (`MessageListInput`): Messages to convert. Can be a string, array of strings, a single message object, or an array of message objects in any supported format.
+
+## Returns
+
+Returns an array of AI SDK V5+ `UIMessage` objects with the following structure:
+
+**id:** (`string`): Unique message identifier.
+
+**role:** (`'user' | 'assistant' | 'system'`): The role of the message sender.
+
+**parts:** (`UIMessagePart[]`): Array of UI parts including text, tool results, files, reasoning, sources, and step markers.
+
+**metadata?:** (`Record<string, unknown>`): Optional metadata including createdAt, threadId, resourceId, and custom fields.
+
+## Examples
+
+### Converting simple text messages
+
+```typescript
+import { toAISdkV5Messages } from '@mastra/ai-sdk/ui'
+
+const messages = toAISdkV5Messages(['Hello', 'How can I help you today?'])
+// Returns array of UIMessage objects with user role
+```
+
+### Loading messages with Mastra client
+
+```typescript
+import { MastraClient } from '@mastra/client-js'
+import { toAISdkV5Messages } from '@mastra/ai-sdk/ui'
+
+const client = new MastraClient()
+
+const { messages } = await client.listThreadMessages('thread-id', { agentId: 'myAgent' })
+const uiMessages = toAISdkV5Messages(messages)
+```

package/.docs/reference/ai-sdk/with-mastra.md

@@ -0,0 +1,63 @@
+# withMastra()
+
+Wraps an AI SDK model with Mastra processors and/or memory.
+
+## Usage example
+
+```typescript
+import { openai } from '@ai-sdk/openai'
+import { generateText } from 'ai'
+import { withMastra } from '@mastra/ai-sdk'
+import type { Processor } from '@mastra/core/processors'
+
+const loggingProcessor: Processor<'logger'> = {
+  id: 'logger',
+  async processInput({ messages }) {
+    console.log('Input:', messages.length, 'messages')
+    return messages
+  },
+}
+
+const model = withMastra(openai('gpt-4o'), {
+  inputProcessors: [loggingProcessor],
+})
+
+const { text } = await generateText({
+  model,
+  prompt: 'What is 2 + 2?',
+})
+```
+
+## Parameters
+
+**model:** (`LanguageModelV2`): Any AI SDK language model (e.g., \`openai('gpt-4o')\`, \`anthropic('claude-3-opus')\`).
+
+**options?:** (`WithMastraOptions`): Configuration object for processors and memory.
+
+**options.inputProcessors?:** (`InputProcessor[]`): Input processors to run before the LLM call.
+
+**options.outputProcessors?:** (`OutputProcessor[]`): Output processors to run on the LLM response.
+
+**options.memory?:** (`WithMastraMemoryOptions`): Memory configuration - enables automatic message history persistence.
+
+**options.memory.storage:** (`MemoryStorage`): Memory storage domain for message persistence. Get it from a composite store using \`await storage.getStore('memory')\`.
+
+**options.memory.threadId:** (`string`): Thread ID for conversation persistence.
+
+**options.memory.resourceId?:** (`string`): Resource ID (user/session identifier).
+
+**options.memory.lastMessages?:** (`number | false`): Number of recent messages to retrieve, or false to disable.
+
+**options.memory.semanticRecall?:** (`WithMastraSemanticRecallOptions`): Semantic recall configuration (RAG-based memory retrieval).
+
+**options.memory.workingMemory?:** (`MemoryConfig['workingMemory']`): Working memory configuration (persistent user data).
+
+**options.memory.readOnly?:** (`boolean`): Read-only mode - prevents saving new messages.
+
+## Returns
+
+A wrapped model compatible with `generateText`, `streamText`, `generateObject`, and `streamObject`.
+
+## Streaming behavior
+
+Output processors that implement `processOutputResult` run after the stream finishes. Consume the stream to completion to persist message history and semantic recall.

package/.docs/reference/ai-sdk/workflow-route.md

@@ -0,0 +1,79 @@
+# workflowRoute()
+
+Creates a workflow route handler for streaming workflow execution using the AI SDK format. This function registers an HTTP `POST` endpoint that accepts input data, executes a workflow, and streams the response back to the client in AI SDK-compatible format. You have to use it inside a [custom API route](https://mastra.ai/docs/server/custom-api-routes).
+
+Use [`handleWorkflowStream()`](https://mastra.ai/reference/ai-sdk/handle-workflow-stream) if you need a framework-agnostic handler.
+
+> **Agent streaming in workflows:** When a workflow step pipes an agent's stream to the workflow writer (e.g., `await response.fullStream.pipeTo(writer)`), the agent's text chunks and tool calls are forwarded to the UI stream in real time, even when the agent runs inside workflow steps.
+>
+> See [Workflow Streaming](https://mastra.ai/docs/streaming/workflow-streaming) for more details.
+
+## Usage example
+
+This example shows how to set up a workflow route at the `/workflow` endpoint that uses a workflow with the ID `weatherWorkflow`.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { workflowRoute } from '@mastra/ai-sdk'
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      workflowRoute({
+        path: '/workflow',
+        workflow: 'weatherWorkflow',
+      }),
+    ],
+  },
+})
+```
+
+You can also use dynamic workflow routing based on a `workflowId`. The URL `/workflow/weatherWorkflow` will resolve to the workflow with the ID `weatherWorkflow`.
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { workflowRoute } from '@mastra/ai-sdk'
+
+export const mastra = new Mastra({
+  server: {
+    apiRoutes: [
+      workflowRoute({
+        path: '/workflow/:workflowId',
+      }),
+    ],
+  },
+})
+```
+
+## Parameters
+
+**path?:** (`string`): The route path (e.g., \`/workflow\` or \`/workflow/:workflowId\`). Include \`:workflowId\` for dynamic workflow routing. (Default: `'/api/workflows/:workflowId/stream'`)
+
+**workflow?:** (`string`): Fixed workflow ID when not using dynamic routing. (Default: `undefined`)
+
+**includeTextStreamParts?:** (`boolean`): Whether to include text stream parts in the output. (Default: `true`)
+
+## Additional configuration
+
+You can use [`prepareSendMessagesRequest`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat#transport.default-chat-transport.prepare-send-messages-request) to customize the request sent to the workflow route, for example to pass additional configuration to the workflow:
+
+```typescript
+const { error, status, sendMessage, messages, regenerate, stop } = useChat({
+  transport: new DefaultChatTransport({
+    api: 'http://localhost:4111/workflow',
+    prepareSendMessagesRequest({ messages }) {
+      return {
+        body: {
+          inputData: {
+            city: messages[messages.length - 1].parts[0].text,
+          },
+          // Or resumeData for resuming a suspended workflow
+          resumeData: {
+            confirmation: messages[messages.length - 1].parts[0].text,
+          },
+        },
+      }
+    },
+  }),
+})
+```

package/.docs/reference/auth/auth0.md

@@ -0,0 +1,73 @@
+# MastraAuthAuth0 Class
+
+The `MastraAuthAuth0` class provides authentication for Mastra using Auth0. It verifies incoming requests using Auth0-issued JWT tokens and integrates with the Mastra server using the `auth` option.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthAuth0 } from '@mastra/auth-auth0'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthAuth0({
+      domain: process.env.AUTH0_DOMAIN,
+      audience: process.env.AUTH0_AUDIENCE,
+    }),
+  },
+})
+```
+
+> **Note:** You can omit the constructor parameters if you have the appropriately named environment variables (`AUTH0_DOMAIN` and `AUTH0_AUDIENCE`) set. In that case, simply use `new MastraAuthAuth0()` without any arguments.
+
+## Constructor parameters
+
+**domain?:** (`string`): Your Auth0 domain (e.g., your-tenant.auth0.com). This is used to verify JWT tokens issued by your Auth0 tenant. (Default: `process.env.AUTH0_DOMAIN`)
+
+**audience?:** (`string`): Your Auth0 API identifier/audience. This ensures tokens are intended for your specific API. (Default: `process.env.AUTH0_AUDIENCE`)
+
+**name?:** (`string`): Custom name for the auth provider instance. (Default: `"auth0"`)
+
+**authorizeUser?:** (`(user: Auth0User) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after token verification. By default, allows all authenticated users with valid tokens.
+
+## Environment Variables
+
+The following environment variables are automatically used when constructor options are not provided:
+
+**AUTH0\_DOMAIN?:** (`string`): Your Auth0 domain. Can be found in your Auth0 Dashboard under Applications > Settings.
+
+**AUTH0\_AUDIENCE?:** (`string`): Your Auth0 API identifier. This is the identifier you set when creating an API in your Auth0 Dashboard.
+
+## Default Authorization Behavior
+
+By default, `MastraAuthAuth0` validates Auth0 JWT tokens and allows access to all authenticated users:
+
+1. **Token Verification**: The JWT token is verified using Auth0's public keys (JWKS)
+2. **Signature Validation**: Ensures the token was signed by your Auth0 tenant
+3. **Expiration Check**: Verifies the token has not expired
+4. **Audience Validation**: Confirms the token was issued for your specific API (audience)
+5. **Issuer Validation**: Ensures the token was issued by your Auth0 domain
+
+If all validations pass, the user is considered authorized. To implement custom authorization logic (e.g., role-based access control), provide a custom `authorizeUser` function.
+
+## Auth0 User Type
+
+The `Auth0User` type used in the `authorizeUser` function corresponds to the decoded JWT token payload, which typically includes:
+
+- `sub`: The user's unique identifier (subject)
+- `email`: The user's email address (if included in token)
+- `email_verified`: Whether the email is verified
+- `name`: The user's display name (if available)
+- `picture`: URL to the user's profile picture (if available)
+- `iss`: Token issuer (your Auth0 domain)
+- `aud`: Token audience (your API identifier)
+- `iat`: Token issued at timestamp
+- `exp`: Token expiration timestamp
+- `scope`: Granted scopes for the token
+- Custom claims and app metadata configured in your Auth0 tenant
+
+The exact properties available depend on your Auth0 configuration, scopes requested, and any custom claims you've configured.
+
+## Related
+
+[MastraAuthAuth0 Class](https://mastra.ai/docs/server/auth/auth0)

package/.docs/reference/auth/better-auth.md

@@ -0,0 +1,71 @@
+# MastraAuthBetterAuth Class
+
+The `MastraAuthBetterAuth` class provides authentication for Mastra applications using Better Auth. It verifies incoming requests with Better Auth sessions and integrates with the Mastra server using the `auth` option.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthBetterAuth } from '@mastra/auth-better-auth'
+import { betterAuth } from 'better-auth'
+
+// Create your Better Auth instance
+const auth = betterAuth({
+  database: {
+    provider: 'postgresql',
+    url: process.env.DATABASE_URL,
+  },
+  emailAndPassword: {
+    enabled: true,
+  },
+  baseURL: process.env.BETTER_AUTH_URL,
+  secret: process.env.BETTER_AUTH_SECRET,
+})
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthBetterAuth({
+      auth,
+    }),
+  },
+})
+```
+
+## Constructor parameters
+
+**auth:** (`Auth`): Your Better Auth instance created via betterAuth({ ... }). This is required and must be properly configured with a supported database provider.
+
+**name?:** (`string`): Custom name for the auth provider instance. (Default: `'better-auth'`)
+
+**authorizeUser?:** (`(user: BetterAuthUser, request: HonoRequest) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after session verification. By default, allows all authenticated users with valid sessions.
+
+**public?:** (`Array<string | RegExp | [string, Methods | Methods[]]>`): Public routes that do not require authentication. Supports exact paths, wildcards, and path params.
+
+**protected?:** (`Array<string | RegExp | [string, Methods | Methods[]]>`): Protected routes that require authentication. Supports exact paths, wildcards, and path params.
+
+## BetterAuthUser Type
+
+The `BetterAuthUser` type contains the session and user information returned by Better Auth:
+
+```typescript
+interface BetterAuthUser {
+  session: Session
+  user: User
+}
+```
+
+- `session`: The Better Auth session object containing session metadata
+- `user`: The authenticated user object with user details
+
+The `Session` and `User` types are exported by the Better Auth package.
+
+## Matching rules
+
+- `public` and `protected` accept exact paths, wildcard patterns (like `/api/*`), and path params (like `/users/:id`).
+- For method-specific rules, use tuples like `["/api/agents", ["GET", "POST"]]`.
+- If a route matches both `public` and `protected`, `public` wins and no auth is required.
+- If neither matches, routes are treated as protected by default (unless a route is explicitly marked `requiresAuth: false`).
+
+## Related
+
+[MastraAuthBetterAuth Class](https://mastra.ai/docs/server/auth/better-auth)