@openhoo/hoopilot 1.0.0 → 1.2.0

package/dist/index.cjs

@@ -63,6 +63,7 @@ __export(index_exports, {
   observeResponseUsage: () => observeResponseUsage,
   parseLogFormat: () => parseLogFormat,
   parseLogLevel: () => parseLogLevel,
+  parseRateLimitHeaders: () => parseRateLimitHeaders,
   readStoredCopilotAuth: () => readStoredCopilotAuth,
   responsesCompactionResult: () => responsesCompactionResult,
   responsesRequestToChatCompletion: () => responsesRequestToChatCompletion,
@@ -1833,6 +1834,38 @@ function applyGithubApiHeaders(headers, token) {
   headers.set("x-github-api-version", COPILOT_USAGE_API_VERSION);
   return headers;
 }
+function parseRateLimitHeaders(headers, nowMs = Date.now()) {
+  const limit = headerInt(headers, "x-ratelimit-limit");
+  const remaining = headerInt(headers, "x-ratelimit-remaining");
+  const used = headerInt(headers, "x-ratelimit-used");
+  const resetEpochSeconds = headerInt(headers, "x-ratelimit-reset");
+  const retryAfterSeconds = headerInt(headers, "retry-after");
+  if (limit === void 0 && remaining === void 0 && used === void 0 && resetEpochSeconds === void 0 && retryAfterSeconds === void 0) {
+    return void 0;
+  }
+  return removeUndefinedRateLimit({
+    limit,
+    observedAtMs: nowMs,
+    remaining,
+    resetEpochSeconds,
+    resource: headers.get("x-ratelimit-resource")?.trim() || "unknown",
+    retryAfterSeconds,
+    used
+  });
+}
+function headerInt(headers, name) {
+  const raw = headers.get(name);
+  if (raw === null) {
+    return void 0;
+  }
+  const value = Number.parseInt(raw.trim(), 10);
+  return Number.isFinite(value) && value >= 0 ? value : void 0;
+}
+function removeUndefinedRateLimit(rateLimit) {
+  return Object.fromEntries(
+    Object.entries(rateLimit).filter(([, value]) => value !== void 0)
+  );
+}
 var CopilotClient = class {
   #auth;
   #allowUnsafeUpstream;
@@ -2249,6 +2282,7 @@ var DURATION_BUCKETS_SECONDS = [0.05, 0.1, 0.25, 0.5, 1, 2.5, 5, 10, 30, 60];
 var USAGE_BUFFER_LIMIT_BYTES = 16 * 1024 * 1024;
 var MAX_TRACKED_MODELS = 200;
 var MAX_MODEL_LABEL_LENGTH = 200;
+var MAX_TRACKED_RATELIMIT_RESOURCES = 32;
 var LABEL_SEPARATOR = "";
 var UNKNOWN_MODEL = "unknown";
 function emptyModelTotals() {
@@ -2262,6 +2296,8 @@ var MetricsRegistry = class {
   #tokens = /* @__PURE__ */ new Map();
   #upstream = /* @__PURE__ */ new Map();
   #copilotQuota;
+  #githubRateLimit = /* @__PURE__ */ new Map();
+  #extraction = { extracted: 0, missing: 0 };
   constructor(options = {}) {
     this.#startedAtMs = (options.now ?? Date.now)();
   }
@@ -2278,6 +2314,19 @@ var MetricsRegistry = class {
     this.#requests.set(key, (this.#requests.get(key) ?? 0) + 1);
     this.#observeDuration(observation.route, observation.durationMs / 1e3);
   }
+  /**
+   * 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) {
+    if (extracted) {
+      this.#extraction.extracted += 1;
+    } else {
+      this.#extraction.missing += 1;
+    }
+  }
   /** Accumulate token counts for a model from one upstream completion. */
   recordTokens(model, usage) {
     const name = this.#modelLabel(model);
@@ -2299,17 +2348,39 @@ var MetricsRegistry = class {
   recordCopilotQuota(usage) {
     this.#copilotQuota = usage;
   }
-  // Sanitize the model into a bounded, control-char-free label. The model can
-  // originate from a client request, so cap its length, strip characters that
-  // would corrupt the exposition format, and fold overflow past the cardinality
-  // limit into UNKNOWN_MODEL to keep the series count bounded.
+  /**
+   * 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) {
+    if (!rateLimit) {
+      return;
+    }
+    const resource = this.#rateLimitResource(rateLimit.resource);
+    this.#githubRateLimit.set(resource, { ...rateLimit, resource });
+  }
+  // Sanitize the model into a bounded label. The model can originate from a
+  // client request, so cap its length, strip characters that would corrupt the
+  // exposition format, and fold overflow past the cardinality limit into
+  // UNKNOWN_MODEL to keep the series count bounded.
   #modelLabel(model) {
-    const cleaned = model.replace(/[\u0000-\u001f\u007f]/g, "").trim().slice(0, MAX_MODEL_LABEL_LENGTH) || UNKNOWN_MODEL;
+    const cleaned = cleanLabel(model).slice(0, MAX_MODEL_LABEL_LENGTH) || UNKNOWN_MODEL;
     if (!this.#tokens.has(cleaned) && this.#tokens.size >= MAX_TRACKED_MODELS) {
       return UNKNOWN_MODEL;
     }
     return cleaned;
   }
+  // The resource comes from a trusted upstream header, but clean and bound it
+  // with the same discipline as model labels: strip control characters that
+  // would corrupt the exposition format and fold overflow into "unknown".
+  #rateLimitResource(resource) {
+    const cleaned = cleanLabel(resource).slice(0, MAX_MODEL_LABEL_LENGTH) || UNKNOWN_MODEL;
+    if (!this.#githubRateLimit.has(cleaned) && this.#githubRateLimit.size >= MAX_TRACKED_RATELIMIT_RESOURCES) {
+      return UNKNOWN_MODEL;
+    }
+    return cleaned;
+  }
   #observeDuration(route, seconds) {
     const value = Number.isFinite(seconds) && seconds >= 0 ? seconds : 0;
     const entry = this.#durations.get(route) ?? {
@@ -2354,11 +2425,16 @@ var MetricsRegistry = class {
         upstreamErrors += count;
       }
     }
+    const githubRateLimit = {};
+    for (const [resource, rateLimit] of this.#githubRateLimit) {
+      githubRateLimit[resource] = toRateLimitSnapshot(rateLimit);
+    }
     return {
+      githubRateLimit,
       inFlight: this.#inFlight,
       requests: { byRoute, byStatus, total: requestsTotal },
       startedAt: new Date(this.#startedAtMs).toISOString(),
-      tokens: { byModel, ...tokenTotals },
+      tokens: { byModel, extraction: { ...this.#extraction }, ...tokenTotals },
       upstream: { errors: upstreamErrors, total: upstreamTotal },
       uptimeSeconds: Math.max(0, Math.round((now() - this.#startedAtMs) / 1e3))
     };
@@ -2408,6 +2484,16 @@ var MetricsRegistry = class {
     for (const [model, totals] of this.#tokens) {
       lines.push(`hoopilot_model_requests_total${labels({ model })} ${totals.requests}`);
     }
+    lines.push(
+      "# HELP hoopilot_token_extraction_total Completions by whether upstream reported token usage."
+    );
+    lines.push("# TYPE hoopilot_token_extraction_total counter");
+    lines.push(
+      `hoopilot_token_extraction_total${labels({ outcome: "extracted" })} ${this.#extraction.extracted}`
+    );
+    lines.push(
+      `hoopilot_token_extraction_total${labels({ outcome: "missing" })} ${this.#extraction.missing}`
+    );
     lines.push("# HELP hoopilot_request_duration_seconds Request duration by route.");
     lines.push("# TYPE hoopilot_request_duration_seconds histogram");
     for (const [route, entry] of this.#durations) {
@@ -2425,10 +2511,43 @@ var MetricsRegistry = class {
       lines.push(`hoopilot_request_duration_seconds_sum${labels({ route })} ${entry.sum}`);
       lines.push(`hoopilot_request_duration_seconds_count${labels({ route })} ${entry.count}`);
     }
+    this.#renderGithubRateLimit(lines);
     this.#renderCopilotQuota(lines);
     return `${lines.join("\n")}
 `;
   }
+  #renderGithubRateLimit(lines) {
+    const entries = [...this.#githubRateLimit.values()];
+    if (entries.length === 0) {
+      return;
+    }
+    const gauge = (suffix, help, pick) => {
+      const present = entries.filter((rateLimit) => pick(rateLimit) !== void 0);
+      if (present.length === 0) {
+        return;
+      }
+      lines.push(`# HELP hoopilot_github_ratelimit_${suffix} ${help}`);
+      lines.push(`# TYPE hoopilot_github_ratelimit_${suffix} gauge`);
+      for (const rateLimit of present) {
+        lines.push(
+          `hoopilot_github_ratelimit_${suffix}${labels({ resource: rateLimit.resource })} ${pick(rateLimit)}`
+        );
+      }
+    };
+    gauge("limit", "GitHub REST API request ceiling for the resource window.", (r) => r.limit);
+    gauge("remaining", "Requests remaining in the GitHub REST API window.", (r) => r.remaining);
+    gauge("used", "Requests used in the GitHub REST API window.", (r) => r.used);
+    gauge(
+      "reset_timestamp_seconds",
+      "Unix epoch when the GitHub REST API window resets.",
+      (r) => r.resetEpochSeconds
+    );
+    gauge(
+      "retry_after_seconds",
+      "Seconds to wait after a GitHub secondary-limit response.",
+      (r) => r.retryAfterSeconds
+    );
+  }
   #renderCopilotQuota(lines) {
     const usage = this.#copilotQuota;
     if (!usage) {
@@ -2530,23 +2649,25 @@ var MetricsRegistry = class {
     }
   }
 };
-function observeResponseUsage(response, fallbackModel, onUsage, signal) {
+function observeResponseUsage(response, fallbackModel, onUsage, signal, onOutcome) {
   const body = response.body;
   if (!body) {
     return response;
   }
   const [clientBranch, observerBranch] = body.tee();
   const isSse = response.headers.get("content-type")?.includes("text/event-stream") ?? false;
-  void consumeUsage(observerBranch, isSse, fallbackModel, onUsage, signal).catch(() => {
-  });
+  void consumeUsage(observerBranch, isSse, fallbackModel, onUsage, signal, onOutcome).catch(
+    () => {
+    }
+  );
   return new Response(clientBranch, {
     headers: response.headers,
     status: response.status,
     statusText: response.statusText
   });
 }
-function recordResponseTextUsage(text, isSse, fallbackModel, onUsage) {
-  const accumulator = createUsageAccumulator(fallbackModel, onUsage);
+function recordResponseTextUsage(text, isSse, fallbackModel, onUsage, onOutcome) {
+  const accumulator = createUsageAccumulator(fallbackModel, onUsage, onOutcome);
   if (isSse) {
     for (const line of text.split(/\r?\n/)) {
       considerSseLine(line, accumulator.consider);
@@ -2559,7 +2680,7 @@ function recordResponseTextUsage(text, isSse, fallbackModel, onUsage) {
   }
   accumulator.finish();
 }
-async function consumeUsage(stream, isSse, fallbackModel, onUsage, signal) {
+async function consumeUsage(stream, isSse, fallbackModel, onUsage, signal, onOutcome) {
   const reader = stream.getReader();
   const onAbort = () => {
     reader.cancel().catch(() => {
@@ -2572,7 +2693,12 @@ async function consumeUsage(stream, isSse, fallbackModel, onUsage, signal) {
     signal?.addEventListener("abort", onAbort, { once: true });
   }
   const decoder = new TextDecoder();
-  const accumulator = createUsageAccumulator(fallbackModel, onUsage);
+  const guardedOutcome = onOutcome ? (extracted) => {
+    if (!signal?.aborted) {
+      onOutcome(extracted);
+    }
+  } : void 0;
+  const accumulator = createUsageAccumulator(fallbackModel, onUsage, guardedOutcome);
   let buffer = "";
   let bufferedBytes = 0;
   let overflowed = false;
@@ -2620,7 +2746,7 @@ async function consumeUsage(stream, isSse, fallbackModel, onUsage, signal) {
   }
   accumulator.finish();
 }
-function createUsageAccumulator(fallbackModel, onUsage) {
+function createUsageAccumulator(fallbackModel, onUsage, onOutcome) {
   let model = fallbackModel;
   let usage;
   return {
@@ -2639,6 +2765,7 @@ function createUsageAccumulator(fallbackModel, onUsage) {
       if (usage) {
         onUsage(model, usage);
       }
+      onOutcome?.(usage !== void 0);
     }
   };
 }
@@ -2669,6 +2796,37 @@ function modelText(value) {
 function nonNegative(value) {
   return Number.isFinite(value) && value > 0 ? value : 0;
 }
+function cleanLabel(value) {
+  let result = "";
+  for (const char of value) {
+    const code = char.charCodeAt(0);
+    if (code > 31 && code !== 127) {
+      result += char;
+    }
+  }
+  return result.trim();
+}
+function toRateLimitSnapshot(rateLimit) {
+  const snapshot = {
+    observedAt: new Date(rateLimit.observedAtMs).toISOString()
+  };
+  if (rateLimit.limit !== void 0) {
+    snapshot.limit = rateLimit.limit;
+  }
+  if (rateLimit.remaining !== void 0) {
+    snapshot.remaining = rateLimit.remaining;
+  }
+  if (rateLimit.used !== void 0) {
+    snapshot.used = rateLimit.used;
+  }
+  if (rateLimit.resetEpochSeconds !== void 0) {
+    snapshot.resetAt = new Date(rateLimit.resetEpochSeconds * 1e3).toISOString();
+  }
+  if (rateLimit.retryAfterSeconds !== void 0) {
+    snapshot.retryAfterSeconds = rateLimit.retryAfterSeconds;
+  }
+  return snapshot;
+}
 function labelKey(...parts) {
   return parts.join(LABEL_SEPARATOR);
 }
@@ -2716,6 +2874,7 @@ function createHoopilotHandler(options = {}) {
   const metrics = options.metrics ?? new MetricsRegistry();
   const readUsage = createUsageReader(client, metrics);
   const recordTokens = (model, usage) => metrics.recordTokens(model, usage);
+  const recordExtraction = (extracted) => metrics.recordTokenExtraction(extracted);
   const streamingProxyMode = resolveStreamingProxyMode(options);
   const bufferProxyBodies = shouldBufferProxyBodies(streamingProxyMode);
   return async (request) => {
@@ -2781,6 +2940,7 @@ function createHoopilotHandler(options = {}) {
             client,
             metrics,
             recordTokens,
+            recordExtraction,
             request,
             requestLogger,
             bufferProxyBodies
@@ -2796,6 +2956,7 @@ function createHoopilotHandler(options = {}) {
             client,
             metrics,
             recordTokens,
+            recordExtraction,
             request,
             requestLogger,
             bufferProxyBodies
@@ -2808,6 +2969,7 @@ function createHoopilotHandler(options = {}) {
             client,
             metrics,
             recordTokens,
+            recordExtraction,
             request,
             requestLogger,
             bufferProxyBodies
@@ -2816,7 +2978,14 @@ function createHoopilotHandler(options = {}) {
       }
       if (request.method === "POST" && apiPath === "/v1/responses/compact") {
         return finish(
-          await handleResponsesCompact(client, metrics, recordTokens, request, requestLogger)
+          await handleResponsesCompact(
+            client,
+            metrics,
+            recordTokens,
+            recordExtraction,
+            request,
+            requestLogger
+          )
         );
       }
       if (request.method === "POST" && apiPath === "/v1/responses") {
@@ -2825,6 +2994,7 @@ function createHoopilotHandler(options = {}) {
             client,
             metrics,
             recordTokens,
+            recordExtraction,
             request,
             requestLogger,
             bufferProxyBodies
@@ -2901,7 +3071,7 @@ function startHoopilotServer(options = {}) {
     url: `http://${urlHost(host)}:${server.port}`
   };
 }
-async function handleAnthropicMessages(client, metrics, recordTokens, request, logger, bufferProxyBodies) {
+async function handleAnthropicMessages(client, metrics, recordTokens, recordExtraction, request, logger, bufferProxyBodies) {
   const anthropicRequest = await readJson(request);
   const responsesRequest = anthropicMessagesToResponsesRequest(anthropicRequest);
   const upstream = await client.responses(JSON.stringify(responsesRequest), request.signal);
@@ -2914,12 +3084,18 @@ async function handleAnthropicMessages(client, metrics, recordTokens, request, l
   if (isStreamingResponse(upstream) && upstream.body) {
     if (bufferProxyBodies) {
       const text = await upstream.text();
-      recordResponseTextUsage(text, true, model, recordTokens);
+      recordResponseTextUsage(text, true, model, recordTokens, recordExtraction);
       return proxyResponse(
         responseFromText(upstream, responsesSseTextToAnthropicSseText(text, { model }))
       );
     }
-    const observed = observeResponseUsage(upstream, model, recordTokens, request.signal);
+    const observed = observeResponseUsage(
+      upstream,
+      model,
+      recordTokens,
+      request.signal,
+      recordExtraction
+    );
     if (!observed.body) {
       return proxyResponse(observed);
     }
@@ -2937,6 +3113,7 @@ async function handleAnthropicMessages(client, metrics, recordTokens, request, l
     const responseModel = typeof body.model === "string" ? body.model.trim() : "";
     recordTokens(responseModel || model, usage);
   }
+  recordExtraction(usage !== void 0);
   return jsonResponse(responsesResponseToAnthropicMessage(body, model));
 }
 function handleAnthropicCountTokens(body) {
@@ -2962,7 +3139,7 @@ async function handleModels(client, metrics, signal, logger) {
   logUpstreamSuccess(logger, "/models", upstream.status);
   return jsonResponse(normalizeModelsResponse(await upstream.json()));
 }
-async function handleChatCompletions(client, metrics, recordTokens, request, logger, bufferProxyBodies) {
+async function handleChatCompletions(client, metrics, recordTokens, recordExtraction, request, logger, bufferProxyBodies) {
   const chatRequest = normalizeChatCompletionRequest(await readJson(request));
   const upstream = await client.chatCompletions(chatRequest, request.signal);
   metrics.recordUpstream("/chat/completions", upstream.ok);
@@ -2977,11 +3154,12 @@ async function handleChatCompletions(client, metrics, recordTokens, request, log
       model,
       recordTokens,
       request.signal,
-      bufferProxyBodies
+      bufferProxyBodies,
+      recordExtraction
     )
   );
 }
-async function handleCompletions(client, metrics, recordTokens, request, logger, bufferProxyBodies) {
+async function handleCompletions(client, metrics, recordTokens, recordExtraction, request, logger, bufferProxyBodies) {
   const body = await readJson(request);
   const upstream = await client.chatCompletions(
     completionsRequestToChatCompletion(body),
@@ -2996,7 +3174,7 @@ async function handleCompletions(client, metrics, recordTokens, request, logger,
   if (isStreamingResponse(upstream) && upstream.body) {
     if (bufferProxyBodies) {
       const upstreamText = await upstream.text();
-      recordResponseTextUsage(upstreamText, true, model, recordTokens);
+      recordResponseTextUsage(upstreamText, true, model, recordTokens, recordExtraction);
       const text = completionSseTextFromChatSseText(upstreamText);
       return proxyResponse(responseFromText(upstream, text));
     }
@@ -3009,7 +3187,8 @@ async function handleCompletions(client, metrics, recordTokens, request, logger,
         }),
         model,
         recordTokens,
-        request.signal
+        request.signal,
+        recordExtraction
       )
     );
   }
@@ -3019,9 +3198,10 @@ async function handleCompletions(client, metrics, recordTokens, request, logger,
     const responseModel = typeof completion.model === "string" ? completion.model.trim() : "";
     recordTokens(responseModel || model, usage);
   }
+  recordExtraction(usage !== void 0);
   return jsonResponse(chatCompletionToCompletion(completion));
 }
-async function handleResponses(client, metrics, recordTokens, request, logger, bufferProxyBodies) {
+async function handleResponses(client, metrics, recordTokens, recordExtraction, request, logger, bufferProxyBodies) {
   const body = await readJsonText(request);
   const upstream = await client.responses(body, request.signal);
   metrics.recordUpstream("/responses", upstream.ok);
@@ -3036,11 +3216,12 @@ async function handleResponses(client, metrics, recordTokens, request, logger, b
       model,
       recordTokens,
       request.signal,
-      bufferProxyBodies
+      bufferProxyBodies,
+      recordExtraction
     )
   );
 }
-async function handleResponsesCompact(client, metrics, recordTokens, request, logger) {
+async function handleResponsesCompact(client, metrics, recordTokens, recordExtraction, request, logger) {
   const body = await readJson(request);
   const upstream = await client.responses(
     JSON.stringify({ ...body, stream: false }),
@@ -3053,17 +3234,23 @@ async function handleResponsesCompact(client, metrics, recordTokens, request, lo
   logUpstreamSuccess(logger, "/responses", upstream.status);
   const isSse = isStreamingResponse(upstream);
   const text = await upstream.text();
-  recordResponseTextUsage(text, isSse, normalizeRequestedModel(body.model), recordTokens);
+  recordResponseTextUsage(
+    text,
+    isSse,
+    normalizeRequestedModel(body.model),
+    recordTokens,
+    recordExtraction
+  );
   return jsonResponse(responsesCompactionResult(text, isSse));
 }
-async function responseWithObservedUsage(response, fallbackModel, recordTokens, signal, bufferBody) {
+async function responseWithObservedUsage(response, fallbackModel, recordTokens, signal, bufferBody, recordExtraction) {
   const isSse = isStreamingResponse(response);
   if (bufferBody && response.body) {
     const text = await response.text();
-    recordResponseTextUsage(text, isSse, fallbackModel, recordTokens);
+    recordResponseTextUsage(text, isSse, fallbackModel, recordTokens, recordExtraction);
     return responseFromText(response, text);
   }
-  return observeResponseUsage(response, fallbackModel, recordTokens, signal);
+  return observeResponseUsage(response, fallbackModel, recordTokens, signal, recordExtraction);
 }
 function responseFromText(source, text) {
   return new Response(text, {
@@ -3492,6 +3679,7 @@ function createUsageReader(client, metrics, now = Date.now, ttlMs = USAGE_CACHE_
     try {
       const upstream = await client.usage(signal);
       metrics.recordUpstream(usagePath, upstream.ok);
+      metrics.recordGithubRateLimit(parseRateLimitHeaders(upstream.headers, now()));
       if (!upstream.ok) {
         return { error: `GitHub Copilot usage request failed with ${upstream.status}.` };
       }
@@ -3550,6 +3738,7 @@ function safeParseJson(text) {
   observeResponseUsage,
   parseLogFormat,
   parseLogLevel,
+  parseRateLimitHeaders,
   readStoredCopilotAuth,
   responsesCompactionResult,
   responsesRequestToChatCompletion,