@mastra/ai-sdk 0.2.7 → 1.0.0-alpha.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @mastra/ai-sdk
 
+## 1.0.0-alpha.0
+
+### Major Changes
+
+- Add sendStart, sendFinish, sendReasoning, and sendSources options to toAISdkV5Stream function, allowing fine-grained control over which message chunks are included in the converted stream. Previously, these values were hardcoded in the transformer. ([#10250](https://github.com/mastra-ai/mastra/pull/10250))
+
+  BREAKING CHANGE: AgentStreamToAISDKTransformer now accepts an options object instead of a single lastMessageId parameter
+
+  Also, add sendStart, sendFinish, sendReasoning, and sendSources parameters to
+  chatRoute function, enabling fine-grained control over which chunks are
+  included in the AI SDK stream output.
+
+### Patch Changes
+
+- Updated dependencies [[`eebb7bb`](https://github.com/mastra-ai/mastra/commit/eebb7bb407c57342a3be3a2efbe68c696589feeb), [`c6e6d07`](https://github.com/mastra-ai/mastra/commit/c6e6d071ecf346a80dceab410af2c567c7e66a57), [`0e6df8f`](https://github.com/mastra-ai/mastra/commit/0e6df8f66340992cb1b319834657deb17368de52), [`6295fd7`](https://github.com/mastra-ai/mastra/commit/6295fd783d49075d5bf2c18ff9486e94d36aaa56), [`d813cf7`](https://github.com/mastra-ai/mastra/commit/d813cf7251695d85cc60469058384ffa74974484)]:
+  - @mastra/core@0.24.2-alpha.0
+
 ## 0.2.7
 
 ### Patch Changes

package/dist/chat-route.d.ts

@@ -9,6 +9,56 @@ export type chatRouteOptions<OUTPUT extends OutputSchema = undefined> = {
 } | {
     path: string;
     agent: string;
-});
-export declare function chatRoute<OUTPUT extends OutputSchema = undefined>({ path, agent, defaultOptions, }: chatRouteOptions<OUTPUT>): ReturnType<typeof registerApiRoute>;
+}) & {
+    sendStart?: boolean;
+    sendFinish?: boolean;
+    sendReasoning?: boolean;
+    sendSources?: boolean;
+};
+/**
+ * Creates a chat route handler for streaming agent conversations using the AI SDK format.
+ *
+ * This function registers an HTTP POST endpoint that accepts messages, executes an agent,
+ * and streams the response back to the client in AI SDK v5 compatible format.
+ * *
+ * @param {chatRouteOptions} options - Configuration options for the chat route
+ * @param {string} [options.path='/chat/:agentId'] - The route path. Include `:agentId` for dynamic routing
+ * @param {string} [options.agent] - Fixed agent ID when not using dynamic routing
+ * @param {AgentExecutionOptions} [options.defaultOptions] - Default options passed to agent execution
+ * @param {boolean} [options.sendStart=true] - Whether to send start events in the stream
+ * @param {boolean} [options.sendFinish=true] - Whether to send finish events in the stream
+ * @param {boolean} [options.sendReasoning=false] - Whether to include reasoning steps in the stream
+ * @param {boolean} [options.sendSources=false] - Whether to include source citations in the stream
+ *
+ * @returns {ReturnType<typeof registerApiRoute>} A registered API route handler
+ *
+ * @throws {Error} When path doesn't include `:agentId` and no fixed agent is specified
+ * @throws {Error} When agent ID is missing at runtime
+ * @throws {Error} When specified agent is not found in Mastra instance
+ *
+ * @example
+ * // Dynamic agent routing
+ * chatRoute({
+ *   path: '/chat/:agentId',
+ *   sendReasoning: true,
+ * });
+ *
+ * @example
+ * // Fixed agent with custom path
+ * chatRoute({
+ *   path: '/api/support-chat',
+ *   agent: 'support-agent',
+ *   defaultOptions: {
+ *     maxSteps: 5,
+ *   },
+ * });
+ *
+ * @remarks
+ * - The route handler expects a JSON body with a `messages` array
+ * - Messages should follow the format: `{ role: 'user' | 'assistant' | 'system', content: string }`
+ * - The response is a Server-Sent Events (SSE) stream compatible with AI SDK v5
+ * - If both `agent` and `:agentId` are present, a warning is logged and the fixed `agent` takes precedence
+ * - Request context from the incoming request overrides `defaultOptions.requestContext` if both are present
+ */
+export declare function chatRoute<OUTPUT extends OutputSchema = undefined>({ path, agent, defaultOptions, sendStart, sendFinish, sendReasoning, sendSources, }: chatRouteOptions<OUTPUT>): ReturnType<typeof registerApiRoute>;
 //# sourceMappingURL=chat-route.d.ts.map

package/dist/chat-route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chat-route.d.ts","sourceRoot":"","sources":["../src/chat-route.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEhE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAIxD,MAAM,MAAM,gBAAgB,CAAC,MAAM,SAAS,YAAY,GAAG,SAAS,IAAI;IACtE,cAAc,CAAC,EAAE,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzD,GAAG,CACA;IACE,IAAI,EAAE,GAAG,MAAM,WAAW,MAAM,EAAE,CAAC;IACnC,KAAK,CAAC,EAAE,KAAK,CAAC;CACf,GACD;IACE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf,CACJ,CAAC;AAEF,wBAAgB,SAAS,CAAC,MAAM,SAAS,YAAY,GAAG,SAAS,EAAE,EACjE,IAAuB,EACvB,KAAK,EACL,cAAc,GACf,EAAE,gBAAgB,CAAC,MAAM,CAAC,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CA6JhE"}
+{"version":3,"file":"chat-route.d.ts","sourceRoot":"","sources":["../src/chat-route.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAEhE,OAAO,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACvD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAIxD,MAAM,MAAM,gBAAgB,CAAC,MAAM,SAAS,YAAY,GAAG,SAAS,IAAI;IACtE,cAAc,CAAC,EAAE,qBAAqB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzD,GAAG,CACA;IACE,IAAI,EAAE,GAAG,MAAM,WAAW,MAAM,EAAE,CAAC;IACnC,KAAK,CAAC,EAAE,KAAK,CAAC;CACf,GACD;IACE,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf,CACJ,GAAG;IACA,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,SAAS,CAAC,MAAM,SAAS,YAAY,GAAG,SAAS,EAAE,EACjE,IAAuB,EACvB,KAAK,EACL,cAAc,EACd,SAAgB,EAChB,UAAiB,EACjB,aAAqB,EACrB,WAAmB,GACpB,EAAE,gBAAgB,CAAC,MAAM,CAAC,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAoKhE"}

package/dist/index.cjs

@@ -271,6 +271,14 @@ function convertFullStreamChunkToUIMessageStream({
       };
     }
     case "reasoning-delta": {
+      if (sendReasoning) {
+        return {
+          type: "reasoning-delta",
+          id: part.id,
+          delta: part.text,
+          ...part.providerMetadata != null ? { providerMetadata: part.providerMetadata } : {}
+        };
+      }
       return;
     }
     case "reasoning-end": {
@@ -288,6 +296,25 @@ function convertFullStreamChunkToUIMessageStream({
       };
     }
     case "source": {
+      if (sendSources && part.sourceType === "url") {
+        return {
+          type: "source-url",
+          sourceId: part.id,
+          url: part.url,
+          title: part.title,
+          ...part.providerMetadata != null ? { providerMetadata: part.providerMetadata } : {}
+        };
+      }
+      if (sendSources && part.sourceType === "document") {
+        return {
+          type: "source-document",
+          sourceId: part.id,
+          mediaType: part.mediaType,
+          title: part.title,
+          filename: part.filename,
+          ...part.providerMetadata != null ? { providerMetadata: part.providerMetadata } : {}
+        };
+      }
       return;
     }
     case "tool-input-start": {
@@ -378,21 +405,23 @@ function convertFullStreamChunkToUIMessageStream({
       return { type: "finish-step" };
     }
     case "start": {
-      {
+      if (sendStart) {
         return {
           type: "start",
           ...messageMetadataValue != null ? { messageMetadata: messageMetadataValue } : {},
           ...responseMessageId != null ? { messageId: responseMessageId } : {}
         };
       }
+      return;
     }
     case "finish": {
-      {
+      if (sendFinish) {
         return {
           type: "finish",
           ...messageMetadataValue != null ? { messageMetadata: messageMetadataValue } : {}
         };
       }
+      return;
     }
     case "abort": {
       return part;
@@ -457,17 +486,23 @@ function AgentNetworkToAISDKTransformer() {
     }
   });
 }
-function AgentStreamToAISDKTransformer(lastMessageId) {
+function AgentStreamToAISDKTransformer({
+  lastMessageId,
+  sendStart,
+  sendFinish,
+  sendReasoning,
+  sendSources
+}) {
   let bufferedSteps = /* @__PURE__ */ new Map();
   return new TransformStream({
     transform(chunk, controller) {
       const part = convertMastraChunkToAISDKv5({ chunk, mode: "stream" });
       const transformedChunk = convertFullStreamChunkToUIMessageStream({
         part,
-        sendReasoning: false,
-        sendSources: false,
-        sendStart: true,
-        sendFinish: true,
+        sendReasoning,
+        sendSources,
+        sendStart,
+        sendFinish,
         responseMessageId: lastMessageId,
         onError() {
           return "Error";
@@ -976,7 +1011,11 @@ function transformNetwork(payload, bufferedNetworks, isNested) {
 }
 
 // src/to-ai-sdk-format.ts
-function toAISdkFormat(stream, options = { from: "agent" }) {
+function toAISdkFormat(stream, options = {
+  from: "agent",
+  sendStart: true,
+  sendFinish: true
+}) {
   const from = options?.from;
   if (from === "workflow") {
     return stream.pipeThrough(WorkflowStreamToAISDKTransformer());
@@ -985,14 +1024,26 @@ function toAISdkFormat(stream, options = { from: "agent" }) {
     return stream.pipeThrough(AgentNetworkToAISDKTransformer());
   }
   const agentReadable = "fullStream" in stream ? stream.fullStream : stream;
-  return agentReadable.pipeThrough(AgentStreamToAISDKTransformer(options?.lastMessageId));
+  return agentReadable.pipeThrough(
+    AgentStreamToAISDKTransformer({
+      lastMessageId: options?.lastMessageId,
+      sendStart: options?.sendStart,
+      sendFinish: options?.sendFinish,
+      sendReasoning: options?.sendReasoning,
+      sendSources: options?.sendSources
+    })
+  );
 }
 
 // src/chat-route.ts
 function chatRoute({
   path = "/chat/:agentId",
   agent,
-  defaultOptions
+  defaultOptions,
+  sendStart = true,
+  sendFinish = true,
+  sendReasoning = false,
+  sendSources = false
 }) {
   if (!agent && !path.includes("/:agentId")) {
     throw new Error("Path must include :agentId to route to the correct agent or pass the agent explicitly");
@@ -1126,7 +1177,14 @@ function chatRoute({
       const uiMessageStream = ai.createUIMessageStream({
         originalMessages: messages,
         execute: async ({ writer }) => {
-          for await (const part of toAISdkFormat(result, { from: "agent", lastMessageId })) {
+          for await (const part of toAISdkFormat(result, {
+            from: "agent",
+            lastMessageId,
+            sendStart,
+            sendFinish,
+            sendReasoning,
+            sendSources
+          })) {
             writer.write(part);
           }
         }
@@ -1170,7 +1228,7 @@ function workflowRoute({
                 resourceId: { type: "string" },
                 inputData: { type: "object", additionalProperties: true },
                 resumeData: { type: "object", additionalProperties: true },
-                requestContext: { type: "object", additionalProperties: true },
+                runtimeContext: { type: "object", additionalProperties: true },
                 tracingOptions: { type: "object", additionalProperties: true },
                 step: { type: "string" }
               }