@githits/mcp 0.30.0 → 0.32.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -18,6 +18,28 @@ update and deployment rather than through a parallel implementation.
18
18
  > filesystem access, authentication implementation or storage, configuration
19
19
  > discovery, or any other host behavior.
20
20
 
21
+ ## Stable Research
22
+
23
+ The public inventory includes `research` by default. It answers one question
24
+ about a public package or repository with a verified, source-cited answer, can
25
+ identify the target from the question, and continues threads by `thread_id`.
26
+ Answers can take a few minutes; `AgenticAskServiceImpl` applies a 210-second
27
+ deadline (`AGENTIC_ASK_REQUEST_TIMEOUT_MS`) and honors the MCP request's abort
28
+ signal. Hosts should keep their request and MCP client timeouts above that
29
+ deadline, or pass a lower `timeoutMs`.
30
+
31
+ Providers must now supply `agenticAskService: AgenticAskService`. Import
32
+ `AgenticAskServiceImpl` and its request/response/runtime contracts from
33
+ `@githits/mcp/client`; construct it with the GitHits REST API base (the same
34
+ `apiUrl` used by `GitHitsServiceImpl`), the request's token provider, and the
35
+ request's client headers and user agent. The browser-callable factory
36
+ `createResearchTool` and `ResearchMcpArgs` are exported from
37
+ `@githits/mcp/tools`. Rate limits map to `RATE_LIMITED`: the short-term limit
38
+ is retryable after `retryAfterSeconds`, while the daily limit sets
39
+ `details.rateLimitScope: "daily"` and is not retryable before 00:00 UTC. Hosted
40
+ MCP must adopt and deploy the released package before its clients receive the
41
+ tool.
42
+
21
43
  ## Stable Target Resolution
22
44
 
23
45
  The public inventory includes `resolve_target` by default. It ranks fuzzy public
@@ -135,6 +157,8 @@ boundary is authenticated and reached.
135
157
 
136
158
  The package expects callers to provide service implementations through `McpToolServices` or a request-scoped `McpToolServicesProvider`. `McpToolServices.readService` is required for the advertised compact `read` tool; remote hosts should construct the `ReadServiceImpl` instance per request with that request's endpoint, token, headers, fetch function, and diagnostics. GitHits does not populate MCP initialize instructions because hosts expose them inconsistently; `quick_start` owns shared guidance instead. Callers may still pass their own `instructions` explicitly. Use `quickStartOptions` to configure the guide. Servers can pass `traceTool` to `createMcpServer()` or `registerMcpTools()` to wrap public tool execution for instrumentation without receiving arguments or auth data.
137
159
 
160
+ Network-backed tools forward the MCP request's abort signal to their service call as an optional trailing `ServiceRequestOptions` argument (`{ signal }`), so a cancelled call or closed connection aborts the backend request. The bundled service implementations behind these tools honor it; custom service implementations should forward `options?.signal` to their own requests. Calls without a signal keep their single-argument shape.
161
+
138
162
  Only imports from `@githits/mcp`, `@githits/mcp/client`, `@githits/mcp/smoke-test`, `@githits/mcp/tools`, and `@githits/mcp/package.json` are public. The workspace alias `@githits/mcp/internal` is not exported, is not supported for external consumers, and must not be used by remote MCP server implementations.
139
163
 
140
164
  Remote MCP servers should provide request-scoped services through `createMcpServer()` and keep transport, auth/session handling, deployment config, and observability outside this package.
package/dist/client.d.ts CHANGED
@@ -56,6 +56,54 @@ interface TokenProvider {
56
56
  forceRefresh(): Promise<string | undefined>;
57
57
  }
58
58
  declare function createStaticTokenProvider(token: string): TokenProvider;
59
+ declare const AGENTIC_ASK_REQUEST_TIMEOUT_MS = 21e4;
60
+ interface AgenticAskQuestion {
61
+ question: string;
62
+ }
63
+ type AgenticAskSubject = {
64
+ target?: string;
65
+ threadId?: never;
66
+ } | {
67
+ target?: never;
68
+ threadId: string;
69
+ };
70
+ type AgenticAskRequest = AgenticAskQuestion & AgenticAskSubject & {
71
+ sourceFormat?: "cli" | "mcp" | "url";
72
+ };
73
+ interface AgenticAskRequestOptions {
74
+ signal?: AbortSignal;
75
+ }
76
+ /** Expected backend envelope; successful JSON is deliberately not runtime-validated. */
77
+ interface AgenticAskResponse {
78
+ display_markdown: string;
79
+ tool_call_id?: string;
80
+ thread_id?: string;
81
+ [key: string]: unknown;
82
+ }
83
+ interface AgenticAskService {
84
+ ask(request: AgenticAskRequest, options?: AgenticAskRequestOptions): Promise<AgenticAskResponse>;
85
+ }
86
+ /**
87
+ * Which Research limit rejected a 429 request: the short-term request rate or
88
+ * the daily limit, which resets at 00:00 UTC.
89
+ */
90
+ type AgenticAskRateLimitScope = "request" | "daily";
91
+ interface AgenticAskServiceRuntimeOptions {
92
+ clientHeaders?: ClientHeaderBuilder;
93
+ userAgent?: string;
94
+ timeoutMs?: number;
95
+ diagnostics?: ServiceDiagnostics;
96
+ }
97
+ declare class AgenticAskServiceImpl implements AgenticAskService {
98
+ private readonly apiUrl;
99
+ private readonly tokenProvider;
100
+ private readonly fetchFn;
101
+ private readonly runtime;
102
+ constructor(apiUrl: string, tokenProvider: TokenProvider, fetchFn?: typeof fetch, runtime?: AgenticAskServiceRuntimeOptions);
103
+ ask(request: AgenticAskRequest, options?: AgenticAskRequestOptions): Promise<AgenticAskResponse>;
104
+ private askRequest;
105
+ private executeAsk;
106
+ }
59
107
  /**
60
108
  * Registry taxonomy shared by code-navigation and package-intelligence
61
109
  * services. Single source of truth for:
@@ -121,6 +169,40 @@ interface ReadTarget {
121
169
  endLine?: number;
122
170
  }
123
171
  /**
172
+ * Optional per-call controls shared by network-backed service methods.
173
+ *
174
+ * `signal` is the caller's cancellation signal, such as an MCP request
175
+ * cancellation. Services combine it with their own request deadline: a caller
176
+ * abort rejects with the signal's reason and is never retried, while an
177
+ * internal deadline keeps each service's timeout error mapping.
178
+ */
179
+ interface ServiceRequestOptions {
180
+ signal?: AbortSignal;
181
+ }
182
+ /** Nullable registry-version association carried by public error inventories. */
183
+ interface RecoveryRef {
184
+ ref: string;
185
+ version?: string | null;
186
+ }
187
+ /** Public recovery facts; registry releases and indexed snapshots stay distinct. */
188
+ interface VersionRefRecovery {
189
+ code: "VERSION_NOT_FOUND" | "REF_NOT_FOUND";
190
+ retryable?: boolean;
191
+ package?: string;
192
+ requestedVersion?: string;
193
+ requestedRef?: string;
194
+ repoUrl?: string;
195
+ latestVersion?: string;
196
+ latestIndexed?: string;
197
+ availablePackageVersions?: string[];
198
+ availableVersions?: RecoveryRef[];
199
+ availableRefs?: RecoveryRef[];
200
+ suggestedRefs?: RecoveryRef[];
201
+ inputPath?: (string | number)[];
202
+ targetIndex?: number;
203
+ targetCount?: number;
204
+ }
205
+ /**
124
206
  * Back-compat alias — the canonical registry union now lives in
125
207
  * `src/shared/pkgseer-registry.ts`. Re-exported here so existing
126
208
  * consumers of `CodeNavigationRegistry` compile unchanged.
@@ -791,7 +873,7 @@ interface CodeNavigationService {
791
873
  }
792
874
  /** Additive client capability for the unpromoted CodeDiff surface. */
