grok-telegram-bot 2.2.3 → 2.3.0

package/src/bot/handlers/projects.ts

@@ -60,8 +60,11 @@ export async function sendProjectMenu(
  *  "last used" is the latest of its directory mtime and the newest session
  *  opened in it, so the project you worked in most recently floats to the top. */
 function sortByRecency(entries: ProjectEntry[], deps: BotDeps): ProjectEntry[] {
+  if (entries.length === 0) return entries;
+  // Cap the session scan — full directory walks get expensive as history grows,
+  // and only the freshest sessions matter for ranking.
   const recencyByCwd = new Map<string, number>();
-  for (const s of deps.store.list(300)) {
+  for (const s of deps.store.list(80)) {
     const key = normCwd(s.cwd);
     if (!key) continue;
     const ms = Date.parse(s.updatedAt);
@@ -87,7 +90,8 @@ export async function showProjects(ctx: Context, deps: BotDeps, query?: string):
   if (create) {
     try {
       const entry = deps.projects.create(create[1]!);
-      await deps.registry.controller(ctx.chat!.id).addNew(entry.path, entry.name);
+      // Instant switch — ACP session is created on the first message.
+      await deps.registry.controller(ctx.chat!.id).switchProject(entry.path, entry.name);
       await refreshMenu(ctx, deps, `\u2705 Created and opened ${entry.name}\n${entry.path} \u2014 send a message.`);
     } catch (e) {
       await deps.ephemeral.open(ctx);
@@ -132,7 +136,7 @@ async function openProjectPath(ctx: Context, deps: BotDeps, raw: string): Promis
   await deps.ephemeral.open(ctx);
   const name = basename(dir) || dir;
   try {
-    await deps.registry.controller(ctx.chat!.id).addNew(dir, name);
+    await deps.registry.controller(ctx.chat!.id).switchProject(dir, name);
     await refreshMenu(ctx, deps, `\u{1F4C1} Now working in ${name}\n${dir} \u2014 send a message.`);
   } catch (e) {
     await deps.ephemeral.reply(ctx, `\u274C Could not open ${dir}: ${(e as Error).message}`);
@@ -171,10 +175,12 @@ export function registerProjects(bot: Bot, deps: BotDeps): void {
       await ctx.answerCallbackQuery({ text: "Selection expired, run /projects again." });
       return;
     }
-    await ctx.answerCallbackQuery();
+    // Answer immediately (before any work) so Telegram never times out the query.
+    await ctx.answerCallbackQuery({ text: `Opening ${entry.name}\u2026` });
     await deps.ephemeral.clear(ctx.chat!.id); // remove the project picker
     try {
-      await deps.registry.controller(ctx.chat!.id).addNew(entry.path, entry.name);
+      // Instant: no ACP session/new — live session is created on first message.
+      await deps.registry.controller(ctx.chat!.id).switchProject(entry.path, entry.name);
       await refreshMenu(ctx, deps, `\u{1F4C1} Now working in ${entry.name} \u2014 send a message.`);
     } catch (err) {
       await ctx.reply(`\u274C Could not open ${entry.name}: ${(err as Error).message}`);

package/src/bot/handlers/voice.ts

@@ -1,6 +1,10 @@
 /**
  * Voice & audio handler — transcribes Telegram voice notes / audio files to
  * text (any language) and submits them as prompts.
+ *
+ * Requires STT_API_URL (and optionally STT_API_KEY). Grok Build CLI over ACP
+ * does not accept audio content blocks, so without an STT endpoint voice is
+ * disabled rather than attaching raw audio the agent cannot hear.
  */
 import type { Bot, Context } from "grammy";
 import { textPrompt } from "../../app/types.js";
@@ -18,7 +22,9 @@ export function registerVoice(bot: Bot, deps: BotDeps): void {
       return;
     }
     if (!deps.stt.enabled) {
-      await ctx.reply("\u{1F399} Voice isn't configured. Set STT_API_URL (and STT_API_KEY) in .env.");
+      await ctx.reply(
+        "\u{1F399} Voice isn't configured. Set STT_API_URL (and STT_API_KEY if needed) in .env.",
+      );
       return;
     }
     await ctx.replyWithChatAction("typing").catch(() => {});
@@ -41,9 +47,20 @@ export function registerVoice(bot: Bot, deps: BotDeps): void {
     }
   };
 
-  bot.on("message:voice", (ctx) => handle(ctx, ctx.message.voice.file_id, ctx.message.voice.mime_type || "audio/ogg", "voice.ogg"));
-  bot.on("message:audio", (ctx) => handle(ctx, ctx.message.audio.file_id, ctx.message.audio.mime_type || "audio/mpeg", ctx.message.audio.file_name || "audio.mp3"));
-  bot.on("message:video_note", (ctx) => handle(ctx, ctx.message.video_note.file_id, "video/mp4", "note.mp4"));
+  bot.on("message:voice", (ctx) =>
+    handle(ctx, ctx.message.voice.file_id, ctx.message.voice.mime_type || "audio/ogg", "voice.ogg"),
+  );
+  bot.on("message:audio", (ctx) =>
+    handle(
+      ctx,
+      ctx.message.audio.file_id,
+      ctx.message.audio.mime_type || "audio/mpeg",
+      ctx.message.audio.file_name || "audio.mp3",
+    ),
+  );
+  bot.on("message:video_note", (ctx) =>
+    handle(ctx, ctx.message.video_note.file_id, "video/mp4", "note.mp4"),
+  );
 }
 
 async function download(ctx: Context, fileId: string, token: string): Promise<Buffer | undefined> {

package/src/bot/image-return.ts

@@ -1,30 +1,125 @@
 /**
- * Agent image return — detects image files the agent produced this turn
- * (screenshots, diagrams…) from its output and tool inputs, and sends them
- * back to Telegram. Only fresh files (modified during the turn) are sent.
+ * Agent image return — finds image files the agent produced this turn
+ * (Imagine `image_gen` / `image_edit`, screenshots, diagrams…) and sends them
+ * back to Telegram as **downloadable files** (`sendDocument`).
+ *
+ * Discovery sources:
+ *   1. Paths mentioned in agent text / tool inputs (project-relative or absolute)
+ *   2. Fresh files under the Grok session media dirs
+ *      (`~/.grok/sessions/<encoded-cwd>/<sessionId>/images/` and `…/assets/`)
+ *   3. Fresh files under `<cwd>/images/` (common short path reported by tools)
  */
 import { type Api, InputFile } from "grammy";
-import { existsSync, statSync } from "node:fs";
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
 import { basename, isAbsolute, join } from "node:path";
 import { createLogger } from "../logger.js";
 
+// Re-export so existing import paths (`./image-return.js`) keep working.
+export { IMAGE_OUTPUT_DIRECTIVE } from "../render/image-output.js";
+
 const log = createLogger("image-return");
 
-const PATH_RE = /[^\s"'`<>|()*\[\]]+\.(?:png|jpe?g|gif|webp|bmp)/gi;
-const PHOTO_EXT = new Set(["png", "jpg", "jpeg", "webp"]);
-const MAX_PHOTO_BYTES = 10 * 1024 * 1024;
+/** Absolute / relative image path tokens in free text (Unix + Windows). */
+const PATH_RE =
+  /(?:[A-Za-z]:[\\/]|\/|~[\\/]|\.{1,2}[\\/])?[^\s"'`<>|()*\[\]{}]+\.(?:png|jpe?g|gif|webp|bmp)/gi;
+const IMAGE_EXT = new Set(["png", "jpg", "jpeg", "gif", "webp", "bmp"]);
 const MAX_FILE_BYTES = 45 * 1024 * 1024;
 
 /** Pull candidate image paths out of arbitrary text, resolved against cwd. */
 export function extractImagePaths(text: string, cwd: string): string[] {
   const out = new Set<string>();
   for (const m of text.matchAll(PATH_RE)) {
-    const raw = m[0].replace(/[).,;:]+$/, "");
+    let raw = m[0].replace(/[).,;:]+$/, "");
+    if (raw.startsWith("~/") || raw.startsWith("~\\")) {
+      raw = join(homedir(), raw.slice(2));
+    }
     out.add(isAbsolute(raw) ? raw : join(cwd, raw));
   }
   return [...out];
 }
 
+/**
+ * Grok stores per-session media under:
+ *   ~/.grok/sessions/<encodeURIComponent(cwd)>/<sessionId>/{images,assets}/
+ * Imagine `image_gen` currently prefers `images/`; older runs used `assets/`.
+ */
+export function grokSessionMediaRoot(cwd: string, sessionId: string): string {
+  return join(homedir(), ".grok", "sessions", encodeURIComponent(cwd), sessionId);
+}
+
+/** @deprecated Prefer grokSessionMediaDirs — kept for callers/tests that used assets. */
+export function grokSessionAssetsDir(cwd: string, sessionId: string): string {
+  return join(grokSessionMediaRoot(cwd, sessionId), "assets");
+}
+
+/** Session folders where Imagine / tools drop generated images. */
+export function grokSessionMediaDirs(cwd: string, sessionId: string): string[] {
+  const root = grokSessionMediaRoot(cwd, sessionId);
+  return [join(root, "images"), join(root, "assets")];
+}
+
+/** List image files under `dir` modified at/after `since` (non-recursive). */
+export function listFreshImagesInDir(dir: string, since: number): string[] {
+  if (!existsSync(dir)) return [];
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return [];
+  }
+  const out: string[] = [];
+  for (const name of names) {
+    const path = join(dir, name);
+    const ext = name.toLowerCase().split(".").pop() ?? "";
+    if (!IMAGE_EXT.has(ext)) continue;
+    try {
+      const st = statSync(path);
+      if (!st.isFile() || st.size === 0 || st.size > MAX_FILE_BYTES) continue;
+      // 2s slack for clock skew / write completion.
+      if (st.mtimeMs < since - 2000) continue;
+      out.push(path);
+    } catch {
+      /* skip */
+    }
+  }
+  // Newest first so max-cap still keeps the latest gens.
+  return out.sort((a, b) => {
+    try {
+      return statSync(b).mtimeMs - statSync(a).mtimeMs;
+    } catch {
+      return 0;
+    }
+  });
+}
+
+/** Collect all image candidates for a turn from text + known asset locations. */
+export function collectTurnImagePaths(opts: {
+  scanText: string;
+  cwd: string;
+  sessionId?: string;
+  since: number;
+}): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  const add = (paths: string[]) => {
+    for (const p of paths) {
+      if (seen.has(p)) continue;
+      seen.add(p);
+      out.push(p);
+    }
+  };
+
+  add(extractImagePaths(opts.scanText, opts.cwd));
+  add(listFreshImagesInDir(join(opts.cwd, "images"), opts.since));
+  if (opts.sessionId) {
+    for (const dir of grokSessionMediaDirs(opts.cwd, opts.sessionId)) {
+      add(listFreshImagesInDir(dir, opts.since));
+    }
+  }
+  return out;
+}
+
 export interface SendImagesOptions {
   /** Only send files modified at/after this epoch ms (fresh this turn). */
   since: number;
@@ -32,9 +127,11 @@ export interface SendImagesOptions {
   already: Set<string>;
   /** Max images to send in this call. */
   max: number;
+  /** Optional Telegram message id to thread replies under. */
+  replyTo?: number;
 }
 
-/** Send the valid, fresh, not-yet-sent images. Returns how many were sent. */
+/** Send the valid, fresh, not-yet-sent images as documents. Returns how many were sent. */
 export async function sendImages(
   api: Api,
   chatId: number,
@@ -42,6 +139,10 @@ export async function sendImages(
   opts: SendImagesOptions,
 ): Promise<number> {
   let sent = 0;
+  const replyExtra =
+    opts.replyTo !== undefined
+      ? { reply_parameters: { message_id: opts.replyTo, allow_sending_without_reply: true } }
+      : {};
   for (const path of paths) {
     if (sent >= opts.max) break;
     if (opts.already.has(path)) continue;
@@ -55,12 +156,15 @@ export async function sendImages(
     if (st.mtimeMs < opts.since - 2000) continue; // skip pre-existing files
     opts.already.add(path);
     try {
-      const ext = path.toLowerCase().split(".").pop() ?? "";
-      const asPhoto = PHOTO_EXT.has(ext) && st.size <= MAX_PHOTO_BYTES;
-      const file = new InputFile(path);
-      if (asPhoto) await api.sendPhoto(chatId, file, { caption: basename(path) });
-      else await api.sendDocument(chatId, file, { caption: basename(path) });
+      // Always send as a document so Telegram delivers a downloadable file
+      // (not a compressed photo bubble).
+      const file = new InputFile(path, basename(path));
+      await api.sendDocument(chatId, file, {
+        caption: basename(path),
+        ...replyExtra,
+      });
       sent++;
+      log.debug(`sent document ${path}`);
     } catch (e) {
       log.debug(`failed to send ${path}:`, (e as Error).message);
     }

package/src/bot/prompt-content.ts

@@ -1,7 +1,7 @@
 /**
- * Build ACP prompt content blocks from a PromptInput (text + images), applying
- * the reasoning directive and any fork-priming context. Also merges multiple
- * queued inputs into one.
+ * Build ACP prompt content blocks from a PromptInput (text + images + optional
+ * resource links), applying the reasoning directive and any fork-priming
+ * context. Also merges multiple queued inputs into one.
  */
 import type { ContentBlock } from "../grok/types.js";
 import type { PromptInput } from "../app/types.js";
@@ -9,8 +9,10 @@ import type { PromptInput } from "../app/types.js";
 export interface ContentOptions {
   reasoning?: string;
   priming?: string;
-  /** Appended at the very bottom so the agent emits a `{progress: N%}` marker. */
+  /** Appended so the agent emits a `{progress: N%}` marker. */
   progress?: string;
+  /** Appended so the agent keeps generated images in the session media folder. */
+  imageOutput?: string;
 }
 
 export function buildContentBlocks(input: PromptInput, opts: ContentOptions = {}): ContentBlock[] {
@@ -19,11 +21,23 @@ export function buildContentBlocks(input: PromptInput, opts: ContentOptions = {}
   for (const img of input.images) {
     blocks.push({ type: "image", data: img.data, mimeType: img.mimeType });
   }
+  for (const link of input.resourceLinks ?? []) {
+    blocks.push({
+      type: "resource_link",
+      uri: link.uri,
+      name: link.name,
+      mimeType: link.mimeType,
+      size: link.size,
+    });
+  }
 
   let text = input.text.trim();
   if (!text && input.images.length > 0) {
     text = input.images.length === 1 ? "Please analyze the attached image." : "Please analyze the attached images.";
   }
+  if (!text && (input.resourceLinks?.length ?? 0) > 0) {
+    text = "Please process the attached file(s).";
+  }
   if (input.quotedText?.trim()) {
     const quoted = input.quotedText.trim();
     const body = text || "(the user's reply carried no additional text)";
@@ -35,7 +49,11 @@ export function buildContentBlocks(input: PromptInput, opts: ContentOptions = {}
   if (opts.reasoning) {
     text = `(${opts.reasoning})\n\n${text}`;
   }
+  if (opts.imageOutput) {
+    text = `${text}\n\n${opts.imageOutput}`;
+  }
   if (opts.progress) {
+    // Progress last so its "marker is the final line" rule stays true.
     text = `${text}\n\n${opts.progress}`;
   }
 
@@ -43,7 +61,7 @@ export function buildContentBlocks(input: PromptInput, opts: ContentOptions = {}
   return blocks;
 }
 
-/** Merge queued inputs into a single prompt (concatenated text, all images). */
+/** Merge queued inputs into a single prompt (concatenated text, all images/links). */
 export function mergeInputs(inputs: PromptInput[]): PromptInput {
   const quotes = inputs
     .map((i) => i.quotedText?.trim())
@@ -54,6 +72,7 @@ export function mergeInputs(inputs: PromptInput[]): PromptInput {
       .filter((t) => t.trim().length > 0)
       .join("\n\n"),
     images: inputs.flatMap((i) => i.images),
+    resourceLinks: inputs.flatMap((i) => i.resourceLinks ?? []),
     replyTo: inputs.find((i) => i.replyTo !== undefined)?.replyTo,
     quotedText: quotes.length > 0 ? [...new Set(quotes)].join("\n\n---\n\n") : undefined,
   };

package/src/bot/session-runtime.ts

@@ -8,7 +8,7 @@ import { basename } from "node:path";
 import { type Api, InlineKeyboard } from "grammy";
 import {
   type GrokClient,
-  isAccountExhaustedError,
+  isAccountRotationError,
   isContextExhaustedError,
   isTransientError,
   type SessionMetadata,
@@ -31,7 +31,8 @@ import { type FileOp, fileOpFromUpdate, mergeFileOp, summarizeFileOps, summarize
 import { isActiveStatus, renderSubagentTransition, statusKey } from "../render/subagent.js";
 import type { PendingStage, SubagentInfo } from "../grok/types.js";
 import { ResponseStreamer } from "../stream/streamer.js";
-import { extractImagePaths, sendImages } from "./image-return.js";
+import { IMAGE_OUTPUT_DIRECTIVE } from "../render/image-output.js";
+import { collectTurnImagePaths, sendImages } from "./image-return.js";
 import { buildContentBlocks, mergeInputs } from "./prompt-content.js";
 import {
   backoffSchedule,
@@ -101,6 +102,8 @@ export class SessionRuntime {
   private turnReplyTo: number | undefined;
   private imageScanText = "";
   private sentImagesThisTurn = new Set<string>();
+  /** Monotonic count used to reject ACP "success" responses with no turn updates. */
+  private sessionUpdateCount = 0;
   private readonly listener: (sessionId: string, update: SessionUpdate) => void;
   private primingContext: string | undefined;
   private watcher: TailWatcher | undefined;
@@ -214,8 +217,11 @@ export class SessionRuntime {
       this.typing.stop();
       this.stopWatch();
       if (this.streamer) {
-        await this.streamer.finalize().catch(() => {});
+        // Finalize off the critical path so project/session switches never wait
+        // on Telegram edits of the previous live stream.
+        const prev = this.streamer;
         this.streamer = undefined;
+        void prev.finalize().catch(() => {});
       }
     }
     this.changed();
@@ -512,6 +518,7 @@ export class SessionRuntime {
     const content = buildContentBlocks(input, {
       reasoning: reasoningDirective(this.reasoning),
       priming: this.primingContext,
+      imageOutput: this.cfg.sendAgentImages ? IMAGE_OUTPUT_DIRECTIVE : undefined,
       progress: this.cfg.showProgress ? PROGRESS_DIRECTIVE : undefined,
     });
     this.primingContext = undefined;
@@ -668,6 +675,7 @@ export class SessionRuntime {
     const forkContent = buildContentBlocks(input, {
       reasoning: reasoningDirective(this.reasoning),
       priming: transcript ? buildPriming(transcript) : undefined,
+      imageOutput: this.cfg.sendAgentImages ? IMAGE_OUTPUT_DIRECTIVE : undefined,
       progress: this.cfg.showProgress ? PROGRESS_DIRECTIVE : undefined,
     });
     return this.runPromptWithRetries(forkContent);
@@ -692,6 +700,14 @@ export class SessionRuntime {
   ): Promise<{ result?: PromptResult; error?: Error; attempts: number } | undefined> {
     const rotator = this.accountRotator;
     if (!rotator?.enabled() || !final.error || this.cancelled) return undefined;
+    // A quota-exhausted or access-denied response cannot be recovered by retrying
+    // this login. Quarantine it before choosing targets, so later rotations do not
+    // cycle back to a known-bad account. This intentionally happens before the
+    // partial-stream guard: we must not retry/rotate a partial reply, but its
+    // account still needs to be skipped during a future rotation.
+    if (isAccountRotationError(final.error)) {
+      await rotator.markFailed(undefined, final.error.message);
+    }
     if (this.streamer?.hasOutput ?? false) return undefined;
     const targets = await rotator.targets().catch(() => [] as { id: string; label: string }[]);
     if (targets.length === 0) return undefined;
@@ -726,11 +742,12 @@ export class SessionRuntime {
       const content = buildContentBlocks(input, {
         reasoning: reasoningDirective(this.reasoning),
         priming: transcript ? buildPriming(transcript) : undefined,
-        progress: this.cfg.showProgress ? PROGRESS_DIRECTIVE : undefined,
+        imageOutput: this.cfg.sendAgentImages ? IMAGE_OUTPUT_DIRECTIVE : undefined,
+      progress: this.cfg.showProgress ? PROGRESS_DIRECTIVE : undefined,
       });
       log.info(
         `chat ${this.chatId} auto-rotating to account ${t.label}` +
-          (isAccountExhaustedError(failReason) ? " (billing/quota exhausted on previous)" : ""),
+          (isAccountRotationError(failReason) ? " (previous account unavailable)" : ""),
       );
       // runPromptWithRetries already skips backoff for 402 / balance exhausted.
       last = await this.runPromptWithRetries(content);
@@ -740,6 +757,9 @@ export class SessionRuntime {
         }
         return last;
       }
+      if (last.error && isAccountRotationError(last.error)) {
+        await rotator.markFailed(t.id, last.error.message);
+      }
       if (this.cancelled || (this.streamer?.hasOutput ?? false)) return last;
       errors.push(`\u2022 ${t.label}: ${last.error?.message ?? "failed"}`);
     }
@@ -767,7 +787,16 @@ export class SessionRuntime {
     for (;;) {
       attempt++;
       try {
+        const updatesBeforePrompt = this.sessionUpdateCount;
         const result = await this.acp.prompt(this.sessionId!, content);
+        // A healthy ACP turn emits at least one session/update (text, thought,
+        // or tool event) before resolving session/prompt. Grok can otherwise
+        // report a successful end-turn after an upstream model failure; never
+        // present that as a completed user request.
+        await sleep(0);
+        if (this.sessionUpdateCount === updatesBeforePrompt) {
+          throw new Error("Empty agent response — Grok ended the turn without any output or tool activity");
+        }
         return { result, attempts: attempt };
       } catch (err) {
         const error = err as Error;
@@ -781,7 +810,7 @@ export class SessionRuntime {
           attempt <= delays.length &&
           canRecover &&
           !forkInstead &&
-          !isAccountExhaustedError(error) &&
+          !isAccountRotationError(error) &&
           isTransientError(error);
         if (!willRetry) return { error, attempts: attempt };
         const waitMs = delays[attempt - 1]!;
@@ -837,6 +866,7 @@ export class SessionRuntime {
     const delays = this.cfg.promptRetryAttempts > 0 ? backoffSchedule(this.cfg.promptRetryAttempts) : [RETRY_BASE_MS];
     const resumeContent = buildContentBlocks(textPrompt(RESUME_INSTRUCTION), {
       reasoning: reasoningDirective(this.reasoning),
+      imageOutput: this.cfg.sendAgentImages ? IMAGE_OUTPUT_DIRECTIVE : undefined,
       progress: this.cfg.showProgress ? PROGRESS_DIRECTIVE : undefined,
     });
 
@@ -866,17 +896,26 @@ export class SessionRuntime {
     return last;
   }
 
-  /** Send any fresh images the agent produced this turn (screenshots, etc.). */
+  /** Send any fresh images the agent produced this turn (Imagine, screenshots…). */
   private async sendTurnImages(): Promise<void> {
-    if (!this.cfg.sendAgentImages || !this.imageScanText) return;
-    const paths = extractImagePaths(this.imageScanText, this.cwd);
+    if (!this.cfg.sendAgentImages) return;
+    // Always check session images/ + assets/ even when the agent never named a
+    // path in text — image_gen writes under ~/.grok/sessions/.../images/.
+    const paths = collectTurnImagePaths({
+      scanText: this.imageScanText,
+      cwd: this.cwd,
+      sessionId: this.sessionId,
+      since: this.turnStartedAt,
+    });
     if (paths.length === 0) return;
     try {
-      await sendImages(this.api, this.chatId, paths, {
+      const n = await sendImages(this.api, this.chatId, paths, {
         since: this.turnStartedAt,
         already: this.sentImagesThisTurn,
         max: this.cfg.agentImagesMax,
+        replyTo: this.turnReplyTo,
       });
+      if (n > 0) log.info(`chat ${this.chatId}: sent ${n} agent image file(s)`);
     } catch {
       /* non-fatal */
     }
@@ -960,6 +999,7 @@ export class SessionRuntime {
 
   private onUpdate(sessionId: string, update: SessionUpdate): void {
     if (!this.busy || sessionId !== this.sessionId) return;
+    this.sessionUpdateCount++;
     const kind = update.sessionUpdate;
 
     // Accumulate the turn's file-change summary + image-scan text even when this
@@ -968,6 +1008,12 @@ export class SessionRuntime {
     if (kind === "tool_call" || kind === "tool_call_update") {
       if (update.rawInput) this.imageScanText += " " + JSON.stringify(update.rawInput);
       if (update.title) this.imageScanText += " " + update.title;
+      // Tool results often carry the saved path only in content_blocks (Imagine).
+      if (Array.isArray(update.content_blocks)) {
+        this.imageScanText += " " + JSON.stringify(update.content_blocks);
+      }
+      // Some agents put free-form result text on `content`.
+      if (update.content?.text) this.imageScanText += " " + update.content.text;
       const fo = fileOpFromUpdate(update);
       if (fo) this.fileOps.set(fo.path, mergeFileOp(this.fileOps.get(fo.path), fo.op));
     } else if (kind === "agent_message_chunk") {

package/src/config.ts

@@ -44,9 +44,10 @@ function resolveInstanceDir(): string {
   return CANONICAL_DIR;
 }
 
-// Load .env from the resolved instance directory. dotenv does NOT override
-// variables already present in the environment (the launcher/service env wins).
-loadDotenv({ path: ENV_PATH });
+// Load .env from the resolved instance directory. Keep the parsed values as
+// well: a machine-wide TELEGRAM_BOT_TOKEN may belong to a sibling bot (Codex,
+// Kiro, etc.) and must never override this Grok instance's identity.
+const instanceEnv = loadDotenv({ path: ENV_PATH }).parsed ?? {};
 
 function expandHome(p: string): string {
   if (p === "~") return homedir();
@@ -146,7 +147,10 @@ export interface AppConfig {
 }
 
 export function loadConfig(): AppConfig {
-  const token = (process.env.TELEGRAM_BOT_TOKEN || "").trim();
+  // Telegram long polling permits one consumer per token. Prefer the token in
+  // this bot's own instance file over a globally inherited environment value,
+  // otherwise a Grok process can accidentally poll as a sibling bot.
+  const token = (instanceEnv.TELEGRAM_BOT_TOKEN || process.env.TELEGRAM_BOT_TOKEN || "").trim();
   if (!token) {
     throw new Error(
       "TELEGRAM_BOT_TOKEN is missing. Copy .env.example to .env and set it (run `npm run setup`).",

package/src/grok/client.ts

@@ -15,6 +15,7 @@ import { EventEmitter } from "node:events";
 import { createLogger } from "../logger.js";
 import { hasLogin } from "../app/grok-credentials.js";
 import { contextWindowFor, DEFAULT_MODEL, KNOWN_MODELS } from "./models.js";
+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";
@@ -43,7 +44,7 @@ export interface SessionMetadata {
 
 const TRANSIENT_CODES = new Set([-32603, -32500, -32000, 500, 502, 503, 504, 429]);
 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;
+  /internal error|high volume|experiencing|overloaded|temporar|unavailable|rate.?limit|too many requests|try again|capacity|dispatch failure|response stream|empty agent response|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;
 /**
@@ -54,6 +55,10 @@ const CONTEXT_EXHAUSTED_RE =
  */
 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;
+/** Account-level authorization failures from the Grok CLI proxy. A different
+ * saved login may be permitted, while same-account retries cannot help. */
+const ACCOUNT_ACCESS_DENIED_RE =
+  /\b403\b|forbidden|access denied/i;
 
 export class GrokError extends Error {
   constructor(
@@ -92,9 +97,36 @@ export function isAccountExhaustedError(err: Error): boolean {
   return false;
 }
 
+/**
+ * True when the active saved login cannot serve the request: either its Grok
+ * Build quota is exhausted (402), or the proxy rejects it as unauthorized
+ * (403 / Forbidden / Access denied). Both must skip same-account backoff and
+ * trigger account rotation when enabled.
+ */
+export function isAccountRotationError(err: Error): boolean {
+  if (isAccountExhaustedError(err) || ACCOUNT_ACCESS_DENIED_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 === 403 || status === "403") return true;
+  if (typeof d.message === "string" && ACCOUNT_ACCESS_DENIED_RE.test(d.message)) return true;
+  for (const value of Object.values(d)) {
+    if (typeof value === "string" && ACCOUNT_ACCESS_DENIED_RE.test(value)) return true;
+    if (value && typeof value === "object") {
+      const nested = value as Record<string, unknown>;
+      const nestedStatus = nested.http_status ?? nested.status ?? nested.statusCode;
+      if (nestedStatus === 403 || nestedStatus === "403") return true;
+      if (typeof nested.message === "string" && ACCOUNT_ACCESS_DENIED_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;
+  // Quota exhaustion and access denial are permanent for this login — rotate,
+  // never back off and retry the same credentials.
+  if (isAccountRotationError(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);
@@ -697,8 +729,12 @@ export class GrokClient extends EventEmitter {
    *  leading reasoning directive, fork/priming preamble) removed, for a clean log. */
   private cleanUserText(content: ContentBlock[]): string {
     let t = this.visibleText(content);
+    // Strip bot-injected appendices (image rules first, then progress — progress
+    // is always last when both are present).
     const pi = t.indexOf(PROGRESS_DIRECTIVE);
     if (pi !== -1) t = t.slice(0, pi).trimEnd();
+    const ii = t.indexOf(IMAGE_OUTPUT_DIRECTIVE);
+    if (ii !== -1) t = t.slice(0, ii).trimEnd();
     const marker = "User's new message:\n";
     const mi = t.lastIndexOf(marker);
     if (mi !== -1) t = t.slice(mi + marker.length);

package/src/grok/types.ts

@@ -26,12 +26,23 @@ export interface JsonRpcNotification {
 
 export type JsonRpcMessage = JsonRpcResponse & JsonRpcNotification & { method?: string };
 
-/** A content block in a prompt or message. */
+/** A content block in a prompt or message (ACP ContentBlock subset). */
 export interface ContentBlock {
-  type: "text" | "image" | "resource";
+  type: "text" | "image" | "audio" | "resource" | "resource_link";
   text?: string;
   data?: string;
   mimeType?: string;
+  /** resource_link */
+  uri?: string;
+  name?: string;
+  size?: number;
+  /** embedded resource */
+  resource?: {
+    uri: string;
+    mimeType?: string;
+    text?: string;
+    blob?: string;
+  };
   [k: string]: unknown;
 }
 
@@ -47,7 +58,11 @@ export interface InitializeResult {
   authMethods?: AuthMethod[];
   agentCapabilities?: {
     loadSession?: boolean;
-    promptCapabilities?: { image?: boolean };
+    promptCapabilities?: {
+      image?: boolean;
+      audio?: boolean;
+      embeddedContext?: boolean;
+    };
   };
   agentInfo?: { name?: string; version?: string };
 }