@mastra/server 1.79.0-alpha.8 → 1.79.0-alpha.9

package/dist/server/handlers/agent-controller.js

@@ -13,8 +13,9 @@ import { z } from "zod/v4";
 * `new Mastra({ agentControllers })`) exposes its sessions over HTTP so
 * non-terminal clients — e.g. a browser-based MastraCode — can create sessions,
 * send messages, stream events, and drive run-control. Each route resolves its
-* target AgentController by id, then operates on a session bound to a
-* `resourceId`. Mutating routes use get-or-create resolution so reconnects
+* target AgentController by id, then operates on the session addressed by
+* `sessionId` (which works on the threads and memory of its `resourceId`).
+* Mutating routes use get-or-create resolution so reconnects
 * resume rather than fork the conversation; read routes only inspect existing
 * live sessions.
 */
@@ -62,54 +63,50 @@ function getAgentControllerOrThrow(mastra, controllerId) {
 	return controller;
 }
 /**
-* Get-or-create a session. Only the create-session route calls this: it is the one request that carries the
-* tags and exact thread a conversation starts on.
+* The resource of the session addressed by `sessionId`, without materializing
+* it: the live session's resource, else the resource of the thread sharing the
+* session's id, else `sessionId` itself (the default when a session is created
+* without a `sessionId`).
 */
