@githits/mcp 0.34.0 → 0.36.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
@@ -157,7 +157,7 @@ boundary is authenticated and reached.
157
157
 
158
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.
159
159
 
160
- Servers can pass an optional `progress` hook to `createMcpServer()` or `registerMcpTools()` to forward live status for `research` and `get_example`. It is used only when the client sends a progress token (including `0`); updates become `notifications/progress` and stop before the tool returns. `RelayReceiver` is the bundled hook: it receives GitHits operation progress over one shared WebSocket, authorized either by the caller's own GitHits token (`{ kind: "caller", getToken }`) or by a service credential supplied at runtime (`{ kind: "service", serviceId, key }`). The package ships no credentials. Progress is best effort: if it is unavailable or rejected, the tool runs unchanged, resending a rejected request once without progress, and the final result is always authoritative. Call `close()` on shutdown.
160
+ Servers can pass an optional `progress` hook to `createMcpServer()` or `registerMcpTools()` to forward live status for `research` and `get_example`. It is used only when the client sends a progress token (including `0`); updates become `notifications/progress` and stop before the tool returns. `RelayReceiver` is the bundled hook: it receives GitHits operation progress over one shared WebSocket, authorized either by the caller's own GitHits token (`{ kind: "caller", getToken }`) or by a service credential supplied at runtime (`{ kind: "service", serviceId, key }`). The package ships no credentials. Calls never wait for the progress connection: the receiver chooses its relay ID locally and connects in the background, so updates published before it is ready are skipped. Progress is best effort: if it is unavailable or rejected, the tool runs unchanged, resending a rejected request once without progress, and the final result is always authoritative. Call `close()` on shutdown. With a `progress` hook, messages are also animated locally with the GitHits narrowing mark (`narrowingFrame` / `narrowingText`); set `progressAnimation: false` to disable it or `{ intervalMs }` to change the frame rate. Frames are generated by the MCP server and sent only to that call's client.
161
161
 
162
162
  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.
163
163
 
package/dist/client.d.ts CHANGED
@@ -271,6 +271,8 @@ interface TargetResolutionIdentity {
271
271
  commitSha?: string;
272
272
  /** Verified UTC committer time for this exact repository commit, not freshness. */
273
273
  committedAt?: string;
274
+ /** Backend package/source assessment, independent of index freshness. */
275
+ releaseCorrespondence?: string | null;
274
276
  site?: string;
275
277
  }
276
278
  type AvailableRef = AvailableVersion;
@@ -714,6 +716,8 @@ interface CodeDiffRefResolution {
714
716
  commitSha: string;
715
717
  refKind: CodeDiffRefKind;
716
718
  versionSource?: CodeDiffVersionSource;
719
+ /** Backend assessment for this exact comparison side, independent of execution. */
720
+ releaseCorrespondence?: string | null;
717
721
  }
