feat(usage): fetch SuperGrok weekly pool via gRPC-web

Decode GetGrokCreditsConfig frames when REST billing returns empty
caps, so SuperGrok weekly quota shows in the usage dashboard.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

tests/unit/grok-cli-usage.test.js

@@ -169,6 +169,67 @@ describe("parseGrokCliBilling", () => {
   });
 });
 
+function encodeVarint(value) {
+  const bytes = [];
+  let v = BigInt(value);
+  do {
+    let byte = Number(v & 0x7fn);
+    v >>= 7n;
+    if (v !== 0n) byte |= 0x80;
+    bytes.push(byte);
+  } while (v !== 0n);
+  return Buffer.from(bytes);
+}
+
+function encodeTag(fieldNumber, wireType) {
+  return encodeVarint((fieldNumber << 3) | wireType);
+}
+
+function encodeFixed32Field(fieldNumber, value) {
+  const body = Buffer.alloc(4);
+  body.writeFloatLE(value, 0);
+  return Buffer.concat([encodeTag(fieldNumber, 5), body]);
+}
+
+function encodeLengthDelimited(fieldNumber, body) {
+  return Buffer.concat([encodeTag(fieldNumber, 2), encodeVarint(body.length), body]);
+}
+
+function encodeVarintField(fieldNumber, value) {
+  return Buffer.concat([encodeTag(fieldNumber, 0), encodeVarint(value)]);
+}
+
+function encodeTimestampField(fieldNumber, seconds, nanos) {
+  const parts = [];
+  if (seconds !== 0) parts.push(encodeVarintField(1, seconds));
+  if (nanos !== 0) parts.push(encodeVarintField(2, nanos));
+  return encodeLengthDelimited(fieldNumber, Buffer.concat(parts));
+}
+
+/** Framed GetGrokCreditsConfig response for a usage ratio 0..1. */
+function buildCreditsResponseBuffer(usageRatio, resetSeconds = 1784825940, resetNanos = 867850000) {
+  const creditsInfo = Buffer.concat([
+    encodeFixed32Field(1, usageRatio),
+    encodeTimestampField(5, resetSeconds, resetNanos),
+  ]);
+  const topMessage = encodeLengthDelimited(1, creditsInfo);
+  const header = Buffer.alloc(5);
+  header[0] = 0x00;
+  header.writeUInt32BE(topMessage.length, 1);
+  return Buffer.concat([header, topMessage]);
+}
+
+function binaryResponse(buffer, status = 200) {
+  return new Response(buffer, {
+    status,
+    headers: { "content-type": "application/grpc-web+proto" },
+  });
+}
+
+const EMPTY_GRPC_WEB_FRAME = Buffer.from([0, 0, 0, 0, 0]);
+const GRPC_CREDITS_URL =
+  "https://grok.com/grok_api_v2.GrokBuildBilling/GetGrokCreditsConfig";
+
 describe("getUsageForProvider(grok-cli)", () => {
   beforeEach(() => {
     vi.clearAllMocks();
@@ -211,6 +272,8 @@ describe("getUsageForProvider(grok-cli)", () => {
     expect(billingCall[1].headers["x-userid"]).toBe(
       "d84768dd-224d-4052-ba49-0d336fa9160c",
     );
+    // REST already has numeric quotas — do not hit gRPC fallback
+    expect(proxyAwareFetch.mock.calls).toHaveLength(2);
   });
 
   it("surfaces auth-expired message on 401", async () => {
@@ -224,6 +287,8 @@ describe("getUsageForProvider(grok-cli)", () => {
     });
 
     expect(usage.message).toMatch(/expired|re-authorize/i);
+    // Auth failure must not attempt gRPC fallback
+    expect(proxyAwareFetch.mock.calls).toHaveLength(2);
   });
 
   it("returns depleted on-demand bar without blocking message when cap is zero", async () => {
@@ -241,15 +306,62 @@ describe("getUsageForProvider(grok-cli)", () => {
     expect(usage.message).toBeUndefined();
     expect(usage.quotas["On-demand"].remainingPercentage).toBe(0);
     expect(usage.quotas["On-demand"].total).toBe(1);
+    // Exhausted free already has a quota bar — no gRPC fallback
+    expect(proxyAwareFetch.mock.calls).toHaveLength(2);
   });
 
-  it("reports active paid access when provider exposes no numeric quota", async () => {
+  it("falls back to GetGrokCreditsConfig gRPC when paid sub has no REST numeric quota", async () => {
+    const resetSeconds = 1784825940;
+    const resetNanos = 867850000;
+    const resetAt = new Date(
+      resetSeconds * 1000 + Math.round(resetNanos / 1_000_000),
+    ).toISOString();
+
     proxyAwareFetch
       .mockResolvedValueOnce(jsonResponse(EXHAUSTED_BILLING))
-      .mockResolvedValueOnce(jsonResponse({
-        ...USER_PROFILE,
-        subscriptionTier: "XPremiumPlus",
-      }));
+      .mockResolvedValueOnce(
+        jsonResponse({
+          ...USER_PROFILE,
+          subscriptionTier: "XPremiumPlus",
+        }),
+      )
+      .mockResolvedValueOnce(binaryResponse(buildCreditsResponseBuffer(0.35, resetSeconds, resetNanos)));
+
+    const usage = await getUsageForProvider({
+      provider: "grok-cli",
+      accessToken: "test-token",
+    });
+
+    expect(usage.message).toBeUndefined();
+    expect(usage.plan).toBe("XPremiumPlus");
+    expect(usage.quotas["Weekly SuperGrok"]).toMatchObject({
+      used: 35,
+      total: 100,
+      remainingPercentage: 65,
+      resetAt,
+      unlimited: false,
+    });
+
+    const grpcCall = proxyAwareFetch.mock.calls[2];
+    expect(grpcCall[0]).toBe(GRPC_CREDITS_URL);
+    expect(grpcCall[1].method).toBe("POST");
+    expect(grpcCall[1].headers.Authorization).toBe("Bearer test-token");
+    expect(grpcCall[1].headers["Content-Type"]).toBe("application/grpc-web+proto");
+    expect(grpcCall[1].headers["X-Grpc-Web"]).toBe("1");
+    // Empty gRPC-web request frame is required (flag 0 + length 0)
+    expect(Buffer.from(grpcCall[1].body)).toEqual(EMPTY_GRPC_WEB_FRAME);
+  });
+
+  it("keeps subscription message when REST empty and gRPC fails open", async () => {
+    proxyAwareFetch
+      .mockResolvedValueOnce(jsonResponse(EXHAUSTED_BILLING))
+      .mockResolvedValueOnce(
+        jsonResponse({
+          ...USER_PROFILE,
+          subscriptionTier: "XPremiumPlus",
+        }),
+      )
+      .mockResolvedValueOnce(binaryResponse(Buffer.alloc(0), 500));
 
     const usage = await getUsageForProvider({
       provider: "grok-cli",
@@ -260,6 +372,26 @@ describe("getUsageForProvider(grok-cli)", () => {
     expect(usage.message).toMatch(/active.*numeric included quota/i);
     expect(usage.quotas).toEqual({});
   });
+
+  it("does not throw when gRPC network fails after empty REST quotas", async () => {
+    proxyAwareFetch
+      .mockResolvedValueOnce(jsonResponse(EXHAUSTED_BILLING))
+      .mockResolvedValueOnce(
+        jsonResponse({
+          ...USER_PROFILE,
+          subscriptionTier: "XPremiumPlus",
+        }),
+      )
+      .mockRejectedValueOnce(new Error("network down"));
+
+    const usage = await getUsageForProvider({
+      provider: "grok-cli",
+      accessToken: "test-token",
+    });
+
+    expect(usage.message).toMatch(/active.*numeric included quota/i);
+    expect(usage.quotas).toEqual({});
+  });
 });
 
 describe("parseQuotaData(grok-cli)", () => {