Add fields param to six more list/search tools#2810
Draft
tommaso-moro wants to merge 1 commit into
Draft
Conversation
Extend the optional `fields` response-filtering parameter (gated behind the `fields_param` feature flag, with adoption/savings telemetry) to six more read tools, following the dual-variant pattern already used by search_code and get_file_contents: - list_issues, list_pull_requests, list_commits, list_releases - search_issues, search_pull_requests For each tool, `X` is the flag-enabled variant that advertises `fields` and filters each result item to the requested subset, while `LegacyX` exposes the original schema and never filters, acting as a kill switch when the flag is off. Exactly one variant survives inventory filtering for any flag state via mutually exclusive FeatureFlagEnable / FeatureFlagDisable annotations. Wrapped responses (list_issues, search_issues, search_pull_requests) preserve their count / pagination envelope and only filter the item list; bare-array responses keep their array shape. Filtering reuses the shared filterEachField helper. A new fieldsSchemaProperty helper builds the `fields` schema (search_code and get_file_contents now use it too), and a shared recordFieldsUsageFor helper centralizes the telemetry full-size computation. Each field enum lists only the JSON fields the specific tool actually emits: list_commits omits stats/files (requested without per-file detail) and list_issues lists only the fields its GraphQL fragment populates. Adds per-tool field-filtering, telemetry, and Legacy definition tests, extends the mutual-exclusivity gating test to all eight gated tools, and regenerates the `_ff_fields_param` toolsnaps and feature-flag docs. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Note
Stacked on #2775. Review/merge that PR first.
What
#2775 introduced an optional
fieldsresponse-filtering parameter, gated behind thefields_paramfeature flag and instrumented with adoption/savings telemetry, forsearch_codeandget_file_contents. This PR extends the exact same pattern to six more read tools:list_issueslist_pull_requestslist_commitslist_releasessearch_issuessearch_pull_requestsCallers can pass
fields: [...]to receive only the fields they need for each result item, reducing tool response size (and downstream context usage) on the largest, most frequently called read tools.How
Each tool follows the dual-variant pattern established in the base PR:
X— thefields_param-enabled variant. Advertises thefieldsarray parameter, filters each result item to the requested subset, and records telemetry. OwnsX_ff_fields_param.snap.LegacyX— thefields_param-disabled variant. Exposes the original schema (nofields), never filters, and records no telemetry — it's the kill switch when the flag is off. Owns the canonicalX.snap.Mutually exclusive
FeatureFlagEnable/FeatureFlagDisableannotations guarantee exactly one variant survives inventory filtering for any flag state (asserted for all eight gated tools inTest_FieldsParamVariants_MutuallyExclusive).Response shapes are preserved:
list_issues,search_issues,search_pull_requests) keep their count / pagination envelope and only filter the item list.list_commits,list_releases,list_pull_requests) keep their array shape.Shared helpers keep the surface small:
fieldsSchemaPropertybuilds thefieldsschema (the base PR's two tools now use it too).recordFieldsUsageForcentralizes the telemetry full-size computation.filterEachFieldhelper.Each field enum lists only the JSON fields the specific tool actually emits — e.g.
list_commitsomitsstats/files(it requests commits without per-file detail) andlist_issueslists only the fields its GraphQL fragment populates — so callers are never offered a field the tool cannot return.Testing
Legacy*definition tests._ff_fields_paramtoolsnaps anddocs/feature-flags.md.script/lintclean;script/test(race) green.