@gitkraken/core-gitlens 0.5.104 → 0.5.106

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;
@@ -1559,9 +1583,11 @@ export class IntegrationService implements Disposable, RepositoryResolutionConte
 
 		// 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.
-		for (const [integrationId, connections] of connectionsById) {
-			await this.reconcileCloudConnections(integrationId, connections, forceConnect);
-		}
+		await Promise.all(
+			Array.from(connectionsById, ([integrationId, connections]) =>
+				this.reconcileCloudConnections(integrationId, connections, forceConnect),
+			),
+		);
 
 		this.ctx.hooks?.connection?.onConnectedChanged?.({
 			integrationIds: [...connectedIntegrations.values()],
@@ -1612,79 +1638,91 @@ export class IntegrationService implements Disposable, RepositoryResolutionConte
 		const existingById = new Map(
 			this.configuredIntegrationService.getConfigured(id, { cloud: true }).map(c => [c.id, c]),
 		);
-		for (const connection of identified) {
-			// The wire `domain` is usually a full URL, though cloud providers can return a bare host.
-			// Self-managed integrations are keyed/constructed by host.
-			const host = hostFromDomain(connection.domain);
-
-			// Self-managed connections are keyed by host, so an unparseable/empty domain would store the
-			// session and descriptor under an empty host — producing ambiguous keys (`connected:<id>:`) that
-			// break later resolution and local-disconnect checks. Skip such a connection rather than corrupt
-			// state; cloud providers key off their canonical domain and are unaffected.
-			if (isGitSelfManagedHostIntegrationId(id) && !host) {
-				scope?.warn(`Skipping connection '${connection.id}' for ${id}: unresolved host from domain`);
-				continue;
-			}
+		const preparedConnections = await Promise.all(
+			identified.map(async connection => {
+				// The wire `domain` is usually a full URL, though cloud providers can return a bare host.
+				// Self-managed integrations are keyed/constructed by host.
+				const host = hostFromDomain(connection.domain);
+
+				// Self-managed connections are keyed by host, so an unparseable/empty domain would store the
+				// session and descriptor under an empty host — producing ambiguous keys (`connected:<id>:`) that
+				// break later resolution and local-disconnect checks. Skip such a connection rather than corrupt
+				// state; cloud providers key off their canonical domain and are unaffected.
+				if (isGitSelfManagedHostIntegrationId(id) && !host) {
+					scope?.warn(`Skipping connection '${connection.id}' for ${id}: unresolved host from domain`);
+					return undefined;
+				}
 
-			// Don't resurrect a connection the user disconnected locally: a host "disconnect" only clears
-			// local state (the backend still lists the token), so without this the next non-forced sync would
-			// re-store the secret/config. A forced reconnect clears this flag (in the sync loop above) before
-			// reconcile runs, so it proceeds normally.
-			if (this.isLocallyDisconnected(id, host)) continue;
-
-			syncEligibleIds.add(connection.id);
-
-			// On a routine (non-forced) check-in, skip the token fetch + secret write for a connection we
-			// already have stored and that hasn't expired: nothing to refresh, so avoid the extra GK API
-			// traffic and secret churn. Still treat it as synced (so it doesn't trip the prune guard) and
-			// record its primary below. Forced syncs, new connections, and expired tokens fall through and
-			// fetch as before.
-			const cached = existingById.get(connection.id);
-			if (!forceConnect && cached != null && !isDescriptorExpired(cached)) {
-				syncedIds.add(connection.id);
-				if (connection.primary) {
-					const domain = isGitSelfManagedHostIntegrationId(id) ? host : undefined;
-					if (!syncedPrimaryIdsByDomain.has(domain)) {
-						syncedPrimaryIdsByDomain.set(domain, connection.id);
-					}
+				// Don't resurrect a connection the user disconnected locally: a host "disconnect" only clears
+				// local state (the backend still lists the token), so without this the next non-forced sync would
+				// re-store the secret/config. A forced reconnect clears this flag (in the sync loop above) before
+				// reconcile runs, so it proceeds normally.
+				if (this.isLocallyDisconnected(id, host)) return undefined;
+
+				syncEligibleIds.add(connection.id);
+
+				// On a routine (non-forced) check-in, skip the token fetch + secret write for a connection we
+				// already have stored and that hasn't expired: nothing to refresh, so avoid the extra GK API
+				// traffic and secret churn. Still treat it as synced (so it doesn't trip the prune guard) and
+				// record its primary below. Forced syncs, new connections, and expired tokens fall through and
+				// fetch as before.
+				const cached = existingById.get(connection.id);
+				if (!forceConnect && cached != null && !isDescriptorExpired(cached)) {
+					return { kind: 'cached' as const, connection: connection, host: host };
 				}
-				continue;
-			}
 
-			try {
-				const session = await cloudIntegrations.getConnectionSession(id, undefined, connection.id);
-				if (session == null) continue;
-
-				let providerSession = toProviderSession(id, connection, session, host);
-
-				// Resolve a human-readable account handle with the same precedence as the gk CLI:
-				// (1) the value the backend put on the connection, (2) a previously-resolved name cached in
-				// our configured store (keyed by connection id), (3) a live provider-API lookup. This keeps
-				// provider round-trips to the first sight of a connection; degrade to undefined on failure.
-				const existing = existingById.get(connection.id);
-				const accountName =
-					normalizeAccountName(connection.accountName) ??
-					normalizeAccountName(existing?.accountName) ??
-					(await this.resolveAccountName(id, host, providerSession));
-				if (accountName != null) {
-					providerSession = {
-						...providerSession,
-						account: { ...providerSession.account, label: accountName },
+				try {
+					const session = await cloudIntegrations.getConnectionSession(id, undefined, connection.id);
+					if (session == null) return undefined;
+
+					let providerSession = toProviderSession(id, connection, session, host);
+
+					// Resolve a human-readable account handle with the same precedence as the gk CLI:
+					// (1) the value the backend put on the connection, (2) a previously-resolved name cached in
+					// our configured store (keyed by connection id), (3) a live provider-API lookup. This keeps
+					// provider round-trips to the first sight of a connection; degrade to undefined on failure.
+					const existing = existingById.get(connection.id);
+					const accountName =
+						normalizeAccountName(connection.accountName) ??
+						normalizeAccountName(existing?.accountName) ??
+						(await this.resolveAccountName(id, host, providerSession));
+					if (accountName != null) {
+						providerSession = {
+							...providerSession,
+							account: { ...providerSession.account, label: accountName },
+						};
+					}
+
+					return {
+						kind: 'fetched' as const,
+						connection: connection,
+						host: host,
+						providerSession: providerSession,
 					};
+				} catch (ex) {
+					scope?.warn(
+						`Failed to sync connection '${connection.id}' for ${id}: ${ex instanceof Error ? ex.message : String(ex)}`,
+					);
+					return undefined;
 				}
+			}),
+		);
 
-				await this.configuredIntegrationService.storeSession(id, providerSession);
-				syncedIds.add(connection.id);
-				if (connection.primary) {
-					const domain = isGitSelfManagedHostIntegrationId(id) ? host : undefined;
-					if (!syncedPrimaryIdsByDomain.has(domain)) {
-						syncedPrimaryIdsByDomain.set(domain, connection.id);
-					}
+		// The remote work above is independent, but session persistence remains ordered because storage
+		// implementations may update a shared configured-connections collection with read-modify-write.
+		for (const prepared of preparedConnections) {
+			if (prepared == null) continue;
+
+			if (prepared.kind === 'fetched') {
+				await this.configuredIntegrationService.storeSession(id, prepared.providerSession);
+			}
+
+			syncedIds.add(prepared.connection.id);
+			if (prepared.connection.primary) {
+				const domain = isGitSelfManagedHostIntegrationId(id) ? prepared.host : undefined;
+				if (!syncedPrimaryIdsByDomain.has(domain)) {
+					syncedPrimaryIdsByDomain.set(domain, prepared.connection.id);
 				}
-			} catch (ex) {
-				scope?.warn(
-					`Failed to sync connection '${connection.id}' for ${id}: ${ex instanceof Error ? ex.message : String(ex)}`,
-				);
 			}
 		}
 

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,

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

@@ -42,6 +42,7 @@ export type IntegrationType = 'git' | 'issues';
 // The issue-read contracts live in their own module (pure data, and their relationship to each other is the
 // point of reading them together); re-exported here so the providers that implement these reads keep one import.
 export type { AccountWideIssuesResult, ProviderIssueSearchPage, SearchMyIssuesOptions } from './issueReads.js';
+export type { ProviderPullRequestSearchPage } from './pullRequestReads.js';
 
 export type IntegrationKey<T extends IntegrationIds = IntegrationIds> = T extends
 	| GitCloudHostIntegrationId
@@ -82,6 +83,7 @@ type SyncReqUsecase = Exclude<
 	| 'countIssues'
 	| 'mergePullRequest'
 	| 'searchIssuesPage'
+	| 'searchPullRequestsPage'
 	| 'searchMyIssues'
 	| 'searchMyPullRequests'
 	| 'searchPullRequests',

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

@@ -0,0 +1,18 @@
+import type { PullRequestShape } from '../../../git/models/pullRequest.js';
+
+/**
+ * One provider page of the filtered pull-request search, before the facade turns it into a neutral
+ * paged result with warnings.
+ *
+ * `totalCount` is the provider-reported pre-ceiling facet count, not the number of rows that remain reachable
+ * after a provider limit. It stays optional because absence means "not reported", never zero. Together with
+ * `truncated` it lets the facade distinguish GitHub's quantified ceiling from another unusable continuation.
+ */
+export type ProviderPullRequestSearchPage = {
+	values: PullRequestShape[];
+	truncated: boolean;
+	cursor?: string;
+	hasMore: boolean;
+	page: number;
+	totalCount?: number;
+};

package/src/plus/integrations/providerFilters.ts

@@ -1,9 +1,4 @@
-export enum PullRequestFilter {
-	Author = 'author',
-	Assignee = 'assignee',
-	ReviewRequested = 'review-requested',
-	Mention = 'mention',
-}
+export { PullRequestFilter } from '../../git/models/pullRequest.js';
 
 export enum IssueFilter {
 	Author = 'author',
@@ -25,3 +20,10 @@ export type {
 	IssueSearchCriteria,
 	IssueSearchRelationship,
 } from '../../git/models/issue.js';
+
+/**
+ * The filtered pull-request search criteria and its capability table. These live in `@gitkraken/core-gitlens/git` for the
+ * same dependency-direction reason as the issue-search model above: provider API clients translate them below
+ * this package and cannot import this facade.
+ */
+export type { PullRequestSearchCapabilities, PullRequestSearchCriteria } from '../../git/models/pullRequest.js';

package/src/plus/integrations/providers/github.ts

@@ -5,6 +5,7 @@ import type { IssueOrPullRequest } from '../../../git/models/issueOrPullRequest.
 import type {
 	PullRequest,
 	PullRequestMergeMethod,
+	PullRequestSearchCriteria,
 	PullRequestState,
 	PullRequestStateFilter,
 } from '../../../git/models/pullRequest.js';
@@ -25,7 +26,11 @@ import { IntegrationReadUnavailableError } from '../errors.js';
 import type { IntegrationConnectionChangeEvent } from '../integrationService.js';
 import type { SearchMyPullRequestsOptions } from '../models/gitHostIntegration.js';
 import { GitHostIntegration } from '../models/gitHostIntegration.js';
-import type { ProviderIssueSearchPage, SearchMyIssuesOptions } from '../models/integration.js';
+import type {
+	ProviderIssueSearchPage,
+	ProviderPullRequestSearchPage,
+	SearchMyIssuesOptions,
+} from '../models/integration.js';
 import type { GitHubIntegrationIds } from './github/github.utils.js';
 import { getGitHubPullRequestIdentityFromMaybeUrl } from './github/github.utils.js';
 import type {
@@ -625,6 +630,37 @@ abstract class GitHubIntegrationBase<ID extends GitHubIntegrationIds> extends Gi
 		);
 	}
 
+	/**
+	 * Filtered pull-request search over a repository/organization or explicit current-user relationship scope. The
+	 * API client owns criteria sanitizing, facet unioning, ordering, and the composite cursor that carries GitHub's
+	 * result-ceiling signal across pages.
+	 */
+	protected override async searchProviderPullRequestsPage(
+		session: ProviderAuthenticationSession,
+		options: {
+			repos?: ProviderRepoInput[];
+			org?: string;
+			criteria?: PullRequestSearchCriteria;
+			cursor?: string;
+			pageSize?: number;
+		},
+		cancellation?: AbortSignal,
+	): Promise<ProviderPullRequestSearchPage | undefined> {
+		return (await this.authenticationService.apis.github)?.searchPullRequestsPage(
+			this,
+			toTokenWithInfo(this.id, session),
+			{
+				repos: options.repos?.map(r => `${r.namespace}/${r.name}`),
+				org: options.org,
+				criteria: options.criteria,
+				baseUrl: this.apiBaseUrl,
+				cursor: options.cursor,
+				pageSize: options.pageSize,
+			},
+			cancellation,
+		);
+	}
+
 	/**
 	 * The filtered issue search: one GraphQL request per page, no forced relationship to the current user, and no
 	 * route through the SDK's repo-scoped read (whose over-limit recovery walk can spend up to 128 requests).

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

@@ -75,11 +75,17 @@ import {
 	IssuesCloudHostIntegrationId,
 } from '../constants.js';
 import type { Integration, IntegrationType } from '../models/integration.js';
-import type { IssueSearchCapabilities } from '../providerFilters.js';
+import type { IssueSearchCapabilities, PullRequestSearchCapabilities } from '../providerFilters.js';
 import { IssueFilter, PullRequestFilter } from '../providerFilters.js';
 
 export { IssueFilter, PullRequestFilter } from '../providerFilters.js';
-export type { IssueSearchCapabilities, IssueSearchCriteria, IssueSearchRelationship } from '../providerFilters.js';
+export type {
+	IssueSearchCapabilities,
+	IssueSearchCriteria,
+	IssueSearchRelationship,
+	PullRequestSearchCapabilities,
+	PullRequestSearchCriteria,
+} from '../providerFilters.js';
 import type { ProviderRepositoryShape } from '../results.js';
 
 export type { ProviderOrganization, ProviderRepositoryShape } from '../results.js';
@@ -696,6 +702,16 @@ export interface ProviderMetadata {
 	 * This is independent from `supportedPullRequestFilters`, which describes repo-scoped reads.
 	 */
 	supportedAccountWidePullRequestFilters?: PullRequestFilter[];
+	/**
+	 * What the filtered pull-request search can express server-side. Absent means the provider has
+	 * no such search and the facade refuses it rather than returning an unfiltered page.
+	 */
+	supportedPullRequestSearch?: PullRequestSearchCapabilities;
+	/**
+	 * Maximum results the provider will serve for one pull-request search facet. Matches beyond it are unreachable
+	 * and are reported as a succeeded omission carrying this limit plus the provider's pre-ceiling facet count.
+	 */
+	pullRequestSearchResultLimit?: number;
 	/** Filters the REPO-scoped issue read can express. */
 	supportedIssueFilters?: IssueFilter[];
 	/**
@@ -760,6 +776,21 @@ const githubIssueSearchCapabilities: IssueSearchCapabilities = {
 	states: true,
 };
 
+/** GitHub and GHE use the same filtered pull-request search syntax and result ceiling. */
+const githubPullRequestSearchCapabilities: PullRequestSearchCapabilities = {
+	relationships: [
+		PullRequestFilter.Author,
+		PullRequestFilter.Assignee,
+		PullRequestFilter.ReviewRequested,
+		PullRequestFilter.Mention,
+	],
+	states: ['open', 'closed', 'merged', 'all'],
+	text: true,
+	includeArchived: true,
+	repositoryScope: true,
+	organizationScope: true,
+};
+
 export const providersMetadata: ProvidersMetadata = {
 	[GitCloudHostIntegrationId.GitHub]: {
 		domain: 'github.com',
@@ -782,6 +813,8 @@ export const providersMetadata: ProvidersMetadata = {
 			PullRequestFilter.ReviewRequested,
 			PullRequestFilter.Mention,
 		],
+		supportedPullRequestSearch: githubPullRequestSearchCapabilities,
+		pullRequestSearchResultLimit: githubSearchResultLimit,
 		// Use 'username' property on account for issue filters
 		supportedIssueFilters: [IssueFilter.Author, IssueFilter.Assignee, IssueFilter.Mention],
 		// The account-wide read is three independent searches (`author:@me`, `assignee:@me`, `mentions:@me`) behind
@@ -812,6 +845,8 @@ export const providersMetadata: ProvidersMetadata = {
 			PullRequestFilter.ReviewRequested,
 			PullRequestFilter.Mention,
 		],
+		supportedPullRequestSearch: githubPullRequestSearchCapabilities,
+		pullRequestSearchResultLimit: githubSearchResultLimit,
 		// Use 'username' property on account for issue filters
 		supportedIssueFilters: [IssueFilter.Author, IssueFilter.Assignee, IssueFilter.Mention],
 		// The account-wide read is three independent searches (`author:@me`, `assignee:@me`, `mentions:@me`) behind

package/src/plus/integrations/reads/context.ts

@@ -7,7 +7,7 @@ import type { ProviderWarning } from '../results.js';
 /**
  * Everything the facade's provider reads need from the service that owns connection state — and nothing else.
  *
- * The reads (`listOrgs`, `listRepos`, the paged PR/issue reads, the sweeps, `broadenIssues`,
+ * The reads (`listOrgs`, `listRepos`, the paged PR/issue reads and searches, the sweeps, `broadenIssues`,
  * `resolveRepository`) are otherwise stateless: given a resolved integration they only transform provider
  * results into the neutral shapes consumers get. What they can't do themselves is decide WHICH integration
  * instance and which host a request addresses, because that depends on the configured connections, the