grok-telegram-bot 2.2.2 → 2.2.3

package/CHANGELOG.md

@@ -9,6 +9,21 @@ The latest section is published verbatim as the GitHub Release notes by
 
 ## [Unreleased]
 
+## [2.2.3] - 2026-07-13
+
+### Fixed
+
+- **💳 Instant account rotate on 402 balance exhausted.** Grok Build
+  `Payment Required` / `usage balance exhausted` errors (usually wrapped as ACP
+  Internal error `[-32603]`) are no longer treated as transient. Same-account
+  backoff retries are skipped. With **auto-rotate ON**, the bot immediately:
+  stops the Grok CLI → swaps `~/.grok/auth.json` → restarts the CLI with
+  headless `cached_token` auth → opens a fresh session → retries the same
+  prompt. If that account fails, it switches to the next saved account (one
+  pass). If all accounts fail (or auto-rotate is OFF), the turn stops with a
+  clear error. Telegram shows
+  `Account switched to … because of: …` plus a CLI-restart notice.
+
 ## [2.2.2] - 2026-07-12
 
 Patch release that hardens multi-account identity and documents the full **2.2.x**

package/README.md

@@ -40,7 +40,7 @@ re-architected for the Grok Build CLI and extended into a full multi-session cli
 | 📈 **Task progress bar** | The agent appends a `{progress: N%}` marker; the bot hides it and shows a **green 0–100% loading bar** on the live message, in the status panel, and on session cards (`SHOW_PROGRESS`). |
 | 🔐 **Sign in from chat** | `/reauth` signs you in without a terminal — **🔑 Sign in** runs headless `grok login --device-auth` (link/code streams to your chat, no host browser), or **📥 Import** an existing on-host login; the agent restarts under the new identity. |
 | 👥 **Multiple accounts** | `/accounts` saves several Grok **sign-ins** (custom names) and switches between them in a tap — **stops the agent → replaces `~/.grok/auth.json` → restarts headlessly** (never opens a browser). |
-| 🔁 **Auto-rotate on give-up** | When a turn exhausts its retries, optionally cycle through your other saved accounts once and retry on each — the first that works wins (toggle in `/accounts`). Same headless auth.json swap. |
+| 🔁 **Auto-rotate on give-up** | When a turn exhausts its retries (or hits **402 balance exhausted** with no same-account retry), optionally cycle through your other saved accounts once: stop CLI → swap `auth.json` → restart + re-auth → retry. First that works wins (toggle in `/accounts`). |
 | ✅ **Auto-approve tools** | By default, ACP permission prompts are auto-approved for the **session** (`AUTO_APPROVE_PERMISSIONS`). Turn both that and `GROK_TRUST_ALL_TOOLS` off for interactive Approve/Deny — those prompts are **pinned** until you act. |
 | 🪙 **Credits & usage** | The `✅ Done` line and `/usage` show credits used (when Grok reports them), turns this session, and account info. |
 | ⌨️ **Typing indicator** | Stays on for the whole turn, even through long tool chains. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grok-telegram-bot",
-  "version": "2.2.2",
+  "version": "2.2.3",
   "description": "Control the official Grok Build CLI from Telegram over the Agent Client Protocol (ACP). Sign in with your xAI account, switch projects, resume sessions, stream responses with diffs, queue follow-ups, manage multiple sign-ins, and run 24/7 as a cross-platform background service.",
   "type": "module",
   "main": "src/index.ts",

package/scripts/_tmp-release.mjs

@@ -0,0 +1,16 @@
+import { execSync } from "node:child_process";
+
+function run(cmd) {
+  console.log(`$ ${cmd}`);
+  execSync(cmd, { stdio: "inherit" });
+}
+
+// Annotated release tag (triggers GitHub Release workflow on push).
+try {
+  run('git tag -a v2.2.3 -m "v2.2.3 — instant account rotate on 402 balance exhausted"');
+} catch {
+  console.log("tag v2.2.3 already exists locally — continuing");
+}
+run("git push origin v2.2.3");
+run("npm publish --access public");
+console.log("done");

package/src/bot/account-rotator.ts

