@openhoo/hoopilot 0.6.1 → 0.7.0

package/dist/cli.js

@@ -110,6 +110,8 @@ var CopilotAuth = class {
 };
 
 // src/copilot.ts
+var DEFAULT_GITHUB_API_BASE_URL = "https://api.github.com";
+var COPILOT_USAGE_API_VERSION = "2025-04-01";
 function applyCopilotHeaders(headers, token) {
   headers.set("accept", headers.get("accept") ?? "application/json");
   headers.set("authorization", `Bearer ${token}`);
@@ -121,12 +123,44 @@ function applyCopilotHeaders(headers, token) {
   headers.set("x-github-api-version", "2026-06-01");
   return headers;
 }
+function applyGithubApiHeaders(headers, token) {
+  headers.set("accept", headers.get("accept") ?? "application/json");
+  headers.set("authorization", `token ${token}`);
+  headers.set("editor-plugin-version", "hoopilot/0.1.0");
+  headers.set("editor-version", "Hoopilot/0.1.0");
+  headers.set("user-agent", "hoopilot/0.1.0");
+  headers.set("x-github-api-version", COPILOT_USAGE_API_VERSION);
+  return headers;
+}
 var CopilotClient = class {
   #auth;
   #fetch;
+  #githubApiBaseUrl;
   constructor(options = {}) {
     this.#auth = new CopilotAuth(options);
     this.#fetch = options.fetch ?? fetch;
+    this.#githubApiBaseUrl = trimTrailingSlash(
+      options.githubApiBaseUrl ?? options.env?.HOOPILOT_GITHUB_API_BASE_URL ?? DEFAULT_GITHUB_API_BASE_URL
+    );
+  }
+  /**
+   * Fetch the Copilot account's quota / premium-request usage from the GitHub
+   * REST `copilot_internal/user` endpoint. The stored device-flow OAuth token is
+   * accepted directly here — no Copilot token exchange is required to read quota.
+   */
+  async usage(signal) {
+    if (!isHttpsOrLoopback(this.#githubApiBaseUrl)) {
+      throw new Error(
+        `Refusing to send the GitHub OAuth token to a non-HTTPS host: ${this.#githubApiBaseUrl}`
+      );
+    }
+    const access = await this.#auth.getAccess();
+    const headers = applyGithubApiHeaders(new Headers(), access.token);
+    return this.#fetch(`${this.#githubApiBaseUrl}/copilot_internal/user`, {
+      headers,
+      method: "GET",
+      signal
+    });
   }
   async chatCompletions(body, signal) {
     return this.fetchCopilot("/chat/completions", {
@@ -166,6 +200,81 @@ var CopilotClient = class {
     });
   }
 };
