@openhoo/hoopilot 1.0.0 → 1.2.0

package/dist/index.d.cts

@@ -15,12 +15,25 @@ declare class MetricsRegistry {
     startRequest(): void;
     /** Record a completed request and clear its in-flight slot. */
     observe(observation: RequestObservation): void;
+    /**
+     * Record whether one upstream completion reported token usage. `missing`
+     * counts responses that carried no usage object — most often streamed Chat
+     * Completions sent without `stream_options: {"include_usage": true}` — so a
+     * rising miss rate flags clients whose token usage is going unaccounted.
+     */
+    recordTokenExtraction(extracted: boolean): void;
     /** Accumulate token counts for a model from one upstream completion. */
     recordTokens(model: string, usage: TokenUsage): void;
     /** Record one upstream Copilot call and whether it succeeded. */
     recordUpstream(path: string, ok: boolean): void;
     /** Store the latest Copilot quota so /metrics can expose it as gauges. */
     recordCopilotQuota(usage: CopilotUsage): void;
+    /**
+     * Store the latest GitHub REST rate-limit budget, keyed by its resource bucket.
+     * A no-op when `rateLimit` is undefined (the response carried no rate-limit
+     * headers) so callers can pass {@link parseRateLimitHeaders} output directly.
+     */
+    recordGithubRateLimit(rateLimit: GithubRateLimit | undefined): void;
     /** A JSON-friendly view of the current counters. */
     snapshot(now?: () => number): MetricsSnapshot;
     /** Render the Prometheus text exposition format (version 0.0.4). */
@@ -37,7 +50,7 @@ declare class MetricsRegistry {
  * branch; combined with the runtime cancelling the client branch, that releases
  * the shared upstream connection instead of draining it in the background.
  */
-declare function observeResponseUsage(response: Response, fallbackModel: string, onUsage: (model: string, usage: TokenUsage) => void, signal?: AbortSignal): Response;
+declare function observeResponseUsage(response: Response, fallbackModel: string, onUsage: (model: string, usage: TokenUsage) => void, signal?: AbortSignal, onOutcome?: (extracted: boolean) => void): Response;
 
 type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 interface Logger {
@@ -149,8 +162,40 @@ interface CopilotUsage {
     quotaResetDate?: string;
     quotas: Record<string, CopilotQuota>;
 }
+/**
+ * GitHub REST API rate-limit budget parsed from the `x-ratelimit-*` headers that
+ * `api.github.com` returns on every response. Hoopilot reads these off the
+ * `copilot_internal/user` quota call it already makes, so the proxy's GitHub API
+ * usage is visible without spending an extra request.
+ */
+interface GithubRateLimit {
+    /** `x-ratelimit-resource` — the bucket the request counted against (e.g. `core`). */
+    resource: string;
+    /** `x-ratelimit-limit` — maximum requests allowed in the current window. */
+    limit?: number;
+    /** `x-ratelimit-remaining` — requests left in the current window. */
+    remaining?: number;
+    /** `x-ratelimit-used` — requests already spent in the current window. */
+    used?: number;
+    /** `x-ratelimit-reset` — Unix epoch seconds when the window resets. */
+    resetEpochSeconds?: number;
+    /** `retry-after` — seconds to wait, present on 429 / secondary-limit responses. */
+    retryAfterSeconds?: number;
+    /** Wall-clock epoch ms when these values were observed. */
+    observedAtMs: number;
+}
+/** JSON view of one GitHub rate-limit resource, as rendered into a snapshot. */
+interface GithubRateLimitSnapshot {
+    limit?: number;
+    observedAt: string;
+    remaining?: number;
+    resetAt?: string;
+    retryAfterSeconds?: number;
+    used?: number;
+}
 /** A point-in-time JSON view of the in-process metrics. */
 interface MetricsSnapshot {
+    githubRateLimit: Record<string, GithubRateLimitSnapshot>;
     inFlight: number;
     requests: {
         byRoute: Record<string, number>;
@@ -162,6 +207,10 @@ interface MetricsSnapshot {
         byModel: Record<string, ModelTokenTotals>;
         cached: number;
         completion: number;
+        extraction: {
+            extracted: number;
+            missing: number;
+        };
         prompt: number;
         reasoning: number;
         total: number;
@@ -227,6 +276,15 @@ declare function applyCopilotHeaders(headers: Headers, token: string): Headers;
  * Copilot completion endpoints.
  */
 declare function applyGithubApiHeaders(headers: Headers, token: string): Headers;
+/**
+ * Parse the GitHub REST `x-ratelimit-*` headers (plus `retry-after`) off a
+ * response into a {@link GithubRateLimit}. `api.github.com` returns these on
+ * every reply, so the proxy reads its GitHub API budget from the quota call it
+ * already makes — no extra request is spent. Returns undefined when the response
+ * carries no rate-limit headers (for example the Copilot completion host, which
+ * does not emit them today) so callers record nothing rather than a phantom row.
+ */
+declare function parseRateLimitHeaders(headers: Headers, nowMs?: number): GithubRateLimit | undefined;
 declare class CopilotClient {
     #private;
     constructor(options?: CopilotAuthOptions);
@@ -309,4 +367,4 @@ declare function extractTokenUsage(usage: unknown): TokenUsage | undefined;
 declare function createHoopilotHandler(options?: HoopilotServerOptions): (request: Request) => Promise<Response>;
 declare function startHoopilotServer(options?: HoopilotServerOptions): StartedHoopilotServer;
 
-export { AnthropicCompatibilityError, COPILOT_USAGE_API_VERSION, type CopilotAccess, CopilotAuth, CopilotAuthError, type CopilotAuthOptions, CopilotClient, type CopilotQuota, type CopilotUsage, DEFAULT_GITHUB_API_BASE_URL, DEFAULT_LOG_FORMAT, DEFAULT_LOG_LEVEL, DEFAULT_MODEL, type FetchLike, type HoopilotLogger, type HoopilotLoggerOptions, type HoopilotServerOptions, type JsonObject, type LogFields, type LogFormat, type LogLevel, type LogMethod, type Logger, MetricsRegistry, type MetricsSnapshot, type ModelTokenTotals, PROMETHEUS_CONTENT_TYPE, type RequestObservation, type StartedHoopilotServer, type TokenUsage, anthropicMessagesToResponsesRequest, applyCopilotHeaders, applyGithubApiHeaders, authStorePath, chatCompletionToCompletion, chatCompletionToResponse, completionStreamFromChatStream, completionsRequestToChatCompletion, createHoopilotHandler, createHoopilotLogger, estimateAnthropicMessageTokens, extractTokenUsage, fallbackModels, githubCopilotDeviceLogin, noopLogger, normalizeChatCompletionRequest, normalizeCopilotUsage, normalizeModelsResponse, normalizeRequestedModel, observeResponseUsage, parseLogFormat, parseLogLevel, readStoredCopilotAuth, responsesCompactionResult, responsesRequestToChatCompletion, responsesResponseToAnthropicMessage, responsesStreamFromChatStream, responsesStreamToAnthropicStream, startHoopilotServer, writeStoredCopilotAuth };
+export { AnthropicCompatibilityError, COPILOT_USAGE_API_VERSION, type CopilotAccess, CopilotAuth, CopilotAuthError, type CopilotAuthOptions, CopilotClient, type CopilotQuota, type CopilotUsage, DEFAULT_GITHUB_API_BASE_URL, DEFAULT_LOG_FORMAT, DEFAULT_LOG_LEVEL, DEFAULT_MODEL, type FetchLike, type GithubRateLimit, type GithubRateLimitSnapshot, type HoopilotLogger, type HoopilotLoggerOptions, type HoopilotServerOptions, type JsonObject, type LogFields, type LogFormat, type LogLevel, type LogMethod, type Logger, MetricsRegistry, type MetricsSnapshot, type ModelTokenTotals, PROMETHEUS_CONTENT_TYPE, type RequestObservation, type StartedHoopilotServer, type TokenUsage, anthropicMessagesToResponsesRequest, applyCopilotHeaders, applyGithubApiHeaders, authStorePath, chatCompletionToCompletion, chatCompletionToResponse, completionStreamFromChatStream, completionsRequestToChatCompletion, createHoopilotHandler, createHoopilotLogger, estimateAnthropicMessageTokens, extractTokenUsage, fallbackModels, githubCopilotDeviceLogin, noopLogger, normalizeChatCompletionRequest, normalizeCopilotUsage, normalizeModelsResponse, normalizeRequestedModel, observeResponseUsage, parseLogFormat, parseLogLevel, parseRateLimitHeaders, readStoredCopilotAuth, responsesCompactionResult, responsesRequestToChatCompletion, responsesResponseToAnthropicMessage, responsesStreamFromChatStream, responsesStreamToAnthropicStream, startHoopilotServer, writeStoredCopilotAuth };

package/dist/index.d.ts

@@ -15,12 +15,25 @@ declare class MetricsRegistry {
     startRequest(): void;
     /** Record a completed request and clear its in-flight slot. */
     observe(observation: RequestObservation): void;
+    /**
+     * Record whether one upstream completion reported token usage. `missing`
+     * counts responses that carried no usage object — most often streamed Chat
+     * Completions sent without `stream_options: {"include_usage": true}` — so a
+     * rising miss rate flags clients whose token usage is going unaccounted.
+     */
+    recordTokenExtraction(extracted: boolean): void;
     /** Accumulate token counts for a model from one upstream completion. */
     recordTokens(model: string, usage: TokenUsage): void;
     /** Record one upstream Copilot call and whether it succeeded. */
     recordUpstream(path: string, ok: boolean): void;
     /** Store the latest Copilot quota so /metrics can expose it as gauges. */
     recordCopilotQuota(usage: CopilotUsage): void;
+    /**
+     * Store the latest GitHub REST rate-limit budget, keyed by its resource bucket.
+     * A no-op when `rateLimit` is undefined (the response carried no rate-limit
+     * headers) so callers can pass {@link parseRateLimitHeaders} output directly.
+     */
+    recordGithubRateLimit(rateLimit: GithubRateLimit | undefined): void;
     /** A JSON-friendly view of the current counters. */
     snapshot(now?: () => number): MetricsSnapshot;
     /** Render the Prometheus text exposition format (version 0.0.4). */
@@ -37,7 +50,7 @@ declare class MetricsRegistry {
  * branch; combined with the runtime cancelling the client branch, that releases
  * the shared upstream connection instead of draining it in the background.
  */
-declare function observeResponseUsage(response: Response, fallbackModel: string, onUsage: (model: string, usage: TokenUsage) => void, signal?: AbortSignal): Response;
+declare function observeResponseUsage(response: Response, fallbackModel: string, onUsage: (model: string, usage: TokenUsage) => void, signal?: AbortSignal, onOutcome?: (extracted: boolean) => void): Response;
 
 type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
 interface Logger {
@@ -149,8 +162,40 @@ interface CopilotUsage {
     quotaResetDate?: string;
     quotas: Record<string, CopilotQuota>;
 }
+/**
+ * GitHub REST API rate-limit budget parsed from the `x-ratelimit-*` headers that
+ * `api.github.com` returns on every response. Hoopilot reads these off the
+ * `copilot_internal/user` quota call it already makes, so the proxy's GitHub API
+ * usage is visible without spending an extra request.
+ */
+interface GithubRateLimit {
+    /** `x-ratelimit-resource` — the bucket the request counted against (e.g. `core`). */
+    resource: string;
+    /** `x-ratelimit-limit` — maximum requests allowed in the current window. */
+    limit?: number;
+    /** `x-ratelimit-remaining` — requests left in the current window. */
+    remaining?: number;
+    /** `x-ratelimit-used` — requests already spent in the current window. */
+    used?: number;
+    /** `x-ratelimit-reset` — Unix epoch seconds when the window resets. */
+    resetEpochSeconds?: number;
+    /** `retry-after` — seconds to wait, present on 429 / secondary-limit responses. */
+    retryAfterSeconds?: number;
+    /** Wall-clock epoch ms when these values were observed. */
+    observedAtMs: number;
+}
+/** JSON view of one GitHub rate-limit resource, as rendered into a snapshot. */
+interface GithubRateLimitSnapshot {
+    limit?: number;
+    observedAt: string;
+    remaining?: number;
+    resetAt?: string;
+    retryAfterSeconds?: number;
+    used?: number;
+}
 /** A point-in-time JSON view of the in-process metrics. */
 interface MetricsSnapshot {
+    githubRateLimit: Record<string, GithubRateLimitSnapshot>;
     inFlight: number;
     requests: {
         byRoute: Record<string, number>;
@@ -162,6 +207,10 @@ interface MetricsSnapshot {
         byModel: Record<string, ModelTokenTotals>;
         cached: number;
         completion: number;
+        extraction: {
+            extracted: number;
+            missing: number;
+        };
         prompt: number;
         reasoning: number;
         total: number;
@@ -227,6 +276,15 @@ declare function applyCopilotHeaders(headers: Headers, token: string): Headers;
  * Copilot completion endpoints.
  */
 declare function applyGithubApiHeaders(headers: Headers, token: string): Headers;
+/**
+ * Parse the GitHub REST `x-ratelimit-*` headers (plus `retry-after`) off a
+ * response into a {@link GithubRateLimit}. `api.github.com` returns these on
+ * every reply, so the proxy reads its GitHub API budget from the quota call it
+ * already makes — no extra request is spent. Returns undefined when the response
+ * carries no rate-limit headers (for example the Copilot completion host, which
+ * does not emit them today) so callers record nothing rather than a phantom row.
+ */
+declare function parseRateLimitHeaders(headers: Headers, nowMs?: number): GithubRateLimit | undefined;
 declare class CopilotClient {
     #private;
     constructor(options?: CopilotAuthOptions);
@@ -309,4 +367,4 @@ declare function extractTokenUsage(usage: unknown): TokenUsage | undefined;
 declare function createHoopilotHandler(options?: HoopilotServerOptions): (request: Request) => Promise<Response>;
 declare function startHoopilotServer(options?: HoopilotServerOptions): StartedHoopilotServer;
 
-export { AnthropicCompatibilityError, COPILOT_USAGE_API_VERSION, type CopilotAccess, CopilotAuth, CopilotAuthError, type CopilotAuthOptions, CopilotClient, type CopilotQuota, type CopilotUsage, DEFAULT_GITHUB_API_BASE_URL, DEFAULT_LOG_FORMAT, DEFAULT_LOG_LEVEL, DEFAULT_MODEL, type FetchLike, type HoopilotLogger, type HoopilotLoggerOptions, type HoopilotServerOptions, type JsonObject, type LogFields, type LogFormat, type LogLevel, type LogMethod, type Logger, MetricsRegistry, type MetricsSnapshot, type ModelTokenTotals, PROMETHEUS_CONTENT_TYPE, type RequestObservation, type StartedHoopilotServer, type TokenUsage, anthropicMessagesToResponsesRequest, applyCopilotHeaders, applyGithubApiHeaders, authStorePath, chatCompletionToCompletion, chatCompletionToResponse, completionStreamFromChatStream, completionsRequestToChatCompletion, createHoopilotHandler, createHoopilotLogger, estimateAnthropicMessageTokens, extractTokenUsage, fallbackModels, githubCopilotDeviceLogin, noopLogger, normalizeChatCompletionRequest, normalizeCopilotUsage, normalizeModelsResponse, normalizeRequestedModel, observeResponseUsage, parseLogFormat, parseLogLevel, readStoredCopilotAuth, responsesCompactionResult, responsesRequestToChatCompletion, responsesResponseToAnthropicMessage, responsesStreamFromChatStream, responsesStreamToAnthropicStream, startHoopilotServer, writeStoredCopilotAuth };
+export { AnthropicCompatibilityError, COPILOT_USAGE_API_VERSION, type CopilotAccess, CopilotAuth, CopilotAuthError, type CopilotAuthOptions, CopilotClient, type CopilotQuota, type CopilotUsage, DEFAULT_GITHUB_API_BASE_URL, DEFAULT_LOG_FORMAT, DEFAULT_LOG_LEVEL, DEFAULT_MODEL, type FetchLike, type GithubRateLimit, type GithubRateLimitSnapshot, type HoopilotLogger, type HoopilotLoggerOptions, type HoopilotServerOptions, type JsonObject, type LogFields, type LogFormat, type LogLevel, type LogMethod, type Logger, MetricsRegistry, type MetricsSnapshot, type ModelTokenTotals, PROMETHEUS_CONTENT_TYPE, type RequestObservation, type StartedHoopilotServer, type TokenUsage, anthropicMessagesToResponsesRequest, applyCopilotHeaders, applyGithubApiHeaders, authStorePath, chatCompletionToCompletion, chatCompletionToResponse, completionStreamFromChatStream, completionsRequestToChatCompletion, createHoopilotHandler, createHoopilotLogger, estimateAnthropicMessageTokens, extractTokenUsage, fallbackModels, githubCopilotDeviceLogin, noopLogger, normalizeChatCompletionRequest, normalizeCopilotUsage, normalizeModelsResponse, normalizeRequestedModel, observeResponseUsage, parseLogFormat, parseLogLevel, parseRateLimitHeaders, readStoredCopilotAuth, responsesCompactionResult, responsesRequestToChatCompletion, responsesResponseToAnthropicMessage, responsesStreamFromChatStream, responsesStreamToAnthropicStream, startHoopilotServer, writeStoredCopilotAuth };