@mastra/ai-sdk 1.7.2 → 1.8.0-alpha.0

package/dist/index.d.ts

@@ -6,7 +6,7 @@ export type { WorkflowDataPart, WorkflowStepDataPart } from './transformers.js';
 export { networkRoute, handleNetworkStream } from './network-route.js';
 export type { NetworkRouteOptions, NetworkStreamHandlerParams, NetworkStreamHandlerOptions } from './network-route.js';
 export type { NetworkDataPart } from './transformers.js';
-export type { AgentDataPart } from './transformers.js';
+export type { AgentDataPart, AgentStepDataPart } from './transformers.js';
 export { toAISdkStream, toAISdkV5Stream } from './convert-streams.js';
 export { workflowSnapshotToStream } from './convert-snapshot.js';
 export { smoothStream } from './smooth-stream.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC3D,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACvE,YAAY,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAC;AACxH,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACpE,YAAY,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAC;AACpH,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAEpD,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,qBAAqB,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AAG3F,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,YAAY,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,+BAA+B,EAAE,MAAM,cAAc,CAAC;AAGhH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC3D,YAAY,EACV,gBAAgB,EAChB,uBAAuB,EACvB,wBAAwB,EACxB,wBAAwB,EACxB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AACvE,YAAY,EAAE,oBAAoB,EAAE,2BAA2B,EAAE,4BAA4B,EAAE,MAAM,kBAAkB,CAAC;AACxH,YAAY,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACpE,YAAY,EAAE,mBAAmB,EAAE,0BAA0B,EAAE,2BAA2B,EAAE,MAAM,iBAAiB,CAAC;AACpH,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAEvE,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,qBAAqB,EAAE,4BAA4B,EAAE,MAAM,iBAAiB,CAAC;AAG3F,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,YAAY,EAAE,iBAAiB,EAAE,uBAAuB,EAAE,+BAA+B,EAAE,MAAM,cAAc,CAAC;AAGhH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -9404,6 +9404,7 @@ function convertFullStreamChunkToUIMessageStream({ part, messageMetadataValue, s
 //#endregion
 //#region src/transformers.ts
 const PRIMITIVE_CACHE_SYMBOL = Symbol("primitive-cache");
