grok-telegram-bot 2.2.4 → 2.3.0

package/.env.example

@@ -132,9 +132,12 @@ QUIET_NOTIFICATIONS=true
 # LOG_DIR=
 # LOG_FILE=
 
-# ── Voice messages (speech-to-text) ──────────────────────────────────────────
-# Any OpenAI/Whisper-compatible transcription endpoint. xAI offers one too:
-# STT_API_URL=https://api.x.ai/v1
+# ── Voice messages (optional) ────────────────────────────────────────────────
+# Voice is ONLY available when STT is configured. Grok Build CLI over ACP does
+# not accept audio content blocks, so without STT the bot replies that voice
+# isn't configured. Use any OpenAI/Whisper-compatible transcription endpoint
+# (including xAI STT if your gateway exposes /audio/transcriptions):
+# STT_API_URL=https://api.openai.com/v1
 # STT_API_KEY=
 # STT_MODEL=whisper-1
-# STT_LANGUAGE=
+# STT_LANGUAGE=                # blank = auto-detect

package/CHANGELOG.md

@@ -7,29 +7,57 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 The latest section is published verbatim as the GitHub Release notes by
 `.github/workflows/release.yml` when a `vX.Y.Z` tag is pushed.
 
-## [Unreleased]
-
-## [2.2.4] - 2026-07-16
-
-### Fixed
-
-- **🚫 Rotate immediately on Grok access denial.** API `403 Forbidden` / `Access
-  denied` responses now bypass same-account retry backoff, mark the failed
-  login with `⚠️`, and rotate to the next eligible saved account. If the active
-  host login was not already saved (for example after an external sign-in or
-  token refresh), it is captured first so the warning is visible and persists.
-- **🔐 Isolated Grok Telegram identity.** The Grok bot now takes its Telegram
-  token from its own instance `.env` before considering an inherited process
-  environment value. This prevents a machine-wide token for a sibling bot from
-  making Grok poll as Codex/Kiro/OpenCode and causing Telegram conflicts.
-- **⚠️ Persistent account warnings.** Account access/quota failures are shown
-  in `/accounts`, excluded from later automatic rotations, and can be manually
-  re-enabled after the account is repaired.
-- **🛟 No false success for silent ACP turns.** A Grok ACP completion with no
-  text, thought, or tool update is now treated as a recoverable agent failure
-  instead of reporting `Done · no text output`.
-
-## [2.2.3] - 2026-07-13
+## [Unreleased]
+
+## [2.3.0] - 2026-07-17
+
+### Added
+
+- **⚡ Instant project switch.** Choosing a project no longer waits on ACP
+  `session/new`. The bot switches cwd immediately and creates the live session
+  lazily on the first message. Reuses an existing controlled runtime for the
+  same path when available.
+- **🖼 Image-output prompt rules.** When agent image return is enabled, prompts
+  include rules to keep generated files in the Grok session media folder
+  (`images/` / `assets/`) or project `images/`, and to report absolute paths.
+
+### Fixed
+
+- **🖼 Agent images as Telegram files.** Generated images are sent with
+  `sendDocument` (downloadable file) instead of compressed `sendPhoto`. Discovery
+  now scans Grok session `images/` **and** `assets/`, plus project `images/` and
+  tool/text paths (Imagine was writing under `images/` while the bot only scanned
+  `assets/`).
+- **⏱ Stale callback queries.** Callback answers are safe/idempotent; expired
+  Telegram query IDs no longer spam ERROR logs. Handlers answer before slow ACP
+  work (stop / model / agent / project open).
+- **🎙 Voice requires STT again.** Voice / audio / video notes only work when
+  `STT_API_URL` is set (optional `STT_API_KEY`). Without STT the bot replies that
+  voice isn't configured — the CLI cannot accept ACP audio blocks.
+- **🔄 Non-blocking session handoff.** Backgrounding a session no longer waits
+  on streamer finalize / `prepare()` mid-switch, so the bot stays responsive.
+
+## [2.2.4] - 2026-07-16
+
+### Fixed
+
+- **🚫 Rotate immediately on Grok access denial.** API `403 Forbidden` / `Access
+  denied` responses now bypass same-account retry backoff, mark the failed
+  login with `⚠️`, and rotate to the next eligible saved account. If the active
+  host login was not already saved (for example after an external sign-in or
+  token refresh), it is captured first so the warning is visible and persists.
+- **🔐 Isolated Grok Telegram identity.** The Grok bot now takes its Telegram
+  token from its own instance `.env` before considering an inherited process
+  environment value. This prevents a machine-wide token for a sibling bot from
+  making Grok poll as Codex/Kiro/OpenCode and causing Telegram conflicts.
+- **⚠️ Persistent account warnings.** Account access/quota failures are shown
+  in `/accounts`, excluded from later automatic rotations, and can be manually
+  re-enabled after the account is repaired.
+- **🛟 No false success for silent ACP turns.** A Grok ACP completion with no
+  text, thought, or tool update is now treated as a recoverable agent failure
+  instead of reporting `Done · no text output`.
+
+## [2.2.3] - 2026-07-13
 
 ### Fixed
 
