tokenmaxxing 1.59.0 → 1.60.0

package/DESIGN.md

@@ -115,7 +115,7 @@ The [profile](docs/content/docs/switching-profile.mdx) records observed cache re
 
 **Removed (1.37.0, issue #79):** the shared live credential and everything that served it: the swap-time harvest, park, and install, tokenmaxxing's own OAuth refresh grant and its interlock with Claude Code's refresh lock, the `~/.claude.json` `oauthAccount` rewrite, the 45-second post-swap cooldown, the pool-wide depleted-wait record, the parked-credential slots (`creds/`, `tokenmaxxing-cred-*`), the ambient `CLAUDE_CONFIG_DIR` refusal, and manual `switch` for the Claude pool.
 
-**Shipped since (0.13.0):** Codex as a second pool with its own state (`codex-accounts.json`, per-account `codex-stores/`, own flock). Since 1.35.0 the engine is one: a generic account record (`id`, `label`, `email`, `tier`, `windows`), one picker, one decision, and one set of account commands run against a `Provider` (`src/lib/provider.ts`); `src/lib/claude.ts` and `src/lib/codex.ts` hold only what differs per product (credential store, identity, usage source, presence, login and install flows), and the provider's `seats` capability (`shared` for Claude, `live` for Codex) is how the engine knows whether present accounts stay candidates and whether a move needs the caller's respawn. Codex differences that shaped it: restart IS the switch (a running codex refuses another account's credential), one store per pooled account with `CODEX_HOME` set per session (everything but `auth.json` symlinked to the shared home, so resume works across stores), usage is a free direct GET with epoch resets and a duration-classified window set (the weekly window is primary on current plans), the refresh token rotates with reuse punished (persisted into the account's own store the instant it returns, never refreshed for an account running in another session), and the codex Stop hook drives the auto-switch through a codex supervisor shim that respawns `codex resume <session-id>` under the target's store (hooks must be trusted once via `/hooks`). Since 1.44.0 two status-only pools, grok and opencode-go, share the engine's account commands and state layout with `statusOnly: true` and no supervisor, hooks, or usage source ([Status-only pools](docs/content/docs/status-only-pools.mdx)).
+**Shipped since (0.13.0):** Codex as a second pool with its own state (`codex-accounts.json`, per-account `codex-stores/`, own flock). Since 1.35.0 the engine is one: a generic account record (`id`, `label`, `email`, `tier`, `windows`), one picker, one decision, and one set of account commands run against a `Provider` (`src/lib/provider.ts`); `src/lib/claude.ts` and `src/lib/codex.ts` hold only what differs per product (credential store, identity, usage source, presence, login and install flows), and the provider's `seats` capability (`shared` for Claude, `live` for Codex) is how the engine knows whether present accounts stay candidates and whether a move needs the caller's respawn. Codex differences that shaped it: restart IS the switch (a running codex refuses another account's credential), one store per pooled account with `CODEX_HOME` set per session (everything but `auth.json` symlinked to the shared home, so resume works across stores), usage is a free direct GET with epoch resets and a duration-classified window set (the weekly window is primary on current plans), the refresh token rotates with reuse punished (persisted into the account's own store the instant it returns, never refreshed for an account running in another session), and the codex Stop hook drives the auto-switch through a codex supervisor shim that respawns `codex resume <session-id>` under the target's store (hooks must be trusted once via `/hooks`). Since 1.44.0 two status-only pools, grok and opencode-go, share the engine's account commands and state layout with `statusOnly: true` and no supervisor or hooks ([Status-only pools](docs/content/docs/status-only-pools.mdx)). grok `status` reads the weekly subscription credit window from the credits billing GET; opencode-go has no usage source.
 
 **Shipped since (1.29.0):** a Cursor Cloud relay. A cloud VM has no keychain, no pool state, and no supervisor, so the path uses what it does have (environment variables, a shell, repo files) and a different credential primitive, one-year inference-only setup tokens, minted once per pooled account by `tokenmaxxing setup-token` on the owner's machine and carried to the VM as one user-scoped Runtime Secret (`TOKENMAXXING_TOKENS`). `tokenmaxxing cursor init` writes `.cursor/environment.json` and a `claude` project subagent (`.cursor/agents/claude.md`) that forwards each task to `tokenmaxxing cloud run`, which spawns `claude -p --dangerously-skip-permissions --output-format json` under `CLAUDE_CODE_OAUTH_TOKEN` and pins the thread to that token (the API caches by exact prefix, so a rotation busts one thread, not all). A setup token carries no usage signal, so rotation is reactive. A run whose transcript gained a non-transient rate-limit row during that run (the structured row the StopFailure hook reads) walls the label until the reset the row names (five hours without one) and resumes the same session on the next token; the result's `api_error_status` alone never walls, so a transient 429 or an older row from a previous token does not cascade across the pool. The local switching engine never reads a setup token; `/usage` prints no percentages under one. Details in [Cursor Cloud](docs/content/docs/cursor-cloud.mdx).
 

package/README.md

@@ -142,7 +142,7 @@ A Cursor Cloud Agent can hand substantial work to Claude Code running on your ow
 - **One shared identity file.** `~/.claude.json` holds one `oauthAccount` that Claude Code rewrites after whichever session refreshed last, so `/status` can show another session's email; the statusline's `◆` marks the account a session actually uses.
 - **Keychain (macOS).** The first keychain access for a new store happens inside the interactive `init`, `add`, or `auth` run, where a prompt can be answered, not inside a headless hook.
 - **Plaintext credentials (Linux).** Claude Code itself stores Linux credentials as a 0600 plaintext file; a store follows the same model.
-- **Status-only pools carry no usage.** grok and opencode-go accounts render with no bars and never move.
+- **Status-only pools do not switch.** grok `status` shows the weekly subscription credit window; opencode-go accounts still render with no bars. Neither pool moves.
 
 ## How it's built
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tokenmaxxing",
-  "version": "1.59.0",
+  "version": "1.60.0",
   "description": "Automatic Claude Code account switching: pool multiple accounts, start each session on its own account, and resume a session on a fresher account when quota fills.",
   "type": "module",
   "license": "MIT",

package/src/lib/grok.ts

@@ -2,10 +2,13 @@ import { mkdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { z } from "zod";
 import { writeFileAtomic } from "./atomic.ts";
+import { fetchGrokUsage, GrokUsageReadError } from "./grokusage.ts";
+import { errorMessage } from "./log.ts";
 import { grokAuthJsonFor, grokPaths, grokPool, grokSeatFromEnv, grokStoreDirFor } from "./paths.ts";
-import type { Provider } from "./provider.ts";
+import type { Provider, SampleReport } from "./provider.ts";
 import { loadAccounts, type Harvest } from "./state.ts";
 import { statusOnlyProvider, type AuthEntry } from "./statusonly.ts";
+import type { Account } from "./types.ts";
 import { c } from "../cli/render.ts";
 
 const GrokAuthEntrySchema = z.looseObject({
@@ -13,11 +16,14 @@ const GrokAuthEntrySchema = z.looseObject({
   principal_id: z.string().optional(),
   email: z.string().nullish(),
   first_name: z.string().nullish(),
+  key: z.string().optional(),
   refresh_token: z.string().optional(),
   expires_at: z.string().nullish(),
 });
 type GrokAuthEntry = z.infer<typeof GrokAuthEntrySchema>;
 
+type GrokCred = { id: string; token: string; expiresAt: number | null };
+
 function harvestOf(id: string, key: string, entry: GrokAuthEntry): Harvest {
   return {
     id,
@@ -31,7 +37,7 @@ function harvestOf(id: string, key: string, entry: GrokAuthEntry): Harvest {
   };
 }
 
-function readAuth(path: string): AuthEntry[] {
+function readMap(path: string): [string, GrokAuthEntry][] {
   let raw: unknown;
   try {
     raw = JSON.parse(readFileSync(path, "utf8"));
@@ -40,18 +46,87 @@ function readAuth(path: string): AuthEntry[] {
   }
   const map = z.record(z.string(), z.unknown()).safeParse(raw);
   if (!map.success) return [];
-  const out: AuthEntry[] = [];
+  const out: [string, GrokAuthEntry][] = [];
   for (const [key, value] of Object.entries(map.data)) {
     const parsed = GrokAuthEntrySchema.safeParse(value);
     if (!parsed.success) continue;
-    const entry = parsed.data;
+    out.push([key, parsed.data]);
+  }
+  return out;
+}
+
+function readAuth(path: string): AuthEntry[] {
+  const out: AuthEntry[] = [];
+  for (const [key, entry] of readMap(path)) {
     const id = entry.user_id ?? entry.principal_id ?? key;
     out.push({ id, usable: (entry.refresh_token ?? "") !== "", harvest: id === "" ? null : harvestOf(id, key, entry) });
   }
   return out;
 }
 
-export const grok: Provider = statusOnlyProvider({
+function credsIn(path: string): GrokCred[] {
+  const out: GrokCred[] = [];
+  for (const [key, entry] of readMap(path)) {
+    const id = entry.user_id ?? entry.principal_id ?? key;
+    const token = entry.key ?? "";
+    if (id === "" || token === "") continue;
+    const expiresAt = entry.expires_at != null ? Date.parse(entry.expires_at) : null;
+    out.push({ id, token, expiresAt: expiresAt != null && Number.isFinite(expiresAt) ? expiresAt : null });
+  }
+  return out;
+}
+
+function liveCred(accountId: string): GrokCred | null {
+  return credsIn(join(grokPaths.home, "auth.json")).find((c) => c.id === accountId) ?? null;
+}
+
+function bearerFor(accountId: string, now: number): { token: string; from: "store" | "live" } | null {
+  const store = credsIn(grokAuthJsonFor(accountId)).find((c) => c.id === accountId) ?? null;
+  const live = liveCred(accountId);
+  if (store != null && (store.expiresAt == null || store.expiresAt > now + 60_000)) return { token: store.token, from: "store" };
+  if (live != null) return { token: live.token, from: "live" };
+  if (store != null) return { token: store.token, from: "store" };
+  return null;
+}
+
+async function readGrokUsage(account: Account, now: number): Promise<{ ok: true; at: number } | { ok: false; reason: string }> {
+  const first = bearerFor(account.id, now);
+  if (first == null) return { ok: false, reason: "no usable credential in this account's store - run `tokenmaxxing auth --grok`" };
+  try {
+    const usage = await fetchGrokUsage({ token: first.token, at: now });
+    account.windows = usage.windows;
+    account.lastUsageAt = usage.at;
+    return { ok: true, at: usage.at };
+  } catch (e) {
+    if (e instanceof GrokUsageReadError && e.status === 401 && first.from === "store") {
+      const live = liveCred(account.id);
+      if (live != null && live.token !== first.token) {
+        try {
+          const usage = await fetchGrokUsage({ token: live.token, at: now });
+          account.windows = usage.windows;
+          account.lastUsageAt = usage.at;
+          return { ok: true, at: usage.at };
+        } catch (retry) {
+          return { ok: false, reason: retry instanceof GrokUsageReadError ? retry.message : errorMessage(retry) };
+        }
+      }
+    }
+    return { ok: false, reason: e instanceof GrokUsageReadError ? e.message : errorMessage(e) };
+  }
+}
+
+async function samplePool(accounts: Account[], _liveId: string | null, now: number): Promise<Map<string, SampleReport>> {
+  const reports = new Map<string, SampleReport>();
+  await Promise.all(
+    accounts.map(async (account) => {
+      const outcome = await readGrokUsage(account, now);
+      reports.set(account.id, outcome.ok ? { ok: true, source: "probe" } : { ok: false, reason: outcome.reason });
+    }),
+  );
+  return reports;
+}
+
+const base = statusOnlyProvider({
   name: "grok",
   flag: " --grok",
   pool: grokPool,
@@ -72,3 +147,8 @@ export const grok: Provider = statusOnlyProvider({
   installNotice: "grok pool is status-only: no supervisor or hooks installed. Use `tokenmaxxing status` to view pooled grok accounts.",
   loginStep: () => `Sign in in the browser session that opens (or run ${c.bold("grok login --device-auth")} on headless hosts first).`,
 });
+
+export const grok: Provider = {
+  ...base,
+  samplePool,
+};

package/src/lib/grokusage.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+import { http, safeErrorDetail } from "./http.ts";
+import { errorMessage } from "./log.ts";
+import { env } from "./paths.ts";
+import { JsonTextSchema, type Window } from "./types.ts";
+
+export class GrokUsageReadError extends Error {
+  status: number | null;
+  constructor(detail: string, status: number | null = null) {
+    super(`grok usage read failed: ${detail}`);
+    this.name = "GrokUsageReadError";
+    this.status = status;
+  }
+}
+
+const InstantSchema = z.iso.datetime({ offset: true });
+
+const CreditsPeriodSchema = z.looseObject({
+  start: InstantSchema,
+  end: InstantSchema,
+});
+
+const CreditsConfigSchema = z.looseObject({
+  currentPeriod: CreditsPeriodSchema,
+  creditUsagePercent: z.number(),
+});
+
+const CreditsBillingSchema = z.looseObject({
+  config: CreditsConfigSchema,
+});
+
+export type GrokUsage = { windows: Window[]; at: number };
+
+function usageUrl(): string {
+  return env("TOKENMAXXING_GROK_USAGE_URL", "https://cli-chat-proxy.grok.com/v1/billing?format=credits");
+}
+
+export async function fetchGrokUsage(input: { token: string; at: number }): Promise<GrokUsage> {
+  const { token, at } = input;
+  let res: Response;
+  try {
+    res = await http.get(usageUrl(), {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/json",
+        "User-Agent": "grok",
+      },
+    });
+  } catch (e) {
+    throw new GrokUsageReadError(`endpoint unreachable: ${errorMessage(e)}`);
+  }
+  const text = await res.text();
+  if (!res.ok) {
+    throw new GrokUsageReadError(`HTTP ${res.status}: ${safeErrorDetail({ text })}`, res.status);
+  }
+  const parsed = CreditsBillingSchema.safeParse(JsonTextSchema.safeParse(text).data);
+  if (!parsed.success) {
+    throw new GrokUsageReadError("endpoint returned an unexpected body shape (withheld)");
+  }
+  const period = parsed.data.config.currentPeriod;
+  const start = Date.parse(period.start);
+  const end = Date.parse(period.end);
+  return {
+    at,
+    windows: [
+      {
+        name: null,
+        usedPercentage: parsed.data.config.creditUsagePercent,
+        resetsAt: Number.isFinite(end) ? end : null,
+        windowSeconds: Number.isFinite(start) && Number.isFinite(end) && end > start ? Math.round((end - start) / 1000) : null,
+        sampledAt: at,
+      },
+    ],
+  };
+}