@mastra/factory 0.0.0-aggregate-trace-20261015182851

package/dist/integrations/github/integration.js

@@ -0,0 +1,1375 @@
+import { attachGithubReconciler, attachGithubRules } from "./rules.js";
+import { createGithubSubscriptionTools, parseCreatedPullRequest, subscribeCurrentSessionToPullRequest } from "./session-subscriptions.js";
+import { resolveGithubRules } from "./default-rules.js";
+import { attachGithubIssueReconciler } from "./issue-reconciler.js";
+import { reconcileInterval, reconciliationEnabled } from "./reconciliation-config.js";
+import { buildGithubRoutes, ingestLinkedRepositoryBacklog } from "./routes.js";
+import { settleOrAbort } from "./settle-or-abort.js";
+import { GithubReconcileWorker } from "./reconcile-worker.js";
+import { Octokit } from "@octokit/rest";
+import { createAppAuth } from "@octokit/auth-app";
+//#region src/integrations/github/integration.ts
+/**
+* Normalize a PEM private key supplied via env. Env tooling tends to mangle
+* multi-line PEMs, so two single-line forms are supported:
+*   - `\n`-escaped: literal `\n` sequences become real newlines
+*   - fully flattened: newlines stripped entirely — the PEM is rebuilt by
+*     re-wrapping the base64 body (Node's decoder rejects header/body/footer
+*     on one line with `error:1E08010C:DECODER routines::unsupported`)
+*/
+function normalizePrivateKey(raw) {
+	const key = raw.replace(/\\n/g, "\n");
+	if (key.includes("\n")) return key;
+	const flattened = key.trim().match(/^(-----BEGIN [A-Z0-9 ]+-----)\s*(.+?)\s*(-----END [A-Z0-9 ]+-----)$/);
+	if (!flattened) return key;
+	const body = flattened[2].replace(/\s+/g, "");
+	return `${flattened[1]}\n${body.match(/.{1,64}/g).join("\n")}\n${flattened[3]}\n`;
+}
+/**
+* How long a collaborator permission lookup may be reused. The reconcile
+* sweep re-stamps every open card's author and webhook gating checks every
+* human sender, so one login can cost dozens of identical requests per cycle
+* against the installation's REST budget. Revoked access reads as trusted for
+* at most this long.
+*/
+const COLLABORATOR_PERMISSION_CACHE_TTL_MS = 30 * 6e4;
+const COLLABORATOR_PERMISSION_CACHE_MAX_ENTRIES = 1e3;
+/** Bound on the shared upstream lookup; callers race their own signal against it. */
+const COLLABORATOR_PERMISSION_LOOKUP_TIMEOUT_MS = 1e4;
+/** Installations whose Octokit (and cached token) is kept; least recently used is evicted. */
+const INSTALLATION_OCTOKIT_CACHE_MAX_ENTRIES = 1e3;
+/** Missed-open issue discovery reads at most this many pages per repository per sweep. */
+const OPEN_ISSUE_DISCOVERY_MAX_PAGES = 5;
+const OPEN_ISSUE_DISCOVERY_PAGE_SIZE = 100;
+/** Page size for issue/PR listings; one GitHub API call per page. */
+const LIST_PAGE_SIZE = 30;
+/** Allow GitHub OAuth token exchanges enough time to complete during installation callbacks. */
+const GITHUB_OAUTH_TOKEN_TIMEOUT_MS = 1e4;
+/** Human-readable names of the required config fields, for construction errors. */
+const REQUIRED_FIELDS = [
+	"appId",
+	"privateKey",
+	"clientId",
+	"clientSecret",
+	"slug"
+];
+var GithubIntegration = class {
+	/** Stable integration identifier (see `../factory-integration.ts`). */
+	id = "github";
+	#rules;
+	get rules() {
+		return this.#rules;
+	}
+	intake = {
+		resolveIntakeDispatch: (input) => this.#resolveIntakeDispatch(input),
+		listSources: async ({ orgId }) => {
+			const installations = await this.sourceControlStorage.installations.list({ orgId });
+			return (await Promise.all(installations.map((installation) => this.sourceControlStorage.repositories.list({
+				orgId,
+				installationId: installation.id
+			})))).flat().map((repository) => ({
+				id: repository.id,
+				name: repository.slug,
+				type: "repository",
+				metadata: { defaultBranch: repository.defaultBranch }
+			}));
+		},
+		listItems: async ({ orgId, sourceIds, cursor }) => {
+			const page = cursor ? Number.parseInt(cursor, 10) : 1;
+			const requestedPage = Number.isSafeInteger(page) && page > 0 ? page : 1;
+			const pages = await Promise.all(sourceIds.map(async (sourceId) => {
+				const repository = await this.sourceControlStorage.repositories.get({
+					orgId,
+					id: sourceId
+				});
+				if (!repository) return {
+					items: [],
+					hasNextPage: false
+				};
+				const installation = await this.sourceControlStorage.installations.get({
+					orgId,
+					id: repository.installationId
+				});
+				if (!installation) return {
+					items: [],
+					hasNextPage: false
+				};
+				const installationId = Number.parseInt(installation.externalId, 10);
+				if (!Number.isSafeInteger(installationId)) return {
+					items: [],
+					hasNextPage: false
+				};
+				const [issues, pullRequests] = await Promise.all([this.listRepoOpenIssues(installationId, repository.slug, requestedPage), this.versionControl.listPullRequests({
+					connection: {
+						type: "app-installation",
+						installationId
+					},
+					sourceId: repository.slug,
+					includeDrafts: false,
+					cursor: String(requestedPage)
+				})]);
+				return {
+					items: [...issues.issues.map((issue) => ({
+						source: {
+							type: "issue",
+							externalId: `${repository.externalId}:${issue.number}`,
+							url: issue.url
+						},
+						sourceId: repository.id,
+						title: issue.title,
+						status: "open",
+						labels: issue.labels,
+						createdAt: issue.createdAt,
+						updatedAt: issue.updatedAt,
+						metadata: {
+							repository: repository.slug,
+							number: issue.number,
+							author: issue.author
+						}
+					})), ...pullRequests.pullRequests.map((pullRequest) => ({
+						source: {
+							type: "pull-request",
+							externalId: `${repository.externalId}:${pullRequest.id}`,
+							url: pullRequest.url
+						},
+						sourceId: repository.id,
+						title: pullRequest.title,
+						status: "open",
+						createdAt: pullRequest.createdAt,
+						updatedAt: pullRequest.updatedAt,
+						metadata: {
+							repository: repository.slug,
+							number: Number(pullRequest.id),
+							author: pullRequest.author,
+							baseBranch: pullRequest.baseBranch,
+							headBranch: pullRequest.headBranch
+						}
+					}))],
+					hasNextPage: issues.nextPage !== null || pullRequests.nextCursor !== null
+				};
+			}));
+			return {
+				items: pages.flatMap((result) => result.items),
+				nextCursor: pages.some((result) => result.hasNextPage) ? String(requestedPage + 1) : null
+			};
+		},
+		listIssues: (input) => this.#listIntakeIssues(input),
+		getIssue: (input) => this.#getIntakeIssue(input),
+		createComment: (input) => this.#createIntakeComment(input),
+		updateIssue: (input) => this.#updateIntakeIssue(input)
+	};
+	versionControl = {
+		initialize: ({ storage }) => {
+			this.#sourceControlStorage = storage;
+		},
+		registerInstallation: ({ orgId, userId, installation }) => this.sourceControlStorage.installations.upsert({
+			orgId,
+			connectedByUserId: userId,
+			externalId: installation.externalId,
+			accountName: installation.accountName,
+			accountType: installation.accountType,
+			providerMetadata: installation.metadata
+		}),
+		registerRepositories: ({ orgId, installationId, repositories }) => Promise.all(repositories.map((repository) => this.sourceControlStorage.repositories.upsert({
+			orgId,
+			input: {
+				installationId,
+				externalId: repository.externalId,
+				slug: repository.slug,
+				defaultBranch: repository.defaultBranch,
+				providerMetadata: repository.metadata
+			}
+		}))),
+		getRepositoryTarget: async ({ orgId, repositoryId }) => {
+			const repository = await this.sourceControlStorage.repositories.get({
+				orgId,
+				id: repositoryId
+			});
+			if (!repository) throw new Error("Version-control repository not found.");
+			const installation = await this.sourceControlStorage.installations.get({
+				orgId,
+				id: repository.installationId
+			});
+			if (!installation) throw new Error("Version-control installation not found.");
+			const installationId = Number.parseInt(installation.externalId, 10);
+			if (!Number.isSafeInteger(installationId)) throw new Error("GitHub installation id is invalid.");
+			return {
+				connection: {
+					type: "app-installation",
+					installationId
+				},
+				sourceId: repository.slug
+			};
+		},
+		getRepositoryAccess: async ({ orgId, repositoryId }) => {
+			const repository = await this.sourceControlStorage.repositories.get({
+				orgId,
+				id: repositoryId
+			});
+			if (!repository) throw new Error("Version-control repository not found.");
+			const installation = await this.sourceControlStorage.installations.get({
+				orgId,
+				id: repository.installationId
+			});
+			if (!installation) throw new Error("Version-control installation not found.");
+			const installationId = Number.parseInt(installation.externalId, 10);
+			if (!Number.isSafeInteger(installationId)) throw new Error("GitHub installation id is invalid.");
+			return {
+				cloneUrl: `https://github.com/${repository.slug}.git`,
+				authorization: {
+					scheme: "bearer",
+					token: await this.mintInstallationToken(installationId)
+				}
+			};
+		},
+		listPullRequests: (input) => this.#listPullRequests(input),
+		getPullRequest: (input) => this.#getPullRequest(input),
+		createPullRequest: (input) => this.#createPullRequest(input),
+		updatePullRequest: (input) => this.#updatePullRequest(input),
+		closePullRequest: (input) => this.#closePullRequest(input),
+		mergePullRequest: (input) => this.#mergePullRequest(input),
+		listComments: (input) => this.#listComments(input),
+		createComment: (input) => this.#createComment(input),
+		updateComment: (input) => this.#updateComment(input),
+		deleteComment: (input) => this.#deleteComment(input),
+		listReviews: (input) => this.#listReviews(input),
+		getReview: (input) => this.#getReview(input),
+		createReview: (input) => this.#createReview(input),
+		updateReview: (input) => this.#updateReview(input),
+		submitReview: (input) => this.#submitReview(input),
+		dismissReview: (input) => this.#dismissReview(input),
+		deletePendingReview: (input) => this.#deletePendingReview(input),
+		listReviewComments: (input) => this.#listReviewComments(input),
+		createReviewComment: (input) => this.#createReviewComment(input),
+		updateReviewComment: (input) => this.#updateReviewComment(input),
+		deleteReviewComment: (input) => this.#deleteReviewComment(input),
+		listRequestedReviewers: (input) => this.#listRequestedReviewers(input),
+		requestReviewers: (input) => this.#requestReviewers(input),
+		removeRequestedReviewers: (input) => this.#removeReviewers(input)
+	};
+	/**
+	* The OAuth/install flow round-trips a signed `state` through GitHub, so a
+	* multi-replica deploy needs a deployment-stable state secret.
+	*/
+	requiresStableStateSigner = true;
+	#appId;
+	#privateKey;
+	#clientId;
+	#clientSecret;
+	#slug;
+	#webhookSecret;
+	#authorizedBots;
+	#storage;
+	#ingestFactoryEvent;
+	#sourceControlStorage;
+	/** `installationId:owner/repo:login` → cached collaborator permission (TTL-bounded). */
+	#collaboratorPermissionCache = /* @__PURE__ */ new Map();
+	/** Same key → lookup already in flight, so overlapping callers share one request. */
+	#collaboratorPermissionInFlight = /* @__PURE__ */ new Map();
+	/**
+	* One Octokit per installation, so its auth instance keeps the installation
+	* token cached (auth-app refreshes it before expiry) instead of minting a new
+	* token on every call.
+	*/
+	#installationOctokits = /* @__PURE__ */ new Map();
+	constructor(config) {
+		this.#rules = resolveGithubRules(config.rules);
+		const missing = REQUIRED_FIELDS.filter((field) => !config[field]);
+		if (missing.length > 0) throw new Error(`GithubIntegration: missing required config field(s): ${missing.join(", ")}. Provide the full GitHub App credentials (appId, privateKey, clientId, clientSecret, slug) or omit the integration to disable GitHub-backed repositories.`);
+		this.#appId = config.appId;
+		this.#privateKey = normalizePrivateKey(config.privateKey);
+		this.#clientId = config.clientId;
+		this.#clientSecret = config.clientSecret;
+		this.#slug = config.slug;
+		this.#webhookSecret = config.webhookSecret || void 0;
+		this.#authorizedBots = (config.authorizedBots ?? []).map((bot) => bot.trim()).filter(Boolean);
+	}
+	/** App slug — the URL name used to build the install URL. */
+	get slug() {
+		return this.#slug;
+	}
+	/** Whether a GitHub login belongs to this integration's App. */
+	isFactoryCommentAuthor(login) {
+		return typeof login === "string" && login.toLowerCase() === `${this.#slug}[bot]`.toLowerCase();
+	}
+	/** Extra bot logins authorized to trigger author-gated PR notifications. */
+	get authorizedBots() {
+		return this.#authorizedBots;
+	}
+	get genericStorage() {
+		if (!this.#storage) throw new Error("GithubIntegration storage has not been initialized.");
+		return this.#storage.generic;
+	}
+	get sourceControlStorage() {
+		const storage = this.#sourceControlStorage ?? this.#storage?.sourceControl;
+		if (!storage) throw new Error("GithubIntegration source-control storage has not been initialized.");
+		return storage;
+	}
+	get integrationStorage() {
+		if (!this.#storage) throw new Error("GithubIntegration storage has not been initialized.");
+		return this.#storage.generic;
+	}
+	/** Resolve a stored GitHub locator without scanning installations or repositories. */
+	async #resolveIntakeDispatch({ orgId, externalSource }) {
+		const target = parseGithubExternalTarget(externalSource.externalId);
+		if (!target) return null;
+		const repository = await this.sourceControlStorage.repositories.findByExternalId({
+			orgId,
+			externalId: target.repositoryId
+		});
+		if (!repository) return null;
+		const installation = await this.sourceControlStorage.installations.get({
+			orgId,
+			id: repository.installationId
+		});
+		if (!installation) return null;
+		const installationId = Number.parseInt(installation.externalId, 10);
+		if (!Number.isSafeInteger(installationId)) return null;
+		return {
+			connection: {
+				type: "app-installation",
+				installationId
+			},
+			sourceId: repository.slug,
+			issueId: target.issueId
+		};
+	}
+	/** Secret GitHub uses to sign webhook deliveries, when configured. */
+	get webhookSecret() {
+		return this.#webhookSecret;
+	}
+	#appAuth() {
+		return {
+			appId: this.#appId,
+			privateKey: this.#privateKey,
+			clientId: this.#clientId,
+			clientSecret: this.#clientSecret
+		};
+	}
+	/**
+	* Octokit authenticated as the GitHub App itself (app JWT). Used for
+	* app-level operations and to mint installation tokens.
+	*/
+	getAppOctokit() {
+		return new Octokit({
+			authStrategy: createAppAuth,
+			auth: this.#appAuth()
+		});
+	}
+	/**
+	* Octokit authenticated as a specific installation (installation access
+	* token). Used to list repos and to operate on a repo on the user's behalf.
+	*/
+	getInstallationOctokit(installationId) {
+		let octokit = this.#installationOctokits.get(installationId);
+		if (octokit) this.#installationOctokits.delete(installationId);
+		else {
+			const created = new Octokit({
+				authStrategy: createAppAuth,
+				auth: {
+					...this.#appAuth(),
+					installationId
+				}
+			});
+			created.hook.error("request", (error) => {
+				if ("status" in error && error.status === 401 && this.#installationOctokits.get(installationId) === created) this.#installationOctokits.delete(installationId);
+				throw error;
+			});
+			octokit = created;
+			if (this.#installationOctokits.size >= INSTALLATION_OCTOKIT_CACHE_MAX_ENTRIES) {
+				const oldest = this.#installationOctokits.keys().next().value;
+				if (oldest !== void 0) this.#installationOctokits.delete(oldest);
+			}
+		}
+		this.#installationOctokits.set(installationId, octokit);
+		return octokit;
+	}
+	/** Octokit authenticated as a user via their OAuth token (the identify step). */
+	getUserOctokit(userToken) {
+		return new Octokit({ auth: userToken });
+	}
+	/**
+	* Mint a short-lived installation access token. Returned token is used only
+	* server-side / inside the sandbox clone URL and never sent to the browser.
+	*/
+	async mintInstallationToken(installationId) {
+		return (await createAppAuth(this.#appAuth())({
+			type: "installation",
+			installationId
+		})).token;
+	}
+	/**
+	* List the installations the authenticated user can access, via their OAuth
+	* token (`GET /user/installations`).
+	*/
+	async listUserInstallations(userToken) {
+		const octokit = this.getUserOctokit(userToken);
+		return (await octokit.paginate(octokit.apps.listInstallationsForAuthenticatedUser, { per_page: 100 })).map((inst) => ({
+			installationId: inst.id,
+			accountLogin: inst.account && "login" in inst.account ? inst.account.login : null,
+			accountType: inst.account && "type" in inst.account ? inst.account.type : null
+		}));
+	}
+	/**
+	* List repos accessible to an installation (paginated). Always reads
+	* GitHub directly, so `fresh` has nothing to bypass here.
+	*/
+	async listInstallationRepos(installationId, _options) {
+		const octokit = this.getInstallationOctokit(installationId);
+		return (await octokit.paginate(octokit.apps.listReposAccessibleToInstallation, { per_page: 100 })).map((repo) => ({
+			id: repo.id,
+			fullName: repo.full_name,
+			name: repo.name,
+			owner: repo.owner.login,
+			defaultBranch: repo.default_branch,
+			private: repo.private,
+			installationId
+		}));
+	}
+	/**
+	* The authenticated user's permission level on a repo, through the
+	* installation. `undefined` when the repo/user is not accessible.
+	*/
+	async getRepositoryCollaboratorPermission(installationId, repoFullName, username, signal) {
+		const parts = splitRepoFullName(repoFullName);
+		if (!parts) return void 0;
+		const cacheKey = `${installationId}:${parts.owner}/${parts.repo}:${username.toLowerCase()}`;
+		const cached = this.#collaboratorPermissionCache.get(cacheKey);
+		if (cached && cached.expiresAt > Date.now()) return cached.permission;
+		this.#collaboratorPermissionCache.delete(cacheKey);
+		const inFlight = this.#collaboratorPermissionInFlight.get(cacheKey);
+		if (inFlight) return settleOrAbort(inFlight, signal, void 0);
+		const lookup = (async () => {
+			try {
+				const { data } = await this.getInstallationOctokit(installationId).repos.getCollaboratorPermissionLevel({
+					...parts,
+					username,
+					request: { signal: AbortSignal.timeout(COLLABORATOR_PERMISSION_LOOKUP_TIMEOUT_MS) }
+				});
+				const permission = data.permission;
+				this.#collaboratorPermissionCache.set(cacheKey, {
+					permission,
+					expiresAt: Date.now() + COLLABORATOR_PERMISSION_CACHE_TTL_MS
+				});
+				if (this.#collaboratorPermissionCache.size > COLLABORATOR_PERMISSION_CACHE_MAX_ENTRIES) {
+					const oldest = this.#collaboratorPermissionCache.keys().next().value;
+					if (oldest !== void 0) this.#collaboratorPermissionCache.delete(oldest);
+				}
+				return permission;
+			} catch {
+				return;
+			} finally {
+				this.#collaboratorPermissionInFlight.delete(cacheKey);
+			}
+		})();
+		this.#collaboratorPermissionInFlight.set(cacheKey, lookup);
+		return settleOrAbort(lookup, signal, void 0);
+	}
+	/**
+	* Fetch a single repo's metadata through an installation token and confirm
+	* the installation actually has access to it. Returns `null` when the repo
+	* is not accessible to the installation (so a client can't create a project
+	* for an arbitrary repo under an installation id it merely owns).
+	*/
+	async getInstallationRepo(installationId, repoFullName) {
+		const parts = splitRepoFullName(repoFullName);
+		if (!parts) return null;
+		const octokit = this.getInstallationOctokit(installationId);
+		try {
+			const { data } = await octokit.repos.get(parts);
+			return {
+				id: data.id,
+				fullName: data.full_name,
+				name: data.name,
+				owner: data.owner.login,
+				defaultBranch: data.default_branch,
+				private: data.private,
+				installationId
+			};
+		} catch {
+			return null;
+		}
+	}
+	async #listIntakeIssues(input) {
+		const installationId = getGithubInstallationId(input.connection);
+		const repoFullName = getSingleSourceId(input.sourceIds, "GitHub Intake requires exactly one repository source.");
+		const page = parsePositiveCursor(input.cursor);
+		const labels = normalizeLabels(input.labels);
+		const result = await this.listRepoOpenIssues(installationId, repoFullName, page, { label: labels.length > 0 ? labels.join(",") : void 0 });
+		return {
+			issues: result.issues.map((issue) => ({
+				id: String(issue.number),
+				identifier: `#${issue.number}`,
+				title: issue.title,
+				url: issue.url,
+				author: issue.author,
+				state: "open",
+				stateType: "open",
+				priority: null,
+				assignee: issue.assignees[0] ?? null,
+				assignees: issue.assignees,
+				source: repoFullName,
+				labels: issue.labels,
+				commentCount: issue.comments,
+				createdAt: issue.createdAt,
+				updatedAt: issue.updatedAt
+			})),
+			nextCursor: result.nextPage === null ? null : String(result.nextPage)
+		};
+	}
+	async #getIntakeIssue(input) {
+		const installationId = getGithubInstallationId(input.connection);
+		const repoFullName = requireSourceId(input.sourceId, "GitHub Intake requires a repository source.");
+		const parts = splitRepoFullName(repoFullName);
+		const issueNumber = parsePositiveInteger(input.issueId);
+		if (!parts || issueNumber === null) return null;
+		const octokit = this.getInstallationOctokit(installationId);
+		try {
+			const [{ data: issue }, comments] = await Promise.all([octokit.issues.get({
+				owner: parts.owner,
+				repo: parts.repo,
+				issue_number: issueNumber
+			}), octokit.paginate(octokit.issues.listComments, {
+				owner: parts.owner,
+				repo: parts.repo,
+				issue_number: issueNumber,
+				per_page: 100
+			})]);
+			if (issue.pull_request) return null;
+			return {
+				id: String(issue.number),
+				identifier: `#${issue.number}`,
+				title: issue.title,
+				url: issue.html_url,
+				author: issue.user?.login ?? null,
+				state: issue.state,
+				stateType: issue.state,
+				priority: null,
+				assignee: issue.assignee?.login ?? null,
+				assignees: (issue.assignees ?? []).map((user) => user.login).filter((login) => Boolean(login)),
+				source: repoFullName,
+				labels: issue.labels.map((label) => typeof label === "string" ? label : label.name ?? "").filter(Boolean),
+				commentCount: issue.comments,
+				createdAt: issue.created_at,
+				updatedAt: issue.updated_at,
+				description: issue.body?.trim() ? issue.body : null,
+				comments: comments.map((comment) => ({
+					author: comment.user?.login ?? null,
+					body: comment.body ?? "",
+					createdAt: comment.created_at
+				}))
+			};
+		} catch (err) {
+			if (isNotFoundError(err)) return null;
+			throw err;
+		}
+	}
+	async #updateIntakeIssue(input) {
+		const installationId = getGithubInstallationId(input.connection);
+		const repoFullName = requireSourceId(input.sourceId, "GitHub Intake requires a repository source.");
+		const parts = splitRepoFullName(repoFullName);
+		const issueNumber = parsePositiveInteger(input.issueId);
+		if (!parts || issueNumber === null) return null;
+		if (input.state.kind === "byName") {
+			console.warn(`GitHub integration: updateIssue byName is not supported (name=${input.state.name}); ignoring.`);
+			return null;
+		}
+		const targetState = input.state.stateType === "unstarted" || input.state.stateType === "started" ? "open" : "closed";
+		const stateReason = targetState === "closed" ? input.state.stateType === "canceled" ? "not_planned" : "completed" : null;
+		const octokit = this.getInstallationOctokit(installationId);
+		try {
+			const { data: current } = await octokit.issues.get({
+				owner: parts.owner,
+				repo: parts.repo,
+				issue_number: issueNumber
+			});
+			if (current.pull_request) {
+				console.warn(`GitHub integration: updateIssue rejected — target ${repoFullName}#${issueNumber} is a pull request.`);
+				return null;
+			}
+			const { data: issue } = await octokit.issues.update({
+				owner: parts.owner,
+				repo: parts.repo,
+				issue_number: issueNumber,
+				state: targetState,
+				...stateReason ? { state_reason: stateReason } : {}
+			});
+			return {
+				id: String(issue.number),
+				identifier: `#${issue.number}`,
+				title: issue.title,
+				url: issue.html_url,
+				author: issue.user?.login ?? null,
+				state: issue.state,
+				stateType: issue.state,
+				priority: null,
+				assignee: issue.assignee?.login ?? null,
+				assignees: (issue.assignees ?? []).map((user) => user.login).filter((login) => Boolean(login)),
+				source: repoFullName,
+				labels: issue.labels.map((label) => typeof label === "string" ? label : label.name ?? "").filter(Boolean),
+				commentCount: issue.comments,
+				createdAt: issue.created_at,
+				updatedAt: issue.updated_at
+			};
+		} catch (err) {
+			if (isNotFoundError(err)) return null;
+			throw err;
+		}
+	}
+	async #createIntakeComment(input) {
+		const installationId = getGithubInstallationId(input.connection);
+		const parts = splitRepoFullName(requireSourceId(input.sourceId, "GitHub Intake requires a repository source."));
+		const issueNumber = parsePositiveInteger(input.issueId);
+		if (!parts || issueNumber === null) return null;
+		const octokit = this.getInstallationOctokit(installationId);
+		try {
+			const { data } = await octokit.issues.createComment({
+				owner: parts.owner,
+				repo: parts.repo,
+				issue_number: issueNumber,
+				body: input.body
+			});
+			return {
+				id: String(data.id),
+				url: data.html_url
+			};
+		} catch (err) {
+			if (isNotFoundError(err)) return null;
+			throw err;
+		}
+	}
+	#repositoryClient(connection, sourceId) {
+		const installationId = getGithubInstallationId(connection);
+		const parts = splitRepoFullName(sourceId);
+		if (!parts) throw new Error("GitHub pull requests require an owner/repository source.");
+		return {
+			octokit: this.getInstallationOctokit(installationId),
+			parts
+		};
+	}
+	async #listPullRequests(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		const page = parsePositiveCursor(input.cursor);
+		const response = await octokit.pulls.list({
+			...parts,
+			state: input.state ?? "open",
+			per_page: 30,
+			page
+		});
+		return {
+			pullRequests: response.data.filter((pr) => input.includeDrafts !== false || !pr.draft).map((pr) => parsePullRequest(pr)),
+			nextCursor: response.data.length === 30 ? String(page + 1) : null
+		};
+	}
+	async #getPullRequest(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		const pullNumber = requirePullRequestNumber(input.pullRequestId);
+		try {
+			const { data } = await octokit.pulls.get({
+				...parts,
+				pull_number: pullNumber
+			});
+			return parsePullRequest(data);
+		} catch (err) {
+			if (isNotFoundError(err)) return null;
+			throw err;
+		}
+	}
+	async #createPullRequest(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		const { data } = await octokit.pulls.create({
+			...parts,
+			title: input.title,
+			body: input.body,
+			base: input.baseBranch,
+			head: input.headBranch,
+			draft: input.draft
+		});
+		return parsePullRequest(data);
+	}
+	async #updatePullRequest(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		const { data } = await octokit.pulls.update({
+			...parts,
+			pull_number: requirePullRequestNumber(input.pullRequestId),
+			title: input.title,
+			body: input.body === null ? "" : input.body,
+			base: input.baseBranch,
+			state: input.state
+		});
+		return parsePullRequest(data);
+	}
+	async #closePullRequest(input) {
+		return this.#updatePullRequest({
+			...input,
+			state: "closed"
+		});
+	}
+	async #mergePullRequest(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		const { data } = await octokit.pulls.merge({
+			...parts,
+			pull_number: requirePullRequestNumber(input.pullRequestId),
+			commit_title: input.commitTitle,
+			commit_message: input.commitMessage,
+			merge_method: input.method
+		});
+		return {
+			merged: data.merged,
+			message: data.message,
+			sha: data.sha ?? null
+		};
+	}
+	async #listComments(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		const page = parsePositiveCursor(input.cursor);
+		const response = await octokit.issues.listComments({
+			...parts,
+			issue_number: requirePullRequestNumber(input.pullRequestId),
+			per_page: 30,
+			page
+		});
+		return {
+			comments: response.data.map((comment) => parsePullRequestComment(comment)),
+			nextCursor: response.data.length === 30 ? String(page + 1) : null
+		};
+	}
+	async #createComment(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		const { data } = await octokit.issues.createComment({
+			...parts,
+			issue_number: requirePullRequestNumber(input.pullRequestId),
+			body: input.body
+		});
+		return parsePullRequestComment(data);
+	}
+	async #updateComment(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		const { data } = await octokit.issues.updateComment({
+			...parts,
+			comment_id: requirePositiveId(input.commentId, "comment"),
+			body: input.body
+		});
+		return parsePullRequestComment(data);
+	}
+	async #deleteComment(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		await octokit.issues.deleteComment({
+			...parts,
+			comment_id: requirePositiveId(input.commentId, "comment")
+		});
+	}
+	async #listReviews(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		const page = parsePositiveCursor(input.cursor);
+		const response = await octokit.pulls.listReviews({
+			...parts,
+			pull_number: requirePullRequestNumber(input.pullRequestId),
+			per_page: 30,
+			page
+		});
+		return {
+			reviews: response.data.map((review) => parseReview(review)),
+			nextCursor: response.data.length === 30 ? String(page + 1) : null
+		};
+	}
+	async #getReview(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		try {
+			const { data } = await octokit.pulls.getReview({
+				...parts,
+				pull_number: requirePullRequestNumber(input.pullRequestId),
+				review_id: requirePositiveId(input.reviewId, "review")
+			});
+			return parseReview(data);
+		} catch (err) {
+			if (isNotFoundError(err)) return null;
+			throw err;
+		}
+	}
+	async #createReview(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		const { data } = await octokit.pulls.createReview({
+			...parts,
+			pull_number: requirePullRequestNumber(input.pullRequestId),
+			body: input.body,
+			commit_id: input.commitId,
+			event: input.event ? reviewEventToGithub(input.event) : void 0
+		});
+		return parseReview(data);
+	}
+	async #updateReview(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		const { data } = await octokit.pulls.updateReview({
+			...parts,
+			pull_number: requirePullRequestNumber(input.pullRequestId),
+			review_id: requirePositiveId(input.reviewId, "review"),
+			body: input.body
+		});
+		return parseReview(data);
+	}
+	async #submitReview(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		const { data } = await octokit.pulls.submitReview({
+			...parts,
+			pull_number: requirePullRequestNumber(input.pullRequestId),
+			review_id: requirePositiveId(input.reviewId, "review"),
+			body: input.body,
+			event: reviewEventToGithub(input.event)
+		});
+		return parseReview(data);
+	}
+	async #dismissReview(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		const { data } = await octokit.pulls.dismissReview({
+			...parts,
+			pull_number: requirePullRequestNumber(input.pullRequestId),
+			review_id: requirePositiveId(input.reviewId, "review"),
+			message: input.message
+		});
+		return parseReview(data);
+	}
+	async #deletePendingReview(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		await octokit.pulls.deletePendingReview({
+			...parts,
+			pull_number: requirePullRequestNumber(input.pullRequestId),
+			review_id: requirePositiveId(input.reviewId, "review")
+		});
+	}
+	async #listReviewComments(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		const page = parsePositiveCursor(input.cursor);
+		const response = await octokit.pulls.listReviewComments({
+			...parts,
+			pull_number: requirePullRequestNumber(input.pullRequestId),
+			per_page: 30,
+			page
+		});
+		return {
+			comments: response.data.map((comment) => parseReviewComment(comment)),
+			nextCursor: response.data.length === 30 ? String(page + 1) : null
+		};
+	}
+	async #createReviewComment(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		const pullNumber = requirePullRequestNumber(input.pullRequestId);
+		if (input.replyToId) {
+			const { data } = await octokit.pulls.createReplyForReviewComment({
+				...parts,
+				pull_number: pullNumber,
+				comment_id: requirePositiveId(input.replyToId, "review comment"),
+				body: input.body
+			});
+			return parseReviewComment(data);
+		}
+		if (!input.commitId || !input.path || input.line === void 0 || !input.side) throw new Error("A review comment requires commitId, path, line, and side unless it is a reply.");
+		if (input.startLine === void 0 !== (input.startSide === void 0)) throw new Error("A multi-line review comment requires both startLine and startSide.");
+		const { data } = await octokit.pulls.createReviewComment({
+			...parts,
+			pull_number: pullNumber,
+			body: input.body,
+			commit_id: input.commitId,
+			path: input.path,
+			line: input.line,
+			side: input.side.toUpperCase(),
+			start_line: input.startLine,
+			start_side: input.startSide?.toUpperCase()
+		});
+		return parseReviewComment(data);
+	}
+	async #updateReviewComment(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		const { data } = await octokit.pulls.updateReviewComment({
+			...parts,
+			comment_id: requirePositiveId(input.commentId, "review comment"),
+			body: input.body
+		});
+		return parseReviewComment(data);
+	}
+	async #deleteReviewComment(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		await octokit.pulls.deleteReviewComment({
+			...parts,
+			comment_id: requirePositiveId(input.commentId, "review comment")
+		});
+	}
+	async #listRequestedReviewers(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		const { data } = await octokit.pulls.listRequestedReviewers({
+			...parts,
+			pull_number: requirePullRequestNumber(input.pullRequestId)
+		});
+		return parseRequestedReviewers(data);
+	}
+	async #requestReviewers(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		const { data } = await octokit.pulls.requestReviewers({
+			...parts,
+			pull_number: requirePullRequestNumber(input.pullRequestId),
+			reviewers: input.users ?? [],
+			team_reviewers: input.teams ?? []
+		});
+		return parseRequestedReviewers(data);
+	}
+	async #removeReviewers(input) {
+		const { octokit, parts } = this.#repositoryClient(input.connection, input.sourceId);
+		const { data } = await octokit.pulls.removeRequestedReviewers({
+			...parts,
+			pull_number: requirePullRequestNumber(input.pullRequestId),
+			reviewers: input.users ?? [],
+			team_reviewers: input.teams ?? []
+		});
+		return parseRequestedReviewers(data);
+	}
+	/** Add labels to an issue (deduplicated; no-op on empty/malformed input). */
+	async addIssueLabels(installationId, repoFullName, issueNumber, labels) {
+		const parts = splitRepoFullName(repoFullName);
+		if (!parts) return;
+		const uniqueLabels = [...new Set(labels.map((label) => label.trim()).filter(Boolean))];
+		if (uniqueLabels.length === 0) return;
+		await this.getInstallationOctokit(installationId).issues.addLabels({
+			owner: parts.owner,
+			repo: parts.repo,
+			issue_number: issueNumber,
+			labels: uniqueLabels
+		});
+	}
+	/** Remove one label from an issue. */
+	async removeIssueLabel(installationId, repoFullName, issueNumber, label) {
+		const parts = splitRepoFullName(repoFullName);
+		const labelName = label.trim();
+		if (!parts || !labelName) return;
+		await this.getInstallationOctokit(installationId).issues.removeLabel({
+			owner: parts.owner,
+			repo: parts.repo,
+			issue_number: issueNumber,
+			name: labelName
+		});
+	}
+	/**
+	* List one page of a repo's open issues through an installation token. The
+	* issues API also returns pull requests, so those are filtered out (the
+	* filter can make a non-final page shorter than the page size — `nextPage`
+	* is derived from the raw response length, not the filtered one).
+	*/
+	async listRepoOpenIssues(installationId, repoFullName, page, options = {}) {
+		const parts = splitRepoFullName(repoFullName);
+		if (!parts) return {
+			issues: [],
+			nextPage: null
+		};
+		const response = await this.getInstallationOctokit(installationId).issues.listForRepo({
+			owner: parts.owner,
+			repo: parts.repo,
+			state: "open",
+			labels: options.label,
+			per_page: 30,
+			page
+		});
+		return {
+			issues: response.data.filter((issue) => !issue.pull_request).map((issue) => ({
+				number: issue.number,
+				title: issue.title,
+				url: issue.html_url,
+				author: issue.user?.login ?? null,
+				assignees: issue.assignees?.flatMap((assignee) => assignee.login ? [assignee.login] : []) ?? [],
+				labels: issue.labels.map((label) => typeof label === "string" ? label : label.name ?? "").filter(Boolean),
+				comments: issue.comments,
+				createdAt: issue.created_at,
+				updatedAt: issue.updated_at
+			})),
+			nextPage: response.data.length === 30 ? page + 1 : null
+		};
+	}
+	/**
+	* Build the GitHub App install URL. `state` is carried through the install
+	* flow and validated on callback.
+	*/
+	buildInstallUrl(state) {
+		const url = new URL(`https://github.com/apps/${this.#slug}/installations/new`);
+		url.searchParams.set("state", state);
+		return url.toString();
+	}
+	/**
+	* Build the OAuth identify URL (authorize) used to confirm the user's
+	* identity and obtain a user token for listing their installations.
+	*/
+	buildOAuthIdentifyUrl(state, redirectUri) {
+		const url = new URL("https://github.com/login/oauth/authorize");
+		url.searchParams.set("client_id", this.#clientId);
+		url.searchParams.set("redirect_uri", redirectUri);
+		url.searchParams.set("state", state);
+		return url.toString();
+	}
+	/** Exchange an OAuth `code` for a user access token. */
+	async exchangeOAuthCode(code, redirectUri) {
+		const res = await fetch("https://github.com/login/oauth/access_token", {
+			method: "POST",
+			signal: AbortSignal.timeout(GITHUB_OAUTH_TOKEN_TIMEOUT_MS),
+			headers: {
+				"content-type": "application/json",
+				accept: "application/json"
+			},
+			body: JSON.stringify({
+				client_id: this.#clientId,
+				client_secret: this.#clientSecret,
+				code,
+				redirect_uri: redirectUri
+			})
+		});
+		if (!res.ok) throw new Error(`GitHub OAuth token exchange failed: ${res.status}`);
+		const data = await res.json();
+		if (!data.access_token) throw new Error(`GitHub OAuth token exchange returned no token: ${data.error_description ?? data.error ?? "unknown"}`);
+		return data.access_token;
+	}
+	/**
+	* The integration's HTTP surface: the `/web/github/*` + `/auth/github/*`
+	* Mastra `apiRoutes` (webhook handler, install/OAuth flow, project +
+	* worktree + session operations). The factory folds these into the server's
+	* `apiRoutes` when the feature is ready. Handlers operate on this instance.
+	*/
+	routes(ctx) {
+		this.#storage = ctx.storage;
+		const ingestFactoryEvent = attachGithubRules(this, ctx);
+		this.#ingestFactoryEvent = ingestFactoryEvent;
+		return buildGithubRoutes({
+			github: this,
+			auth: ctx.auth,
+			sandbox: ctx.sandbox,
+			...ctx.users ? { users: ctx.users } : {},
+			storage: ctx.factoryStorage,
+			stateSigner: ctx.stateSigner,
+			baseUrl: ctx.baseUrl,
+			controller: ctx.controller,
+			memorySettings: ctx.storage.memorySettings,
+			emitAudit: ctx.hooks?.emitAudit,
+			projects: ctx.storage.projects,
+			ingestFactoryEvent,
+			sessionRetirement: ctx.sessionRetirement,
+			...ctx.workItems ? { workItems: ctx.workItems } : {}
+		});
+	}
+	/**
+	* Import a newly linked repository's open issues and pull requests onto
+	* the board. No-op until routes are mounted with rules configured.
+	*/
+	async ingestLinkedRepositoryBacklog(args) {
+		await ingestLinkedRepositoryBacklog({
+			github: this,
+			...args,
+			ingestFactoryEvent: this.#ingestFactoryEvent
+		});
+	}
+	/**
+	* Pull-request and issue sweeps share a worker and lease, but can be enabled
+	* and paced independently. The legacy combined controls remain the fallback.
+	*/
+	workers(ctx) {
+		const pullRequestEnabled = reconciliationEnabled(process.env.MASTRACODE_GITHUB_PR_RECONCILE_ENABLED, process.env.MASTRACODE_GITHUB_RECONCILE_ENABLED);
+		const issueEnabled = reconciliationEnabled(process.env.MASTRACODE_GITHUB_ISSUE_RECONCILE_ENABLED, process.env.MASTRACODE_GITHUB_RECONCILE_ENABLED);
+		if (!pullRequestEnabled && !issueEnabled) return [];
+		const reconcile = pullRequestEnabled ? attachGithubReconciler(this, ctx, (input) => this.fetchPullRequestState(input)) : void 0;
+		const issues = issueEnabled ? attachGithubIssueReconciler(this, ctx, (input) => this.fetchIssueState(input), (input) => this.listOpenIssueStates(input)) : void 0;
+		if (!reconcile && !issues) return [];
+		const legacyInterval = reconcileInterval(process.env.MASTRACODE_GITHUB_RECONCILE_INTERVAL_MS);
+		const intervalMs = reconcileInterval(process.env.MASTRACODE_GITHUB_PR_RECONCILE_INTERVAL_MS) ?? legacyInterval;
+		const issueIntervalMs = reconcileInterval(process.env.MASTRACODE_GITHUB_ISSUE_RECONCILE_INTERVAL_MS) ?? legacyInterval;
+		return [new GithubReconcileWorker({
+			...reconcile ? { reconcile } : {},
+			...issues ? { reconcileIssues: issues } : {},
+			sourceControl: ctx.storage.sourceControl,
+			...intervalMs ? { intervalMs } : {},
+			...issueIntervalMs ? { issueIntervalMs } : {}
+		})];
+	}
+	/**
+	* Reads live PR state for the merge reconciler. Returns undefined when the PR
+	* cannot be resolved so a sweep never fabricates a merge.
+	*/
+	async fetchPullRequestState(input) {
+		try {
+			const pullRequest = await this.#getPullRequest({
+				connection: {
+					type: "app-installation",
+					installationId: input.installationId
+				},
+				sourceId: input.repository,
+				pullRequestId: String(input.number)
+			});
+			if (!pullRequest) return void 0;
+			return {
+				title: pullRequest.title,
+				url: pullRequest.url,
+				state: pullRequest.state === "closed" ? "closed" : "open",
+				draft: pullRequest.draft,
+				merged: pullRequest.merged,
+				assignees: pullRequest.assignees ?? [],
+				requestedReviewers: pullRequest.requestedReviewers ?? [],
+				labels: pullRequest.labels ?? [],
+				headBranch: pullRequest.headBranch,
+				baseBranch: pullRequest.baseBranch,
+				...pullRequest.author ? { author: pullRequest.author } : {},
+				...pullRequest.createdAt ? { createdAt: pullRequest.createdAt } : {}
+			};
+		} catch {
+			return;
+		}
+	}
+	/**
+	* Reads live issue state for the reconciler. Returns undefined when the
+	* issue cannot be resolved (missing, is actually a PR, API error) so a
+	* sweep never fabricates a close.
+	*/
+	async fetchIssueState(input) {
+		const parts = splitRepoFullName(input.repository);
+		if (!parts) return void 0;
+		try {
+			const { data: issue } = await this.getInstallationOctokit(input.installationId).issues.get({
+				owner: parts.owner,
+				repo: parts.repo,
+				issue_number: input.number
+			});
+			if (issue.pull_request) return void 0;
+			return {
+				title: issue.title,
+				url: issue.html_url,
+				state: issue.state === "closed" ? "closed" : "open",
+				...issue.state_reason ? { stateReason: issue.state_reason } : {},
+				assignees: (issue.assignees ?? []).map((user) => user.login).filter((login) => Boolean(login)),
+				labels: (issue.labels ?? []).map((label) => typeof label === "string" ? label : label.name).filter((name) => Boolean(name)),
+				...issue.user?.login ? { author: issue.user.login } : {},
+				createdAt: issue.created_at,
+				updatedAt: issue.updated_at
+			};
+		} catch {
+			return;
+		}
+	}
+	/**
+	* Lists a repository's open issues (pull requests excluded) so the issue
+	* sweep can mint cards for issues whose webhook never arrived.
+	*/
+	async listOpenIssueStates(input) {
+		const parts = splitRepoFullName(input.repository);
+		if (!parts) return [];
+		const octokit = this.getInstallationOctokit(input.installationId);
+		const issues = [];
+		for (let page = 1; page <= OPEN_ISSUE_DISCOVERY_MAX_PAGES; page += 1) {
+			const { data } = await octokit.issues.listForRepo({
+				owner: parts.owner,
+				repo: parts.repo,
+				state: "open",
+				per_page: OPEN_ISSUE_DISCOVERY_PAGE_SIZE,
+				page
+			});
+			for (const issue of data) {
+				if (issue.pull_request) continue;
+				issues.push({
+					number: issue.number,
+					title: issue.title,
+					url: issue.html_url,
+					state: "open",
+					assignees: (issue.assignees ?? []).map((user) => user.login).filter((login) => Boolean(login)),
+					labels: (issue.labels ?? []).map((label) => typeof label === "string" ? label : label.name).filter((name) => Boolean(name)),
+					...issue.user?.login ? { author: issue.user.login } : {},
+					createdAt: issue.created_at,
+					updatedAt: issue.updated_at
+				});
+			}
+			if (data.length < OPEN_ISSUE_DISCOVERY_PAGE_SIZE) break;
+		}
+		return issues;
+	}
+	/**
+	* Session-scoped agent tools for token refresh and PR subscriptions in
+	* sessions bound to a GitHub-backed project. Empty elsewhere.
+	*/
+	async upsertFactoryTriageComment(input) {
+		const parts = splitRepoFullName(input.repository);
+		if (!parts) throw new Error("GitHub triage comments require an owner/repository source.");
+		const octokit = this.getInstallationOctokit(input.installationId);
+		const comments = [];
+		for (let page = 1;; page += 1) {
+			const response = await octokit.issues.listComments({
+				...parts,
+				issue_number: input.issueNumber,
+				per_page: 100,
+				page
+			});
+			comments.push(...response.data);
+			if (response.data.length < 100) break;
+		}
+		const existing = comments.filter((comment) => comment.body?.includes("<!-- mastra-factory-triage -->") && this.isFactoryCommentAuthor(comment.user?.login)).sort((left, right) => left.id - right.id)[0];
+		if (existing) {
+			const { data } = await octokit.issues.updateComment({
+				...parts,
+				comment_id: existing.id,
+				body: input.body
+			});
+			return {
+				action: "updated",
+				commentId: String(data.id),
+				url: data.html_url
+			};
+		}
+		const { data } = await octokit.issues.createComment({
+			...parts,
+			issue_number: input.issueNumber,
+			body: input.body
+		});
+		return {
+			action: "created",
+			commentId: String(data.id),
+			url: data.html_url
+		};
+	}
+	sessionTools({ requestContext }) {
+		return createGithubSubscriptionTools(requestContext, this);
+	}
+	async postToolObserver({ toolContext, requestContext }) {
+		const pullRequestUrl = parseCreatedPullRequest(toolContext);
+		if (!pullRequestUrl || !requestContext) return;
+		await subscribeCurrentSessionToPullRequest(requestContext, pullRequestUrl, "auto-gh-pr-create", this);
+	}
+	/** Non-secret config snapshot for system diagnostics/startup logs. */
+	diagnostics() {
+		return {
+			slug: this.#slug,
+			webhookSecretConfigured: this.#webhookSecret !== void 0
+		};
+	}
+};
+function parsePullRequest(pr) {
+	return {
+		id: String(pr.number),
+		title: pr.title,
+		url: pr.html_url,
+		author: pr.user?.login ?? null,
+		assignees: (pr.assignees ?? []).flatMap((assignee) => assignee.login ? [assignee.login] : []),
+		requestedReviewers: (pr.requested_reviewers ?? []).flatMap((reviewer) => reviewer.login ? [reviewer.login] : []),
+		labels: (pr.labels ?? []).flatMap((label) => typeof label === "string" ? [label] : label.name ? [label.name] : []),
+		body: pr.body?.trim() ? pr.body : null,
+		state: pr.state === "closed" ? "closed" : "open",
+		draft: pr.draft ?? false,
+		merged: pr.merged ?? Boolean(pr.merged_at),
+		mergeable: typeof pr.mergeable === "boolean" ? pr.mergeable : null,
+		baseBranch: pr.base.ref,
+		headBranch: pr.head.ref,
+		headSha: pr.head.sha,
+		createdAt: pr.created_at,
+		updatedAt: pr.updated_at
+	};
+}
+function parsePullRequestComment(comment) {
+	return {
+		id: String(comment.id),
+		url: comment.html_url,
+		author: comment.user?.login ?? null,
+		body: comment.body ?? "",
+		createdAt: comment.created_at,
+		updatedAt: comment.updated_at
+	};
+}
+function parseReview(review) {
+	return {
+		id: String(review.id),
+		url: review.html_url ?? null,
+		author: review.user?.login ?? null,
+		body: review.body?.trim() ? review.body : null,
+		state: parseReviewState(review.state),
+		commitId: review.commit_id ?? null,
+		submittedAt: review.submitted_at ?? null
+	};
+}
+function parseReviewComment(comment) {
+	const parsed = parsePullRequestComment(comment);
+	const side = comment.side?.toLowerCase();
+	return {
+		...parsed,
+		path: comment.path,
+		line: comment.line ?? null,
+		side: side === "left" || side === "right" ? side : null,
+		commitId: comment.commit_id,
+		replyToId: comment.in_reply_to_id ? String(comment.in_reply_to_id) : null
+	};
+}
+function parseRequestedReviewers(data) {
+	return {
+		users: (data.users ?? data.requested_reviewers ?? []).flatMap((user) => user.login ? [user.login] : []),
+		teams: (data.teams ?? data.requested_teams ?? []).flatMap((team) => team.slug ? [team.slug] : [])
+	};
+}
+function parseReviewState(state) {
+	if (state === "PENDING") return "pending";
+	if (state === "COMMENTED") return "commented";
+	if (state === "APPROVED") return "approved";
+	if (state === "CHANGES_REQUESTED") return "changes-requested";
+	if (state === "DISMISSED") return "dismissed";
+	throw new Error(`Unsupported GitHub review state: ${state}`);
+}
+function reviewEventToGithub(event) {
+	if (event === "approve") return "APPROVE";
+	if (event === "request-changes") return "REQUEST_CHANGES";
+	return "COMMENT";
+}
+function requirePullRequestNumber(value) {
+	return requirePositiveId(value, "pull request");
+}
+function requirePositiveId(value, resource) {
+	const parsed = parsePositiveInteger(value);
+	if (parsed === null) throw new Error(`GitHub ${resource} id must be a positive integer.`);
+	return parsed;
+}
+function getGithubInstallationId(connection) {
+	if (connection.type !== "app-installation") throw new Error("GitHub capabilities require an app-installation connection.");
+	return connection.installationId;
+}
+function getSingleSourceId(sourceIds, message) {
+	if (sourceIds.length !== 1) throw new Error(message);
+	return sourceIds[0];
+}
+function normalizeLabels(labels) {
+	return [...new Set((labels ?? []).map((label) => label.trim()).filter(Boolean))];
+}
+function requireSourceId(sourceId, message) {
+	if (!sourceId) throw new Error(message);
+	return sourceId;
+}
+function parsePositiveCursor(cursor) {
+	if (cursor === void 0) return 1;
+	const page = parsePositiveInteger(cursor);
+	if (page === null) throw new Error("GitHub cursor must be a positive page number.");
+	return page;
+}
+function parsePositiveInteger(value) {
+	if (!/^\d+$/.test(value)) return null;
+	const parsed = Number(value);
+	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : null;
+}
+function isNotFoundError(error) {
+	return typeof error === "object" && error !== null && "status" in error && error.status === 404;
+}
+/** Split an `owner/name` full name into its parts, or `null` when malformed. */
+function splitRepoFullName(repoFullName) {
+	const slash = repoFullName.indexOf("/");
+	if (slash <= 0 || slash === repoFullName.length - 1) return null;
+	return {
+		owner: repoFullName.slice(0, slash),
+		repo: repoFullName.slice(slash + 1)
+	};
+}
+function parseGithubExternalTarget(externalId) {
+	const match = externalId.match(/^github:(\d+):(?:issue|pull-request):(\d+)$/) ?? externalId.match(/^(\d+):(\d+)$/);
+	if (!match?.[1] || !match[2]) return null;
+	const repositoryId = parsePositiveInteger(match[1]);
+	const issueId = parsePositiveInteger(match[2]);
+	return repositoryId && issueId ? {
+		repositoryId: String(repositoryId),
+		issueId: String(issueId)
+	} : null;
+}
+//#endregion
+export { GithubIntegration, LIST_PAGE_SIZE, normalizePrivateKey };
+
+//# sourceMappingURL=integration.js.map