@gitkraken/core-gitlens 0.5.105 → 0.5.107

package/src/plus/git-github/api/github.ts

@@ -13,7 +13,13 @@ import type { Account, UnidentifiedAuthor } from '../../../git/models/author.js'
 import type { DefaultBranch } from '../../../git/models/defaultBranch.js';
 import type { Issue, IssueSearchCriteria, IssueShape } from '../../../git/models/issue.js';
 import type { IssueOrPullRequest } from '../../../git/models/issueOrPullRequest.js';
-import type { PullRequest, PullRequestState, PullRequestStateFilter } from '../../../git/models/pullRequest.js';
+import type {
+	PullRequest,
+	PullRequestSearchCriteria,
+	PullRequestShape,
+	PullRequestState,
+	PullRequestStateFilter,
+} from '../../../git/models/pullRequest.js';
 import { PullRequestMergeMethod } from '../../../git/models/pullRequest.js';
 import type { Provider } from '../../../git/models/remoteProvider.js';
 import type { RepositoryMetadata } from '../../../git/models/repositoryMetadata.js';
@@ -72,6 +78,7 @@ import {
 	toGitHubIssueSearchQualifiers,
 	toGitHubIssueSearchScopeQualifiers,
 } from './issueSearchQuery.js';
+import { toGitHubPullRequestSearchFacets } from './pullRequestSearchQuery.js';
 import type { GitHubTokenInfo } from './token.js';
 
 const emptyPagedResult: PagedResult<any> = Object.freeze({ values: [] });
@@ -89,6 +96,13 @@ const requestRetryMaxDelay = 2000; // ms
 /** How many email->login user searches to alias into a single GraphQL request (keeps query cost within limits). */
 const accountResolveBatchSize = 25;
 
