@mastra/core 1.7.0 → 1.8.0

package/dist/docs/references/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/dist/docs/references/reference-ai-sdk-with-mastra.md

@@ -0,0 +1,59 @@
+# 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`.

package/dist/docs/references/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/dist/docs/references/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/dist/docs/references/reference-auth-clerk.md

@@ -0,0 +1,36 @@
+# MastraAuthClerk Class
+
+The `MastraAuthClerk` class provides authentication for Mastra applications using Clerk. It verifies incoming requests with Clerk-issued JWT tokens and integrates with the Mastra server using the `auth` option.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthClerk } from '@mastra/auth-clerk'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthClerk({
+      jwksUri: process.env.CLERK_JWKS_URI,
+      publishableKey: process.env.CLERK_PUBLISHABLE_KEY,
+      secretKey: process.env.CLERK_SECRET_KEY,
+    }),
+  },
+})
+```
+
+## Constructor parameters
+
+**publishableKey?:** (`string`): Your Clerk publishable key. Can be found in your Clerk Dashboard under API Keys. (Default: `process.env.CLERK_PUBLISHABLE_KEY`)
+
+**secretKey?:** (`string`): Your Clerk secret key. Used for server-side authentication and token verification. (Default: `process.env.CLERK_SECRET_KEY`)
+
+**jwksUri?:** (`string`): The JWKS URI from your Clerk application. Used to verify JWT signatures. (Default: `process.env.CLERK_JWKS_URI`)
+
+**name?:** (`string`): Custom name for the auth provider instance.
+
+**authorizeUser?:** (`(user: User, request: HonoRequest) => 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.
+
+## Related
+
+[MastraAuthClerk Class](https://mastra.ai/docs/server/auth/clerk)

package/dist/docs/references/reference-auth-firebase.md

@@ -0,0 +1,80 @@
+# MastraAuthFirebase Class
+
+The `MastraAuthFirebase` class provides authentication for Mastra using Firebase Authentication. It verifies incoming requests using Firebase ID tokens and integrates with the Mastra server using the `auth` option.
+
+## Usage examples
+
+### Basic usage with environment variables
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthFirebase } from '@mastra/auth-firebase'
+
+// Automatically uses FIREBASE_SERVICE_ACCOUNT and FIRESTORE_DATABASE_ID env vars
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthFirebase(),
+  },
+})
+```
+
+### Custom configuration
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthFirebase } from '@mastra/auth-firebase'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthFirebase({
+      serviceAccount: '/path/to/service-account-key.json',
+      databaseId: 'your-database-id',
+    }),
+  },
+})
+```
+
+## Constructor parameters
+
+**serviceAccount?:** (`string`): Path to the Firebase service account JSON file. This file contains the credentials needed to verify Firebase ID tokens on the server side. (Default: `process.env.FIREBASE_SERVICE_ACCOUNT`)
+
+**databaseId?:** (`string`): The Firestore database ID to use. Typically '(default)' for the default database. (Default: `process.env.FIRESTORE_DATABASE_ID || process.env.FIREBASE_DATABASE_ID`)
+
+**name?:** (`string`): Custom name for the auth provider instance. (Default: `"firebase"`)
+
+**authorizeUser?:** (`(user: FirebaseUser) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after token verification. By default, checks for the presence of a document in the 'user\_access' collection keyed by the user's UID.
+
+## Environment Variables
+
+The following environment variables are automatically used when constructor options are not provided:
+
+**FIREBASE\_SERVICE\_ACCOUNT?:** (`string`): Path to Firebase service account JSON file. Used if serviceAccount option is not provided.
+
+**FIRESTORE\_DATABASE\_ID?:** (`string`): Firestore database ID. Primary environment variable for database configuration.
+
+**FIREBASE\_DATABASE\_ID?:** (`string`): Alternative environment variable for Firestore database ID. Used if FIRESTORE\_DATABASE\_ID is not set.
+
+## Default Authorization Behavior
+
+By default, `MastraAuthFirebase` uses Firestore to manage user access:
+
+1. After successfully verifying a Firebase ID token, the `authorizeUser` method is called
+2. It checks for the existence of a document in the `user_access` collection with the user's UID as the document ID
+3. If the document exists, the user is authorized; otherwise, access is denied
+4. The Firestore database used is determined by the `databaseId` parameter or environment variables
+
+## Firebase User Type
+
+The `FirebaseUser` type used in the `authorizeUser` function corresponds to Firebase's `DecodedIdToken` interface, which includes:
+
+- `uid`: The user's unique identifier
+- `email`: The user's email address (if available)
+- `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)
+- `auth_time`: When the user authenticated
+- And other standard JWT claims
+
+## Related
+
+[MastraAuthFirebase Class](https://mastra.ai/docs/server/auth/firebase)

package/dist/docs/references/reference-auth-jwt.md

@@ -0,0 +1,26 @@
+# MastraJwtAuth Class
+
+The `MastraJwtAuth` class provides a lightweight authentication mechanism for Mastra using JSON Web Tokens (JWTs). It verifies incoming requests based on a shared secret and integrates with the Mastra server using the `auth` option.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraJwtAuth } from '@mastra/auth'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraJwtAuth({
+      secret: '<your-secret>',
+    }),
+  },
+})
+```
+
+## Constructor parameters
+
+**secret:** (`string`): A unique string used to sign and verify JSON Web Tokens (JWTs) for authenticating incoming requests.
+
+## Related
+
+[MastraJwtAuth](https://mastra.ai/docs/server/auth/jwt)

package/dist/docs/references/reference-auth-supabase.md

@@ -0,0 +1,33 @@
+# MastraAuthSupabase Class
+
+The `MastraAuthSupabase` class provides authentication for Mastra using Supabase Auth. It verifies incoming requests using Supabase's authentication system and integrates with the Mastra server using the `auth` option.
+
+## Usage example
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraAuthSupabase } from '@mastra/auth-supabase'
+
+export const mastra = new Mastra({
+  server: {
+    auth: new MastraAuthSupabase({
+      url: process.env.SUPABASE_URL,
+      anonKey: process.env.SUPABASE_ANON_KEY,
+    }),
+  },
+})
+```
+
+## Constructor parameters
+
+**url?:** (`string`): The URL of your Supabase project. Can be found in your Supabase project settings. (Default: `process.env.SUPABASE_URL`)
+
+**anonKey?:** (`string`): The anonymous/public key for your Supabase project. Used for client-side authentication. (Default: `process.env.SUPABASE_ANON_KEY`)
+
+**name?:** (`string`): Custom name for the auth provider instance.
+
+**authorizeUser?:** (`(user: User, request: HoneRequest) => Promise<boolean> | boolean`): Custom authorization function to determine if a user should be granted access. Called after token verification. By default, checks the 'isAdmin' column in the 'users' table.
+
+## Related
+
+[MastraAuthSupabase](https://mastra.ai/docs/server/auth/supabase)