@monotykamary/pi-better-grok 0.1.4 → 0.2.0

package/README.md

@@ -16,6 +16,7 @@ pi install git:github.com/monotykamary/pi-better-grok
 | `pi --grok-fast`    | Start with fast mode enabled                                                                                                 |
 | `/grok-usage`       | Force-refresh and show SuperGrok subscription usage                                                                          |
 | `/grok-usage debug` | Show diagnostics (auth source, last fetch, config path)                                                                      |
+| `/grok-resets`      | Inspect and redeem SuperGrok banked rate-limit resets                                                                        |
 | `/grok-settings`    | Open the settings picker (footer, usage, fast mode)                                                                          |
 
 ## Usage widget
@@ -29,6 +30,16 @@ Data comes from the same revision-pinned Grok subscription surface used by the c
 
 Status widget line: `Usage: 66% left · ↺ 5d5h - Mon 5:34 PM` (weekly period + reset clock). Defaults to the widget area below the editor, like pi-better-openai; set `"footer": {"mode": "replace"}` for the full custom footer.
 
+## Banked resets
+
+SuperGrok plans earn banked rate-limit reset tokens: redeeming one restores the weekly usage limit early. `/grok-resets` lists the remaining inventory, asks which token to redeem when several are available, and always confirms before spending one — redemption is immediate and cannot be undone. The inventory is warmed at session start and refreshed on a 5-minute TTL, so the command opens instantly; the server re-validates every redemption, so a stale offer can never be consumed twice.
+
+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.
+
+## pi-multiprovider
+
+When [pi-multiprovider](https://github.com/monotykamary/pi-multiprovider) pools several `xai` accounts, the session's active account (chosen with `/switch-account`) is resolved first for usage display and banked resets, and the usage widget refreshes on every switch. Without that extension, credential resolution is unchanged: pi's native `xai` OAuth, then `xai-oauth`/`xai-auth` auth-file entries, then the Grok CLI store.
+
 ## Configuration
 
 JSON config at `~/.pi/agent/extensions/pi-better-grok.json` (global) or `<project>/.pi/extensions/pi-better-grok.json` (project):
@@ -58,7 +69,7 @@ Unknown fields are preserved on write.
 
 ## Acknowledgments
 
-Protocol contracts and prior art: [stnly/pi-grok](https://github.com/stnly/pi-grok), [puetsua/pi-grok-usage](https://github.com/puetsua/pi-grok-usage), [apoapostolov/pi-grok-usage](https://github.com/apoapostolov/pi-grok-usage), [luxus/pi-xai](https://github.com/luxus/pi-xai). See `THIRD_PARTY_NOTICES.md`.
+Protocol contracts and prior art: [stnly/pi-grok](https://github.com/stnly/pi-grok), [puetsua/pi-grok-usage](https://github.com/puetsua/pi-grok-usage), [apoapostolov/pi-grok-usage](https://github.com/apoapostolov/pi-grok-usage), [luxus/pi-xai](https://github.com/luxus/pi-xai), and the SuperGrok reset-token surface documented by [stablyai/orca #18116](https://github.com/stablyai/orca/pull/18116). See `THIRD_PARTY_NOTICES.md`.
 
 ## Security
 

package/index.ts

@@ -10,7 +10,27 @@
 import { type ExtensionAPI, type ExtensionContext } 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 { formatTokens, sanitizeStatusText, truncateToWidth, visibleWidth } from "./src/format.ts";
+import {
+  formatTokens,
+  sanitizeDiagnosticError,
+  sanitizeStatusText,
+  truncateToWidth,
+  visibleWidth,
+} from "./src/format.ts";
+import {
+  isMultiproviderService,
+  MULTIPROVIDER_SERVICE_EVENT,
+  setActiveMultiproviderService,
+  type MultiproviderService,
+} from "./src/multiprovider.ts";
+import {
+  buildGrokResetConfirmation,
+  formatGrokResetChoice,
+  formatGrokResetOutcome,
+  redeemGrokResetForSession,
+  selectGrokResetToken,
+} from "./src/resets.ts";
+import { ResetController } from "./src/reset-controller.ts";
 import {
   applySettingToRawConfig,
   configPaths,
@@ -81,6 +101,7 @@ class DynamicBorder {
 const COMMAND = "grok-fast";
 const USAGE_COMMAND = "grok-usage";
 const SETTINGS_COMMAND = "grok-settings";
+const RESETS_COMMAND = "grok-resets";
 const FLAG = "grok-fast";
 
 type SettingsPickerItem = {
@@ -132,6 +153,39 @@ export default function betterGrok(pi: ExtensionAPI): void {
   let cachedSessionNameLeafId: string | null | undefined;
   let cachedSessionName: string | undefined;
   const usageController = new UsageController(config, updateFooter, fetchUsageSnapshot);
+  const resetController = new ResetController();
+  let multiproviderService: MultiproviderService | undefined;
+  let unsubscribeMultiprovider: (() => void) | undefined;
+  let multiproviderRefreshCtx: ExtensionContext | undefined;
+
+  // Follow pi-multiprovider's active pooled account for the native xAI
+  // providers. The event re-fires with the same stable object at load and
+  // session start; the identity check keeps the change subscriptions attached
+  // exactly once. When the extension is absent, nothing here activates and
+  // credential resolution keeps its standalone behavior.
+  if (typeof pi.events?.on === "function") {
+    pi.events.on(MULTIPROVIDER_SERVICE_EVENT, (value) => {
+      if (!isMultiproviderService(value) || value === multiproviderService) return;
+      unsubscribeMultiprovider?.();
+      multiproviderService = value;
+      setActiveMultiproviderService(value);
+      const offs = XAI_PROVIDER_IDS.map((providerId) =>
+        value.onActiveAccountChanged(providerId, (event) => {
+          void usageController.refresh(event.ctx, { force: true });
+          void resetController.refresh(event.ctx, { force: true }).catch(() => {});
+          updateFooter(event.ctx);
+        }),
+      );
+      unsubscribeMultiprovider = () => {
+        for (const off of offs) off();
+      };
+      const ctx = multiproviderRefreshCtx;
+      if (ctx) {
+        void usageController.refresh(ctx, { force: true });
+        updateFooter(ctx);
+      }
+    });
+  }
 
   function refresh(ctx: ExtensionContext): ResolvedConfig {
     cachedConfig = resolveConfig(ctx.cwd || process.cwd());
@@ -240,6 +294,64 @@ export default function betterGrok(pi: ExtensionAPI): void {
     },
   });
 
+  async function redeemBankedReset(ctx: ExtensionContext): Promise<void> {
+    if (!hasTerminalUI(ctx)) {
+      ctx.ui.notify("/grok-resets requires an interactive TUI session.", "warning");
+      return;
+    }
+    let credits = resetController.snapshot?.credits;
+    if (!credits) {
+      await resetController.refresh(ctx, { force: true }).catch(() => {});
+      credits = resetController.snapshot?.credits;
+    }
+    if (!credits) {
+      const reason = resetController.lastError;
+      ctx.ui.notify(`Banked reset lookup failed${reason ? `: ${reason}` : "."}`, "error");
+      return;
+    }
+    void resetController.refresh(ctx).catch(() => {});
+    if (credits.availableCount <= 0) {
+      ctx.ui.notify("No banked Grok resets are available for this account.", "info");
+      return;
+    }
+    let selected = selectGrokResetToken(credits.tokens);
+    if (credits.tokens.length > 1 && selected) {
+      const options = credits.tokens.map((token, index) => formatGrokResetChoice(token, index));
+      const chosen = await ctx.ui.select("Redeem which banked reset?", options);
+      if (chosen === undefined) {
+        ctx.ui.notify("Banked reset redemption cancelled.", "info");
+        return;
+      }
+      selected = credits.tokens[Math.max(0, options.indexOf(chosen))];
+    }
+    const confirmation = buildGrokResetConfirmation({
+      token: selected,
+      availableCount: credits.availableCount,
+      snapshot: usageController.snapshot,
+    });
+    if (!(await ctx.ui.confirm(confirmation.title, confirmation.message))) {
+      ctx.ui.notify("Banked reset redemption cancelled.", "info");
+      return;
+    }
+    try {
+      const timeoutSignal = AbortSignal.timeout(30_000);
+      const signal = ctx.signal ? AbortSignal.any([ctx.signal, timeoutSignal]) : timeoutSignal;
+      const result = await redeemGrokResetForSession(ctx, selected?.tokenId, signal);
+      const outcome = formatGrokResetOutcome(result);
+      ctx.ui.notify(outcome.message, outcome.level);
+      void usageController.refresh(ctx, { force: true });
+      void resetController.refresh(ctx, { force: true }).catch(() => {});
+      updateFooter(ctx);
+    } catch (error) {
+      ctx.ui.notify(
+        `Banked reset redemption failed: ${sanitizeDiagnosticError(
+          error instanceof Error ? error.message : String(error),
+        )}`,
+        "error",
+      );
+    }
+  }
+
   pi.registerCommand(USAGE_COMMAND, {
     description: "Show Grok subscription usage status",
     handler: async (args, ctx) => {
@@ -354,6 +466,13 @@ export default function betterGrok(pi: ExtensionAPI): void {
     }
   }
 
+  pi.registerCommand(RESETS_COMMAND, {
+    description: "Inspect and redeem SuperGrok banked rate-limit resets",
+    handler: async (_args, ctx) => {
+      await redeemBankedReset(ctx);
+    },
+  });
+
   pi.registerCommand(SETTINGS_COMMAND, {
     description: "Open Better Grok settings picker",
     handler: async (_args, ctx) => {
@@ -555,6 +674,7 @@ export default function betterGrok(pi: ExtensionAPI): void {
   pi.on("session_start", (_event, ctx) => {
     invalidateContextUsage();
     invalidateSessionName();
+    multiproviderRefreshCtx = ctx;
     const nextConfig = refresh(ctx);
     fastController.initializeForSession(ctx, nextConfig, pi.getFlag(FLAG) === true);
     if (
@@ -566,6 +686,9 @@ export default function betterGrok(pi: ExtensionAPI): void {
     refreshFooterTotals(ctx);
     updateFooter(ctx);
     usageController.start(ctx);
+    if (nextConfig.usage.enabled && isGrokSubscriptionModel(ctx, nextConfig)) {
+      resetController.start(ctx);
+    }
     if (fastController.active) ctx.ui.notify(fastController.stateText(nextConfig), "info");
   });
 
@@ -623,6 +746,7 @@ export default function betterGrok(pi: ExtensionAPI): void {
     invalidateContextUsage();
     invalidateSessionName();
     usageController.shutdown();
+    resetController.stop();
   });
 
   pi.on("before_provider_request", (event, ctx) => {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@monotykamary/pi-better-grok",
-  "version": "0.1.4",
-  "description": "Improve Grok/xAI in pi with fast mode, subscription usage stats, footer polish, and settings — mirroring pi-better-openai.",
+  "version": "0.2.0",
+  "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",
     "grok",

package/src/grok-auth.ts

@@ -1,6 +1,7 @@
 import { readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getActiveMultiproviderService } from "./multiprovider.ts";
 import { piAgentDir } from "./paths.ts";
 
 // Native pi providers that may hold an xAI OAuth credential, in preference order.
@@ -14,9 +15,16 @@ export const GROK_CLI_LEGACY_AUTH_SCOPE_KEY = "https://accounts.x.ai/sign-in";
 
 export type GrokCredential = {
   token: string;
-  source: "modelRegistry" | "authFile" | "grokCli";
+  source: "multiprovider" | "modelRegistry" | "authFile" | "grokCli";
 };
 
+// Credential context slice; the multiprovider resolver keys pool affinity off
+// the session, so a sessionManager must be present for that path.
+export type GrokCredentialContext = Pick<
+  ExtensionContext,
+  "model" | "modelRegistry" | "sessionManager"
+>;
+
 export function isXaiProvider(provider: unknown): provider is XaiProviderId {
   return typeof provider === "string" && (XAI_PROVIDER_IDS as readonly string[]).includes(provider);
 }
@@ -197,8 +205,23 @@ export function readGrokCliToken(env: NodeJS.ProcessEnv = process.env): string |
 }
 
 export async function resolveGrokCredential(
-  ctx: Pick<ExtensionContext, "model" | "modelRegistry">,
+  ctx: GrokCredentialContext,
 ): Promise<GrokCredential | null> {
+  // A pooled account pinned for this session (pi-multiprovider /switch-account)
+  // wins over pi's own credential: subscription usage is per-account. Resolve
+  // in native xAI provider-id preference order.
+  const multiprovider = getActiveMultiproviderService();
+  if (multiprovider && ctx) {
+    for (const providerId of providerIdsFor(ctx)) {
+      try {
+        const resolved = await multiprovider.resolveActiveAccountAuth(providerId, ctx);
+        const token = resolved?.accessToken?.trim();
+        if (token) return { token, source: "multiprovider" };
+      } catch {
+        // Fall through to pi-owned credential resolution.
+      }
+    }
+  }
   const registry = (ctx as { modelRegistry?: unknown })?.modelRegistry;
   const modelRuntime = (ctx as { modelRuntime?: unknown })?.modelRuntime;
   if (registry && typeof registry === "object" && "find" in registry) {

package/src/multiprovider.ts

@@ -0,0 +1,67 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+// Soft bridge to pi-multiprovider, mirroring pi-better-openai. When that
+// extension is installed it emits this event with a service object; without it
+// everything here stays inert and credential resolution keeps its standalone
+// behavior. Unlike Codex, xAI has several native provider ids, so consumers
+// subscribe per id instead of one canonical provider.
+export const MULTIPROVIDER_SERVICE_EVENT = "pi-multiprovider:service";
+
+export type MultiproviderActiveAccount = {
+  id: string;
+  label: string;
+  authKind: string;
+};
+
+export type MultiproviderAccountAuth = {
+  accessToken: string;
+  label: string;
+  source?: string;
+};
+
+export type MultiproviderAccountChangedEvent = {
+  providerId: string;
+  account: MultiproviderActiveAccount | undefined;
+  ctx: ExtensionContext;
+};
+
+export type MultiproviderServiceContext = Pick<
+  ExtensionContext,
+  "modelRegistry" | "model" | "sessionManager"
+>;
+
+export type MultiproviderService = {
+  getActiveAccount(
+    providerId: string,
+    ctx: MultiproviderServiceContext,
+  ): Promise<MultiproviderActiveAccount | undefined>;
+  resolveActiveAccountAuth(
+    providerId: string,
+    ctx: MultiproviderServiceContext,
+    signal?: AbortSignal,
+  ): Promise<MultiproviderAccountAuth | undefined>;
+  onActiveAccountChanged(
+    providerId: string,
+    callback: (event: MultiproviderAccountChangedEvent) => void,
+  ): () => void;
+};
+
+export function isMultiproviderService(value: unknown): value is MultiproviderService {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as Partial<MultiproviderService>;
+  return (
+    typeof candidate.getActiveAccount === "function" &&
+    typeof candidate.resolveActiveAccountAuth === "function" &&
+    typeof candidate.onActiveAccountChanged === "function"
+  );
+}
+
+let activeService: MultiproviderService | undefined;
+
+export function setActiveMultiproviderService(service: MultiproviderService | undefined): void {
+  activeService = service;
+}
+
+export function getActiveMultiproviderService(): MultiproviderService | undefined {
+  return activeService;
+}

package/src/reset-controller.ts

@@ -0,0 +1,97 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { sanitizeDiagnosticError } from "./format.ts";
+import { type GrokResetCredits, requestGrokResetCredits } from "./resets.ts";
+
+export const BANKED_RESET_CACHE_TTL_MS = 5 * 60_000;
+const BANKED_RESET_REQUEST_TIMEOUT_MS = 10_000;
+
+export type BankedResetCache = {
+  credits: GrokResetCredits;
+  updatedAt: number;
+};
+
+// Keeps the banked-reset token inventory warm so /grok-resets opens without
+// paying the credential-resolution + billing RPC round trip. The cache is
+// prefetched at session start, refreshed on a TTL, and served even when stale
+// (a stale open still kicks off a background refresh; the backend re-validates
+// every redemption server-side, so a stale offer can never be consumed twice).
+export class ResetController {
+  private cache: BankedResetCache | undefined;
+  private error: string | undefined;
+  private lastFetchAt: number | undefined;
+  private inFlight: Promise<void> | undefined;
+  private timer: ReturnType<typeof setInterval> | undefined;
+  private sessionSignal: AbortSignal | undefined;
+  private sessionAbortHandler: (() => void) | undefined;
+
+  get snapshot(): BankedResetCache | undefined {
+    return this.cache;
+  }
+
+  get lastError(): string | undefined {
+    return this.error;
+  }
+
+  isFresh(now = Date.now()): boolean {
+    return this.cache !== undefined && now - this.cache.updatedAt < BANKED_RESET_CACHE_TTL_MS;
+  }
+
+  refresh(ctx: ExtensionContext, options?: { force?: boolean }): Promise<void> {
+    if (this.inFlight) return this.inFlight;
+    if (
+      !options?.force &&
+      this.lastFetchAt !== undefined &&
+      Date.now() - this.lastFetchAt < BANKED_RESET_CACHE_TTL_MS
+    )
+      return Promise.resolve();
+    this.lastFetchAt = Date.now();
+    const timeoutSignal = AbortSignal.timeout(BANKED_RESET_REQUEST_TIMEOUT_MS);
+    const signal = ctx.signal ? AbortSignal.any([ctx.signal, timeoutSignal]) : timeoutSignal;
+    const task = (async () => {
+      try {
+        const credits = await requestGrokResetCredits(ctx, signal);
+        if (credits) {
+          this.cache = { credits, updatedAt: Date.now() };
+          this.error = undefined;
+        } else {
+          this.error = "xAI credentials unavailable.";
+        }
+      } catch (error) {
+        this.error = sanitizeDiagnosticError(
+          error instanceof Error ? error.message : String(error),
+        );
+      } finally {
+        this.inFlight = undefined;
+      }
+    })();
+    this.inFlight = task;
+    return task;
+  }
+
+  start(ctx: ExtensionContext): void {
+    this.stop();
+    if (ctx.signal?.aborted) return;
+    this.sessionSignal = ctx.signal;
+    this.sessionAbortHandler = () => this.stop();
+    ctx.signal?.addEventListener("abort", this.sessionAbortHandler, { once: true });
+    void this.refresh(ctx).catch(() => {});
+    this.timer = setInterval(() => {
+      if (ctx.signal?.aborted) {
+        this.stop();
+        return;
+      }
+      void this.refresh(ctx).catch(() => {});
+    }, BANKED_RESET_CACHE_TTL_MS);
+    this.timer.unref?.();
+  }
+
+  stop(): void {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = undefined;
+    if (this.sessionSignal && this.sessionAbortHandler) {
+      this.sessionSignal.removeEventListener("abort", this.sessionAbortHandler);
+    }
+    this.sessionSignal = undefined;
+    this.sessionAbortHandler = undefined;
+  }
+}

package/src/resets.ts

@@ -0,0 +1,542 @@
+import { maskIdentifier } from "./format.ts";
+import {
+  resolveGrokCredential,
+  type GrokCredential,
+  type GrokCredentialContext,
+} from "./grok-auth.ts";
+import { formatPercent, type UsageSnapshot } from "./usage.ts";
+
+// SuperGrok banked rate-limit resets. The inventory and redeem calls ride the
+// grok.com consumer billing gRPC-Web service that the web usage page itself
+// calls, authenticated with the same xAI OAuth token the usage meter uses.
+// This is an undocumented surface: request shapes are pinned here and schema
+// drift is expected — treat responses defensively and re-validate everything.
+export const GROK_REMAINING_RESETS_URL =
+  "https://grok.com/prod_mc_billing.ConsumerUiSvc/GetRemainingResets";
+export const GROK_REDEEM_RESET_URL = "https://grok.com/prod_mc_billing.ConsumerUiSvc/RedeemReset";
+
+// Why: the billing RPC accepts the CLI token with only gRPC-Web framing; browser
+// identity headers add no authorization (same pattern as the usage surface).
+export const GROK_CLI_AUTH_HEADER = "xai-grok-cli";
+export const GRPC_WEB_CONTENT_TYPE = "application/grpc-web+proto";
+
+const LIST_TIMEOUT_MS = 10_000;
+const REDEEM_TIMEOUT_MS = 30_000;
+const MAX_RESPONSE_BYTES = 256 * 1024;
+const MAX_TOKEN_ID_LENGTH = 128;
+const MAX_TOKENS = 64;
+
+export type GrokResetToken = {
+  tokenId: string;
+  grantedAtMs: number | null;
+  expiresAtMs: number | null;
+};
+
+export type GrokResetCredits = {
+  availableCount: number;
+  nextExpiresAtMs: number | null;
+  tokens: GrokResetToken[];
+};
+
+export type GrokRedeemCode = "reset" | "no_credit" | "already_redeemed";
+
+export type GrokRedeemResult = { code: GrokRedeemCode };
+
+export type ResetErrorCode = "auth" | "http" | "grpc" | "invalid" | "oversize" | "transport";
+
+export class ResetError extends Error {
+  readonly code: ResetErrorCode;
+  readonly status?: number;
+  readonly grpcStatus?: string;
+
+  constructor(code: ResetErrorCode, message: string, status?: number, grpcStatus?: string) {
+    super(message);
+    this.name = "ResetError";
+    this.code = code;
+    this.status = status;
+    this.grpcStatus = grpcStatus;
+  }
+}
+
+export const EMPTY_RESET_CREDITS: GrokResetCredits = {
+  availableCount: 0,
+  nextExpiresAtMs: null,
+  tokens: [],
+};
+
+// gRPC-Web protobuf codec. Field numbers follow grok.com's public consumer_ui
+// descriptor: ConsumerRedeemResetReq.token_id is field 10, remaining-reset
+// responses carry repeated token messages on field 10 with inner fields
+// 10 (token_id string), 20 (granted_at Timestamp), 30 (expires_at Timestamp).
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+
+function encodeVarint(value: number): Uint8Array<ArrayBuffer> {
+  if (!Number.isFinite(value) || value < 0)
+    throw new ResetError("invalid", "Varint must be a non-negative finite number.");
+  let n = Math.floor(value);
+  const bytes: number[] = [];
+  while (n > 0x7f) {
+    bytes.push((n & 0x7f) | 0x80);
+    n = Math.floor(n / 128);
+  }
+  bytes.push(n);
+  return Uint8Array.from(bytes);
+}
+
+function encodeKey(field: number, wireType: number): Uint8Array<ArrayBuffer> {
+  return encodeVarint((field << 3) | wireType);
+}
+
+function concatBytes(parts: readonly Uint8Array<ArrayBufferLike>[]): Uint8Array<ArrayBuffer> {
+  const total = parts.reduce((sum, part) => sum + part.byteLength, 0);
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const part of parts) {
+    out.set(part, offset);
+    offset += part.byteLength;
+  }
+  return out;
+}
+
+function encodeLengthDelimited(
+  field: number,
+  data: Uint8Array<ArrayBufferLike>,
+): Uint8Array<ArrayBuffer> {
+  return concatBytes([encodeKey(field, 2), encodeVarint(data.byteLength), data]);
+}
+
+export function encodeStringField(field: number, value: string): Uint8Array<ArrayBuffer> {
+  return encodeLengthDelimited(field, textEncoder.encode(value));
+}
+
+export function encodeRedeemResetRequest(tokenId: string): Uint8Array<ArrayBuffer> {
+  return encodeStringField(10, tokenId);
+}
+
+function encodeGrpcWebFrame(
+  flags: number,
+  payload: Uint8Array<ArrayBufferLike>,
+): Uint8Array<ArrayBuffer> {
+  const header = new Uint8Array(5);
+  header[0] = flags;
+  header[1] = (payload.byteLength >>> 24) & 0xff;
+  header[2] = (payload.byteLength >>> 16) & 0xff;
+  header[3] = (payload.byteLength >>> 8) & 0xff;
+  header[4] = payload.byteLength & 0xff;
+  return concatBytes([header, payload]);
+}
+
+// Why: grok.com accepts a data frame only on the request; trailers are a
+// response convention.
+export function encodeGrpcWebRequest(
+  payload: Uint8Array<ArrayBufferLike>,
+): Uint8Array<ArrayBuffer> {
+  return encodeGrpcWebFrame(0, payload);
+}
+
+export type GrpcWebResponse = {
+  payload: Uint8Array;
+  grpcStatus: string;
+  grpcMessage: string | null;
+};
+
+function decodeVarint(buf: Uint8Array, start: number): { value: number; next: number } {
+  let value = 0;
+  let shift = 0;
+  let i = start;
+  while (i < buf.byteLength) {
+    const byte = buf[i++];
+    if (byte === undefined) break;
+    value += (byte & 0x7f) * 2 ** shift;
+    if ((byte & 0x80) === 0) return { value, next: i };
+    shift += 7;
+    if (shift > 35)
+      throw new ResetError("invalid", "Grok reset response contained an oversized varint.");
+  }
+  throw new ResetError("invalid", "Grok reset response contained a truncated varint.");
+}
+
+type ProtoField =
+  | { field: number; wireType: 0; value: number }
+  | { field: number; wireType: 2; value: Uint8Array };
+
+function decodeFields(buf: Uint8Array): ProtoField[] {
+  const fields: ProtoField[] = [];
+  let i = 0;
+  while (i < buf.byteLength) {
+    const key = decodeVarint(buf, i);
+    i = key.next;
+    const field = key.value >>> 3;
+    const wireType = key.value & 7;
+    if (wireType === 0) {
+      const varint = decodeVarint(buf, i);
+      i = varint.next;
+      fields.push({ field, wireType: 0, value: varint.value });
+    } else if (wireType === 2) {
+      const length = decodeVarint(buf, i);
+      i = length.next;
+      const end = i + length.value;
+      if (end > buf.byteLength)
+        throw new ResetError("invalid", "Grok reset response contained a truncated field.");
+      fields.push({ field, wireType: 2, value: buf.subarray(i, end) });
+      i = end;
+    } else if (wireType === 1) {
+      if (i + 8 > buf.byteLength)
+        throw new ResetError("invalid", "Grok reset response contained a truncated fixed64 field.");
+      i += 8;
+    } else if (wireType === 5) {
+      if (i + 4 > buf.byteLength)
+        throw new ResetError("invalid", "Grok reset response contained a truncated fixed32 field.");
+      i += 4;
+    } else {
+      throw new ResetError(
+        "invalid",
+        `Grok reset response used an unsupported wire type (${wireType}).`,
+      );
+    }
+  }
+  return fields;
+}
+
+function decodeTimestampMs(data: Uint8Array): number | null {
+  const seconds = decodeFields(data).find((entry) => entry.field === 1 && entry.wireType === 0);
+  if (!seconds || seconds.wireType !== 0) return null;
+  return seconds.value * 1000;
+}
+
+export function decodeRemainingResetTokens(payload: Uint8Array): GrokResetToken[] {
+  const tokens: GrokResetToken[] = [];
+  for (const entry of decodeFields(payload)) {
+    if (entry.field !== 10 || entry.wireType !== 2) continue;
+    let tokenId: string | null = null;
+    let grantedAtMs: number | null = null;
+    let expiresAtMs: number | null = null;
+    for (const inner of decodeFields(entry.value)) {
+      if (inner.field === 10 && inner.wireType === 2) tokenId = textDecoder.decode(inner.value);
+      else if (inner.field === 20 && inner.wireType === 2)
+        grantedAtMs = decodeTimestampMs(inner.value);
+      else if (inner.field === 30 && inner.wireType === 2)
+        expiresAtMs = decodeTimestampMs(inner.value);
+    }
+    if (tokenId) tokens.push({ tokenId, grantedAtMs, expiresAtMs });
+  }
+  return tokens;
+}
+
+function parseTrailerBlock(text: string): { status: string | null; message: string | null } {
+  let status: string | null = null;
+  let message: string | null = null;
+  for (const line of text.split(/\r?\n/)) {
+    const idx = line.indexOf(":");
+    if (idx <= 0) continue;
+    const key = line.slice(0, idx).trim().toLowerCase();
+    const value = line.slice(idx + 1).trim();
+    if (key === "grpc-status") status = value;
+    else if (key === "grpc-message") {
+      try {
+        message = decodeURIComponent(value);
+      } catch {
+        message = value;
+      }
+    }
+  }
+  return { status, message };
+}
+
+export function decodeGrpcWebResponse(
+  raw: Uint8Array,
+  headerStatus?: string | null,
+  headerMessage?: string | null,
+): GrpcWebResponse {
+  let payload: Uint8Array = new Uint8Array(0);
+  let trailerStatus: string | null = null;
+  let trailerMessage: string | null = null;
+  let i = 0;
+  while (i < raw.byteLength) {
+    if (raw.byteLength - i < 5)
+      throw new ResetError("invalid", "Grok reset response had a truncated gRPC-Web frame header.");
+    const flags = raw[i]!;
+
+    const length =
+      raw[i + 1]! * 0x1000000 + raw[i + 2]! * 0x10000 + raw[i + 3]! * 0x100 + raw[i + 4]!;
+    i += 5;
+    const end = i + length;
+    if (end > raw.byteLength)
+      throw new ResetError(
+        "invalid",
+        "Grok reset response had a truncated gRPC-Web frame payload.",
+      );
+    const chunk = raw.subarray(i, end);
+    i = end;
+    if (flags & 0x80) {
+      const parsed = parseTrailerBlock(textDecoder.decode(chunk));
+      trailerStatus = parsed.status;
+      trailerMessage = parsed.message;
+      break;
+    }
+    payload = chunk;
+  }
+  const grpcStatus = trailerStatus ?? headerStatus;
+  if (grpcStatus == null)
+    throw new ResetError("invalid", "Grok reset response was missing grpc-status.");
+  return { payload, grpcStatus, grpcMessage: trailerMessage ?? headerMessage ?? null };
+}
+
+function isPrintableAscii(value: string): boolean {
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code < 0x21 || code > 0x7e) return false;
+  }
+  return true;
+}
+
+function sanitizeTokenId(value: string): string | null {
+  return value && value.length <= MAX_TOKEN_ID_LENGTH && isPrintableAscii(value) ? value : null;
+}
+
+export function summarizeResetTokens(tokens: readonly GrokResetToken[]): GrokResetCredits {
+  const sanitized = tokens
+    .map((token) => {
+      const tokenId = sanitizeTokenId(token.tokenId);
+      return tokenId ? { ...token, tokenId } : undefined;
+    })
+    .filter((token): token is GrokResetToken => token !== undefined)
+    .slice(0, MAX_TOKENS);
+  const expiries = sanitized
+    .map((token) => token.expiresAtMs)
+    .filter((expiresAtMs): expiresAtMs is number => typeof expiresAtMs === "number")
+    .sort((left, right) => left - right);
+  return {
+    availableCount: sanitized.length,
+    nextExpiresAtMs: expiries[0] ?? null,
+    tokens: sanitized,
+  };
+}
+
+// Soonest-expiring token first: banked resets expire, so spend the one closest
+// to expiry. Tokens without an expiry sort last.
+export function selectGrokResetToken(
+  tokens: readonly GrokResetToken[],
+): GrokResetToken | undefined {
+  return [...tokens].sort((left, right) => {
+    const leftExpiry = left.expiresAtMs ?? Number.POSITIVE_INFINITY;
+    const rightExpiry = right.expiresAtMs ?? Number.POSITIVE_INFINITY;
+    if (leftExpiry !== rightExpiry) return leftExpiry - rightExpiry;
+    return (left.grantedAtMs ?? 0) - (right.grantedAtMs ?? 0);
+  })[0];
+}
+
+// Redeem outcome mapping, pinned to grok.com's observed grpc-status codes:
+// 0 = reset applied; 9 (FAILED_PRECONDITION-ish) = already redeemed when the
+// message says so, otherwise no credit; 3 (INVALID_ARGUMENT) naming token_id
+// means the token was unknown or spent. Everything else is a hard failure.
+export function mapGrokRedeemStatus(
+  grpcStatus: string,
+  grpcMessage: string | null,
+): GrokRedeemResult {
+  if (grpcStatus === "0") return { code: "reset" };
+  const message = (grpcMessage ?? "").toLowerCase();
+  if (grpcStatus === "9") {
+    return message.includes("redeem") && message.includes("already")
+      ? { code: "already_redeemed" }
+      : { code: "no_credit" };
+  }
+  if (grpcStatus === "3" && message.includes("token_id")) return { code: "no_credit" };
+  throw new ResetError(
+    "grpc",
+    grpcMessage
+      ? `Grok reset failed: ${grpcMessage}`
+      : `Grok reset failed (grpc-status ${grpcStatus})`,
+    undefined,
+    grpcStatus,
+  );
+}
+
+function resetHeaders(credential: GrokCredential): Record<string, string> {
+  return {
+    Authorization: `Bearer ${credential.token}`,
+    "X-XAI-Token-Auth": GROK_CLI_AUTH_HEADER,
+    "Content-Type": GRPC_WEB_CONTENT_TYPE,
+    "x-grpc-web": "1",
+  };
+}
+
+async function postGrokRpc(
+  url: string,
+  credential: GrokCredential,
+  payload: Uint8Array,
+  options: { signal?: AbortSignal; timeoutMs: number },
+): Promise<GrpcWebResponse> {
+  const timeout = AbortSignal.timeout(options.timeoutMs);
+  const signal = options.signal ? AbortSignal.any([options.signal, timeout]) : timeout;
+  let response: Response;
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      headers: resetHeaders(credential),
+      body: encodeGrpcWebRequest(payload),
+      signal,
+    });
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new ResetError("transport", `Grok reset request failed: ${message}`);
+  }
+  if (!response.ok) {
+    if (response.status === 401 || response.status === 403) {
+      throw new ResetError(
+        "auth",
+        `xAI reset request was unauthorized (HTTP ${response.status}). Run /login xai and try again.`,
+        response.status,
+      );
+    }
+    throw new ResetError(
+      "http",
+      `Grok reset request failed (HTTP ${response.status}).`,
+      response.status,
+    );
+  }
+  const raw = new Uint8Array(await response.arrayBuffer());
+  if (raw.byteLength > MAX_RESPONSE_BYTES) {
+    throw new ResetError("oversize", "Grok reset response exceeded the size limit.");
+  }
+  return decodeGrpcWebResponse(
+    raw,
+    response.headers.get("grpc-status"),
+    response.headers.get("grpc-message"),
+  );
+}
+
+export async function fetchGrokResetCredits(
+  credential: GrokCredential,
+  options: { signal?: AbortSignal } = {},
+): Promise<GrokResetCredits> {
+  if (!credential.token) {
+    throw new ResetError("auth", "xAI OAuth credentials are required. Run /login xai first.");
+  }
+  const response = await postGrokRpc(GROK_REMAINING_RESETS_URL, credential, new Uint8Array(), {
+    signal: options.signal,
+    timeoutMs: LIST_TIMEOUT_MS,
+  });
+  if (response.grpcStatus === "16") {
+    throw new ResetError(
+      "auth",
+      response.grpcMessage
+        ? `xAI reset-token inventory rejected the credential: ${response.grpcMessage}`
+        : "xAI reset-token inventory rejected the credential. Run /login xai and try again.",
+      undefined,
+      response.grpcStatus,
+    );
+  }
+  // Accounts without the SuperGrok reset entitlement answer with a non-OK grpc
+  // status instead of an empty inventory; treat that as zero so /grok-resets
+  // still opens. Redeem re-validates server-side, so this can never over-count.
+  if (response.grpcStatus !== "0") return EMPTY_RESET_CREDITS;
+  return summarizeResetTokens(decodeRemainingResetTokens(response.payload));
+}
+
+export async function redeemGrokReset(
+  credential: GrokCredential,
+  tokenId: string | undefined,
+  options: { signal?: AbortSignal } = {},
+): Promise<GrokRedeemResult> {
+  if (!credential.token) {
+    throw new ResetError("auth", "xAI authentication is unavailable. Run /login xai first.");
+  }
+  let token = tokenId?.trim() ?? "";
+  if (!token) {
+    const credits = await fetchGrokResetCredits(credential, options);
+    token = selectGrokResetToken(credits.tokens)?.tokenId ?? "";
+  }
+  if (!token) return { code: "no_credit" };
+  const response = await postGrokRpc(
+    GROK_REDEEM_RESET_URL,
+    credential,
+    encodeRedeemResetRequest(token),
+    { signal: options.signal, timeoutMs: REDEEM_TIMEOUT_MS },
+  );
+  return mapGrokRedeemStatus(response.grpcStatus, response.grpcMessage);
+}
+
+export function decodeRedeemResetTokenId(payload: Uint8Array): string | null {
+  for (const field of decodeFields(payload)) {
+    if (field.field === 10 && field.wireType === 2) return textDecoder.decode(field.value);
+  }
+  return null;
+}
+
+export type GrokResetContext = GrokCredentialContext;
+
+export async function requestGrokResetCredits(
+  ctx: GrokResetContext,
+  signal?: AbortSignal,
+): Promise<GrokResetCredits | undefined> {
+  const credential = await resolveGrokCredential(ctx);
+  if (!credential) return undefined;
+  return fetchGrokResetCredits(credential, { signal });
+}
+
+export async function redeemGrokResetForSession(
+  ctx: GrokResetContext,
+  tokenId: string | undefined,
+  signal?: AbortSignal,
+): Promise<GrokRedeemResult> {
+  const credential = await resolveGrokCredential(ctx);
+  if (!credential) {
+    throw new ResetError("auth", "xAI authentication is unavailable. Run /login xai first.");
+  }
+  return redeemGrokReset(credential, tokenId, { signal });
+}
+
+function formatResetTimestamp(ms: number | null): string {
+  if (ms === null) return "unknown";
+  return new Date(ms).toLocaleString(undefined, {
+    month: "short",
+    day: "numeric",
+    hour: "numeric",
+    minute: "2-digit",
+  });
+}
+
+export function formatGrokResetChoice(token: GrokResetToken, index: number): string {
+  const expires = `expires ${formatResetTimestamp(token.expiresAtMs)}`;
+  return `${index + 1}. SuperGrok rate-limit reset (${maskIdentifier(token.tokenId)}) · ${expires}`;
+}
+
+export function formatGrokResetOutcome(result: GrokRedeemResult): {
+  message: string;
+  level: "info" | "warning";
+} {
+  switch (result.code) {
+    case "reset":
+      return {
+        message: "Banked reset redeemed — your SuperGrok usage limit was restored.",
+        level: "info",
+      };
+    case "no_credit":
+      return { message: "No banked Grok resets remain available.", level: "warning" };
+    case "already_redeemed":
+      return { message: "That banked reset was already redeemed.", level: "warning" };
+  }
+}
+
+export function buildGrokResetConfirmation(options: {
+  token?: GrokResetToken;
+  availableCount: number;
+  snapshot?: Pick<UsageSnapshot, "creditUsagePercent">;
+}): { title: string; message: string } {
+  const token = options.token;
+  const lines: string[] = ["SuperGrok rate-limit reset"];
+  lines.push(`Token: ${token ? maskIdentifier(token.tokenId) : "auto-selected"}`);
+  if (token?.grantedAtMs != null) lines.push(`Granted: ${formatResetTimestamp(token.grantedAtMs)}`);
+  lines.push(`Expires: ${formatResetTimestamp(token?.expiresAtMs ?? null)}`);
+  lines.push(`Available: ${options.availableCount}`);
+  if (options.snapshot?.creditUsagePercent != null) {
+    lines.push(`Current usage: weekly ${formatPercent(options.snapshot.creditUsagePercent)} used`);
+  }
+  lines.push("");
+  lines.push(
+    "This redeems one SuperGrok reset token, restores your weekly usage limit immediately, and cannot be undone.",
+  );
+  return { title: "Redeem banked Grok reset?", message: lines.join("\n") };
+}