793
875
  interface CodeDiffService {
794
- codeDiff(params: CodeDiffParams): Promise<CodeDiffResult>;
876
+ codeDiff(params: CodeDiffParams, options?: ServiceRequestOptions): Promise<CodeDiffResult>;
795
877
  }
796
878
  /**
797
879
  * GraphQL resolver error for CodeDiff. `partial` is present only when the
@@ -816,7 +898,7 @@ declare class CodeNavigationServiceImpl implements CodeNavigationService, CodeDi
816
898
  private postGraphqlWithTargetResolutionFallback;
817
899
  search(params: UnifiedSearchParams, options?: UnifiedSearchReadOptions): Promise<UnifiedSearchOutcome>;
818
900
  searchStatus(searchRef: string, waitTimeoutMs?: number, options?: UnifiedSearchReadOptions): Promise<UnifiedSearchOutcome>;
819
- codeDiff(params: CodeDiffParams): Promise<CodeDiffResult>;
901
+ codeDiff(params: CodeDiffParams, options?: ServiceRequestOptions): Promise<CodeDiffResult>;
820
902
  private executeCodeDiff;
821
903
  private createCodeDiffRootError;
822
904
  private executeUnifiedSearch;
@@ -1041,7 +1123,7 @@ interface GrepResult {
1041
1123
  totalMatches: number;
1042
1124
  }
1043
1125
  interface GrepService {
1044
- grep(params: GrepParams): Promise<GrepResult>;
1126
+ grep(params: GrepParams, options?: ServiceRequestOptions): Promise<GrepResult>;
1045
1127
  }
1046
1128
  interface GrepServiceRuntime {
1047
1129
  clientHeaders?: ClientHeaderBuilder;
@@ -1078,7 +1160,7 @@ declare class GrepServiceImpl implements GrepService {
1078
1160
  private readonly fetchFn;
1079
1161
  private readonly runtime;
1080
1162
  constructor(endpointUrl: string, tokenProvider: TokenProvider, fetchFn?: typeof fetch, runtime?: GrepServiceRuntime);
1081
- grep(params: GrepParams): Promise<GrepResult>;
1163
+ grep(params: GrepParams, options?: ServiceRequestOptions): Promise<GrepResult>;
1082
1164
  private executeGrep;
1083
1165
  }
1084
1166
  type ListFileIntent = "PRODUCTION" | "TEST" | "BENCHMARK" | "EXAMPLE" | "GENERATED" | "FIXTURE" | "BUILD" | "VENDOR";
@@ -1197,7 +1279,7 @@ interface ListResult {
1197
1279
  preparation: ListSitePreparation | null;
1198
1280
  }
1199
1281
  interface ListService {
1200
- list(params: ListParams): Promise<ListResult>;
1282
+ list(params: ListParams, options?: ServiceRequestOptions): Promise<ListResult>;
1201
1283
  }
1202
1284
  interface ListServiceRuntime {
1203
1285
  clientHeaders?: ClientHeaderBuilder;
@@ -1221,7 +1303,8 @@ declare class ListGraphQLError extends Error {
1221
1303
  readonly indexingRef?: string | undefined;
1222
1304
  readonly hint?: string | undefined;
1223
1305
  readonly indexingMetadata: ListIndexingErrorMetadata | undefined;
1224
- constructor(message: string, code?: string | undefined, retryable?: boolean | undefined, repoUrl?: string | undefined, commitSha?: string | undefined, indexingRef?: string | undefined, hint?: string | undefined, indexingMetadata?: ListIndexingErrorMetadata | undefined);
1306
+ readonly recovery: VersionRefRecovery | undefined;
1307
+ constructor(message: string, code?: string | undefined, retryable?: boolean | undefined, repoUrl?: string | undefined, commitSha?: string | undefined, indexingRef?: string | undefined, hint?: string | undefined, indexingMetadata?: ListIndexingErrorMetadata | undefined, recovery?: VersionRefRecovery | undefined);
1225
1308
  }
1226
1309
  declare class ListBackendError extends Error {
1227
1310
  readonly status?: number | undefined;
@@ -1244,7 +1327,7 @@ declare class ListServiceImpl implements ListService {
1244
1327
  private readonly fetchFn;
1245
1328
  private readonly runtime;
1246
1329
  constructor(endpointUrl: string, tokenProvider: TokenProvider, fetchFn?: typeof fetch, runtime?: ListServiceRuntime);
1247
- list(params: ListParams): Promise<ListResult>;
1330
+ list(params: ListParams, options?: ServiceRequestOptions): Promise<ListResult>;
1248
1331
  private executeList;
1249
1332
  }
1250
1333
  interface PackageSummaryParams {
@@ -1312,10 +1395,10 @@ interface PackageVulnerabilitiesParams {
1312
1395
  includeTransitive?: boolean;
1313
1396
  /** Optional internal breadth for advisory-wide transitive detail fields. */
1314
1397
  includeTransitiveAdvisoryDetails?: boolean;
1315
- /** Advisory rows to return for the root and opt-in transitive audit; direct counts always include all scopes. */
1398
+ /** Advisory rows to return. Summary counts always include all scopes. */
1316
1399
  advisoryScope?: VulnerabilityScope;
1317
1400
  }
