grok-telegram-bot 2.3.0 → 2.4.0

package/src/bot/suggestions.ts

@@ -0,0 +1,429 @@
+/**
+ * Post-turn follow-up suggestions + gated self-recheck helpers.
+ *
+ * Self-recheck (once per real user turn, when enabled):
+ *  1. Hard-skip if no files were modified.
+ *  2. Quiet meta ask: AI refuses (simple / pure build / nothing to re-verify)
+ *     or writes a focused recheck prompt.
+ *  3. That prompt is queued as the one-shot SELF-RECHECK turn.
+ *  4. Then Done + suggestions.
+ *
+ * After Done, the bot quietly asks for 1–3 short next steps as JSON with a
+ * "need" score (0–100). Suggestions appear as inline buttons; those at/above
+ * SUGGESTIONS_AUTO_APPROVE_PCT are merged into **one** auto-queued prompt
+ * (`1) …\n2) …`) so they run as a single turn.
+ */
+import { InlineKeyboard } from "grammy";
+
+/** Max suggestions shown / accepted. */
+export const SUGGESTION_MAX = 3;
+/** Button label budget (Telegram ~64 chars). */
+const BTN_MAX = 56;
+
+/** Marker for the automatic post-turn self-recheck prompt (once per user turn). */
+export const SELF_RECHECK_MARKER = "SELF-RECHECK (automatic quality pass";
+
+/**
+ * Default self-recheck body (user can override via SELF_RECHECK_PROMPT).
+ * Placeholders: {{USER}} = user's request, {{DONE}} = first-turn summary.
+ */
+export const DEFAULT_SELF_RECHECK_PROMPT = [
+  `${SELF_RECHECK_MARKER} — once only).`,
+  "Do a rigorous self-review of the work just completed for the user request below.",
+  "",
+  "You are both a bugs/logic finder AND a completeness checker for related follow-ups.",
+  "Look for:",
+  "1) Bugs, regressions, incomplete steps, wrong assumptions, missing verification, edge cases.",
+  "2) Logical gaps the user would still need — e.g. if they asked for password reset and you",
+  "   shipped the happy path only, also cover brute-force protection, rate limits, token expiry,",
+  "   email enumeration, CSRF, audit logging, and similar security/ops follow-through that a",
+  "   solid implementation of THAT feature should include (not a random new product idea).",
+  "",
+  "Rules:",
+  "- Prefer fixing real problems with tools when needed; do not invent unrelated features.",
+  "- If something is unfinished relative to the user request (or a tightly related follow-up",
+  "  that leaves the feature incomplete/insecure), finish or fix it now.",
+  "- If everything checks out, briefly confirm what you verified (no long essay).",
+  "- Do NOT ask the user questions. Do NOT call enter_plan_mode unless truly necessary.",
+  "- End with an honest {progress: N%} marker for this recheck pass.",
+  "",
+  "USER'S REQUEST:",
+  "{{USER}}",
+  "",
+  "WHAT WAS JUST DONE (summary):",
+  "{{DONE}}",
+].join("\n");
+
+export interface Suggestion {
+  /** Plain follow-up the user would type / the bot will submit. */
+  text: string;
+  /** How needed/critical relative to the last user prompt (0–100). */
+  need: number;
+}
+
+/**
+ * Quiet meta-prompt after a successful turn. Must produce JSON only.
+ * Percentage rules enforce honesty: unrelated ideas cannot score above 60.
+ */
+export function buildSuggestionsPrompt(userText: string, assistantSnippet: string): string {
+  const user = clamp(userText.replace(/\s+/g, " ").trim(), 500) || "(empty)";
+  const did = clamp(assistantSnippet.replace(/\s+/g, " ").trim(), 600) || "(no assistant text)";
+  return [
+    "FOLLOW-UP SUGGESTIONS (meta only). Do NOT use tools. Do NOT write code. Do NOT continue the task.",
+    "Based ONLY on the user's last request and what was just done, propose 1 to 3 short next steps.",
+    "",
+    "USER'S LAST PROMPT:",
+    user,
+    "",
+    "WHAT WAS JUST DONE (summary):",
+    did,
+    "",
+    "For each suggestion set need = integer 0–100 = how needed/critical it is for completing or properly finishing THAT user prompt:",
+    "- High need (70–100): tightly related, critical next step for the same request (fix a gap, verify, finish unfinished part).",
+    "- Medium (40–69): related polish or natural continuation of the same task.",
+    "- Low (1–39): optional or weakly related.",
+    "- HARD RULE: if a suggestion is NOT clearly related to the user's last prompt, need MUST be ≤ 60 (never higher).",
+    "- Do not invent unrelated new features just to fill slots; prefer fewer high-quality items.",
+    "- Prefer the highest need for the single most critical related follow-up.",
+    "",
+    "Reply with ONLY a JSON array (no markdown fences, no keys other than text/need, no commentary):",
+    '[{"text":"short imperative follow-up the user would send","need":85}]',
+    "Constraints: 1–3 items; text ≤ 120 chars; plain language; no quotes wrapping the whole array.",
+  ].join("\n");
+}
+
+/** Parse model output into 0–3 validated suggestions. */
+export function parseSuggestions(raw: string): Suggestion[] {
+  if (!raw?.trim()) return [];
+  let t = raw.trim();
+  // Strip accidental code fences / progress markers.
+  t = t.replace(/\{[\s]*progress[\s]*:[\s]*\d{1,3}\s*%?[\s]*\}/gi, "").trim();
+  const fence = /^```(?:json)?\s*([\s\S]*?)```$/i.exec(t);
+  if (fence) t = fence[1]!.trim();
+  // Extract first JSON array if prose sneaks in.
+  const arrMatch = /\[[\s\S]*\]/.exec(t);
+  if (arrMatch) t = arrMatch[0]!;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(t);
+  } catch {
+    // Try line-wise objects.
+    const objs = [...t.matchAll(/\{[^{}]*"text"[^{}]*\}/g)].map((m) => {
+      try {
+        return JSON.parse(m[0]!) as unknown;
+      } catch {
+        return undefined;
+      }
+    });
+    parsed = objs.filter(Boolean);
+  }
+
+  const list = Array.isArray(parsed) ? parsed : [];
+  const out: Suggestion[] = [];
+  for (const item of list) {
+    if (!item || typeof item !== "object") continue;
+    const rec = item as Record<string, unknown>;
+    const text = String(rec.text ?? rec.suggestion ?? rec.prompt ?? "").replace(/\s+/g, " ").trim();
+    if (!text || text.length < 2) continue;
+    let need = Number(rec.need ?? rec.pct ?? rec.percent ?? rec.score ?? 0);
+    if (!Number.isFinite(need)) need = 0;
+    need = Math.max(0, Math.min(100, Math.round(need)));
+    out.push({ text: text.slice(0, 120), need });
+    if (out.length >= SUGGESTION_MAX) break;
+  }
+  // Highest need first for auto-approve + button order.
+  out.sort((a, b) => b.need - a.need);
+  return out;
+}
+
+/** Inline keyboard for Done: one row per suggestion + optional extra rows. */
+export function suggestionsKeyboard(
+  batchId: number,
+  suggestions: Suggestion[],
+  extra?: InlineKeyboard,
+): InlineKeyboard {
+  const kb = new InlineKeyboard();
+  suggestions.forEach((s, i) => {
+    const label = clamp(`${s.need}% · ${s.text}`, BTN_MAX);
+    kb.text(label, `sug:${batchId}:${i}`).row();
+  });
+  if (extra) {
+    // Append extra keyboard rows (e.g. Switch session).
+    const rows = (extra as unknown as { inline_keyboard?: Array<Array<{ text: string; callback_data: string }>> })
+      .inline_keyboard;
+    if (rows) {
+      for (const row of rows) {
+        for (let i = 0; i < row.length; i++) {
+          const b = row[i]!;
+          if (i === row.length - 1) kb.text(b.text, b.callback_data).row();
+          else kb.text(b.text, b.callback_data);
+        }
+      }
+    }
+  }
+  return kb;
+}
+
+/** Suggestions at/above the auto-approve threshold (need >= pct). */
+export function autoApproveSuggestions(suggestions: Suggestion[], thresholdPct: number): Suggestion[] {
+  if (thresholdPct <= 0) return [];
+  const thr = Math.max(0, Math.min(100, Math.round(thresholdPct)));
+  return suggestions.filter((s) => s.need >= thr);
+}
+
+/**
+ * Merge auto-approved suggestions into a single multi-step prompt so they run
+ * as one agent turn: `1) …\n2) …\n3) …` (already sorted highest need first).
+ */
+export function formatBatchedSuggestionsPrompt(suggestions: Suggestion[]): string {
+  if (suggestions.length === 0) return "";
+  if (suggestions.length === 1) return suggestions[0]!.text;
+  return suggestions.map((s, i) => `${i + 1}) ${s.text}`).join("\n");
+}
+
+/** Detect the quiet suggestions meta-prompt (history strip / title guard). */
+export function isSuggestionsMetaPrompt(text: string): boolean {
+  return /^FOLLOW-UP SUGGESTIONS \(meta only\)/i.test(text.trim());
+}
+
+/** Marker for the quiet "should we recheck?" meta-prompt. */
+export const SELF_RECHECK_DECISION_MARKER = "SELF-RECHECK DECISION (meta only)";
+
+/** Detect the quiet self-recheck decision meta-prompt. */
+export function isSelfRecheckDecisionPrompt(text: string): boolean {
+  return text.trim().startsWith(SELF_RECHECK_DECISION_MARKER);
+}
+
+/** Detect the automatic self-recheck pass (not a normal user message). */
+export function isSelfRecheckPrompt(text: string): boolean {
+  return text.trim().startsWith(SELF_RECHECK_MARKER);
+}
+
+/** Outcome of the quiet recheck-decision turn. */
+export type SelfRecheckDecision =
+  | { needed: false; reason?: string }
+  | { needed: true; prompt: string };
+
+/**
+ * Quiet meta-prompt: AI either refuses recheck (simple / no value) or writes
+ * the focused recheck instructions that will be submitted as the next turn.
+ */
+export function buildSelfRecheckDecisionPrompt(
+  userText: string,
+  assistantSnippet: string,
+  filesSummary: string,
+): string {
+  const user = clamp(userText.replace(/\s+/g, " ").trim(), 700) || "(empty)";
+  const did = clamp(assistantSnippet.replace(/\s+/g, " ").trim(), 900) || "(no assistant text)";
+  const files = clamp(filesSummary.replace(/\s+/g, " ").trim(), 400) || "(none)";
+  return [
+    `${SELF_RECHECK_DECISION_MARKER}. Do NOT use tools. Do NOT write code. Do NOT continue the task.`,
+    "Decide whether a second automatic quality pass is worth running for the work just completed.",
+    "",
+    "Set needed=false (skip recheck) when ANY of these apply:",
+    "- Simple task: Q&A, explanation, status, one-liner, or trivial change.",
+    "- Pure build / install / run / package with no non-trivial logic to re-audit.",
+    "- Work is clearly complete and low-risk; a re-verify would add little value.",
+    "- No plausible bugs, incomplete steps, or tightly related security/ops gaps.",
+    "",
+    "Set needed=true when:",
+    "- Non-trivial code/config changed and edge cases, regressions, or incomplete",
+    "  follow-through are plausible (auth, multi-file logic, concurrency, data paths).",
+    "- A focused second pass with tools could catch real bugs or finish related gaps.",
+    "",
+    "If needed=true, write a focused recheck prompt: imperative instructions for a one-shot",
+    "second pass that may use tools to fix REAL issues. Do not invent unrelated features.",
+    "If needed=false, give a short reason.",
+    "",
+    "USER'S REQUEST:",
+    user,
+    "",
+    "WHAT WAS JUST DONE (summary):",
+    did,
+    "",
+    "FILES MODIFIED THIS TURN:",
+    files,
+    "",
+    "Reply with ONLY one JSON object (no markdown fences, no commentary):",
+    '{"needed":false,"reason":"short reason"}',
+    "or",
+    '{"needed":true,"prompt":"focused recheck / fix instructions for the agent"}',
+  ].join("\n");
+}
+
+/**
+ * Parse quiet recheck-decision JSON. Defaults to skip on empty/invalid output
+ * so a bad meta reply never blocks Done — except when the model clearly wrote a
+ * recheck body without wrapping JSON (treated as needed=true).
+ */
+export function parseSelfRecheckDecision(raw: string): SelfRecheckDecision {
+  if (!raw?.trim()) return { needed: false, reason: "empty decision" };
+  let t = raw.trim();
+  // Strip trailing progress markers only (avoid eating prompt text mid-JSON).
+  t = t.replace(/\n?\s*\{[\s]*progress[\s]*:[\s]*\d{1,3}\s*%?[\s]*\}\s*$/gi, "").trim();
+  t = t.replace(/\{[\s]*progress[\s]*:[\s]*\d{1,3}\s*%?[\s]*\}/gi, "").trim();
+  const fence = /^```(?:json)?\s*([\s\S]*?)```$/i.exec(t);
+  if (fence) t = fence[1]!.trim();
+
+  // Soft refuse phrases (JSON or prose).
+  if (/\b(not needed|no recheck|skip recheck|unnecessary|not necessary|no need to recheck)\b/i.test(t)
+    && !/"needed"\s*:\s*true/i.test(t)) {
+    // Only force-skip when JSON does not explicitly set needed:true.
+    if (!/"needed"\s*:\s*true/i.test(raw) && !/"recheck"\s*:\s*true/i.test(raw)) {
+      const asJson = tryParseDecisionObject(t);
+      if (!asJson || asJson.needed !== true) {
+        return { needed: false, reason: "refused in prose" };
+      }
+    }
+  }
+
+  const asJson = tryParseDecisionObject(t);
+  if (asJson) return asJson;
+
+  // Plain imperative body (model forgot JSON) → treat as recheck prompt.
+  const prose = t.replace(/\s+/g, " ").trim();
+  if (prose.length >= 24 && !/^(ok|done|none|n\/a|skip)\b/i.test(prose)) {
+    return { needed: true, prompt: prose.slice(0, 4000) };
+  }
+  return { needed: false, reason: "unparseable decision" };
+}
+
+/** Best-effort extract/parse of a decision object from model text. */
+function tryParseDecisionObject(t: string): SelfRecheckDecision | undefined {
+  // Prefer balanced-ish first object; fall back to greedy match.
+  let candidate = t;
+  const objMatch = /\{[\s\S]*\}/.exec(t);
+  if (objMatch) candidate = objMatch[0]!;
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(candidate);
+  } catch {
+    // Try smaller object if trailing junk broke parse.
+    const m = /\{[^{}]*"needed"[^{}]*\}/i.exec(t)
+      || /\{[^{}]*"recheck"[^{}]*\}/i.exec(t)
+      || /\{[^{}]*"prompt"[^{}]*\}/i.exec(t);
+    if (!m) return undefined;
+    try {
+      parsed = JSON.parse(m[0]!);
+    } catch {
+      return undefined;
+    }
+  }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return undefined;
+  const rec = parsed as Record<string, unknown>;
+
+  // Do not treat suggestion-style "need" (0–100 score) as the needed flag.
+  // Only needed / recheck / required (boolean-ish) control the gate.
+  const neededRaw = rec.needed ?? rec.recheck ?? rec.required;
+  const prompt = String(rec.prompt ?? rec.text ?? rec.instructions ?? rec.recheck_prompt ?? "")
+    .replace(/\r\n/g, "\n")
+    .trim();
+
+  let needed: boolean | undefined;
+  if (typeof neededRaw === "boolean") needed = neededRaw;
+  else if (typeof neededRaw === "string") {
+    const s = neededRaw.trim().toLowerCase();
+    if (/^(1|true|yes|y|needed|recheck)$/i.test(s)) needed = true;
+    else if (/^(0|false|no|n|skip|none)$/i.test(s)) needed = false;
+  } else if (typeof neededRaw === "number") {
+    needed = neededRaw > 0;
+  }
+
+  // Explicit skip / refuse keys always win.
+  if (rec.skip === true || rec.refuse === true) needed = false;
+
+  // Prompt-only object: model wrote instructions without a needed flag → run.
+  if (needed === undefined && prompt.length >= 3) needed = true;
+  if (needed === undefined) needed = false;
+
+  if (!needed) {
+    const reason = String(rec.reason ?? rec.why ?? rec.message ?? "").replace(/\s+/g, " ").trim();
+    return { needed: false, reason: reason || undefined };
+  }
+
+  // needed=true but no usable prompt → empty body; caller fills default template.
+  if (!prompt || prompt.length < 3) {
+    return { needed: true, prompt: "" };
+  }
+  return { needed: true, prompt: prompt.slice(0, 4000) };
+}
+
+/**
+ * Build the one-shot self-recheck turn text from an optional env template.
+ * Placeholders: {{USER}}, {{DONE}} (also {USER}/{DONE} for convenience).
+ */
+export function buildSelfRecheckPrompt(
+  userText: string,
+  assistantSnippet: string,
+  template?: string,
+): string {
+  const user = clamp(userText.replace(/\s+/g, " ").trim(), 700) || "(empty)";
+  const did = clamp(assistantSnippet.replace(/\s+/g, " ").trim(), 900) || "(no assistant text)";
+  const tpl = (template?.trim() || DEFAULT_SELF_RECHECK_PROMPT).trim();
+  let out = tpl
+    .replace(/\{\{\s*USER\s*\}\}/gi, user)
+    .replace(/\{\{\s*DONE\s*\}\}/gi, did)
+    .replace(/\{USER\}/gi, user)
+    .replace(/\{DONE\}/gi, did);
+  // Ensure the marker is present so isSelfRecheckPrompt / one-shot guard work
+  // even if the user customized SELF_RECHECK_PROMPT and dropped it.
+  return ensureSelfRecheckMarker(out);
+}
+
+/**
+ * Turn an AI-written recheck body into a full one-shot turn (marker + context).
+ */
+export function composeSelfRecheckTurn(
+  agentPrompt: string,
+  userText: string,
+  assistantSnippet: string,
+): string {
+  const user = clamp(userText.replace(/\s+/g, " ").trim(), 700) || "(empty)";
+  const did = clamp(assistantSnippet.replace(/\s+/g, " ").trim(), 900) || "(no assistant text)";
+  const body =
+    agentPrompt.trim() ||
+    DEFAULT_SELF_RECHECK_PROMPT
+      .replace(/\{\{\s*USER\s*\}\}/gi, user)
+      .replace(/\{\{\s*DONE\s*\}\}/gi, did)
+      .replace(/\{USER\}/gi, user)
+      .replace(/\{DONE\}/gi, did);
+  // Full template already has context — don't double-append USER/DONE sections.
+  // Only skip wrapping when the body looks like a complete recheck brief (marker
+  // or both a request header and a done header), not a casual mention of the words.
+  const looksComplete =
+    isSelfRecheckPrompt(body) ||
+    (/USER'S REQUEST:/i.test(body) && /WHAT WAS JUST DONE/i.test(body));
+  if (looksComplete) {
+    return ensureSelfRecheckMarker(body);
+  }
+  return ensureSelfRecheckMarker(
+    [
+      body,
+      "",
+      "Rules:",
+      "- Prefer fixing real problems with tools when needed; do not invent unrelated features.",
+      "- Do NOT ask the user questions. Do NOT call enter_plan_mode unless truly necessary.",
+      "- End with an honest {progress: N%} marker for this recheck pass.",
+      "",
+      "USER'S REQUEST:",
+      user,
+      "",
+      "WHAT WAS JUST DONE (summary):",
+      did,
+    ].join("\n"),
+  );
+}
+
+/** Prepend the self-recheck marker when missing. */
+export function ensureSelfRecheckMarker(text: string): string {
+  const t = text.trim();
+  if (t.startsWith(SELF_RECHECK_MARKER)) return t;
+  return `${SELF_RECHECK_MARKER} — once only).\n\n${t}`;
+}
+
+function clamp(s: string, max: number): string {
+  if (s.length <= max) return s;
+  return s.slice(0, max - 1) + "\u2026";
+}

package/src/config.ts

@@ -144,6 +144,29 @@ export interface AppConfig {
   autoUpdate: boolean;
   updateCheckMs: number;
   singleInstance: boolean;
+  /**
+   * After a successful Done, ask Grok for 1–3 follow-up suggestions (JSON) and
+   * attach them as inline buttons on the Done message. Default true.
+   */
+  suggestionsEnabled: boolean;
+  /**
+   * Auto-queue any suggestion whose need score is ≥ this percent (0–100).
+   * 0 disables auto-approve (buttons only). Default 95.
+   * Multiple hits are merged into one numbered multi-step prompt.
+   */
+  suggestionsAutoApprovePct: number;
+  /**
+   * After a successful user turn (queue empty), optionally run one self-recheck
+   * pass before Done + suggestions. Skipped when no files changed or when a
+   * quiet AI decision refuses. Default true. Typo alias: SLEF_RECHECK.
+   */
+  selfRecheckEnabled: boolean;
+  /**
+   * Optional override for the recheck turn body when the AI decides recheck is
+   * needed (SELF_RECHECK_PROMPT). Supports {{USER}} and {{DONE}}. Empty → use
+   * the AI-written recheck prompt (or built-in default if the AI left it blank).
+   */
+  selfRecheckPrompt: string;
 }
 
 export function loadConfig(): AppConfig {
@@ -231,11 +254,29 @@ export function loadConfig(): AppConfig {
     autoUpdate: bool(process.env.AUTO_UPDATE, true),
     updateCheckMs: num(process.env.UPDATE_CHECK_MS, 3_600_000),
     singleInstance: bool(process.env.GROK_TG_SINGLE_INSTANCE, true),
+    // Post-turn follow-ups: default on; auto-run suggestions scoring ≥ 95%.
+    suggestionsEnabled: bool(process.env.SUGGESTIONS_ENABLED, true),
+    suggestionsAutoApprovePct: clampPct(process.env.SUGGESTIONS_AUTO_APPROVE_PCT, 95),
+    // One-shot post-turn self-recheck before Done/suggestions (default on).
+    // Accept typo SLEF_RECHECK as alias.
+    selfRecheckEnabled: bool(
+      process.env.SELF_RECHECK ?? process.env.SLEF_RECHECK,
+      true,
+    ),
+    selfRecheckPrompt: (process.env.SELF_RECHECK_PROMPT ?? "").trim(),
   };
 
   return cfg;
 }
 
+/** Parse 0–100 percentage; blank → default. */
+function clampPct(v: string | undefined, def: number): number {
+  if (v === undefined || v === "") return def;
+  const n = Number(v);
+  if (!Number.isFinite(n)) return def;
+  return Math.max(0, Math.min(100, Math.round(n)));
+}
+
 /** Resolve the `grok` binary path. The official installer puts it in
  *  ~/.grok/bin; also try common PATH locations before a bare `grok`. */
 function resolveGrokPath(explicit?: string): string {

package/src/grok/client.ts

@@ -19,19 +19,26 @@ import { IMAGE_OUTPUT_DIRECTIVE } from "../render/image-output.js";
 import { PROGRESS_DIRECTIVE } from "../render/progress.js";
 import { SessionLog } from "./session-log.js";
 import { JsonRpcTransport } from "./transport.js";
-import type {
-  ContentBlock,
-  InitializeResult,
-  JsonRpcMessage,
-  PendingStage,
-  PermissionOutcome,
-  PromptResult,
-  RequestPermissionParams,
-  SessionNotificationParams,
-  SessionUpdate,
-  SubagentInfo,
-  SubagentListUpdate,
+import {
+  contentText,
+  type ContentBlock,
+  type InitializeResult,
+  type JsonRpcMessage,
+  type PendingStage,
+  type PermissionOutcome,
+  type PromptResult,
+  type RequestPermissionParams,
+  type SessionNotificationParams,
+  type SessionUpdate,
+  type SubagentInfo,
+  type SubagentListUpdate,
 } from "./types.js";
+import {
+  autoApproveExitPlanMode,
+  autoSkipAskUserQuestion,
+  isAskUserQuestionMethod,
+  isPlanExitMethod,
+} from "./plan-approval.js";
 
 const log = createLogger("grok:client");
 
@@ -59,6 +66,11 @@ const ACCOUNT_EXHAUSTED_RE =
  * saved login may be permitted, while same-account retries cannot help. */
 const ACCOUNT_ACCESS_DENIED_RE =
   /\b403\b|forbidden|access denied/i;
+/** Process/session lifecycle failures are not evidence that the active login
+ * is bad. They require a session re-bind on the current process generation,
+ * never account rotation. */
+const SESSION_LIFECYCLE_RE =
+  /unknown session id|grok agent is restarting|grok agent stdio exited|grok agent (?:is )?not running|agent connection (?:is )?closed|authentication required.{0,80}no auth method id provided/i;
 
 export class GrokError extends Error {
   constructor(
@@ -123,7 +135,14 @@ export function isAccountRotationError(err: Error): boolean {
   return false;
 }
 
+export function isSessionLifecycleError(err: Error): boolean {
+  return SESSION_LIFECYCLE_RE.test(err.message);
+}
+
 export function isTransientError(err: Error): boolean {
+  // Retrying the same stale session cannot recover a process-generation
+  // mismatch. SessionRuntime owns the immediate re-bind + one safe retry.
+  if (isSessionLifecycleError(err)) return false;
   // Quota exhaustion and access denial are permanent for this login — rotate,
   // never back off and retry the same credentials.
   if (isAccountRotationError(err)) return false;
@@ -265,9 +284,10 @@ export class GrokClient extends EventEmitter {
     this.availableModels = KNOWN_MODELS.map((m) => ({ modelId: m.modelId, name: m.name, description: m.description }));
   }
 
-  async start(): Promise<void> {
+  async start(notifyRestarted = false): Promise<void> {
     this.stopped = false;
     await this.connect();
+    if (notifyRestarted) this.emit("restarted");
   }
 
   private async connect(): Promise<void> {
@@ -499,6 +519,16 @@ export class GrokClient extends EventEmitter {
     this.currentModeId = modeId;
   }
 
+  /** Persisted Running/Sessions card comment (current step or chat summary). */
+  sessionComment(sessionId: string | undefined): string | undefined {
+    if (!sessionId) return undefined;
+    return this.slog.commentFor(sessionId);
+  }
+
+  setSessionComment(sessionId: string, comment: string): void {
+    this.slog.setComment(sessionId, comment);
+  }
+
   async executeCommand(sessionId: string, command: string): Promise<unknown> {
     return this.request("_grok.dev/commands/execute", { sessionId, command });
   }
@@ -529,9 +559,7 @@ export class GrokClient extends EventEmitter {
     this.stopped = true;
     this.restartAttempts = 0;
     await this.killCurrent();
-    this.stopped = false;
-    await this.connect();
-    this.emit("restarted");
+    await this.start(true);
   }
 
   private killCurrent(): Promise<void> {
@@ -643,8 +671,34 @@ export class GrokClient extends EventEmitter {
         // No handler: auto-approve, preferring session-scope / always options.
         const opts = (params.options as Array<{ optionId: string; name?: string; kind?: string }>) ?? [];
         result = pickAllowOption(opts);
+      } else if (isPlanExitMethod(method)) {
+        // Live method name is `_x.ai/exit_plan_mode` (leading underscore).
+        // Grok intercepts exit_plan_mode and reverse-requests the client to
+        // show a plan-approval UI. Method-not-found is reported as
+        // "client disconnected" and plan mode stays Active forever.
+        const planSnippet =
+          (typeof params.planContent === "string" && params.planContent) ||
+          (typeof params.plan_content === "string" && params.plan_content) ||
+          (typeof params.plan_file_path === "string" && params.plan_file_path) ||
+          "";
+        const keys = Object.keys(params || {}).slice(0, 20).join(",");
+        log.info(
+          `auto-approving plan exit via ${method}` +
+            (params.sessionId ? ` session=${String(params.sessionId).slice(0, 8)}` : "") +
+            (params.toolCallId ? ` tool=${String(params.toolCallId).slice(0, 24)}` : "") +
+            (planSnippet ? ` plan=${planSnippet.replace(/\s+/g, " ").slice(0, 80)}` : "") +
+            (keys ? ` keys=[${keys}]` : ""),
+        );
+        result = autoApproveExitPlanMode(params);
+      } else if (isAskUserQuestionMethod(method)) {
+        // No TUI question form: skip so the agent continues (prefer later Telegram UI).
+        log.info(`auto-skipping ${method} (no interactive question UI in Telegram bridge)`);
+        result = autoSkipAskUserQuestion(params);
       } else {
         // We advertise no fs/terminal capabilities, so the agent shouldn't ask.
+        // Log at warn — unknown reverse methods used to silently break plan exit
+        // when we only matched `x.ai/…` and Grok sent `_x.ai/…`.
+        log.warn(`unsupported client reverse-request: ${method} keys=[${Object.keys(params || {}).join(",")}]`);
         throw new GrokError(`unsupported client method: ${method}`, -32601);
       }
       this.transport?.send({ jsonrpc: "2.0", id, result });
@@ -690,10 +744,28 @@ export class GrokClient extends EventEmitter {
 
   /** Accumulate assistant text and log tool calls to the session's jsonl. */
   private recordUpdate(sessionId: string, u: SessionUpdate): void {
-    if (u.sessionUpdate === "agent_message_chunk" && typeof u.content?.text === "string") {
-      this.assistantBuf.set(sessionId, (this.assistantBuf.get(sessionId) ?? "") + u.content.text);
-    } else if (u.sessionUpdate === "tool_call" && (u.title || u.kind)) {
-      this.slog.logTool(sessionId, u.title || u.kind || "tool", "");
+    if (u.sessionUpdate === "agent_message_chunk") {
+      const t = contentText(u.content);
+      if (t) this.assistantBuf.set(sessionId, (this.assistantBuf.get(sessionId) ?? "") + t);
+    } else if (u.sessionUpdate === "tool_call" || u.sessionUpdate === "tool_call_update") {
+      // Prefer stable name over generic title ("Tool call").
+      const name =
+        (typeof u.name === "string" && u.name) ||
+        (typeof u.toolName === "string" && u.toolName) ||
+        (typeof u.title === "string" && u.title && !/^tool[_ ]?call$/i.test(u.title) ? u.title : "") ||
+        u.kind ||
+        "tool";
+      const raw = (u.rawInput || {}) as Record<string, unknown>;
+      const detail =
+        (typeof raw.path === "string" && raw.path) ||
+        (typeof raw.target_file === "string" && raw.target_file) ||
+        (typeof raw.command === "string" && raw.command) ||
+        (typeof raw.pattern === "string" && raw.pattern) ||
+        (Array.isArray(u.locations) && u.locations[0]?.path) ||
+        "";
+      if (u.sessionUpdate === "tool_call" || detail) {
+        this.slog.logTool(sessionId, String(name), detail ? String(detail).slice(0, 200) : "");
+      }
     }
     // Derive a context-usage %/token count if the update carries usage info.
     const usage = (u as { usage?: { totalTokens?: number } }).usage;
@@ -738,6 +810,20 @@ export class GrokClient extends EventEmitter {
     const marker = "User's new message:\n";
     const mi = t.lastIndexOf(marker);
     if (mi !== -1) t = t.slice(mi + marker.length);
+    // Strip auto-complexity steering (and legacy forced-complex wrapper).
+    const taskMarker = "User task:";
+    const ti = t.lastIndexOf(taskMarker);
+    if (
+      ti !== -1 &&
+      (/^COMPLEXITY \(decide yourself/i.test(t) || /^TASK COMPLEXITY:/i.test(t))
+    ) {
+      t = t.slice(ti + taskMarker.length);
+    }
+    // Never persist quiet meta-prompts as a user message title.
+    if (/^Session status update \(meta only\)/i.test(t.trim())) t = "";
+    if (/^FOLLOW-UP SUGGESTIONS \(meta only\)/i.test(t.trim())) t = "";
+    if (/^SELF-RECHECK DECISION \(meta only\)/i.test(t.trim())) t = "";
+    if (/^SELF-RECHECK \(automatic quality pass/i.test(t.trim())) t = "";
     t = t.replace(/^\([^\n)]*\)\s*\n+/, "");
     return t.trim();
   }