718
722
  interface RawCodeDiffSummary {
719
723
  filesChanged: number;
@@ -1131,7 +1135,30 @@ interface GrepUnavailableTarget {
1131
1135
  progressRef: string | null;
1132
1136
  suggestedSiteTargets: string[] | null;
1133
1137
  }
1138
+ /** An unverified backend-authored alternative; never applied by the client. */
1139
+ interface GrepPathSuggestion {
1140
+ target: string;
1141
+ path: string;
1142
+ }
1143
+ /** Snapshot-backed path diagnosis, independent of matches and coverage failures. */
1144
+ interface GrepPathWarning {
1145
+ requestedInputIndices: number[];
1146
+ target: string;
1147
+ path: string;
1148
+ repositorySubpath: string;
1149
+ message: string;
1150
+ suggestions: GrepPathSuggestion[];
1151
+ }
1152
+ /** Canonical source provenance for one known original package/repository input. */
1153
+ interface GrepInputTargetResolution {
1154
+ inputIndex: number;
1155
+ target: string;
1156
+ targetResolution: TargetResolution;
1157
+ }
1134
1158
  interface GrepResult {
1159
+ /** Required on wire results; optional for existing injected service providers. */
1160
+ targetResolutions?: GrepInputTargetResolution[];
1161
+ pathWarnings: GrepPathWarning[];
1135
1162
  indexingEstimates?: DiscoveryIndexingEstimate[];
1136
1163
  hits: GrepHit[];
1137
1164
  targets: GrepTargetStatus[];
@@ -1241,6 +1268,8 @@ interface ListTargetIdentity {
1241
1268
  gitRef: string | null;
1242
1269
  commitSha?: string | null;
1243
1270
  committedAt?: string | null;
1271
+ /** Backend package/source assessment, independent of index freshness. */
1272
+ releaseCorrespondence?: string | null;
1244
1273
  }
1245
1274
  interface ListTargetResolution {
1246
1275
  requested: ListTargetIdentity | null;
@@ -2349,4 +2378,4 @@ declare class ResolveTargetServiceImpl implements ResolveTargetService {
2349
2378
  resolveTarget(params: ResolveTargetParams, options?: ServiceRequestOptions): Promise<ResolveTargetResult>;
2350
2379
  private executeResolveTarget;
2351
2380
  }
2352
- 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, RegistryRepository, ResolveTargetKind, ResolveTargetLatestVersionMaliciousAdvisory, ResolveTargetLatestVersionMaliciousEvidence, ResolveTargetMatch, ResolveTargetParams, ResolveTargetReference, ResolveTargetResult, ResolveTargetService, ResolveTargetServiceImpl, ResolveTargetTarget, ServiceDiagnostics, ServiceRequestOptions, SessionIdConfigError, TokenProvider, createClientHeaderBuilder, createStaticTokenProvider, getApiUrl, getCodeNavigationUrl, getEnvApiToken, getEnvSessionId, getMcpUrl, toPkgseerRegistry, toPkgseerRegistryLowercase };
2381
+ 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, GrepInputTargetResolution, GrepLineSlice, GrepNetworkError, GrepParams, GrepPathSelector, GrepPathSuggestion, GrepPathWarning, 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, RegistryRepository, 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-jemh0eym.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-1bad2znr.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};
1
+ import{GrepGraphQLError2,GrepBackendError2,GrepAccessError2,GrepNetworkError2,MalformedGrepResponseError2,GrepServiceImpl2,ListAccessError2,ListGraphQLError2,ListBackendError2,ListNetworkError2,MalformedListResponseError2,ListServiceImpl2,ReadServiceImpl2,RefreshingGitHitsService2,ResolveTargetServiceImpl2,createStaticTokenProvider2,SessionIdConfigError2,getEnvSessionId2,createClientHeaderBuilder2}from"./shared/chunk-33zcd460.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-jatk4vrs.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
@@ -164,6 +164,8 @@ interface TargetResolutionIdentity {
164
164
  commitSha?: string;
165
165
  /** Verified UTC committer time for this exact repository commit, not freshness. */
166
166
  committedAt?: string;
167
+ /** Backend package/source assessment, independent of index freshness. */
168
+ releaseCorrespondence?: string | null;
167
169
  site?: string;
168
170
  }
169
171
  type AvailableRef = AvailableVersion;
@@ -607,6 +609,8 @@ interface CodeDiffRefResolution {
607
609
  commitSha: string;
608
610
  refKind: CodeDiffRefKind;
609
611
  versionSource?: CodeDiffVersionSource;
612
+ /** Backend assessment for this exact comparison side, independent of execution. */
613
+ releaseCorrespondence?: string | null;
610
614
  }
611
615
  interface RawCodeDiffSummary {
612
616
  filesChanged: number;
@@ -890,7 +894,30 @@ interface GrepUnavailableTarget {
890
894
  progressRef: string | null;
891
895
  suggestedSiteTargets: string[] | null;
892
896
  }
897
+ /** An unverified backend-authored alternative; never applied by the client. */
898
+ interface GrepPathSuggestion {
899
+ target: string;
900
+ path: string;
901
+ }
902
+ /** Snapshot-backed path diagnosis, independent of matches and coverage failures. */
903
+ interface GrepPathWarning {
904
+ requestedInputIndices: number[];
905
+ target: string;
906
+ path: string;
907
+ repositorySubpath: string;
908
+ message: string;
909
+ suggestions: GrepPathSuggestion[];
910
+ }
911
+ /** Canonical source provenance for one known original package/repository input. */
912
+ interface GrepInputTargetResolution {
913
+ inputIndex: number;
914
+ target: string;
915
+ targetResolution: TargetResolution;
916
+ }
893
917
  interface GrepResult {
918
+ /** Required on wire results; optional for existing injected service providers. */
919
+ targetResolutions?: GrepInputTargetResolution[];
920
+ pathWarnings: GrepPathWarning[];
894
921
  indexingEstimates?: DiscoveryIndexingEstimate[];
895
922
  hits: GrepHit[];
896
923
  targets: GrepTargetStatus[];
@@ -961,6 +988,8 @@ interface ListTargetIdentity {
961
988
  gitRef: string | null;
962
989
  commitSha?: string | null;
963
990
  committedAt?: string | null;
991
+ /** Backend package/source assessment, independent of index freshness. */
992
+ releaseCorrespondence?: string | null;
964
993
  }
965
994
  interface ListTargetResolution {
966
995
  requested: ListTargetIdentity | null;
@@ -1930,6 +1959,8 @@ interface McpProgressUpdate {
1930
1959
  progress: number;
1931
1960
  /** Fixed, server-allowlisted status text. */
1932
1961
  message: string;
1962
+ /** Coarse backend stage, such as `searching` or `reading`, when provided. */
1963
+ stage?: string;
1933
1964
  }
1934
1965
  /** One correlated backend call; `end()` stops delivery before the result returns. */
1935
1966
  interface McpProgressOperation extends ProgressRequest {
@@ -1978,13 +2009,9 @@ interface RelayReceiverOptions {
1978
2009
  createSocket?: (url: string) => RelaySocket;
1979
2010
  /** Extra headers for relay setup requests, such as client attribution. */
1980
2011
  clientHeaders?: () => Record<string, string>;
1981
- /** Longest a call waits for an existing relay's socket before proceeding. */
2012
+ /** @deprecated Ignored: calls never wait for the relay socket. */
1982
2013
  connectWaitMs?: number;
1983
- /**
1984
- * Longest a call waits while the first relay is minted and its socket opens.
1985
- * Minting takes about a second, so a shorter wait would skip progress for the
1986
- * first call of every process.
1987
- */
2014
+ /** @deprecated Ignored: calls never wait for the relay socket. */
1988
2015
  firstConnectWaitMs?: number;
1989
2016
  /** Close an unused socket after this long. */
1990
2017
  idleCloseMs?: number;
@@ -1999,15 +2026,19 @@ interface RelayReceiverOptions {
1999
2026
  * Receives backend operation progress over one shared WebSocket and routes it
2000
2027
  * to the MCP call that supplied each operation ID.
2001
2028
  *
2002
- * Every failure degrades to "no progress": relay setup errors back off, socket
2003
- * drops reconnect in the background, and late or unknown events are dropped.
2029
+ * Calls never wait for the relay. The relay ID is chosen locally, so a call's
2030
+ * progress headers are known immediately; minting the receive URL and opening
2031
+ * the socket run in the background, and updates are delivered once the socket
2032
+ * joins. Updates published before that are missed, which only affects the
2033
+ * first call of a process. Every failure degrades to "no progress": relay setup
2034
+ * errors back off, socket drops reconnect in the background, and late or
2035
+ * unknown events are dropped.
2004
2036
  */
2005
2037
  declare class RelayReceiver implements McpProgressHook {
2006
2038
  private readonly options;
2007
2039
  private readonly fetchFn;
2008
2040
  private readonly createSocket;
2009
- private readonly connectWaitMs;
2010
- private readonly firstConnectWaitMs;
2041
+ private readonly relayId;
2011
2042
  private readonly idleCloseMs;
2012
2043
  private readonly reconnectBaseMs;
2013
2044
  private readonly minRenewDelayMs;
@@ -2025,6 +2056,11 @@ declare class RelayReceiver implements McpProgressHook {
2025
2056
  private closed;
2026
2057
  constructor(options: RelayReceiverOptions);
2027
2058
  begin(notify: (update: McpProgressUpdate) => void): Promise<McpProgressOperation | undefined>;
2059
+ /**
2060
+ * Starts minting and connecting in the background before the first call,
2061
+ * for hosts that know a progress call is about to start. Never waits.
2062
+ */
2063
+ warm(): void;
2028
2064
  /** Stops all timers and closes the socket; later calls get no progress. */
2029
2065
  close(): void;
2030
2066
  private ensureConnected;
@@ -2034,6 +2070,7 @@ declare class RelayReceiver implements McpProgressHook {
2034
2070
  /** A socket that cannot open (e.g. a proxy blocking WebSockets) backs off. */
2035
2071
  private socketFailed;
2036
2072
  private deliver;
2073
+ /** Mints a receive URL for this receiver's locally chosen relay ID. */
2037
2074
  private setup;
2038
2075
  private authHeaders;
2039
2076
  private serviceHeaders;
@@ -2046,7 +2083,14 @@ declare class RelayReceiver implements McpProgressHook {
2046
2083
  private detach;
2047
2084
  private clearTimer;
2048
2085
  }
2049
- import { z as z3 } from "zod";
2086
+ /** Local animation of MCP progress messages; `false` disables it. */
2087
+ interface McpProgressAnimationOptions {
2088
+ /** Time between frames. Hosts render each frame as a notification. */
2089
+ intervalMs?: number;
2090
+ }
2091
+ /** Backend stage covered by the opening message. */
2092
+ declare const OPENING_STAGE = "started";
2093
+ import { z as z4 } from "zod";
2050
2094
  /** Annotation fields required by OpenAI's MCP marketplace validation. */
2051
2095
  interface CompleteToolAnnotations {
2052
2096
  title?: string;
@@ -2071,8 +2115,11 @@ interface ToolProgressOperation extends ProgressRequest {
2071
2115
  }
2072
2116
  /** Progress already bound to the current MCP request's progress token. */
2073
2117
  interface ToolProgress {
2074
- /** Returns `undefined` when progress is unavailable; run without it then. */
2075
- begin(): Promise<ToolProgressOperation | undefined>;
2118
+ /**
2119
+ * Starts progress for one backend call, showing `initialMessage` until the
2120
+ * first live update. Returns `undefined` when progress is unavailable.
2121
+ */
2122
+ begin(initialMessage?: string): Promise<ToolProgressOperation | undefined>;
2076
2123
  }
2077
2124
  /** Host-provided execution state shared by MCP and direct tool callers. */
2078
2125
  interface ToolExecutionContext {
@@ -2096,7 +2143,7 @@ type ToolResult = {
2096
2143
  * Zod raw shape type (what MCP SDK expects)
2097
2144
  */
2098
2145
  type ZodRawShape = {
2099
- [k: string]: z3.ZodTypeAny;
2146
+ [k: string]: z4.ZodTypeAny;
2100
2147
  };
2101
2148
  /**
2102
2149
  * Services required to construct the MCP tool surface.
@@ -2143,6 +2190,11 @@ interface CreateMcpServerOptions<TExtra = unknown> {
2143
2190
  traceTool?: McpToolExecutionHook;
2144
2191
  /** Optional progress source; used only when the client sends a progress token. */
2145
2192
  progress?: McpProgressHook;
2193
+ /**
2194
+ * Animates progress messages locally with the GitHits narrowing mark.
2195
+ * Defaults to on (500 ms frames) when `progress` is set; `false` disables.
2196
+ */
2197
+ progressAnimation?: McpProgressAnimationOptions | boolean;
2146
2198
  }
2147
2199
  interface McpToolDescriptor<TSchema extends ZodRawShape = ZodRawShape> {
2148
2200
  name: string;
@@ -2157,9 +2209,38 @@ declare function registerMcpTools<TExtra = unknown>(server: McpServer, options:
2157
2209
  services: McpToolServicesProvider<TExtra>;
2158
2210
  traceTool?: McpToolExecutionHook;
2159
2211
  progress?: McpProgressHook;
2212
+ progressAnimation?: McpProgressAnimationOptions | boolean;
2160
2213
  }): void;
2161
2214
  /**
2162
2215
  * Creates the transport-neutral MCP server with injected services.
2163
2216
  */
2164
2217
  declare function createMcpServer<TExtra = unknown>(options: CreateMcpServerOptions<TExtra>): McpServer;
2165
- export { BuildMcpInstructionsOptions, BuildMcpQuickStartOptions, CreateMcpServerOptions, McpAuthAction, McpAuthActionContext, McpProgressHook, McpProgressOperation, McpProgressUpdate, McpRequestContext, McpServerMetadata, McpToolDescriptor, McpToolExecutionHook, McpToolServices, McpToolServicesProvider, RelayAuth, RelayReceiver, RelayReceiverOptions, RelaySocket, ToolExecutionContext, ToolTermsRemediation, buildMcpInstructions, buildMcpQuickStart, createMcpServer, getMcpToolDescriptors, registerMcpTools };
2218
+ /**
2219
+ * "Narrowing scatter" progress mark: candidate dots converge on one precise
2220
+ * hit, mirroring how research narrows from many sources to specific files and
2221
+ * symbols. Drawn with braille cells (2x4 dots each) so it renders as plain
2222
+ * text in terminals and MCP hosts.
2223
+ */
2224
+ /** One rendered braille cell; `tone` runs from 0 (dim candidate) to 1 (hit). */
2225
+ interface NarrowingCell {
2226
+ char: string;
2227
+ tone: number;
2228
+ }
2229
+ interface NarrowingFrameOptions {
2230
+ /** Width in braille cells. */
2231
+ width?: number;
2232
+ /** Frames per converge-and-hit cycle. */
2233
+ period?: number;
2234
+ /**
2235
+ * How far the run has narrowed, from 0 (just started) to 1 (answer ready).
2236
+ * Later stages start each cycle from a tighter cluster; 1 holds the hit.
2237
+ */
2238
+ focus?: number;
2239
+ }
2240
+ /** Renders frame `frame` of the narrowing mark. */
2241
+ declare function narrowingFrame(frame: number, options?: NarrowingFrameOptions): NarrowingCell[];
2242
+ /** Plain-text frame for hosts without colour, such as MCP clients. */
2243
+ declare function narrowingText(frame: number, options?: NarrowingFrameOptions): string;
2244
+ /** How far a backend progress stage has narrowed the work, for `focus`. */
2245
+ declare function focusForStage(stage: string | undefined): number;
2246
+ export { BuildMcpInstructionsOptions, BuildMcpQuickStartOptions, CreateMcpServerOptions, McpAuthAction, McpAuthActionContext, McpProgressAnimationOptions, McpProgressHook, McpProgressOperation, McpProgressUpdate, McpRequestContext, McpServerMetadata, McpToolDescriptor, McpToolExecutionHook, McpToolServices, McpToolServicesProvider, NarrowingCell, NarrowingFrameOptions, OPENING_STAGE, RelayAuth, RelayReceiver, RelayReceiverOptions, RelaySocket, ToolExecutionContext, ToolTermsRemediation, buildMcpInstructions, buildMcpQuickStart, createMcpServer, focusForStage, getMcpToolDescriptors, narrowingFrame, narrowingText, registerMcpTools };