@mastra/client-js 1.57.0-alpha.0 → 1.57.0-alpha.2

package/dist/docs/SKILL.md

@@ -3,7 +3,7 @@ name: mastra-client-js
 description: Documentation for @mastra/client-js. Use when working with @mastra/client-js APIs, configuration, or implementation.
 metadata:
   package: "@mastra/client-js"
-  version: "1.57.0-alpha.0"
+  version: "1.57.0-alpha.2"
 ---
 
 ## When to use

package/dist/docs/assets/SOURCE_MAP.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.57.0-alpha.0",
+  "version": "1.57.0-alpha.2",
   "package": "@mastra/client-js",
   "exports": {},
   "modules": {}

package/dist/docs/references/reference-client-js-agent-controller.md

@@ -177,7 +177,7 @@ Switches the active mode.
 
 ### `switchModel(modelId, options?)`
 
-Switches the session's active model and persists it as the current model for the active thread. Switching modes doesn't change it. Pass `{ thinkingLevel }` as the second argument to apply and persist a thinking level with the model.
+Switches the session's active model and persists it as the current model for the active thread, independently of mode changes. Pass `{ thinkingLevel }` as the second argument to apply and persist a thinking level with the model.
 
 ```typescript
 await session.switchModel('anthropic/claude-sonnet-5-5', {

package/dist/docs/references/reference-client-js-agents.md

@@ -351,6 +351,22 @@ const { messages, initialHistoryPagination } = useChat({
 
 The subscription also exposes `abort(options?)` and `unsubscribe()`. `await subscription.abort({ clearPendingSignals: true })` requests an abort and clears pending signals without closing the subscription. Omit the flag to preserve pending input. `unsubscribe()` closes the subscription without aborting the run.
 
+### `abortRun(runId)`
+
+Requests cancellation of a durable run by its ID, including a run without a memory thread. Cancelling the response body or aborting the client-wide `abortSignal` only disconnects the observer from durable execution. A per-call `abortSignal` passed to a streaming method requests cancellation for you. Use `abortRun()` to stop a run without that signal.
+
+```typescript
+const runId = crypto.randomUUID()
+const response = await agent.stream('Research this topic', { runId })
+
+// When the user chooses Stop:
+const { aborted } = await agent.abortRun(runId)
+```
+
+**runId** (`string`): ID of the durable run to cancel.
+
+Returns `{ aborted: boolean }`. A remote abort request is asynchronous, so `true` doesn't confirm that the worker has stopped. Unknown or completed runs return `false`. This method requires a durable agent and Agent execution permission. Run ownership checks apply. Runs with memory threads also require `memory:write` permission when fine-grained authorization is enabled. Non-durable agents return HTTP 501.
+
 ### `abortThread()`
 
 Requests cancellation of the thread's active run. Set `clearPendingSignals: true` to clear pending signals before aborting.
@@ -748,7 +764,7 @@ response.processDataStream({
 
 ### Shape client tool output for the model
 
-Client tools support `toModelOutput` to control what the model receives, including multimodal content such as images. Because client tools execute locally, the mapping also runs on the client after `execute` completes. The transformed output is sent back to the server alongside the raw result, so the raw result stays available for storage and application logic.
+Client tools support `toModelOutput` to control what the model receives, including multimodal content such as images. Because client tools execute locally, the mapping also runs on the client after `execute` completes. The client sends both the transformed output and the raw result back to the server, keeping the raw result available for storage and application logic.
 
 ```typescript
 const screenshotTool = createTool({

package/dist/docs/references/reference-client-js-datasets.md

@@ -130,7 +130,7 @@ Submitting to an experiment that has a target returns a `400`. Submitting after
 
 ## finalizeExperiment()
 
-Marks a caller-driven experiment completed. The server computes per-item counts from the persisted result rows, so the caller keeps no bookkeeping: `succeededCount` (at least one attempt without an error), `failedCount` (every attempt errored), and `skippedCount` (never submitted). Idempotent: finalizing an already-completed experiment returns the stored record.
+Marks a caller-driven experiment completed. The server handles bookkeeping for the caller by computing per-item counts from the persisted result rows: `succeededCount` (at least one attempt without an error), `failedCount` (every attempt errored), and `skippedCount` (never submitted). Idempotent: finalizing an already-completed experiment returns the stored record.
 
 **datasetId** (`string`): ID of the dataset the experiment runs against.
 

package/dist/index.cjs

@@ -1080,11 +1080,51 @@ function processClientTools(clientTools) {
 	}));
 }
 //#endregion