+const COMPLETED_STEPS_SYMBOL = Symbol("completed-steps-cache");
 function cloneWorkflowStep(step, includeOutput) {
 	return {
 		name: step.name,
@@ -9531,7 +9532,8 @@ function createAgentStreamToAISDKTransformer(convertMastraChunkToAISDK, { lastMe
 			if (transformedChunk) if (transformedChunk.type === "tool-agent") {
 				const payload = transformedChunk.payload;
 				const agentTransformed = transformAgent(payload, bufferedSteps);
-				if (agentTransformed) controller.enqueue(agentTransformed);
+				if (agentTransformed) if (Array.isArray(agentTransformed)) for (const part of agentTransformed) controller.enqueue(part);
+				else controller.enqueue(agentTransformed);
 			} else if (transformedChunk.type === "tool-workflow") {
 				const payload = transformedChunk.payload;
 				const workflowChunk = transformWorkflow(payload, bufferedSteps, true, void 0, void 0, convertMastraChunkToAISDK);
@@ -9614,30 +9616,7 @@ function AgentStreamToAISDKV6Transformer({ lastMessageId, sendStart = true, send
 	});
 }
 function ensureAgentRunState(bufferedSteps, runId) {
-	if (!bufferedSteps.has(runId)) bufferedSteps.set(runId, {
-		id: "",
-		object: null,
-		finishReason: null,
-		usage: null,
-		warnings: [],
-		text: "",
-		reasoning: [],
-		sources: [],
-		files: [],
-		toolCalls: [],
-		pendingToolCalls: [],
-		toolResults: [],
-		request: {},
-		response: {
-			id: "",
-			timestamp: /* @__PURE__ */ new Date(),
-			modelId: "",
-			messages: []
-		},
-		providerMetadata: void 0,
-		steps: [],
-		status: "running"
-	});
+	if (!bufferedSteps.has(runId)) bufferedSteps.set(runId, createAgentRunState());
 	return bufferedSteps.get(runId);
 }
 function upsertPendingToolCall(pendingToolCalls = [], toolCallId, updates) {
@@ -9673,36 +9652,109 @@ function appendPendingToolCallArgs(pendingToolCalls = [], payload) {
 function removePendingToolCall(pendingToolCalls = [], toolCallId) {
 	return pendingToolCalls.filter((call) => call.toolCallId !== toolCallId);
 }
+function createAgentResponseState() {
+	return {
+		id: "",
+		timestamp: /* @__PURE__ */ new Date(),
+		modelId: "",
+		messages: []
+	};
+}
+function createAgentRunState(id = "") {
+	return {
+		id,
+		object: null,
+		finishReason: null,
+		usage: null,
+		warnings: [],
+		text: "",
+		reasoning: [],
+		sources: [],
+		files: [],
+		toolCalls: [],
+		pendingToolCalls: [],
+		toolResults: [],
+		request: {},
+		response: createAgentResponseState(),
+		providerMetadata: void 0,
+		steps: [],
+		status: "running"
+	};
+}
+function cloneAgentResponse(response, { includeMessages }) {
+	if (!response) return response;
+	return {
+		...response,
+		...Object.prototype.hasOwnProperty.call(response, "messages") ? { messages: includeMessages ? response.messages : [] } : {},
+		...Object.prototype.hasOwnProperty.call(response, "dbMessages") ? { dbMessages: includeMessages ? response.dbMessages : [] } : {},
+		...Object.prototype.hasOwnProperty.call(response, "uiMessages") ? { uiMessages: includeMessages ? response.uiMessages : [] } : {}
+	};
+}
+function cloneAgentStep(step, { includeDetails }) {
+	if (includeDetails) return {
+		...step,
+		response: cloneAgentResponse(step.response, { includeMessages: true })
+	};
+	return {
+		...step,
+		object: null,
+		files: [],
+		sources: [],
+		toolCalls: [],
+		pendingToolCalls: [],
+		toolResults: [],
+		dynamicToolCalls: [],
+		dynamicToolResults: [],
+		staticToolCalls: [],
+		staticToolResults: [],
+		text: "",
+		reasoning: [],
+		content: Array.isArray(step.content) ? [] : step.content,
+		reasoningText: typeof step.reasoningText === "string" ? "" : step.reasoningText,
+		response: cloneAgentResponse(step.response, { includeMessages: false })
+	};
+}
+function serializeAgentRun(current, { includeCompletedStepDetails, includeResponseMessages }) {
+	const { _textOffset: _to, _reasoningOffset: _ro, ...data } = current;
+	return {
+		...data,
+		response: cloneAgentResponse(data.response, { includeMessages: includeResponseMessages }),
+		steps: data.steps.map((step) => cloneAgentStep(step, { includeDetails: includeCompletedStepDetails }))
+	};
+}
+function createAgentDataPart(args) {
+	const { current, runId, includeCompletedStepDetails, includeResponseMessages } = args;
+	return {
+		type: "data-tool-agent",
+		id: runId,
+		data: serializeAgentRun(current, {
+			includeCompletedStepDetails,
+			includeResponseMessages
+		})
+	};
+}
+function createAgentStepDataPart(args) {
+	const { runId, stepIndex, step } = args;
+	return {
+		type: "data-tool-agent-step",
+		id: `${runId}:${stepIndex}`,
+		data: {
+			runId,
+			stepIndex,
+			step: cloneAgentStep(step, { includeDetails: true })
+		}
+	};
+}
 function transformAgent(payload, bufferedSteps) {
 	let hasChanged = false;
+	let completedStep = null;
 	switch (payload.type) {
-		case "start":
-			bufferedSteps.set(payload.runId, {
-				id: payload.payload.id,
-				object: null,
-				finishReason: null,
-				usage: null,
-				warnings: [],
-				text: "",
-				reasoning: [],
-				sources: [],
-				files: [],
-				toolCalls: [],
-				pendingToolCalls: [],
-				toolResults: [],
-				request: {},
-				response: {
-					id: "",
-					timestamp: /* @__PURE__ */ new Date(),
-					modelId: "",
-					messages: []
-				},
-				providerMetadata: void 0,
-				steps: [],
-				status: "running"
-			});
+		case "start": {
+			const startState = createAgentRunState(payload.payload.id);
+			bufferedSteps.set(payload.runId, startState);
 			hasChanged = true;
 			break;
+		}
 		case "tool-call-input-streaming-start": {
 			const toolInputStartRun = ensureAgentRunState(bufferedSteps, payload.runId);
 			const existing = toolInputStartRun.pendingToolCalls?.find((call) => call.toolCallId === payload.payload.toolCallId);
@@ -9833,6 +9885,7 @@ function transformAgent(payload, bufferedSteps) {
 			break;
 		case "step-finish": {
 			const stepRun = ensureAgentRunState(bufferedSteps, payload.runId);
+			const stepIndex = stepRun.steps.length;
 			const { steps: _steps, _textOffset, _reasoningOffset, ...stepRunWithoutSteps } = stepRun;
 			const textOffset = _textOffset || 0;
 			const reasoningOffset = _reasoningOffset || 0;
@@ -9874,18 +9927,28 @@ function transformAgent(payload, bufferedSteps) {
 				_textOffset: stepRun.text.length,
 				_reasoningOffset: stepRun.reasoning.length
 			});
+			completedStep = {
+				stepIndex,
+				step: stepResult
+			};
 			hasChanged = true;
 			break;
 		}
 		default: break;
 	}
 	if (hasChanged) {
-		const { _textOffset: _to, _reasoningOffset: _ro, ...data } = bufferedSteps.get(payload.runId);
-		return {
-			type: "data-tool-agent",
-			id: payload.runId,
-			data
-		};
+		const snapshot = createAgentDataPart({
+			current: bufferedSteps.get(payload.runId),
+			runId: payload.runId,
+			includeCompletedStepDetails: payload.type === "finish",
+			includeResponseMessages: payload.type === "finish"
+		});
+		if (completedStep) return [snapshot, createAgentStepDataPart({
+			runId: payload.runId,
+			stepIndex: completedStep.stepIndex,
+			step: completedStep.step
+		})];
+		return snapshot;
 	}
 	return null;
 }
@@ -10311,10 +10374,24 @@ function transformNetwork(payload, bufferedNetworks, isNested) {
 				const step = current.steps.find((step) => step.id === stepId);
 				if (!step) return null;
 				step[PRIMITIVE_CACHE_SYMBOL] = step[PRIMITIVE_CACHE_SYMBOL] || /* @__PURE__ */ new Map();
+				if (payload.payload.type === "start") delete step[COMPLETED_STEPS_SYMBOL];
 				const result = transformAgent(payload.payload, step[PRIMITIVE_CACHE_SYMBOL]);
-				if (result) {
-					const { request, response, ...data } = result.data;
+				const snapshot = Array.isArray(result) ? result[0] : result;
+				if (snapshot) {
+					const { request, response, ...data } = snapshot.data;
+					if (Array.isArray(result)) {
+						const { stepIndex, step: completedStepDetail } = result[1].data;
+						step[COMPLETED_STEPS_SYMBOL] = step[COMPLETED_STEPS_SYMBOL] || /* @__PURE__ */ new Map();
+						step[COMPLETED_STEPS_SYMBOL].set(stepIndex, completedStepDetail);
+					}
 					step.task = data;
+					const completedSteps = step[COMPLETED_STEPS_SYMBOL];
+					if (completedSteps && completedSteps.size > 0 && Array.isArray(data.steps)) {
+						for (const [stepIndex, completedStepDetail] of completedSteps) if (stepIndex < data.steps.length) data.steps[stepIndex] = {
+							...data.steps[stepIndex],
+							...completedStepDetail
+						};
+					}
 				}
 				bufferedNetworks.set(payload.runId, current);
 				return {
@@ -10438,6 +10515,124 @@ function toAISdkStream(stream, options = {
 	}));
 }
 //#endregion
+//#region src/sse-heartbeat.ts
+const SSE_HEARTBEAT_BYTES = new TextEncoder().encode(": heartbeat\n\n");
+const LF_BYTE = 10;
+const MAX_TIMEOUT_MS = 2147483647;
+/** Throws when an enabled heartbeat interval cannot be scheduled with a timer. */
+function assertValidHeartbeatMs(heartbeatMs) {
+	if (heartbeatMs !== void 0 && !(heartbeatMs <= 0) && (!Number.isFinite(heartbeatMs) || heartbeatMs > MAX_TIMEOUT_MS)) throw new RangeError(`heartbeatMs must be a finite number no greater than ${MAX_TIMEOUT_MS}`);
+}
+/**
+* Adds periodic SSE comment heartbeats to an AI SDK response body.
+* AI SDK serialization uses LF-delimited frames, which this private wrapper preserves and relies on.
+*/
+function withSseHeartbeat(response, heartbeatMs) {
+	assertValidHeartbeatMs(heartbeatMs);
+	if (heartbeatMs === void 0 || heartbeatMs <= 0 || !response.body) return response;
+	const reader = response.body.getReader();
+	let heartbeatTimeout;
+	let wakePull;
+	let readResult;
+	let readError;
+	let hasReadError = false;
+	let reading = false;
+	let finished = false;
+	let readerReleased = false;
+	let atFrameBoundary = true;
+	let lastByte;
+	let nextHeartbeatAt = performance.now() + heartbeatMs;
+	const clearHeartbeat = () => {
+		if (heartbeatTimeout !== void 0) {
+			clearTimeout(heartbeatTimeout);
+			heartbeatTimeout = void 0;
+		}
+	};
+	const releaseReader = () => {
+		if (readerReleased) return;
+		readerReleased = true;
+		reader.releaseLock();
+	};
+	const updateFrameBoundary = (chunk) => {
+		if (chunk.byteLength === 0) return;
+		atFrameBoundary = chunk.byteLength === 1 ? lastByte === LF_BYTE && chunk[0] === LF_BYTE : chunk[chunk.byteLength - 2] === LF_BYTE && chunk[chunk.byteLength - 1] === LF_BYTE;
+		lastByte = chunk[chunk.byteLength - 1];
+	};
+	const startRead = () => {
+		if (reading || readResult || hasReadError || finished) return;
+		reading = true;
+		reader.read().then((result) => {
+			reading = false;
+			readResult = result;
+			wakePull?.("read");
+		}, (error) => {
+			reading = false;
+			readError = error;
+			hasReadError = true;
+			wakePull?.("read");
+		});
+	};
+	const forwardRead = (controller) => {
+		if (hasReadError) {
+			finished = true;
+			releaseReader();
+			controller.error(readError);
+			return;
+		}
+		if (!readResult) return;
+		const result = readResult;
+		readResult = void 0;
+		if (result.done) {
+			finished = true;
+			releaseReader();
+			controller.close();
+			return;
+		}
+		updateFrameBoundary(result.value);
+		controller.enqueue(result.value);
+	};
+	const stream = new ReadableStream({
+		async pull(controller) {
+			if (finished) return;
+			startRead();
+			if (readResult || hasReadError) {
+				forwardRead(controller);
+				return;
+			}
+			const next = await new Promise((resolve) => {
+				wakePull = resolve;
+				if (atFrameBoundary) heartbeatTimeout = setTimeout(() => resolve("heartbeat"), Math.max(0, nextHeartbeatAt - performance.now()));
+			});
+			wakePull = void 0;
+			clearHeartbeat();
+			if (finished) return;
+			if (readResult || hasReadError) {
+				forwardRead(controller);
+				return;
+			}
+			if (next === "heartbeat") {
+				controller.enqueue(SSE_HEARTBEAT_BYTES.slice());
+				nextHeartbeatAt = performance.now() + heartbeatMs;
+			}
+		},
+		async cancel(reason) {
+			if (finished) return;
+			finished = true;
+			clearHeartbeat();
+			try {
+				await reader.cancel(reason);
+			} finally {
+				releaseReader();
+			}
+		}
+	});
+	return new Response(stream, {
+		status: response.status,
+		statusText: response.statusText,
+		headers: response.headers
+	});
+}
+//#endregion
 //#region src/chat-route.ts
 /**
 * Collects every approval response across all assistant messages in a v6
@@ -10640,11 +10835,13 @@ async function handleChatStream({ mastra, agentId, agentVersion, params, default
 * @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
+* @param {number} [options.heartbeatMs] - Target interval for periodic SSE comment heartbeats. Already-buffered source events and stream lifecycle signals take priority. Values up to 0 disable heartbeats. `NaN`, positive infinity, and values above 2,147,483,647 throw a `RangeError`.
 * @param {(error: unknown) => string} [options.onError] - Custom error serializer streamed to the client. When omitted, errors are passed through a default serializer that strips sensitive fields (e.g. `APICallError.requestBodyValues`, which holds the system prompt) before they reach the client.
 *
 * @returns {ReturnType<typeof registerApiRoute>} A registered API route handler
 *
 * @throws {Error} When path doesn't include `:agentId` and no fixed agent is specified
+* @throws {RangeError} When `heartbeatMs` is `NaN`, positive infinity, or greater than 2,147,483,647
 * @throws {Error} When agent ID is missing at runtime
 * @throws {Error} When specified agent is not found in Mastra instance
 *
@@ -10667,12 +10864,13 @@ async function handleChatStream({ mastra, agentId, agentVersion, params, default
 * @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
+* - The response is a Server-Sent Events (SSE) stream compatible with the selected AI SDK version
 * - 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
 */
-function chatRoute({ path = "/chat/:agentId", agent, defaultOptions, experimentalTransform, version = "v5", agentVersion, sendStart = true, sendFinish = true, sendReasoning = false, sendSources = false, onError }) {
+function chatRoute({ path = "/chat/:agentId", agent, defaultOptions, experimentalTransform, version = "v5", agentVersion, sendStart = true, sendFinish = true, sendReasoning = false, sendSources = false, heartbeatMs, onError }) {
 	if (!agent && !path.includes("/:agentId")) throw new Error("Path must include :agentId to route to the correct agent or pass the agent explicitly");
+	assertValidHeartbeatMs(heartbeatMs);
 	return registerApiRoute(path, {
 		method: "POST",
 		openapi: {
@@ -10801,11 +10999,13 @@ function chatRoute({ path = "/chat/:agentId", agent, defaultOptions, experimenta
 				sendSources,
 				onError
 			};
-			if (version === "v6") return createUIMessageStreamResponse({ stream: await handleChatStream({
+			let response;
+			if (version === "v6") response = createUIMessageStreamResponse({ stream: await handleChatStream({
 				...handlerOptions,
 				version: "v6"
 			}) });
-			return createUIMessageStreamResponse$1({ stream: await handleChatStream(handlerOptions) });
+			else response = createUIMessageStreamResponse$1({ stream: await handleChatStream(handlerOptions) });
+			return withSseHeartbeat(response, heartbeatMs);
 		}
 	});
 }