+function normalizeCopilotUsage(body) {
+  const record = asRecord(body);
+  const quotas = {};
+  const snapshots = asRecord(record.quota_snapshots);
+  for (const [category, detail] of Object.entries(snapshots)) {
+    quotas[category] = normalizeQuotaDetail(asRecord(detail));
+  }
+  if (Object.keys(quotas).length === 0) {
+    const remaining = asRecord(record.limited_user_quotas);
+    const monthly = asRecord(record.monthly_quotas);
+    for (const category of /* @__PURE__ */ new Set([...Object.keys(remaining), ...Object.keys(monthly)])) {
+      const entitlement = numberOrUndefined(monthly[category]);
+      const left = numberOrUndefined(remaining[category]);
+      quotas[category] = removeUndefinedQuota({
+        entitlement,
+        percentRemaining: entitlement !== void 0 && entitlement > 0 && left !== void 0 ? left / entitlement * 100 : void 0,
+        remaining: left,
+        used: usedFrom(entitlement, left)
+      });
+    }
+  }
+  return removeUndefinedUsage({
+    accessTypeSku: stringOrUndefined(record.access_type_sku),
+    chatEnabled: typeof record.chat_enabled === "boolean" ? record.chat_enabled : void 0,
+    plan: stringOrUndefined(record.copilot_plan),
+    quotaResetDate: stringOrUndefined(record.quota_reset_date) ?? stringOrUndefined(record.quota_reset_date_utc) ?? stringOrUndefined(record.limited_user_reset_date),
+    quotas
+  });
+}
+function normalizeQuotaDetail(detail) {
+  const entitlement = numberOrUndefined(detail.entitlement);
+  const remaining = numberOrUndefined(detail.remaining) ?? numberOrUndefined(detail.quota_remaining);
+  return removeUndefinedQuota({
+    entitlement,
+    overageCount: numberOrUndefined(detail.overage_count),
+    overagePermitted: typeof detail.overage_permitted === "boolean" ? detail.overage_permitted : void 0,
+    percentRemaining: numberOrUndefined(detail.percent_remaining),
+    remaining,
+    unlimited: typeof detail.unlimited === "boolean" ? detail.unlimited : void 0,
+    used: usedFrom(entitlement, remaining)
+  });
+}
+function usedFrom(entitlement, remaining) {
+  if (entitlement === void 0 || remaining === void 0) {
+    return void 0;
+  }
+  return Math.max(0, entitlement - remaining);
+}
+function isHttpsOrLoopback(rawUrl) {
+  let url;
+  try {
+    url = new URL(rawUrl);
+  } catch {
+    return false;
+  }
+  if (url.protocol === "https:") {
+    return true;
+  }
+  return url.protocol === "http:" && (url.hostname === "127.0.0.1" || url.hostname === "localhost" || url.hostname === "::1");
+}
+function numberOrUndefined(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function stringOrUndefined(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function removeUndefinedQuota(quota) {
+  return Object.fromEntries(
+    Object.entries(quota).filter(([, value]) => value !== void 0)
+  );
+}
+function removeUndefinedUsage(usage) {
+  const entries = Object.entries(usage).filter(([, value]) => value !== void 0);
+  return Object.fromEntries(entries);
+}
 
 // src/github-device.ts
 import { setTimeout as sleep } from "timers/promises";
@@ -503,6 +612,40 @@ function contentToText(content) {
   }
   return "";
 }
+function extractTokenUsage(usage) {
+  const record = asRecord(usage);
+  const prompt = firstNumber(record.prompt_tokens, record.input_tokens);
+  const completion = firstNumber(record.completion_tokens, record.output_tokens);
+  const total = firstNumber(record.total_tokens);
+  if (prompt === void 0 && completion === void 0 && total === void 0) {
+    return void 0;
+  }
+  const promptTokens = prompt ?? 0;
+  const completionTokens = completion ?? 0;
+  const reasoning = firstNumber(
+    asRecord(record.completion_tokens_details).reasoning_tokens,
+    asRecord(record.output_tokens_details).reasoning_tokens
+  );
+  const cached = firstNumber(
+    asRecord(record.prompt_tokens_details).cached_tokens,
+    asRecord(record.input_tokens_details).cached_tokens
+  );
+  return removeUndefined({
+    cachedTokens: cached,
+    completionTokens,
+    promptTokens,
+    reasoningTokens: reasoning,
+    totalTokens: total ?? promptTokens + completionTokens
+  });
+}
+function firstNumber(...values) {
+  for (const value of values) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+      return value;
+    }
+  }
+  return void 0;
+}
 function firstChoice(completion) {
   const choices = Array.isArray(completion.choices) ? completion.choices : [];
   return asRecord(choices[0]);
@@ -517,104 +660,449 @@ function epochSeconds() {
   return Math.floor(Date.now() / 1e3);
 }
 
+// src/metrics.ts
+var PROMETHEUS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8";
+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 LABEL_SEPARATOR = "";
+var UNKNOWN_MODEL = "unknown";
+function emptyModelTotals() {
+  return { cached: 0, completion: 0, prompt: 0, reasoning: 0, requests: 0, total: 0 };
+}
+var MetricsRegistry = class {
+  #startedAtMs;
+  #inFlight = 0;
+  #requests = /* @__PURE__ */ new Map();
+  #durations = /* @__PURE__ */ new Map();
+  #tokens = /* @__PURE__ */ new Map();
+  #upstream = /* @__PURE__ */ new Map();
+  #copilotQuota;
+  constructor(options = {}) {
+    this.#startedAtMs = (options.now ?? Date.now)();
+  }
+  /** Mark a request as started; pair with exactly one {@link observe}. */
+  startRequest() {
+    this.#inFlight += 1;
+  }
+  /** Record a completed request and clear its in-flight slot. */
+  observe(observation) {
+    if (this.#inFlight > 0) {
+      this.#inFlight -= 1;
+    }
+    const key = labelKey(observation.route, observation.method, String(observation.status));
+    this.#requests.set(key, (this.#requests.get(key) ?? 0) + 1);
+    this.#observeDuration(observation.route, observation.durationMs / 1e3);
+  }
+  /** Accumulate token counts for a model from one upstream completion. */
+  recordTokens(model, usage) {
+    const name = this.#modelLabel(model);
+    const totals = this.#tokens.get(name) ?? emptyModelTotals();
+    totals.requests += 1;
+    totals.prompt += nonNegative(usage.promptTokens);
+    totals.completion += nonNegative(usage.completionTokens);
+    totals.total += nonNegative(usage.totalTokens);
+    totals.reasoning += nonNegative(usage.reasoningTokens ?? 0);
+    totals.cached += nonNegative(usage.cachedTokens ?? 0);
+    this.#tokens.set(name, totals);
+  }
+  /** Record one upstream Copilot call and whether it succeeded. */
+  recordUpstream(path, ok) {
+    const key = labelKey(path, ok ? "ok" : "error");
+    this.#upstream.set(key, (this.#upstream.get(key) ?? 0) + 1);
+  }
+  /** Store the latest Copilot quota so /metrics can expose it as gauges. */
+  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.
+  #modelLabel(model) {
+    const cleaned = model.replace(/[\u0000-\u001f\u007f]/g, "").trim().slice(0, MAX_MODEL_LABEL_LENGTH) || UNKNOWN_MODEL;
+    if (!this.#tokens.has(cleaned) && this.#tokens.size >= MAX_TRACKED_MODELS) {
+      return UNKNOWN_MODEL;
+    }
+    return cleaned;
+  }
+  #observeDuration(route, seconds) {
+    const value = Number.isFinite(seconds) && seconds >= 0 ? seconds : 0;
+    const entry = this.#durations.get(route) ?? {
+      buckets: new Array(DURATION_BUCKETS_SECONDS.length).fill(0),
+      count: 0,
+      sum: 0
+    };
+    entry.count += 1;
+    entry.sum += value;
+    const index = DURATION_BUCKETS_SECONDS.findIndex((bound) => value <= bound);
+    if (index !== -1) {
+      entry.buckets[index] = (entry.buckets[index] ?? 0) + 1;
+    }
+    this.#durations.set(route, entry);
+  }
+  /** A JSON-friendly view of the current counters. */
+  snapshot(now = Date.now) {
+    const byRoute = {};
+    const byStatus = {};
+    let requestsTotal = 0;
+    for (const [key, count] of this.#requests) {
+      const [route = "", , status = ""] = key.split(LABEL_SEPARATOR);
+      byRoute[route] = (byRoute[route] ?? 0) + count;
+      byStatus[status] = (byStatus[status] ?? 0) + count;
+      requestsTotal += count;
+    }
+    const byModel = {};
+    const tokenTotals = { cached: 0, completion: 0, prompt: 0, reasoning: 0, total: 0 };
+    for (const [model, totals] of this.#tokens) {
+      byModel[model] = { ...totals };
+      tokenTotals.prompt += totals.prompt;
+      tokenTotals.completion += totals.completion;
+      tokenTotals.total += totals.total;
+      tokenTotals.reasoning += totals.reasoning;
+      tokenTotals.cached += totals.cached;
+    }
+    let upstreamTotal = 0;
+    let upstreamErrors = 0;
+    for (const [key, count] of this.#upstream) {
+      upstreamTotal += count;
+      if (key.endsWith(`${LABEL_SEPARATOR}error`)) {
+        upstreamErrors += count;
+      }
+    }
+    return {
+      inFlight: this.#inFlight,
+      requests: { byRoute, byStatus, total: requestsTotal },
+      startedAt: new Date(this.#startedAtMs).toISOString(),
+      tokens: { byModel, ...tokenTotals },
+      upstream: { errors: upstreamErrors, total: upstreamTotal },
+      uptimeSeconds: Math.max(0, Math.round((now() - this.#startedAtMs) / 1e3))
+    };
+  }
+  /** Render the Prometheus text exposition format (version 0.0.4). */
+  renderPrometheus(now = Date.now) {
+    const lines = [];
+    lines.push("# HELP hoopilot_process_start_time_seconds Unix epoch when the proxy started.");
+    lines.push("# TYPE hoopilot_process_start_time_seconds gauge");
+    lines.push(`hoopilot_process_start_time_seconds ${this.#startedAtMs / 1e3}`);
+    lines.push("# HELP hoopilot_uptime_seconds Seconds since the proxy started.");
+    lines.push("# TYPE hoopilot_uptime_seconds gauge");
+    lines.push(`hoopilot_uptime_seconds ${Math.max(0, (now() - this.#startedAtMs) / 1e3)}`);
+    lines.push("# HELP hoopilot_requests_in_flight Requests currently being served.");
+    lines.push("# TYPE hoopilot_requests_in_flight gauge");
+    lines.push(`hoopilot_requests_in_flight ${this.#inFlight}`);
+    lines.push("# HELP hoopilot_requests_total Completed requests by route, method, and status.");
+    lines.push("# TYPE hoopilot_requests_total counter");
+    for (const [key, count] of this.#requests) {
+      const [route = "", method = "", status = ""] = key.split(LABEL_SEPARATOR);
+      lines.push(`hoopilot_requests_total${labels({ method, route, status })} ${count}`);
+    }
+    lines.push(
+      "# HELP hoopilot_upstream_requests_total Copilot upstream calls by path and outcome."
+    );
+    lines.push("# TYPE hoopilot_upstream_requests_total counter");
+    for (const [key, count] of this.#upstream) {
+      const [path = "", outcome = ""] = key.split(LABEL_SEPARATOR);
+      lines.push(`hoopilot_upstream_requests_total${labels({ outcome, path })} ${count}`);
+    }
+    lines.push(
+      "# HELP hoopilot_tokens_total Tokens reported by upstream usage, by model and type."
+    );
+    lines.push("# TYPE hoopilot_tokens_total counter");
+    for (const [model, totals] of this.#tokens) {
+      lines.push(`hoopilot_tokens_total${labels({ model, type: "prompt" })} ${totals.prompt}`);
+      lines.push(
+        `hoopilot_tokens_total${labels({ model, type: "completion" })} ${totals.completion}`
+      );
+      lines.push(
+        `hoopilot_tokens_total${labels({ model, type: "reasoning" })} ${totals.reasoning}`
+      );
+      lines.push(`hoopilot_tokens_total${labels({ model, type: "cached" })} ${totals.cached}`);
+    }
+    lines.push("# HELP hoopilot_model_requests_total Completions with usage observed, by model.");
+    lines.push("# TYPE hoopilot_model_requests_total counter");
+    for (const [model, totals] of this.#tokens) {
+      lines.push(`hoopilot_model_requests_total${labels({ model })} ${totals.requests}`);
+    }
+    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) {
+      let cumulative = 0;
+      for (let i = 0; i < DURATION_BUCKETS_SECONDS.length; i += 1) {
+        cumulative += entry.buckets[i] ?? 0;
+        const le = formatNumber(DURATION_BUCKETS_SECONDS[i] ?? 0);
+        lines.push(
+          `hoopilot_request_duration_seconds_bucket${labels({ le, route })} ${cumulative}`
+        );
+      }
+      lines.push(
+        `hoopilot_request_duration_seconds_bucket${labels({ le: "+Inf", route })} ${entry.count}`
+      );
+      lines.push(`hoopilot_request_duration_seconds_sum${labels({ route })} ${entry.sum}`);
+      lines.push(`hoopilot_request_duration_seconds_count${labels({ route })} ${entry.count}`);
+    }
+    this.#renderCopilotQuota(lines);
+    return `${lines.join("\n")}
+`;
+  }
+  #renderCopilotQuota(lines) {
+    const usage = this.#copilotQuota;
+    if (!usage) {
+      return;
+    }
+    const categories = Object.entries(usage.quotas);
+    const gauge = (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)}`);
+      }
+    };
+    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(
+      "percent_remaining",
+      "Percent of quota remaining for the Copilot category.",
+      (q) => q.percentRemaining
+    );
+    const resetMs = usage.quotaResetDate ? Date.parse(usage.quotaResetDate) : Number.NaN;
+    if (Number.isFinite(resetMs)) {
+      lines.push(
+        "# HELP hoopilot_copilot_quota_reset_timestamp_seconds Unix epoch of the next reset."
+      );
+      lines.push("# TYPE hoopilot_copilot_quota_reset_timestamp_seconds gauge");
+      lines.push(`hoopilot_copilot_quota_reset_timestamp_seconds ${resetMs / 1e3}`);
+    }
+    if (usage.plan || usage.accessTypeSku) {
+      lines.push("# HELP hoopilot_copilot_info Copilot plan metadata as a constant-1 info gauge.");
+      lines.push("# TYPE hoopilot_copilot_info gauge");
+      lines.push(
+        `hoopilot_copilot_info${labels({
+          access_type_sku: usage.accessTypeSku ?? "",
+          plan: usage.plan ?? ""
+        })} 1`
+      );
+    }
+  }
+};
+function observeResponseUsage(response, fallbackModel, onUsage, signal) {
+  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(() => {
+  });
+  return new Response(clientBranch, {
+    headers: response.headers,
+    status: response.status,
+    statusText: response.statusText
+  });
+}
+async function consumeUsage(stream, isSse, fallbackModel, onUsage, signal) {
+  const reader = stream.getReader();
+  const onAbort = () => {
+    reader.cancel().catch(() => {
+    });
+  };
+  if (signal?.aborted) {
+    reader.cancel().catch(() => {
+    });
+  } else {
+    signal?.addEventListener("abort", onAbort, { once: true });
+  }
+  const decoder = new TextDecoder();
+  let model = fallbackModel;
+  let usage;
+  let buffer = "";
+  let bufferedBytes = 0;
+  let overflowed = false;
+  const consider = (payload) => {
+    const record = asRecord(payload);
+    const found = extractTokenUsage(record.usage) ?? extractTokenUsage(asRecord(record.response).usage);
+    if (found) {
+      usage = found;
+    }
+    const candidateModel = modelText(record.model) || modelText(asRecord(record.response).model);
+    if (candidateModel) {
+      model = candidateModel;
+    }
+  };
+  try {
+    while (true) {
+      const result = await reader.read();
+      if (result.done) {
+        break;
+      }
+      const chunk = decoder.decode(result.value, { stream: true });
+      if (isSse) {
+        buffer += chunk;
+        const lines = buffer.split(/\r?\n/);
+        buffer = lines.pop() ?? "";
+        for (const line of lines) {
+          considerSseLine(line, consider);
+        }
+        if (buffer.length > USAGE_BUFFER_LIMIT_BYTES) {
+          buffer = "";
+        }
+      } else if (!overflowed) {
+        bufferedBytes += result.value.byteLength;
+        if (bufferedBytes > USAGE_BUFFER_LIMIT_BYTES) {
+          overflowed = true;
+          buffer = "";
+        } else {
+          buffer += chunk;
+        }
+      }
+    }
+    const finalBuffer = buffer + decoder.decode();
+    if (isSse) {
+      if (finalBuffer) {
+        considerSseLine(finalBuffer, consider);
+      }
+    } else if (!overflowed && finalBuffer) {
+      const parsed = safeParse(finalBuffer);
+      if (parsed !== void 0) {
+        consider(parsed);
+      }
+    }
+  } finally {
+    signal?.removeEventListener("abort", onAbort);
+    reader.releaseLock();
+  }
+  if (usage) {
+    onUsage(model, usage);
+  }
+}
+function considerSseLine(line, consider) {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith("data:")) {
+    return;
+  }
+  const data = trimmed.slice("data:".length).trim();
+  if (!data || data === "[DONE]") {
+    return;
+  }
+  const parsed = safeParse(data);
+  if (parsed !== void 0) {
+    consider(parsed);
+  }
+}
+function safeParse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+function modelText(value) {
+  return typeof value === "string" ? value.trim() : "";
+}
+function nonNegative(value) {
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}
+function labelKey(...parts) {
+  return parts.join(LABEL_SEPARATOR);
+}
+function labels(pairs) {
+  const entries = Object.entries(pairs);
+  if (entries.length === 0) {
+    return "";
+  }
+  const rendered = entries.map(([name, value]) => `${name}="${escapeLabelValue(value)}"`);
+  return `{${rendered.join(",")}}`;
+}
+function escapeLabelValue(value) {
+  return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r");
+}
+function formatNumber(value) {
+  return Number.isInteger(value) ? value.toString() : String(value);
+}
+
 // src/server.ts
 var DEFAULT_HOST = "127.0.0.1";
 var DEFAULT_PORT = 4141;
 var INVALID_JSON_MESSAGE = "Request body must be valid JSON.";
+var USAGE_CACHE_TTL_MS = 6e4;
 function createHoopilotHandler(options = {}) {
   const client = new CopilotClient(options);
   const apiKey = options.apiKey ?? options.env?.HOOPILOT_API_KEY;
   const logger = serverLogger(options);
+  const metrics = options.metrics ?? new MetricsRegistry();
+  const readUsage = createUsageReader(client, metrics);
+  const recordTokens = (model, usage) => metrics.recordTokens(model, usage);
   return async (request) => {
     const startedAt = performance.now();
     const url = new URL(request.url);
     const apiPath = canonicalApiPath(url.pathname);
     const requestId = requestIdFor(request);
+    const route = routeFor(request.method, apiPath);
     const requestLogger = logger.child({
       method: request.method,
       path: url.pathname,
       requestId,
-      route: routeFor(request.method, apiPath)
+      route
+    });
+    metrics.startRequest();
+    const finish = (response) => finishResponse(response, {
+      logger: requestLogger,
+      method: request.method,
+      metrics,
+      requestId,
+      route,
+      startedAt
     });
     if (request.method === "OPTIONS") {
-      return finishResponse(new Response(null, { headers: corsHeaders() }), {
-        logger: requestLogger,
-        requestId,
-        startedAt
-      });
+      return finish(new Response(null, { headers: corsHeaders() }));
     }
     if (!isAuthorized(request, apiKey)) {
       requestLogger.warn({ event: "http.request.unauthorized" }, "invalid hoopilot api key");
-      return finishResponse(
-        jsonError(401, "invalid_api_key", "Invalid or missing Hoopilot API key."),
-        {
-          logger: requestLogger,
-          requestId,
-          startedAt
-        }
-      );
+      return finish(jsonError(401, "invalid_api_key", "Invalid or missing Hoopilot API key."));
     }
     try {
       if (request.method === "GET" && (apiPath === "/" || apiPath === "/healthz")) {
-        return finishResponse(
-          jsonResponse({
-            name: "hoopilot",
-            object: "health",
-            status: "ok"
-          }),
-          { logger: requestLogger, requestId, startedAt }
-        );
+        return finish(jsonResponse({ name: "hoopilot", object: "health", status: "ok" }));
+      }
+      if (request.method === "GET" && apiPath === "/metrics") {
+        return finish(metricsResponse(metrics));
+      }
+      if (request.method === "GET" && apiPath === "/v1/usage") {
+        return finish(await handleUsage(metrics, readUsage, request.signal));
       }
       if (request.method === "GET" && apiPath === "/v1/responses") {
-        return finishResponse(websocketUnsupportedResponse(), {
-          logger: requestLogger,
-          requestId,
-          startedAt
-        });
+        return finish(websocketUnsupportedResponse());
       }
       if (request.method === "GET" && apiPath === "/v1/models") {
-        return finishResponse(await handleModels(client, request.signal, requestLogger), {
-          logger: requestLogger,
-          requestId,
-          startedAt
-        });
+        return finish(await handleModels(client, metrics, request.signal, requestLogger));
       }
       if (request.method === "POST" && apiPath === "/v1/chat/completions") {
-        return finishResponse(await handleChatCompletions(client, request, requestLogger), {
-          logger: requestLogger,
-          requestId,
-          startedAt
-        });
+        return finish(
+          await handleChatCompletions(client, metrics, recordTokens, request, requestLogger)
+        );
       }
       if (request.method === "POST" && apiPath === "/v1/completions") {
-        return finishResponse(await handleCompletions(client, request, requestLogger), {
-          logger: requestLogger,
-          requestId,
-          startedAt
-        });
+        return finish(
+          await handleCompletions(client, metrics, recordTokens, request, requestLogger)
+        );
       }
       if (request.method === "POST" && apiPath === "/v1/responses") {
-        return finishResponse(await handleResponses(client, request, requestLogger), {
-          logger: requestLogger,
-          requestId,
-          startedAt
-        });
+        return finish(await handleResponses(client, metrics, recordTokens, request, requestLogger));
       }
-      return finishResponse(
-        jsonError(404, "not_found", `No route for ${request.method} ${url.pathname}.`),
-        { logger: requestLogger, requestId, startedAt }
-      );
+      return finish(jsonError(404, "not_found", `No route for ${request.method} ${url.pathname}.`));
     } catch (error) {
       if (error instanceof CopilotAuthError) {
         requestLogger.warn(
           { err: errorDetails(error), event: "copilot.auth.missing" },
           "copilot auth failed"
         );
-        return finishResponse(jsonError(401, "copilot_auth_error", error.message), {
-          logger: requestLogger,
-          requestId,
-          startedAt
-        });
+        return finish(jsonError(401, "copilot_auth_error", error.message));
       }
       const message = errorMessage(error);
       if (message === INVALID_JSON_MESSAGE) {
@@ -628,11 +1116,7 @@ function createHoopilotHandler(options = {}) {
           "request failed"
         );
       }
-      return finishResponse(jsonError(500, "internal_error", message), {
-        logger: requestLogger,
-        requestId,
-        startedAt
-      });
+      return finish(jsonError(500, "internal_error", message));
     }
   };
 }
@@ -661,8 +1145,9 @@ function startHoopilotServer(options = {}) {
     url: `http://${host}:${server.port}`
   };
 }
