@openhoo/hoopilot 0.7.4 → 0.7.5

package/README.md

@@ -158,7 +158,7 @@ Incoming `x-request-id` headers are preserved on responses. If a request has no
 
 Hoopilot tracks token usage, request counts, and latency in memory while the server runs, and can report your GitHub Copilot account quota (premium-request "credit" usage).
 
-- `GET /metrics` returns Prometheus text (`text/plain; version=0.0.4`). It exposes request counters (`hoopilot_requests_total`), upstream call counters (`hoopilot_upstream_requests_total`), token counters by model and type (`hoopilot_tokens_total{model,type}`), a request-duration histogram (`hoopilot_request_duration_seconds`), an in-flight gauge, and—once `/v1/usage` has been fetched at least once—Copilot quota gauges (`hoopilot_copilot_quota_remaining{category}`, `_entitlement`, `_used`, `_percent_remaining`). Counters reset to zero on restart, which Prometheus handles natively.
+- `GET /metrics` returns Prometheus text (`text/plain; version=0.0.4`). It exposes request counters (`hoopilot_requests_total`), upstream call counters (`hoopilot_upstream_requests_total`), token counters by model and type (`hoopilot_tokens_total{model,type}`), a request-duration histogram (`hoopilot_request_duration_seconds`), an in-flight gauge, and—once `/v1/usage` has been fetched at least once—Copilot quota gauges (`hoopilot_copilot_quota_remaining{category}`, `_entitlement`, `_used`, `_percent_remaining`, `_overage_count`, `_overage_entitlement`, `_unlimited`, `_overage_permitted`, `_has_quota`, `_token_based_billing`, and category reset/snapshot timestamps). Counters reset to zero on restart, which Prometheus handles natively.
 - `GET /v1/usage` returns JSON combining the proxy metrics snapshot with live Copilot quota fetched from GitHub (cached for 60 seconds). If the quota cannot be read, `copilot` is `null` and `copilot_error` explains why, but the proxy metrics are still returned.
 - `hoopilot usage` prints your Copilot plan and quota from the command line.
 

package/dist/cli.js

@@ -293,22 +293,31 @@ function normalizeCopilotUsage(body) {
 }
 function normalizeQuotaDetail(detail) {
   const entitlement = numberOrUndefined(detail.entitlement);
+  const overageCount = numberOrUndefined(detail.overage_count);
   const remaining = numberOrUndefined(detail.remaining) ?? numberOrUndefined(detail.quota_remaining);
   return removeUndefinedQuota({
     entitlement,
-    overageCount: numberOrUndefined(detail.overage_count),
+    hasQuota: typeof detail.has_quota === "boolean" ? detail.has_quota : void 0,
+    overageCount,
+    overageEntitlement: numberOrUndefined(detail.overage_entitlement),
     overagePermitted: typeof detail.overage_permitted === "boolean" ? detail.overage_permitted : void 0,
     percentRemaining: numberOrUndefined(detail.percent_remaining),
+    quotaId: stringOrUndefined(detail.quota_id),
+    quotaResetAt: stringOrUndefined(detail.quota_reset_at),
     remaining,
+    timestampUtc: stringOrUndefined(detail.timestamp_utc),
+    tokenBasedBilling: typeof detail.token_based_billing === "boolean" ? detail.token_based_billing : void 0,
     unlimited: typeof detail.unlimited === "boolean" ? detail.unlimited : void 0,
-    used: usedFrom(entitlement, remaining)
+    used: usedFrom(entitlement, remaining, overageCount)
   });
 }