@@ -733,6 +761,9 @@ from a single chat and switch between them, on a redesigned, compact menu.
   diffs, MarkdownV2 rendering, scheduled tasks, multi-image prompts, and a
   cross-platform 24/7 background service.
 
+[2.3.0]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.3.0
+[2.2.4]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.2.4
+[2.2.3]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.2.3
 [2.2.2]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.2.2
 [2.2.1]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.2.1
 [2.2.0]: https://github.com/artickc/grok-telegram-bot/releases/tag/v2.2.0

package/README.md

@@ -275,16 +275,25 @@ caption. The bot downloads them and attaches them all to the prompt as image
 content blocks, so the agent can analyze them together. Images sent while Grok
 is busy are queued with your next turn.
 
-**Images come back too:** when the agent produces images during a turn (e.g.
-takes screenshots while testing an app), the bot detects the freshly-written
-files and sends them back to Telegram automatically (`SEND_AGENT_IMAGES`).
+**Images come back too:** when the agent produces images during a turn — Imagine
+`image_gen` / `image_edit` (written under
+`~/.grok/sessions/<cwd>/<session>/images/` and `…/assets/`), screenshots, or
+files under `<project>/images/` — the bot detects the freshly-written files and
+sends them back to Telegram as **downloadable documents** (`SEND_AGENT_IMAGES`,
+default on). Prompts also include image-output rules so the agent keeps gens in
+the session media folder and reports absolute paths.
 
 ## 🎙 Sending voice
 
-Send a voice note (or audio file) and the bot transcribes it and runs it as a
-prompt. Configure any OpenAI/Whisper-compatible endpoint via `STT_API_URL` in
-`.env`; leave `STT_LANGUAGE` blank for automatic detection (English, Russian,
-Romanian/Moldovan, and ~100 more).
+Send a voice note, audio file, or video note and the bot runs it as a prompt
+**only when STT is configured**.
+
+Set any OpenAI/Whisper-compatible endpoint via `STT_API_URL` (and `STT_API_KEY`
+if needed). The bot transcribes, shows the quote, and submits plain text.
+Without `STT_API_URL`, voice is rejected with a short “not configured” message
+— Grok Build CLI rejects ACP `audio` content blocks, so raw audio cannot be
+heard by the agent. Leave `STT_LANGUAGE` blank for automatic detection
+(English, Russian, Romanian/Moldovan, and ~100 more).
 
 ## 📎 Sending files
 
@@ -530,7 +539,8 @@ user. See [SECURITY.md](./SECURITY.md) for the full model.
 - [x] Multi-image prompts (albums)
 - [x] Combined, throttled output (anti-spam)
 - [x] 24/7 cross-platform background service
-- [x] Voice messages → speech-to-text → prompt (multi-language)
+- [x] Voice messages → STT (`STT_API_URL`) → text prompt (disabled without STT)
+- [x] Agent-generated images → Telegram document files (session `images/`/`assets/`)
 - [x] Context-usage % in the status panel
 - [x] Inline approvals — approve/deny risky tools from buttons (non trust-all mode)
 - [x] Session auto-approve + pinned permission prompts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grok-telegram-bot",
-  "version": "2.2.4",
+  "version": "2.3.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/stt.ts

