Merge branch 'master' into gitea/new_feature

open-sse/services/cursorModels.js

@@ -0,0 +1,187 @@
+/**
+ * Cursor live model catalog fetcher.
+ *
+ * Cursor exposes the account-specific model picker through the AgentService
+ * `GetUsableModels` Connect RPC. Unlike the static provider registry, this
+ * includes models newly enabled for the account and omits unavailable ones.
+ */
+
+import crypto from "crypto";
+import http2 from "http2";
+import { PROVIDER_OAUTH } from "../providers/index.js";
+import { buildCursorHeaders } from "../utils/cursorChecksum.js";
+import { decodeMessage } from "../utils/cursorProtobuf.js";
+
+const FETCH_TIMEOUT_MS = 10_000;
+const CACHE_TTL_MS = 5 * 60 * 1000;
+
+// agent.v1.ModelDetails protobuf field numbers.
+const MODEL_ID_FIELD = 1;
+const DISPLAY_MODEL_ID_FIELD = 3;
+const DISPLAY_NAME_FIELD = 4;
+const DISPLAY_NAME_SHORT_FIELD = 5;
+const RESPONSE_MODELS_FIELD = 1;
+
+/** @type {Map<string, { expiresAt: number, models: { id: string, name: string }[] }>} */
+const catalogCache = new Map();
+
+function getCursorModelsUrl() {
+  const config = PROVIDER_OAUTH.cursor;
+  if (!config?.agentEndpoint || !config?.modelsEndpoint) return null;
+  return `${config.agentEndpoint.replace(/\/$/, "")}${config.modelsEndpoint}`;
+}
+
+function cacheKey(credentials) {
+  const seed = [
+    credentials?.providerSpecificData?.machineId,
+    credentials?.accessToken,
+  ].filter(Boolean).join(":");
+  if (!seed) return "cursor-anonymous";
+  return crypto.createHash("sha256").update(`cursor:${seed}`).digest("hex");
+}
+
+function firstString(fields, fieldNumber) {
+  const value = fields.get(fieldNumber)?.[0]?.value;
+  if (!value || typeof value === "number") return "";
+  return Buffer.from(value).toString("utf8");
+}
+
+/**
+ * Decode Cursor's `agent.v1.GetUsableModelsResponse` protobuf payload.
+ * The response contains repeated `agent.v1.ModelDetails` messages in field 1.
+ */
+export function parseCursorUsableModels(payload) {
+  const response = decodeMessage(payload);
+  const seen = new Set();
+  const models = [];
+
+  for (const entry of response.get(RESPONSE_MODELS_FIELD) || []) {
+    if (!entry?.value || typeof entry.value === "number") continue;
+    const detail = decodeMessage(entry.value);
+    const id = firstString(detail, MODEL_ID_FIELD).trim();
+    if (!id || seen.has(id)) continue;
+    seen.add(id);
+
+    const name = (
+      firstString(detail, DISPLAY_NAME_FIELD)
+      || firstString(detail, DISPLAY_NAME_SHORT_FIELD)
+      || firstString(detail, DISPLAY_MODEL_ID_FIELD)
+      || id
+    ).trim();
+    models.push({ id, name });
+  }
+
+  return models;
+}
+
+/**
+ * agent.api5.cursor.sh is HTTP/2-only; Node fetch/undici cannot speak h2.
+ * Unary GetUsableModels uses an unframed protobuf body (application/proto).
+ */
+function http2PostProto(url, headers, body, signal, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    const urlObj = new URL(url);
+    const client = http2.connect(`https://${urlObj.host}`);
+    const chunks = [];
+    let responseHeaders = {};
+    let settled = false;
+
+    const finish = (fn) => (...args) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeoutId);
+      try { client.close(); } catch {}
+      fn(...args);
+    };
+
+    const timeoutId = setTimeout(finish(() => {
+      reject(new Error("Cursor GetUsableModels timed out"));
+    }), timeoutMs);
+
+    client.on("error", finish(reject));
+
+    const req = client.request({
+      ":method": "POST",
+      ":path": urlObj.pathname,
+      ":authority": urlObj.host,
+      ":scheme": "https",
+      ...headers,
+    });
+
+    req.on("response", (hdrs) => { responseHeaders = hdrs; });
+    req.on("data", (chunk) => { chunks.push(chunk); });
+    req.on("end", finish(() => {
+      resolve({
+        status: Number(responseHeaders[":status"] || 0),
+        body: Buffer.concat(chunks),
+      });
+    }));
+    req.on("error", finish(reject));
+
+    if (signal) {
+      const onAbort = finish(() => reject(new Error("Request aborted")));
+      if (signal.aborted) onAbort();
+      else signal.addEventListener("abort", onAbort, { once: true });
+    }
+
+    req.end(body && body.length ? Buffer.from(body) : undefined);
+  });
+}
+
+async function fetchCursorCatalog(credentials, signal) {
+  const accessToken = credentials?.accessToken;
+  const machineId = credentials?.providerSpecificData?.machineId;
+  const url = getCursorModelsUrl();
+  if (!accessToken || !machineId || !url) return null;
+
+  const headers = {
+    ...buildCursorHeaders(accessToken, machineId, credentials?.providerSpecificData?.ghostMode !== false),
+    // Connect unary calls use an unframed protobuf body, unlike Cursor chat's
+    // streaming `application/connect+proto` endpoint.
+    accept: "application/proto",
+    "content-type": "application/proto",
+  };
+  delete headers["connect-accept-encoding"];
+  delete headers["connect-protocol-version"];
+
+  const response = await http2PostProto(url, headers, new Uint8Array(), signal, FETCH_TIMEOUT_MS);
+  if (response.status !== 200) {
+    const error = new Error(`Cursor GetUsableModels returned ${response.status}`);
+    error.status = response.status;
+    throw error;
+  }
+
+  return parseCursorUsableModels(new Uint8Array(response.body));
+}
+
+/**
+ * Resolve the live Cursor catalog for the authenticated account.
+ * Returns null on any failure so callers can fall back to static models.
+ */
+export async function resolveCursorModels(credentials, options = {}) {
+  if (!credentials?.accessToken || !credentials?.providerSpecificData?.machineId) {
+    options.log?.debug?.("CURSOR_MODELS", "No Cursor access token or machine ID; skipping live fetch");
+    return null;
+  }
+
+  const key = cacheKey(credentials);
+  const now = Date.now();
+  if (!options.forceRefresh) {
+    const cached = catalogCache.get(key);
+    if (cached?.expiresAt > now) return { models: cached.models };
+  }
+
+  try {
+    const models = await fetchCursorCatalog(credentials, options.signal);
+    if (!models?.length) return null;
+    catalogCache.set(key, { expiresAt: now + CACHE_TTL_MS, models });
+    return { models };
+  } catch (error) {
+    options.log?.warn?.("CURSOR_MODELS", `Live model fetch failed: ${error?.message || error}`);
+    return null;
+  }
+}
+
+export function clearCursorModelCache() {
+  catalogCache.clear();
+}