@@ -1,6 +1,7 @@
 /**
- * Auto-rotate-on-give-up. When a turn exhausts its retries (and auto-fork can't
- * recover it), the runtime can cycle through the OTHER saved Grok accounts,
+ * Auto-rotate-on-give-up. When a turn exhausts its retries (or fails immediately
+ * with a permanent billing error like HTTP 402 balance exhausted) and auto-fork
+ * can't recover it, the runtime can cycle through the OTHER saved Grok accounts,
  * retrying the same prompt on each — useful when the active account is
  * throttled, out of quota, or its backend keeps returning "dispatch failure".
  *
@@ -12,8 +13,11 @@
  * a rotation restarts the shared agent and affects every chat — intended, since
  * the whole point is to move everyone onto a working login.
  *
- * CRITICAL: switch = stop agent → replace ~/.grok/auth.json → start agent with
- * headless `cached_token` auth. Never opens a browser / never runs `grok login`.
+ * CRITICAL: every activate() MUST fully restart the CLI so the new auth applies:
+ *   1. stop agent (`stopAndWait`) — process must exit so it cannot rewrite auth,
+ *   2. replace ~/.grok/auth.json with the saved snapshot,
+ *   3. start agent + `authenticate({ methodId: "cached_token" })` headlessly.
+ * Never opens a browser / never runs `grok login`.
  */
 import type { GrokClient } from "../grok/client.js";
 import type { AccountManager } from "../app/accounts.js";