-async function handleModels(client, signal, logger) {
+async function handleModels(client, metrics, signal, logger) {
   const upstream = await client.models(signal);
+  metrics.recordUpstream("/models", upstream.ok);
   if (!upstream.ok) {
     if (isUpstreamAuthStatus(upstream.status)) {
       return proxyError(upstream, logger);
@@ -680,38 +1165,50 @@ async function handleModels(client, signal, logger) {
   logUpstreamSuccess(logger, "/models", upstream.status);
   return jsonResponse(normalizeModelsResponse(await upstream.json()));
 }
-async function handleChatCompletions(client, request, logger) {
+async function handleChatCompletions(client, metrics, recordTokens, request, logger) {
   const chatRequest = normalizeChatCompletionRequest(await readJson(request));
   const upstream = await client.chatCompletions(chatRequest, request.signal);
+  metrics.recordUpstream("/chat/completions", upstream.ok);
   if (!upstream.ok) {
     return proxyError(upstream, logger);
   }
   logUpstreamSuccess(logger, "/chat/completions", upstream.status);
-  return proxyResponse(upstream);
+  const model = normalizeRequestedModel(chatRequest.model);
+  return proxyResponse(observeResponseUsage(upstream, model, recordTokens, request.signal));
 }
-async function handleCompletions(client, request, logger) {
+async function handleCompletions(client, metrics, recordTokens, request, logger) {
   const body = await readJson(request);
   const upstream = await client.chatCompletions(
     completionsRequestToChatCompletion(body),
     request.signal
   );
+  metrics.recordUpstream("/chat/completions", upstream.ok);
   if (!upstream.ok) {
     return proxyError(upstream, logger);
   }
   logUpstreamSuccess(logger, "/chat/completions", upstream.status);
+  const model = normalizeRequestedModel(body.model);
   if (isStreamingResponse(upstream)) {
-    return proxyResponse(upstream);
+    return proxyResponse(observeResponseUsage(upstream, model, recordTokens, request.signal));
   }
-  return jsonResponse(chatCompletionToCompletion(await upstream.json()));
+  const completion = asRecord(await upstream.json());
+  const usage = extractTokenUsage(completion.usage);
+  if (usage) {
+    const responseModel = typeof completion.model === "string" ? completion.model.trim() : "";
+    recordTokens(responseModel || model, usage);
+  }
+  return jsonResponse(chatCompletionToCompletion(completion));
 }
-async function handleResponses(client, request, logger) {
+async function handleResponses(client, metrics, recordTokens, request, logger) {
   const body = await readJsonText(request);
   const upstream = await client.responses(body, request.signal);
+  metrics.recordUpstream("/responses", upstream.ok);
   if (!upstream.ok) {
     return proxyError(upstream, logger);
   }
   logUpstreamSuccess(logger, "/responses", upstream.status);
-  return proxyResponse(upstream);
+  const model = normalizeRequestedModel(asRecord(safeParseJson(body)).model);
+  return proxyResponse(observeResponseUsage(upstream, model, recordTokens, request.signal));
 }
 async function proxyError(upstream, logger) {
   const text = await upstream.text();
@@ -830,7 +1327,21 @@ function serverLogger(options) {
 }
 function finishResponse(response, options) {
   const withRequestId = responseWithRequestId(response, options.requestId);
-  logRequestCompleted(options.logger, withRequestId, options.startedAt);
+  const stream = isStreamingResponse(withRequestId);
+  const status = withRequestId.status;
+  const complete = () => {
+    const durationMs = Math.round((performance.now() - options.startedAt) * 100) / 100;
+    options.metrics.observe({ durationMs, method: options.method, route: options.route, status });
+    logRequestCompleted(options.logger, status, stream, durationMs);
+  };
+  if (stream && withRequestId.body) {
+    return new Response(trackStreamCompletion(withRequestId.body, complete), {
+      headers: withRequestId.headers,
+      status,
+      statusText: withRequestId.statusText
+    });
+  }
+  complete();
   return withRequestId;
 }
 function responseWithRequestId(response, requestId) {
@@ -842,18 +1353,48 @@ function responseWithRequestId(response, requestId) {
     statusText: response.statusText
   });
 }
-function logRequestCompleted(logger, response, startedAt) {
+function trackStreamCompletion(body, onComplete) {
+  const reader = body.getReader();
+  let fired = false;
+  const fire = () => {
+    if (!fired) {
+      fired = true;
+      onComplete();
+    }
+  };
+  return new ReadableStream({
+    async pull(controller) {
+      try {
+        const { done, value } = await reader.read();
+        if (done) {
+          controller.close();
+          fire();
+          return;
+        }
+        controller.enqueue(value);
+      } catch (error) {
+        fire();
+        controller.error(error);
+      }
+    },
+    cancel(reason) {
+      fire();
+      return reader.cancel(reason);
+    }
+  });
+}
+function logRequestCompleted(logger, status, stream, durationMs) {
   const fields = {
-    durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
+    durationMs,
     event: "http.request.completed",
-    status: response.status,
-    stream: isStreamingResponse(response)
+    status,
+    stream
   };
-  if (response.status >= 500) {
+  if (status >= 500) {
     logger.error(fields, "request completed with server error");
     return;
   }
-  if (response.status >= 400) {
+  if (status >= 400) {
     logger.warn(fields, "request completed with client error");
     return;
   }
@@ -874,6 +1415,8 @@ function canonicalApiPath(path) {
       return "/v1/completions";
     case "/responses":
       return "/v1/responses";
+    case "/usage":
+      return "/v1/usage";
     default:
       return withoutTrailingSlash;
   }
@@ -885,6 +1428,12 @@ function routeFor(method, path) {
   if (method === "GET" && (path === "/" || path === "/healthz")) {
     return "health";
   }
+  if (method === "GET" && path === "/metrics") {
+    return "metrics";
+  }
+  if (method === "GET" && path === "/v1/usage") {
+    return "usage";
+  }
   if (method === "GET" && path === "/v1/models") {
     return "models";
   }
@@ -915,6 +1464,57 @@ function logUpstreamSuccess(logger, upstreamPath, status) {
     "copilot upstream request completed"
   );
 }
+function metricsResponse(metrics) {
+  return new Response(metrics.renderPrometheus(), {
+    headers: {
+      ...corsHeaders(),
+      "content-type": PROMETHEUS_CONTENT_TYPE
+    },
+    status: 200
+  });
+}
+async function handleUsage(metrics, readUsage, signal) {
+  const proxy = metrics.snapshot();
+  const { copilot, error } = await readUsage(signal);
+  const body = { copilot: copilot ?? null, object: "usage", proxy };
+  if (error) {
+    body.copilot_error = error;
+  }
+  return jsonResponse(body);
+}
+function createUsageReader(client, metrics, now = Date.now, ttlMs = USAGE_CACHE_TTL_MS) {
+  const usagePath = "/copilot_internal/user";
+  let cache;
+  return async (signal) => {
+    if (cache && now() - cache.atMs < ttlMs) {
+      return { copilot: cache.value };
+    }
+    try {
+      const upstream = await client.usage(signal);
+      metrics.recordUpstream(usagePath, upstream.ok);
+      if (!upstream.ok) {
+        return { error: `GitHub Copilot usage request failed with ${upstream.status}.` };
+      }
+      const value = normalizeCopilotUsage(await upstream.json().catch(() => ({})));
+      cache = { atMs: now(), value };
+      metrics.recordCopilotQuota(value);
+      return { copilot: value };
+    } catch (error) {
+      metrics.recordUpstream(usagePath, false);
+      if (error instanceof CopilotAuthError) {
+        return { error: error.message };
+      }
+      return { error: errorMessage(error) };
+    }
+  };
+}
+function safeParseJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
 
 // src/update.ts
 import { execFileSync } from "child_process";
@@ -1474,6 +2074,16 @@ async function main(argv = Bun.argv.slice(2)) {
     await runModels(args2);
     return;
   }
+  if (command === "usage") {
+    const args2 = withRuntimeEnv(parseArgs(argv.slice(1)));
+    if (args2.help) {
+      console.log(helpText(await getVersion()));
+      return;
+    }
+    args2.logger = commandLogger(args2, "usage");
+    await runUsage(args2);
+    return;
+  }
   const args = withRuntimeEnv(parseArgs(argv));
   if (args.help) {
     console.log(helpText(await getVersion()));
@@ -1619,6 +2229,87 @@ async function runModels(options = {}) {
   }
   return ids;
 }
+async function runUsage(options = {}) {
+  const logger = options.logger?.child({ component: "usage" }) ?? noopLogger;
+  logger.debug({ event: "usage.fetch.started" }, "fetching github copilot quota");
+  const response = await new CopilotClient(options).usage();
+  if (!response.ok) {
+    const message = `GitHub Copilot usage request failed with ${response.status}: ${await truncatedResponseText(response)}`;
+    if (response.status === 401 || response.status === 403) {
+      throw new CopilotAuthError(message);
+    }
+    throw new Error(message);
+  }
+  const usage = normalizeCopilotUsage(await response.json().catch(() => ({})));
+  logger.debug(
+    { event: "usage.fetch.succeeded", plan: usage.plan },
+    "github copilot quota fetched"
+  );
+  for (const line of formatCopilotUsage(usage)) {
+    console.log(line);
+  }
+  return usage;
+}
+function formatCopilotUsage(usage) {
+  const lines = [];
+  if (usage.plan) {
+    lines.push(`Plan: ${usage.plan}`);
+  }
+  if (usage.quotaResetDate) {
+    lines.push(`Quota resets: ${usage.quotaResetDate}`);
+  }
+  const order = ["premium_interactions", "chat", "completions"];
+  const names = Object.keys(usage.quotas).sort(
+    (a, b) => quotaRank(order, a) - quotaRank(order, b) || a.localeCompare(b)
+  );
+  for (const name of names) {
+    const quota = usage.quotas[name];
+    if (quota) {
+      lines.push(`${quotaLabel(name)}: ${formatQuota(quota)}`);
+    }
+  }
+  if (lines.length === 0) {
+    lines.push("No GitHub Copilot quota information available for this account.");
+  }
+  return lines;
+}
+function quotaRank(order, name) {
+  const index = order.indexOf(name);
+  return index === -1 ? order.length : index;
+}
+function quotaLabel(name) {
+  switch (name) {
+    case "premium_interactions":
+      return "Premium requests";
+    case "chat":
+      return "Chat";
+    case "completions":
+      return "Completions";
+    default:
+      return name;
+  }
+}
+function formatQuota(quota) {
+  if (quota.unlimited) {
+    return "unlimited";
+  }
+  const parts = [];
+  if (quota.used !== void 0 && quota.entitlement !== void 0) {
+    parts.push(`${roundQuota(quota.used)}/${roundQuota(quota.entitlement)} used`);
+  } else if (quota.remaining !== void 0) {
+    parts.push(`${roundQuota(quota.remaining)} remaining`);
+  }
+  if (quota.percentRemaining !== void 0) {
+    parts.push(`${roundQuota(quota.percentRemaining)}% remaining`);
+  }
+  if (quota.overageCount) {
+    parts.push(`${roundQuota(quota.overageCount)} overage`);
+  }
+  return parts.length > 0 ? parts.join(", ") : "n/a";
+}
+function roundQuota(value) {
+  return Number.isInteger(value) ? value : Math.round(value * 10) / 10;
+}
 async function verifyCopilotOAuthToken(token, options = {}) {
   const apiBaseUrl = trimTrailingSlash(
     options.copilotApiBaseUrl ?? options.env?.COPILOT_API_BASE_URL ?? DEFAULT_COPILOT_API_BASE_URL
@@ -1689,6 +2380,7 @@ Usage:
   hoopilot [serve] [options]
   hoopilot login [options]
   hoopilot models [options]
+  hoopilot usage [options]
   hoopilot update
   npx @openhoo/hoopilot [options]
 
@@ -1696,8 +2388,13 @@ Commands:
   serve                             Start the proxy server (default)
   login                             Sign in through GitHub OAuth in a browser and verify Copilot access
   models                            List available GitHub Copilot model IDs
+  usage                             Show GitHub Copilot quota and premium-request usage
   update, upgrade                   Update hoopilot to the latest release
 
+While the server runs, GET /metrics exposes Prometheus metrics (request counts,
+token usage, latency) and GET /v1/usage returns those metrics plus live Copilot
+quota as JSON.
+
 Options:
   -p, --port <port>                 Port to listen on. Default: 4141
       --host <host>                 Host to listen on. Default: 127.0.0.1
@@ -1719,6 +2416,7 @@ Environment:
   HOOPILOT_LOG_FORMAT               json or pretty. Default: pretty
   HOOPILOT_LOG_LEVEL                trace, debug, info, warn, error, fatal, or silent
   COPILOT_API_BASE_URL
+  HOOPILOT_GITHUB_API_BASE_URL      GitHub REST base for the usage/quota lookup. Default: https://api.github.com
   HOOPILOT_NO_UPDATE_CHECK          Set to disable update checks (also NO_UPDATE_NOTIFIER)
 `;
 }
@@ -1732,6 +2430,7 @@ export {
   main,
   parseArgs,
   runModels,
+  runUsage,
   verifyCopilotOAuthToken
 };
 //# sourceMappingURL=cli.js.map