grok-telegram-bot 2.3.1 → 2.4.0

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/types.ts

@@ -63,8 +63,25 @@ export interface PromptInput {
    * 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 },
+): PromptInput {
+  return {
+    text,
+    images: [],
+    resourceLinks: [],
+    replyTo,
+    quotedText,
+    skipSelfRecheck: opts?.skipSelfRecheck,
+  };
 }

package/src/app/updater.ts

@@ -154,12 +154,23 @@ export class Updater {
       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 {
+      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();
+      if (!child.pid) {
+        log.error("re-exec spawn produced no pid — staying alive");
+        return;
+      }
+      log.info(`re-exec child pid ${child.pid}`);
+    } 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 {

package/src/bot/bot.ts

@@ -11,6 +11,7 @@ import { SettingsStore } from "../app/settings-store.js";
 import { SttService } from "../app/stt.js";
 import { Updater } from "../app/updater.js";
 import { UsageService } from "../app/usage.js";
+import { textPrompt } from "../app/types.js";
 import type { AppConfig } from "../config.js";
 import { INSTANCE_DIR } from "../config.js";
 import { createLogger } from "../logger.js";
@@ -26,6 +27,7 @@ import { type BotDeps, MenuCache } from "./deps.js";
 import { registerControl } from "./handlers/control.js";
 import { registerDocuments } from "./handlers/document.js";
 import { registerHistory } from "./handlers/history.js";
+import { registerImportSession } from "./handlers/import-session.js";
 import { registerKill } from "./handlers/kill.js";
 import { registerMcp } from "./handlers/mcp.js";
 import { registerMenu } from "./handlers/menu.js";
@@ -171,11 +173,45 @@ export async function createBot(cfg: AppConfig, acp: GrokClient): Promise<BotBun
     if (sid) await switchAndShow(ctx, deps, sid);
   });
 
+  // Legacy complexity buttons (removed — agent decides; auto-plan if complex).
+  bot.callbackQuery(/^cplx:(simple|complex)$/, async (ctx) => {
+    await ctx.answerCallbackQuery({ text: "Complexity is automatic now" });
+    await ctx
+      .editMessageText("\u2705 Complexity is decided by the agent automatically \u2014 just send your task.", {
+        reply_markup: { inline_keyboard: [] },
+      })
+      .catch(() => {});
+  });
+
+  // Post-turn suggestion buttons on the Done message.
+  bot.callbackQuery(/^sug:(\d+):(\d+)$/, async (ctx) => {
+    const batchId = Number(ctx.match![1]);
+    const index = Number(ctx.match![2]);
+    const rt = deps.registry.get(ctx.chat!.id);
+    const text = rt.takeSuggestion(batchId, index);
+    if (!text) {
+      await ctx.answerCallbackQuery({ text: "Suggestion expired", show_alert: true });
+      return;
+    }
+    await ctx.answerCallbackQuery({ text: "Sending\u2026" });
+    // Dim the keyboard so double-taps don't re-fire.
+    await ctx.editMessageReplyMarkup({ reply_markup: { inline_keyboard: [] } }).catch(() => {});
+    try {
+      const outcome = await rt.submit(textPrompt(text, ctx.callbackQuery.message?.message_id));
+      if (outcome === "queued") {
+        await ctx.reply(`\u{1F4E5} Queued suggestion (position ${rt.queueLength}).`).catch(() => {});
+      }
+    } catch (e) {
+      await ctx.reply(`\u274C Couldn't run suggestion: ${(e as Error).message}`).catch(() => {});
+    }
+  });
+
   registerMenu(bot, deps); // persistent-keyboard buttons (hears)
   registerWizardInput(bot, deps); // wizard text input (before commands)
   registerControl(bot, deps);
   registerProjects(bot, deps);
   registerSessions(bot, deps);
+  registerImportSession(bot, deps);
   registerSessionKill(bot, deps);
   registerRunning(bot, deps);
   registerHistory(bot, deps);

package/src/bot/chat-controller.ts

@@ -23,6 +23,11 @@ export interface RunningSession {
   unread: number;
   /** Latest task-completion % (0–100) for this session, if known. */
   progress?: number;
+  /**
+   * Card comment: live step while working, chat summary when idle
+   * ("what is happening / what was done").
+   */
+  comment?: string;
 }
 
 export interface SwitchResult {
@@ -76,6 +81,7 @@ export class ChatController {
       foreground: rt.isForeground,
       unread: this.unreadCount(rt),
       progress: rt.taskProgress,
+      comment: rt.cardComment,
     }));
   }
 
@@ -142,6 +148,28 @@ export class ChatController {
     return rt;
   }
 
