@monotykamary/pi-better-grok 0.2.2 → 0.3.1

package/README.md

@@ -36,7 +36,9 @@ SuperGrok plans earn banked rate-limit reset tokens: redeeming one restores the
 
 The inventory and redeem calls use the grok.com consumer billing gRPC-Web service (`prod_mc_billing.ConsumerUiSvc/GetRemainingResets` and `RedeemReset`) that the web usage page itself calls, authenticated with the same xAI OAuth token as the usage meter. This surface is undocumented; request shapes are pinned in `src/resets.ts` and schema drift is expected.
 
-**Known limitation:** grok.com fronts this RPC with a Cloudflare managed challenge, which browser-fingerprinted clients (Electron apps) pass but plain CLI runtimes cannot — the edge answers with `403 · cf-mitigated: challenge` regardless of headers or credentials. When that happens the widget hides the count and `/grok-resets` explains the challenge instead of misreporting it as an auth failure. The wiring is live end to end, so the count appears in any environment where the fetch can succeed.
+**Cloudflare requirement (worked around):** grok.com fronts this RPC with a managed challenge that non-browser clients cannot solve — even a perfect Chrome TLS impersonation (curl-impersonate) is challenged, because the site requires a `cf_clearance` cookie issued after a browser solves the challenge once. The cookie is bound to the browser's user-agent and IP. This is the same mechanism community Grok proxies (e.g. grok2api) rely on.
+
+Because pi runs on the same machine (and IP) as your browser, supplying both values in config unlocks the surface. To get them: open grok.com in your browser, DevTools → Application → Cookies → copy `cf_clearance`; Network → any request → copy the `User-Agent` request header. When the clearance expires, `/grok-resets` says so explicitly and you re-copy the cookie. Without a clearance configured, the widget hides the count and `/grok-resets` explains the challenge instead of misreporting it as an auth failure.
 
 ## pi-multiprovider
 
@@ -58,7 +60,8 @@ JSON config at `~/.pi/agent/extensions/pi-better-grok.json` (global) or `<projec
     "showResetTimes": true,
     "showBankedResets": true
   },
-  "footer": { "mode": "status" }
+  "footer": { "mode": "status" },
+  "resets": { "cookies": "", "userAgent": "" }
 }
 ```
 

package/index.ts

@@ -7,7 +7,12 @@
  * cli-chat-proxy.grok.com identity-first billing surface using pi's native
  * xAI OAuth credential.
  */
