@mastra/client-js 1.56.0-alpha.1 → 1.56.0-alpha.11

package/dist/index.js

@@ -1,8 +1,7 @@
-import { parsePartialJson, processDataStream } from "@ai-sdk/ui-utils";
 import { v4 } from "@lukeed/uuid";
 import { getErrorFromUnknown } from "@mastra/core/error";
-import { standardSchemaToJSONSchema, toStandardSchema } from "@mastra/schema-compat/schema";
 import { RequestContext, RequestContext as RequestContext$1 } from "@mastra/core/request-context";
+import { standardSchemaToJSONSchema, toStandardSchema } from "@mastra/schema-compat/schema";
 import { zodToJsonSchema } from "@mastra/schema-compat/zod-to-json";
 import { MastraA2AError } from "@mastra/core/a2a/client";
 import { AgentCard, CancelTaskRequest, DeleteTaskPushNotificationConfigRequest, GetTaskPushNotificationConfigRequest, GetTaskRequest, ListTaskPushNotificationConfigsRequest, ListTaskPushNotificationConfigsResponse, ListTasksRequest, ListTasksResponse, SendMessageRequest, SendMessageResponse, StreamResponse, SubscribeToTaskRequest, Task, TaskPushNotificationConfig } from "@mastra/core/a2a/v1";
