n9router 0.4.50 → 0.4.52

package/app/open-sse/services/tokenRefresh.js

@@ -3,30 +3,38 @@ import { OAUTH_ENDPOINTS, REFRESH_LEAD_MS } from "../config/appConstants.js";
 import {
   refreshXaiToken,
   refreshAccessToken,
+  refreshKimiToken,
   refreshClaudeOAuthToken,
   refreshGoogleToken,
-  refreshQwenToken,
   refreshCodexToken,
   refreshKiroToken,
   refreshIflowToken,
   refreshGitHubToken,
   refreshCopilotToken,
   refreshCodebuddyToken,
+  refreshCodebuddyIntlToken,
+  refreshTraeToken,
+  refreshZedToken,
+  refreshWindsurfToken,
   classifyOAuthRefreshError,
 } from "./tokenRefresh/providers.js";
 
 // Re-export all provider refresh functions (preserves public API for all consumers)
 export {
   refreshAccessToken,
+  refreshKimiToken,
   refreshClaudeOAuthToken,
   refreshGoogleToken,
-  refreshQwenToken,
   refreshCodexToken,
   refreshKiroToken,
   refreshIflowToken,
   refreshGitHubToken,
   refreshCopilotToken,
   refreshCodebuddyToken,
+  refreshCodebuddyIntlToken,
+  refreshTraeToken,
+  refreshZedToken,
+  refreshWindsurfToken,
   classifyOAuthRefreshError,
 };
 
