@mastra/factory 0.21.1-alpha.3 → 0.22.0-alpha.4

package/dist/session/source-control-tools.js

@@ -1,10 +1,12 @@
 import { getFactoryAuthOrgId, getFactoryAuthUserFromContext, getFactoryAuthUserId } from "../auth.js";
 import { mergeRequestNumberFromBranch } from "../work-item-branch.js";
-import { normalizedVerdictLine } from "../review-verdict.js";
+import { ensureLocalBranch, isCheckoutOf, pushRepositoryBranch, refreshMergeRequestCheckout } from "../integrations/github/sandbox.js";
 import { resolveSessionWorkdir } from "../sandbox/session-sandbox.js";
-import { pushRepositoryBranch, refreshMergeRequestCheckout } from "../integrations/github/sandbox.js";
-import { createTool } from "@mastra/core/tools";
+import { updateSessionEnvironmentRepository } from "./environment-state-processor.js";
+import { environmentSlugs, findEnvironmentRepository, resolveSessionRepositories } from "./environment-repositories.js";
+import { normalizedVerdictLine } from "../review-verdict.js";
 import { z } from "zod";
+import { createTool } from "@mastra/core/tools";
 //#region src/session/source-control-tools.ts
 /** Returns why a review's leading `Verdict:` line contradicts the submitted event, if it does. */
 function verdictEventMismatch(event, body) {
@@ -34,45 +36,93 @@ function authIdentity(requestContext) {
 		userId: getFactoryAuthUserId(user)
 	};
 }
-async function resolveSessionTarget(requestContext, providers) {
-	const context = requestContext.get("controller");
-	const { orgId, userId } = authIdentity(requestContext);
-	if (!context?.resourceId || !orgId || !userId) throw new Error("Source-control tools require an authenticated repository session.");
+async function resolveProviderSession(resourceId, providers) {
 	const matches = (await Promise.all(providers.map(async (provider) => ({
 		provider,
-		session: await provider.storage.sessions.getBySessionId(context.resourceId)
+		session: await provider.storage.sessions.getBySessionId(resourceId)
 	})))).filter((match) => match.session !== null);
 	if (matches.length !== 1) throw new Error(matches.length === 0 ? "The active session is not backed by a source-control repository." : "The active session is ambiguous across source-control providers.");
-	const { provider, session } = matches[0];
+	return matches[0];
+}
+async function resolveSessionTarget(requestContext, providers, options = {}) {
+	const context = requestContext.get("controller");
+	const { orgId, userId } = authIdentity(requestContext);
+	if (!context?.resourceId || !orgId || !userId) throw new Error("Source-control tools require an authenticated repository session.");
+	const { provider, session } = await resolveProviderSession(context.resourceId, providers);
 	if (session.orgId !== orgId || session.visibility === "private" && session.userId !== userId) throw new Error("The active source-control session is not available to the authenticated user.");
-	const projectRepository = await provider.storage.projectRepositories.get({
+	const ownRepository = session.projectRepositoryId ? await provider.storage.projectRepositories.get({
 		orgId,
 		id: session.projectRepositoryId
-	});
-	if (!projectRepository) throw new Error("The active project repository was not found.");
+	}) : null;
+	if (!ownRepository) throw new Error("The active project repository was not found.");
 	const state = context.getState();
-	if (state.projectRepositoryId && state.projectRepositoryId !== projectRepository.id) throw new Error("The active source-control session does not match its controller repository.");
-	const connection = await provider.storage.connections.get({
+	if (state.projectRepositoryId && state.projectRepositoryId !== ownRepository.id) throw new Error("The active source-control session does not match its controller repository.");
+	const ownConnection = await provider.storage.connections.get({
 		orgId,
-		id: projectRepository.connectionId
+		id: ownRepository.connectionId
 	});
-	if (!connection) throw new Error("The active source-control connection was not found.");
-	if (state.factoryProjectId && state.factoryProjectId !== connection.factoryProjectId) throw new Error("The active source-control session does not match its Factory project.");
+	if (!ownConnection) throw new Error("The active source-control connection was not found.");
+	if (state.factoryProjectId && state.factoryProjectId !== ownConnection.factoryProjectId) throw new Error("The active source-control session does not match its Factory project.");
+	if (options.repository !== void 0) {
+		const candidates = await resolveSessionRepositories({
+			sourceControl: provider.storage,
+			session
+		});
+		const match = findEnvironmentRepository(candidates, options.repository);
+		if (!match) throw new Error(`Repository '${options.repository}' is not in this Factory's environment. Valid repositories: ${environmentSlugs(candidates).join(", ")}.`);
+		return {
+			context,
+			provider,
+			session,
+			projectRepository: match.link,
+			repository: match.repository,
+			orgId,
+			userId,
+			ownRepository: match.link.id === ownRepository.id
+		};
+	}
 	const repository = await provider.storage.repositories.get({
 		orgId,
-		id: projectRepository.repositoryId
+		id: ownRepository.repositoryId
 	});
 	if (!repository) throw new Error("The active source-control repository was not found.");
 	return {
 		context,
 		provider,
 		session,
-		projectRepository,
+		projectRepository: ownRepository,
 		repository,
 		orgId,
-		userId
+		userId,
+		ownRepository: true
 	};
 }
+/**
+* The slugs a session may target and the one it is filed under, for the tool
+* descriptions. `undefined` when the session cannot be resolved; the tools
+* then describe the default without naming it.
+*/
+async function describeSessionRepositories(resourceId, providers) {
+	try {
+		const { provider, session } = await resolveProviderSession(resourceId, providers);
+		const repositories = await resolveSessionRepositories({
+			sourceControl: provider.storage,
+			session
+		});
+		const own = repositories.find((candidate) => candidate.link.id === session.projectRepositoryId);
+		return {
+			slugs: environmentSlugs(repositories),
+			own: own?.repository.slug
+		};
+	} catch {
+		return;
+	}
+}
+function repositoryArgumentDescription(described) {
+	if (!described || described.slugs.length === 0) return "Optional `repository` (owner/name) selects another repository of this Factory's environment; defaults to this session's repository.";
+	const fallback = described.own ? `${described.own}, this session's repository` : "this session's repository";
+	return `Optional \`repository\` (owner/name) selects one of this Factory's environment repositories: ${described.slugs.join(", ")}. Defaults to ${fallback}.`;
+}
 function changeRequestId(value) {
 	return String(value);
 }
@@ -94,13 +144,16 @@ async function emitAgentAudit(audit, requestContext, input) {
 		});
 	}
 }