1318
- type VulnerabilityScope = "AFFECTED" | "NON_AFFECTING" | "ALL";
1401
+ type VulnerabilityScope = "AFFECTED" | "NON_AFFECTING" | "UNKNOWN" | "ALL";
1319
1402
  interface PackageVersionIdentity {
1320
1403
  name: string;
1321
1404
  registry?: string;
@@ -1339,10 +1422,14 @@ interface VulnerabilityDetail {
1339
1422
  aliases?: string[];
1340
1423
  isMalicious?: boolean;
1341
1424
  affectsInspectedVersion?: boolean;
1425
+ assessmentStatus?: string;
1426
+ assessmentReasons?: string[];
1342
1427
  matchedAffectedVersionRanges?: string[];
1343
1428
  duplicateIds?: string[];
1344
1429
  }
1345
1430
  interface VulnerabilitySecurityDetails {
1431
+ unknownVulnerabilityCount?: number;
1432
+ assessmentStatus?: string;
1346
1433
  affectedVulnerabilityCount: number;
1347
1434
  nonAffectingVulnerabilityCount: number;
1348
1435
  allVulnerabilityCount: number;
@@ -1355,7 +1442,13 @@ interface VulnerabilityReport {
1355
1442
  security?: VulnerabilitySecurityDetails;
1356
1443
  transitive?: TransitiveVulnerabilityAudit;
1357
1444
  }
1358
- interface TransitiveVulnerabilityAudit {
1445
+ interface TransitiveVulnerabilityAuditCounts {
1446
+ affectedCount: number;
1447
+ nonAffectingCount: number;
1448
+ unknownCount: number;
1449
+ totalCount: number;
1450
+ }
1451
+ interface TransitiveVulnerabilityAudit extends TransitiveVulnerabilityAuditCounts {
1359
1452
  /** Advisory scope applied to dependency-package occurrences. */
1360
1453
  advisoryScope: VulnerabilityScope;
1361
1454
  /** Number of resolved package-version graph nodes checked. */
@@ -1367,7 +1460,7 @@ interface TransitiveVulnerabilityAudit {
1367
1460
  calculatedAt?: string;
1368
1461
  packages: TransitiveVulnerabilityAuditPackage[];
1369
1462
  }
1370
- interface TransitiveVulnerabilityAuditPackage {
1463
+ interface TransitiveVulnerabilityAuditPackage extends TransitiveVulnerabilityAuditCounts {
1371
1464
  registry: string;
1372
1465
  name: string;
1373
1466
  occurrenceCount: number;
@@ -1427,6 +1520,8 @@ interface PackageUpgradeReviewParams {
1427
1520
  minSeverity?: number;
1428
1521
  }
1429
1522
  interface PackageUpgradeAdvisorySummary {
1523
+ assessmentStatus?: string;
1524
+ assessmentReasons?: string[];
1430
1525
  id?: string;
1431
1526
  aliases: string[];
1432
1527
  summary?: string;
@@ -1436,6 +1531,8 @@ interface PackageUpgradeAdvisorySummary {
1436
1531
  isMalicious?: boolean;
1437
1532
  }
1438
1533
  interface PackageUpgradeVersionVulnerabilitySummary {
1534
+ unknownVulnerabilityCount?: number;
1535
+ assessmentStatus?: string;
1439
1536
  version: string;
1440
1537
  publishedAt?: string;
1441
1538
  deprecated?: boolean;
@@ -1551,6 +1648,12 @@ interface PackageUpgradeDependencyIssues {
1551
1648
  introducedConflicts: string[];
1552
1649
  introducedOutdated: string[];
1553
1650
  }
1651
+ interface PackageUpgradeUnknownEvidence {
1652
+ section: string;
1653
+ code: string;
1654
+ message: string;
1655
+ retryable?: boolean;
1656
+ }
1554
1657
  interface PackageUpgradeReview {
1555
1658
  registry: string;
1556
1659
  name: string;
@@ -1563,7 +1666,9 @@ interface PackageUpgradeReview {
1563
1666
  compatibility?: PackageUpgradeCompatibility;
1564
1667
  dependencyChanges?: PackageUpgradeDependencyChanges;
1565
1668
  dependencyIssues?: PackageUpgradeDependencyIssues;
1669
+ /** Compatibility field derived from unknownDetails, never selected separately. */
1566
1670
  unknowns: string[];
1671
+ unknownDetails?: PackageUpgradeUnknownEvidence[];
1567
1672
  }
1568
1673
  interface PackageUpgradeReviewResponse {
1569
1674
  summary: {
@@ -1683,6 +1788,8 @@ interface VulnerabilitySummaryDetail {
1683
1788
  isMalicious?: boolean;
1684
1789
  }
1685
1790
  interface TransitiveDependencyVulnerability {
1791
+ assessmentStatus?: string;
1792
+ assessmentReasons?: string[];
1686
1793
  version: string;
1687
1794
  affectsResolvedVersion: boolean;
1688
1795
  matchedAffectedVersionRanges: string[];
@@ -1984,14 +2091,14 @@ interface PackageDocResult {
1984
2091
  page?: PackageDocPage;
1985
2092
  }
1986
2093
  interface PackageIntelligenceService {
1987
- packageSummary(params: PackageSummaryParams): Promise<PackageSummary>;
1988
- packageVulnerabilities(params: PackageVulnerabilitiesParams): Promise<VulnerabilityReport>;
1989
- packageDependencies(params: PackageDependenciesParams): Promise<DependencyReport>;
1990
- packageUpgradeDependencyProbe(params: PackageUpgradeDependencyProbeParams): Promise<DependencyReport>;
1991
- packageUpgradeReview(params: PackageUpgradeReviewParams): Promise<PackageUpgradeReviewResponse>;
1992
- packageChangelog(params: PackageChangelogParams): Promise<ChangelogReport>;
1993
- listPackageDocs(params: ListPackageDocsParams): Promise<PackageDocsList>;
1994
- readPackageDoc(params: ReadPackageDocParams): Promise<PackageDocResult>;
2094
+ packageSummary(params: PackageSummaryParams, options?: ServiceRequestOptions): Promise<PackageSummary>;
2095
+ packageVulnerabilities(params: PackageVulnerabilitiesParams, options?: ServiceRequestOptions): Promise<VulnerabilityReport>;
2096
+ packageDependencies(params: PackageDependenciesParams, options?: ServiceRequestOptions): Promise<DependencyReport>;
2097
+ packageUpgradeDependencyProbe(params: PackageUpgradeDependencyProbeParams, options?: ServiceRequestOptions): Promise<DependencyReport>;
2098
+ packageUpgradeReview(params: PackageUpgradeReviewParams, options?: ServiceRequestOptions): Promise<PackageUpgradeReviewResponse>;
2099
+ packageChangelog(params: PackageChangelogParams, options?: ServiceRequestOptions): Promise<ChangelogReport>;
2100
+ listPackageDocs(params: ListPackageDocsParams, options?: ServiceRequestOptions): Promise<PackageDocsList>;
2101
+ readPackageDoc(params: ReadPackageDocParams, options?: ServiceRequestOptions): Promise<PackageDocResult>;
1995
2102
  }
1996
2103
  declare class PackageIntelligenceServiceImpl implements PackageIntelligenceService {
1997
2104
  private readonly endpointUrl;
@@ -2004,21 +2111,21 @@ declare class PackageIntelligenceServiceImpl implements PackageIntelligenceServi
2004
2111
  clientVersion?: string;
2005
2112
  diagnostics?: ServiceDiagnostics;
2006
2113
  });
2007
- packageSummary(params: PackageSummaryParams): Promise<PackageSummary>;
2114
+ packageSummary(params: PackageSummaryParams, options?: ServiceRequestOptions): Promise<PackageSummary>;
2008
2115
  private executePackageSummary;
2009
2116
  private createHttpError;
2010
2117
  private createTransportError;
2011
2118
  private createGraphQLError;
2012
2119
  private normalise;
2013
- packageVulnerabilities(params: PackageVulnerabilitiesParams): Promise<VulnerabilityReport>;
2120
+ packageVulnerabilities(params: PackageVulnerabilitiesParams, options?: ServiceRequestOptions): Promise<VulnerabilityReport>;
2014
2121
  private executePackageVulnerabilities;
2015
2122
  private fetchPackageVulnerabilitiesPage;
2016
2123
  private normaliseVulnerabilityReport;
2017
2124
  private fetchTransitiveVulnerabilityAudit;
2018
2125
  private normaliseTransitiveVulnerabilityAudit;
2019
- packageDependencies(params: PackageDependenciesParams): Promise<DependencyReport>;
2020
- packageUpgradeDependencyProbe(params: PackageUpgradeDependencyProbeParams): Promise<DependencyReport>;
2021
- packageUpgradeReview(params: PackageUpgradeReviewParams): Promise<PackageUpgradeReviewResponse>;
2126
+ packageDependencies(params: PackageDependenciesParams, options?: ServiceRequestOptions): Promise<DependencyReport>;
2127
+ packageUpgradeDependencyProbe(params: PackageUpgradeDependencyProbeParams, options?: ServiceRequestOptions): Promise<DependencyReport>;
2128
+ packageUpgradeReview(params: PackageUpgradeReviewParams, options?: ServiceRequestOptions): Promise<PackageUpgradeReviewResponse>;
2022
2129
  private executePackageUpgradeReview;
2023
2130
  private fetchUpgradeStatementPage;
2024
2131
  private executePackageUpgradeDependencyProbe;
@@ -2028,13 +2135,13 @@ declare class PackageIntelligenceServiceImpl implements PackageIntelligenceServi
2028
2135
  private normaliseVulnerabilitySummaryDetail;
2029
2136
  private normaliseTransitiveAuditAdvisory;
2030
2137
  private normaliseDependencyIssuesSummary;
2031
- packageChangelog(params: PackageChangelogParams): Promise<ChangelogReport>;
2138
+ packageChangelog(params: PackageChangelogParams, options?: ServiceRequestOptions): Promise<ChangelogReport>;
2032
2139
  private executePackageChangelog;
2033
2140
  private fetchPackageChangelogPage;
2034
- listPackageDocs(params: ListPackageDocsParams): Promise<PackageDocsList>;
2141
+ listPackageDocs(params: ListPackageDocsParams, options?: ServiceRequestOptions): Promise<PackageDocsList>;
2035
2142
  private executeListPackageDocs;
2036
2143
  private normalisePackageDocsList;
2037
- readPackageDoc(params: ReadPackageDocParams): Promise<PackageDocResult>;
2144
+ readPackageDoc(params: ReadPackageDocParams, options?: ServiceRequestOptions): Promise<PackageDocResult>;
2038
2145
  private executeReadPackageDoc;
2039
2146
  }
2040
2147
  interface ReadParams {
@@ -2086,7 +2193,7 @@ interface ReadSymbolResolutionResult {
2086
2193
  }
2087
2194
  type ReadResult = ReadCodeResult | ReadDocsResult | ReadSymbolResolutionResult;
2088
2195
  interface ReadService {
2089
- read(params: ReadParams): Promise<ReadResult>;
2196
+ read(params: ReadParams, options?: ServiceRequestOptions): Promise<ReadResult>;
2090
2197
  }
2091
2198
  interface ReadServiceRuntime {
2092
2199
  clientHeaders?: ClientHeaderBuilder;
@@ -2101,7 +2208,7 @@ declare class ReadServiceImpl implements ReadService {
2101
2208
  private readonly fetchFn;
2102
2209
  private readonly runtime;
2103
2210
  constructor(endpointUrl: string, tokenProvider: TokenProvider, fetchFn?: typeof fetch, runtime?: ReadServiceRuntime);
2104
- read(params: ReadParams): Promise<ReadResult>;
2211
+ read(params: ReadParams, options?: ServiceRequestOptions): Promise<ReadResult>;
2105
2212
  private executeRead;
2106
2213
  }
2107
2214
  /**
@@ -2200,7 +2307,7 @@ interface ResolveTargetResult {
2200
2307
  ambiguousReason: string;
2201
2308
  }
2202
2309
  interface ResolveTargetService {
2203
- resolveTarget(params: ResolveTargetParams): Promise<ResolveTargetResult>;
2310
+ resolveTarget(params: ResolveTargetParams, options?: ServiceRequestOptions): Promise<ResolveTargetResult>;
2204
2311
  }
2205
2312
  declare class ResolveTargetServiceImpl implements ResolveTargetService {
2206
2313
  private readonly endpointUrl;
@@ -2213,7 +2320,7 @@ declare class ResolveTargetServiceImpl implements ResolveTargetService {
2213
2320
  clientVersion?: string;
2214
2321
  diagnostics?: ServiceDiagnostics;
2215
2322
  });
2216
- resolveTarget(params: ResolveTargetParams): Promise<ResolveTargetResult>;
2323
+ resolveTarget(params: ResolveTargetParams, options?: ServiceRequestOptions): Promise<ResolveTargetResult>;
2217
2324
  private executeResolveTarget;
2218
2325
  }
2219
- export { AgentInfo, CodeDiffError, CodeDiffErrorDetails, CodeDiffErrorRef, CodeDiffMode, CodeDiffOptions, CodeDiffPackageInfo, CodeDiffPackageTarget, CodeDiffParams, CodeDiffPartialResult, CodeDiffRefKind, CodeDiffRefResolution, CodeDiffRepositoryTarget, CodeDiffResult, CodeDiffService, CodeDiffTarget, CodeDiffVersionSource, CodeNavigationService, CodeNavigationServiceImpl, CodeSymbolCandidate, CodeSymbolResolution, CodeSymbolSuggestion, ContentModification, ContentSafety, DEFAULT_API_URL, DEFAULT_CODE_NAV_URL, DEFAULT_MCP_URL, DiscoveryIndexingEstimate, GitHitsService, GitHitsServiceImpl, GrepAccessError, GrepBackendError, GrepContentSafety, GrepCorpus, GrepFileIssue, GrepGraphQLError, GrepHit, GrepLineSlice, GrepNetworkError, GrepParams, GrepPathSelector, GrepReadAction, GrepReadiness, GrepRepositoryHit, GrepResult, GrepService, GrepServiceImpl, GrepSiteHit, GrepTarget, GrepTargetStatus, GrepTraversal, GrepUnavailableTarget, IndexingDurationEstimate, KnownLatestVersionMaliciousStatus, KnownMaliciousAdvisoryClassificationReason, LatestVersionMaliciousStatus, ListAccessError, ListAction, ListAvailableVersion, ListBackendError, ListBrowseAction, ListEntry, ListEntryKind, ListFileIntent, ListGraphQLError, ListIndexingEstimate, ListInventoryKind, ListNetworkError, ListParams, ListReadAction, ListResolution, ListResult, ListService, ListServiceImpl, ListSiteJob, ListSitePreparation, ListSiteWait, ListSiteWaitOutcome, ListTargetIdentity, ListTargetResolution, MalformedGrepResponseError, MalformedListResponseError, MaliciousAdvisoryClassificationReason, PKGSEER_REGISTRY_LIST, PackageIntelligenceService, PackageIntelligenceServiceImpl, RawCodeDiff, RawCodeDiffContentCoverage, RawCodeDiffContentFailure, RawCodeDiffFile, RawCodeDiffFileContentStatus, RawCodeDiffFileStatus, RawCodeDiffPathEncoding, RawCodeDiffScope, RawCodeDiffScopeStatus, RawCodeDiffSummary, ReadCodeResult, ReadDocsResult, ReadParams, ReadResult, ReadService, ReadServiceImpl, ReadSymbolResolutionResult, ReadTarget, RefreshingGitHitsService, ResolveTargetKind, ResolveTargetLatestVersionMaliciousAdvisory, ResolveTargetLatestVersionMaliciousEvidence, ResolveTargetMatch, ResolveTargetParams, ResolveTargetReference, ResolveTargetResult, ResolveTargetService, ResolveTargetServiceImpl, ResolveTargetTarget, ServiceDiagnostics, SessionIdConfigError, TokenProvider, createClientHeaderBuilder, createStaticTokenProvider, getApiUrl, getCodeNavigationUrl, getEnvApiToken, getEnvSessionId, getMcpUrl, toPkgseerRegistry, toPkgseerRegistryLowercase };
2326
+ export { AGENTIC_ASK_REQUEST_TIMEOUT_MS, AgentInfo, AgenticAskRateLimitScope, AgenticAskRequest, AgenticAskRequestOptions, AgenticAskResponse, AgenticAskService, AgenticAskServiceImpl, AgenticAskServiceRuntimeOptions, CodeDiffError, CodeDiffErrorDetails, CodeDiffErrorRef, CodeDiffMode, CodeDiffOptions, CodeDiffPackageInfo, CodeDiffPackageTarget, CodeDiffParams, CodeDiffPartialResult, CodeDiffRefKind, CodeDiffRefResolution, CodeDiffRepositoryTarget, CodeDiffResult, CodeDiffService, CodeDiffTarget, CodeDiffVersionSource, CodeNavigationService, CodeNavigationServiceImpl, CodeSymbolCandidate, CodeSymbolResolution, CodeSymbolSuggestion, ContentModification, ContentSafety, DEFAULT_API_URL, DEFAULT_CODE_NAV_URL, DEFAULT_MCP_URL, DiscoveryIndexingEstimate, GitHitsService, GitHitsServiceImpl, GrepAccessError, GrepBackendError, GrepContentSafety, GrepCorpus, GrepFileIssue, GrepGraphQLError, GrepHit, GrepLineSlice, GrepNetworkError, GrepParams, GrepPathSelector, GrepReadAction, GrepReadiness, GrepRepositoryHit, GrepResult, GrepService, GrepServiceImpl, GrepSiteHit, GrepTarget, GrepTargetStatus, GrepTraversal, GrepUnavailableTarget, IndexingDurationEstimate, KnownLatestVersionMaliciousStatus, KnownMaliciousAdvisoryClassificationReason, LatestVersionMaliciousStatus, ListAccessError, ListAction, ListAvailableVersion, ListBackendError, ListBrowseAction, ListEntry, ListEntryKind, ListFileIntent, ListGraphQLError, ListIndexingEstimate, ListInventoryKind, ListNetworkError, ListParams, ListReadAction, ListResolution, ListResult, ListService, ListServiceImpl, ListSiteJob, ListSitePreparation, ListSiteWait, ListSiteWaitOutcome, ListTargetIdentity, ListTargetResolution, MalformedGrepResponseError, MalformedListResponseError, MaliciousAdvisoryClassificationReason, PKGSEER_REGISTRY_LIST, PackageIntelligenceService, PackageIntelligenceServiceImpl, RawCodeDiff, RawCodeDiffContentCoverage, RawCodeDiffContentFailure, RawCodeDiffFile, RawCodeDiffFileContentStatus, RawCodeDiffFileStatus, RawCodeDiffPathEncoding, RawCodeDiffScope, RawCodeDiffScopeStatus, RawCodeDiffSummary, ReadCodeResult, ReadDocsResult, ReadParams, ReadResult, ReadService, ReadServiceImpl, ReadSymbolResolutionResult, ReadTarget, RefreshingGitHitsService, ResolveTargetKind, ResolveTargetLatestVersionMaliciousAdvisory, ResolveTargetLatestVersionMaliciousEvidence, ResolveTargetMatch, ResolveTargetParams, ResolveTargetReference, ResolveTargetResult, ResolveTargetService, ResolveTargetServiceImpl, ResolveTargetTarget, ServiceDiagnostics, ServiceRequestOptions, SessionIdConfigError, TokenProvider, createClientHeaderBuilder, createStaticTokenProvider, getApiUrl, getCodeNavigationUrl, getEnvApiToken, getEnvSessionId, getMcpUrl, toPkgseerRegistry, toPkgseerRegistryLowercase };
package/dist/client.js CHANGED
@@ -1 +1 @@
1
- import{GrepGraphQLError2,GrepBackendError2,GrepAccessError2,GrepNetworkError2,MalformedGrepResponseError2,GrepServiceImpl2,ListAccessError2,ListGraphQLError2,ListBackendError2,ListNetworkError2,MalformedListResponseError2,ListServiceImpl2,ReadServiceImpl2,RefreshingGitHitsService2,ResolveTargetServiceImpl2,createStaticTokenProvider2,SessionIdConfigError2,getEnvSessionId2,createClientHeaderBuilder2}from"./shared/chunk-876mzceb.js";import{DEFAULT_MCP_URL2,DEFAULT_API_URL2,DEFAULT_CODE_NAV_URL2,getMcpUrl2,getApiUrl2,getCodeNavigationUrl2,getEnvApiToken2,PKGSEER_REGISTRY_LIST2,toPkgseerRegistry2,toPkgseerRegistryLowercase2,GitHitsServiceImpl2,CodeDiffError2,CodeNavigationServiceImpl2,PackageIntelligenceServiceImpl2}from"./shared/chunk-2tjd7frp.js";export{CodeDiffError2 as CodeDiffError,CodeNavigationServiceImpl2 as CodeNavigationServiceImpl,DEFAULT_API_URL2 as DEFAULT_API_URL,DEFAULT_CODE_NAV_URL2 as DEFAULT_CODE_NAV_URL,DEFAULT_MCP_URL2 as DEFAULT_MCP_URL,GitHitsServiceImpl2 as GitHitsServiceImpl,GrepAccessError2 as GrepAccessError,GrepBackendError2 as GrepBackendError,GrepGraphQLError2 as GrepGraphQLError,GrepNetworkError2 as GrepNetworkError,GrepServiceImpl2 as GrepServiceImpl,ListAccessError2 as ListAccessError,ListBackendError2 as ListBackendError,ListGraphQLError2 as ListGraphQLError,ListNetworkError2 as ListNetworkError,ListServiceImpl2 as ListServiceImpl,MalformedGrepResponseError2 as MalformedGrepResponseError,MalformedListResponseError2 as MalformedListResponseError,PKGSEER_REGISTRY_LIST2 as PKGSEER_REGISTRY_LIST,PackageIntelligenceServiceImpl2 as PackageIntelligenceServiceImpl,ReadServiceImpl2 as ReadServiceImpl,RefreshingGitHitsService2 as RefreshingGitHitsService,ResolveTargetServiceImpl2 as ResolveTargetServiceImpl,SessionIdConfigError2 as SessionIdConfigError,createClientHeaderBuilder2 as createClientHeaderBuilder,createStaticTokenProvider2 as createStaticTokenProvider,getApiUrl2 as getApiUrl,getCodeNavigationUrl2 as getCodeNavigationUrl,getEnvApiToken2 as getEnvApiToken,getEnvSessionId2 as getEnvSessionId,getMcpUrl2 as getMcpUrl,toPkgseerRegistry2 as toPkgseerRegistry,toPkgseerRegistryLowercase2 as toPkgseerRegistryLowercase};
1
+ import{GrepGraphQLError2,GrepBackendError2,GrepAccessError2,GrepNetworkError2,MalformedGrepResponseError2,GrepServiceImpl2,ListAccessError2,ListGraphQLError2,ListBackendError2,ListNetworkError2,MalformedListResponseError2,ListServiceImpl2,ReadServiceImpl2,RefreshingGitHitsService2,ResolveTargetServiceImpl2,createStaticTokenProvider2,SessionIdConfigError2,getEnvSessionId2,createClientHeaderBuilder2}from"./shared/chunk-a1w4dxpc.js";import{DEFAULT_MCP_URL2,DEFAULT_API_URL2,DEFAULT_CODE_NAV_URL2,getMcpUrl2,getApiUrl2,getCodeNavigationUrl2,getEnvApiToken2,GitHitsServiceImpl2,AGENTIC_ASK_REQUEST_TIMEOUT_MS2,AgenticAskServiceImpl2,PKGSEER_REGISTRY_LIST2,toPkgseerRegistry2,toPkgseerRegistryLowercase2,CodeDiffError2,CodeNavigationServiceImpl2,PackageIntelligenceServiceImpl2}from"./shared/chunk-j6q0y6f2.js";export{AGENTIC_ASK_REQUEST_TIMEOUT_MS2 as AGENTIC_ASK_REQUEST_TIMEOUT_MS,AgenticAskServiceImpl2 as AgenticAskServiceImpl,CodeDiffError2 as CodeDiffError,CodeNavigationServiceImpl2 as CodeNavigationServiceImpl,DEFAULT_API_URL2 as DEFAULT_API_URL,DEFAULT_CODE_NAV_URL2 as DEFAULT_CODE_NAV_URL,DEFAULT_MCP_URL2 as DEFAULT_MCP_URL,GitHitsServiceImpl2 as GitHitsServiceImpl,GrepAccessError2 as GrepAccessError,GrepBackendError2 as GrepBackendError,GrepGraphQLError2 as GrepGraphQLError,GrepNetworkError2 as GrepNetworkError,GrepServiceImpl2 as GrepServiceImpl,ListAccessError2 as ListAccessError,ListBackendError2 as ListBackendError,ListGraphQLError2 as ListGraphQLError,ListNetworkError2 as ListNetworkError,ListServiceImpl2 as ListServiceImpl,MalformedGrepResponseError2 as MalformedGrepResponseError,MalformedListResponseError2 as MalformedListResponseError,PKGSEER_REGISTRY_LIST2 as PKGSEER_REGISTRY_LIST,PackageIntelligenceServiceImpl2 as PackageIntelligenceServiceImpl,ReadServiceImpl2 as ReadServiceImpl,RefreshingGitHitsService2 as RefreshingGitHitsService,ResolveTargetServiceImpl2 as ResolveTargetServiceImpl,SessionIdConfigError2 as SessionIdConfigError,createClientHeaderBuilder2 as createClientHeaderBuilder,createStaticTokenProvider2 as createStaticTokenProvider,getApiUrl2 as getApiUrl,getCodeNavigationUrl2 as getCodeNavigationUrl,getEnvApiToken2 as getEnvApiToken,getEnvSessionId2 as getEnvSessionId,getMcpUrl2 as getMcpUrl,toPkgseerRegistry2 as toPkgseerRegistry,toPkgseerRegistryLowercase2 as toPkgseerRegistryLowercase};
package/dist/index.d.ts CHANGED
@@ -19,6 +19,32 @@ declare function buildMcpQuickStart(options?: BuildMcpQuickStartOptions): string
19
19
  */
20
20
  declare function buildMcpInstructions(options?: BuildMcpInstructionsOptions): string;
21
21
  import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
22
+ interface AgenticAskQuestion {
23
+ question: string;
24
+ }
25
+ type AgenticAskSubject = {
26
+ target?: string;
27
+ threadId?: never;
28
+ } | {
29
+ target?: never;
30
+ threadId: string;
31
+ };
32
+ type AgenticAskRequest = AgenticAskQuestion & AgenticAskSubject & {
33
+ sourceFormat?: "cli" | "mcp" | "url";
34
+ };
35
+ interface AgenticAskRequestOptions {
36
+ signal?: AbortSignal;
37
+ }
38
+ /** Expected backend envelope; successful JSON is deliberately not runtime-validated. */
39
+ interface AgenticAskResponse {
40
+ display_markdown: string;
41
+ tool_call_id?: string;
42
+ thread_id?: string;
43
+ [key: string]: unknown;
44
+ }
45
+ interface AgenticAskService {
46
+ ask(request: AgenticAskRequest, options?: AgenticAskRequestOptions): Promise<AgenticAskResponse>;
47
+ }
22
48
  declare const registryMap: {
23
49
  readonly npm: "NPM";
24
50
  readonly pypi: "PYPI";
@@ -59,6 +85,17 @@ interface ReadTarget {
59
85
  endLine?: number;
60
86
  }
61
87
  /**
88
+ * Optional per-call controls shared by network-backed service methods.
89
+ *
90
+ * `signal` is the caller's cancellation signal, such as an MCP request
91
+ * cancellation. Services combine it with their own request deadline: a caller
92
+ * abort rejects with the signal's reason and is never retried, while an
93
+ * internal deadline keeps each service's timeout error mapping.
94
+ */
95
+ interface ServiceRequestOptions {
96
+ signal?: AbortSignal;
97
+ }
98
+ /**
62
99
  * Back-compat alias — the canonical registry union now lives in
63
100
  * `src/shared/pkgseer-registry.ts`. Re-exported here so existing
64
101
  * consumers of `CodeNavigationRegistry` compile unchanged.
@@ -697,7 +734,7 @@ interface CodeNavigationService {
697
734
  }
698
735
  /** Additive client capability for the unpromoted CodeDiff surface. */
699
736
  interface CodeDiffService {
700
- codeDiff(params: CodeDiffParams): Promise<CodeDiffResult>;
737
+ codeDiff(params: CodeDiffParams, options?: ServiceRequestOptions): Promise<CodeDiffResult>;
701
738
  }
702
739
  /**
703
740
  * Parameters for search API call.
@@ -845,7 +882,7 @@ interface GrepResult {
845
882
  totalMatches: number;
846
883
  }
847
884
  interface GrepService {
848
- grep(params: GrepParams): Promise<GrepResult>;
885
+ grep(params: GrepParams, options?: ServiceRequestOptions): Promise<GrepResult>;
849
886
  }
850
887
  type ListFileIntent = "PRODUCTION" | "TEST" | "BENCHMARK" | "EXAMPLE" | "GENERATED" | "FIXTURE" | "BUILD" | "VENDOR";
851
888
  interface ListParams {
@@ -962,7 +999,7 @@ interface ListResult {
962
999
  preparation: ListSitePreparation | null;
963
1000
  }
964
1001
  interface ListService {
965
- list(params: ListParams): Promise<ListResult>;
1002
+ list(params: ListParams, options?: ServiceRequestOptions): Promise<ListResult>;
966
1003
  }
967
1004
  interface PackageSummaryParams {
968
1005
  registry: PkgseerRegistry;
@@ -1029,10 +1066,10 @@ interface PackageVulnerabilitiesParams {
1029
1066
  includeTransitive?: boolean;
1030
1067
  /** Optional internal breadth for advisory-wide transitive detail fields. */
1031
1068
  includeTransitiveAdvisoryDetails?: boolean;
1032
- /** Advisory rows to return for the root and opt-in transitive audit; direct counts always include all scopes. */
1069
+ /** Advisory rows to return. Summary counts always include all scopes. */
1033
1070
  advisoryScope?: VulnerabilityScope;
1034
1071
  }
1035
- type VulnerabilityScope = "AFFECTED" | "NON_AFFECTING" | "ALL";
1072
+ type VulnerabilityScope = "AFFECTED" | "NON_AFFECTING" | "UNKNOWN" | "ALL";
1036
1073
  interface PackageVersionIdentity {
1037
1074
  name: string;
1038
1075
  registry?: string;
@@ -1056,10 +1093,14 @@ interface VulnerabilityDetail {
1056
1093
  aliases?: string[];
1057
1094
  isMalicious?: boolean;
1058
1095
  affectsInspectedVersion?: boolean;
1096
+ assessmentStatus?: string;
1097
+ assessmentReasons?: string[];
1059
1098
  matchedAffectedVersionRanges?: string[];
1060
1099
  duplicateIds?: string[];
1061
1100
  }
1062
1101
  interface VulnerabilitySecurityDetails {
1102
+ unknownVulnerabilityCount?: number;
1103
+ assessmentStatus?: string;
1063
1104
  affectedVulnerabilityCount: number;
1064
1105
  nonAffectingVulnerabilityCount: number;
1065
1106
  allVulnerabilityCount: number;
@@ -1072,7 +1113,13 @@ interface VulnerabilityReport {
1072
1113
  security?: VulnerabilitySecurityDetails;
1073
1114
  transitive?: TransitiveVulnerabilityAudit;
1074
1115
  }
1075
- interface TransitiveVulnerabilityAudit {
1116
+ interface TransitiveVulnerabilityAuditCounts {
1117
+ affectedCount: number;
1118
+ nonAffectingCount: number;
1119
+ unknownCount: number;
1120
+ totalCount: number;
1121
+ }
1122
+ interface TransitiveVulnerabilityAudit extends TransitiveVulnerabilityAuditCounts {
1076
1123
  /** Advisory scope applied to dependency-package occurrences. */
1077
1124
  advisoryScope: VulnerabilityScope;
1078
1125
  /** Number of resolved package-version graph nodes checked. */
@@ -1084,7 +1131,7 @@ interface TransitiveVulnerabilityAudit {
1084
1131
  calculatedAt?: string;
1085
1132
  packages: TransitiveVulnerabilityAuditPackage[];
1086
1133
  }
1087
- interface TransitiveVulnerabilityAuditPackage {
1134
+ interface TransitiveVulnerabilityAuditPackage extends TransitiveVulnerabilityAuditCounts {
1088
1135
  registry: string;
1089
1136
  name: string;
1090
1137
  occurrenceCount: number;
@@ -1144,6 +1191,8 @@ interface PackageUpgradeReviewParams {
1144
1191
  minSeverity?: number;
1145
1192
  }
1146
1193
  interface PackageUpgradeAdvisorySummary {
1194
+ assessmentStatus?: string;
1195
+ assessmentReasons?: string[];
1147
1196
  id?: string;
1148
1197
  aliases: string[];
1149
1198
  summary?: string;
@@ -1153,6 +1202,8 @@ interface PackageUpgradeAdvisorySummary {
1153
1202
  isMalicious?: boolean;
1154
1203
  }
1155
1204
  interface PackageUpgradeVersionVulnerabilitySummary {
1205
+ unknownVulnerabilityCount?: number;
1206
+ assessmentStatus?: string;
1156
1207
  version: string;
1157
1208
  publishedAt?: string;
1158
1209
  deprecated?: boolean;
@@ -1268,6 +1319,12 @@ interface PackageUpgradeDependencyIssues {
1268
1319
  introducedConflicts: string[];
1269
1320
  introducedOutdated: string[];
1270
1321
  }
1322
+ interface PackageUpgradeUnknownEvidence {
1323
+ section: string;
1324
+ code: string;
1325
+ message: string;
1326
+ retryable?: boolean;
1327
+ }
1271
1328
  interface PackageUpgradeReview {
1272
1329
  registry: string;
1273
1330
  name: string;
@@ -1280,7 +1337,9 @@ interface PackageUpgradeReview {
1280
1337
  compatibility?: PackageUpgradeCompatibility;
1281
1338
  dependencyChanges?: PackageUpgradeDependencyChanges;
1282
1339
  dependencyIssues?: PackageUpgradeDependencyIssues;
1340
+ /** Compatibility field derived from unknownDetails, never selected separately. */
1283
1341
  unknowns: string[];
1342
+ unknownDetails?: PackageUpgradeUnknownEvidence[];
1284
1343
  }
1285
1344
  interface PackageUpgradeReviewResponse {
1286
1345
  summary: {
@@ -1400,6 +1459,8 @@ interface VulnerabilitySummaryDetail {
1400
1459
  isMalicious?: boolean;
1401
1460
  }
1402
1461
  interface TransitiveDependencyVulnerability {
1462
+ assessmentStatus?: string;
1463
+ assessmentReasons?: string[];
1403
1464
  version: string;
1404
1465
  affectsResolvedVersion: boolean;
1405
1466
  matchedAffectedVersionRanges: string[];
@@ -1701,14 +1762,14 @@ interface PackageDocResult {
1701
1762
  page?: PackageDocPage;
1702
1763
  }
1703
1764
  interface PackageIntelligenceService {
1704
- packageSummary(params: PackageSummaryParams): Promise<PackageSummary>;
1705
- packageVulnerabilities(params: PackageVulnerabilitiesParams): Promise<VulnerabilityReport>;
1706
- packageDependencies(params: PackageDependenciesParams): Promise<DependencyReport>;
1707
- packageUpgradeDependencyProbe(params: PackageUpgradeDependencyProbeParams): Promise<DependencyReport>;
1708
- packageUpgradeReview(params: PackageUpgradeReviewParams): Promise<PackageUpgradeReviewResponse>;
1709
- packageChangelog(params: PackageChangelogParams): Promise<ChangelogReport>;
1710
- listPackageDocs(params: ListPackageDocsParams): Promise<PackageDocsList>;
1711
- readPackageDoc(params: ReadPackageDocParams): Promise<PackageDocResult>;
1765
+ packageSummary(params: PackageSummaryParams, options?: ServiceRequestOptions): Promise<PackageSummary>;
1766
+ packageVulnerabilities(params: PackageVulnerabilitiesParams, options?: ServiceRequestOptions): Promise<VulnerabilityReport>;
1767
+ packageDependencies(params: PackageDependenciesParams, options?: ServiceRequestOptions): Promise<DependencyReport>;
1768
+ packageUpgradeDependencyProbe(params: PackageUpgradeDependencyProbeParams, options?: ServiceRequestOptions): Promise<DependencyReport>;
1769
+ packageUpgradeReview(params: PackageUpgradeReviewParams, options?: ServiceRequestOptions): Promise<PackageUpgradeReviewResponse>;
1770
+ packageChangelog(params: PackageChangelogParams, options?: ServiceRequestOptions): Promise<ChangelogReport>;
1771
+ listPackageDocs(params: ListPackageDocsParams, options?: ServiceRequestOptions): Promise<PackageDocsList>;
1772
+ readPackageDoc(params: ReadPackageDocParams, options?: ServiceRequestOptions): Promise<PackageDocResult>;
1712
1773
  }
1713
1774
  interface ReadParams {
1714
1775
  target: string;
@@ -1759,7 +1820,7 @@ interface ReadSymbolResolutionResult {
1759
1820
  }
1760
1821
  type ReadResult = ReadCodeResult | ReadDocsResult | ReadSymbolResolutionResult;
1761
1822
  interface ReadService {
1762
- read(params: ReadParams): Promise<ReadResult>;
1823
+ read(params: ReadParams, options?: ServiceRequestOptions): Promise<ReadResult>;
1763
1824
  }
1764
1825
  type ResolveTargetKind = "PACKAGE" | "REPOSITORY" | "SITE";
1765
1826
  type KnownLatestVersionMaliciousStatus = "NOT_APPLICABLE" | "CLEAR" | "AFFECTED" | "UNKNOWN";
@@ -1835,7 +1896,7 @@ interface ResolveTargetResult {
1835
1896
  ambiguousReason: string;
1836
1897
  }
1837
1898
  interface ResolveTargetService {
1838
- resolveTarget(params: ResolveTargetParams): Promise<ResolveTargetResult>;
1899
+ resolveTarget(params: ResolveTargetParams, options?: ServiceRequestOptions): Promise<ResolveTargetResult>;
1839
1900
  }
1840
1901
  import { z as z3 } from "zod";
1841
1902
  /** Annotation fields required by OpenAI's MCP marketplace validation. */
@@ -1892,6 +1953,8 @@ interface McpToolServices {
1892
1953
  readService: ReadService;
1893
1954
  grepService: GrepService;
1894
1955
  resolveTargetService: ResolveTargetService;
1956
+ /** Research over the GitHits REST API; answers can take a few minutes. */
1957
+ agenticAskService: AgenticAskService;
1895
1958
  }
1896
1959
  interface McpServerMetadata {
1897
1960
  name: string;