@@ -60,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) }
@@ -377,6 +377,16 @@ function isTerminalHttpError(error) {
 	return typeof status === "number" && (status >= 400 && status < 500 || status === 501);
 }
 /**
+* Whether an error is the server's trace query execution timeout (504 with code
+* `TRACE_QUERY_EXECUTION_TIMEOUT`). Re-sending the same query hits the same
+* timeout budget, so retrying only repeats an expensive database query.
+* Plain 504s from proxies or gateways do not carry this code and stay retryable.
+*/
+function isTraceQueryTimeoutError(error) {
+	const { status, body } = error ?? {};
+	return status === 504 && body?.code === "TRACE_QUERY_EXECUTION_TIMEOUT";
+}
+/**
 * Whether a failed resubscribe should end a long-lived subscription instead of
 * retrying. Like {@link isTerminalHttpError}, but 408 Request Timeout and
 * 429 Too Many Requests stay retryable because they mean "try again later".
@@ -386,6 +396,571 @@ function isTerminalReconnectError(error) {
 	return isTerminalHttpError(error) && status !== 408 && status !== 429;
 }
 //#endregion
+//#region src/utils/ai-sdk-v4/data-stream-parts.ts
+const dataStreamParts = [
+	{
+		code: "0",
+		name: "text",
+		parse: (value) => {
+			if (typeof value !== "string") throw new Error("\"text\" parts expect a string value.");
+			return {
+				type: "text",
+				value
+			};
+		}
+	},
+	{
+		code: "2",
+		name: "data",
+		parse: (value) => {
+			if (!Array.isArray(value)) throw new Error("\"data\" parts expect an array value.");
+			return {
+				type: "data",
+				value
+			};
+		}
+	},
+	{
+		code: "3",
+		name: "error",
+		parse: (value) => {
+			if (typeof value !== "string") throw new Error("\"error\" parts expect a string value.");
+			return {
+				type: "error",
+				value
+			};
+		}
+	},
+	{
+		code: "8",
+		name: "message_annotations",
+		parse: (value) => {
+			if (!Array.isArray(value)) throw new Error("\"message_annotations\" parts expect an array value.");
+			return {
+				type: "message_annotations",
+				value
+			};
+		}
+	},
+	{
+		code: "9",
+		name: "tool_call",
+		parse: (value) => {
+			if (value == null || typeof value !== "object" || !("toolCallId" in value) || typeof value.toolCallId !== "string" || !("toolName" in value) || typeof value.toolName !== "string" || !("args" in value) || typeof value.args !== "object") throw new Error("\"tool_call\" parts expect an object with a \"toolCallId\", \"toolName\", and \"args\" property.");
+			return {
+				type: "tool_call",
+				value
+			};
+		}
+	},
+	{
+		code: "a",
+		name: "tool_result",
+		parse: (value) => {
+			if (value == null || typeof value !== "object" || !("toolCallId" in value) || typeof value.toolCallId !== "string" || !("result" in value)) throw new Error("\"tool_result\" parts expect an object with a \"toolCallId\" and a \"result\" property.");
+			return {
+				type: "tool_result",
+				value
+			};
+		}
+	},
+	{
+		code: "b",
+		name: "tool_call_streaming_start",
+		parse: (value) => {
+			if (value == null || typeof value !== "object" || !("toolCallId" in value) || typeof value.toolCallId !== "string" || !("toolName" in value) || typeof value.toolName !== "string") throw new Error("\"tool_call_streaming_start\" parts expect an object with a \"toolCallId\" and \"toolName\" property.");
+			return {
+				type: "tool_call_streaming_start",
+				value
+			};
+		}
+	},
+	{
+		code: "c",
+		name: "tool_call_delta",
+		parse: (value) => {
+			if (value == null || typeof value !== "object" || !("toolCallId" in value) || typeof value.toolCallId !== "string" || !("argsTextDelta" in value) || typeof value.argsTextDelta !== "string") throw new Error("\"tool_call_delta\" parts expect an object with a \"toolCallId\" and \"argsTextDelta\" property.");
+			return {
+				type: "tool_call_delta",
+				value
+			};
+		}
+	},
+	{
+		code: "d",
+		name: "finish_message",
+		parse: (value) => {
+			if (value == null || typeof value !== "object" || !("finishReason" in value) || typeof value.finishReason !== "string") throw new Error("\"finish_message\" parts expect an object with a \"finishReason\" property.");
+			const result = { finishReason: value.finishReason };
+			if ("usage" in value && value.usage != null && typeof value.usage === "object" && "promptTokens" in value.usage && "completionTokens" in value.usage) result.usage = {
+				promptTokens: typeof value.usage.promptTokens === "number" ? value.usage.promptTokens : NaN,
+				completionTokens: typeof value.usage.completionTokens === "number" ? value.usage.completionTokens : NaN
+			};
+			return {
+				type: "finish_message",
+				value: result
+			};
+		}
+	},
+	{
+		code: "e",
+		name: "finish_step",
+		parse: (value) => {
+			if (value == null || typeof value !== "object" || !("finishReason" in value) || typeof value.finishReason !== "string") throw new Error("\"finish_step\" parts expect an object with a \"finishReason\" property.");
+			const result = {
+				finishReason: value.finishReason,
+				isContinued: false
+			};
+			if ("usage" in value && value.usage != null && typeof value.usage === "object" && "promptTokens" in value.usage && "completionTokens" in value.usage) result.usage = {
+				promptTokens: typeof value.usage.promptTokens === "number" ? value.usage.promptTokens : NaN,
+				completionTokens: typeof value.usage.completionTokens === "number" ? value.usage.completionTokens : NaN
+			};
+			if ("isContinued" in value && typeof value.isContinued === "boolean") result.isContinued = value.isContinued;
+			return {
+				type: "finish_step",
+				value: result
+			};
+		}
+	},
+	{
+		code: "f",
+		name: "start_step",
+		parse: (value) => {
+			if (value == null || typeof value !== "object" || !("messageId" in value) || typeof value.messageId !== "string") throw new Error("\"start_step\" parts expect an object with an \"id\" property.");
+			return {
+				type: "start_step",
+				value: { messageId: value.messageId }
+			};
+		}
+	},
+	{
+		code: "g",
+		name: "reasoning",
+		parse: (value) => {
+			if (typeof value !== "string") throw new Error("\"reasoning\" parts expect a string value.");
+			return {
+				type: "reasoning",
+				value
+			};
+		}
+	},
+	{
+		code: "h",
+		name: "source",
+		parse: (value) => {
+			if (value == null || typeof value !== "object") throw new Error("\"source\" parts expect a Source object.");
+			return {
+				type: "source",
+				value
+			};
+		}
+	},
+	{
+		code: "i",
+		name: "redacted_reasoning",
+		parse: (value) => {
+			if (value == null || typeof value !== "object" || !("data" in value) || typeof value.data !== "string") throw new Error("\"redacted_reasoning\" parts expect an object with a \"data\" property.");
+			return {
+				type: "redacted_reasoning",
+				value: { data: value.data }
+			};
+		}
+	},
+	{
+		code: "j",
+		name: "reasoning_signature",
+		parse: (value) => {
+			if (value == null || typeof value !== "object" || !("signature" in value) || typeof value.signature !== "string") throw new Error("\"reasoning_signature\" parts expect an object with a \"signature\" property.");
+			return {
+				type: "reasoning_signature",
+				value: { signature: value.signature }
+			};
+		}
+	},
+	{
+		code: "k",
+		name: "file",
+		parse: (value) => {
+			if (value == null || typeof value !== "object" || !("data" in value) || typeof value.data !== "string" || !("mimeType" in value) || typeof value.mimeType !== "string") throw new Error("\"file\" parts expect an object with a \"data\" and \"mimeType\" property.");
+			return {
+				type: "file",
+				value
+			};
+		}
+	}
+];
+const dataStreamPartsByCode = Object.fromEntries(dataStreamParts.map((part) => [part.code, part]));
+Object.fromEntries(dataStreamParts.map((part) => [part.name, part.code]));
+const validCodes = dataStreamParts.map((part) => part.code);
+/**
+Parses a stream part from a string.
+
+@param line The string to parse.
+@returns The parsed stream part.
+@throws An error if the string cannot be parsed.
+*/
+const parseDataStreamPart = (line) => {
+	const firstSeparatorIndex = line.indexOf(":");
+	if (firstSeparatorIndex === -1) throw new Error("Failed to parse stream string. No separator found.");
+	const prefix = line.slice(0, firstSeparatorIndex);
+	if (!validCodes.includes(prefix)) throw new Error(`Failed to parse stream string. Invalid code ${prefix}.`);
+	const code = prefix;
+	const textValue = line.slice(firstSeparatorIndex + 1);
+	const jsonValue = JSON.parse(textValue);
+	return dataStreamPartsByCode[code].parse(jsonValue);
+};
+//#endregion
+//#region src/utils/ai-sdk-v4/fix-json.ts
+function fixJson(input) {
+	const stack = ["ROOT"];
+	let lastValidIndex = -1;
+	let literalStart = null;
+	function processValueStart(char, i, swapState) {
+		switch (char) {
+			case "\"":
+				lastValidIndex = i;
+				stack.pop();
+				stack.push(swapState);
+				stack.push("INSIDE_STRING");
+				break;
+			case "f":
+			case "t":
+			case "n":
+				lastValidIndex = i;
+				literalStart = i;
+				stack.pop();
+				stack.push(swapState);
+				stack.push("INSIDE_LITERAL");
+				break;
+			case "-":
+				stack.pop();
+				stack.push(swapState);
+				stack.push("INSIDE_NUMBER");
+				break;
+			case "0":
+			case "1":
+			case "2":
+			case "3":
+			case "4":
+			case "5":
+			case "6":
+			case "7":
+			case "8":
+			case "9":
+				lastValidIndex = i;
+				stack.pop();
+				stack.push(swapState);
+				stack.push("INSIDE_NUMBER");
+				break;
+			case "{":
+				lastValidIndex = i;
+				stack.pop();
+				stack.push(swapState);
+				stack.push("INSIDE_OBJECT_START");
+				break;
+			case "[":
+				lastValidIndex = i;
+				stack.pop();
+				stack.push(swapState);
+				stack.push("INSIDE_ARRAY_START");
+		}
+	}
+	function processAfterObjectValue(char, i) {
+		switch (char) {
+			case ",":
+				stack.pop();
+				stack.push("INSIDE_OBJECT_AFTER_COMMA");
+				break;
+			case "}":
+				lastValidIndex = i;
+				stack.pop();
+		}
+	}
+	function processAfterArrayValue(char, i) {
+		switch (char) {
+			case ",":
+				stack.pop();
+				stack.push("INSIDE_ARRAY_AFTER_COMMA");
+				break;
+			case "]":
+				lastValidIndex = i;
+				stack.pop();
+		}
+	}
+	for (let i = 0; i < input.length; i++) {
+		const char = input[i];
+		switch (stack[stack.length - 1]) {
+			case "ROOT":
+				processValueStart(char, i, "FINISH");
+				break;
+			case "INSIDE_OBJECT_START":
+				switch (char) {
+					case "\"":
+						stack.pop();
+						stack.push("INSIDE_OBJECT_KEY");
+						break;
+					case "}":
+						lastValidIndex = i;
+						stack.pop();
+				}
+				break;
+			case "INSIDE_OBJECT_AFTER_COMMA":
+				switch (char) {
+					case "\"":
+						stack.pop();
+						stack.push("INSIDE_OBJECT_KEY");
+				}
+				break;
+			case "INSIDE_OBJECT_KEY":
+				switch (char) {
+					case "\"":
+						stack.pop();
+						stack.push("INSIDE_OBJECT_AFTER_KEY");
+				}
+				break;
+			case "INSIDE_OBJECT_AFTER_KEY":
+				switch (char) {
+					case ":":
+						stack.pop();
+						stack.push("INSIDE_OBJECT_BEFORE_VALUE");
+				}
+				break;
+			case "INSIDE_OBJECT_BEFORE_VALUE":
+				processValueStart(char, i, "INSIDE_OBJECT_AFTER_VALUE");
+				break;
+			case "INSIDE_OBJECT_AFTER_VALUE":
+				processAfterObjectValue(char, i);
+				break;
+			case "INSIDE_STRING":
+				switch (char) {
+					case "\"":
+						stack.pop();
+						lastValidIndex = i;
+						break;
+					case "\\":
+						stack.push("INSIDE_STRING_ESCAPE");
+						break;
+					default: lastValidIndex = i;
+				}
+				break;
+			case "INSIDE_ARRAY_START":
+				switch (char) {
+					case "]":
+						lastValidIndex = i;
+						stack.pop();
+						break;
+					default:
+						lastValidIndex = i;
+						processValueStart(char, i, "INSIDE_ARRAY_AFTER_VALUE");
+				}
+				break;
+			case "INSIDE_ARRAY_AFTER_VALUE":
+				switch (char) {
+					case ",":
+						stack.pop();
+						stack.push("INSIDE_ARRAY_AFTER_COMMA");
+						break;
+					case "]":
+						lastValidIndex = i;
+						stack.pop();
+						break;
+					default: lastValidIndex = i;
+				}
+				break;
+			case "INSIDE_ARRAY_AFTER_COMMA":
+				processValueStart(char, i, "INSIDE_ARRAY_AFTER_VALUE");
+				break;
+			case "INSIDE_STRING_ESCAPE":
+				stack.pop();
+				lastValidIndex = i;
+				break;
+			case "INSIDE_NUMBER":
+				switch (char) {
+					case "0":
+					case "1":
+					case "2":
+					case "3":
+					case "4":
+					case "5":
+					case "6":
+					case "7":
+					case "8":
+					case "9":
+						lastValidIndex = i;
+						break;
+					case "e":
+					case "E":
+					case "-":
+					case ".": break;
+					case ",":
+						stack.pop();
+						if (stack[stack.length - 1] === "INSIDE_ARRAY_AFTER_VALUE") processAfterArrayValue(char, i);
+						if (stack[stack.length - 1] === "INSIDE_OBJECT_AFTER_VALUE") processAfterObjectValue(char, i);
+						break;
+					case "}":
+						stack.pop();
+						if (stack[stack.length - 1] === "INSIDE_OBJECT_AFTER_VALUE") processAfterObjectValue(char, i);
+						break;
+					case "]":
+						stack.pop();
+						if (stack[stack.length - 1] === "INSIDE_ARRAY_AFTER_VALUE") processAfterArrayValue(char, i);
+						break;
+					default: stack.pop();
+				}
+				break;
+			case "INSIDE_LITERAL": {
+				const partialLiteral = input.substring(literalStart, i + 1);
+				if (!"false".startsWith(partialLiteral) && !"true".startsWith(partialLiteral) && !"null".startsWith(partialLiteral)) {
+					stack.pop();
+					if (stack[stack.length - 1] === "INSIDE_OBJECT_AFTER_VALUE") processAfterObjectValue(char, i);
+					else if (stack[stack.length - 1] === "INSIDE_ARRAY_AFTER_VALUE") processAfterArrayValue(char, i);
+				} else lastValidIndex = i;
+				break;
+			}
+		}
+	}
+	let result = input.slice(0, lastValidIndex + 1);
+	for (let i = stack.length - 1; i >= 0; i--) switch (stack[i]) {
+		case "INSIDE_STRING":
+			result += "\"";
+			break;
+		case "INSIDE_OBJECT_KEY":
+		case "INSIDE_OBJECT_AFTER_KEY":
+		case "INSIDE_OBJECT_AFTER_COMMA":
+		case "INSIDE_OBJECT_START":
+		case "INSIDE_OBJECT_BEFORE_VALUE":
+		case "INSIDE_OBJECT_AFTER_VALUE":
+			result += "}";
+			break;
+		case "INSIDE_ARRAY_START":
+		case "INSIDE_ARRAY_AFTER_COMMA":
+		case "INSIDE_ARRAY_AFTER_VALUE":
+			result += "]";
+			break;
+		case "INSIDE_LITERAL": {
+			const partialLiteral = input.substring(literalStart, input.length);
+			if ("true".startsWith(partialLiteral)) result += "true".slice(partialLiteral.length);
+			else if ("false".startsWith(partialLiteral)) result += "false".slice(partialLiteral.length);
+			else if ("null".startsWith(partialLiteral)) result += "null".slice(partialLiteral.length);
+		}
+	}
+	return result;
+}
+//#endregion
+//#region src/utils/ai-sdk-v4/parse-partial-json.ts
+function tryParse(text) {
+	try {
+		return {
+			success: true,
+			value: JSON.parse(text)
+		};
+	} catch {
+		return { success: false };
+	}
+}
+function parsePartialJson(jsonText) {
+	if (jsonText === void 0) return {
+		value: void 0,
+		state: "undefined-input"
+	};
+	let result = tryParse(jsonText);
+	if (result.success) return {
+		value: result.value,
+		state: "successful-parse"
+	};
+	result = tryParse(fixJson(jsonText));
+	if (result.success) return {
+		value: result.value,
+		state: "repaired-parse"
+	};
+	return {
+		value: void 0,
+		state: "failed-parse"
+	};
+}
+//#endregion
+//#region src/utils/ai-sdk-v4/process-data-stream.ts
+const NEWLINE = "\n".charCodeAt(0);
+function concatChunks(chunks, totalLength) {
+	const concatenatedChunks = new Uint8Array(totalLength);
+	let offset = 0;
+	for (const chunk of chunks) {
+		concatenatedChunks.set(chunk, offset);
+		offset += chunk.length;
+	}
+	chunks.length = 0;
+	return concatenatedChunks;
+}
+async function processDataStream({ stream, onTextPart, onReasoningPart, onReasoningSignaturePart, onRedactedReasoningPart, onSourcePart, onFilePart, onDataPart, onErrorPart, onToolCallStreamingStartPart, onToolCallDeltaPart, onToolCallPart, onToolResultPart, onMessageAnnotationsPart, onFinishMessagePart, onFinishStepPart, onStartStepPart }) {
+	const reader = stream.getReader();
+	const decoder = new TextDecoder();
+	const chunks = [];
+	let totalLength = 0;
+	while (true) {
+		const { value } = await reader.read();
+		if (value) {
+			chunks.push(value);
+			totalLength += value.length;
+			if (value[value.length - 1] !== NEWLINE) continue;
+		}
+		if (chunks.length === 0) break;
+		const concatenatedChunks = concatChunks(chunks, totalLength);
+		totalLength = 0;
+		const streamParts = decoder.decode(concatenatedChunks, { stream: true }).split("\n").filter((line) => line !== "").map(parseDataStreamPart);
+		for (const { type, value } of streamParts) switch (type) {
+			case "text":
+				await onTextPart?.(value);
+				break;
+			case "reasoning":
+				await onReasoningPart?.(value);
+				break;
+			case "reasoning_signature":
+				await onReasoningSignaturePart?.(value);
+				break;
+			case "redacted_reasoning":
+				await onRedactedReasoningPart?.(value);
+				break;
+			case "file":
+				await onFilePart?.(value);
+				break;
+			case "source":
+				await onSourcePart?.(value);
+				break;
+			case "data":
+				await onDataPart?.(value);
+				break;
+			case "error":
+				await onErrorPart?.(value);
+				break;
+			case "message_annotations":
+				await onMessageAnnotationsPart?.(value);
+				break;
+			case "tool_call_streaming_start":
+				await onToolCallStreamingStartPart?.(value);
+				break;
+			case "tool_call_delta":
+				await onToolCallDeltaPart?.(value);
+				break;
+			case "tool_call":
+				await onToolCallPart?.(value);
+				break;
+			case "tool_result":
+				await onToolResultPart?.(value);
+				break;
+			case "finish_message":
+				await onFinishMessagePart?.(value);
+				break;
+			case "finish_step":
+				await onFinishStepPart?.(value);
+				break;
+			case "start_step":
+				await onStartStepPart?.(value);
+				break;
+			default: throw new Error(`Unknown stream part type: ${type}`);
+		}
+	}
+}
+//#endregion
 //#region src/utils/client-tool-model-output.ts
 /**
 * Normalize modelOutput from toModelOutput() to the AI SDK V2 tool result
@@ -618,7 +1193,7 @@ var BaseResource = class {
 			} catch (error) {
 				lastError = error;
 				if (signal?.aborted || error?.name === "AbortError") throw error;
-				if (isTerminalHttpError(error)) throw error;
+				if (isTerminalHttpError(error) || isTraceQueryTimeoutError(error)) throw error;
 				if (attempt === retries) break;
 				await new Promise((resolve, reject) => {
 					const timer = setTimeout(() => {
@@ -639,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);
@@ -833,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}`;
@@ -1970,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;
 				}
 			}
 		});
@@ -2034,6 +2659,10 @@ var Agent = class extends BaseResource {
 		try {
 			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 = "";
@@ -2041,6 +2670,13 @@ var Agent = class extends BaseResource {
 				pendingText += text;
 				const lines = pendingText.split("\n\n");
 				pendingText = isFinal ? "" : lines.pop() ?? "";
+				for (const line of lines) {
+					if (!line.startsWith("data: ") || !line.includes("\"type\":\"finish\"")) continue;
+					try {
+						const all = JSON.parse(line.slice(6))?.payload?.messages?.all;
+						if (Array.isArray(all)) finishedHistory = all;
+					} catch {}
+				}
 				const readableLines = lines.filter((line) => line.trim() !== "[DONE]" && line.trim() !== "data: [DONE]").join("\n\n");
 				if (readableLines) safeEnqueue(new TextEncoder().encode(`${readableLines}\n\n`));
 			};
@@ -2095,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);
 						});
@@ -2194,12 +2833,12 @@ var Agent = class extends BaseResource {
 								role: "tool",
 								content: toolResultContents
 							};
-							const updatedMessages = threadId ? [toolResultMessage] : [
+							const updatedMessages = threadId ? [toolResultMessage] : (route === "resume-stream" || route === "approve-tool-call" || route === "decline-tool-call") && finishedHistory ? [...finishedHistory, toolResultMessage] : [
 								...Array.isArray(processedParams.messages) ? processedParams.messages : [],
 								...messages,
 								toolResultMessage
 							];
-							const recursionRoute = route === "resume-stream" ? "stream" : route === "resume-stream-until-idle" ? "stream-until-idle" : route;
+							const recursionRoute = route === "resume-stream" || route === "approve-tool-call" || route === "decline-tool-call" ? "stream" : route === "resume-stream-until-idle" ? "stream-until-idle" : route;
 							if (isAborted()) return;
 							try {
 								await this.processStreamResponse({
@@ -2221,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) => {
@@ -2231,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);
@@ -2398,12 +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)
+			requestContext: parseClientRequestContext(requestContext),
+			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,
@@ -2429,12 +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)
+			requestContext: parseClientRequestContext(requestContext),
+			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,
@@ -2494,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,
@@ -2558,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,
@@ -2588,27 +3256,93 @@ var Agent = class extends BaseResource {
 	* Used when `requireToolApproval` is enabled with generate() to allow the agent to proceed.
 	*/
 	async approveToolCallGenerate(params) {
-		const { requestContext, ...rest } = params;
-		return this.request(`/agents/${this.agentId}/approve-tool-call-generate`, {
-			method: "POST",
-			body: {
-				...rest,
-				requestContext: parseClientRequestContext(requestContext)
-			}
-		});
+		const { requestContext, clientTools, clientToolsResolver, memory, ...rest } = params;
+		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).
 	* Used when `requireToolApproval` is enabled with generate() to prevent tool execution.
 	*/
 	async declineToolCallGenerate(params) {
-		const { requestContext, ...rest } = params;
-		return this.request(`/agents/${this.agentId}/decline-tool-call-generate`, {
-			method: "POST",
-			body: {
-				...rest,
-				requestContext: parseClientRequestContext(requestContext)
-			}
+		const { requestContext, clientTools, clientToolsResolver, memory, ...rest } = params;
+		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
+	* /generate, like generate() does. With memory the continuation sends only the new messages to the
+	* thread. Without memory it re-sends the conversation up to the last user turn, because the resume
+	* routes keep the earlier history server-side and drop it once the run finishes.
+	*/
+	async continueResumedGenerate(response, { requestContext, clientTools, clientToolsResolver, memory }) {
+		if (response.finishReason !== "tool-calls") return response;
+		const context = requestContext === void 0 || requestContext instanceof RequestContext$1 ? requestContext : new RequestContext$1(Object.entries(requestContext));
+		const threadId = typeof memory?.thread === "string" ? memory.thread : memory?.thread?.id;
+		const history = response.messages ?? [];
+		const priorTurns = history.slice(0, history.findLastIndex((message) => message.role === "user") + 1);
+		return executeToolCallAndRespond({
+			response,
+			params: {
+				messages: threadId ? [] : priorTurns,
+				clientTools: clientToolsResolver?.() ?? clientTools,
+				clientToolsResolver,
+				requestContext: context,
+				memory
+			},
+			agentId: this.agentId,
+			resourceId: memory?.resource,
+			threadId,
+			requestContext: context,
+			respondFn: (messages, options) => this.generate(messages, options)
 		});
 	}
 	/**
@@ -3806,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");
@@ -4550,10 +5285,10 @@ var Observability = class extends BaseResource {
 		});
 	}
 	/**
-	* Queries thread identities using eligible-trace and cross-trace predicates.
+	* Queries full-history thread rows using a trace or thread activity window.
 	*
-	* @param params - Thread query with its eligible trace selection
-	* @returns Matching thread identities
+	* @param params - Thread query with its qualification window, filters and pagination
+	* @returns Matching thread rows. Legacy requests retain their identity-only response.
 	*/
 	queryTraceThreads(params) {
 		return this.request("/observability/threads/query", {
@@ -6138,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
 			}
 		});
 	}
@@ -6205,10 +6932,12 @@ var AgentControllerSession = class extends BaseResource {
 			delayMs: finiteOr(options.reconnect.delayMs, 1e3),
 			maxDelayMs: finiteOr(options.reconnect.maxDelayMs, 3e4)
 		} : null;
+		const idleTimeoutMs = finiteOr(options.idleTimeoutMs, 6e4);
 		/** Exponential backoff for the Nth (1-based) retry of an outage streak. */
 		const backoffDelay = (attempt) => reconnectOptions ? Math.min(reconnectOptions.delayMs * 2 ** (attempt - 1), reconnectOptions.maxDelayMs) : 0;
 		let cancelled = false;
 		let currentReader = null;
+		let currentAbort = null;
 		let reconnectTimer;
 		let delayResolve;
 		const settleDelay = () => {
@@ -6224,8 +6953,39 @@ var AgentControllerSession = class extends BaseResource {
 			delayResolve = resolve;
 			reconnectTimer = setTimeout(settleDelay, ms);
 		});
+		const idleTimeoutError = () => {
+			const error = /* @__PURE__ */ new Error(`Agent controller session stream received no data for ${idleTimeoutMs}ms`);
+			error.name = "AgentControllerStreamIdleError";
+			return error;
+		};
 		const requestStream = async () => {
-			const response = await this.request(this.url(`${this.base()}/stream`), { stream: true });
+			const abort = new AbortController();
+			currentAbort = abort;
+			let openTimer;
+			const request = this.request(`${this.base()}/stream`, {
+				stream: true,
+				signal: abort.signal
+			});
+			request.then((response) => {
+				if (abort.signal.aborted) response.body?.cancel().catch(() => {});
+			}).catch(() => {});
+			let response;
+			try {
+				if (idleTimeoutMs > 0) response = await Promise.race([request, new Promise((_resolve, reject) => {
+					openTimer = setTimeout(() => {
+						const error = idleTimeoutError();
+						abort.abort(error);
+						reject(error);
+					}, idleTimeoutMs);
+				})]);
+				else response = await request;
+			} finally {
+				clearTimeout(openTimer);
+			}
+			if (abort.signal.aborted) {
+				response.body?.cancel().catch(() => {});
+				throw abort.signal.reason;
+			}
 			if (!response.body) throw new Error("No response body for agent controller session stream");
 			return response;
 		};
@@ -6251,12 +7011,40 @@ var AgentControllerSession = class extends BaseResource {
 		const pump = async (response) => {
 			const reader = response.body.getReader();
 			currentReader = reader;
+			const abort = currentAbort;
 			const decoder = new TextDecoder();
 			let buffer = "";
+			let idleTimer;
+			let timedOut = false;
+			const armIdleTimer = () => {
+				if (idleTimeoutMs <= 0) return;
+				clearTimeout(idleTimer);
+				idleTimer = setTimeout(() => {
+					timedOut = true;
+					reader.cancel(idleTimeoutError()).catch(() => {});
+					abort?.abort(idleTimeoutError());
+				}, idleTimeoutMs);
+			};
 			try {
+				armIdleTimer();
 				while (!cancelled) {
-					const { done, value } = await reader.read();
+					let chunk;
+					try {
+						chunk = await reader.read();
+					} catch (error) {
+						if (timedOut && !cancelled) return {
+							kind: "transport_error",
+							error: idleTimeoutError()
+						};
+						throw error;
+					}
+					if (timedOut && !cancelled) return {
+						kind: "transport_error",
+						error: idleTimeoutError()
+					};
+					const { done, value } = chunk;
 					if (done) return cancelled ? { kind: "cancelled" } : { kind: "done" };
+					armIdleTimer();
 					if (cancelled) return { kind: "cancelled" };
 					buffer += decoder.decode(value, { stream: true });
 					let separator;
@@ -6290,7 +7078,9 @@ var AgentControllerSession = class extends BaseResource {
 					error
 				};
 			} finally {
+				clearTimeout(idleTimer);
 				if (currentReader === reader) currentReader = null;
+				if (currentAbort === abort) currentAbort = null;
 				reader.cancel().catch(() => {});
 			}
 		};
@@ -6367,6 +7157,7 @@ var AgentControllerSession = class extends BaseResource {
 			cancelled = true;
 			settleDelay();
 			currentReader?.cancel().catch(() => {});
+			currentAbort?.abort();
 		} };
 	}
 	/**
@@ -6381,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,
@@ -6392,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
@@ -6400,12 +7191,13 @@ 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: {
 				toolCallId,
 				approved,
+				...options?.alwaysAllowCategory ? { alwaysAllowCategory: true } : {},
 				...requestContext ? { requestContext } : {}
 			}
 		});
@@ -6417,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: {
@@ -6437,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,
@@ -6449,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 }
 		});
@@ -6470,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,
@@ -6491,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 ?? {}
 		});
@@ -6541,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 {
@@ -6560,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,
@@ -6571,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,
@@ -6600,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,
@@ -6625,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,
@@ -6639,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
 		});
@@ -6672,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. */
@@ -6751,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
 	*/
@@ -7002,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`);
 	}
@@ -7023,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}`);
 	}
@@ -7272,7 +8067,7 @@ var MastraClient = class extends BaseResource {
 	getTraceQueryValues(params, options) {
 		return this.observability.getTraceQueryValues(params, options);
 	}
-	/** Queries thread identities using eligible-trace and cross-trace predicates. */
+	/** Queries full-history thread rows using a trace or thread activity window. */
 	queryTraceThreads(params) {
 		return this.observability.queryTraceThreads(params);
 	}