+  /**
+   * Import a foreign session (Kiro / OpenCode / Claude / Codex) as a new
+   * controlled Grok session in the same project, primed with the full transcript.
+   * The new session becomes the foreground /running entry.
+   */
+  async addImport(
+    cwd: string,
+    projectName: string | undefined,
+    priming: string,
+  ): Promise<SessionRuntime> {
+    this.ensureRestored();
+    const prevFg = this.fg;
+    const rt = this.create({ cwd, projectName });
+    this.runtimes.push(rt);
+    this.fg = rt;
+    void this.background(prevFg);
+    await rt.startImportedSession(cwd, projectName, priming);
+    this.markSeen(rt);
+    this.persist();
+    return rt;
+  }
+
   /**
    * Connect to a session with resume-or-fork semantics (used by /sessions),
    * adding it as a controlled session and bringing it to the foreground.
@@ -251,6 +279,13 @@ export class ChatController {
     return this.runtimes.find((r) => r.sessionId === sessionId)?.taskProgress;
   }
 
+  /** Live step / chat summary for a controlled session id. */
+  commentFor(sessionId?: string): string | undefined {
+    if (!sessionId) return undefined;
+    this.ensureRestored();
+    return this.runtimes.find((r) => r.sessionId === sessionId)?.cardComment;
+  }
+
   findBySession(sessionId: string): boolean {
     return this.runtimes.some((r) => r.sessionId === sessionId);
   }

package/src/bot/commands.ts

@@ -8,6 +8,7 @@ export const COMMANDS: { command: string; description: string }[] = [
   { command: "sessions", description: "List/resume sessions (active first) \u00b7 /sessions <q>" },
   { command: "active", description: "Sessions running now on the PC" },
   { command: "running", description: "Sessions this chat controls \u2014 switch between them" },
+  { command: "import", description: "Import a Kiro/OpenCode/Claude/Codex /running session" },
   { command: "killall", description: "Kill all active sessions on the PC" },
   { command: "mcp", description: "Inspect & toggle MCP servers \u00b7 health-check" },
   { command: "tasks", description: "Manage scheduled tasks" },
@@ -41,6 +42,7 @@ export const HELP_TEXT = [
   "/projects \u2014 choose which folder Grok works in",
   "/sessions \u2014 resume one of your recent Grok sessions",
   "/active \u2014 attach to a session currently running on the PC",
+  "/import \u2014 import a /running session from Kiro, OpenCode, Claude, or Codex",
   "/history \u2014 show the latest messages of the current session",
   "/new \u2014 start a brand-new session in the current project",
   "/btw <text> \u2014 run it now if idle, otherwise right after the current task",

package/src/bot/complexity-gate.ts

@@ -0,0 +1,69 @@
+/**
+ * First-prompt complexity steering (fully automatic — never asks the user).
+ *
+ * On the first user message of a fresh session the bot prepends a directive so
+ * Grok itself decides Simple vs Complex:
+ *   • Simple  — implement directly.
+ *   • Complex — enter plan mode, investigate carefully, write a plan,
+ *               exit_plan_mode (auto-approved by this bridge), implement,
+ *               then re-review the result.
+ *
+ * No Telegram buttons, no user choice, no waiting.
+ */
+import type { PromptInput } from "../app/types.js";
+
+/**
+ * Agent-only directive. Must stay free of real `{progress: N%}` digit markers
+ * (history cleaner strips those). Uses the letter N only if mentioning format.
+ */
+export const AUTO_COMPLEXITY_DIRECTIVE = [
+  "COMPLEXITY (decide yourself — never ask the user):",
+  "Silently classify this task as Simple or Complex. Do NOT ask the user which it is. Do NOT show Simple/Complex buttons or questions.",
+  "",
+  "If SIMPLE (clear path, small change, obvious fix, short answer):",
+  "  implement or answer directly with normal care.",
+  "",
+  "If COMPLEX (ambiguity, multi-file architecture, high rework risk, unclear approach):",
+  "  1. Enter plan mode (enter_plan_mode) when available.",
+  "  2. Investigate carefully: explore the codebase, map patterns, edge cases, and risks before coding.",
+  "  3. Write a solid plan to the plan file; prefer investigation over speed.",
+  "  4. Call exit_plan_mode when ready. This Telegram bridge auto-approves plan exit",
+  "     (there is no TUI plan popup). After exit_plan_mode succeeds, implement fully.",
+  "     Do NOT wait for the user to \"approve a popup\" — just call exit_plan_mode and proceed.",
+  "  5. After implementation, re-review your work (verify correctness, edge cases, and that the plan was followed) before finishing.",
+  "",
+  "User task:",
+].join("\n");
+
+/** Optional mode ids Grok may advertise for plan mode (best-effort only). */
+export const PLAN_MODE_CANDIDATES = ["plan", "planning", "architect", "design"] as const;
+
+/**
+ * Prepend the auto-complexity directive so the agent decides Simple vs Complex
+ * without any user interaction.
+ */
+export function wrapAutoComplexityPrompt(input: PromptInput): PromptInput {
+  const body = input.text.trim() || "(see attached media / files)";
+  // Avoid double-wrapping if a retry/queue path already applied it.
+  if (body.startsWith("COMPLEXITY (decide yourself")) return input;
+  return {
+    ...input,
+    text: `${AUTO_COMPLEXITY_DIRECTIVE}\n${body}`,
+  };
+}
+
+/** Pick a plan-mode id from the agent's advertised modes, if any. */
+export function pickPlanModeId(
+  modes: Array<{ id: string; name: string }>,
+  hasMode: (id: string) => boolean,
+): string | undefined {
+  for (const id of PLAN_MODE_CANDIDATES) {
+    if (hasMode(id)) return id;
+  }
+  for (const m of modes) {
+    if (/plan|architect|design/i.test(m.id) || /plan|architect|design/i.test(m.name)) {
+      return m.id;
+    }
+  }
+  return undefined;
+}