feat: expose user billing usage summary

internal/cloud/server.ts

@@ -314,6 +314,11 @@ async function handleRestAdapter(request, response, url, options) {
     return;
   }
 
+  if (url.pathname === "/v1/usage/summary" && request.method === "GET") {
+    await handleUsageSummaryHttp(request, response, url, options);
+    return;
+  }
+
   if (request.method === "GET" && url.pathname === "/v1") {
     const dbProbe = await buildDbRuntimeReadiness(options.env ?? process.env, options.dbProbe);
     const codeAgent = await describeCodeAgentAvailability(options.env ?? process.env, options);
@@ -936,6 +941,53 @@ async function codeAgentOptions(request, response, options, authOptions = {}) {
   };
 }
 
+async function handleUsageSummaryHttp(request, response, url, options) {
+  const nextOptions = await codeAgentOptions(request, response, options, { required: true });
+  if (!nextOptions) return;
+  const client = nextOptions.userBillingClient;
+  const token = bearerTokenFromRequest(request);
+  if (nextOptions.userBillingAuth?.active !== true || !token) {
+    sendRestError(request, response, 403, "user_billing_auth_required", "usage summary requires a user-billing bearer token", {
+      operation: "GET /v1/usage/summary",
+      target: { type: "route", id: "/v1/usage/summary" },
+      result: "rejected"
+    });
+    return;
+  }
+  if (!client?.configured || typeof client.billingSummary !== "function") {
+    sendRestError(request, response, 503, "user_billing_not_configured", "HWLAB user-billing summary is not configured", {
+      operation: "GET /v1/usage/summary",
+      target: { type: "service", id: "hwlab-user-billing" }
+    });
+    return;
+  }
+  const limit = parsePositiveInteger(url.searchParams.get("limit"), 20);
+  const result = await client.billingSummary(token, { limit: Math.min(limit, 100) });
+  if (!result.ok) {
+    sendRestError(request, response, result.status ?? 502, result.error?.code ?? "user_billing_summary_failed", result.error?.message ?? "user-billing summary request failed", {
+      operation: "GET /v1/usage/summary",
+      target: { type: "service", id: "hwlab-user-billing" },
+      reason: result.error?.code,
+      result: "failed"
+    });
+    return;
+  }
+  sendJson(response, 200, {
+    ...(result.body ?? {}),
+    proxy: {
+      serviceId: CLOUD_API_SERVICE_ID,
+      route: "/v1/usage/summary",
+      source: "hwlab-user-billing",
+      valuesRedacted: true
+    }
+  });
+}
+
+function bearerTokenFromRequest(request) {
+  const header = String(getHeader(request, "authorization") ?? "").trim();
+  return header.toLowerCase().startsWith("bearer ") ? header.slice(7).trim() : "";
+}
+
 async function readJsonObject(request, limitBytes) {
   const body = await readBody(request, limitBytes);
   try {