-import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  type ExtensionAPI,
+  type ExtensionContext,
+  type Theme,
+  type ThemeColor,
+} from "@earendil-works/pi-coding-agent";
 import { Container, SettingsList, type SettingsListTheme } from "@earendil-works/pi-tui";
 import { CONFIG_BASENAME, STATUS_KEY } from "./src/identity.ts";
 import {
@@ -29,6 +34,7 @@ import {
   formatGrokResetOutcome,
   redeemGrokResetForSession,
   selectGrokResetToken,
+  setGrokResetNetworkProfile,
 } from "./src/resets.ts";
 import { ResetController } from "./src/reset-controller.ts";
 import {
@@ -55,6 +61,8 @@ import {
   parseUsageSnapshot,
   requestGrokUsage,
   UsageError,
+  type UsageSegment,
+  type UsageSeverity,
   type UsageSnapshot,
 } from "./src/usage.ts";
 import {
@@ -84,6 +92,46 @@ const requireSettingsListTheme = (): SettingsListTheme => {
   return loadedSettingsListTheme;
 };
 
+const USAGE_SEVERITY_COLORS: Record<UsageSeverity, ThemeColor> = {
+  ok: "success",
+  warning: "warning",
+  critical: "error",
+  muted: "dim",
+};
+
+/**
+ * Keep a coloured segment on one line. Unlike sanitizeStatusText this leaves the
+ * spacing shared by neighbouring segments ("5h: " + "90%") intact.
+ */
+function flattenSegment(text: string): string {
+  return text.replace(/[\r\n\t]+/g, " ");
+}
+
+/**
+ * Colour a usage line segment by segment: the percentage carries the severity
+ * colour while the label, countdown and banked resets stay dim.
+ */
+function colorizeUsageSegments(segments: UsageSegment[], theme: Theme): string {
+  return segments
+    .map((segment) =>
+      theme.fg(USAGE_SEVERITY_COLORS[segment.severity], flattenSegment(segment.text)),
+    )
+    .join("");
+}
+
+/** Pair the fast-mode segment with the usage segments for the status widget. */
+function statusWidgetParts(
+  fast: string | undefined,
+  usage: UsageSegment[] | undefined,
+): UsageSegment[] | undefined {
+  const parts: UsageSegment[] = fast ? [{ text: fast, severity: "muted" }] : [];
+  if (usage?.length) {
+    if (parts.length > 0) parts.push({ text: " · ", severity: "muted" });
+    parts.push(...usage);
+  }
+  return parts.length > 0 ? parts : undefined;
+}
+
 class DynamicBorder {
   readonly #color: (text: string) => string;
 
@@ -194,6 +242,11 @@ export default function betterGrok(pi: ExtensionAPI): void {
 
   function refresh(ctx: ExtensionContext): ResolvedConfig {
     cachedConfig = resolveConfig(ctx.cwd || process.cwd());
+    setGrokResetNetworkProfile(
+      cachedConfig.resets.cookies || cachedConfig.resets.userAgent
+        ? { cookies: cachedConfig.resets.cookies, userAgent: cachedConfig.resets.userAgent }
+        : undefined,
+    );
     return cachedConfig;
   }
 
@@ -542,8 +595,10 @@ export default function betterGrok(pi: ExtensionAPI): void {
           parts.push(contextText);
 
           const cfg = config(ctx);
-          const usageStatusLine = usageController.statusLine(ctx, cfg, usingSubscription);
-          const usageLine = usageStatusLine ? theme.fg("dim", usageStatusLine) : undefined;
+          const usageStatusSegments = usageController.statusSegments(ctx, cfg, usingSubscription);
+          const usageLine = usageStatusSegments
+            ? colorizeUsageSegments(usageStatusSegments, theme)
+            : undefined;
 
           let statsLeft = parts.join(" ");
           let statsLeftWidth = visibleWidth(statsLeft);
@@ -624,22 +679,22 @@ export default function betterGrok(pi: ExtensionAPI): void {
     statusInstalled = text !== undefined;
   }
 
-  function setStatusWidget(ctx: ExtensionContext, text: string | undefined): void {
-    if (!text && !statusWidgetInstalled) return;
+  function setStatusWidget(ctx: ExtensionContext, parts: UsageSegment[] | undefined): void {
+    if (!parts && !statusWidgetInstalled) return;
     ctx.ui.setWidget(
       STATUS_KEY,
-      text
+      parts
         ? (_tui, theme) => ({
             invalidate() {},
             render(width: number): string[] {
-              const line = theme.fg("dim", sanitizeStatusText(text));
+              const line = colorizeUsageSegments(parts, theme);
               return [truncateToWidth(line, width, theme.fg("dim", "..."))];
             },
           })
         : undefined,
       { placement: "belowEditor" },
     );
-    statusWidgetInstalled = text !== undefined;
+    statusWidgetInstalled = parts !== undefined;
   }
 
   function updateFooter(ctx: ExtensionContext): void {
@@ -672,8 +727,8 @@ export default function betterGrok(pi: ExtensionAPI): void {
     }
 
     const fast = fastController.statusSegment(ctx, cfg);
-    const usage = usageController.statusLine(ctx, cfg);
-    setStatusWidget(ctx, [fast, usage].filter(Boolean).join(" · ") || undefined);
+    const usage = usageController.statusSegments(ctx, cfg);
+    setStatusWidget(ctx, statusWidgetParts(fast, usage));
   }
 
   pi.on("session_start", (_event, ctx) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monotykamary/pi-better-grok",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "description": "Improve Grok/xAI in pi with fast mode, subscription usage stats, banked reset redemption, multiprovider pools, footer polish, and settings — mirroring pi-better-openai.",
   "keywords": [
     "footer",

package/src/config.ts

@@ -29,6 +29,14 @@ export type UsageConfig = {
 };
 export type FooterConfig = { mode?: FooterMode };
 
+// Cloudflare fronts the grok.com billing gRPC with a managed challenge that
+// non-browser runtimes cannot solve. A clearance cookie captured from a grok.com
+// browser session (bound to the browser user-agent and IP) unlocks the fetch.
+export type ResetConfig = {
+  cookies?: string;
+  userAgent?: string;
+};
+
 export interface ConfigFile {
   persistState?: boolean;
   active?: boolean;
@@ -37,6 +45,7 @@ export interface ConfigFile {
   fast?: FastConfig;
   usage?: UsageConfig;
   footer?: FooterConfig;
+  resets?: ResetConfig;
 }
 
 export interface SupportedModel {
@@ -57,6 +66,7 @@ export interface ResolvedConfig {
   fast: Required<FastConfig>;
   usage: Required<UsageConfig>;
   footer: Required<FooterConfig>;
+  resets: Required<ResetConfig>;
 }
 
 export const DEFAULT_FAST_CONFIG: Required<FastConfig> = { effort: "low" };
@@ -68,6 +78,7 @@ export const DEFAULT_USAGE_CONFIG: Required<UsageConfig> = {
   showBankedResets: true,
 };
 export const DEFAULT_FOOTER_CONFIG: Required<FooterConfig> = { mode: "status" };
+export const DEFAULT_RESET_CONFIG: Required<ResetConfig> = { cookies: "", userAgent: "" };
 export const DEFAULT_CONFIG: ConfigFile = {
   persistState: true,
   active: false,
@@ -76,6 +87,7 @@ export const DEFAULT_CONFIG: ConfigFile = {
   fast: DEFAULT_FAST_CONFIG,
   usage: DEFAULT_USAGE_CONFIG,
   footer: DEFAULT_FOOTER_CONFIG,
+  resets: DEFAULT_RESET_CONFIG,
 };
 
 type SettingsOptionSection = "footer" | "usage" | "fast";
@@ -322,5 +334,6 @@ export function resolveConfig(cwd: string, home = homedir(), env = process.env):
     fast: mergedSection(DEFAULT_FAST_CONFIG, globalRaw.fast, projectRaw.fast),
     usage: mergedSection(DEFAULT_USAGE_CONFIG, globalRaw.usage, projectRaw.usage),
     footer: mergedSection(DEFAULT_FOOTER_CONFIG, globalRaw.footer, projectRaw.footer),
+    resets: mergedSection(DEFAULT_RESET_CONFIG, globalRaw.resets, projectRaw.resets),
   };
 }

package/src/resets.ts

@@ -360,13 +360,28 @@ export function mapGrokRedeemStatus(
   );
 }
 
+export type ResetNetworkProfile = { cookies?: string; userAgent?: string };
+
+let networkProfile: ResetNetworkProfile | undefined;
+
+// Optional Cloudflare clearance profile: cookies captured from a grok.com
+// browser session (at minimum cf_clearance) plus the user-agent that solved
+// the challenge. Cloudflare binds the clearance to the user-agent and IP, and
+// pi runs on the same machine as the browser, so only the user-agent must match.
+export function setGrokResetNetworkProfile(profile: ResetNetworkProfile | undefined): void {
+  networkProfile = profile?.cookies || profile?.userAgent ? profile : undefined;
+}
+
 function resetHeaders(credential: GrokCredential): Record<string, string> {
-  return {
+  const headers: Record<string, string> = {
     Authorization: `Bearer ${credential.token}`,
     "X-XAI-Token-Auth": GROK_CLI_AUTH_HEADER,
     "Content-Type": GRPC_WEB_CONTENT_TYPE,
     "x-grpc-web": "1",
   };
+  if (networkProfile?.cookies) headers.Cookie = networkProfile.cookies;
+  if (networkProfile?.userAgent) headers["User-Agent"] = networkProfile.userAgent;
+  return headers;
 }
 
 async function postGrokRpc(
@@ -393,7 +408,9 @@ async function postGrokRpc(
     if (response.headers.get("cf-mitigated") === "challenge") {
       throw new ResetError(
         "challenge",
-        `grok.com is serving a Cloudflare browser challenge (HTTP ${response.status}); banked reset data cannot be fetched from a non-browser client.`,
+        networkProfile?.cookies
+          ? `grok.com answered with a Cloudflare challenge even with the configured clearance cookie (HTTP ${response.status}); it likely expired or no longer matches the browser user-agent. Re-copy it from a grok.com browser session.`
+          : `grok.com is serving a Cloudflare browser challenge (HTTP ${response.status}); banked reset data cannot be fetched from a non-browser client. Set resets.cookies and resets.userAgent in the Better Grok config from a grok.com browser session to enable it.`,
         response.status,
       );
     }

package/src/usage-controller.ts

@@ -3,7 +3,13 @@ import type { ResolvedConfig } from "./config.ts";
 import { isXaiProvider, readPiStoredOAuthToken } from "./grok-auth.ts";
 import { sanitizeDiagnosticError } from "./format.ts";
 import { currentModelKey } from "./fast-controller.ts";
-import { formatUsageDetail, formatUsageSnapshot, type UsageSnapshot } from "./usage.ts";
+import {
+  type UsageSegment,
+  type UsageSnapshot,
+  formatUsageDetail,
+  formatUsageSnapshot,
+  usageSegments,
+} from "./usage.ts";
 
 export function isGrokSubscriptionModel(
   ctx: Pick<ExtensionContext, "model" | "modelRegistry">,
@@ -77,22 +83,32 @@ export class UsageController {
     return this.usageSnapshot;
   }
 
-  statusLine(
+  statusSegments(
     ctx: ExtensionContext,
     cfg = this.getConfig(ctx),
     isUsingOAuth?: boolean,
-  ): string | undefined {
+  ): UsageSegment[] | undefined {
     return this.usageSnapshot &&
       !this.usageError &&
       cfg.usage.enabled &&
       isGrokSubscriptionModel(ctx, cfg, isUsingOAuth)
-      ? formatUsageSnapshot(this.usageSnapshot, {
+      ? usageSegments(this.usageSnapshot, {
           ...cfg.usage,
           bankedResets: this.getBankedResets?.() ?? null,
         })
       : undefined;
   }
 
+  statusLine(
+    ctx: ExtensionContext,
+    cfg = this.getConfig(ctx),
+    isUsingOAuth?: boolean,
+  ): string | undefined {
+    return this.statusSegments(ctx, cfg, isUsingOAuth)
+      ?.map((segment) => segment.text)
+      .join("");
+  }
+
   formatStatus(ctx: ExtensionContext): string {
     const cfg = this.getConfig(ctx);
     if (!cfg.usage.enabled) return "Usage display is disabled.";

package/src/usage.ts

@@ -241,24 +241,59 @@ export function formatBankedResetsSuffix(count: number | null | undefined): stri
   return `${count} banked reset${count === 1 ? "" : "s"}`;
 }
 
-export function formatUsageSnapshot(
+export type UsageSeverity = "ok" | "warning" | "critical" | "muted";
+
+export type UsageSegment = {
+  text: string;
+  severity: UsageSeverity;
+};
+
+/** Remaining budget at or below these thresholds turns the percentage amber/red. */
+const WARNING_LEFT_PERCENT = 30;
+const CRITICAL_LEFT_PERCENT = 10;
+
+export function severityForLeftPercent(percent: number | null): UsageSeverity {
+  if (percent === null) return "muted";
+  if (percent <= CRITICAL_LEFT_PERCENT) return "critical";
+  if (percent <= WARNING_LEFT_PERCENT) return "warning";
+  return "ok";
+}
+
+export function usageSegments(
   snapshot: UsageSnapshot,
   options: UsageStatusOptions,
   now = Date.now(),
-): string {
+): UsageSegment[] {
   const used = snapshot.creditUsagePercent;
   const left = used === null ? null : clampPercent(100 - used);
-  const parts = [`Usage: ${formatPercent(left)} left`];
+  const segments: UsageSegment[] = [
+    { text: "Usage: ", severity: "muted" },
+    { text: formatPercent(left), severity: severityForLeftPercent(left) },
+    { text: " left", severity: "muted" },
+  ];
   if (options.showResetTimes) {
     const seconds = periodSecondsLeft(snapshot, now);
     const countdown = formatResetCountdown(seconds);
     const clock = formatResetClock(seconds, now);
-    if (countdown && clock) parts.push(`↺ ${countdown} - ${clock}`);
+    if (countdown && clock) {
+      segments.push({ text: ` · ↺ ${countdown} - ${clock}`, severity: "muted" });
+    }
   }
   const banked =
     options.showBankedResets === false ? null : formatBankedResetsSuffix(options.bankedResets);
-  if (banked) parts.push(banked);
-  return parts.join(" · ");
+  if (banked) segments.push({ text: ` · ${banked}`, severity: "muted" });
+  return segments;
+}
+
+/** Flat text form of {@link usageSegments}, used for status lines and notifications. */
+export function formatUsageSnapshot(
+  snapshot: UsageSnapshot,
+  options: UsageStatusOptions,
+  now = Date.now(),
+): string {
+  return usageSegments(snapshot, options, now)
+    .map((segment) => segment.text)
+    .join("");
 }
 
 export function formatUsageDetail(snapshot: UsageSnapshot): string {