@mastra/client-js 1.56.0-alpha.8 → 1.56.0

package/dist/index.js

@@ -59,15 +59,16 @@ function attributesToOtlp(attrs) {
 			key,
 			value: { boolValue: raw }
 		});
-		else if (typeof raw === "number") if (Number.isInteger(raw)) out.push({
-			key,
-			value: { intValue: raw }
-		});
-		else out.push({
-			key,
-			value: { doubleValue: raw }
-		});
-		else try {
+		else if (typeof raw === "number") {
+			if (Number.isInteger(raw)) out.push({
+				key,
+				value: { intValue: raw }
+			});
+			else out.push({
+				key,
+				value: { doubleValue: raw }
+			});
+		} else try {
 			out.push({
 				key,
 				value: { stringValue: JSON.stringify(raw) }
@@ -662,7 +663,6 @@ function fixJson(input) {
 				stack.pop();
 				stack.push(swapState);
 				stack.push("INSIDE_ARRAY_START");
-				break;
 		}
 	}
 	function processAfterObjectValue(char, i) {
@@ -674,7 +674,6 @@ function fixJson(input) {
 			case "}":
 				lastValidIndex = i;
 				stack.pop();
-				break;
 		}
 	}
 	function processAfterArrayValue(char, i) {
@@ -686,7 +685,6 @@ function fixJson(input) {
 			case "]":
 				lastValidIndex = i;
 				stack.pop();
-				break;
 		}
 	}
 	for (let i = 0; i < input.length; i++) {
@@ -704,7 +702,6 @@ function fixJson(input) {
 					case "}":
 						lastValidIndex = i;
 						stack.pop();
-						break;
 				}
 				break;
 			case "INSIDE_OBJECT_AFTER_COMMA":
@@ -712,7 +709,6 @@ function fixJson(input) {
 					case "\"":
 						stack.pop();
 						stack.push("INSIDE_OBJECT_KEY");
-						break;
 				}
 				break;
 			case "INSIDE_OBJECT_KEY":
@@ -720,7 +716,6 @@ function fixJson(input) {
 					case "\"":
 						stack.pop();
 						stack.push("INSIDE_OBJECT_AFTER_KEY");
-						break;
 				}
 				break;
 			case "INSIDE_OBJECT_AFTER_KEY":
@@ -728,7 +723,6 @@ function fixJson(input) {
 					case ":":
 						stack.pop();
 						stack.push("INSIDE_OBJECT_BEFORE_VALUE");
-						break;
 				}
 				break;
 			case "INSIDE_OBJECT_BEFORE_VALUE":
@@ -758,7 +752,6 @@ function fixJson(input) {
 					default:
 						lastValidIndex = i;
 						processValueStart(char, i, "INSIDE_ARRAY_AFTER_VALUE");
-						break;
 				}
 				break;
 			case "INSIDE_ARRAY_AFTER_VALUE":
@@ -771,9 +764,7 @@ function fixJson(input) {
 						lastValidIndex = i;
 						stack.pop();
 						break;
-					default:
-						lastValidIndex = i;
-						break;
+					default: lastValidIndex = i;
 				}
 				break;
 			case "INSIDE_ARRAY_AFTER_COMMA":
@@ -814,9 +805,7 @@ function fixJson(input) {
 						stack.pop();
 						if (stack[stack.length - 1] === "INSIDE_ARRAY_AFTER_VALUE") processAfterArrayValue(char, i);
 						break;
-					default:
-						stack.pop();
-						break;
+					default: stack.pop();
 				}
 				break;
 			case "INSIDE_LITERAL": {
@@ -1225,8 +1214,16 @@ var BaseResource = class {
 };
 //#endregion
 //#region src/resources/agent.ts
-const SIGNAL_RUNTIME_OPTIONS_TTL_MS = 300 * 1e3;
+const SIGNAL_RUNTIME_OPTIONS_TTL_MS = 3e5;
 const signalRuntimeOptionsByRunId = /* @__PURE__ */ new Map();
+/**
+* Client tools a resume request can execute, keyed by run. The stream that stayed open from
+* before the suspension must not run those tools again, but it must run any resumed client tool
+* the resume request cannot execute (a server-side approve sends no client tools). Held until the
+* last stream of the run closes, which is after the resume request returns.
+*/
+const resumingClientToolNamesByRunKey = /* @__PURE__ */ new Map();
+const openStreamCountByRunKey = /* @__PURE__ */ new Map();
 const latestSignalRuntimeOptionsByThread = /* @__PURE__ */ new Map();
 const createSignalRuntimeOptionsEntry = (store, key, streamOptions) => {
 	const timeout = setTimeout(() => store.delete(key), SIGNAL_RUNTIME_OPTIONS_TTL_MS);
@@ -1419,6 +1416,49 @@ var Agent = class extends BaseResource {
 	getSignalRuntimeRunKey(runId) {
 		return `${this.options.baseUrl}|${this.apiPrefix}|${this.agentId}|${runId}`;
 	}
+	/**
+	* Records that `runId` is being resumed by a request that can execute these client tools, so the
+	* stream that is still open from before the suspension skips them. Released when the last stream
+	* of the run closes, which is after this request returns.
+	*/
+	holdResumingClientTools(runId, clientTools) {
+		const names = Object.entries(clientTools ?? {}).filter(([, tool]) => typeof tool.execute === "function").map(([name]) => name);
+		if (names.length === 0) return () => {};
+		const key = this.getSignalRuntimeRunKey(runId);
+		const held = resumingClientToolNamesByRunKey.get(key) ?? /* @__PURE__ */ new Map();
+		for (const name of names) held.set(name, (held.get(name) ?? 0) + 1);
+		resumingClientToolNamesByRunKey.set(key, held);
+		let released = false;
+		return ({ force = false } = {}) => {
+			if (released || !force && openStreamCountByRunKey.has(key)) return;
+			released = true;
+			const current = resumingClientToolNamesByRunKey.get(key);
+			if (!current) return;
+			for (const name of names) {
+				const count = (current.get(name) ?? 1) - 1;
+				if (count > 0) current.set(name, count);
+				else current.delete(name);
+			}
+			if (current.size === 0) resumingClientToolNamesByRunKey.delete(key);
+		};
+	}
+	/** Drops the held tool names when the last stream of the run closes. */
+	trackOpenStream(runId) {
+		const key = this.getSignalRuntimeRunKey(runId);
+		openStreamCountByRunKey.set(key, (openStreamCountByRunKey.get(key) ?? 0) + 1);
+		let released = false;
+		return () => {
+			if (released) return;
+			released = true;
+			const remaining = (openStreamCountByRunKey.get(key) ?? 1) - 1;
+			if (remaining > 0) {
+				openStreamCountByRunKey.set(key, remaining);
+				return;
+			}
+			openStreamCountByRunKey.delete(key);
+			resumingClientToolNamesByRunKey.delete(key);
+		};
+	}
 	getSignalRuntimeThreadKey({ resourceId, threadId }) {
 		if (!threadId) return void 0;
 		return `${this.options.baseUrl}|${this.apiPrefix}|${this.agentId}|${resourceId ?? ""}|${threadId}`;
@@ -2556,7 +2596,6 @@ var Agent = class extends BaseResource {
 					case "finish":
 						finishReason = chunk.payload?.stepResult?.reason ?? finishReason;
 						if (chunk.payload?.usage != null) usage = chunk.payload.usage;
-						break;
 				}
 			}
 		});
@@ -2621,6 +2660,9 @@ var Agent = class extends BaseResource {
 			let messages = [];
 			let streamRunId = processedParams.runId;
 			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 = "";
@@ -2689,6 +2731,9 @@ var Agent = class extends BaseResource {
 							});
 						}
 						const executableToolCalls = [...toolInvocationsById.values()].filter((toolCall) => {
+							if (resumedToolCallIds.has(toolCall.toolCallId)) {
+								if ((streamRunId ? resumingClientToolNamesByRunKey.get(this.getSignalRuntimeRunKey(streamRunId)) : void 0)?.has(toolCall.toolName)) return false;
+							}
 							const clientTool = processedParams.clientTools?.[toolCall.toolName];
 							return Boolean(clientTool?.execute);
 						});
@@ -2815,6 +2860,12 @@ var Agent = class extends BaseResource {
 				},
 				onStreamChunk: (chunk) => {
 					if (!streamRunId && typeof chunk.runId === "string") streamRunId = chunk.runId;
+					if (chunk.type === "tool-call-approval" || chunk.type === "tool-call-suspended") suspended = true;
+					else if (suspended && chunk.type === "tool-call" && typeof chunk.payload?.toolCallId === "string") {
+						const toolName = chunk.payload.toolName;
+						const held = streamRunId ? resumingClientToolNamesByRunKey.get(this.getSignalRuntimeRunKey(streamRunId)) : void 0;
+						if (typeof toolName === "string" && held?.has(toolName)) resumedToolCallIds.add(chunk.payload.toolCallId);
+					}
 				},
 				lastMessage: void 0
 			}).catch(async (error) => {
@@ -2825,6 +2876,7 @@ var Agent = class extends BaseResource {
 				safeClose();
 			}).finally(() => {
 				signal?.removeEventListener("abort", onAbort);
+				releaseOpenStream();
 			});
 		} catch (error) {
 			if (!isAbortError(error)) console.error("Error processing stream response:", error);
@@ -2992,13 +3044,18 @@ var Agent = class extends BaseResource {
 	}
 	async approveToolCall(params) {
 		const { requestContext, ...rest } = params;
+		const executableClientTools = params.clientToolsResolver?.() ?? params.clientTools;
+		const releaseHold = this.holdResumingClientTools(rest.runId, executableClientTools);
 		const processedParams = {
 			...rest,
 			requestContext: parseClientRequestContext(requestContext),
-			clientTools: processClientTools(params.clientToolsResolver?.() ?? params.clientTools)
+			clientTools: processClientTools(executableClientTools)
 		};
 		const { readable, controller: readableController, signal } = this.createCancellableStream(params.abortSignal);
-		const response = await this.processStreamResponse(processedParams, readableController, "approve-tool-call", signal);
+		const response = await this.processStreamResponse(processedParams, readableController, "approve-tool-call", signal).catch((error) => {
+			releaseHold({ force: true });
+			throw error;
+		});
 		const streamResponse = new Response(readable, {
 			status: response.status,
 			statusText: response.statusText,
@@ -3024,13 +3081,18 @@ var Agent = class extends BaseResource {
 	}
 	async declineToolCall(params) {
 		const { requestContext, ...rest } = params;
+		const executableClientTools = params.clientToolsResolver?.() ?? params.clientTools;
+		const releaseHold = this.holdResumingClientTools(rest.runId, executableClientTools);
 		const processedParams = {
 			...rest,
 			requestContext: parseClientRequestContext(requestContext),
-			clientTools: processClientTools(params.clientToolsResolver?.() ?? params.clientTools)
+			clientTools: processClientTools(executableClientTools)
 		};
 		const { readable, controller: readableController, signal } = this.createCancellableStream(params.abortSignal);
-		const response = await this.processStreamResponse(processedParams, readableController, "decline-tool-call", signal);
+		const response = await this.processStreamResponse(processedParams, readableController, "decline-tool-call", signal).catch((error) => {
+			releaseHold({ force: true });
+			throw error;
+		});
 		const streamResponse = new Response(readable, {
 			status: response.status,
 			statusText: response.statusText,
@@ -3090,18 +3152,23 @@ var Agent = class extends BaseResource {
 	* Used to continue execution after a suspension point (e.g., workflow suspend within an agent).
 	*/
 	async resumeStream(resumeData, options) {
+		const executableClientTools = options.clientToolsResolver?.() ?? options.clientTools;
+		const releaseHold = this.holdResumingClientTools(options.runId, executableClientTools);
 		const processedParams = {
 			...options,
 			resumeData,
 			requestContext: parseClientRequestContext(options.requestContext),
-			clientTools: processClientTools(options.clientToolsResolver?.() ?? options.clientTools),
+			clientTools: processClientTools(executableClientTools),
 			structuredOutput: options.structuredOutput ? {
 				...options.structuredOutput,
 				schema: standardSchemaToJSONSchema(toStandardSchema(options.structuredOutput.schema))
 			} : void 0
 		};
 		const { readable, controller: readableController, signal } = this.createCancellableStream(options.abortSignal);
-		const response = await this.processStreamResponse(processedParams, readableController, "resume-stream", signal);
+		const response = await this.processStreamResponse(processedParams, readableController, "resume-stream", signal).catch((error) => {
+			releaseHold({ force: true });
+			throw error;
+		});
 		const streamResponse = new Response(readable, {
 			status: response.status,
 			statusText: response.statusText,
@@ -3154,18 +3221,23 @@ var Agent = class extends BaseResource {
 	* Used to continue execution after a suspension point (e.g., workflow suspend within an agent).
 	*/
 	async resumeStreamUntilIdle(resumeData, options) {
+		const executableClientTools = options.clientToolsResolver?.() ?? options.clientTools;
+		const releaseHold = this.holdResumingClientTools(options.runId, executableClientTools);
 		const processedParams = {
 			...options,
 			resumeData,
 			requestContext: parseClientRequestContext(options.requestContext),
-			clientTools: processClientTools(options.clientToolsResolver?.() ?? options.clientTools),
+			clientTools: processClientTools(executableClientTools),
 			structuredOutput: options.structuredOutput ? {
 				...options.structuredOutput,
 				schema: standardSchemaToJSONSchema(toStandardSchema(options.structuredOutput.schema))
 			} : void 0
 		};
 		const { readable, controller: readableController, signal } = this.createCancellableStream(options.abortSignal);
-		const response = await this.processStreamResponse(processedParams, readableController, "resume-stream-until-idle", signal);
+		const response = await this.processStreamResponse(processedParams, readableController, "resume-stream-until-idle", signal).catch((error) => {
+			releaseHold({ force: true });
+			throw error;
+		});
 		const streamResponse = new Response(readable, {
 			status: response.status,
 			statusText: response.statusText,
@@ -3185,20 +3257,32 @@ var Agent = class extends BaseResource {
 	*/
 	async approveToolCallGenerate(params) {
 		const { requestContext, clientTools, clientToolsResolver, memory, ...rest } = params;
-		const response = await this.request(`/agents/${this.agentId}/approve-tool-call-generate`, {
-			method: "POST",
-			body: {
-				...rest,
-				requestContext: parseClientRequestContext(requestContext),
-				clientTools: processClientTools(clientToolsResolver?.() ?? clientTools)
-			}
-		});
-		return this.continueResumedGenerate(response, {
-			requestContext,
-			clientTools,
-			clientToolsResolver,
-			memory
-		});
+		const executableClientTools = clientToolsResolver?.() ?? clientTools;
+		const releaseHold = this.holdResumingClientTools(rest.runId, executableClientTools);
+		let response;
+		try {
+			response = await this.request(`/agents/${this.agentId}/approve-tool-call-generate`, {
+				method: "POST",
+				body: {
+					...rest,
+					requestContext: parseClientRequestContext(requestContext),
+					clientTools: processClientTools(executableClientTools)
+				}
+			});
+		} catch (error) {
+			releaseHold({ force: true });
+			throw error;
+		}
+		try {
+			return await this.continueResumedGenerate(response, {
+				requestContext,
+				clientTools: executableClientTools,
+				clientToolsResolver,
+				memory
+			});
+		} finally {
+			releaseHold();
+		}
 	}
 	/**
 	* Declines a pending tool call and returns the complete response (non-streaming).
@@ -3206,20 +3290,32 @@ var Agent = class extends BaseResource {
 	*/
 	async declineToolCallGenerate(params) {
 		const { requestContext, clientTools, clientToolsResolver, memory, ...rest } = params;
-		const response = await this.request(`/agents/${this.agentId}/decline-tool-call-generate`, {
-			method: "POST",
-			body: {
-				...rest,
-				requestContext: parseClientRequestContext(requestContext),
-				clientTools: processClientTools(clientToolsResolver?.() ?? clientTools)
-			}
-		});
-		return this.continueResumedGenerate(response, {
-			requestContext,
-			clientTools,
-			clientToolsResolver,
-			memory
-		});
+		const executableClientTools = clientToolsResolver?.() ?? clientTools;
+		const releaseHold = this.holdResumingClientTools(rest.runId, executableClientTools);
+		let response;
+		try {
+			response = await this.request(`/agents/${this.agentId}/decline-tool-call-generate`, {
+				method: "POST",
+				body: {
+					...rest,
+					requestContext: parseClientRequestContext(requestContext),
+					clientTools: processClientTools(executableClientTools)
+				}
+			});
+		} catch (error) {
+			releaseHold({ force: true });
+			throw error;
+		}
+		try {
+			return await this.continueResumedGenerate(response, {
+				requestContext,
+				clientTools: executableClientTools,
+				clientToolsResolver,
+				memory
+			});
+		} finally {
+			releaseHold();
+		}
 	}
 	/**
 	* Runs executable client tools the model called after an approval decision and continues on
@@ -4444,7 +4540,8 @@ async function verifyAgentCardSignatureIfPresent(agentCard, options) {
 			index
 		});
 		if (!verificationKey) throw new Error("No verification key was provided for Agent Card signature verification");
-		await compactVerify(compactJws, await importVerificationKey(verificationKey, protectedHeader.alg), { algorithms: allowedAlgorithms });
+		const importedKey = await importVerificationKey(verificationKey, protectedHeader.alg);
+		await compactVerify(compactJws, importedKey, { algorithms: allowedAlgorithms });
 		return agentCard;
 	} catch (error) {
 		verificationErrors.push(error instanceof Error ? error.message : "Unknown verification failure");
@@ -6776,48 +6873,40 @@ function hydrateEventTimestamps(event) {
 	return isKnownParsedEvent(event) ? hydrateKnownEvent(event) : event;
 }
 /**
-* A session bound to a `resourceId` within one agent controller. Sessions are
-* get-or-create on the server, so re-creating the same resourceId (and scope)
-* resumes the existing conversation rather than forking it.
-*
-* Pass a `scope` to address an independent session over the same resourceId:
-* two sessions with the same resourceId but different scopes have their own
-* run loop, thread binding, and mode/model/state (e.g. one session per git
-* worktree, with the worktree path as the scope). The scope travels on every
-* request as a `sessionScope` query param.
+* A session addressed by its `sessionId` within one agent controller. Sessions
+* are get-or-create on the server, so re-creating the same sessionId resumes
+* the existing conversation rather than forking it. Many sessions can work on
+* one `resourceId` (whose threads and memory they use); each has its own run
+* loop, thread binding, and mode/model/state.
 */
 var AgentControllerSession = class extends BaseResource {
 	controllerId;
-	resourceId;
-	scope;
-	constructor(options, controllerId, resourceId, scope) {
+	sessionId;
+	constructor(options, controllerId, sessionId) {
 		super(options);
 		this.controllerId = controllerId;
-		this.resourceId = resourceId;
-		this.scope = scope;
+		this.sessionId = sessionId;
 	}
 	base() {
-		return `/agent-controller/${encodeURIComponent(this.controllerId)}/sessions/${encodeURIComponent(this.resourceId)}`;
-	}
-	/** Append this session's scope (if any) as a `sessionScope` query param. */
-	url(path) {
-		if (this.scope === void 0) return path;
-		return `${path}${path.includes("?") ? "&" : "?"}sessionScope=${encodeURIComponent(this.scope)}`;
+		return `/agent-controller/${encodeURIComponent(this.controllerId)}/sessions/${encodeURIComponent(this.sessionId)}`;
 	}
 	/**
-	* Create or resume this session. Pass `tags` to scope initial thread
-	* selection — a thread is a resume candidate only when its metadata matches
-	* every tag. Pass `threadId` to bind the session to one exact thread,
-	* creating it with that id when it does not exist.
+	* Create or resume this session. `resourceId` names whose threads and memory
+	* the session works on. Without it the server resumes the session on the
+	* resource it already has (the live session's, or the resource of the thread
+	* with the session's id), falling back to the sessionId. Pass `tags` to scope
+	* initial thread selection — a thread is a resume candidate only when its
+	* metadata matches every tag. Pass `threadId` to bind the session to one
+	* exact thread, creating it with that id when it does not exist.
 	*/
 	create(options) {
 		return this.request(`/agent-controller/${encodeURIComponent(this.controllerId)}/sessions`, {
 			method: "POST",
 			body: {
-				resourceId: this.resourceId,
+				resourceId: options?.resourceId,
+				sessionId: this.sessionId,
 				tags: options?.tags,
-				threadId: options?.threadId,
-				sessionScope: this.scope
+				threadId: options?.threadId
 			}
 		});
 	}
@@ -6873,7 +6962,7 @@ var AgentControllerSession = class extends BaseResource {
 			const abort = new AbortController();
 			currentAbort = abort;
 			let openTimer;
-			const request = this.request(this.url(`${this.base()}/stream`), {
+			const request = this.request(`${this.base()}/stream`, {
 				stream: true,
 				signal: abort.signal
 			});
@@ -7083,7 +7172,7 @@ var AgentControllerSession = class extends BaseResource {
 			files: void 0
 		} : message;
 		const requestContext = parseClientRequestContext(options?.requestContext);
-		await this.request(this.url(`${this.base()}/messages`), {
+		await this.request(`${this.base()}/messages`, {
 			method: "POST",
 			body: {
 				message: content,
@@ -7094,7 +7183,7 @@ var AgentControllerSession = class extends BaseResource {
 	}
 	/** Abort the in-flight run for this session. */
 	async abort() {
-		await this.request(this.url(`${this.base()}/abort`), { method: "POST" });
+		await this.request(`${this.base()}/abort`, { method: "POST" });
 	}
 	/**
 	* Approve or decline a pending tool call (`tool_approval_required`). Resolves
@@ -7102,7 +7191,7 @@ var AgentControllerSession = class extends BaseResource {
 	*/
 	async approveTool(toolCallId, approved, options) {
 		const requestContext = parseClientRequestContext(options?.requestContext);
-		return this.request(this.url(`${this.base()}/tool-approval`), {
+		return this.request(`${this.base()}/tool-approval`, {
 			method: "POST",
 			retries: 0,
 			body: {
@@ -7120,7 +7209,7 @@ var AgentControllerSession = class extends BaseResource {
 	*/
 	async respondToToolSuspension(toolCallId, resumeData, options) {
 		const requestContext = parseClientRequestContext(options?.requestContext);
-		return this.request(this.url(`${this.base()}/tool-suspension`), {
+		return this.request(`${this.base()}/tool-suspension`, {
 			method: "POST",
 			retries: 0,
 			body: {
@@ -7140,7 +7229,7 @@ var AgentControllerSession = class extends BaseResource {
 			files: void 0
 		} : message;
 		const requestContext = parseClientRequestContext(options?.requestContext);
-		await this.request(this.url(`${this.base()}/steer`), {
+		await this.request(`${this.base()}/steer`, {
 			method: "POST",
 			body: {
 				message: content,
@@ -7152,18 +7241,18 @@ var AgentControllerSession = class extends BaseResource {
 	/** Get the current mode, model, and thread (for initial UI hydration). */
 	state(options) {
 		const path = options?.threadId ? `${this.base()}?threadId=${encodeURIComponent(options.threadId)}` : this.base();
-		return this.request(this.url(path));
+		return this.request(path);
 	}
 	/** Merge key-value pairs into the session state. Existing keys not in the payload are preserved. */
 	async setState(updates) {
-		await this.request(this.url(`${this.base()}/state`), {
+		await this.request(`${this.base()}/state`, {
 			method: "PUT",
 			body: { state: updates }
 		});
 	}
 	/** Switch the active mode (e.g. `build`, `plan`). */
 	async switchMode(modeId) {
-		await this.request(this.url(`${this.base()}/mode`), {
+		await this.request(`${this.base()}/mode`, {
 			method: "POST",
 			body: { modeId }
 		});
@@ -7173,7 +7262,7 @@ var AgentControllerSession = class extends BaseResource {
 	* `thinkingLevel` is provided it is applied and persisted with the model.
 	*/
 	async switchModel(modelId, { thinkingLevel } = {}) {
-		await this.request(this.url(`${this.base()}/model`), {
+		await this.request(`${this.base()}/model`, {
 			method: "POST",
 			body: thinkingLevel !== void 0 ? {
 				modelId,
@@ -7194,36 +7283,36 @@ var AgentControllerSession = class extends BaseResource {
 		if (opts.limit != null) params.set("limit", String(opts.limit));
 		if (opts.tags && Object.keys(opts.tags).length > 0) params.set("tags", JSON.stringify(opts.tags));
 		const query = params.toString() ? `?${params.toString()}` : "";
-		return (await this.request(this.url(`${this.base()}/threads${query}`))).threads;
+		return (await this.request(`${this.base()}/threads${query}`)).threads;
 	}
 	/** Switch the session to an existing thread (rebinds stream + state). */
 	async switchThread(threadId) {
-		await this.request(this.url(`${this.base()}/thread`), {
+		await this.request(`${this.base()}/thread`, {
 			method: "POST",
 			body: { threadId }
 		});
 	}
 	/** Create a new thread (unbinds previous, binds the new one). */
 	async createThread(title) {
-		return this.request(this.url(`${this.base()}/threads`), {
+		return this.request(`${this.base()}/threads`, {
 			method: "POST",
 			body: { title }
 		});
 	}
 	/** Delete a thread. If it's the active thread the session unbinds. */
 	async deleteThread(threadId) {
-		await this.request(this.url(`${this.base()}/threads/${encodeURIComponent(threadId)}`), { method: "DELETE" });
+		await this.request(`${this.base()}/threads/${encodeURIComponent(threadId)}`, { method: "DELETE" });
 	}
 	/** Rename a thread. */
 	async renameThread(threadId, title) {
-		await this.request(this.url(`${this.base()}/threads/${encodeURIComponent(threadId)}`), {
+		await this.request(`${this.base()}/threads/${encodeURIComponent(threadId)}`, {
 			method: "PUT",
 			body: { title }
 		});
 	}
 	/** Clone a thread (and its messages). The session binds to the clone. */
 	async cloneThread(options) {
-		return this.request(this.url(`${this.base()}/threads/clone`), {
+		return this.request(`${this.base()}/threads/clone`, {
 			method: "POST",
 			body: options ?? {}
 		});
@@ -7244,7 +7333,7 @@ var AgentControllerSession = class extends BaseResource {
 			if (include) queryParams.set("include", JSON.stringify(include));
 		}
 		const query = queryParams.toString();
-		const body = await this.request(this.url(`${this.base()}/threads/${encodeURIComponent(threadId)}/messages${query ? `?${query}` : ""}`));
+		const body = await this.request(`${this.base()}/threads/${encodeURIComponent(threadId)}/messages${query ? `?${query}` : ""}`);
 		const messages = body.messages.map(hydrateMessage);
 		if (legacy) return messages;
 		return {
@@ -7263,7 +7352,7 @@ var AgentControllerSession = class extends BaseResource {
 			files: void 0
 		} : message;
 		const requestContext = parseClientRequestContext(options?.requestContext);
-		await this.request(this.url(`${this.base()}/follow-up`), {
+		await this.request(`${this.base()}/follow-up`, {
 			method: "POST",
 			body: {
 				message: content,
@@ -7274,26 +7363,26 @@ var AgentControllerSession = class extends BaseResource {
 	}
 	/** Get the observational memory record for this session's thread. */
 	async getOMRecord() {
-		return (await this.request(this.url(`${this.base()}/om`))).record;
+		return (await this.request(`${this.base()}/om`)).record;
 	}
 	/** Change the session's resource identity. */
 	async setResourceId(newResourceId) {
-		await this.request(this.url(`${this.base()}/resource`), {
+		await this.request(`${this.base()}/resource`, {
 			method: "POST",
 			body: { newResourceId }
 		});
 	}
 	/** Get known resource IDs for this session. */
 	async getResourceIds() {
-		return (await this.request(this.url(`${this.base()}/resources`))).resourceIds;
+		return (await this.request(`${this.base()}/resources`)).resourceIds;
 	}
 	/** Get the current goal for this session's thread. */
 	async getGoal() {
-		return (await this.request(this.url(`${this.base()}/goal`))).goal;
+		return (await this.request(`${this.base()}/goal`)).goal;
 	}
 	/** Set a new goal objective. The agent's in-loop judge evaluates progress after each turn. */
 	async setGoal(objective, options) {
-		return (await this.request(this.url(`${this.base()}/goal`), {
+		return (await this.request(`${this.base()}/goal`, {
 			method: "POST",
 			body: {
 				objective,
@@ -7303,22 +7392,22 @@ var AgentControllerSession = class extends BaseResource {
 	}
 	/** Update goal options (judge model, max runs, status). */
 	async updateGoal(options) {
-		return (await this.request(this.url(`${this.base()}/goal`), {
+		return (await this.request(`${this.base()}/goal`, {
 			method: "PUT",
 			body: options
 		})).goal;
 	}
 	/** Clear the current goal. */
 	async clearGoal() {
-		await this.request(this.url(`${this.base()}/goal`), { method: "DELETE" });
+		await this.request(`${this.base()}/goal`, { method: "DELETE" });
 	}
 	/** Get the current permission rules (per-category and per-tool policies). */
 	async getPermissions() {
-		return this.request(this.url(`${this.base()}/permissions`));
+		return this.request(`${this.base()}/permissions`);
 	}
 	/** Set the approval policy for a tool category. */
 	async setPermissionForCategory(category, policy) {
-		await this.request(this.url(`${this.base()}/permissions/category`), {
+		await this.request(`${this.base()}/permissions/category`, {
 			method: "PUT",
 			body: {
 				category,
@@ -7328,7 +7417,7 @@ var AgentControllerSession = class extends BaseResource {
 	}
 	/** Set the approval policy for a specific tool. */
 	async setPermissionForTool(toolName, policy) {
-		await this.request(this.url(`${this.base()}/permissions/tool`), {
+		await this.request(`${this.base()}/permissions/tool`, {
 			method: "PUT",
 			body: {
 				toolName,
@@ -7342,7 +7431,7 @@ var AgentControllerSession = class extends BaseResource {
 	* or is persisted for later.
 	*/
 	async sendNotification(input) {
-		return this.request(this.url(`${this.base()}/notifications`), {
+		return this.request(`${this.base()}/notifications`, {
 			method: "POST",
 			body: input
 		});
@@ -7375,12 +7464,11 @@ var AgentController = class extends BaseResource {
 		return this.request(`${this.basePath()}/workspace`);
 	}
 	/**
-	* Scope to a session bound to `resourceId` (e.g. a user or conversation id).
-	* Pass `scope` to address an independent session over the same resourceId
-	* (e.g. one session per git worktree, with the worktree path as the scope).
+	* Address the session with this `sessionId`. Sessions created without an
+	* explicit id are addressed by their `resourceId`.
 	*/
-	session(resourceId, scope) {
-		return new AgentControllerSession(this.options, this.controllerId, resourceId, scope);
+	session(sessionId) {
+		return new AgentControllerSession(this.options, this.controllerId, sessionId);
 	}
 };
 /** Pull the plain text out of an assistant message's nested content parts. */
@@ -7454,7 +7542,7 @@ var MastraClient = class extends BaseResource {
 	}
 	/**
 	* Scopes to an agent controller hosted on the connected Mastra instance. Use
-	* `getAgentController(id).session(resourceId)` to create/resume a session,
+	* `getAgentController(id).session(sessionId)` to create/resume a session,
 	* stream its events, and send messages.
 	* @param controllerId - The id the agent controller is registered under on Mastra
 	*/
@@ -7705,8 +7793,10 @@ var MastraClient = class extends BaseResource {
 		if (logLevel) searchParams.set("logLevel", logLevel);
 		if (page !== void 0) searchParams.set("page", String(page));
 		if (perPage !== void 0) searchParams.set("perPage", String(perPage));
-		if (_filters) if (Array.isArray(_filters)) for (const filter of _filters) searchParams.append("filters", filter);
-		else searchParams.set("filters", _filters);
+		if (_filters) {
+			if (Array.isArray(_filters)) for (const filter of _filters) searchParams.append("filters", filter);
+			else searchParams.set("filters", _filters);
+		}
 		if (searchParams.size) return this.request(`/logs?${searchParams}`);
 		else return this.request(`/logs`);
 	}
@@ -7726,8 +7816,10 @@ var MastraClient = class extends BaseResource {
 		if (logLevel) searchParams.set("logLevel", logLevel);
 		if (page !== void 0) searchParams.set("page", String(page));
 		if (perPage !== void 0) searchParams.set("perPage", String(perPage));
-		if (_filters) if (Array.isArray(_filters)) for (const filter of _filters) searchParams.append("filters", filter);
-		else searchParams.set("filters", _filters);
+		if (_filters) {
+			if (Array.isArray(_filters)) for (const filter of _filters) searchParams.append("filters", filter);
+			else searchParams.set("filters", _filters);
+		}
 		if (searchParams.size) return this.request(`/logs/${runId}?${searchParams}`);
 		else return this.request(`/logs/${runId}`);
 	}
@@ -7804,6 +7896,77 @@ var MastraClient = class extends BaseResource {
 		});
 	}
 	/**
+	* Lists the event types an MCP server declares (experimental).
+	* `testEmit` is true when the server serves {@link emitMcpServerEvent} (under `mastra dev`).
+	* @param serverId - The ID of the MCP server.
+	*/
+	getMcpServerEvents(serverId) {
+		return this.request(`/mcp/${encodeURIComponent(serverId)}/events`);
+	}
+	/**
+	* Reads occurrences of an MCP server event type, like the `events/poll` MCP request (experimental).
+	* Pass the returned `cursor` to the next call to resume.
+	* @param serverId - The ID of the MCP server.
+	* @param eventName - The event type name.
+	* @param body - Event arguments, resume cursor and page size.
+	*/
+	pollMcpServerEvent(serverId, eventName, body = {}) {
+		return this.request(`/mcp/${encodeURIComponent(serverId)}/events/${encodeURIComponent(eventName)}/poll`, {
+			method: "POST",
+			body
+		});
+	}
+	/**
+	* Streams occurrences of a push-capable MCP server event type (experimental).
+	* Yields an `active` frame first, then `event`, `heartbeat` and `error` frames, and ends
+	* when the server ends the stream. Abort `options.signal` or break out of the loop to stop.
+	*
+	* @example
+	* ```typescript
+	* const controller = new AbortController();
+	* for await (const frame of client.streamMcpServerEvent('tickets', 'ticket.created', {}, { signal: controller.signal })) {
+	*   if (frame.type === 'event') console.log(frame.occurrence.data);
+	* }
+	* ```
+	*/
+	async *streamMcpServerEvent(serverId, eventName, body = {}, options = {}) {
+		const response = await this.request(`/mcp/${encodeURIComponent(serverId)}/events/${encodeURIComponent(eventName)}/stream`, {
+			method: "POST",
+			body,
+			stream: true,
+			signal: options.signal,
+			retries: 0
+		});
+		if (!response.body) throw new Error("Response body is null");
+		const reader = response.body.pipeThrough(createSseJsonTransform()).getReader();
+		const cancel = () => void reader.cancel().catch(() => {});
+		options.signal?.addEventListener("abort", cancel, { once: true });
+		try {
+			while (true) {
+				const { value, done } = await reader.read();
+				if (done) return;
+				yield value;
+			}
+		} finally {
+			options.signal?.removeEventListener("abort", cancel);
+			await reader.cancel().catch(() => {});
+		}
+	}
+	/**
+	* Emits a test occurrence of an emit-fed MCP server event type (experimental).
+	* Only served under `mastra dev`; other servers respond 404. The occurrence's
+	* `eventId` starts with `mastra-test-`.
+	* @param serverId - The ID of the MCP server.
+	* @param eventName - The event type name.
+	* @param data - The event payload; validated against the event's payload schema.
+	*/
+	emitMcpServerEvent(serverId, eventName, data) {
+		return this.request(`/mcp/${encodeURIComponent(serverId)}/events/${encodeURIComponent(eventName)}/emit`, {
+			method: "POST",
+			body: { data }
+		});
+	}
+	/**
 	* Gets an A2A client for interacting with an agent via the A2A protocol
 	* @param agentId - ID of the agent to interact with
 	* @returns A2A client instance