open-sse/services/projectId.js

@@ -83,7 +83,7 @@ startCacheCleanup();
  * @param {string} accessToken  - Valid OAuth access token
  * @returns {Promise<string|null>} Real project ID or null
  */
-export async function getProjectIdForConnection(connectionId, accessToken) {
+export async function getProjectIdForConnection(connectionId, accessToken, provider = "gemini-cli") {
     if (!connectionId || !accessToken) return null;
 
     // Return cached value if still fresh
@@ -102,7 +102,7 @@ export async function getProjectIdForConnection(connectionId, accessToken) {
 
     const promise = (async () => {
         try {
-            const projectId = await fetchProjectId(accessToken, controller.signal);
+            const projectId = await fetchProjectId(accessToken, controller.signal, provider);
             if (projectId) {
                 projectIdCache.set(connectionId, {projectId, fetchedAt: Date.now()});
                 return projectId;
@@ -155,8 +155,9 @@ export function removeConnection(connectionId) {
  * @param {AbortSignal} signal
  * @returns {Promise<string|null>}
  */
-async function fetchProjectId(accessToken, signal) {
-    const response = await fetch(CLOUD_CODE_API.loadCodeAssist, {
+async function fetchProjectId(accessToken, signal, provider) {
+    const endpoints = CLOUD_CODE_API[provider] || CLOUD_CODE_API["gemini-cli"];
+    const response = await fetch(endpoints.loadCodeAssist, {
         method: "POST",
         headers: { ...LOAD_CODE_ASSIST_HEADERS, "Authorization": `Bearer ${accessToken}` },
         body: JSON.stringify({ metadata: LOAD_CODE_ASSIST_METADATA }),
@@ -185,7 +186,7 @@ async function fetchProjectId(accessToken, signal) {
         }
     }
 
-    return onboardUser(accessToken, tierID, signal);
+    return onboardUser(accessToken, tierID, signal, endpoints);
 }
 
 /**
@@ -196,7 +197,7 @@ async function fetchProjectId(accessToken, signal) {
  * @param {AbortSignal} externalSignal  – propagated from the connection's AbortController
  * @returns {Promise<string|null>}
  */
-async function onboardUser(accessToken, tierID, externalSignal) {
+async function onboardUser(accessToken, tierID, externalSignal, endpoints) {
     console.log(`[ProjectId] Onboarding user with tier: ${tierID}`);
 
     const reqBody = { tierId: tierID, metadata: LOAD_CODE_ASSIST_METADATA };
@@ -213,7 +214,7 @@ async function onboardUser(accessToken, tierID, externalSignal) {
         externalSignal?.addEventListener("abort", forwardAbort);
 
         try {
-            const response = await fetch(CLOUD_CODE_API.onboardUser, {
+            const response = await fetch(endpoints.onboardUser, {
                 method: "POST",
                 headers: { ...LOAD_CODE_ASSIST_HEADERS, "Authorization": `Bearer ${accessToken}` },
                 body: JSON.stringify(reqBody),

open-sse/services/tokenRefresh.js

@@ -3,6 +3,7 @@ import { OAUTH_ENDPOINTS, REFRESH_LEAD_MS } from "../config/appConstants.js";
 import {
   refreshXaiToken,
   refreshAccessToken,
+  refreshKimiToken,
   refreshClaudeOAuthToken,
   refreshGoogleToken,
   refreshQwenToken,
@@ -12,12 +13,17 @@ import {
   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,
@@ -27,6 +33,10 @@ export {
   refreshGitHubToken,
   refreshCopilotToken,
   refreshCodebuddyToken,
+  refreshCodebuddyIntlToken,
+  refreshTraeToken,
+  refreshZedToken,
+  refreshWindsurfToken,
   classifyOAuthRefreshError,
 };
 
@@ -44,7 +54,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) {
@@ -133,6 +146,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
 };

open-sse/services/tokenRefresh/providers.js

@@ -1,5 +1,5 @@
 import { PROVIDERS, PROVIDER_OAUTH } from "../../config/providers.js";
-import { OAUTH_ENDPOINTS, GITHUB_COPILOT } from "../../config/appConstants.js";
+import { OAUTH_ENDPOINTS, GITHUB_COPILOT, buildKimiHeaders } from "../../config/appConstants.js";
 import { proxyAwareFetch } from "../../utils/proxyFetch.js";
 import { dedupRefresh } from "./dedup.js";
 import { buildExternalIdpRefreshParams } from "../../../src/lib/oauth/kiroExternalIdp.js";
@@ -31,10 +31,68 @@ export async function refreshXaiToken(refreshToken, log) {
   }, log);
 }
 
+// Per-provider refresh variants for the generic path. Keys not listed fall back
+// to the default form-encoded OAuth2 refresh with client_id + client_secret.
+const REFRESH_PROFILES = {
+  claude: {
+    bodyFormat: "json",
+    includeClientSecret: false,
+    url: () => OAUTH_ENDPOINTS.anthropic.token,
+    dedupKey: "claude",
+  },
+  qwen: {
+    url: () => OAUTH_ENDPOINTS.qwen.token,
+    dedupKey: "qwen",
+    parse: (tokens) => tokens.resource_url ? { providerSpecificData: { resourceUrl: tokens.resource_url } } : {},
+  },
+  iflow: {
+    url: () => OAUTH_ENDPOINTS.iflow.token,
+    dedupKey: "iflow",
+    extraHeaders: (creds, cfg) => ({
+      Authorization: `Basic ${btoa(`${cfg.clientId}:${cfg.clientSecret}`)}`,
+    }),
+  },
+  github: {
+    url: () => OAUTH_ENDPOINTS.github.token,
+    dedupKey: "github",
+    includeClientSecret: (cfg) => !!cfg?.clientSecret,
+  },
+  kimi: {
+    dedupKey: "kimi",
+    extraHeaders: (creds) => buildKimiHeaders(creds?.providerSpecificData?.deviceId),
+  },
+};
+
+function resolveRefreshUrl(provider, config, profile) {
+  if (profile?.url) {
+    try { return profile.url(); } catch { /* fall through */ }
+  }
+  return config?.refreshUrl || PROVIDER_OAUTH[provider]?.tokenUrl || null;
+}
+
+function buildRefreshBody(profile, config, refreshToken) {
+  const fmt = profile?.bodyFormat === "json" ? "json" : "form";
+  const includeSecret = profile?.includeClientSecret === undefined
+    ? true
+    : typeof profile.includeClientSecret === "function"
+      ? profile.includeClientSecret(config)
+      : profile.includeClientSecret;
+  const payload = {
+    grant_type: "refresh_token",
+    refresh_token: refreshToken,
+    client_id: config.clientId,
+  };
+  if (includeSecret && config.clientSecret) payload.client_secret = config.clientSecret;
+  if (fmt === "json") return { format: "json", body: JSON.stringify(payload) };
+  return { format: "form", body: new URLSearchParams(payload) };
+}
+
 export async function refreshAccessToken(provider, refreshToken, credentials, log) {
   const config = PROVIDERS[provider];
+  const profile = REFRESH_PROFILES[provider] || {};
+  const url = resolveRefreshUrl(provider, config, profile);
 
-  if (!config || !config.refreshUrl) {
+  if (!config || !url) {
     log?.warn?.("TOKEN_REFRESH", `No refresh URL configured for provider: ${provider}`);
     return null;
   }
@@ -44,21 +102,17 @@ export async function refreshAccessToken(provider, refreshToken, credentials, lo
     return null;
   }
 
-  return dedupRefresh(provider, refreshToken, async () => {
+  const dedupKey = profile.dedupKey || provider;
+
+  return dedupRefresh(dedupKey, refreshToken, async () => {
   try {
-    const response = await fetch(config.refreshUrl, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/x-www-form-urlencoded",
-        Accept: "application/json",
-      },
-      body: new URLSearchParams({
-        grant_type: "refresh_token",
-        refresh_token: refreshToken,
-        client_id: config.clientId,
-        client_secret: config.clientSecret,
-      }),
-    });
+    const { format: bodyFormat, body } = buildRefreshBody(profile, config, refreshToken);
+    const headers = {
+      "Content-Type": bodyFormat === "json" ? "application/json" : "application/x-www-form-urlencoded",
+      Accept: "application/json",
+      ...(profile.extraHeaders ? (profile.extraHeaders(credentials, config) || {}) : {}),
+    };
+    const response = await fetch(url, { method: "POST", headers, body });
 
     if (!response.ok) {
       const errorText = await response.text();
@@ -81,6 +135,7 @@ export async function refreshAccessToken(provider, refreshToken, credentials, lo
       accessToken: tokens.access_token,
       refreshToken: tokens.refresh_token || refreshToken,
       expiresIn: tokens.expires_in,
+      ...(profile.parse ? (profile.parse(tokens) || {}) : {}),
     };
   } catch (error) {
     log?.error?.("TOKEN_REFRESH", `Error refreshing token for ${provider}`, {
@@ -91,37 +146,15 @@ export async function refreshAccessToken(provider, refreshToken, credentials, lo
   }, log);
 }
 
+// CLIProxyAPI DeviceFlowClient.RefreshToken: form body (no client_secret) + X-Msh-* headers
+// Delegate to refreshAccessToken("kimi", ...) — profile carries the X-Msh headers.
+export async function refreshKimiToken(refreshToken, credentials, log) {
+  return refreshAccessToken("kimi", refreshToken, credentials, log);
+}
+
+// Claude OAuth: JSON body, client_id only. Delegate to refreshAccessToken("claude", ...).
 export async function refreshClaudeOAuthToken(refreshToken, log) {
-  if (!refreshToken) return null;
-  return dedupRefresh("claude", refreshToken, async () => {
-  try {
-    const response = await fetch(OAUTH_ENDPOINTS.anthropic.token, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Accept: "application/json",
-      },
-      body: JSON.stringify({
-        grant_type: "refresh_token",
-        refresh_token: refreshToken,
-        client_id: PROVIDERS.claude.clientId,
-      }),
-    });
-
-    if (!response.ok) {
-      const errorText = await response.text();
-      log?.error?.("TOKEN_REFRESH", "Failed to refresh Claude OAuth token", { status: response.status, error: errorText });
-      return null;
-    }
-
-    const tokens = await response.json();
-    log?.info?.("TOKEN_REFRESH", "Successfully refreshed Claude OAuth token", { hasNewAccessToken: !!tokens.access_token, expiresIn: tokens.expires_in });
-    return { accessToken: tokens.access_token, refreshToken: tokens.refresh_token || refreshToken, expiresIn: tokens.expires_in };
-  } catch (error) {
-    log?.error?.("TOKEN_REFRESH", `Network error refreshing Claude token: ${error.message}`);
-    return null;
-  }
-  }, log);
+  return refreshAccessToken("claude", refreshToken, {}, log);
 }
 
 export async function refreshGoogleToken(refreshToken, clientId, clientSecret, log) {
@@ -158,58 +191,9 @@ export async function refreshGoogleToken(refreshToken, clientId, clientSecret, l
   }, log);
 }
 
+// Qwen: form body + clientId, surfaces resource_url. Delegate to refreshAccessToken("qwen", ...).
 export async function refreshQwenToken(refreshToken, log) {
-  if (!refreshToken) return null;
-  return dedupRefresh("qwen", refreshToken, async () => {
-  const endpoint = OAUTH_ENDPOINTS.qwen.token;
-
-  try {
-    const response = await fetch(endpoint, {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/x-www-form-urlencoded",
-        Accept: "application/json",
-      },
-      body: new URLSearchParams({
-        grant_type: "refresh_token",
-        refresh_token: refreshToken,
-        client_id: PROVIDERS.qwen.clientId,
-      }),
-    });
-
-    if (response.status === 200) {
-      const tokens = await response.json();
-
-      log?.info?.("TOKEN_REFRESH", "Successfully refreshed Qwen token", {
-        hasNewAccessToken: !!tokens.access_token,
-        hasNewRefreshToken: !!tokens.refresh_token,
-        expiresIn: tokens.expires_in,
-      });
-
-      return {
-        accessToken: tokens.access_token,
-        refreshToken: tokens.refresh_token || refreshToken,
-        expiresIn: tokens.expires_in,
-        providerSpecificData: tokens.resource_url
-          ? { resourceUrl: tokens.resource_url }
-          : undefined,
-      };
-    } else {
-      const errorText = await response.text().catch(() => "");
-      log?.warn?.("TOKEN_REFRESH", `Error with Qwen endpoint`, {
-        status: response.status,
-        error: errorText,
-      });
-    }
-  } catch (error) {
-    log?.warn?.("TOKEN_REFRESH", `Network error trying Qwen endpoint`, {
-      error: error.message,
-    });
-  }
-
-  log?.error?.("TOKEN_REFRESH", "Failed to refresh Qwen token");
-  return null;
-  }, log);
+  return refreshAccessToken("qwen", refreshToken, {}, log);
 }
 
 export function classifyOAuthRefreshError(errorText = "", status = 0) {
@@ -434,95 +418,14 @@ export async function refreshKiroToken(refreshToken, providerSpecificData, log,
   }, log);
 }
 
+// iFlow: Basic Auth + client_id+client_secret in body. Delegate to refreshAccessToken("iflow", ...).
 export async function refreshIflowToken(refreshToken, log) {
-  if (!refreshToken) return null;
-  return dedupRefresh("iflow", refreshToken, async () => {
-  const basicAuth = btoa(`${PROVIDERS.iflow.clientId}:${PROVIDERS.iflow.clientSecret}`);
-
-  const response = await fetch(OAUTH_ENDPOINTS.iflow.token, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/x-www-form-urlencoded",
-      Accept: "application/json",
-      Authorization: `Basic ${basicAuth}`,
-    },
-    body: new URLSearchParams({
-      grant_type: "refresh_token",
-      refresh_token: refreshToken,
-      client_id: PROVIDERS.iflow.clientId,
-      client_secret: PROVIDERS.iflow.clientSecret,
-    }),
-  });
-
-  if (!response.ok) {
-    const errorText = await response.text();
-    log?.error?.("TOKEN_REFRESH", "Failed to refresh iFlow token", {
-      status: response.status,
-      error: errorText,
-    });
-    return null;
-  }
-
-  const tokens = await response.json();
-
-  log?.info?.("TOKEN_REFRESH", "Successfully refreshed iFlow token", {
-    hasNewAccessToken: !!tokens.access_token,
-    hasNewRefreshToken: !!tokens.refresh_token,
-    expiresIn: tokens.expires_in,
-  });
-
-  return {
-    accessToken: tokens.access_token,
-    refreshToken: tokens.refresh_token || refreshToken,
-    expiresIn: tokens.expires_in,
-  };
-  }, log);
+  return refreshAccessToken("iflow", refreshToken, {}, log);
 }
 
+// GitHub: optional client_secret. Delegate to refreshAccessToken("github", ...).
 export async function refreshGitHubToken(refreshToken, log) {
-  if (!refreshToken) return null;
-  return dedupRefresh("github", refreshToken, async () => {
-  const params = {
-    grant_type: "refresh_token",
-    refresh_token: refreshToken,
-    client_id: PROVIDERS.github.clientId,
-  };
-  if (PROVIDERS.github.clientSecret) {
-    params.client_secret = PROVIDERS.github.clientSecret;
-  }
-
-  const response = await fetch(OAUTH_ENDPOINTS.github.token, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/x-www-form-urlencoded",
-      Accept: "application/json",
-    },
-    body: new URLSearchParams(params),
-  });
-
-  if (!response.ok) {
-    const errorText = await response.text();
-    log?.error?.("TOKEN_REFRESH", "Failed to refresh GitHub token", {
-      status: response.status,
-      error: errorText,
-    });
-    return null;
-  }
-
-  const tokens = await response.json();
-
-  log?.info?.("TOKEN_REFRESH", "Successfully refreshed GitHub token", {
-    hasNewAccessToken: !!tokens.access_token,
-    hasNewRefreshToken: !!tokens.refresh_token,
-    expiresIn: tokens.expires_in,
-  });
-
-  return {
-    accessToken: tokens.access_token,
-    refreshToken: tokens.refresh_token || refreshToken,
-    expiresIn: tokens.expires_in,
-  };
-  }, log);
+  return refreshAccessToken("github", refreshToken, {}, log);
 }
 
 export async function refreshCopilotToken(githubAccessToken, log) {
@@ -622,3 +525,146 @@ export async function refreshCodebuddyToken(refreshToken, log) {
     };
   }, log);
 }
+
+export async function refreshCodebuddyIntlToken(refreshToken, log) {
+  if (!refreshToken) return null;
+  return dedupRefresh("codebuddy-intl", refreshToken, async () => {
+    const oauth = PROVIDER_OAUTH["codebuddy-intl"] || {};
+    const response = await fetch(oauth.refreshUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+        "User-Agent": oauth.userAgent,
+        "X-Requested-With": "XMLHttpRequest",
+        "X-Domain": "www.codebuddy.ai",
+        "X-Refresh-Token": refreshToken,
+        "X-Auth-Refresh-Source": "plugin",
+        "X-Product": "SaaS",
+      },
+      body: "{}",
+    });
+
+    if (!response.ok) {
+      const errorText = await response.text();
+      log?.error?.("TOKEN_REFRESH", "Failed to refresh CodeBuddy intl token", {
+        status: response.status,
+        error: errorText,
+      });
+      return null;
+    }
+
+    const data = await response.json();
+    if (data.code !== 0 || !data.data?.accessToken) {
+      log?.error?.("TOKEN_REFRESH", "CodeBuddy intl token refresh returned no token", {
+        code: data.code,
+        msg: data.msg,
+      });
+      return null;
+    }
+
+    log?.info?.("TOKEN_REFRESH", "Successfully refreshed CodeBuddy intl token", {
+      hasNewAccessToken: !!data.data.accessToken,
+      hasNewRefreshToken: !!data.data.refreshToken,
+      expiresIn: data.data.expiresIn,
+    });
+
+    return {
+      accessToken: data.data.accessToken,
+      refreshToken: data.data.refreshToken || refreshToken,
+      expiresIn: data.data.expiresIn,
+    };
+  }, log);
+}
+
+// Trae refresh — POST ExchangeToken with JSON body {ClientID, RefreshToken, ClientSecret, UserID}.
+// Response: {Result: {AccessToken, RefreshToken, TokenType, ExpiresAt}}.
+export async function refreshTraeToken(refreshToken, credentials, log) {
+  if (!refreshToken) return null;
+  const oauth = PROVIDER_OAUTH.trae || {};
+  const url = oauth.exchangeTokenUrl || oauth.tokenUrl;
+  if (!url) {
+    log?.warn?.("TOKEN_REFRESH", "No Trae exchangeTokenUrl configured");
+    return null;
+  }
+
+  return dedupRefresh("trae", refreshToken, async () => {
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Accept: "application/json",
+          "User-Agent": "Trae/1.0.0 antigravity-cockpit-tools",
+        },
+        body: JSON.stringify({
+          ClientID: oauth.clientId || "ono9krqynydwx5",
+          RefreshToken: refreshToken,
+          ClientSecret: oauth.clientSecret || "-",
+          UserID: "",
+        }),
+      });
+
+      if (!response.ok) {
+        const errorText = await response.text();
+        log?.error?.("TOKEN_REFRESH", "Failed to refresh Trae token", {
+          status: response.status,
+          error: errorText,
+        });
+        return null;
+      }
+
+      const payload = await response.json();
+      const result = payload?.Result || payload?.result || payload;
+      const accessToken = result?.AccessToken || result?.accessToken;
+      if (!accessToken) {
+        log?.error?.("TOKEN_REFRESH", "Trae refresh returned no AccessToken", { payload });
+        return null;
+      }
+
+      const newRefresh = result?.RefreshToken || result?.refreshToken || refreshToken;
+      const expiresAt = result?.ExpiresAt || result?.expiresAt;
+      let expiresIn;
+      if (typeof expiresAt === "number") {
+        expiresIn = Math.max(1, expiresAt - Math.floor(Date.now() / 1000));
+      } else if (typeof expiresAt === "string") {
+        const ms = new Date(expiresAt).getTime() - Date.now();
+        expiresIn = ms > 0 ? Math.floor(ms / 1000) : undefined;
+      }
+
+      log?.info?.("TOKEN_REFRESH", "Successfully refreshed Trae token", {
+        hasNewAccessToken: !!accessToken,
+        hasNewRefreshToken: newRefresh !== refreshToken,
+        expiresIn,
+      });
+
+      return {
+        accessToken,
+        refreshToken: newRefresh,
+        expiresIn,
+      };
+    } catch (error) {
+      log?.error?.("TOKEN_REFRESH", `Error refreshing Trae token: ${error.message}`);
+      return null;
+    }
+  }, log);
+}
+
+// Zed access_token is long-lived; auth flow returns no refresh_token.
+// No refresh possible — re-login required when token expires/revoked.
+// Mirrors cursor/kilocode null-refresh pattern.
+export function refreshZedToken() {
+  return null;
+}
+
+// Windsurf apiKey is the long-lived terminal credential (no OAuth2 refresh_token
+// grant yields a fresh apiKey). Refresh handled out-of-band by the caller.
+// TODO(firebase): if short-lived Firebase JWT credentials must be refreshed,
+// re-run RegisterUser with the refreshed Firebase JWT (separate code path).
+export async function refreshWindsurfToken(credentials, log) {
+  log?.info?.(
+    "TOKEN_REFRESH",
+    "windsurf: apiKey is long-lived (no refresh_token flow) — skipping"
+  );
+  return null;
+}

open-sse/services/usage.js

@@ -13,6 +13,8 @@ import { getMiniMaxUsage } from "./usage/minimax.js";
 import { getCodeBuddyCnUsage } from "./usage/codebuddy-cn.js";
 import { getXaiUsage } from "./usage/xai.js";
 import { getGrokCliUsage } from "./usage/grok-cli.js";
+import { getKimiUsage } from "./usage/kimi.js";
+import { getDeepseekUsage } from "./usage/deepseek.js";
 import {
   getQwenUsage,
   getIflowUsage,
@@ -47,6 +49,8 @@ const USAGE_HANDLERS = {
   "codebuddy-cn": (c) => getCodeBuddyCnUsage(c.accessToken, c.apiKey, c.providerSpecificData, c.proxyOptions),
   xai: (c) => getXaiUsage(c.accessToken, c.proxyOptions),
   "grok-cli": (c) => getGrokCliUsage(c.accessToken, c.providerSpecificData, c.proxyOptions),
+  kimi: (c) => getKimiUsage(c.accessToken, c.apiKey, c.proxyOptions, c.providerSpecificData),
+  deepseek: (c) => getDeepseekUsage(c.apiKey, c.proxyOptions),
 };
 
 export async function getUsageForProvider(connection, proxyOptions = null) {

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}` };
+  }
+}

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;
@@ -198,6 +206,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 +279,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
@@ -306,6 +373,16 @@ export async function getGrokCliUsage(accessToken, providerSpecificData = null,
     const parsed = parseGrokCliBilling(billing, user);
 
     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

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;
+  }
+}

open-sse/services/usage/kimi.js

@@ -0,0 +1,211 @@
+/**
+ * Kimi Coding usage — GET /v1/usages
+ *
+ * Dual auth (single provider id `kimi`):
+ *   - apiKey present → x-api-key only (platform / coding API key)
+ *   - else accessToken → Bearer + X-Msh-* (device-code OAuth)
+ *
+ * Note: chat messages use combined x-api-key; /usages OAuth is Bearer.
+ * 403 permission_denied is NOT auth-expired — account lacks usage feature / sub.
+ */
+
+import { proxyAwareFetch } from "../../utils/proxyFetch.js";
+import { parseResetTime, toFiniteNumber } from "./shared.js";
+import { buildKimiHeaders } from "../../config/appConstants.js";
+
+const USAGE_URL = "https://api.kimi.com/coding/v1/usages";
+
+const PLAN_LEVELS = {
+  LEVEL_BASIC: "Moderato",
+  LEVEL_INTERMEDIATE: "Allegretto",
+  LEVEL_ADVANCED: "Allegro",
+  LEVEL_STANDARD: "Vivace",
+};
+
+function getKimiPlanName(level) {
+  if (!level) return "";
+  const key = String(level);
+  if (PLAN_LEVELS[key]) return PLAN_LEVELS[key];
+  return key.replace(/^LEVEL_/, "").toLowerCase();
+}
+
+/** Best-effort extract human message from Kimi error JSON (403 body is Connect-RPC-ish). */
+export function formatKimiUsageError(status, responseText) {
+  let parsed = null;
+  try {
+    parsed = JSON.parse(responseText || "");
+  } catch {
+    /* plain text */
+  }
+
+  const detail0 = Array.isArray(parsed?.details) ? parsed.details[0] : null;
+  const debug = detail0?.debug || parsed?.debug || null;
+  const reason = debug?.reason || parsed?.reason || "";
+  const localized =
+    debug?.localizedMessage?.message ||
+    detail0?.localizedMessage?.message ||
+    parsed?.message ||
+    "";
+
+  if (status === 401) {
+    return "Kimi authentication expired. Please re-authorize.";
+  }
+
+  // Live OAuth token without Kimi Code usage entitlement returns 403
+  // REASON_FEATURE_NO_PERMISSION — not an expired session.
+  if (
+    status === 403 &&
+    (reason === "REASON_FEATURE_NO_PERMISSION" ||
+      /permission_denied|do not have permission|subscribe/i.test(
+        `${parsed?.code || ""} ${localized} ${responseText || ""}`,
+      ))
+  ) {
+    return (
+      localized ||
+      "Kimi connected, but this account has no permission to view usage. Subscribe to Kimi Code to access quota."
+    );
+  }
+
+  const snippet = (localized || responseText || "").slice(0, 100);
+  return snippet
+    ? `Kimi Coding connected. API Error ${status}: ${snippet}`
+    : `Kimi Coding connected. API Error ${status}`;
+}
+
+function makeQuota({ used, total, remaining, resetAt }) {
+  const safeTotal = Math.max(0, toFiniteNumber(total, 0));
+  const safeUsed = Math.max(0, toFiniteNumber(used, 0));
+  // Prefer provider remaining when present; never set absolute `remaining`
+  // on the quota object — QuotaTable treats it as a 0–100 percentage.
+  let remainingPct;
+  if (safeTotal > 0 && remaining != null && Number.isFinite(Number(remaining))) {
+    remainingPct = (Math.max(0, Number(remaining)) / safeTotal) * 100;
+  } else if (safeTotal > 0) {
+    remainingPct = (Math.max(0, safeTotal - safeUsed) / safeTotal) * 100;
+  } else {
+    remainingPct = 0;
+  }
+  return {
+    used: safeUsed,
+    total: safeTotal,
+    remainingPercentage: remainingPct,
+    resetAt: resetAt || null,
+    unlimited: false,
+  };
+}
+
+/**
+ * @param {string|null|undefined} accessToken
+ * @param {string|null|undefined} apiKey
+ * @param {object|null} proxyOptions
+ * @param {object|null} providerSpecificData
+ */
+export async function getKimiUsage(
+  accessToken = null,
+  apiKey = null,
+  proxyOptions = null,
+  providerSpecificData = null,
+) {
+  const useApiKey = typeof apiKey === "string" && apiKey.length > 0;
+  const useOAuth = !useApiKey && typeof accessToken === "string" && accessToken.length > 0;
+
+  if (!useApiKey && !useOAuth) {
+    return { message: "Kimi access token or API key not available." };
+  }
+
+  const authHeaders = useApiKey
+    ? { "x-api-key": apiKey }
+    : {
+        Authorization: `Bearer ${accessToken}`,
+        ...buildKimiHeaders(providerSpecificData?.deviceId),
+      };
+
+  try {
+    const response = await proxyAwareFetch(
+      USAGE_URL,
+      {
+        method: "GET",
+        headers: {
+          ...authHeaders,
+          "Content-Type": "application/json",
+          Accept: "application/json",
+        },
+      },
+      proxyOptions,
+    );
+
+    const responseText = await response.text().catch(() => "");
+
+    if (!response.ok) {
+      return {
+        plan: "Kimi Coding",
+        message: formatKimiUsageError(response.status, responseText),
+      };
+    }
+
+    let data;
+    try {
+      data = JSON.parse(responseText || "{}");
+    } catch {
+      return {
+        plan: "Kimi Coding",
+        message: "Kimi Coding connected. Invalid JSON response from API.",
+      };
+    }
+
+    const quotas = {};
+    const usageObj = data?.usage && typeof data.usage === "object" ? data.usage : {};
+    const usageLimit = toFiniteNumber(usageObj.limit ?? usageObj.Limit, 0);
+    const usageUsed = toFiniteNumber(usageObj.used ?? usageObj.Used, 0);
+    const usageRemainingRaw = usageObj.remaining ?? usageObj.Remaining;
+    const usageRemaining =
+      usageRemainingRaw != null && usageRemainingRaw !== ""
+        ? toFiniteNumber(usageRemainingRaw, NaN)
+        : NaN;
+    const usageResetTime =
+      usageObj.resetTime || usageObj.ResetTime || usageObj.reset_at || usageObj.resetAt;
+
+    if (usageLimit > 0) {
+      quotas.Weekly = makeQuota({
+        used: usageUsed,
+        total: usageLimit,
+        remaining: Number.isFinite(usageRemaining) ? usageRemaining : null,
+        resetAt: parseResetTime(usageResetTime),
+      });
+    }
+
+    const limitsArray = Array.isArray(data?.limits) ? data.limits : [];
+    for (const item of limitsArray) {
+      if (!item || typeof item !== "object") continue;
+      const detail = item.detail && typeof item.detail === "object" ? item.detail : {};
+      const limit = toFiniteNumber(detail.limit ?? detail.Limit, 0);
+      const remaining = toFiniteNumber(detail.remaining ?? detail.Remaining, NaN);
+      const resetTime = detail.resetTime || detail.reset_at || detail.resetAt;
+      if (limit > 0) {
+        const rem = Number.isFinite(remaining) ? remaining : Math.max(0, limit);
+        quotas.Ratelimit = makeQuota({
+          used: Math.max(0, limit - rem),
+          total: limit,
+          remaining: rem,
+          resetAt: parseResetTime(resetTime),
+        });
+      }
+    }
+
+    const membershipLevel = data?.user?.membership?.level;
+    const planName = getKimiPlanName(membershipLevel) || "Kimi Coding";
+
+    if (Object.keys(quotas).length > 0) {
+      return { plan: planName, quotas };
+    }
+
+    return {
+      plan: planName,
+      message: "Kimi Coding connected. Usage tracked per request.",
+    };
+  } catch (error) {
+    return {
+      message: `Kimi Coding connected. Unable to fetch usage: ${error.message}`,
+    };
+  }
+}