@@ -52,10 +56,11 @@ export class AccountRotatorImpl implements AccountRotator {
   }
 
   /**
-   * Pure file-based account swap:
-   *   1. Stop the shared agent (so it cannot rewrite auth.json),
+   * Pure file-based account swap with a full CLI restart so the new token is
+   * loaded (agent is process-local with `--no-leader`):
+   *   1. Stop the shared agent and wait for exit (so it cannot rewrite auth.json),
    *   2. Copy the saved snapshot over ~/.grok/auth.json,
-   *   3. Start the agent and authenticate with `cached_token` (headless).
+   *   3. Start a fresh agent process and authenticate with `cached_token`.
    * Never launches a browser.
    */
   async activate(id: string): Promise<void> {
@@ -63,12 +68,15 @@ export class AccountRotatorImpl implements AccountRotator {
     await this.accounts.captureCurrent().catch((e) => {
       log.warn("pre-rotate capture failed (continuing):", (e as Error).message);
     });
-    log.info(`rotating: stopping agent before auth.json swap (${id})`);
+    log.info(`rotating: stopping Grok CLI before auth.json swap (${id})`);
     await this.acp.stopAndWait();
     try {
       const meta = await this.accounts.switchTo(id);
-      log.info(`rotating: auth.json now ${meta.label}; starting agent`);
+      log.info(`rotating: auth.json now ${meta.label}; starting Grok CLI + re-auth`);
+      // start() → connect() → initialize + authenticate(cached_token) against
+      // the freshly written auth.json. A live process would keep the old token.
       await this.acp.start();
+      log.info(`rotating: Grok CLI up on ${meta.label}`);
     } catch (e) {
       // Best-effort recover the agent so the bot stays usable even if the
       // target login was bad.

package/src/bot/handlers/accounts.ts

@@ -57,7 +57,9 @@ async function view(deps: BotDeps, note?: string): Promise<{ text: string; keybo
   lines.push(
     "",
     `\u{1F501} Auto-rotate on errors: ${rotate ? "ON" : "OFF"}`,
-    rotate ? "  \u2514 If a turn gives up, it cycles through the other accounts once." : "  \u2514 Turns stay on the active account.",
+    rotate
+      ? "  \u2514 On give-up / 402 balance exhausted: stop CLI, swap auth, restart, retry each account once."
+      : "  \u2514 Turns stay on the active account (402 balance exhausted stops immediately).",
   );
   if (note) lines.push("", note);
 

package/src/bot/prompt-retry.ts

@@ -68,3 +68,30 @@ export function formatErrorSummary(error: Error, elapsed: string, attempts: numb
   }
   return `\u274C Gave up after ${attempts} attempts over ${elapsed}.\nLast error: ${error.message}${tip}`;
 }
+
+/**
+ * Compact, human-facing reason for an account switch (Telegram status line).
+ * Prefers a short billing/quota phrase when present; otherwise truncates.
+ */
+export function shortSwitchReason(error: Error, max = 140): string {
+  const raw = error.message.replace(/\s+/g, " ").trim();
+  const known =
+    raw.match(/Grok Build usage balance exhausted/i)?.[0] ??
+    raw.match(/usage balance exhausted/i)?.[0] ??
+    raw.match(/balance exhausted/i)?.[0] ??
+    raw.match(/Payment Required/i)?.[0] ??
+    raw.match(/quota exceeded/i)?.[0] ??
+    raw.match(/out of (?:credits|quota|balance)/i)?.[0];
+  const text = known ?? raw;
+  return text.length > max ? `${text.slice(0, max - 1)}\u2026` : text;
+}
+
+/** Shown when auto-rotate swaps login mid-turn and retries on the new account. */
+export function formatAccountSwitchNotice(label: string, error: Error): string {
+  return [
+    `\u{1F504} Account switched to ${label}`,
+    `because of: ${shortSwitchReason(error)}`,
+    "",
+    "Restarting Grok CLI with the new login and retrying\u2026",
+  ].join("\n");
+}

package/src/bot/session-runtime.ts

@@ -6,7 +6,13 @@
  */
 import { basename } from "node:path";
 import { type Api, InlineKeyboard } from "grammy";
-import { type GrokClient, isContextExhaustedError, isTransientError, type SessionMetadata } from "../grok/client.js";
+import {
+  type GrokClient,
+  isAccountExhaustedError,
+  isContextExhaustedError,
+  isTransientError,
+  type SessionMetadata,
+} from "../grok/client.js";
 import type { AccountRotator } from "./account-rotator.js";
 import type { ContentBlock, PromptResult, SessionUpdate } from "../grok/types.js";
 import type { AppConfig } from "../config.js";
@@ -27,7 +33,14 @@ import type { PendingStage, SubagentInfo } from "../grok/types.js";
 import { ResponseStreamer } from "../stream/streamer.js";
 import { extractImagePaths, sendImages } from "./image-return.js";
 import { buildContentBlocks, mergeInputs } from "./prompt-content.js";
-import { backoffSchedule, fmtSeconds, formatErrorSummary, formatRetryNotice, RETRY_BASE_MS } from "./prompt-retry.js";
+import {
+  backoffSchedule,
+  fmtSeconds,
+  formatAccountSwitchNotice,
+  formatErrorSummary,
+  formatRetryNotice,
+  RETRY_BASE_MS,
+} from "./prompt-retry.js";
 import { sendMarkdownDoc } from "./telegram-io.js";
 import { TypingIndicator } from "./typing.js";
 
@@ -661,13 +674,17 @@ export class SessionRuntime {
   }
 
   /**
-   * Auto-rotate-on-give-up. When a turn has failed (retries exhausted, auto-fork
-   * didn't recover it) and nothing was streamed, cycle through the OTHER saved
-   * accounts once — switching login + restarting the agent, then retrying the
-   * same prompt on a fresh session for each. The first account that succeeds
-   * wins and stays active; if every account fails we return a single combined
-   * error listing what each one reported. Bounded to ONE pass (no infinite
+   * Auto-rotate-on-give-up. When a turn has failed (retries exhausted / billing
+   * 402 with no same-account retry, auto-fork didn't recover) and nothing was
+   * streamed, cycle through the OTHER saved accounts once — each step:
+   *   stop Grok CLI → replace ~/.grok/auth.json → start CLI + headless auth →
+   *   open a fresh session → retry the same prompt.
+   * The first account that succeeds wins and stays active; if every account
+   * fails we stop with a combined error. Bounded to ONE pass (no infinite
    * loop). No-op unless the rotator is enabled and other accounts exist.
+   *
+   * Billing/quota failures (402 balance exhausted) skip backoff retries on
+   * each account and rotate instantly so the turn continues without a long wait.
    */
   private async maybeRotateAccount(
     input: PromptInput,
@@ -685,11 +702,13 @@ export class SessionRuntime {
 
     for (const t of targets) {
       if (this.cancelled) return last;
+      const failReason = last.error ?? final.error;
       if (this.foreground) {
-        await this.notify(`\u{1F501} Auto-rotating accounts \u2014 trying ${t.label}\u2026`, { replyTo: this.turnReplyTo });
+        await this.notify(formatAccountSwitchNotice(t.label, failReason), { replyTo: this.turnReplyTo });
       }
       try {
-        await rotator.activate(t.id); // switch login + restart the shared agent
+        // stop CLI → swap auth.json → start CLI + authenticate(cached_token)
+        await rotator.activate(t.id);
       } catch (e) {
         errors.push(`\u2022 ${t.label}: couldn't switch \u2014 ${(e as Error).message}`);
         continue;
@@ -709,17 +728,23 @@ export class SessionRuntime {
         priming: transcript ? buildPriming(transcript) : undefined,
         progress: this.cfg.showProgress ? PROGRESS_DIRECTIVE : undefined,
       });
-      log.info(`chat ${this.chatId} auto-rotating to account ${t.label}`);
+      log.info(
+        `chat ${this.chatId} auto-rotating to account ${t.label}` +
+          (isAccountExhaustedError(failReason) ? " (billing/quota exhausted on previous)" : ""),
+      );
+      // runPromptWithRetries already skips backoff for 402 / balance exhausted.
       last = await this.runPromptWithRetries(content);
       if (last.result && !this.cancelled) {
-        if (this.foreground) await this.notify(`\u2705 Recovered on ${t.label}.`, { replyTo: this.turnReplyTo });
+        if (this.foreground) {
+          await this.notify(`\u2705 Recovered on ${t.label}.`, { replyTo: this.turnReplyTo });
+        }
         return last;
       }
       if (this.cancelled || (this.streamer?.hasOutput ?? false)) return last;
       errors.push(`\u2022 ${t.label}: ${last.error?.message ?? "failed"}`);
     }
 
-    // One full cycle done and still failing — stop with a combined report.
+    // One full cycle done and still failing — stop with a combined report.
     const combined = new Error(`Tried ${targets.length + 1} account(s), all failed:\n${errors.join("\n")}`);
     return { error: combined, attempts: last.attempts };
   }
@@ -748,12 +773,15 @@ export class SessionRuntime {
         const error = err as Error;
         const canRecover = !this.cancelled && !(this.streamer?.hasOutput ?? false);
         // A context-exhausted session won't recover by retrying the same
-        // oversized prompt — skip the backoff and let auto-fork compact it now.
+        // oversized prompt — skip the backoff and let auto-fork compact it now.
         const forkInstead = canRecover && this.cfg.autoForkOnError && this.isContextRelatedFailure(error);
+        // Billing/quota 402 (balance exhausted) is permanent for this login —
+        // never backoff-retry; surface immediately so auto-rotate can switch.
         const willRetry =
           attempt <= delays.length &&
           canRecover &&
           !forkInstead &&
+          !isAccountExhaustedError(error) &&
           isTransientError(error);
         if (!willRetry) return { error, attempts: attempt };
         const waitMs = delays[attempt - 1]!;

package/src/grok/client.ts

@@ -46,6 +46,14 @@ const TRANSIENT_RE =
   /internal error|high volume|experiencing|overloaded|temporar|unavailable|rate.?limit|too many requests|try again|capacity|dispatch failure|response stream|connection (?:reset|closed|refused|error)|reset by peer|broken pipe|socket hang ?up|econnreset|econnrefused|enotfound|eai_again|etimedout|\b50[234]\b|\b429\b/i;
 const CONTEXT_EXHAUSTED_RE =
   /context (?:length|window|limit|size|overflow)|maximum context|input (?:is )?too long|prompt (?:is )?too long|too many (?:input )?tokens|token limit|exceeds? (?:the )?(?:maximum|context|token)|reduce the (?:length|size)|context.{0,24}exhaust/i;
+/**
+ * Permanent-for-this-login billing/quota failures (e.g. HTTP 402 "Grok Build
+ * usage balance exhausted"). These ride inside ACP Internal error [-32603] but
+ * must NOT be backoff-retried on the same account — only account rotation can
+ * recover.
+ */
+const ACCOUNT_EXHAUSTED_RE =
+  /\b402\b|payment required|balance exhausted|usage balance|out of (?:credits|quota|balance)|insufficient (?:credits|balance|quota)|quota exceeded|no (?:remaining )?credits/i;
 
 export class GrokError extends Error {
   constructor(
@@ -58,7 +66,35 @@ export class GrokError extends Error {
   }
 }
 
+/**
+ * True when the failure is a billing/quota exhaustion for the active Grok
+ * login (HTTP 402, "balance exhausted", etc.). Same-account retries cannot
+ * help; the turn should stop (or auto-rotate to another saved account).
+ */
+export function isAccountExhaustedError(err: Error): boolean {
+  if (ACCOUNT_EXHAUSTED_RE.test(err.message)) return true;
+  const data = (err as GrokError).data;
+  if (!data || typeof data !== "object") return false;
+  const d = data as Record<string, unknown>;
+  const status = d.http_status ?? d.status ?? d.statusCode;
+  if (status === 402 || status === "402") return true;
+  if (typeof d.message === "string" && ACCOUNT_EXHAUSTED_RE.test(d.message)) return true;
+  // Nested JSON sometimes lands as a stringified payload inside `data`.
+  for (const v of Object.values(d)) {
+    if (typeof v === "string" && ACCOUNT_EXHAUSTED_RE.test(v)) return true;
+    if (v && typeof v === "object") {
+      const nested = v as Record<string, unknown>;
+      const ns = nested.http_status ?? nested.status ?? nested.statusCode;
+      if (ns === 402 || ns === "402") return true;
+      if (typeof nested.message === "string" && ACCOUNT_EXHAUSTED_RE.test(nested.message)) return true;
+    }
+  }
+  return false;
+}
+
 export function isTransientError(err: Error): boolean {
+  // Balance/quota exhaustion is permanent for this login — never backoff-retry.
+  if (isAccountExhaustedError(err)) return false;
   const code = (err as GrokError).code;
   if (typeof code === "number" && TRANSIENT_CODES.has(code)) return true;
   return TRANSIENT_RE.test(err.message);

package/scripts/_push-main-release.mjs

@@ -1,99 +0,0 @@
-/**
- * Push current working-tree release files to main + create annotated tag.
- * (Local git push is restricted in this environment.)
- */
-import { readFileSync } from "node:fs";
-import { spawnSync } from "node:child_process";
-
-const owner = "artickc";
-const repo = "grok-telegram-bot";
-const branch = "main";
-const version = "2.2.2";
-const tag = `v${version}`;
-const message = "release: v2.2.2 — account identity, docs, 2.2.x multi-account batch";
-const tagMessage =
-  "v2.2.2 — multi-account headless rotation, session auto-approve, pinned permissions, account identity";
-
-const files = [
-  ".gitignore",
-  "CHANGELOG.md",
-  "README.md",
-  "package.json",
-  "src/app/accounts.ts",
-  "src/app/grok-credentials.ts",
-  "src/bot/handlers/accounts.ts",
-  "test/credentials.test.ts",
-];
-
-// eslint-disable-next-line no-control-regex
-const ANSI_RE = /\x1b\[[0-9;?]*[ -/]*[@-~]/g;
-
-function ghApi(method, path, body) {
-  const args = ["api", "-X", method, path];
-  const opts = {
-    encoding: "utf8",
-    maxBuffer: 50 * 1024 * 1024,
-    shell: false,
-    env: { ...process.env, NO_COLOR: "1", CLICOLOR: "0", FORCE_COLOR: "0", GH_FORCE_TTY: "0" },
-  };
-  if (body !== undefined) {
-    args.push("--input", "-");
-    opts.input = JSON.stringify(body);
-  }
-  const r = spawnSync("gh", args, opts);
-  if (r.status !== 0) {
-    throw new Error(`gh api ${method} ${path} failed (${r.status}): ${r.stderr || r.stdout}`);
-  }
-  const text = (r.stdout || "").replace(ANSI_RE, "").trim();
-  if (!text) return {};
-  return JSON.parse(text);
-}
-
-const ref = ghApi("GET", `repos/${owner}/${repo}/git/ref/heads/${branch}`);
-const baseSha = ref.object.sha;
-const baseCommit = ghApi("GET", `repos/${owner}/${repo}/git/commits/${baseSha}`);
-const baseTree = baseCommit.tree.sha;
-console.log("base", baseSha);
-
-const tree = [];
-for (const path of files) {
-  const content = readFileSync(path, "utf8");
-  const blob = ghApi("POST", `repos/${owner}/${repo}/git/blobs`, {
-    content: Buffer.from(content, "utf8").toString("base64"),
-    encoding: "base64",
-  });
-  tree.push({ path, mode: "100644", type: "blob", sha: blob.sha });
-  console.log("blob", path, blob.sha.slice(0, 8));
-}
-
-const newTree = ghApi("POST", `repos/${owner}/${repo}/git/trees`, {
-  base_tree: baseTree,
-  tree,
-});
-const commit = ghApi("POST", `repos/${owner}/${repo}/git/commits`, {
-  message,
-  tree: newTree.sha,
-  parents: [baseSha],
-});
-ghApi("PATCH", `repos/${owner}/${repo}/git/refs/heads/${branch}`, {
-  sha: commit.sha,
-  force: false,
-});
-console.log("main ->", commit.sha);
-
-const tagObj = ghApi("POST", `repos/${owner}/${repo}/git/tags`, {
-  tag,
-  message: tagMessage,
-  object: commit.sha,
-  type: "commit",
-  tagger: {
-    name: "artickc",
-    email: "artickc@users.noreply.github.com",
-    date: new Date().toISOString(),
-  },
-});
-ghApi("POST", `repos/${owner}/${repo}/git/refs`, {
-  ref: `refs/tags/${tag}`,
-  sha: tagObj.sha,
-});
-console.log("tag", tag, "->", commit.sha);