@@ -1,9 +1,12 @@
 /**
  * Speech-to-text via any OpenAI/Whisper-compatible endpoint.
  *
+ * Required for Telegram voice / audio / video notes: Grok Build CLI over ACP
+ * does not accept audio content blocks, so without STT_API_URL the bot rejects
+ * voice with a "not configured" message instead of attaching unusable audio.
+ *
  * Language handling: when STT_LANGUAGE is unset, Whisper auto-detects the
- * spoken language (covers English, Russian, Romanian/Moldovan, and ~100 more),
- * so multilingual voice notes work out of the box.
+ * spoken language (covers English, Russian, Romanian/Moldovan, and ~100 more).
  */
 import { createLogger } from "../logger.js";
 

package/src/app/types.ts

@@ -37,10 +37,24 @@ export interface PromptImage {
   mimeType: string;
 }
 
-/** A unit of work submitted to the agent: text plus optional images. */
+/**
+ * A file the agent can open (ACP `resource_link`). Used for voice notes and
+ * other binaries when we cannot embed the media as a first-class content type
+ * (Grok CLI currently rejects ACP `audio` blocks).
+ */
+export interface PromptResourceLink {
+  uri: string;
+  name: string;
+  mimeType?: string;
+  size?: number;
+}
+
+/** A unit of work submitted to the agent: text plus optional images / links. */
 export interface PromptInput {
   text: string;
   images: PromptImage[];
+  /** Optional file references (voice notes, binaries). */
+  resourceLinks?: PromptResourceLink[];
   /** Telegram message id of the prompt, so the reply threads to it. */
   replyTo?: number;
   /**
@@ -52,5 +66,5 @@ export interface PromptInput {
 }
 
 export function textPrompt(text: string, replyTo?: number, quotedText?: string): PromptInput {
-  return { text, images: [], replyTo, quotedText };
+  return { text, images: [], resourceLinks: [], replyTo, quotedText };
 }

package/src/bot/bot.ts

@@ -20,6 +20,7 @@ import { TaskRunner } from "../tasks/runner.js";
 import { Scheduler } from "../tasks/scheduler.js";
 import { TaskStore } from "../tasks/store.js";
 import { createAuthMiddleware } from "./auth.js";
+import { isStaleCallbackError, safeCallbackMiddleware } from "./callback.js";
 import { COMMANDS } from "./commands.js";
 import { type BotDeps, MenuCache } from "./deps.js";
 import { registerControl } from "./handlers/control.js";
@@ -139,6 +140,9 @@ export async function createBot(cfg: AppConfig, acp: GrokClient): Promise<BotBun
   bot.on("message:pinned_message", (ctx) => void ctx.deleteMessage().catch(() => {}));
 
   bot.use(createAuthMiddleware(cfg));
+  // Answer callback queries safely: never throw on stale IDs, auto-answer if a
+  // handler forgets (prevents the loading spinner + unhandled 400 noise).
+  bot.use(safeCallbackMiddleware());
 
   // Keep history clean: after handling, delete the user's command (/…) and
   // persistent-bar button taps. Plain prompts and wizard input are kept.
@@ -188,6 +192,12 @@ export async function createBot(cfg: AppConfig, acp: GrokClient): Promise<BotBun
   registerMessages(bot, deps); // catch-all text prompt — keep last
 
   bot.catch((err) => {
+    // Stale callback answers are expected when the bot was busy past Telegram's
+    // ~timeout — middleware already swallows most of them; keep noise out of ERROR.
+    if (isStaleCallbackError(err.error)) {
+      log.debug("stale callback query:", err.error instanceof Error ? err.error.message : err.error);
+      return;
+    }
     log.error("unhandled bot error:", err.error instanceof Error ? err.error.message : err.error);
   });
 

package/src/bot/callback.ts

@@ -0,0 +1,74 @@
+/**
+ * Callback-query helpers — Telegram requires answerCallbackQuery within a few
+ * seconds of the tap. Stale/expired IDs throw 400; without a catch those become
+ * unhandled bot errors and the client spinner never clears.
+ */
+import { type Context, type MiddlewareFn, GrammyError } from "grammy";
+
+/** True when Telegram rejected the answer because the query expired or is invalid. */
+export function isStaleCallbackError(err: unknown): boolean {
+  if (!(err instanceof GrammyError)) return false;
+  if (err.error_code !== 400 && err.error_code !== 440) return false;
+  return /query is too old|query ID is invalid|response timeout expired/i.test(err.description);
+}
+
+type AnswerParams = Parameters<Context["answerCallbackQuery"]>[0];
+
+/**
+ * Idempotent, non-throwing answer for a single handler (when middleware is not
+ * in play). Safe to call after slow work — stale queries are swallowed.
+ */
+export async function safeAnswerCallbackQuery(ctx: Context, params?: AnswerParams): Promise<boolean> {
+  try {
+    await ctx.answerCallbackQuery(params);
+    return true;
+  } catch (err) {
+    if (isStaleCallbackError(err)) return false;
+    throw err;
+  }
+}
+
+/**
+ * Patch every callback update so:
+ *   1. answerCallbackQuery never throws on stale/expired query IDs,
+ *   2. double-answers are no-ops,
+ *   3. if a handler forgets to answer, we answer once in `finally` so the
+ *      client spinner always stops (best-effort; may already be too late).
+ */
+export function safeCallbackMiddleware(): MiddlewareFn<Context> {
+  return async (ctx, next) => {
+    if (!ctx.callbackQuery) {
+      await next();
+      return;
+    }
+
+    let answered = false;
+    const original = ctx.answerCallbackQuery.bind(ctx);
+
+    ctx.answerCallbackQuery = (async (params?: AnswerParams) => {
+      if (answered) return true;
+      answered = true;
+      try {
+        return await original(params);
+      } catch (err) {
+        if (isStaleCallbackError(err)) return true;
+        // Leave answered=true so a retry storm can't spam Telegram; surface
+        // unexpected errors to bot.catch for visibility.
+        throw err;
+      }
+    }) as Context["answerCallbackQuery"];
+
+    try {
+      await next();
+    } finally {
+      if (!answered) {
+        try {
+          await original();
+        } catch {
+          /* stale or network — spinner already gone */
+        }
+        answered = true;
+      }
+    }
+  };
+}

package/src/bot/chat-controller.ts

@@ -79,20 +79,69 @@ export class ChatController {
     }));
   }
 
