@mastra/client-js 0.0.0-error-handler-fix-20251020202607 → 0.0.0-execa-dynamic-import-20260304221256

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-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/dist/docs/references/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)
+```