-function usedFrom(entitlement, remaining) {
+function usedFrom(entitlement, remaining, overageCount) {
   if (entitlement === void 0 || remaining === void 0) {
     return void 0;
   }
-  return Math.max(0, entitlement - remaining);
+  const base = entitlement - remaining;
+  const overage = remaining === 0 ? overageCount ?? 0 : 0;
+  return Math.max(0, base + overage);
 }
 function numberOrUndefined(value) {
   return typeof value === "number" && Number.isFinite(value) ? value : void 0;
@@ -1094,11 +1103,43 @@ var MetricsRegistry = class {
     gauge("remaining", "Remaining quota for the Copilot category.", (q) => q.remaining);
     gauge("entitlement", "Quota entitlement for the Copilot category.", (q) => q.entitlement);
     gauge("used", "Used quota (entitlement minus remaining) for the category.", (q) => q.used);
+    gauge("overage_count", "Overage count for the Copilot category.", (q) => q.overageCount);
+    gauge(
+      "overage_entitlement",
+      "Overage entitlement for the Copilot category.",
+      (q) => q.overageEntitlement
+    );
     gauge(
       "percent_remaining",
       "Percent of quota remaining for the Copilot category.",
       (q) => q.percentRemaining
     );
+    booleanGauge(
+      "unlimited",
+      "Whether the Copilot quota category is unlimited.",
+      (q) => q.unlimited
+    );
+    booleanGauge(
+      "overage_permitted",
+      "Whether overage is permitted for the Copilot category.",
+      (q) => q.overagePermitted
+    );
+    booleanGauge("has_quota", "Whether the Copilot quota category has a quota.", (q) => q.hasQuota);
+    booleanGauge(
+      "token_based_billing",
+      "Whether the Copilot quota category uses token-based billing.",
+      (q) => q.tokenBasedBilling
+    );
+    dateGauge(
+      "category_reset_timestamp_seconds",
+      "Unix epoch of the Copilot category-specific quota reset.",
+      (q) => q.quotaResetAt
+    );
+    dateGauge(
+      "category_snapshot_timestamp_seconds",
+      "Unix epoch of the Copilot category quota snapshot.",
+      (q) => q.timestampUtc
+    );
     const resetMs = usage.quotaResetDate ? Date.parse(usage.quotaResetDate) : Number.NaN;
     if (Number.isFinite(resetMs)) {
       lines.push(
@@ -1117,6 +1158,30 @@ var MetricsRegistry = class {
         })} 1`
       );
     }
+    function booleanGauge(suffix, help, pick) {
+      const present = categories.filter(([, quota]) => pick(quota) !== void 0);
+      if (present.length === 0) {
+        return;
+      }
+      lines.push(`# HELP hoopilot_copilot_quota_${suffix} ${help}`);
+      lines.push(`# TYPE hoopilot_copilot_quota_${suffix} gauge`);
+      for (const [category, quota] of present) {
+        lines.push(
+          `hoopilot_copilot_quota_${suffix}${labels({ category })} ${pick(quota) ? 1 : 0}`
+        );
+      }
+    }
+    function dateGauge(suffix, help, pick) {
+      const present = categories.map(([category, quota]) => [category, Date.parse(pick(quota) ?? "")]).filter(([, timestamp]) => Number.isFinite(timestamp));
+      if (present.length === 0) {
+        return;
+      }
+      lines.push(`# HELP hoopilot_copilot_quota_${suffix} ${help}`);
+      lines.push(`# TYPE hoopilot_copilot_quota_${suffix} gauge`);
+      for (const [category, timestamp] of present) {
+        lines.push(`hoopilot_copilot_quota_${suffix}${labels({ category })} ${timestamp / 1e3}`);
+      }
+    }
   }
 };
 function observeResponseUsage(response, fallbackModel, onUsage, signal) {
@@ -1814,8 +1879,8 @@ function metricsResponse(metrics) {
   });
 }
 async function handleUsage(metrics, readUsage, signal) {
-  const proxy = metrics.snapshot();
   const { copilot, error } = await readUsage(signal);
+  const proxy = metrics.snapshot();
   const body = { copilot: copilot ?? null, object: "usage", proxy };
   if (error) {
     body.copilot_error = error;
@@ -1840,10 +1905,10 @@ function createUsageReader(client, metrics, now = Date.now, ttlMs = USAGE_CACHE_
       metrics.recordCopilotQuota(value);
       return { copilot: value };
     } catch (error) {
-      metrics.recordUpstream(usagePath, false);
       if (error instanceof CopilotAuthError) {
         return { error: error.message };
       }
+      metrics.recordUpstream(usagePath, false);
       return { error: errorMessage(error) };
     }
   };