@@ -44,7 +52,10 @@ export function isUnrecoverableRefreshError(result) {
 }
 
 export function getRefreshLeadMs(provider) {
-  return REFRESH_LEAD_MS[provider] || TOKEN_EXPIRY_BUFFER_MS;
+  if (REFRESH_LEAD_MS[provider]) return REFRESH_LEAD_MS[provider];
+  // Legacy id after kimi-coding → kimi merge
+  if (provider === "kimi-coding" && REFRESH_LEAD_MS.kimi) return REFRESH_LEAD_MS.kimi;
+  return TOKEN_EXPIRY_BUFFER_MS;
 }
 
 export function parseVertexSaJson(apiKey) {
@@ -124,7 +135,6 @@ const REFRESH_HANDLERS = {
   antigravity: (c, log) => refreshGoogleToken(c.refreshToken, PROVIDERS.antigravity.clientId, PROVIDERS.antigravity.clientSecret, log),
   claude: (c, log) => refreshClaudeOAuthToken(c.refreshToken, log),
   codex: (c, log) => refreshCodexToken(c.refreshToken, log),
-  qwen: (c, log) => refreshQwenToken(c.refreshToken, log),
   iflow: (c, log) => refreshIflowToken(c.refreshToken, log),
   github: (c, log) => refreshGitHubToken(c.refreshToken, log),
   kiro: (c, log) => refreshKiroToken(c.refreshToken, c.providerSpecificData, log),
@@ -133,6 +143,13 @@ const REFRESH_HANDLERS = {
   "grok-cli": (c, log) => refreshXaiToken(c.refreshToken, log),
   gcli: (c, log) => refreshXaiToken(c.refreshToken, log),
   "codebuddy-cn": (c, log) => refreshCodebuddyToken(c.refreshToken, log),
+  "codebuddy-intl": (c, log) => refreshCodebuddyIntlToken(c.refreshToken, log),
+  trae: (c, log) => refreshTraeToken(c.refreshToken, c, log),
+  zed: () => refreshZedToken(),
+  windsurf: (c, log) => refreshWindsurfToken(c, log),
+  // Kimi Code OAuth (merged into id `kimi`); legacy id still routes here
+  kimi: (c, log) => refreshKimiToken(c.refreshToken, c, log),
+  "kimi-coding": (c, log) => refreshKimiToken(c.refreshToken, c, log),
   vertex: vertexRefreshHandler,
   "vertex-partner": vertexRefreshHandler
 };
@@ -185,7 +202,6 @@ export function formatProviderCredentials(provider, credentials, log) {
       };
 
     case "codex":
-    case "qwen":
     case "iflow":
     case "openai":
     case "openrouter":

package/app/open-sse/services/usage/codebuddy-cn.js

@@ -43,17 +43,17 @@ function refillCadence(acc) {
   return "Monthly";
 }
 
-export async function getCodeBuddyCnUsage(accessToken, apiKey, providerSpecificData, proxyOptions = null) {
+async function getCodeBuddyUsage(providerId, accessToken, apiKey, providerSpecificData, proxyOptions = null) {
   const token = accessToken || apiKey;
   if (!token) {
-    return { message: "CodeBuddy CN credential not available." };
+    return { message: `CodeBuddy (${providerId}) credential not available.` };
   }
 
   try {
-    const response = await proxyAwareFetch(U(PROVIDER_ID).url, {
+    const response = await proxyAwareFetch(U(providerId).url, {
       method: "POST",
       headers: {
-        ...(PROVIDERS[PROVIDER_ID]?.headers || {}),
+        ...(PROVIDERS[providerId]?.headers || {}),
         Authorization: `Bearer ${token}`,
         "Content-Type": "application/json",
         Accept: "application/json",
@@ -129,10 +129,18 @@ export async function getCodeBuddyCnUsage(accessToken, apiKey, providerSpecificD
     });
 
     const basePkg = refills[0] || accounts[0] || {};
-    const plan = basePkg.PackageName || basePkg.SubProductName || "CodeBuddy CN";
+    const plan = basePkg.PackageName || basePkg.SubProductName || "CodeBuddy";
 
     return { plan, quotas };
   } catch (error) {
-    return { message: `CodeBuddy CN error: ${error.message}` };
+    return { message: `CodeBuddy (${providerId}) error: ${error.message}` };
   }
 }
+
+export async function getCodeBuddyCnUsage(accessToken, apiKey, providerSpecificData, proxyOptions = null) {
+  return getCodeBuddyUsage(PROVIDER_ID, accessToken, apiKey, providerSpecificData, proxyOptions);
+}
+
+export async function getCodeBuddyIntlUsage(accessToken, apiKey, providerSpecificData, proxyOptions = null) {
+  return getCodeBuddyUsage("codebuddy-intl", accessToken, apiKey, providerSpecificData, proxyOptions);
+}

package/app/open-sse/services/usage/deepseek.js

@@ -0,0 +1,112 @@
+/**
+ * DeepSeek usage — GET https://api.deepseek.com/user/balance
+ * Auth: Bearer <apiKey>
+ */
+
+import { proxyAwareFetch } from "../../utils/proxyFetch.js";
+import { toFiniteNumber } from "./shared.js";
+
+const BALANCE_URL = "https://api.deepseek.com/user/balance";
+
+function parseBalanceInfos(data) {
+  const list = Array.isArray(data?.balance_infos) ? data.balance_infos : [];
+  const results = [];
+  for (const item of list) {
+    if (!item || typeof item !== "object") continue;
+    const currency =
+      typeof item.currency === "string" ? item.currency.toUpperCase() : "";
+    if (!currency) continue;
+    const totalBalance = toFiniteNumber(
+      item.total_balance ?? item.totalBalance,
+      0,
+    );
+    results.push({
+      currency,
+      totalBalance,
+      grantedBalance: toFiniteNumber(
+        item.granted_balance ?? item.grantedBalance,
+        0,
+      ),
+      toppedUpBalance: toFiniteNumber(
+        item.topped_up_balance ?? item.toppedUpBalance,
+        0,
+      ),
+    });
+  }
+  return results;
+}
+
+/**
+ * @param {string|null|undefined} apiKey
+ * @param {object|null} proxyOptions
+ */
+export async function getDeepseekUsage(apiKey = null, proxyOptions = null) {
+  if (!apiKey || typeof apiKey !== "string" || !apiKey.trim()) {
+    return { message: "DeepSeek API key not available. Add a key to view usage." };
+  }
+
+  try {
+    const response = await proxyAwareFetch(
+      BALANCE_URL,
+      {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${apiKey.trim()}`,
+          "Content-Type": "application/json",
+          Accept: "application/json",
+        },
+      },
+      proxyOptions,
+    );
+
+    if (response.status === 401 || response.status === 403) {
+      return {
+        plan: "DeepSeek",
+        message: "DeepSeek authentication failed. Check the API key.",
+      };
+    }
+
+    if (!response.ok) {
+      const errText = await response.text().catch(() => "");
+      return {
+        plan: "DeepSeek",
+        message: `DeepSeek balance API error (${response.status})${errText ? `: ${errText.slice(0, 120)}` : ""}`,
+      };
+    }
+
+    const data = await response.json().catch(() => null);
+    if (!data || typeof data !== "object") {
+      return { message: "DeepSeek balance response was not JSON." };
+    }
+
+    const balances = parseBalanceInfos(data);
+    if (balances.length === 0) {
+      return {
+        plan: "DeepSeek",
+        message: "DeepSeek connected. No balance data returned.",
+      };
+    }
+
+    const isAvailable = data.is_available === true || data.isAvailable === true;
+    const quotas = {};
+    for (const b of balances) {
+      const total = Math.max(0, b.totalBalance);
+      // Credit pot: show full remaining against current balance; never set absolute
+      // `remaining` — QuotaTable treats it as a 0–100 percentage.
+      quotas[`Balance (${b.currency})`] = {
+        used: 0,
+        total,
+        remainingPercentage: total > 0 ? 100 : 0,
+        resetAt: null,
+        unlimited: total > 0,
+      };
+    }
+
+    return {
+      plan: isAvailable ? "DeepSeek" : "DeepSeek (Insufficient Balance)",
+      quotas,
+    };
+  } catch (error) {
+    return { message: `DeepSeek error: ${error.message}` };
+  }
+}

package/app/open-sse/services/usage/google.js

@@ -122,7 +122,7 @@ export async function getAntigravityUsage(accessToken, providerSpecificData, pro
     const subscriptionInfo = await getAntigravitySubscriptionInfo(accessToken, proxyOptions);
     const projectId = subscriptionInfo?.cloudaicompanionProject || null;
 
-    const requestOptions = {
+    const response = await fetchWithTimeout(ANTIGRAVITY_CONFIG.quotaApiUrl, {
       method: "POST",
       headers: {
         "Authorization": `Bearer ${accessToken}`,
@@ -134,39 +134,18 @@ export async function getAntigravityUsage(accessToken, providerSpecificData, pro
       body: JSON.stringify({
         ...(projectId ? { project: projectId } : {})
       }),
-    };
-    let response = await fetchWithTimeout(
-      ANTIGRAVITY_CONFIG.quotaApiUrl,
-      requestOptions,
-      10000,
-      proxyOptions,
-    );
-
-    // Some Antigravity accounts reject quota requests carrying the project id
-    // even though loadCodeAssist returned it. Retry once without the project.
-    if (response.status === 403 && projectId) {
-      response = await fetchWithTimeout(
-        ANTIGRAVITY_CONFIG.quotaApiUrl,
-        { ...requestOptions, body: JSON.stringify({}) },
-        10000,
-        proxyOptions,
-      );
-    }
+    }, 10000, proxyOptions);
 
     if (response.status === 403) {
       return {
-        plan: subscriptionInfo?.subscriptionTier || "Unknown",
         message: "Antigravity quota API access forbidden. Chat may still work.",
-        isForbidden: true,
         quotas: {}
       };
     }
 
     if (response.status === 401) {
       return {
-        plan: subscriptionInfo?.subscriptionTier || "Unknown",
         message: "Antigravity quota API authentication expired. Chat may still work.",
-        isExpired: true,
         quotas: {}
       };
     }
@@ -180,22 +159,30 @@ export async function getAntigravityUsage(accessToken, providerSpecificData, pro
 
     // Parse model quotas (inspired by vscode-antigravity-cockpit)
     if (data.models) {
+      // Filter only recommended/important models (must match PROVIDER_MODELS ag ids)
+      const importantModels = [
+        'gemini-3.6-flash-high',
+        'gemini-3.6-flash-medium',
+        'gemini-3.6-flash-low',
+        'gemini-3.5-flash-low',
+        'gemini-3.5-flash-extra-low',
+        'gemini-pro-agent',
+        'gemini-3.1-pro-low',
+        'claude-sonnet-4-6',
+        'claude-opus-4-6-thinking',
+        'gpt-oss-120b-medium',
+        // Image generation models
+        'gemini-3.1-flash-image',
+      ];
+
       for (const [modelKey, info] of Object.entries(data.models)) {
         // Skip models without quota info
         if (!info.quotaInfo) {
           continue;
         }
 
-        const matchesTarget =
-          modelKey === "claude-opus-4-6-thinking" ||
-          modelKey === "claude-sonnet-4-6" ||
-          modelKey.startsWith("gemini-3.1-pro-") ||
-          modelKey === "gemini-3.1-pro" ||
-          modelKey.startsWith("gemini-3.5-") ||
-          modelKey === "gemini-3.5" ||
-          modelKey === "gemini-3-flash-agent";
-
-        if (info.isInternal || !matchesTarget) {
+        // Skip internal models and non-important models
+        if (info.isInternal || !importantModels.includes(modelKey)) {
           continue;
         }
 
@@ -220,7 +207,7 @@ export async function getAntigravityUsage(accessToken, providerSpecificData, pro
     }
 
     return {
-      plan: subscriptionInfo?.subscriptionTier || "Unknown",
+      plan: subscriptionInfo?.currentTier?.name || "Unknown",
       quotas,
       subscriptionInfo,
     };
@@ -246,30 +233,7 @@ async function getAntigravitySubscriptionInfo(accessToken, proxyOptions = null)
     }, 10000, proxyOptions);
 
     if (!response.ok) return null;
-    const data = await response.json();
-    const paidTier = data.paidTier;
-    const currentTier = data.currentTier;
-    const allowedTiers = data.allowedTiers;
-    const ineligibleTiers = data.ineligibleTiers;
-    const isIneligible = Array.isArray(ineligibleTiers) && ineligibleTiers.length > 0;
-
-    let subscriptionTier = paidTier?.name || paidTier?.id || null;
-    if (!subscriptionTier) {
-      if (!isIneligible) {
-        subscriptionTier = currentTier?.name || currentTier?.id || null;
-      } else if (Array.isArray(allowedTiers)) {
-        const defaultTier = allowedTiers.find((tier) => tier.isDefault === true);
-        const nameOrId = defaultTier?.name || defaultTier?.id;
-        if (nameOrId) subscriptionTier = `${nameOrId} (Restricted)`;
-      }
-    }
-
-    if (!subscriptionTier && currentTier && !isIneligible) {
-      subscriptionTier = "Free";
-    }
-
-    data.subscriptionTier = subscriptionTier;
-    return data;
+    return await response.json();
   } catch (error) {
     console.error("[Antigravity Subscription] Error:", error.message);
     return null;

package/app/open-sse/services/usage/grok-cli.js

@@ -29,11 +29,19 @@ import {
   GROK_CLI_USER_AGENT,
   GROK_CLI_VERSION,
 } from "../../config/grokCli.js";
+import { decodeGrokCreditsFrame } from "./grokCliQuotaFrame.js";
 
 const USAGE = U("grok-cli");
 const BILLING_URL = USAGE.url || "https://cli-chat-proxy.grok.com/v1/billing?format=credits";
 const USER_URL = USAGE.userUrl || "https://cli-chat-proxy.grok.com/v1/user?include=subscription";
 
+// SuperGrok weekly pool.
+const GRPC_CREDITS_URL =
+  "https://grok.com/grok_api_v2.GrokBuildBilling/GetGrokCreditsConfig";
+// Empty gRPC-web request frame (flag 0 + length 0). Without it upstream returns
+// grpc-status 13 "Missing request message." with a 0-byte body.
+const GRPC_WEB_EMPTY_REQUEST_FRAME = Buffer.from([0, 0, 0, 0, 0]);
+
 /** Unwrap protobuf-json `{ val: n }` or plain numbers/strings. */
 function unwrapVal(value, fallback = 0) {
   if (value == null) return fallback;
@@ -83,6 +91,24 @@ function resolvePlan(user, config) {
   return "Grok Build";
 }
 
+// Display only; upstream remains authoritative for access and quota enforcement.
+function planFromAccessToken(accessToken) {
+  try {
+    const payload = JSON.parse(Buffer.from(accessToken.split(".")[1], "base64url"));
+    return {
+      0: "Free",
+      1: "SuperGrok",
+      2: "X Basic",
+      3: "X Premium",
+      4: "X Premium Plus",
+      5: "SuperGrok Heavy",
+      6: "SuperGrok Lite",
+    }[payload.tier] || "";
+  } catch {
+    return "";
+  }
+}
+
 function makeQuota({ used, total, resetAt, unlimited = false }) {
   const safeTotal = Math.max(0, toFiniteNumber(total, 0));
   const safeUsed = Math.max(0, toFiniteNumber(used, 0));
@@ -198,6 +224,21 @@ export function parseGrokCliBilling(billing, user = null) {
     };
   }
 
+  // SuperGrok weekly shared-pool usage (subscription tier). creditUsagePercent is
+  // the single total used %; productUsage is a breakdown legend, NOT independent
+  // quotas — never split it into separate bars.
+  const usedPct = unwrapVal(
+    config.creditUsagePercent ?? config.credit_usage_percent ?? root.creditUsagePercent,
+    NaN,
+  );
+  if (Number.isFinite(usedPct) && usedPct >= 0) {
+    quotas["Weekly SuperGrok"] = makeQuota({
+      used: Math.max(0, Math.min(100, usedPct)),
+      total: 100,
+      resetAt: periodEnd,
+    });
+  }
+
   // Opportunistic richer credit envelopes (future / other account types)
   const creditBags = [
     root.credits,
@@ -256,6 +297,50 @@ export function parseGrokCliBilling(billing, user = null) {
   };
 }
 
+/**
+ * Live SuperGrok weekly pool via gRPC-web GetGrokCreditsConfig.
+ * Fail-open: any network/auth/parse failure returns null.
+ * @returns {{ percentUsed: number, resetAt: string|null } | null}
+ */
+export async function fetchGrokCliCreditsConfig(accessToken, proxyOptions = null) {
+  if (!accessToken) return null;
+  try {
+    const res = await proxyAwareFetch(
+      GRPC_CREDITS_URL,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${accessToken}`,
+          "Content-Type": "application/grpc-web+proto",
+          "X-Grpc-Web": "1",
+          Accept: "application/grpc-web+proto",
+        },
+        body: GRPC_WEB_EMPTY_REQUEST_FRAME,
+      },
+      proxyOptions,
+    );
+    if (!res?.ok) return null;
+    const arrayBuffer = await res.arrayBuffer().catch(() => null);
+    if (!arrayBuffer) return null;
+    return decodeGrokCreditsFrame(Buffer.from(arrayBuffer));
+  } catch {
+    return null;
+  }
+}
+
+function quotasFromGrpcCredits(decoded) {
+  if (!decoded || !Number.isFinite(decoded.percentUsed)) return null;
+  // Round for bar display (fixed32 ratio * 100 can be 34.999… for 0.35)
+  const used = Math.round(Math.max(0, Math.min(100, decoded.percentUsed)));
+  return {
+    "Weekly SuperGrok": makeQuota({
+      used,
+      total: 100,
+      resetAt: decoded.resetAt || null,
+    }),
+  };
+}
+
 /**
  * @param {string} accessToken
  * @param {object|null} providerSpecificData
@@ -304,8 +389,19 @@ export async function getGrokCliUsage(accessToken, providerSpecificData = null,
     }
 
     const parsed = parseGrokCliBilling(billing, user);
+    parsed.plan = planFromAccessToken(accessToken) || parsed.plan;
 
     if (!parsed.quotas || Object.keys(parsed.quotas).length === 0) {
+      // Paid SuperGrok often returns cap=0 over REST but exposes the shared
+      // weekly pool on GetGrokCreditsConfig — try that before giving up.
+      const grpc = await fetchGrokCliCreditsConfig(accessToken, proxyOptions);
+      const grpcQuotas = quotasFromGrpcCredits(grpc);
+      if (grpcQuotas) {
+        return {
+          plan: parsed.plan,
+          quotas: grpcQuotas,
+        };
+      }
       return {
         plan: parsed.plan,
         message: parsed.subscriptionAccess

package/app/open-sse/services/usage/grokCliQuotaFrame.js

@@ -0,0 +1,191 @@
+/**
+ * gRPC-web frame decoder for xAI GetGrokCreditsConfig
+ * (grok_api_v2.GrokBuildBilling/GetGrokCreditsConfig).
+ *
+ * Real response shape (live capture 2026-07-20):
+ *   top-level field 1 (length-delimited) — nested credits info
+ *     subfield 1  (fixed32 float)            — usage ratio 0..1
+ *     subfield 5  (Timestamp{seconds,nanos}) — credit-pool reset time
+ *
+ * Fail-open: any malformed buffer returns null, never throws.
+ */
+
+const FIELD_CREDITS_INFO = 1;
+const CREDITS_FIELD_USAGE_RATIO = 1;
+const CREDITS_FIELD_RESET_TIMESTAMP = 5;
+const TIMESTAMP_FIELD_SECONDS = 1;
+const TIMESTAMP_FIELD_NANOS = 2;
+
+const WIRE_TYPE_VARINT = 0;
+const WIRE_TYPE_FIXED64 = 1;
+const WIRE_TYPE_LENGTH_DELIMITED = 2;
+const WIRE_TYPE_FIXED32 = 5;
+
+const GRPC_WEB_TRAILER_FLAG_BIT = 0x80;
+const MAX_VARINT_SHIFT_BITS = 70n;
+
+/**
+ * Validate a gRPC-web frame header at `offset`.
+ * @returns {{ flag: number, payloadStart: number, payloadLength: number } | null}
+ */
+export function probeFrameHeader(buffer, offset = 0) {
+  if (!Buffer.isBuffer(buffer) || offset < 0 || buffer.length - offset < 5) return null;
+  const flag = buffer[offset];
+  if (flag !== 0x00 && flag !== 0x01 && flag !== 0x80 && flag !== 0x81) return null;
+  const payloadStart = offset + 5;
+  const payloadLength = buffer.readUInt32BE(offset + 1);
+  if (payloadLength > buffer.length - payloadStart) return null;
+  return { flag, payloadStart, payloadLength };
+}
+
+function readVarint(buffer, offset) {
+  let result = 0n;
+  let shift = 0n;
+  let pos = offset;
+  for (;;) {
+    if (pos >= buffer.length) return null;
+    const byte = buffer[pos];
+    result |= BigInt(byte & 0x7f) << shift;
+    pos += 1;
+    if ((byte & 0x80) === 0) break;
+    shift += 7n;
+    if (shift > MAX_VARINT_SHIFT_BITS) return null;
+  }
+  return { value: Number(result), next: pos };
+}
+
+function readLengthDelimitedField(buffer, offset) {
+  const lengthResult = readVarint(buffer, offset);
+  if (!lengthResult) return null;
+  const { value: length, next: bodyStart } = lengthResult;
+  if (length < 0 || bodyStart + length > buffer.length) return null;
+  return {
+    field: { wireType: WIRE_TYPE_LENGTH_DELIMITED, bytes: buffer.subarray(bodyStart, bodyStart + length) },
+    next: bodyStart + length,
+  };
+}
+
+function readFixedWidthField(buffer, offset, width, wireType) {
+  if (offset + width > buffer.length) return null;
+  return {
+    field: { wireType, bytes: buffer.subarray(offset, offset + width) },
+    next: offset + width,
+  };
+}
+
+function readField(buffer, offset) {
+  const tagResult = readVarint(buffer, offset);
+  if (!tagResult) return null;
+  const fieldNumber = tagResult.value >>> 3;
+  const wireType = tagResult.value & 0x7;
+  if (fieldNumber === 0) return null;
+
+  if (wireType === WIRE_TYPE_VARINT) {
+    const valueResult = readVarint(buffer, tagResult.next);
+    if (!valueResult) return null;
+    return {
+      fieldNumber,
+      field: { wireType: WIRE_TYPE_VARINT, value: valueResult.value },
+      next: valueResult.next,
+    };
+  }
+  if (wireType === WIRE_TYPE_LENGTH_DELIMITED) {
+    const result = readLengthDelimitedField(buffer, tagResult.next);
+    return result ? { fieldNumber, field: result.field, next: result.next } : null;
+  }
+  if (wireType === WIRE_TYPE_FIXED64) {
+    const result = readFixedWidthField(buffer, tagResult.next, 8, WIRE_TYPE_FIXED64);
+    return result ? { fieldNumber, field: result.field, next: result.next } : null;
+  }
+  if (wireType === WIRE_TYPE_FIXED32) {
+    const result = readFixedWidthField(buffer, tagResult.next, 4, WIRE_TYPE_FIXED32);
+    return result ? { fieldNumber, field: result.field, next: result.next } : null;
+  }
+  return null;
+}
+
+function decodeFields(buffer) {
+  const fields = new Map();
+  let offset = 0;
+  while (offset < buffer.length) {
+    const result = readField(buffer, offset);
+    if (!result) return null;
+    fields.set(result.fieldNumber, result.field);
+    offset = result.next;
+  }
+  return fields;
+}
+
+function findDataFramePayload(buffer) {
+  let offset = 0;
+  while (offset < buffer.length) {
+    const frame = probeFrameHeader(buffer, offset);
+    if (!frame) return null;
+    const frameEnd = frame.payloadStart + frame.payloadLength;
+    const isTrailer = (frame.flag & GRPC_WEB_TRAILER_FLAG_BIT) !== 0;
+    if (!isTrailer) {
+      return buffer.subarray(frame.payloadStart, frameEnd);
+    }
+    offset = frameEnd;
+  }
+  return null;
+}
+
+function extractNestedMessage(field) {
+  if (!field || field.wireType !== WIRE_TYPE_LENGTH_DELIMITED) return null;
+  return decodeFields(field.bytes);
+}
+
+function extractUsageRatio(field) {
+  if (!field) return 0; // proto3 omission = 0% used
+  if (field.wireType === WIRE_TYPE_FIXED32) return field.bytes.readFloatLE(0);
+  if (field.wireType === WIRE_TYPE_FIXED64) return field.bytes.readDoubleLE(0);
+  return null;
+}
+
+function extractResetAt(field) {
+  if (!field || field.wireType !== WIRE_TYPE_LENGTH_DELIMITED) return null;
+
+  const timestampFields = decodeFields(field.bytes);
+  if (!timestampFields) return null;
+
+  const secondsField = timestampFields.get(TIMESTAMP_FIELD_SECONDS);
+  const nanosField = timestampFields.get(TIMESTAMP_FIELD_NANOS);
+  const seconds = secondsField?.wireType === WIRE_TYPE_VARINT ? secondsField.value : 0;
+  const nanos = nanosField?.wireType === WIRE_TYPE_VARINT ? nanosField.value : 0;
+
+  const millis = seconds * 1000 + Math.round(nanos / 1_000_000);
+  const parsed = new Date(millis);
+  return Number.isNaN(parsed.getTime()) ? null : parsed.toISOString();
+}
+
+/**
+ * Decode GetGrokCreditsConfig response → `{ percentUsed: 0-100, resetAt }` or null.
+ * @param {Buffer} buffer
+ * @returns {{ percentUsed: number, resetAt: string|null } | null}
+ */
+export function decodeGrokCreditsFrame(buffer) {
+  if (!buffer || !Buffer.isBuffer(buffer) || buffer.length === 0) return null;
+
+  try {
+    const framed = probeFrameHeader(buffer, 0) !== null;
+    const payload = framed ? findDataFramePayload(buffer) : buffer;
+    if (!payload) return null;
+
+    const topLevelFields = decodeFields(payload);
+    if (!topLevelFields) return null;
+
+    const creditsInfo = extractNestedMessage(topLevelFields.get(FIELD_CREDITS_INFO));
+    if (!creditsInfo) return null;
+
+    const usageRatio = extractUsageRatio(creditsInfo.get(CREDITS_FIELD_USAGE_RATIO));
+    if (usageRatio === null || !Number.isFinite(usageRatio) || usageRatio < 0) return null;
+
+    return {
+      percentUsed: Math.min(100, usageRatio * 100),
+      resetAt: extractResetAt(creditsInfo.get(CREDITS_FIELD_RESET_TIMESTAMP)),
+    };
+  } catch {
+    return null;
+  }
+}