-  /** Start a brand-new session and bring it to the foreground. */
+  /** Start a brand-new session and bring it to the foreground.
+   *  Always binds a live ACP session (`session/new`) — use {@link switchProject}
+   *  when you only need to change the working directory (instant). */
   async addNew(cwd: string, projectName?: string): Promise<SessionRuntime> {
     this.ensureRestored();
     const prevFg = this.fg;
     const rt = this.create({ cwd, projectName });
     this.runtimes.push(rt);
     this.fg = rt;
-    await this.background(prevFg);
+    // Fire-and-forget: finalizing the previous streamer must not block the new
+    // session bind (that was a major source of "bot freezes on switch").
+    void this.background(prevFg);
     await rt.startNewSession(cwd, projectName);
     this.markSeen(rt);
     this.persist();
     return rt;
   }
 
+  /**
+   * Switch the chat to a project directory **without** waiting on ACP.
+   * - Reuses an existing controlled runtime for the same path when possible.
+   * - Does **not** call `session/new` — the live session is created lazily on
+   *   the first prompt / prepare (via `ensureSession`).
+   * This keeps the project picker responsive even while another turn is running.
+   */
+  async switchProject(cwd: string, projectName?: string): Promise<SessionRuntime> {
+    this.ensureRestored();
+    const key = normPath(cwd);
+    const same = this.runtimes.filter((r) => normPath(r.cwd) === key);
+    // Prefer the current FG if it already points here, else the most recent match.
+    const existing = same.find((r) => r === this.fg) ?? same.at(-1);
+
+    if (existing) {
+      if (projectName) existing.projectName = projectName;
+      if (existing === this.fg) {
+        this.persist();
+        return existing;
+      }
+      if (existing.sessionId) {
+        // Fast path: switchTo no longer awaits ACP re-bind.
+        const sw = await this.switchTo(existing.sessionId);
+        return sw?.rt ?? existing;
+      }
+      void this.background(this.fg);
+      this.fg = existing;
+      await existing.setForeground(true);
+      this.persist();
+      return existing;
+    }
+
+    const prevFg = this.fg;
+    const rt = this.create({ cwd, projectName });
+    this.runtimes.push(rt);
+    this.fg = rt;
+    void this.background(prevFg);
+    // Drop other never-used project placeholders (no session yet) so rapid
+    // project browsing can't accumulate infinite idle runtimes/listeners.
+    this.pruneUnusedPlaceholders(rt);
+    // No startNewSession — sessionId stays undefined until the first message.
+    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.
@@ -114,7 +163,7 @@ export class ChatController {
     const rt = this.create({ cwd, projectName, sessionId });
     this.runtimes.push(rt);
     this.fg = rt;
-    await this.background(prevFg);
+    void this.background(prevFg);
     const result = await rt.attach(sessionId, cwd, projectName, priorEntries);
     this.markSeen(rt);
     this.persist();
@@ -131,8 +180,8 @@ export class ChatController {
     const rt = this.create({ cwd, projectName, sessionId });
     this.runtimes.push(rt);
     this.fg = rt;
-    await this.background(prevFg);
-    await rt.prepare().catch(() => {});
+    void this.background(prevFg);
+    // Lazy re-bind on first prompt (rebindPending); don't block the resume UI.
     const path = this.store.jsonlPath(sessionId);
     const unread = readHistory(path, 12);
     this.lastRead.set(sessionId, jsonlSize(path));
@@ -148,10 +197,12 @@ export class ChatController {
     if (rt === this.fg) {
       return { rt, sessionId, projectName: rt.projectName, busy: rt.isBusy, unread: [], firstView: false, alreadyForeground: true };
     }
-    await this.background(this.fg);
+    void this.background(this.fg);
     this.fg = rt;
     await rt.setForeground(true);
-    await rt.prepare().catch(() => {});
+    // Do NOT await prepare()/loadSession here — re-bind is lazy on the next
+    // prompt (rebindPending). Awaiting ACP mid-switch freezes the bot when the
+    // agent is busy with another turn.
 
     const path = this.store.jsonlPath(sessionId);
     const seen = this.lastRead.get(sessionId);
@@ -222,8 +273,23 @@ export class ChatController {
       seen.add(cs.sessionId);
       this.runtimes.push(this.create({ cwd: cs.projectPath, projectName: cs.projectName, sessionId: cs.sessionId }));
     }
+    // Lazy project switches persist projectPath without a sessionId. If the
+    // saved project is not among controlled sessions, recreate an unbound FG
+    // so a restart lands on the project the user last chose.
+    if (s.projectPath) {
+      const key = normPath(s.projectPath);
+      const hasProject = this.runtimes.some((r) => normPath(r.cwd) === key);
+      if (!hasProject) {
+        this.runtimes.push(this.create({ cwd: s.projectPath, projectName: s.projectName }));
+      }
+    }
     if (this.runtimes.length > 0) {
-      const fg = this.runtimes.find((r) => r.sessionId === s.foregroundSessionId) ?? this.runtimes[0]!;
+      let fg = this.runtimes.find((r) => r.sessionId && r.sessionId === s.foregroundSessionId);
+      if (!fg && s.projectPath) {
+        const key = normPath(s.projectPath);
+        fg = this.runtimes.find((r) => normPath(r.cwd) === key);
+      }
+      fg = fg ?? this.runtimes[0]!;
       for (const r of this.runtimes) void r.setForeground(r === fg);
       this.fg = fg;
     }
@@ -284,6 +350,17 @@ export class ChatController {
     await rt.setForeground(false);
   }
 
+  /** Remove idle runtimes that never bound an ACP session (lazy project taps). */
+  private pruneUnusedPlaceholders(keep: SessionRuntime): void {
+    for (let i = this.runtimes.length - 1; i >= 0; i--) {
+      const r = this.runtimes[i]!;
+      if (r === keep || r === this.fg) continue;
+      if (r.sessionId || r.isBusy) continue;
+      r.dispose();
+      this.runtimes.splice(i, 1);
+    }
+  }
+
   private markSeen(rt: SessionRuntime): void {
     if (rt.sessionId) this.lastRead.set(rt.sessionId, jsonlSize(this.store.jsonlPath(rt.sessionId)));
   }
@@ -315,3 +392,8 @@ export class ChatController {
     });
   }
 }
+
+/** Path key for project matching (case / separators / trailing slash). */
+function normPath(p: string): string {
+  return p.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+}

package/src/bot/handlers/menu.ts

@@ -56,8 +56,10 @@ export function registerMenu(bot: Bot, deps: BotDeps): void {
   bot.callbackQuery(/^agent:set:(\d+)$/, async (ctx) => {
     const mode = deps.acp.availableModes[Number(ctx.match![1])];
     if (!mode) return void ctx.answerCallbackQuery({ text: "Expired, tap Agent again." });
+    // Answer before ACP so a slow setMode never expires the callback query.
+    await ctx.answerCallbackQuery({ text: `\u{1F916} Agent: ${mode.name}` });
     await deps.registry.get(ctx.chat!.id).setAgentPref(mode.id);
-    await confirm(ctx, deps, `\u{1F916} Agent: ${mode.name}`);
+    await confirmUi(ctx, deps);
   });
 
   // ── Reasoning ──────────────────────────────────────────────────────────────
@@ -71,12 +73,17 @@ export function registerMenu(bot: Bot, deps: BotDeps): void {
   bot.callbackQuery(/^model:set:(\d+)$/, async (ctx) => {
     const entry = deps.acp.availableModels[Number(ctx.match![1])];
     if (!entry) return void ctx.answerCallbackQuery({ text: "Expired, tap Model again." });
+    await ctx.answerCallbackQuery({ text: `\u{1F9E9} Model: ${entry.name}` });
     const res = await deps.registry.get(ctx.chat!.id).setModelPref(entry.modelId);
-    await confirm(ctx, deps, res.ok ? `\u{1F9E9} Model: ${entry.name}` : `\u26A0\uFE0F Model set failed: ${res.error}`);
+    if (!res.ok) {
+      await ctx.reply(`\u26A0\uFE0F Model set failed: ${res.error}`).catch(() => {});
+    }
+    await confirmUi(ctx, deps);
   });
   bot.callbackQuery("model:clear", async (ctx) => {
+    await ctx.answerCallbackQuery({ text: "\u{1F9E9} Model: default" });
     await deps.registry.get(ctx.chat!.id).setModelPref("");
-    await confirm(ctx, deps, "\u{1F9E9} Model: default");
+    await confirmUi(ctx, deps);
   });
 }
 
@@ -143,15 +150,25 @@ async function dispatchMenu(ctx: Context, deps: BotDeps, action: string): Promis
       } catch (e) {
         return void ctx.reply(`\u274C ${(e as Error).message}`);
       }
-    case "stop":
-      return void ctx.answerCallbackQuery({ text: (await rt.cancel()) ? "Cancelling\u2026" : "Nothing is running" });
+    case "stop": {
+      // Answer first so a slow cancel never times out the callback query.
+      await ctx.answerCallbackQuery({ text: rt.isBusy ? "Cancelling\u2026" : "Nothing is running" });
+      if (rt.isBusy) await rt.cancel();
+      return;
+    }
     default:
       return void ctx.answerCallbackQuery();
   }
 }
 
 async function confirm(ctx: Context, deps: BotDeps, text: string): Promise<void> {
+  // Toast first (callback must be answered within ~seconds), then UI updates.
   await ctx.answerCallbackQuery({ text });
+  await confirmUi(ctx, deps);
+}
+
+/** Refresh status + reopen the main menu after a preference change. */
+async function confirmUi(ctx: Context, deps: BotDeps): Promise<void> {
   try {
     await ctx.deleteMessage();
   } catch {

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

@@ -7,8 +7,8 @@
 import { basename } from "node:path";
 import { type Api, InlineKeyboard } from "grammy";
 import {
-  type GrokClient,
-  isAccountRotationError,
+  type GrokClient,
+  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,
@@ -99,10 +100,10 @@ export class SessionRuntime {
   private turnCount = 0;
   /** Telegram message id of the current turn's prompt, so replies thread to it. */
   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 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;
@@ -216,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();
@@ -514,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;
@@ -670,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,18 +698,18 @@ export class SessionRuntime {
     input: PromptInput,
     final: { result?: PromptResult; error?: Error; attempts: number },
   ): 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 }[]);
+    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;
 
     const transcript = this.sessionId ? recentTranscript(this.cfg.sessionsDir, this.sessionId) : undefined;
@@ -736,25 +742,26 @@ 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}` +
-          (isAccountRotationError(failReason) ? " (previous account unavailable)" : ""),
+          (isAccountRotationError(failReason) ? " (previous account unavailable)" : ""),
       );
       // runPromptWithRetries already skips backoff for 402 / balance exhausted.
       last = await this.runPromptWithRetries(content);
-      if (last.result && !this.cancelled) {
+      if (last.result && !this.cancelled) {
         if (this.foreground) {
           await this.notify(`\u2705 Recovered on ${t.label}.`, { replyTo: this.turnReplyTo });
         }
         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"}`);