-async function startSession(controller, resourceId, options, requestContext) {
-	await controller.init();
-	const { tags, scope, threadId } = options ?? {};
-	const id = threadId ?? (scope ? `${resourceId}::${scope}` : resourceId);
-	return controller.createSession({
-		resourceId,
-		id,
-		ownerId: controller.id,
-		tags,
-		scope,
-		threadId,
-		requestContext
-	});
+async function resolveSessionResourceId(controller, sessionId) {
+	const live = await controller.getSession(sessionId);
+	if (live) return live.identity.getResourceId();
+	return (await controller.queryThreadById({ threadId: sessionId }))?.resourceId ?? sessionId;
 }
 /**
-* Resolve the session every other route acts on: the live one, or a lost one (e.g. after a restart) rebuilt on
-* its most recent stored thread. Never starts a conversation, so a write that arrives before the session was
-* started fails instead of landing on a thread nobody reads.
+* Resolve the session addressed by `sessionId` that every route other than create acts on: the live one, or a
+* lost one (e.g. after a restart) rebuilt from storage. When a thread with the session's id exists, the session
+* resumes on that thread under the thread's resource (hosts that use `sessionId === threadId` recover their own
+* thread even when many sessions share one resource); otherwise it resumes on `resourceId = sessionId`, the
+* default `POST /sessions` applies when no `sessionId` is sent. Never starts a conversation, so a write that
+* arrives before the session was started fails instead of landing on a thread nobody reads.
 */
-async function getSession(controller, resourceId, options, requestContext) {
+async function getSession(controller, sessionId, requestContext) {
 	await controller.init();
-	const scope = options?.scope;
-	const id = scope ? `${resourceId}::${scope}` : resourceId;
+	const live = await controller.getSession(sessionId);
+	const thread = live ? null : await controller.queryThreadById({ threadId: sessionId });
 	try {
 		return await controller.createSession({
-			resourceId,
-			id,
+			id: sessionId,
+			resourceId: live?.identity.getResourceId() ?? thread?.resourceId ?? sessionId,
 			ownerId: controller.id,
-			scope,
+			threadId: thread ? sessionId : void 0,
 			resumeOnly: true,
 			requestContext
 		});
 	} catch (error) {
 		if (error instanceof Error && error.code === "SESSION_NOT_STARTED") throw new HTTPException(404, {
-			message: `No session has been started for resource "${resourceId}". Create it with POST /agent-controller/:controllerId/sessions first.`,
+			message: `No session "${sessionId}" has been started. Create it with POST /agent-controller/:controllerId/sessions first.`,
 			cause: error
 		});
 		throw error;
 	}
 }
-async function getExistingSession(controller, resourceId, scope, requestContext) {
+async function getExistingSession(controller, sessionId, requestContext) {
 	await controller.init();
-	const session = await controller.getSessionByResource(resourceId, scope, requestContext);
+	const session = await controller.getSession(sessionId, requestContext);
 	if (session) return session;
-	return getSession(controller, resourceId, { scope }, requestContext);
+	return getSession(controller, sessionId, requestContext);
 }
 /**
 * Acknowledges a session operation that keeps running after the response is
@@ -146,22 +143,29 @@ function ackBackgroundSessionWork({ work, session, mastra, operation }) {
 const controllerIdPathParams = z.object({ controllerId: z.string() });
 const sessionPathParams = z.object({
 	controllerId: z.string(),
-	resourceId: z.string()
+	sessionId: z.string()
 });
 /**
-* Optional session scope (mirrors `AgentController.createSession`'s `scope`):
-* requests with the same resourceId but different scopes address independent
-* sessions (e.g. one per git worktree). Sent as a `sessionScope` query param
-* on session routes; named to avoid colliding with the model-switch `scope`.
+* Sessions used to be addressed by `resourceId` plus `sessionScope`. The param is gone: reject it
+* rather than drop it, so an older client's scoped session can't quietly merge into another one.
 */
-const sessionScopeQuerySchema = z.object({ sessionScope: z.string().optional() });
-const sessionStateQuerySchema = sessionScopeQuerySchema.extend({ threadId: z.string().optional() });
+const removedSessionScope = z.never({ error: "sessionScope was removed; address the session by sessionId" }).optional();
+const sessionQuerySchema = z.object({ sessionScope: removedSessionScope });
+const sessionStateQuerySchema = sessionQuerySchema.extend({ threadId: z.string().optional() });
 const createSessionBodySchema = z.object({
-	resourceId: z.string(),
+	/**
+	* Whose threads and memory the session works on. Optional when `sessionId` is
+	* sent: the session then resumes 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 session id.
+	*/
+	resourceId: z.string().optional(),
+	/** Address of the session. Defaults to `resourceId`. */
+	sessionId: z.string().optional(),
+	sessionScope: removedSessionScope,
 	tags: z.record(z.string(), z.string()).optional(),
-	threadId: z.string().optional(),
-	sessionScope: z.string().optional()
-});
+	threadId: z.string().optional()
+}).refine((body) => body.resourceId !== void 0 || body.sessionId !== void 0, { message: "resourceId or sessionId is required" });
 const MAX_FILE_DATA_LENGTH = 14 * 1024 * 1024;
 const MAX_TOTAL_FILE_DATA_LENGTH = 28 * 1024 * 1024;
 /**
@@ -223,7 +227,7 @@ const createThreadBodySchema = z.object({ title: z.string().optional() });
 const renameThreadBodySchema = z.object({ title: z.string() });
 const threadPathParams = z.object({
 	controllerId: z.string(),
-	resourceId: z.string(),
+	sessionId: z.string(),
 	threadId: z.string()
 });
 const cloneThreadBodySchema = z.object({
@@ -232,14 +236,14 @@ const cloneThreadBodySchema = z.object({
 });
 const controllerPaginationNumber = z.coerce.number().int().min(0);
 const listMessagesQuerySchema = z.object({
+	sessionScope: removedSessionScope,
 	/** @deprecated Use page and perPage instead. */
 	limit: controllerPaginationNumber.optional(),
 	page: controllerPaginationNumber.optional(),
 	perPage: z.preprocess((value) => value === "false" ? false : value, z.union([z.literal(false), controllerPaginationNumber])).optional(),
 	orderBy: messageOrderBySchema,
 	include: includeSchema,
-	filter: filterSchema,
-	sessionScope: z.string().optional()
+	filter: filterSchema
 }).superRefine((value, ctx) => {
 	if (value.limit === void 0) return;
 	for (const field of [
@@ -260,8 +264,8 @@ const listMessagesQuerySchema = z.object({
 * only their own threads. Malformed JSON is treated as "no filter".
 */
 const listThreadsQuerySchema = z.object({
+	sessionScope: removedSessionScope,
 	limit: z.coerce.number().optional(),
-	sessionScope: z.string().optional(),
 	tags: z.preprocess((value) => {
 		if (typeof value !== "string" || value.length === 0) return void 0;
 		try {
@@ -296,6 +300,7 @@ const sendNotificationBodySchema = z.object({
 const listAgentControllersResponseSchema = z.object({ agentControllers: z.array(z.object({ id: z.string() })) });
 const createSessionResponseSchema = z.object({
 	controllerId: z.string(),
+	sessionId: z.string(),
 	resourceId: z.string(),
 	threadId: z.string().optional()
 });
@@ -371,6 +376,7 @@ const taskSnapshotSchema = z.object({
 });
 const sessionStateResponseSchema = z.object({
 	controllerId: z.string(),
+	sessionId: z.string(),
 	resourceId: z.string(),
 	threadId: z.string().optional(),
 	modeId: z.string(),
@@ -487,25 +493,34 @@ const LIST_AGENT_CONTROLLERS_ROUTE = createRoute({
 const CREATE_AGENT_CONTROLLER_SESSION_ROUTE = createRoute({
 	method: "POST",
 	path: "/agent-controller/:controllerId/sessions",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: controllerIdPathParams,
 	bodySchema: createSessionBodySchema,
 	responseSchema: createSessionResponseSchema,
 	summary: "Create or resume a controller session",
-	description: "Creates a session for the given resourceId, or returns the existing one (get-or-create), so reconnects resume the conversation. Every other session route requires a started session and returns 404 until one exists or can be recovered from a stored thread.",
+	description: "Creates the session addressed by `sessionId` on the given resourceId, or returns the existing one (get-or-create), so reconnects resume the conversation. Without a `sessionId` the session is addressed by `resourceId`; without a `resourceId` it resumes on the resource it already has. Every other session route requires a started session and returns 404 until one exists or can be recovered from a stored thread.",
 	tags: ["AgentController"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, tags, threadId, requestContext }) => {
+	handler: async ({ mastra, controllerId, resourceId, sessionId, tags, threadId, requestContext }) => {
 		try {
+			const controller = getAgentControllerOrThrow(mastra, controllerId);
+			await controller.init();
+			const id = sessionId ?? resourceId;
+			const session = await controller.createSession({
+				id,
+				resourceId: resourceId ?? await resolveSessionResourceId(controller, id),
+				ownerId: controller.id,
+				tags,
+				threadId,
+				requestContext
+			});
 			return {
 				controllerId,
-				resourceId,
-				threadId: (await startSession(getAgentControllerOrThrow(mastra, controllerId), resourceId, {
-					tags,
-					scope: sessionScope,
-					threadId
-				}, requestContext)).thread.getId() ?? void 0
+				sessionId: session.identity.getId(),
+				resourceId: session.identity.getResourceId(),
+				threadId: session.thread.getId() ?? void 0
 			};
 		} catch (error) {
 			return handleError(error, "error creating controller session");
@@ -552,20 +567,20 @@ function toWireEvent(event) {
 }
 const STREAM_AGENT_CONTROLLER_SESSION_ROUTE = createRoute({
 	method: "GET",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/stream",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/stream",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "stream",
 	streamFormat: "sse",
 	sseFlushOnConnect: true,
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	summary: "Stream controller session events",
 	description: "Subscribes to a session’s event bus and streams events to the client over SSE.",
 	tags: ["AgentController", "Streaming"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:read",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, abortSignal, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, abortSignal, requestContext }) => {
 		try {
-			const session = await getExistingSession(getAgentControllerOrThrow(mastra, controllerId), resourceId, sessionScope, requestContext);
+			const session = await getExistingSession(getAgentControllerOrThrow(mastra, controllerId), sessionId, requestContext);
 			let cleanedUp = false;
 			let heartbeat;
 			let unsubscribe;
@@ -634,10 +649,10 @@ const STREAM_AGENT_CONTROLLER_SESSION_ROUTE = createRoute({
 });
 const SEND_AGENT_CONTROLLER_MESSAGE_ROUTE = createRoute({
 	method: "POST",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/messages",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/messages",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	bodySchema: sendMessageBodySchema,
 	responseSchema: ackResponseSchema,
 	summary: "Send a message to a controller session",
@@ -645,9 +660,9 @@ const SEND_AGENT_CONTROLLER_MESSAGE_ROUTE = createRoute({
 	tags: ["AgentController", "Streaming"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, message, files, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, message, files, requestContext }) => {
 		try {
-			const session = await getSession(getAgentControllerOrThrow(mastra, controllerId), resourceId, { scope: sessionScope }, requestContext);
+			const session = await getSession(getAgentControllerOrThrow(mastra, controllerId), sessionId, requestContext);
 			const author = getRequestMessageAuthor(requestContext);
 			ackBackgroundSessionWork({
 				work: session.sendMessage({
@@ -668,19 +683,19 @@ const SEND_AGENT_CONTROLLER_MESSAGE_ROUTE = createRoute({
 });
 const ABORT_AGENT_CONTROLLER_SESSION_ROUTE = createRoute({
 	method: "POST",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/abort",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/abort",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	responseSchema: ackResponseSchema,
 	summary: "Abort a controller session run",
 	description: "Aborts the in-flight run for the session, if any.",
 	tags: ["AgentController"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, requestContext }) => {
 		try {
-			(await getSession(getAgentControllerOrThrow(mastra, controllerId), resourceId, { scope: sessionScope }, requestContext)).abort();
+			(await getSession(getAgentControllerOrThrow(mastra, controllerId), sessionId, requestContext)).abort();
 			return { ok: true };
 		} catch (error) {
 			return handleError(error, "error aborting controller session");
@@ -689,10 +704,10 @@ const ABORT_AGENT_CONTROLLER_SESSION_ROUTE = createRoute({
 });
 const AGENT_CONTROLLER_TOOL_APPROVAL_ROUTE = createRoute({
 	method: "POST",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/tool-approval",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/tool-approval",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	bodySchema: toolApprovalBodySchema,
 	responseSchema: toolCommandAckResponseSchema,
 	summary: "Respond to a controller tool approval",
@@ -700,9 +715,9 @@ const AGENT_CONTROLLER_TOOL_APPROVAL_ROUTE = createRoute({
 	tags: ["AgentController"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, toolCallId, approved, alwaysAllowCategory, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, toolCallId, approved, alwaysAllowCategory, requestContext }) => {
 		try {
-			const session = await getSession(getAgentControllerOrThrow(mastra, controllerId), resourceId, { scope: sessionScope }, requestContext);
+			const session = await getSession(getAgentControllerOrThrow(mastra, controllerId), sessionId, requestContext);
 			if ((toolCallId ? session.approval.isArmed({ toolCallId }) : session.approval.isArmed()) || !toolCallId) {
 				const result = session.respondToToolApproval({
 					toolCallId,
@@ -742,10 +757,10 @@ const AGENT_CONTROLLER_TOOL_APPROVAL_ROUTE = createRoute({
 });
 const AGENT_CONTROLLER_TOOL_SUSPENSION_ROUTE = createRoute({
 	method: "POST",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/tool-suspension",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/tool-suspension",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	bodySchema: toolSuspensionBodySchema,
 	responseSchema: toolCommandAckResponseSchema,
 	summary: "Respond to a suspended controller tool",
@@ -753,9 +768,9 @@ const AGENT_CONTROLLER_TOOL_SUSPENSION_ROUTE = createRoute({
 	tags: ["AgentController"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, toolCallId, runId, resumeData, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, toolCallId, runId, resumeData, requestContext }) => {
 		try {
-			const session = await getSession(getAgentControllerOrThrow(mastra, controllerId), resourceId, { scope: sessionScope }, requestContext);
+			const session = await getSession(getAgentControllerOrThrow(mastra, controllerId), sessionId, requestContext);
 			const claim = session.claimToolSuspension(toolCallId, runId);
 			if (!claim.accepted) return {
 				ok: false,
@@ -779,10 +794,10 @@ const AGENT_CONTROLLER_TOOL_SUSPENSION_ROUTE = createRoute({
 });
 const STEER_AGENT_CONTROLLER_SESSION_ROUTE = createRoute({
 	method: "POST",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/steer",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/steer",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	bodySchema: steerBodySchema,
 	responseSchema: ackResponseSchema,
 	summary: "Steer the in-flight run",
@@ -790,9 +805,9 @@ const STEER_AGENT_CONTROLLER_SESSION_ROUTE = createRoute({
 	tags: ["AgentController"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, message, files, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, message, files, requestContext }) => {
 		try {
-			const session = await getSession(getAgentControllerOrThrow(mastra, controllerId), resourceId, { scope: sessionScope }, requestContext);
+			const session = await getSession(getAgentControllerOrThrow(mastra, controllerId), sessionId, requestContext);
 			const author = getRequestMessageAuthor(requestContext);
 			ackBackgroundSessionWork({
 				work: session.steer({
@@ -813,10 +828,10 @@ const STEER_AGENT_CONTROLLER_SESSION_ROUTE = createRoute({
 });
 const SWITCH_AGENT_CONTROLLER_MODE_ROUTE = createRoute({
 	method: "POST",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/mode",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/mode",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	bodySchema: switchModeBodySchema,
 	responseSchema: ackResponseSchema,
 	summary: "Switch the session mode",
@@ -824,9 +839,9 @@ const SWITCH_AGENT_CONTROLLER_MODE_ROUTE = createRoute({
 	tags: ["AgentController"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, modeId, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, modeId, requestContext }) => {
 		try {
-			await (await getSession(getAgentControllerOrThrow(mastra, controllerId), resourceId, { scope: sessionScope }, requestContext)).mode.switch({ modeId });
+			await (await getSession(getAgentControllerOrThrow(mastra, controllerId), sessionId, requestContext)).mode.switch({ modeId });
 			return { ok: true };
 		} catch (error) {
 			return handleError(error, "error switching controller mode");
@@ -835,10 +850,10 @@ const SWITCH_AGENT_CONTROLLER_MODE_ROUTE = createRoute({
 });
 const SWITCH_AGENT_CONTROLLER_MODEL_ROUTE = createRoute({
 	method: "POST",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/model",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/model",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	bodySchema: switchModelBodySchema,
 	responseSchema: ackResponseSchema,
 	summary: "Switch the session model",
@@ -846,9 +861,9 @@ const SWITCH_AGENT_CONTROLLER_MODEL_ROUTE = createRoute({
 	tags: ["AgentController"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, modelId, thinkingLevel, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, modelId, thinkingLevel, requestContext }) => {
 		try {
-			await (await getSession(getAgentControllerOrThrow(mastra, controllerId), resourceId, { scope: sessionScope }, requestContext)).model.switch(modelId, { thinkingLevel });
+			await (await getSession(getAgentControllerOrThrow(mastra, controllerId), sessionId, requestContext)).model.switch(modelId, { thinkingLevel });
 			return { ok: true };
 		} catch (error) {
 			return handleError(error, "error switching controller model");
@@ -857,10 +872,10 @@ const SWITCH_AGENT_CONTROLLER_MODEL_ROUTE = createRoute({
 });
 const SWITCH_AGENT_CONTROLLER_THREAD_ROUTE = createRoute({
 	method: "POST",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/thread",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/thread",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	bodySchema: switchThreadBodySchema,
 	responseSchema: ackResponseSchema,
 	summary: "Switch the session thread",
@@ -868,9 +883,9 @@ const SWITCH_AGENT_CONTROLLER_THREAD_ROUTE = createRoute({
 	tags: ["AgentController"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, threadId, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, threadId, requestContext }) => {
 		try {
-			const session = await getSession(getAgentControllerOrThrow(mastra, controllerId), resourceId, { scope: sessionScope }, requestContext);
+			const session = await getSession(getAgentControllerOrThrow(mastra, controllerId), sessionId, requestContext);
 			if (session.thread.getId() !== threadId) await session.thread.switch({
 				threadId,
 				requestContext
@@ -883,22 +898,23 @@ const SWITCH_AGENT_CONTROLLER_THREAD_ROUTE = createRoute({
 });
 const TRANSFER_AGENT_CONTROLLER_THREAD_OWNERSHIP_ROUTE = createRoute({
 	method: "POST",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/threads/:threadId/owner",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/threads/:threadId/owner",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: threadPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	responseSchema: transferOwnershipResponseSchema,
 	summary: "Take ownership of a thread",
 	description: "Transfers ownership of the specified thread to the authenticated user from the request context. The thread must belong to the session's resource, and the caller needs memory write access to it. The session's active thread does not change.",
 	tags: ["AgentController", "Threads"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, threadId, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, threadId, requestContext }) => {
 		try {
 			const ownerId = getRequestMessageAuthor(requestContext)?.id;
 			if (!ownerId) throw new HTTPException(401, { message: "An authenticated user is required to transfer thread ownership" });
 			const controller = getAgentControllerOrThrow(mastra, controllerId);
 			await controller.init();
+			const resourceId = await resolveSessionResourceId(controller, sessionId);
 			const thread = await controller.queryThreadById({ threadId });
 			if (!thread || thread.resourceId !== resourceId) throw new HTTPException(404, { message: "Thread not found" });
 			await enforceThreadAccess({
@@ -909,7 +925,7 @@ const TRANSFER_AGENT_CONTROLLER_THREAD_OWNERSHIP_ROUTE = createRoute({
 				effectiveResourceId: resourceId,
 				permission: MastraFGAPermissions.MEMORY_WRITE
 			});
-			await (await getSession(controller, resourceId, { scope: sessionScope }, requestContext)).thread.transferOwnership({
+			await (await getSession(controller, sessionId, requestContext)).thread.transferOwnership({
 				toOwnerId: ownerId,
 				threadId
 			});
@@ -924,7 +940,7 @@ const TRANSFER_AGENT_CONTROLLER_THREAD_OWNERSHIP_ROUTE = createRoute({
 });
 const GET_AGENT_CONTROLLER_SESSION_STATE_ROUTE = createRoute({
 	method: "GET",
-	path: "/agent-controller/:controllerId/sessions/:resourceId",
+	path: "/agent-controller/:controllerId/sessions/:sessionId",
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
 	queryParamSchema: sessionStateQuerySchema,
@@ -934,9 +950,10 @@ const GET_AGENT_CONTROLLER_SESSION_STATE_ROUTE = createRoute({
 	tags: ["AgentController"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:read",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, threadId: requestedThreadId, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, threadId: requestedThreadId, requestContext }) => {
 		try {
-			const session = await getExistingSession(getAgentControllerOrThrow(mastra, controllerId), resourceId, sessionScope, requestContext);
+			const session = await getExistingSession(getAgentControllerOrThrow(mastra, controllerId), sessionId, requestContext);
+			const resourceId = session.identity.getResourceId();
 			const ds = session.displayState.get();
 			const threadId = requestedThreadId ?? session.thread.getId() ?? void 0;
 			const storage = mastra.getStorage();
@@ -960,6 +977,7 @@ const GET_AGENT_CONTROLLER_SESSION_STATE_ROUTE = createRoute({
 			const oneOfOptional = (value, allowed) => allowed.includes(value) ? value : void 0;
 			return {
 				controllerId,
+				sessionId: session.identity.getId(),
 				resourceId,
 				threadId,
 				modeId: session.mode.get(),
@@ -1049,19 +1067,20 @@ const LIST_AGENT_CONTROLLER_ACTIVE_RUNS_ROUTE = createRoute({
 });
 const LIST_AGENT_CONTROLLER_THREADS_ROUTE = createRoute({
 	method: "GET",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/threads",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/threads",
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
 	queryParamSchema: listThreadsQuerySchema,
 	responseSchema: listThreadsResponseSchema,
 	summary: "List session threads",
-	description: "Lists the threads for the session’s resource, most-recently-updated first. Pass `limit` to return only the newest N (e.g. for a sidebar). Pass `tags` (a JSON-encoded object) to scope the list to threads matching every tag — e.g. `{ projectPath }` so git worktrees sharing a resourceId each see only their own threads.",
+	description: "Lists every thread of the session’s resource (not only the session’s own threads), most-recently-updated first. Pass `limit` to return only the newest N (e.g. for a sidebar). Pass `tags` (a JSON-encoded object) to scope the list to threads matching every tag — e.g. `{ projectPath }` so git worktrees sharing a resourceId each see only their own threads.",
 	tags: ["AgentController"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:read",
-	handler: async ({ mastra, controllerId, resourceId, limit, tags }) => {
+	handler: async ({ mastra, controllerId, sessionId, limit, tags }) => {
 		try {
 			const controller = getAgentControllerOrThrow(mastra, controllerId);
+			const resourceId = await resolveSessionResourceId(controller, sessionId);
 			const threads = await controller.queryThreads({ resourceId });
 			const getTags = (t) => {
 				const metadata = t.metadata ?? {};
@@ -1096,10 +1115,10 @@ const LIST_AGENT_CONTROLLER_THREADS_ROUTE = createRoute({
 });
 const SEND_AGENT_CONTROLLER_NOTIFICATION_ROUTE = createRoute({
 	method: "POST",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/notifications",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/notifications",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	bodySchema: sendNotificationBodySchema,
 	responseSchema: z.object({
 		accepted: z.boolean(),
@@ -1112,9 +1131,9 @@ const SEND_AGENT_CONTROLLER_NOTIFICATION_ROUTE = createRoute({
 	tags: ["AgentController"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, source, kind, summary, priority, payload, sourceId, dedupeKey, coalesceKey, attributes, metadata, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, source, kind, summary, priority, payload, sourceId, dedupeKey, coalesceKey, attributes, metadata, requestContext }) => {
 		try {
-			const result = await (await getSession(getAgentControllerOrThrow(mastra, controllerId), resourceId, { scope: sessionScope }, requestContext)).sendNotificationSignal({
+			const result = await (await getSession(getAgentControllerOrThrow(mastra, controllerId), sessionId, requestContext)).sendNotificationSignal({
 				source,
 				kind,
 				summary,
@@ -1139,10 +1158,10 @@ const SEND_AGENT_CONTROLLER_NOTIFICATION_ROUTE = createRoute({
 });
 const CREATE_AGENT_CONTROLLER_THREAD_ROUTE = createRoute({
 	method: "POST",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/threads",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/threads",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	bodySchema: createThreadBodySchema,
 	responseSchema: threadResponseSchema,
 	summary: "Create a new thread",
@@ -1150,9 +1169,9 @@ const CREATE_AGENT_CONTROLLER_THREAD_ROUTE = createRoute({
 	tags: ["AgentController", "Threads"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, title, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, title, requestContext }) => {
 		try {
-			const thread = await (await getSession(getAgentControllerOrThrow(mastra, controllerId), resourceId, { scope: sessionScope }, requestContext)).thread.create({
+			const thread = await (await getSession(getAgentControllerOrThrow(mastra, controllerId), sessionId, requestContext)).thread.create({
 				title,
 				requestContext
 			});
@@ -1170,19 +1189,19 @@ const CREATE_AGENT_CONTROLLER_THREAD_ROUTE = createRoute({
 });
 const DELETE_AGENT_CONTROLLER_THREAD_ROUTE = createRoute({
 	method: "DELETE",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/threads/:threadId",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/threads/:threadId",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: threadPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	responseSchema: ackResponseSchema,
 	summary: "Delete a thread",
 	description: "Deletes a thread. If the deleted thread is the active one, the session is unbound.",
 	tags: ["AgentController", "Threads"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, threadId, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, threadId, requestContext }) => {
 		try {
-			await (await getSession(getAgentControllerOrThrow(mastra, controllerId), resourceId, { scope: sessionScope }, requestContext)).thread.delete({
+			await (await getSession(getAgentControllerOrThrow(mastra, controllerId), sessionId, requestContext)).thread.delete({
 				threadId,
 				requestContext
 			});
@@ -1194,10 +1213,10 @@ const DELETE_AGENT_CONTROLLER_THREAD_ROUTE = createRoute({
 });
 const RENAME_AGENT_CONTROLLER_THREAD_ROUTE = createRoute({
 	method: "PUT",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/threads/:threadId",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/threads/:threadId",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: threadPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	bodySchema: renameThreadBodySchema,
 	responseSchema: ackResponseSchema,
 	summary: "Rename a thread",
@@ -1205,9 +1224,9 @@ const RENAME_AGENT_CONTROLLER_THREAD_ROUTE = createRoute({
 	tags: ["AgentController", "Threads"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, threadId, title, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, threadId, title, requestContext }) => {
 		try {
-			const session = await getSession(getAgentControllerOrThrow(mastra, controllerId), resourceId, { scope: sessionScope }, requestContext);
+			const session = await getSession(getAgentControllerOrThrow(mastra, controllerId), sessionId, requestContext);
 			if (session.thread.getId() !== threadId) await session.thread.switch({
 				threadId,
 				requestContext
@@ -1221,10 +1240,10 @@ const RENAME_AGENT_CONTROLLER_THREAD_ROUTE = createRoute({
 });
 const CLONE_AGENT_CONTROLLER_THREAD_ROUTE = createRoute({
 	method: "POST",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/threads/clone",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/threads/clone",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	bodySchema: cloneThreadBodySchema,
 	responseSchema: threadResponseSchema,
 	summary: "Clone a thread",
@@ -1232,9 +1251,9 @@ const CLONE_AGENT_CONTROLLER_THREAD_ROUTE = createRoute({
 	tags: ["AgentController", "Threads"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, sourceThreadId, title, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, sourceThreadId, title, requestContext }) => {
 		try {
-			const thread = await (await getSession(getAgentControllerOrThrow(mastra, controllerId), resourceId, { scope: sessionScope }, requestContext)).thread.clone({
+			const thread = await (await getSession(getAgentControllerOrThrow(mastra, controllerId), sessionId, requestContext)).thread.clone({
 				sourceThreadId,
 				title,
 				requestContext
@@ -1253,7 +1272,7 @@ const CLONE_AGENT_CONTROLLER_THREAD_ROUTE = createRoute({
 });
 const LIST_AGENT_CONTROLLER_THREAD_MESSAGES_ROUTE = createRoute({
 	method: "GET",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/threads/:threadId/messages",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/threads/:threadId/messages",
 	responseType: "json",
 	pathParamSchema: threadPathParams,
 	queryParamSchema: listMessagesQuerySchema,
@@ -1263,12 +1282,13 @@ const LIST_AGENT_CONTROLLER_THREAD_MESSAGES_ROUTE = createRoute({
 	tags: ["AgentController", "Threads"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:read",
-	handler: async ({ mastra, controllerId, resourceId, threadId, limit, page, perPage, orderBy, include, filter, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, threadId, limit, page, perPage, orderBy, include, filter, requestContext }) => {
 		try {
 			if (limit !== void 0 && (perPage !== void 0 || orderBy !== void 0 || include !== void 0 || filter !== void 0)) throw new HTTPException(400, { message: "limit can only be combined with page; use perPage instead" });
 			const controller = getAgentControllerOrThrow(mastra, controllerId);
+			const resourceId = await resolveSessionResourceId(controller, sessionId);
 			const thread = await controller.queryThreadById({ threadId });
-			if (!thread || resourceId && thread.resourceId && thread.resourceId !== resourceId) throw new HTTPException(404, { message: "Thread not found" });
+			if (!thread || thread.resourceId && thread.resourceId !== resourceId) throw new HTTPException(404, { message: "Thread not found" });
 			await enforceThreadAccess({
 				mastra,
 				requestContext,
@@ -1315,10 +1335,10 @@ const LIST_AGENT_CONTROLLER_THREAD_MESSAGES_ROUTE = createRoute({
 });
 const FOLLOW_UP_AGENT_CONTROLLER_SESSION_ROUTE = createRoute({
 	method: "POST",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/follow-up",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/follow-up",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	bodySchema: followUpBodySchema,
 	responseSchema: ackResponseSchema,
 	summary: "Queue a follow-up message",
@@ -1326,9 +1346,9 @@ const FOLLOW_UP_AGENT_CONTROLLER_SESSION_ROUTE = createRoute({
 	tags: ["AgentController"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, message, files, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, message, files, requestContext }) => {
 		try {
-			const session = await getSession(getAgentControllerOrThrow(mastra, controllerId), resourceId, { scope: sessionScope }, requestContext);
+			const session = await getSession(getAgentControllerOrThrow(mastra, controllerId), sessionId, requestContext);
 			ackBackgroundSessionWork({
 				work: session.followUp({
 					content: message,
@@ -1398,20 +1418,20 @@ const GET_AGENT_CONTROLLER_WORKSPACE_STATUS_ROUTE = createRoute({
 });
 const GET_AGENT_CONTROLLER_OM_RECORD_ROUTE = createRoute({
 	method: "GET",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/om",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/om",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	responseSchema: omRecordResponseSchema,
 	summary: "Get observational memory record",
 	description: "Returns the current observational memory record for the session’s thread/resource.",
 	tags: ["AgentController"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:read",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, requestContext }) => {
 		try {
 			const controller = getAgentControllerOrThrow(mastra, controllerId);
-			const session = await getExistingSession(controller, resourceId, sessionScope, requestContext);
+			const session = await getExistingSession(controller, sessionId, requestContext);
 			return { record: await controller.getObservationalMemoryRecord(session) ?? void 0 };
 		} catch (error) {
 			return handleError(error, "error reading controller OM record");
@@ -1420,10 +1440,10 @@ const GET_AGENT_CONTROLLER_OM_RECORD_ROUTE = createRoute({
 });
 const SET_AGENT_CONTROLLER_RESOURCE_ID_ROUTE = createRoute({
 	method: "POST",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/resource",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/resource",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	bodySchema: z.object({ newResourceId: z.string() }),
 	responseSchema: ackResponseSchema,
 	summary: "Change the session resource ID",
@@ -1431,10 +1451,10 @@ const SET_AGENT_CONTROLLER_RESOURCE_ID_ROUTE = createRoute({
 	tags: ["AgentController"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, newResourceId, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, newResourceId, requestContext }) => {
 		try {
 			const controller = getAgentControllerOrThrow(mastra, controllerId);
-			const session = await getSession(controller, resourceId, { scope: sessionScope }, requestContext);
+			const session = await getSession(controller, sessionId, requestContext);
 			await controller.setResourceId(session, { resourceId: newResourceId });
 			return { ok: true };
 		} catch (error) {
@@ -1444,20 +1464,20 @@ const SET_AGENT_CONTROLLER_RESOURCE_ID_ROUTE = createRoute({
 });
 const GET_AGENT_CONTROLLER_RESOURCE_IDS_ROUTE = createRoute({
 	method: "GET",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/resources",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/resources",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	responseSchema: z.object({ resourceIds: z.array(z.string()) }),
 	summary: "Get known resource IDs",
 	description: "Lists the resource IDs known to this session (from threads).",
 	tags: ["AgentController"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:read",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, requestContext }) => {
 		try {
 			const controller = getAgentControllerOrThrow(mastra, controllerId);
-			const session = await getExistingSession(controller, resourceId, sessionScope, requestContext);
+			const session = await getExistingSession(controller, sessionId, requestContext);
 			return { resourceIds: await controller.getKnownResourceIds(session) };
 		} catch (error) {
 			return handleError(error, "error listing controller resource IDs");
@@ -1499,20 +1519,20 @@ function getAgentForSession(controller, session) {
 }
 const GET_AGENT_CONTROLLER_GOAL_ROUTE = createRoute({
 	method: "GET",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/goal",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/goal",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	responseSchema: goalResponseSchema,
 	summary: "Get the current goal",
 	description: "Returns the active/paused/done goal objective for the session’s thread, if any.",
 	tags: ["AgentController", "Goals"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:read",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, requestContext }) => {
 		try {
 			const controller = getAgentControllerOrThrow(mastra, controllerId);
-			const session = await getExistingSession(controller, resourceId, sessionScope, requestContext);
+			const session = await getExistingSession(controller, sessionId, requestContext);
 			const threadId = session.thread.getId();
 			if (!threadId) return { goal: void 0 };
 			return { goal: await getAgentForSession(controller, session).getObjective({ threadId }) ?? void 0 };
@@ -1523,10 +1543,10 @@ const GET_AGENT_CONTROLLER_GOAL_ROUTE = createRoute({
 });
 const SET_AGENT_CONTROLLER_GOAL_ROUTE = createRoute({
 	method: "POST",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/goal",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/goal",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	bodySchema: setGoalBodySchema,
 	responseSchema: goalResponseSchema,
 	summary: "Set a goal",
@@ -1534,10 +1554,10 @@ const SET_AGENT_CONTROLLER_GOAL_ROUTE = createRoute({
 	tags: ["AgentController", "Goals"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, objective, judgeModelId, maxRuns, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, objective, judgeModelId, maxRuns, requestContext }) => {
 		try {
 			const controller = getAgentControllerOrThrow(mastra, controllerId);
-			const session = await getSession(controller, resourceId, { scope: sessionScope }, requestContext);
+			const session = await getSession(controller, sessionId, requestContext);
 			const threadId = session.thread.getId();
 			if (!threadId) throw new HTTPException(400, { message: "session has no active thread" });
 			return { goal: await getAgentForSession(controller, session).setObjective(objective, {
@@ -1553,10 +1573,10 @@ const SET_AGENT_CONTROLLER_GOAL_ROUTE = createRoute({
 });
 const UPDATE_AGENT_CONTROLLER_GOAL_ROUTE = createRoute({
 	method: "PUT",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/goal",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/goal",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	bodySchema: updateGoalBodySchema,
 	responseSchema: goalResponseSchema,
 	summary: "Update goal options",
@@ -1564,10 +1584,10 @@ const UPDATE_AGENT_CONTROLLER_GOAL_ROUTE = createRoute({
 	tags: ["AgentController", "Goals"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, judgeModelId, maxRuns, status, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, judgeModelId, maxRuns, status, requestContext }) => {
 		try {
 			const controller = getAgentControllerOrThrow(mastra, controllerId);
-			const session = await getSession(controller, resourceId, { scope: sessionScope }, requestContext);
+			const session = await getSession(controller, sessionId, requestContext);
 			const threadId = session.thread.getId();
 			if (!threadId) throw new HTTPException(400, { message: "session has no active thread" });
 			return { goal: await getAgentForSession(controller, session).updateObjectiveOptions({
@@ -1583,20 +1603,20 @@ const UPDATE_AGENT_CONTROLLER_GOAL_ROUTE = createRoute({
 });
 const CLEAR_AGENT_CONTROLLER_GOAL_ROUTE = createRoute({
 	method: "DELETE",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/goal",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/goal",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	responseSchema: ackResponseSchema,
 	summary: "Clear the goal",
 	description: "Removes the active goal from the session’s thread.",
 	tags: ["AgentController", "Goals"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, requestContext }) => {
 		try {
 			const controller = getAgentControllerOrThrow(mastra, controllerId);
-			const session = await getSession(controller, resourceId, { scope: sessionScope }, requestContext);
+			const session = await getSession(controller, sessionId, requestContext);
 			const threadId = session.thread.getId();
 			if (!threadId) throw new HTTPException(400, { message: "session has no active thread" });
 			await getAgentForSession(controller, session).clearObjective({ threadId });
@@ -1608,19 +1628,19 @@ const CLEAR_AGENT_CONTROLLER_GOAL_ROUTE = createRoute({
 });
 const GET_AGENT_CONTROLLER_PERMISSIONS_ROUTE = createRoute({
 	method: "GET",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/permissions",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/permissions",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	responseSchema: permissionRulesResponseSchema,
 	summary: "Get permission rules",
 	description: "Returns the current permission rules (per-category and per-tool policies) for the session.",
 	tags: ["AgentController", "Permissions"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:read",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, requestContext }) => {
 		try {
-			const rules = (await getExistingSession(getAgentControllerOrThrow(mastra, controllerId), resourceId, sessionScope, requestContext)).permissions.getRules();
+			const rules = (await getExistingSession(getAgentControllerOrThrow(mastra, controllerId), sessionId, requestContext)).permissions.getRules();
 			return {
 				categories: rules.categories,
 				tools: rules.tools
@@ -1632,10 +1652,10 @@ const GET_AGENT_CONTROLLER_PERMISSIONS_ROUTE = createRoute({
 });
 const SET_AGENT_CONTROLLER_CATEGORY_PERMISSION_ROUTE = createRoute({
 	method: "PUT",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/permissions/category",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/permissions/category",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	bodySchema: setCategoryPermissionBodySchema,
 	responseSchema: ackResponseSchema,
 	summary: "Set permission for a tool category",
@@ -1643,9 +1663,9 @@ const SET_AGENT_CONTROLLER_CATEGORY_PERMISSION_ROUTE = createRoute({
 	tags: ["AgentController", "Permissions"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, category, policy, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, category, policy, requestContext }) => {
 		try {
-			await (await getSession(getAgentControllerOrThrow(mastra, controllerId), resourceId, { scope: sessionScope }, requestContext)).permissions.setForCategory({
+			await (await getSession(getAgentControllerOrThrow(mastra, controllerId), sessionId, requestContext)).permissions.setForCategory({
 				category,
 				policy
 			});
@@ -1657,10 +1677,10 @@ const SET_AGENT_CONTROLLER_CATEGORY_PERMISSION_ROUTE = createRoute({
 });
 const SET_AGENT_CONTROLLER_TOOL_PERMISSION_ROUTE = createRoute({
 	method: "PUT",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/permissions/tool",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/permissions/tool",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	bodySchema: setToolPermissionBodySchema,
 	responseSchema: ackResponseSchema,
 	summary: "Set permission for a specific tool",
@@ -1668,9 +1688,9 @@ const SET_AGENT_CONTROLLER_TOOL_PERMISSION_ROUTE = createRoute({
 	tags: ["AgentController", "Permissions"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, toolName, policy, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, toolName, policy, requestContext }) => {
 		try {
-			await (await getSession(getAgentControllerOrThrow(mastra, controllerId), resourceId, { scope: sessionScope }, requestContext)).permissions.setForTool({
+			await (await getSession(getAgentControllerOrThrow(mastra, controllerId), sessionId, requestContext)).permissions.setForTool({
 				toolName,
 				policy
 			});
@@ -1682,10 +1702,10 @@ const SET_AGENT_CONTROLLER_TOOL_PERMISSION_ROUTE = createRoute({
 });
 const SET_AGENT_CONTROLLER_SESSION_STATE_ROUTE = createRoute({
 	method: "PUT",
-	path: "/agent-controller/:controllerId/sessions/:resourceId/state",
+	path: "/agent-controller/:controllerId/sessions/:sessionId/state",
+	queryParamSchema: sessionQuerySchema,
 	responseType: "json",
 	pathParamSchema: sessionPathParams,
-	queryParamSchema: sessionScopeQuerySchema,
 	bodySchema: z.object({ state: z.record(z.string(), z.unknown()) }),
 	responseSchema: ackResponseSchema,
 	summary: "Set session state",
@@ -1693,9 +1713,9 @@ const SET_AGENT_CONTROLLER_SESSION_STATE_ROUTE = createRoute({
 	tags: ["AgentController"],
 	requiresAuth: true,
 	requiresPermission: "agent-controller:execute",
-	handler: async ({ mastra, controllerId, resourceId, sessionScope, state, requestContext }) => {
+	handler: async ({ mastra, controllerId, sessionId, state, requestContext }) => {
 		try {
-			await (await getSession(getAgentControllerOrThrow(mastra, controllerId), resourceId, { scope: sessionScope }, requestContext)).state.set(state);
+			await (await getSession(getAgentControllerOrThrow(mastra, controllerId), sessionId, requestContext)).state.set(state);
 			return { ok: true };
 		} catch (error) {
 			return handleError(error, "error setting controller session state");