+// Pull-request search selects the full PR fragment (reviews, requests, refs, commits, etc.),
+// which makes GitHub reject broad 100-node searches with `Resource limits for this query
+// exceeded` on large repositories. Thirty keeps the default within that GraphQL cost budget
+// while callers that know their scope is cheap can still opt into the supported 100-node max.
+const defaultPullRequestSearchPageSize = 30;
+const maxPullRequestSearchPageSize = 100;
+
 function isRetryableTransientError(ex: unknown): ex is RequestError {
 	// An aborted request is rethrown as the original `AbortError` (not a `RequestError`), so it is
 	// excluded here. octokit maps a fetch/network failure to a `RequestError` with status 500 and
@@ -164,6 +178,22 @@ export interface AliasedIssueSearchResult {
 	totalCount?: number;
 }
 
+/** One page of the filtered pull-request search. */
+export interface PullRequestSearchResult {
+	values: PullRequestShape[];
+	/** Opaque cursor carrying each active facet continuation plus the positional page. */
+	cursor?: string;
+	hasMore: boolean;
+	page: number;
+	/** True at GitHub's search ceiling or when GitHub advertises a page without a usable cursor. */
+	truncated: boolean;
+	/**
+	 * The largest pre-ceiling `issueCount` any relationship × state facet reported, which is what
+	 * {@link githubSearchResultLimit} applies to. Never the number of rows reachable after that ceiling.
+	 */
+	totalCount?: number;
+}
+
 // Matches a GraphQL document whose operation is definitely a read query — the `query` keyword as
 // the first significant token, after any leading whitespace or `#` comment lines. We retry only
 // when this matches; a mutation (even one prefixed by a comment), a subscription, or anything we
@@ -3480,6 +3510,15 @@ export class GitHubApi {
 		return `https://avatars.githubusercontent.com/u/e?email=${encodeURIComponent(email)}&s=${avatarSize}`;
 	}
 
+	/**
+	 * One page of the current user's pull requests, filtered by state and optionally by an explicit
+	 * relationship qualifier. Backs the PR sweeps, which drain it page by page.
+	 *
+	 * Ordering is part of the contract, not an option: always `sort:updated` (most recently updated first),
+	 * matching {@link searchPullRequestsPage}. A caller that stops before `hasMore` clears — every sweep with a
+	 * page budget — therefore retains a well-defined recency window instead of an arbitrary slice of GitHub's
+	 * relevance ranking.
+	 */
 	@trace({ args: (provider, token) => ({ provider: provider.name, token: `<token:${token.microHash}>` }) })
 	async searchMyPullRequestsPage(
 		provider: Provider,
@@ -3578,12 +3617,20 @@ export class GitHubApi {
 				options?.includeDefaultInvolvement === false
 					? 'is:pr archived:false'
 					: 'is:pr involves:@me archived:false';
+			// Ordering is part of the contract, not an option — same as `searchPullRequestsPage`. Without it
+			// GitHub answers in `best-match` (relevance) order, so any result set the caller stops short of
+			// draining is an arbitrary sample rather than "the N most recent": which rows land inside a page
+			// budget can then shift with GitHub's ranking even when nothing changed upstream. Consumers that
+			// cap the walk depend on this to make their window deterministic and time-bounded.
 			const rsp = await this.graphql<SearchResult>(
 				provider,
 				token,
 				query,
 				{
-					search: [stateQualifier, relationshipQualifier, search].filter(Boolean).join(' ').trim(),
+					search: [stateQualifier, relationshipQualifier, search, 'sort:updated']
+						.filter(Boolean)
+						.join(' ')
+						.trim(),
 					cursor: options?.cursor,
 					baseUrl: options?.baseUrl,
 					avatarSize: options?.avatarSize,
@@ -4022,6 +4069,229 @@ export class GitHubApi {
 		}
 	}
 
+	/**
+	 * Searches pull requests over a repository/org or current-user relationship scope. One GraphQL document carries
+	 * every active relationship × state facet, so one HTTP request serves one page even when the logical search is
+	 * a union. The cursor preserves each facet's continuation plus the positional page.
+	 *
+	 * Ordering is always most-recently-updated-first, and user text is sanitized before it reaches the provider
+	 * query. See {@link toGitHubPullRequestSearchFacets}.
+	 */
+	@trace({ args: (provider, token) => ({ provider: provider.name, token: `<token:${token.microHash}>` }) })
+	async searchPullRequestsPage(
+		provider: Provider,
+		token: GitHubTokenInfo,
+		options?: {
+			repos?: string[];
+			org?: string;
+			criteria?: PullRequestSearchCriteria;
+			baseUrl?: string;
+			avatarSize?: number;
+			cursor?: string;
+			pageSize?: number;
+		},
+		cancellation?: AbortSignal,
+	): Promise<PullRequestSearchResult | undefined> {
+		const scope = getScopedLogger();
+
+		const pageSize = Math.min(
+			maxPullRequestSearchPageSize,
+			Math.max(1, Math.trunc(options?.pageSize ?? defaultPullRequestSearchPageSize)),
+		);
+		const facets = toGitHubPullRequestSearchFacets(options?.criteria);
+		const facetAliases = facets.map(f => f.alias).sort();
+		const scopeQualifiers = toGitHubIssueSearchScopeQualifiers(options?.org, options?.repos);
+		const facetSearches = new Map(
+			facets.map(f => [f.alias, [...scopeQualifiers, ...f.qualifiers].join(' ')] as const),
+		);
+		// Bind a cursor to every qualifier without publishing the user text/scope inside the opaque cursor. FNV-1a
+		// is a compact drift key, not a security primitive: a mismatch only degrades safely to page 1.
+		let cursorKeyHash = 0x811c9dc5;
+		for (const value of [...facetSearches.entries()].sort(([a], [b]) => a.localeCompare(b)).flat()) {
+			for (let i = 0; i < value.length; i++) {
+				cursorKeyHash ^= value.charCodeAt(i);
+				cursorKeyHash = Math.imul(cursorKeyHash, 0x01000193);
+			}
+			cursorKeyHash ^= 0;
+			cursorKeyHash = Math.imul(cursorKeyHash, 0x01000193);
+		}
+		const cursorKey = (cursorKeyHash >>> 0).toString(36);
+
+		type SearchCategory = {
+			issueCount: number;
+			pageInfo?: { endCursor?: string | null; hasNextPage: boolean };
+			nodes: (GitHubPullRequest | null)[] | null;
+		};
+		interface SearchCursor {
+			key: string;
+			page: number;
+			facets: Record<string, string | null>;
+			truncated?: boolean;
+			totalCount?: number;
+		}
+
+		let cursor: SearchCursor | undefined;
+		if (options?.cursor != null) {
+			try {
+				const parsed = JSON.parse(options.cursor) as Partial<SearchCursor>;
+				const parsedFacets = parsed.facets;
+				if (parsedFacets != null && typeof parsedFacets === 'object' && !Array.isArray(parsedFacets)) {
+					const parsedAliases = Object.keys(parsedFacets).sort();
+					const sameFacets =
+						parsedAliases.length === facetAliases.length &&
+						parsedAliases.every((alias, index) => alias === facetAliases[index]);
+					const usableSlots = Object.values(parsedFacets).every(
+						slot => slot === null || (typeof slot === 'string' && slot.length > 0),
+					);
+					if (parsed.key === cursorKey && sameFacets && usableSlots) {
+						cursor = {
+							key: cursorKey,
+							page:
+								typeof parsed.page === 'number' && Number.isFinite(parsed.page)
+									? Math.max(1, Math.trunc(parsed.page))
+									: 1,
+							facets: parsedFacets,
+							truncated: parsed.truncated === true,
+							totalCount:
+								typeof parsed.totalCount === 'number' && Number.isFinite(parsed.totalCount)
+									? Math.max(0, Math.trunc(parsed.totalCount))
+									: undefined,
+						};
+					}
+				}
+			} catch {}
+		}
+		const page = cursor?.page ?? 1;
+		const isActive = (alias: string): boolean => cursor?.facets[alias] !== null;
+		const activeFacets = facets.filter(f => isActive(f.alias));
+		if (activeFacets.length === 0) {
+			return {
+				values: [],
+				hasMore: false,
+				page: page,
+				truncated: cursor?.truncated === true,
+				totalCount: cursor?.totalCount,
+			};
+		}
+
+		const includeVar = (alias: string): string => `include${alias.charAt(0).toUpperCase()}${alias.slice(1)}`;
+		const params = facets.flatMap(f => [
+			`$${f.alias}Search: String!`,
+			`$${f.alias}Cursor: String`,
+			`$${includeVar(f.alias)}: Boolean!`,
+		]);
+		const fields = facets.map(
+			f => `${f.alias}: search(first: ${pageSize}, after: $${f.alias}Cursor, query: $${f.alias}Search, type: ISSUE)
+				@include(if: $${includeVar(f.alias)}) {
+				issueCount
+				pageInfo {
+					endCursor
+					hasNextPage
+				}
+				nodes {
+					... on PullRequest {
+						${gqlPullRequestFragment}
+					}
+				}
+			}`,
+		);
+		const query = `query searchPullRequestsPage(
+			${params.join('\n\t\t\t')}
+			$avatarSize: Int
+		) {
+			${fields.join('\n\t\t\t')}
+		}`;
+
+		const variables: Record<string, unknown> = {
+			baseUrl: options?.baseUrl,
+			avatarSize: options?.avatarSize,
+		};
+		for (const facet of facets) {
+			variables[`${facet.alias}Search`] = facetSearches.get(facet.alias);
+			variables[`${facet.alias}Cursor`] = cursor?.facets[facet.alias] ?? undefined;
+			variables[includeVar(facet.alias)] = isActive(facet.alias);
+		}
+
+		try {
+			const rsp = await this.graphql<Record<string, SearchCategory | undefined>>(
+				provider,
+				token,
+				query,
+				variables,
+				scope,
+				cancellation,
+			);
+			if (rsp == null) return { values: [], hasMore: false, page: page, truncated: false };
+
+			const pullRequests: PullRequestShape[] = [];
+			for (const facet of activeFacets) {
+				for (const node of rsp[facet.alias]?.nodes ?? []) {
+					if (node?.id == null) continue;
+
+					try {
+						pullRequests.push(fromGitHubPullRequest(node, provider));
+					} catch (ex) {
+						scope?.warn(`skipped unmappable pull request; id=${node.id}, url=${node.url}, ex=${ex}`);
+					}
+				}
+			}
+			pullRequests.sort((a, b) => b.updatedDate.getTime() - a.updatedDate.getTime());
+			const values = [
+				...uniqueBy(
+					pullRequests,
+					pr => pr.url,
+					(original, _current) => original,
+				),
+			];
+
+			const nextFacets: Record<string, string | null> = {};
+			let hasMore = false;
+			let continuationMissing = false;
+			let totalCount = cursor?.totalCount ?? 0;
+			let providerLimitReached = false;
+			for (const facet of facets) {
+				if (!isActive(facet.alias)) {
+					nextFacets[facet.alias] = null;
+					continue;
+				}
+
+				const category = rsp[facet.alias];
+				const endCursor =
+					category?.pageInfo?.hasNextPage === true && category.pageInfo.endCursor
+						? category.pageInfo.endCursor
+						: null;
+				nextFacets[facet.alias] = endCursor;
+				if (endCursor != null) {
+					hasMore = true;
+				}
+				if (category?.pageInfo?.hasNextPage === true && category.pageInfo.endCursor == null) {
+					continuationMissing = true;
+				}
+				totalCount = Math.max(totalCount, category?.issueCount ?? 0);
+				providerLimitReached ||= (category?.issueCount ?? 0) > githubSearchResultLimit;
+			}
+			const truncated = cursor?.truncated === true || providerLimitReached || continuationMissing;
+			const next: SearchCursor = {
+				key: cursorKey,
+				page: page + 1,
+				facets: nextFacets,
+				truncated: truncated || undefined,
+				totalCount: totalCount,
+			};
+
+			return {
+				values: values,
+				cursor: hasMore ? JSON.stringify(next) : undefined,
+				hasMore: hasMore,
+				page: page,
+				truncated: truncated,
+				totalCount: totalCount,
+			};
+		} catch (ex) {
+			throw this.handleException(ex, provider, scope);
+		}
+	}
+
 	@trace({ args: (provider, token) => ({ provider: provider.name, token: `<token:${token.microHash}>` }) })
 	async searchPullRequests(
 		provider: Provider,

package/src/plus/git-github/api/pullRequestSearchQuery.ts

@@ -0,0 +1,80 @@
+import type { PullRequestSearchCriteria, PullRequestStateFilter } from '../../../git/models/pullRequest.js';
+import { PullRequestFilter } from '../../../git/models/pullRequest.js';
+import { sanitizeGitHubSearchText } from './issueSearchQuery.js';
+
+export type GitHubPullRequestSearchFacet = {
+	/** Stable GraphQL alias and composite-cursor key. */
+	alias: string;
+	qualifiers: string[];
+};
+
+const relationshipQualifier: Record<PullRequestFilter, string> = {
+	[PullRequestFilter.Author]: 'author:@me',
+	[PullRequestFilter.Assignee]: 'assignee:@me',
+	[PullRequestFilter.ReviewRequested]: 'review-requested:@me',
+	[PullRequestFilter.Mention]: 'mentions:@me',
+};
+
+const relationshipAlias: Record<PullRequestFilter, string> = {
+	[PullRequestFilter.Author]: 'author',
+	[PullRequestFilter.Assignee]: 'assignee',
+	[PullRequestFilter.ReviewRequested]: 'reviewRequested',
+	[PullRequestFilter.Mention]: 'mention',
+};
+
+const stateAlias: Record<PullRequestStateFilter, string> = {
+	open: 'Open',
+	closed: 'Closed',
+	merged: 'Merged',
+	all: 'All',
+};
+
+function stateQualifiers(state: PullRequestStateFilter): string[] {
+	switch (state) {
+		case 'closed':
+			// GitHub's `is:closed` includes merged PRs; `is:unmerged` removes that subset.
+			return ['is:closed', 'is:unmerged'];
+		case 'merged':
+			return ['is:merged'];
+		case 'all':
+			return [];
+		case 'open':
+			return ['is:open'];
+	}
+}
+
+/**
+ * Translates provider-neutral PR criteria into the independent GitHub searches whose union answers the request.
+ *
+ * GitHub's API search syntax ANDs repeated relationship/state qualifiers and does not implement the boolean
+ * groups accepted by the newer web UI. Each requested relationship × state pair therefore becomes one GraphQL
+ * alias; the API client sends every active alias in a single document, preserving one HTTP request per page.
+ * An omitted relationship is the explicitly unfiltered repository/organization scope, never `involves:@me`.
+ */
+export function toGitHubPullRequestSearchFacets(
+	criteria: PullRequestSearchCriteria | undefined,
+): GitHubPullRequestSearchFacet[] {
+	const relationships: (PullRequestFilter | undefined)[] = criteria?.relationships?.length
+		? [...new Set(criteria.relationships)]
+		: [undefined];
+	const requestedStates: PullRequestStateFilter[] = criteria?.states?.length
+		? [...new Set(criteria.states)]
+		: ['open'];
+	const states: PullRequestStateFilter[] = requestedStates.includes('all') ? ['all'] : requestedStates;
+	const text = criteria?.text != null ? sanitizeGitHubSearchText(criteria.text) : '';
+
+	return relationships.flatMap(relationship =>
+		states.map(state => ({
+			alias: `${relationship != null ? relationshipAlias[relationship] : 'scope'}${stateAlias[state]}`,
+			qualifiers: [
+				'is:pr',
+				...(relationship != null ? [relationshipQualifier[relationship]] : []),
+				...stateQualifiers(state),
+				...(criteria?.includeArchived === true ? [] : ['archived:false']),
+				...(text.length > 0 ? [text] : []),
+				// Contract, not an option: a capped result is the N most recently updated only under this order.
+				'sort:updated',
+			],
+		})),
+	);
+}

package/src/plus/integrations/index.ts

@@ -218,6 +218,8 @@ export { IssueFilter, PullRequestFilter } from './providerFilters.js';
 // The filtered issue search's criteria model and the capability table that says which of it a provider honors.
 // String unions and plain interfaces, so a consumer builds criteria without importing an internal subpath.
 export type { IssueSearchCapabilities, IssueSearchCriteria, IssueSearchRelationship } from './providerFilters.js';
+// Account-wide pull-request search criteria and the per-provider capability table.
+export type { PullRequestSearchCapabilities, PullRequestSearchCriteria } from './providerFilters.js';
 // The count-only issue probe's input and result shapes.
 export type { IssueCountResult, IssueCountScope } from './reads/counts.js';
 // Cross-provider PR/issue state filters (string unions in the git models).

package/src/plus/integrations/integrationService.ts

@@ -1,6 +1,11 @@
 import type { Account } from '../../git/models/author.js';
 import type { IssueSearchCriteria, IssueShape } from '../../git/models/issue.js';
-import type { PullRequest, PullRequestShape, PullRequestStateFilter } from '../../git/models/pullRequest.js';
+import type {
+	PullRequest,
+	PullRequestSearchCriteria,
+	PullRequestShape,
+	PullRequestStateFilter,
+} from '../../git/models/pullRequest.js';
 import type { GitRemote } from '../../git/models/remote.js';
 import type { RemoteProviderId } from '../../git/models/remoteProvider.js';
 import type { ResourceDescriptor } from '../../git/models/resourceDescriptor.js';
@@ -67,6 +72,7 @@ import type {
 	ProviderReposInput,
 	ProviderRepositoryShape,
 	PullRequestFilter,
+	PullRequestSearchCapabilities,
 } from './providers/models.js';
 import { providersMetadata } from './providers/models.js';
 import type { ProvidersApi } from './providers/providersApi.js';
@@ -81,6 +87,7 @@ import { listIssueTrackerIssuesPage } from './reads/issueTracker.js';
 import { listPullRequestsPage } from './reads/pullRequests.js';
 import { resolveRepository } from './reads/resolveRepository.js';
 import { searchIssuesPage } from './reads/searchIssues.js';
+import { searchPullRequestsPage } from './reads/searchPullRequests.js';
 import { sweepClosedPullRequests, sweepPullRequests } from './reads/sweeps.js';
 import { noConnectionWarning } from './reads/warnings.js';
 import type {
@@ -533,6 +540,7 @@ export class IntegrationService implements Disposable, RepositoryResolutionConte
 	getSupportedFilters(providerId: IntegrationIds): {
 		pullRequests: PullRequestFilter[];
 		pullRequestsAccountWide: PullRequestFilter[];
+		pullRequestSearch: PullRequestSearchCapabilities;
 		issues: IssueFilter[];
 		issuesAccountWide: IssueFilter[];
 		issueSearch: IssueSearchCapabilities;
@@ -1051,6 +1059,22 @@ export class IntegrationService implements Disposable, RepositoryResolutionConte
 		return listPullRequestsPage(this, options);
 	}
 
+	/** See {@link IntegrationManager.searchPullRequestsPage}. */
+	async searchPullRequestsPage(options: {
+		providerId: IntegrationIds;
+		repos?: ProviderReposInput;
+		org?: string;
+		criteria?: PullRequestSearchCriteria;
+		page?: number;
+		cursor?: string;
+		itemsPerPage?: number;
+		forceSync?: boolean;
+		connectionId?: string;
+		domain?: string;
+	}): Promise<ProviderPagedResult<PullRequestShape>> {
+		return searchPullRequestsPage(this, options);
+	}
+
 	async listIssuesPage(options: {
 		providerId: IntegrationIds;
 		repos?: ProviderReposInput;
@@ -1550,12 +1574,31 @@ export class IntegrationService implements Disposable, RepositoryResolutionConte
 			}
 		}
 
+		// Concurrent, not serial: each `syncCloudConnection` is a cloud round trip (a forced sync deletes the
+		// stored session and refetches it), so a serial loop pays the SUM of every provider's latency on a
+		// path that gates EVERY provider read. `reconcileCloudConnections` below is already `Promise.all`.
+		//
+		// Safe because every shared mutable path is already serialized, which is why this can be a plain
+		// fan-out rather than needing per-provider grouping:
+		// - `ensureProvider` is `@gate()`d on `providerId`, so the two integrations a multi-host
+		//   self-managed id yields (one per domain, see `getSupportedCloudIntegrations`) share one
+		//   in-flight construction instead of racing to `providers.set`.
+		// - `ensureSession` is `@gate()`d per integration instance.
+		// - `addOrUpdateConfigured`/`removeConfigured` mutate `configured` in a synchronous critical
+		//   section (no `await` between read and `set`), and `storeConfigured` has its own write queue.
+		// - Secrets and the `connected:` workspace flags are keyed by integration id + domain.
+		const integrations: Integration[] = [];
 		for await (const integration of this.getSupportedCloudIntegrations(domainsById)) {
-			await integration.syncCloudConnection(
-				this.getCloudConnectionState(integration, connectedIntegrations, domainsById),
-				forceConnect,
-			);
+			integrations.push(integration);
 		}
+		await Promise.all(
+			integrations.map(integration =>
+				integration.syncCloudConnection(
+					this.getCloudConnectionState(integration, connectedIntegrations, domainsById),
+					forceConnect,
+				),
+			),
+		);
 
 		// Persist every account when the backend advertises per-connection identity (multi-account). This
 		// is a strict no-op for backends that return a single, id-less connection per provider.

package/src/plus/integrations/manager.ts

@@ -1,10 +1,19 @@
 import type { IssueSearchCriteria, IssueShape } from '../../git/models/issue.js';
-import type { PullRequestShape, PullRequestStateFilter } from '../../git/models/pullRequest.js';
+import type {
+	PullRequestSearchCriteria,
+	PullRequestShape,
+	PullRequestStateFilter,
+} from '../../git/models/pullRequest.js';
 import type { Event } from '../../utils/event.js';
 import type { ConfiguredIntegrationsChangeEvent } from './authentication/configuredIntegrationService.js';
 import type { ConfiguredIntegrationDescriptor } from './authentication/models.js';
 import type { IntegrationIds } from './constants.js';
-import type { IssueFilter, IssueSearchCapabilities, PullRequestFilter } from './providerFilters.js';
+import type {
+	IssueFilter,
+	IssueSearchCapabilities,
+	PullRequestFilter,
+	PullRequestSearchCapabilities,
+} from './providerFilters.js';
 import type { IssueCountResult, IssueCountScope } from './reads/counts.js';
 import type {
 	ConnectionStateChangeEvent,
@@ -142,8 +151,9 @@ export type ListProjectsOptions =
  *
  * ## Paging contract
  *
- * Every paged read (`listRepos`, `listPullRequestsPage`, `listIssuesPage`, `listIssueTrackerIssuesPage`,
- * `broadenIssues`) takes both `page` and `cursor`, and the two are NOT interchangeable:
+ * Every paged read (`listRepos`, `listPullRequestsPage`, `searchPullRequestsPage`, `listIssuesPage`,
+ * `listIssueTrackerIssuesPage`, `broadenIssues`) takes both `page` and `cursor`, and the two are NOT
+ * interchangeable:
  *
  * - **Supplying `cursor` guarantees a single upstream round trip per provider scope.** A threaded continuation
  *   is handed to the provider as-is; the facade never walks the pages before it. This is a guarantee, not an
@@ -199,6 +209,11 @@ export interface IntegrationManager {
 		pullRequests: PullRequestFilter[];
 		/** Optional for structural compatibility; missing means no account-wide narrowing filters are supported. */
 		pullRequestsAccountWide?: PullRequestFilter[];
+		/**
+		 * Criteria and scopes {@link searchPullRequestsPage} can express. Always present; an empty relationship list
+		 * means the provider exposes no filtered pull-request search.
+		 */
+		pullRequestSearch: PullRequestSearchCapabilities;
 		issues: IssueFilter[];
 		issuesAccountWide: IssueFilter[];
 		/**
@@ -274,6 +289,42 @@ export interface IntegrationManager {
 		 */
 		domain?: string;
 	}): Promise<ProviderPagedResult<PullRequestShape>>;
+	/**
+	 * Pull requests matching structured criteria over a repository/organization or current-user relationship
+	 * scope.
+	 *
+	 * This is a separate read from {@link listPullRequestsPage}: free text reaches the provider instead of filtering
+	 * whichever rows happened to be loaded, and every cursor-threaded page costs exactly one upstream request.
+	 * `criteria.relationships` and `criteria.states` are OR sets, so `[closed, merged]` expresses the complete
+	 * terminal set and `[Author, Assignee, ReviewRequested]` matches the visible PR list without falling back to
+	 * GitHub's mismatched `involves:@me`. Omit relationships only with a repository/organization scope to search
+	 * every PR there.
+	 *
+	 * Results are always ordered most-recently-updated-first. If the provider's result ceiling is reached, the
+	 * request still succeeds and carries a warning omission with `totalCount`, `limit`, and `recovery: 'none'`.
+	 * `totalCount` is the largest provider-reported pre-ceiling facet count, not the reachable or returned row
+	 * count; this mirrors the per-search ceiling's own unit.
+	 *
+	 * Check `getSupportedFilters().pullRequestSearch` before calling. A provider that reports no relationships
+	 * refuses the read rather than returning a page that never honored the criteria or scope.
+	 */
+	searchPullRequestsPage(options: {
+		providerId: IntegrationIds;
+		/** Repository descriptors that bound the search; ids cannot name provider search qualifiers. */
+		repos?: ProviderRepositoriesInput;
+		/** Organization/account that bounds the search. */
+		org?: string;
+		criteria?: PullRequestSearchCriteria;
+		/** Cursor-only: without a cursor, reaching page N costs O(N) upstream requests. */
+		page?: number;
+		cursor?: string;
+		/** Page size per relationship × state facet; the deduped union can contain more rows. */
+		itemsPerPage?: number;
+		forceSync?: boolean;
+		connectionId?: string;
+		/** Self-managed host domain fallback; see {@link ProviderSweepTarget.domain}. */
+		domain?: string;
+	}): Promise<ProviderPagedResult<PullRequestShape>>;
 	listIssuesPage(options: {
 		providerId: IntegrationIds;
 		repos?: ProviderRepositoriesInput;

package/src/plus/integrations/models/gitHostIntegration.ts

@@ -3,7 +3,12 @@ import type { Account, UnidentifiedAuthor } from '../../../git/models/author.js'
 import type { DefaultBranch } from '../../../git/models/defaultBranch.js';
 import type { IssueSearchCriteria, IssueShape, IssueStateFilter } from '../../../git/models/issue.js';
 import type { IssueOrPullRequestState as PullRequestState } from '../../../git/models/issueOrPullRequest.js';
-import type { PullRequest, PullRequestMergeMethod, PullRequestStateFilter } from '../../../git/models/pullRequest.js';
+import type {
+	PullRequest,
+	PullRequestMergeMethod,
+	PullRequestSearchCriteria,
+	PullRequestStateFilter,
+} from '../../../git/models/pullRequest.js';
 import type { RepositoryMetadata } from '../../../git/models/repositoryMetadata.js';
 import type { ResourceDescriptor } from '../../../git/models/resourceDescriptor.js';
 import type { PullRequestUrlIdentity } from '../../../git/utils/pullRequest.utils.js';
@@ -44,7 +49,12 @@ import {
 } from '../providers/models.js';
 import type { ProvidersApi } from '../providers/providersApi.js';
 import { mergeCollectionMetadata } from '../providers/utils/providerPaging.js';
-import type { IntegrationResult, IntegrationType, ProviderIssueSearchPage } from './integration.js';
+import type {
+	IntegrationResult,
+	IntegrationType,
+	ProviderIssueSearchPage,
+	ProviderPullRequestSearchPage,
+} from './integration.js';
 import { IntegrationBase } from './integration.js';
 
 function isAzureDevOpsProvider(
@@ -1543,6 +1553,50 @@ export abstract class GitHostIntegration<
 		options?: SearchMyPullRequestsOptions,
 	): Promise<IntegrationResult<PullRequest[] | undefined>>;
 
+	/**
+	 * Result-returning wrapper for the filtered pull-request search. Errors become the soft
+	 * `{ error }` branch so the public facade can preserve an empty account and a failed request as distinct
+	 * outcomes.
+	 */
+	async searchPullRequestsPageResult(
+		options: {
+			repos?: ProviderRepoInput[];
+			org?: string;
+			criteria?: PullRequestSearchCriteria;
+			cursor?: string;
+			pageSize?: number;
+		},
+		cancellation?: AbortSignal,
+		connectionId?: string,
+	): Promise<IntegrationResult<ProviderPullRequestSearchPage | undefined>> {
+		const scope = getScopedLogger();
+		const session = await this.resolveReadSession(connectionId, scope);
+		if (session == null) return undefined;
+
+		const start = performance.now();
+		try {
+			const result = await this.searchProviderPullRequestsPage?.(session, options, cancellation);
+			this.resetRequestExceptionCount('searchPullRequestsPage');
+			return { value: result, duration: performance.now() - start };
+		} catch (ex) {
+			this.handleProviderException('searchPullRequestsPage', ex, { scope: scope, connectionId: connectionId });
+			return { error: toError(ex), duration: performance.now() - start };
+		}
+	}
+
+	/** Must agree with `ProviderMetadata.supportedPullRequestSearch`. */
+	protected searchProviderPullRequestsPage?(
+		session: ProviderAuthenticationSession,
+		options: {
+			repos?: ProviderRepoInput[];
+			org?: string;
+			criteria?: PullRequestSearchCriteria;
+			cursor?: string;
+			pageSize?: number;
+		},
+		cancellation?: AbortSignal,
+	): Promise<ProviderPullRequestSearchPage | undefined>;
+
 	async searchPullRequests(
 		searchQuery: string,
 		repo?: T,