+//#region src/utils/sse-event-splitter.ts
+/** Split SSE events without rescanning or copying an unfinished event on each read. */
+function createSseEventSplitter() {
+	let parts = [];
+	let pendingNewline = false;
+	return (text, isFinal = false) => {
+		const events = [];
+		let start = 0;
+		if (text) {
+			if (pendingNewline) {
+				if (text.startsWith("\n")) {
+					events.push(parts.join(""));
+					parts = [];
+					start = 1;
+				} else parts.push("\n");
+				pendingNewline = false;
+			}
+			let separator;
+			while ((separator = text.indexOf("\n\n", start)) !== -1) {
+				parts.push(text.slice(start, separator));
+				events.push(parts.join(""));
+				parts = [];
+				start = separator + 2;
+			}
+			if (start < text.length) {
+				pendingNewline = text.endsWith("\n");
+				const end = pendingNewline ? text.length - 1 : text.length;
+				if (start < end) parts.push(text.slice(start, end));
+			}
+		}
+		if (isFinal) {
+			if (pendingNewline) parts.push("\n");
+			events.push(parts.join(""));
+			parts = [];
+			pendingNewline = false;
+		}
+		return events;
+	};
+}
+//#endregion
 //#region src/utils/process-mastra-stream.ts
 async function sharedProcessMastraStream({ stream, onChunk, signal }) {
 	const reader = stream.getReader();
 	const decoder = new TextDecoder();
-	let buffer = "";
+	const splitEvents = createSseEventSplitter();
 	const abort = () => void reader.cancel();
 	if (signal?.aborted) abort();
 	else signal?.addEventListener("abort", abort, { once: true });
@@ -1092,9 +1132,7 @@ async function sharedProcessMastraStream({ stream, onChunk, signal }) {
 		while (true) {
 			const { done, value } = await reader.read();
 			if (done) break;
-			buffer += decoder.decode(value, { stream: true });
-			const lines = buffer.split("\n\n");
-			buffer = lines.pop() || "";
+			const lines = splitEvents(decoder.decode(value, { stream: true }));
 			for (const line of lines) if (line.startsWith("data: ")) {
 				const data = line.slice(6);
 				if (data === "[DONE]") return;
@@ -1894,10 +1932,18 @@ var Agent = class extends BaseResource {
 		};
 		return streamResponse;
 	}
-	async abortThread(params) {
+	/** Stops execution of a run, including runs without a memory thread. */
+	async abortRun(runId, options) {
+		return this.request(`/agents/${this.agentId}/runs/${encodeURIComponent(runId)}/abort`, {
+			method: "POST",
+			signal: options?.signal
+		});
+	}
+	async abortThread(params, options) {
 		const { resourceId, threadId, clearPendingSignals, expectedRunId } = params;
 		return this.request(`/agents/${this.agentId}/threads/abort`, {
 			method: "POST",
+			signal: options?.signal,
 			body: {
 				resourceId,
 				threadId,
@@ -2631,10 +2677,11 @@ var Agent = class extends BaseResource {
 	}
 	/**
 	* Creates the consumer-facing stream for the streaming methods. Cancelling the
-	* returned stream (or aborting `externalSignal`) aborts the underlying request
-	* and stops any client-tool continuations.
+	* returned stream or the client-wide signal detaches the HTTP observer and
+	* stops any client-tool continuations. Per-call execution cancellation is
+	* handled separately by processStreamResponse.
 	*/
-	createCancellableStream(externalSignal) {
+	createCancellableStream() {
 		const abortController = new AbortController();
 		let readableController;
 		return {
@@ -2647,10 +2694,63 @@ var Agent = class extends BaseResource {
 				}
 			}),
 			controller: readableController,
-			signal: mergeAbortSignals(abortController.signal, externalSignal, this.options.abortSignal)
+			signal: mergeAbortSignals(abortController.signal, this.options.abortSignal)
 		};
 	}
 	async processStreamResponse(processedParams, controller, route = "stream", signal) {
+		const suppliedRunId = processedParams.runId;
+		processedParams = {
+			...processedParams,
+			runId: processedParams.runId ?? (0, _lukeed_uuid.v4)()
+		};
+		const callerSignal = processedParams.abortSignal;
+		callerSignal?.throwIfAborted();
+		const transportAbort = new AbortController();
+		const cancellationAbort = new AbortController();
+		const detachSignal = signal;
+		signal = mergeAbortSignals(detachSignal, transportAbort.signal);
+		let cancellationTimer;
+		const stopCancellation = () => cancellationAbort.abort();
+		const cancelExecution = () => {
+			cancellationTimer = setTimeout(() => cancellationAbort.abort(/* @__PURE__ */ new Error("Agent run cancellation was not acknowledged")), 1e4);
+			(async () => {
+				try {
+					while (true) {
+						cancellationAbort.signal.throwIfAborted();
+						if ((await this.abortRun(processedParams.runId, { signal: cancellationAbort.signal })).aborted) return;
+						await new Promise((resolve, reject) => {
+							const onAbort = () => {
+								clearTimeout(timer);
+								reject(cancellationAbort.signal.reason);
+							};
+							const timer = setTimeout(() => {
+								cancellationAbort.signal.removeEventListener("abort", onAbort);
+								resolve();
+							}, 100);
+							cancellationAbort.signal.addEventListener("abort", onAbort, { once: true });
+							if (cancellationAbort.signal.aborted) onAbort();
+						});
+					}
+				} catch (error) {
+					if (!cancellationAbort.signal.aborted && !(error instanceof Error && "status" in error && (error.status === 404 || error.status === 501))) try {
+						controller.error(error);
+					} catch {}
+				} finally {
+					clearTimeout(cancellationTimer);
+					transportAbort.abort(callerSignal?.reason);
+				}
+			})();
+		};
+		const cleanupCancellation = () => {
+			callerSignal?.removeEventListener("abort", cancelExecution);
+			detachSignal?.removeEventListener("abort", stopCancellation);
+			clearTimeout(cancellationTimer);
+			stopCancellation();
+		};
+		detachSignal?.addEventListener("abort", stopCancellation, { once: true });
+		if (detachSignal?.aborted) stopCancellation();
+		callerSignal?.addEventListener("abort", cancelExecution, { once: true });
+		if (callerSignal?.aborted) cancelExecution();
 		const { memory } = processedParams ?? {};
 		const { resource, thread } = memory ?? {};
 		const threadId = processedParams.threadId ?? (typeof thread === "string" ? thread : thread?.id);
@@ -2667,9 +2767,15 @@ var Agent = class extends BaseResource {
 			body: requestBody,
 			stream: true,
 			signal
+		}).catch((error) => {
+			cleanupCancellation();
+			throw error;
 		});
-		if (!response.body) throw new Error("No response body");
-		const isAborted = () => Boolean(signal?.aborted);
+		if (!response.body) {
+			cleanupCancellation();
+			throw new Error("No response body");
+		}
+		const isAborted = () => Boolean(signal?.aborted || callerSignal?.aborted);
 		const isAbortError = (error) => isAborted() || error?.name === "AbortError";
 		const safeClose = () => {
 			try {
@@ -2682,18 +2788,16 @@ var Agent = class extends BaseResource {
 		};
 		try {
 			let messages = [];
-			let streamRunId = processedParams.runId;
+			let streamRunId = suppliedRunId;
 			let finishedHistory;
 			let suspended = false;
 			const resumedToolCallIds = /* @__PURE__ */ new Set();
 			const releaseOpenStream = streamRunId ? this.trackOpenStream(streamRunId) : () => {};
 			const [streamForController, streamForProcessing] = response.body.tee();
 			const decoder = new TextDecoder();
-			let pendingText = "";
+			const splitEvents = createSseEventSplitter();
 			const enqueueReadableText = (text, isFinal = false) => {
-				pendingText += text;
-				const lines = pendingText.split("\n\n");
-				pendingText = isFinal ? "" : lines.pop() ?? "";
+				const lines = splitEvents(text, isFinal);
 				for (const line of lines) {
 					if (!line.startsWith("data: ") || !line.includes("\"type\":\"finish\"")) continue;
 					try {
@@ -2900,10 +3004,12 @@ var Agent = class extends BaseResource {
 				} catch {}
 				safeClose();
 			}).finally(() => {
+				cleanupCancellation();
 				signal?.removeEventListener("abort", onAbort);
 				releaseOpenStream();
 			});
 		} catch (error) {
+			cleanupCancellation();
 			if (!isAbortError(error)) console.error("Error processing stream response:", error);
 		}
 		return response;
@@ -3001,7 +3107,7 @@ var Agent = class extends BaseResource {
 			clientTools: processClientTools(params.clientToolsResolver?.() ?? params.clientTools),
 			structuredOutput
 		};
-		const { readable, controller: readableController, signal } = this.createCancellableStream(params.abortSignal);
+		const { readable, controller: readableController, signal } = this.createCancellableStream();
 		const response = await this.processStreamResponse(processedParams, readableController, "stream", signal);
 		const streamResponse = new Response(readable, {
 			status: response.status,
@@ -3032,7 +3138,7 @@ var Agent = class extends BaseResource {
 			clientTools: processClientTools(params.clientToolsResolver?.() ?? params.clientTools),
 			structuredOutput
 		};
-		const { readable, controller: readableController, signal } = this.createCancellableStream(params.abortSignal);
+		const { readable, controller: readableController, signal } = this.createCancellableStream();
 		const response = await this.processStreamResponse(processedParams, readableController, "stream-until-idle", signal);
 		const streamResponse = new Response(readable, {
 			status: response.status,
@@ -3076,7 +3182,7 @@ var Agent = class extends BaseResource {
 			requestContext: parseClientRequestContext(requestContext),
 			clientTools: processClientTools(executableClientTools)
 		};
-		const { readable, controller: readableController, signal } = this.createCancellableStream(params.abortSignal);
+		const { readable, controller: readableController, signal } = this.createCancellableStream();
 		const response = await this.processStreamResponse(processedParams, readableController, "approve-tool-call", signal).catch((error) => {
 			releaseHold({ force: true });
 			throw error;
@@ -3113,7 +3219,7 @@ var Agent = class extends BaseResource {
 			requestContext: parseClientRequestContext(requestContext),
 			clientTools: processClientTools(executableClientTools)
 		};
-		const { readable, controller: readableController, signal } = this.createCancellableStream(params.abortSignal);
+		const { readable, controller: readableController, signal } = this.createCancellableStream();
 		const response = await this.processStreamResponse(processedParams, readableController, "decline-tool-call", signal).catch((error) => {
 			releaseHold({ force: true });
 			throw error;
@@ -3189,7 +3295,7 @@ var Agent = class extends BaseResource {
 				schema: (0, _mastra_schema_compat_schema.standardSchemaToJSONSchema)((0, _mastra_schema_compat_schema.toStandardSchema)(options.structuredOutput.schema))
 			} : void 0
 		};
-		const { readable, controller: readableController, signal } = this.createCancellableStream(options.abortSignal);
+		const { readable, controller: readableController, signal } = this.createCancellableStream();
 		const response = await this.processStreamResponse(processedParams, readableController, "resume-stream", signal).catch((error) => {
 			releaseHold({ force: true });
 			throw error;
@@ -3258,7 +3364,7 @@ var Agent = class extends BaseResource {
 				schema: (0, _mastra_schema_compat_schema.standardSchemaToJSONSchema)((0, _mastra_schema_compat_schema.toStandardSchema)(options.structuredOutput.schema))
 			} : void 0
 		};
-		const { readable, controller: readableController, signal } = this.createCancellableStream(options.abortSignal);
+		const { readable, controller: readableController, signal } = this.createCancellableStream();
 		const response = await this.processStreamResponse(processedParams, readableController, "resume-stream-until-idle", signal).catch((error) => {
 			releaseHold({ force: true });
 			throw error;
@@ -4416,7 +4522,7 @@ var Workflow = class extends BaseResource {
 	*/
 	async createRun(params) {
 		const searchParams = new URLSearchParams();
-		if (!!params?.runId) searchParams.set("runId", params.runId);
+		if (params?.runId) searchParams.set("runId", params.runId);
 		const res = await this.request(`/workflows/${this.workflowId}/create-run?${searchParams.toString()}`, {
 			method: "POST",
 			body: {
@@ -4974,7 +5080,7 @@ var AgentBuilder = class extends BaseResource {
 	*/
 	async createRun(params) {
 		const searchParams = new URLSearchParams();
-		if (!!params?.runId) searchParams.set("runId", params.runId);
+		if (params?.runId) searchParams.set("runId", params.runId);
 		const url = `/agent-builder/${this.actionId}/create-run${searchParams.toString() ? `?${searchParams.toString()}` : ""}`;
 		return this.request(url, { method: "POST" });
 	}