+      }
+      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"}`);
     }
 
     // One full cycle done and still failing — stop with a combined report.
@@ -776,21 +783,21 @@ export class SessionRuntime {
   ): Promise<{ result?: PromptResult; error?: Error; attempts: number }> {
     const delays = this.cfg.promptRetryAttempts > 0 ? backoffSchedule(this.cfg.promptRetryAttempts) : [];
     const totalAttempts = delays.length + 1;
-    let attempt = 0;
-    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 };
+    let attempt = 0;
+    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;
         const canRecover = !this.cancelled && !(this.streamer?.hasOutput ?? false);
@@ -803,7 +810,7 @@ export class SessionRuntime {
           attempt <= delays.length &&
           canRecover &&
           !forkInstead &&
-          !isAccountRotationError(error) &&
+          !isAccountRotationError(error) &&
           isTransientError(error);
         if (!willRetry) return { error, attempts: attempt };
         const waitMs = delays[attempt - 1]!;
@@ -859,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,
     });
 
@@ -888,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 */
     }
@@ -980,10 +997,10 @@ export class SessionRuntime {
     void this.runTurn(batch);
   }
 
-  private onUpdate(sessionId: string, update: SessionUpdate): void {
-    if (!this.busy || sessionId !== this.sessionId) return;
-    this.sessionUpdateCount++;
-    const kind = update.sessionUpdate;
+  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
     // session is in the background (its output isn't streamed here, but the
@@ -991,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/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";
@@ -728,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 };
 }

