grok-telegram-bot 2.3.1 → 2.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grok-telegram-bot",
-  "version": "2.3.1",
+  "version": "2.5.0",
   "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/src/app/accounts.ts

@@ -20,6 +20,23 @@ import type { AccountInfo } from "./usage.js";
 
 const log = createLogger("accounts");
 
+/** Real usage counters recorded by the bot from completed turns (not billing API). */
+export interface AccountUsage {
+  /** Completed (non-cancelled) turns on this account. */
+  turns: number;
+  /**
+   * Sum of per-turn credit figures Grok reported via `_grok.dev/metadata`.
+   * Only increments when the agent actually sends a credits value.
+   */
+  credits: number;
+  /** ISO timestamp of the last successful turn on this account. */
+  lastUsedAt?: string;
+  /** Credits reported on the most recent turn (if any). */
+  lastTurnCredits?: number;
+  /** Context-window % from the most recent turn that reported it. */
+  lastContextPct?: number;
+}
+
 /** Persisted, non-secret metadata about a saved account. */
 export interface StoredAccount {
   id: string;
@@ -32,6 +49,8 @@ export interface StoredAccount {
   startUrl?: string;
   accountType?: string;
   region?: string;
+  /** Live usage stats accumulated while this account was active. */
+  usage?: AccountUsage;
   /** Excluded from automatic rotation after an account-specific quota/billing failure. */
   warning?: {
     reason: string;
@@ -262,6 +281,53 @@ export class AccountManager {
     return updated;
   }
 
+  /**
+   * Record a completed turn against the active (or given) saved account.
+   * Credits are only added when Grok reported a figure for the turn; turns
+   * always increment so /accounts shows real activity even without credits.
+   */
+  recordTurnUsage(
+    stats: { credits?: number; contextPct?: number },
+    accountId?: string,
+  ): StoredAccount | undefined {
+    const id = accountId ?? this.activeAccountId() ?? this.markedActiveId();
+    if (!id) return undefined;
+    let updated: StoredAccount | undefined;
+    this.store.update((d) => {
+      const account = d.accounts.find((a) => a.id === id);
+      if (!account) return;
+      const prev = account.usage ?? { turns: 0, credits: 0 };
+      const credits =
+        typeof stats.credits === "number" && Number.isFinite(stats.credits) && stats.credits > 0
+          ? stats.credits
+          : undefined;
+      const next: AccountUsage = {
+        turns: (prev.turns || 0) + 1,
+        credits: (prev.credits || 0) + (credits ?? 0),
+        lastUsedAt: new Date().toISOString(),
+        lastTurnCredits: credits ?? prev.lastTurnCredits,
+        lastContextPct:
+          typeof stats.contextPct === "number" && Number.isFinite(stats.contextPct)
+            ? stats.contextPct
+            : prev.lastContextPct,
+      };
+      account.usage = next;
+      updated = account;
+    });
+    return updated;
+  }
+
+  /** Compact one-line usage summary for menus (empty when no stats yet). */
+  formatUsageLine(account: StoredAccount): string {
+    const u = account.usage;
+    if (!u || (u.turns <= 0 && u.credits <= 0 && !u.lastUsedAt)) return "";
+    const parts: string[] = [];
+    if (u.turns > 0) parts.push(`${u.turns} turn${u.turns === 1 ? "" : "s"}`);
+    if (u.credits > 0) parts.push(`${fmtUsageNumber(u.credits)} credits`);
+    if (u.lastUsedAt) parts.push(`last ${fmtRelative(u.lastUsedAt)}`);
+    return parts.join(" \u00B7 ");
+  }
+
   async forget(id: string): Promise<boolean> {
     const existed = !!this.get(id);
     await rm(this.snapshotPath(id), { force: true }).catch(() => {});
@@ -272,3 +338,21 @@ export class AccountManager {
     return existed;
   }
 }
+
+function fmtUsageNumber(n: number): string {
+  if (!Number.isFinite(n)) return String(n);
+  if (Number.isInteger(n)) return n.toLocaleString("en-US");
+  return n.toFixed(2);
+}
+
+/** Short relative time for usage lines ("2h ago", "just now"). */
+function fmtRelative(iso: string): string {
+  const t = Date.parse(iso);
+  if (!Number.isFinite(t)) return iso.slice(0, 10);
+  const sec = Math.max(0, Math.round((Date.now() - t) / 1000));
+  if (sec < 60) return "just now";
+  if (sec < 3600) return `${Math.floor(sec / 60)}m ago`;
+  if (sec < 86_400) return `${Math.floor(sec / 3600)}h ago`;
+  if (sec < 86_400 * 14) return `${Math.floor(sec / 86_400)}d ago`;
+  return new Date(t).toISOString().slice(0, 10);
+}

package/src/app/instance-lock.ts

@@ -88,6 +88,12 @@ export class InstanceLock {
     }
   }
 
+  /** Refresh lock metadata while we still hold it (lifetime heartbeat). */
+  touch(): void {
+    if (!this.held) return;
+    this.write();
+  }
+
   private write(): void {
     const data: LockData = { pid: process.pid, startedAt: Date.now(), supervised: this.supervised };
     try {

package/src/app/lifetime-flag.ts

@@ -0,0 +1,20 @@
+/**
+ * Cross-module intentional-exit flag so beforeExit keep-alive and the polling
+ * loop do not fight updater re-exec / fatal exits / SIGINT.
+ */
+let intentional = false;
+let reason = "";
+
+/** Mark that the process is exiting on purpose (do not keep-alive). */
+export function markIntentionalShutdown(why: string): void {
+  intentional = true;
+  reason = why;
+}
+
+export function isIntentionalShutdown(): boolean {
+  return intentional;
+}
+
+export function intentionalShutdownReason(): string {
+  return reason;
+}

package/src/app/settings-store.ts

@@ -1,6 +1,8 @@
 /**
- * Per-chat settings persistence (project, agent, model, reasoning, pinned
- * status message id). Backed by a single JSON file so state survives restarts.
+ * Per-chat / per-forum-topic settings persistence (project, agent, model,
+ * reasoning, pinned status message id, controlled sessions).
+ * Keys: `"12345"` for private chats, `"12345:t7"` for forum topic thread 7.
+ * Backed by a single JSON file so state survives restarts.
  */
 import { join } from "node:path";
 import { JsonStore } from "./json-store.js";
@@ -15,24 +17,61 @@ export class SettingsStore {
     this.store = new JsonStore<SettingsMap>(join(dataDir, "settings.json"), {});
   }
 
+  /** Settings for a private chat (or legacy callers). */
   get(chatId: number): ChatSettings {
-    const existing = this.store.get()[String(chatId)];
+    return this.getKey(String(chatId));
+  }
+
+  /** Settings by storage key (`chatId` or `chatId:t{threadId}`). */
+  getKey(key: string): ChatSettings {
+    const existing = this.store.get()[key];
     return existing ?? defaultSettings();
   }
 
   update(chatId: number, patch: Partial<ChatSettings>): ChatSettings {
-    const key = String(chatId);
-    const next = { ...this.get(chatId), ...patch };
+    return this.updateKey(String(chatId), patch);
+  }
+
+  updateKey(key: string, patch: Partial<ChatSettings>): ChatSettings {
+    const next = { ...this.getKey(key), ...patch };
     this.store.update((m) => {
       m[key] = next;
     });
     return next;
   }
 
+  /**
+   * All settings entries whose projectPath matches (for bidirectional
+   * bot ↔ forum session discovery).
+   */
+  entriesForProject(projectPath: string): Array<{ key: string; settings: ChatSettings }> {
+    const want = normPath(projectPath);
+    const out: Array<{ key: string; settings: ChatSettings }> = [];
+    for (const [key, s] of Object.entries(this.store.get())) {
+      if (s.projectPath && normPath(s.projectPath) === want) {
+        out.push({ key, settings: s });
+      }
+      for (const cs of s.controlledSessions ?? []) {
+        if (cs.projectPath && normPath(cs.projectPath) === want) {
+          out.push({ key, settings: s });
+          break;
+        }
+      }
+    }
+    return out;
+  }
+
   /** All chat ids that have interacted (for broadcast announcements). */
   chatIds(): number[] {
-    return Object.keys(this.store.get())
-      .map(Number)
-      .filter((n) => Number.isFinite(n));
+    const ids = new Set<number>();
+    for (const key of Object.keys(this.store.get())) {
+      const n = Number(key.split(":")[0]);
+      if (Number.isFinite(n)) ids.add(n);
+    }
+    return [...ids];
   }
 }
+
+function normPath(p: string): string {
+  return p.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+}

package/src/app/types.ts

@@ -13,6 +13,11 @@ export interface ChatSettings {
   agent?: string;
   model?: string;
   reasoning: ReasoningEffort;
+  /**
+   * Preferred saved Grok account login id for this chat/topic (optional).
+   * Applied when starting turns if different from the process-active account.
+   */
+  preferredAccountId?: string;
   /** Telegram message id of the pinned status panel, if any. */
   statusMessageId?: number;
   /** Sessions this chat controls (for multi-session switching). */
@@ -57,14 +62,37 @@ export interface PromptInput {
   resourceLinks?: PromptResourceLink[];
   /** Telegram message id of the prompt, so the reply threads to it. */
   replyTo?: number;
+  /**
+   * Short id for the bot-owned prompt anchor (`#prompt_<id>`). All AI messages
+   * for this turn carry the same tag so the user can search related replies.
+   */
+  promptId?: string;
   /**
    * Content of the message the user was replying to (or the portion they
    * quoted). Injected as context so the agent sees what the user is responding
    * to. See {@link ../bot/reply-context.ts}.
    */
   quotedText?: string;
+  /**
+   * System/meta turns (self-recheck, auto-approved suggestion batches) must not
+   * trigger another self-recheck — only real user prompts do (once each).
+   */
+  skipSelfRecheck?: boolean;
 }
 
-export function textPrompt(text: string, replyTo?: number, quotedText?: string): PromptInput {
-  return { text, images: [], resourceLinks: [], replyTo, quotedText };
+export function textPrompt(
+  text: string,
+  replyTo?: number,
+  quotedText?: string,
+  opts?: { skipSelfRecheck?: boolean; promptId?: string },
+): PromptInput {
+  return {
+    text,
+    images: [],
+    resourceLinks: [],
+    replyTo,
+    promptId: opts?.promptId,
+    quotedText,
+    skipSelfRecheck: opts?.skipSelfRecheck,
+  };
 }

package/src/app/updater.ts

@@ -17,6 +17,7 @@ import { get } from "node:https";
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { JsonStore } from "./json-store.js";
+import { markIntentionalShutdown } from "./lifetime-flag.js";
 import { createLogger } from "../logger.js";
 import { extractChangelog, isNewer, isSafeVersion } from "./version.js";
 
@@ -145,21 +146,52 @@ export class Updater {
   }
 
   private async restart(): Promise<void> {
+    // Signal main/beforeExit that this exit is intentional (avoid keep-alive race).
+    markIntentionalShutdown("updater-reexec");
     await this.opts.shutdown().catch(() => {});
     // Under systemd/launchd, a clean exit triggers a managed relaunch (no double
     // instance). On Windows / foreground there is no supervisor, so re-exec.
     if (process.env.GROK_TG_SUPERVISED === "1") {
       log.info("exiting for supervisor to relaunch the updated bot");
+      try {
+        process.stderr.write("[updater] supervised exit for relaunch\n");
+      } catch {
+        /* ignore */
+      }
       setTimeout(() => process.exit(0), 250);
       return;
     }
     log.info("re-executing the updated bot");
-    const child = spawn(
-      process.execPath,
-      ["--import", "tsx", join(this.opts.projectRoot, "src", "index.ts"), "--instance", this.opts.instanceDir],
-      { detached: true, stdio: "ignore", cwd: this.opts.projectRoot, env: process.env },
-    );
-    child.unref();
+    try {
+      // TTY: inherit stdio so `npm start` doesn't look like a silent death.
+      // Non-TTY (service): detach and ignore stdio.
+      const inherit = Boolean(process.stdout.isTTY);
+      const child = spawn(
+        process.execPath,
+        ["--import", "tsx", join(this.opts.projectRoot, "src", "index.ts"), "--instance", this.opts.instanceDir],
+        {
+          detached: !inherit,
+          stdio: inherit ? "inherit" : "ignore",
+          cwd: this.opts.projectRoot,
+          env: process.env,
+        },
+      );
+      if (!inherit) child.unref();
+      if (!child.pid) {
+        log.error("re-exec spawn produced no pid — staying alive");
+        return;
+      }
+      log.info(`re-exec child pid ${child.pid} (stdio=${inherit ? "inherit" : "ignore"})`);
+      try {
+        process.stderr.write(`[updater] re-exec child pid ${child.pid}; parent exiting\n`);
+      } catch {
+        /* ignore */
+      }
+    } catch (e) {
+      // Never exit if replacement failed — silent death is worse than stale code.
+      log.error(`re-exec failed: ${(e as Error).message} — staying alive`);
+      return;
+    }
     setTimeout(() => process.exit(0), 500);
   }
 

package/src/app/usage.ts

@@ -1,10 +1,27 @@
 /**
- * Account info for Grok Build. Grok signs in with your xAI account
- * (`grok login`), so /usage surfaces the signed-in identity (from the token in
- * ~/.grok/auth.json) plus the live per-session context usage the ACP agent
- * reports.
+ * Account + Grok CLI billing usage.
+ *
+ * Identity comes from ~/.grok/auth.json. Live Grok Build quota is fetched from
+ * the same CLI chat proxy OmniRoute-style clients use:
+ *   GET https://cli-chat-proxy.grok.com/v1/billing
+ * with the OIDC token from `grok login` (Bearer).
+ *
+ * Session-level context/credits still come from ACP `_grok.dev/metadata`.
  */
-import { hasLogin, identityFromAuth, loginLabel } from "./grok-credentials.js";
+import { createLogger } from "../logger.js";
+import {
+  currentAuthEntry,
+  currentToken,
+  hasLogin,
+  identityFromAuth,
+  loginLabel,
+} from "./grok-credentials.js";
+
+const log = createLogger("usage");
+
+const BILLING_URL = "https://cli-chat-proxy.grok.com/v1/billing";
+/** Cache live billing for a short window so /usage + /accounts don't spam the API. */
+const BILLING_TTL_MS = 30_000;
 
 export interface AccountInfo {
   /** Signed-in identity (email when the token carries one, else a label). */
@@ -14,25 +31,205 @@ export interface AccountInfo {
   region?: string;
   /** Stable identifier for matching saved accounts. */
   startUrl?: string;
+  /** JWT tier claim when present (Grok CLI subscription tier). */
+  tier?: string | number;
+  teamId?: string;
+}
+
+/** Live Grok CLI monthly quota from cli-chat-proxy. */
+export interface GrokCliBilling {
+  /** Included monthly allowance (raw units from the API). */
+  monthlyLimit: number;
+  /** Used so far this billing period. */
+  used: number;
+  /** Remaining = max(0, limit - used). */
+  remaining: number;
+  /** 0–100 percent of monthly limit consumed. */
+  usedPct: number;
+  onDemandCap: number;
+  billingPeriodStart?: string;
+  billingPeriodEnd?: string;
+  /** Prior cycles when the API returns them. */
+  history?: Array<{ year: number; month: number; totalUsed: number }>;
+  fetchedAt: string;
+}
+
+interface BillingCache {
+  at: number;
+  data?: GrokCliBilling;
+  error?: string;
 }
 
 export class UsageService {
+  private billingCache: BillingCache | undefined;
+
   // Kept for signature compatibility; Grok state lives in ~/.grok/auth.json.
   constructor(private readonly grokCliPath: string) {}
 
   async account(): Promise<AccountInfo | undefined> {
     if (!hasLogin()) {
-      // XAI_API_KEY with no browser login still counts as usable.
       if (process.env.XAI_API_KEY?.trim()) return { email: "XAI_API_KEY", accountType: "api key" };
       return undefined;
     }
     const id = identityFromAuth();
     const label = loginLabel();
-    return { email: id.email || label, accountType: undefined, startUrl: label };
+    const entry = currentAuthEntry();
+    const tok = currentToken();
+    let tier: string | number | undefined;
+    let teamId = typeof entry?.team_id === "string" ? entry.team_id : undefined;
+    if (tok) {
+      const claims = decodeJwt(tok);
+      if (claims?.tier !== undefined) tier = claims.tier as string | number;
+      if (!teamId && typeof claims?.team_id === "string") teamId = claims.team_id;
+    }
+    return {
+      email: id.email || label,
+      accountType: tier !== undefined ? `tier ${tier}` : undefined,
+      startUrl: label,
+      tier,
+      teamId,
+    };
   }
 
   /** Whether Grok has a usable sign-in (browser token or XAI_API_KEY). */
   async isLoggedIn(): Promise<boolean> {
     return hasLogin();
   }
+
+  /**
+   * Live Grok Build monthly quota for the active CLI login.
+   * Same endpoint OmniRoute uses for grok-cli remaining % dashboards.
+   */
+  async cliBilling(force = false): Promise<{ billing?: GrokCliBilling; error?: string }> {
+    const now = Date.now();
+    if (
+      !force &&
+      this.billingCache &&
+      now - this.billingCache.at < BILLING_TTL_MS
+    ) {
+      return { billing: this.billingCache.data, error: this.billingCache.error };
+    }
+
+    const token = currentToken();
+    if (!token) {
+      if (process.env.XAI_API_KEY?.trim()) {
+        return { error: "XAI_API_KEY mode — CLI monthly quota is only available after `grok login`" };
+      }
+      return { error: "Not signed in (no grok login token)" };
+    }
+
+    try {
+      const res = await fetch(BILLING_URL, {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${token}`,
+          Accept: "application/json",
+        },
+        signal: AbortSignal.timeout(12_000),
+      });
+      if (!res.ok) {
+        const err = `billing HTTP ${res.status}`;
+        log.warn(err);
+        this.billingCache = { at: now, error: err };
+        return { error: err };
+      }
+      const json = (await res.json()) as BillingWire;
+      const billing = parseBilling(json);
+      this.billingCache = { at: now, data: billing };
+      return { billing };
+    } catch (e) {
+      const err = (e as Error).message || "billing fetch failed";
+      log.warn("cli billing:", err);
+      this.billingCache = { at: now, error: err };
+      return { error: err };
+    }
+  }
+}
+
+interface BillingWire {
+  config?: {
+    monthlyLimit?: { val?: number };
+    used?: { val?: number };
+    onDemandCap?: { val?: number };
+    billingPeriodStart?: string;
+    billingPeriodEnd?: string;
+    history?: Array<{
+      billingCycle?: { year?: number; month?: number };
+      totalUsed?: { val?: number };
+      includedUsed?: { val?: number };
+      onDemandUsed?: { val?: number };
+    }>;
+  };
+}
+
+function parseBilling(json: BillingWire): GrokCliBilling {
+  const c = json.config ?? {};
+  const monthlyLimit = num(c.monthlyLimit?.val);
+  const used = num(c.used?.val);
+  const remaining = Math.max(0, monthlyLimit - used);
+  const usedPct = monthlyLimit > 0 ? Math.min(100, Math.round((used / monthlyLimit) * 1000) / 10) : 0;
+  const history = (c.history ?? [])
+    .map((h) => ({
+      year: h.billingCycle?.year ?? 0,
+      month: h.billingCycle?.month ?? 0,
+      totalUsed: num(h.totalUsed?.val ?? h.includedUsed?.val),
+    }))
+    .filter((h) => h.year > 0);
+  return {
+    monthlyLimit,
+    used,
+    remaining,
+    usedPct,
+    onDemandCap: num(c.onDemandCap?.val),
+    billingPeriodStart: c.billingPeriodStart,
+    billingPeriodEnd: c.billingPeriodEnd,
+    history: history.length ? history : undefined,
+    fetchedAt: new Date().toISOString(),
+  };
+}
+
+function num(v: unknown): number {
+  return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+
+function decodeJwt(jwt: string): Record<string, unknown> | undefined {
+  const parts = jwt.split(".");
+  if (parts.length < 2) return undefined;
+  try {
+    return JSON.parse(Buffer.from(parts[1]!, "base64url").toString("utf-8")) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Format billing for Telegram plain-text UIs. */
+export function formatCliBillingLines(b: GrokCliBilling): string[] {
+  const lines = [
+    "\u{1F4B3} Grok CLI monthly quota (cli-chat-proxy)",
+    `  Used: ${fmt(b.used)} / ${fmt(b.monthlyLimit)} (${b.usedPct}%)`,
+    `  Remaining: ${fmt(b.remaining)}`,
+  ];
+  if (b.billingPeriodStart || b.billingPeriodEnd) {
+    lines.push(
+      `  Period: ${fmtDate(b.billingPeriodStart)} \u2192 ${fmtDate(b.billingPeriodEnd)}`,
+    );
+  }
+  if (b.onDemandCap > 0) lines.push(`  On-demand cap: ${fmt(b.onDemandCap)}`);
+  if (b.history?.length) {
+    const prev = b.history
+      .slice(0, 3)
+      .map((h) => `${h.year}-${String(h.month).padStart(2, "0")}: ${fmt(h.totalUsed)}`)
+      .join(" \u00B7 ");
+    lines.push(`  History: ${prev}`);
+  }
+  return lines;
+}
+
+function fmt(n: number): string {
+  return n.toLocaleString("en-US");
+}
+
+function fmtDate(iso?: string): string {
+  if (!iso) return "\u2014";
+  return iso.slice(0, 10);
 }

package/src/bot/account-rotator.ts

@@ -52,6 +52,8 @@ export interface AccountRotator {
   withRotationLock<T>(observed: RotationState, run: (changed: boolean) => Promise<T>): Promise<T>;
   /** Wait for an in-progress rotation probe before re-binding a stale session. */
   waitForIdle(): Promise<void>;
+  /** Record a completed turn's usage against the active saved account. */
+  recordTurnUsage(stats: { credits?: number; contextPct?: number }): void;
 }
 
 export class AccountRotatorImpl implements AccountRotator {
@@ -67,6 +69,14 @@ export class AccountRotatorImpl implements AccountRotator {
     return this.accounts.autoRotateEnabled();
   }
 
+  recordTurnUsage(stats: { credits?: number; contextPct?: number }): void {
+    try {
+      this.accounts.recordTurnUsage(stats);
+    } catch (e) {
+      log.debug("recordTurnUsage failed:", (e as Error).message);
+    }
+  }
+
   state(): RotationState {
     const activeId = this.accounts.activeAccountId();
     return {