-const changeRequestSchema = z.object({ changeRequestId: z.union([z.string().trim().min(1), z.number().int().positive()]) });
-function createSourceControlTools({ requestContext, providers, audit }) {
+const repositorySchema = z.object({ repository: z.string().trim().min(1).optional() });
+const changeRequestSchema = repositorySchema.extend({ changeRequestId: z.union([z.string().trim().min(1), z.number().int().positive()]) });
+async function createSourceControlTools({ requestContext, providers, audit }) {
 	if (!requestContext || typeof requestContext.get !== "function") return {};
 	const controller = requestContext.get("controller");
 	const identity = authIdentity(requestContext);
 	if (!controller?.resourceId || !identity.orgId || !identity.userId || providers.length === 0) return {};
-	const withTarget = () => resolveSessionTarget(requestContext, providers);
+	const repositoryArgument = repositoryArgumentDescription(await describeSessionRepositories(controller.resourceId, providers));
+	const withTarget = (options) => resolveSessionTarget(requestContext, providers, options);
+	const targetFor = (input) => withTarget(input.repository !== void 0 ? { repository: input.repository } : void 0);
 	const reference = async (target) => ({
 		...await target.provider.versionControl.getRepositoryTarget({
 			orgId: target.orgId,
@@ -139,17 +192,26 @@ function createSourceControlTools({ requestContext, providers, audit }) {
 		}),
 		source_control_push_branch: createTool({
 			id: "source_control_push_branch",
-			description: "Push the active Factory session branch to its connected source-control provider. Credentials are resolved and scrubbed server-side; this tool takes no token, repository, remote, or branch arguments.",
-			inputSchema: z.object({}),
-			execute: async (_input, { workspace }) => {
-				const target = await withTarget();
+			description: `Push the active Factory session branch to its connected source-control provider. Credentials are resolved and scrubbed server-side; this tool takes no token, remote, or branch arguments. ${repositoryArgument}`,
+			inputSchema: repositorySchema,
+			execute: async (input, { workspace }) => {
+				const target = await targetFor(input);
 				const sandbox = executableSandbox(workspace?.sandbox);
 				const workdir = await resolveSessionWorkdir(target.session.id, sandbox, target.repository.slug);
 				const access = await target.provider.versionControl.getRepositoryAccess({
 					orgId: target.orgId,
 					repositoryId: target.repository.id
 				});
-				await pushRepositoryBranch(sandbox, workdir, target.session.branch, access, target.repository.slug);
+				if (!target.ownRepository && !await isCheckoutOf(sandbox, workdir, access.cloneUrl)) throw new Error(`There is no checkout of ${target.repository.slug} in this session.`);
+				const branch = target.session.branch;
+				await ensureLocalBranch(sandbox, workdir, branch);
+				await pushRepositoryBranch(sandbox, workdir, branch, access, target.repository.slug);
+				await target.provider.storage.sessionRepositories.upsert({
+					sessionId: target.session.sessionId,
+					projectRepositoryId: target.projectRepository.id,
+					branch
+				});
+				updateSessionEnvironmentRepository(target.session.sessionId, target.repository.slug, { branch });
 				await emitAgentAudit(audit, requestContext, {
 					action: "factory.agent.push",
 					targets: [{
@@ -157,23 +219,24 @@ function createSourceControlTools({ requestContext, providers, audit }) {
 						id: target.repository.slug
 					}],
 					metadata: {
-						branch: target.session.branch,
-						provider: target.provider.id
+						branch,
+						provider: target.provider.id,
+						repository: target.repository.slug
 					}
 				});
 				return {
 					pushed: true,
-					branch: target.session.branch,
+					branch,
 					repository: target.repository.slug
 				};
 			}
 		}),
 		source_control_get_change_request: createTool({
 			id: "source_control_get_change_request",
-			description: "Read a pull request or merge request in the active Factory repository by its numeric repository-local ID.",
+			description: `Read a pull request or merge request in the active Factory repository by its numeric repository-local ID. ${repositoryArgument}`,
 			inputSchema: changeRequestSchema,
 			execute: async (input) => {
-				const target = await withTarget();
+				const target = await targetFor(input);
 				return target.provider.versionControl.getPullRequest({
 					...await reference(target),
 					pullRequestId: changeRequestId(input.changeRequestId)
@@ -182,10 +245,10 @@ function createSourceControlTools({ requestContext, providers, audit }) {
 		}),
 		source_control_list_change_request_reviews: createTool({
 			id: "source_control_list_change_request_reviews",
-			description: "List submitted reviews and approvals on a pull request or merge request in the active repository.",
+			description: `List submitted reviews and approvals on a pull request or merge request in the active repository. ${repositoryArgument}`,
 			inputSchema: changeRequestSchema.extend({ cursor: z.string().trim().min(1).optional() }),
 			execute: async (input) => {
-				const target = await withTarget();
+				const target = await targetFor(input);
 				return target.provider.versionControl.listReviews({
 					...await reference(target),
 					pullRequestId: changeRequestId(input.changeRequestId),
@@ -195,22 +258,31 @@ function createSourceControlTools({ requestContext, providers, audit }) {
 		}),
 		source_control_create_change_request: createTool({
 			id: "source_control_create_change_request",
-			description: "Open a pull request or merge request from the active Factory session branch into its persisted base branch. Push the branch with source_control_push_branch first.",
-			inputSchema: z.object({
+			description: `Open a pull request or merge request from the active Factory session branch into the repository's base branch (the session's persisted base branch in its own repository, the linked or default branch elsewhere). Push the branch with source_control_push_branch first. ${repositoryArgument}`,
+			inputSchema: repositorySchema.extend({
 				title: z.string().trim().min(1),
 				body: z.string().optional(),
 				draft: z.boolean().optional()
 			}),
 			execute: async (input) => {
-				const target = await withTarget();
+				const target = await targetFor(input);
+				const baseBranch = target.ownRepository ? target.session.baseBranch : target.projectRepository.branch ?? target.repository.defaultBranch;
 				const created = await target.provider.versionControl.createPullRequest({
 					...await reference(target),
 					title: input.title,
 					...input.body !== void 0 ? { body: input.body } : {},
-					baseBranch: target.session.baseBranch,
+					baseBranch,
 					headBranch: target.session.branch,
 					...input.draft !== void 0 ? { draft: input.draft } : {}
 				});
+				await target.provider.storage.sessionRepositories.upsert({
+					sessionId: target.session.sessionId,
+					projectRepositoryId: target.projectRepository.id,
+					fallbackBranch: target.session.branch,
+					changeRequestId: changeRequestId(created.id),
+					changeRequestUrl: created.url
+				});
+				updateSessionEnvironmentRepository(target.session.sessionId, target.repository.slug, { changeRequestUrl: created.url });
 				await emitAgentAudit(audit, requestContext, {
 					action: "factory.agent.pr_opened",
 					targets: [{
@@ -222,7 +294,8 @@ function createSourceControlTools({ requestContext, providers, audit }) {
 					}],
 					metadata: {
 						url: created.url,
-						provider: target.provider.id
+						provider: target.provider.id,
+						repository: target.repository.slug
 					}
 				});
 				return created;
@@ -230,7 +303,7 @@ function createSourceControlTools({ requestContext, providers, audit }) {
 		}),
 		source_control_update_change_request: createTool({
 			id: "source_control_update_change_request",
-			description: "Update the title, body, target branch, or open/closed state of a change request.",
+			description: `Update the title, body, target branch, or open/closed state of a change request. ${repositoryArgument}`,
 			inputSchema: changeRequestSchema.extend({
 				title: z.string().trim().min(1).optional(),
 				body: z.string().nullable().optional(),
@@ -238,7 +311,7 @@ function createSourceControlTools({ requestContext, providers, audit }) {
 				state: z.enum(["open", "closed"]).optional()
 			}),
 			execute: async (input) => {
-				const target = await withTarget();
+				const target = await targetFor(input);
 				return target.provider.versionControl.updatePullRequest({
 					...await reference(target),
 					pullRequestId: changeRequestId(input.changeRequestId),
@@ -251,10 +324,10 @@ function createSourceControlTools({ requestContext, providers, audit }) {
 		}),
 		source_control_comment_change_request: createTool({
 			id: "source_control_comment_change_request",
-			description: "Add a top-level comment to a pull request or merge request in the active repository.",
+			description: `Add a top-level comment to a pull request or merge request in the active repository. ${repositoryArgument}`,
 			inputSchema: changeRequestSchema.extend({ body: z.string().trim().min(1) }),
 			execute: async (input) => {
-				const target = await withTarget();
+				const target = await targetFor(input);
 				return target.provider.versionControl.createComment({
 					...await reference(target),
 					pullRequestId: changeRequestId(input.changeRequestId),
@@ -264,10 +337,10 @@ function createSourceControlTools({ requestContext, providers, audit }) {
 		}),
 		source_control_list_change_request_comments: createTool({
 			id: "source_control_list_change_request_comments",
-			description: "List top-level comments on a pull request or merge request in the active repository.",
+			description: `List top-level comments on a pull request or merge request in the active repository. ${repositoryArgument}`,
 			inputSchema: changeRequestSchema.extend({ cursor: z.string().trim().min(1).optional() }),
 			execute: async (input) => {
-				const target = await withTarget();
+				const target = await targetFor(input);
 				return target.provider.versionControl.listComments({
 					...await reference(target),
 					pullRequestId: changeRequestId(input.changeRequestId),
@@ -277,13 +350,13 @@ function createSourceControlTools({ requestContext, providers, audit }) {
 		}),
 		source_control_update_change_request_comment: createTool({
 			id: "source_control_update_change_request_comment",
-			description: "Edit a top-level pull-request or merge-request comment in the active repository.",
-			inputSchema: z.object({
+			description: `Edit a top-level pull-request or merge-request comment in the active repository. ${repositoryArgument}`,
+			inputSchema: repositorySchema.extend({
 				commentId: z.string().trim().min(1),
 				body: z.string().trim().min(1)
 			}),
 			execute: async (input) => {
-				const target = await withTarget();
+				const target = await targetFor(input);
 				return target.provider.versionControl.updateComment({
 					...await reference(target),
 					commentId: input.commentId,
@@ -293,10 +366,10 @@ function createSourceControlTools({ requestContext, providers, audit }) {
 		}),
 		source_control_delete_change_request_comment: createTool({
 			id: "source_control_delete_change_request_comment",
-			description: "Delete a top-level pull-request or merge-request comment in the active repository.",
-			inputSchema: z.object({ commentId: z.string().trim().min(1) }),
+			description: `Delete a top-level pull-request or merge-request comment in the active repository. ${repositoryArgument}`,
+			inputSchema: repositorySchema.extend({ commentId: z.string().trim().min(1) }),
 			execute: async (input) => {
-				const target = await withTarget();
+				const target = await targetFor(input);
 				await target.provider.versionControl.deleteComment({
 					...await reference(target),
 					commentId: input.commentId
@@ -306,10 +379,10 @@ function createSourceControlTools({ requestContext, providers, audit }) {
 		}),
 		source_control_list_diff_comments: createTool({
 			id: "source_control_list_diff_comments",
-			description: "List line-anchored review comments and discussion replies on a pull request or merge request in the active repository.",
+			description: `List line-anchored review comments and discussion replies on a pull request or merge request in the active repository. ${repositoryArgument}`,
 			inputSchema: changeRequestSchema.extend({ cursor: z.string().trim().min(1).optional() }),
 			execute: async (input) => {
-				const target = await withTarget();
+				const target = await targetFor(input);
 				return target.provider.versionControl.listReviewComments({
 					...await reference(target),
 					pullRequestId: changeRequestId(input.changeRequestId),
@@ -319,7 +392,7 @@ function createSourceControlTools({ requestContext, providers, audit }) {
 		}),
 		source_control_create_diff_comment: createTool({
 			id: "source_control_create_diff_comment",
-			description: "Create a line-anchored review comment or reply to an existing diff discussion. Use replyToId alone for a reply; otherwise provide commitId, path, line, and side.",
+			description: `Create a line-anchored review comment or reply to an existing diff discussion. Use replyToId alone for a reply; otherwise provide commitId, path, line, and side. ${repositoryArgument}`,
 			inputSchema: changeRequestSchema.extend({
 				body: z.string().trim().min(1),
 				replyToId: z.string().trim().min(1).optional(),
@@ -340,7 +413,7 @@ function createSourceControlTools({ requestContext, providers, audit }) {
 				return (input.replyToId !== void 0 ? anchorFields.every((field) => field === void 0) : anchor) && input.startLine === void 0 === (input.startSide === void 0);
 			}, { message: "Provide replyToId alone to reply to a diff thread, or commitId, path, line, and side to start one. startLine and startSide must be provided together." }),
 			execute: async (input) => {
-				const target = await withTarget();
+				const target = await targetFor(input);
 				const base = {
 					...await reference(target),
 					pullRequestId: changeRequestId(input.changeRequestId),
@@ -366,13 +439,13 @@ function createSourceControlTools({ requestContext, providers, audit }) {
 		}),
 		source_control_update_diff_comment: createTool({
 			id: "source_control_update_diff_comment",
-			description: "Edit a line-anchored review comment or discussion reply in the active repository.",
-			inputSchema: z.object({
+			description: `Edit a line-anchored review comment or discussion reply in the active repository. ${repositoryArgument}`,
+			inputSchema: repositorySchema.extend({
 				commentId: z.string().trim().min(1),
 				body: z.string().trim().min(1)
 			}),
 			execute: async (input) => {
-				const target = await withTarget();
+				const target = await targetFor(input);
 				return target.provider.versionControl.updateReviewComment({
 					...await reference(target),
 					commentId: input.commentId,
@@ -382,10 +455,10 @@ function createSourceControlTools({ requestContext, providers, audit }) {
 		}),
 		source_control_delete_diff_comment: createTool({
 			id: "source_control_delete_diff_comment",
-			description: "Delete a line-anchored review comment or discussion reply in the active repository.",
-			inputSchema: z.object({ commentId: z.string().trim().min(1) }),
+			description: `Delete a line-anchored review comment or discussion reply in the active repository. ${repositoryArgument}`,
+			inputSchema: repositorySchema.extend({ commentId: z.string().trim().min(1) }),
 			execute: async (input) => {
-				const target = await withTarget();
+				const target = await targetFor(input);
 				await target.provider.versionControl.deleteReviewComment({
 					...await reference(target),
 					commentId: input.commentId
@@ -395,13 +468,13 @@ function createSourceControlTools({ requestContext, providers, audit }) {
 		}),
 		source_control_resolve_diff_thread: createTool({
 			id: "source_control_resolve_diff_thread",
-			description: "Resolve or reopen the review thread containing a diff comment. Providers without resolvable threads return an explicit limitation.",
-			inputSchema: z.object({
+			description: `Resolve or reopen the review thread containing a diff comment. Providers without resolvable threads return an explicit limitation. ${repositoryArgument}`,
+			inputSchema: repositorySchema.extend({
 				commentId: z.string().trim().min(1),
 				resolved: z.boolean().default(true)
 			}),
 			execute: async (input) => {
-				const target = await withTarget();
+				const target = await targetFor(input);
 				const resolveReviewThread = target.provider.versionControl.resolveReviewThread;
 				if (!resolveReviewThread) throw new Error(`${target.provider.id} does not support resolving review threads.`);
 				await resolveReviewThread({
@@ -414,7 +487,7 @@ function createSourceControlTools({ requestContext, providers, audit }) {
 		}),
 		source_control_review_change_request: createTool({
 			id: "source_control_review_change_request",
-			description: "Submit an approve, request-changes, or comment review to a change request. Provider limitations are returned explicitly.",
+			description: `Submit an approve, request-changes, or comment review to a change request. Provider limitations are returned explicitly. ${repositoryArgument}`,
 			inputSchema: changeRequestSchema.extend({
 				event: z.enum([
 					"approve",
@@ -446,7 +519,7 @@ function createSourceControlTools({ requestContext, providers, audit }) {
 				});
 			}),
 			execute: async (input) => {
-				const target = await withTarget();
+				const target = await targetFor(input);
 				const reviewedHead = reviewedHeadFromBody(input.body);
 				if (reviewedHead) {
 					const pullRequest = await target.provider.versionControl.getPullRequest({
@@ -475,13 +548,13 @@ function createSourceControlTools({ requestContext, providers, audit }) {
 		}),
 		source_control_request_reviewers: createTool({
 			id: "source_control_request_reviewers",
-			description: "Request individual or team reviewers on a pull request or merge request. Provider limitations are returned explicitly.",
+			description: `Request individual or team reviewers on a pull request or merge request. Provider limitations are returned explicitly. ${repositoryArgument}`,
 			inputSchema: changeRequestSchema.extend({
 				users: z.array(z.string().trim().min(1)).default([]),
 				teams: z.array(z.string().trim().min(1)).default([])
 			}),
 			execute: async (input) => {
-				const target = await withTarget();
+				const target = await targetFor(input);
 				return target.provider.versionControl.requestReviewers({
 					...await reference(target),
 					pullRequestId: changeRequestId(input.changeRequestId),
@@ -492,7 +565,7 @@ function createSourceControlTools({ requestContext, providers, audit }) {
 		}),
 		source_control_merge_change_request: createTool({
 			id: "source_control_merge_change_request",
-			description: "Merge a pull request or merge request using the requested provider-supported merge method.",
+			description: `Merge a pull request or merge request using the requested provider-supported merge method. ${repositoryArgument}`,
 			inputSchema: changeRequestSchema.extend({
 				method: z.enum([
 					"merge",
@@ -503,7 +576,7 @@ function createSourceControlTools({ requestContext, providers, audit }) {
 				commitMessage: z.string().optional()
 			}),
 			execute: async (input) => {
-				const target = await withTarget();
+				const target = await targetFor(input);
 				return target.provider.versionControl.mergePullRequest({
 					...await reference(target),
 					pullRequestId: changeRequestId(input.changeRequestId),