package/src/render/image-output.ts

@@ -0,0 +1,12 @@
+/**
+ * Prompt appendix so the agent keeps generated images in the session media
+ * folder and mentions absolute paths (the bot delivers those as Telegram files).
+ *
+ * Keep tidy-idempotent (no trailing spaces / 3+ blank lines) so
+ * `cleanStoredText` can strip it by exact match after extractProgress/tidy.
+ */
+export const IMAGE_OUTPUT_DIRECTIVE = [
+  "IMAGE OUTPUT RULES:",
+  "When generating images (image_gen / image_edit) or saving image files, write them under the current Grok session media folder (session images/ or assets/) or the project images/ directory — not random temp locations.",
+  "Always mention the absolute path of each image file you create in your reply so the client can deliver it as a downloadable Telegram file.",
+].join("\n");

package/src/sessions/history.ts

@@ -3,6 +3,7 @@
  * Reads only the tail of large logs to stay fast.
  */
 import { closeSync, openSync, readSync, statSync } from "node:fs";
+import { IMAGE_OUTPUT_DIRECTIVE } from "../render/image-output.js";
 import { extractProgress, PROGRESS_DIRECTIVE } from "../render/progress.js";
 import type { HistoryEntry, HistoryRole } from "./types.js";
 
@@ -161,6 +162,7 @@ function cleanStoredText(text: string): string {
   if (!text) return text;
   let t = extractProgress(text).cleaned;
   if (t.includes(PROGRESS_DIRECTIVE)) t = t.split(PROGRESS_DIRECTIVE).join("").trim();
+  if (t.includes(IMAGE_OUTPUT_DIRECTIVE)) t = t.split(IMAGE_OUTPUT_DIRECTIVE).join("").trim();
   return t;
 }