grok-telegram-bot 2.4.0 → 2.6.0

package/src/forum/project-icon.ts

@@ -0,0 +1,142 @@
+/**
+ * Discover a best-effort project icon (favicon, web assets, MSIX/store logos).
+ * Used when creating forum topics: Telegram cannot set arbitrary topic avatars
+ * from files, so we pin the image inside the topic as a visual stand-in.
+ */
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { basename, extname, join } from "node:path";
+
+const IMAGE_EXT = new Set([".ico", ".png", ".jpg", ".jpeg", ".webp", ".svg", ".gif"]);
+
+const ROOT_CANDIDATES = [
+  "favicon.ico",
+  "favicon.png",
+  "favicon.svg",
+  "apple-touch-icon.png",
+  "apple-touch-icon-precomposed.png",
+  "logo.png",
+  "logo.svg",
+  "icon.png",
+  "icon.ico",
+  "app-icon.png",
+];
+
+const SUBDIR_CANDIDATES = [
+  ["public", "favicon.ico"],
+  ["public", "favicon.png"],
+  ["public", "apple-touch-icon.png"],
+  ["static", "favicon.ico"],
+  ["assets", "favicon.ico"],
+  ["assets", "favicon.png"],
+  ["assets", "logo.png"],
+  ["Assets", "StoreLogo.png"],
+  ["Assets", "Square44x44Logo.png"],
+  ["Assets", "Square150x150Logo.png"],
+  ["Assets", "LockScreenLogo.png"],
+  ["Images", "logo.png"],
+  ["images", "logo.png"],
+  ["images", "icon.png"],
+  ["src", "assets", "logo.png"],
+  ["src", "assets", "favicon.ico"],
+];
+
+/** Prefer larger / more “logo-like” MSIX asset names. */
+const MSIX_NAME_RE =
+  /StoreLogo|Square\d+x\d+Logo|Wide\d+x\d+Logo|BadgeLogo|AppList|logo|icon|favicon/i;
+
+/**
+ * Return the best absolute icon path for a project directory, or undefined.
+ */
+export function discoverProjectIcon(projectPath: string): string | undefined {
+  if (!projectPath || !existsSync(projectPath)) return undefined;
+
+  for (const rel of ROOT_CANDIDATES) {
+    const p = join(projectPath, rel);
+    if (isImageFile(p)) return p;
+  }
+  for (const parts of SUBDIR_CANDIDATES) {
+    const p = join(projectPath, ...parts);
+    if (isImageFile(p)) return p;
+  }
+
+  // MSIX / WinUI: scan Assets for logo-like files.
+  const assetsDir = join(projectPath, "Assets");
+  const fromAssets = pickBestImageInDir(assetsDir);
+  if (fromAssets) return fromAssets;
+
+  // Package.appxmanifest Logo="Assets\..."
+  const fromManifest = iconFromAppxManifest(projectPath);
+  if (fromManifest) return fromManifest;
+
+  // Store listing folders (common in this workspace).
+  for (const sub of ["StoreListing", "store-listing", "listing", "media"]) {
+    const hit = pickBestImageInDir(join(projectPath, sub));
+    if (hit) return hit;
+  }
+
+  return undefined;
+}
+
+function iconFromAppxManifest(projectPath: string): string | undefined {
+  const manifest = join(projectPath, "Package.appxmanifest");
+  if (!existsSync(manifest)) return undefined;
+  let xml: string;
+  try {
+    xml = readFileSync(manifest, "utf-8");
+  } catch {
+    return undefined;
+  }
+  // Logo="Assets\StoreLogo.png" or Logo="Assets/StoreLogo.png"
+  const re = /\b(?:Logo|Square\d+x\d+Logo|Wide\d+x\d+Logo|StoreLogo)\s*=\s*"([^"]+)"/gi;
+  let m: RegExpExecArray | null;
+  const candidates: string[] = [];
+  while ((m = re.exec(xml))) {
+    const rel = m[1]!.replace(/\\/g, "/");
+    candidates.push(join(projectPath, rel));
+  }
+  for (const p of candidates) {
+    if (isImageFile(p)) return p;
+  }
+  return undefined;
+}
+
+function pickBestImageInDir(dir: string): string | undefined {
+  let names: string[];
+  try {
+    names = readdirSync(dir);
+  } catch {
+    return undefined;
+  }
+  const scored: Array<{ path: string; score: number; size: number }> = [];
+  for (const name of names) {
+    const p = join(dir, name);
+    if (!isImageFile(p)) continue;
+    let size = 0;
+    try {
+      size = statSync(p).size;
+    } catch {
+      continue;
+    }
+    let score = 0;
+    if (MSIX_NAME_RE.test(name)) score += 50;
+    if (/StoreLogo/i.test(name)) score += 30;
+    if (/favicon/i.test(name)) score += 40;
+    if (extname(name).toLowerCase() === ".png") score += 5;
+    // Prefer mid-size icons over tiny badges / huge splash.
+    if (size > 2_000 && size < 500_000) score += 10;
+    scored.push({ path: p, score, size });
+  }
+  if (scored.length === 0) return undefined;
+  scored.sort((a, b) => b.score - a.score || b.size - a.size);
+  return scored[0]!.path;
+}
+
+function isImageFile(p: string): boolean {
+  if (!existsSync(p)) return false;
+  try {
+    if (!statSync(p).isFile()) return false;
+  } catch {
+    return false;
+  }
+  return IMAGE_EXT.has(extname(p).toLowerCase()) || basename(p).toLowerCase() === "favicon.ico";
+}

package/src/forum/thread.ts

@@ -0,0 +1,49 @@
+/** Telegram General forum topic id (always 1). */
+export const FORUM_GENERAL_THREAD_ID = 1;
+
+/**
+ * Batch/runtime key for a chat. Private chats use thread 0.
+ * Forum messages without message_thread_id are treated as General (1).
+ */
+export function batchKey(chatId: number, threadId: number | undefined, isForumGroup: boolean): string {
+  if (!isForumGroup) return `${chatId}:0`;
+  return `${chatId}:${threadId ?? FORUM_GENERAL_THREAD_ID}`;
+}
+
+/** Normalize forum thread id (undefined → General). */
+export function forumThreadId(threadId: number | undefined): number {
+  return threadId ?? FORUM_GENERAL_THREAD_ID;
+}
+
+/**
+ * True when this forum thread is the General manager topic.
+ * Only exact id `1` — do NOT treat private chats (undefined) as General.
+ * Callers should pass {@link forumThreadId} first when reading raw Telegram ids.
+ */
+export function isGeneralThread(threadId: number | undefined): boolean {
+  return threadId === FORUM_GENERAL_THREAD_ID;
+}
+
+/**
+ * Thread id for **outbound** Telegram API calls (`sendMessage`, `editMessage`, …).
+ *
+ * Critical: Bot API often rejects `message_thread_id: 1` for the General forum
+ * topic with "Bad Request: message thread not found". Omitting the field posts
+ * to General correctly. Real project topics (id > 1) must still pass the id.
+ *
+ * Inbound routing still uses {@link forumThreadId} (undefined → 1).
+ */
+export function outboundMessageThreadId(
+  threadId: number | undefined,
+): number | undefined {
+  if (threadId === undefined || threadId === FORUM_GENERAL_THREAD_ID) return undefined;
+  return threadId;
+}
+
+/** Extra object for send/edit: only includes message_thread_id when safe. */
+export function outboundThreadExtra(
+  threadId: number | undefined,
+): { message_thread_id?: number } {
+  const id = outboundMessageThreadId(threadId);
+  return id !== undefined ? { message_thread_id: id } : {};
+}

package/src/forum/topic-store.ts

@@ -0,0 +1,114 @@
+/**
+ * Persist forum topic ↔ project bindings under the bot data directory.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ForumTopicBinding, ForumTopicState, TopicKind } from "./types.js";
+
+export class TopicStore {
+  private readonly file: string;
+  private state: ForumTopicState;
+
+  constructor(dataDir: string, groupId: number) {
+    mkdirSync(dataDir, { recursive: true });
+    this.file = join(dataDir, `forum-topics-${groupId}.json`);
+    this.state = this.load(groupId);
+  }
+
+  get groupId(): number {
+    return this.state.groupId;
+  }
+
+  all(): ForumTopicBinding[] {
+    return Object.values(this.state.topics);
+  }
+
+  get(threadId: number): ForumTopicBinding | undefined {
+    return this.state.topics[String(threadId)];
+  }
+
+  upsert(binding: ForumTopicBinding): void {
+    this.state.topics[String(binding.threadId)] = { ...binding, updatedAt: Date.now() };
+    this.save();
+  }
+
+  bindProject(threadId: number, projectPath: string, name?: string, kind: TopicKind = "project"): ForumTopicBinding {
+    const prev = this.get(threadId);
+    const next: ForumTopicBinding = {
+      threadId,
+      name: name || prev?.name || basenamePath(projectPath),
+      kind,
+      projectPath,
+      iconPath: prev?.iconPath,
+      sessionId: prev?.sessionId,
+      updatedAt: Date.now(),
+    };
+    this.upsert(next);
+    this.clearPending(threadId);
+    return next;
+  }
+
+  markPending(threadId: number): void {
+    if (!this.state.pendingBind.includes(threadId)) {
+      this.state.pendingBind.push(threadId);
+      this.save();
+    }
+  }
+
+  isPending(threadId: number): boolean {
+    return this.state.pendingBind.includes(threadId);
+  }
+
+  clearPending(threadId: number): void {
+    this.state.pendingBind = this.state.pendingBind.filter((id) => id !== threadId);
+    this.save();
+  }
+
+  findByProjectPath(projectPath: string): ForumTopicBinding | undefined {
+    const key = norm(projectPath);
+    return this.all().find((t) => t.projectPath && norm(t.projectPath) === key);
+  }
+
+  findAiChat(): ForumTopicBinding | undefined {
+    return this.all().find((t) => t.kind === "ai_chat");
+  }
+
+  setLastSetup(): void {
+    this.state.lastSetupAt = Date.now();
+    this.save();
+  }
+
+  private load(groupId: number): ForumTopicState {
+    if (!existsSync(this.file)) {
+      return { groupId, topics: {}, pendingBind: [] };
+    }
+    try {
+      const raw = JSON.parse(readFileSync(this.file, "utf-8")) as Partial<ForumTopicState>;
+      return {
+        groupId: typeof raw.groupId === "number" ? raw.groupId : groupId,
+        topics: (raw.topics && typeof raw.topics === "object" ? raw.topics : {}) as Record<
+          string,
+          ForumTopicBinding
+        >,
+        pendingBind: Array.isArray(raw.pendingBind) ? raw.pendingBind.filter((n) => typeof n === "number") : [],
+        lastSetupAt: typeof raw.lastSetupAt === "number" ? raw.lastSetupAt : undefined,
+      };
+    } catch {
+      return { groupId, topics: {}, pendingBind: [] };
+    }
+  }
+
+  private save(): void {
+    writeFileSync(this.file, JSON.stringify(this.state, null, 2), "utf-8");
+  }
+}
+
+function norm(p: string): string {
+  return p.replace(/\\/g, "/").replace(/\/+$/, "").toLowerCase();
+}
+
+function basenamePath(p: string): string {
+  const n = p.replace(/\\/g, "/").replace(/\/+$/, "");
+  const i = n.lastIndexOf("/");
+  return i >= 0 ? n.slice(i + 1) : n;
+}

package/src/forum/types.ts

@@ -0,0 +1,29 @@
+/**
+ * Forum topic ↔ project mapping types (one Telegram forum group).
+ */
+
+export type TopicKind = "ai_chat" | "project" | "general" | "unbound";
+
+export interface ForumTopicBinding {
+  /** Telegram message_thread_id */
+  threadId: number;
+  /** Topic title when last seen / created */
+  name: string;
+  kind: TopicKind;
+  /** Absolute project path, or workspace for AI chat. Null when unbound. */
+  projectPath: string | null;
+  /** Best-effort icon file path (favicon / MSIX logo), if discovered. */
+  iconPath?: string;
+  /** Last Grok ACP session id bound to this topic (optional resume hint). */
+  sessionId?: string;
+  updatedAt: number;
+}
+
+export interface ForumTopicState {
+  groupId: number;
+  topics: Record<string, ForumTopicBinding>; // key = String(threadId)
+  /** Threads waiting for the user to provide a project path. */
+  pendingBind: number[];
+  /** Last successful auto-setup time (ms). */
+  lastSetupAt?: number;
+}

package/src/grok/client.ts

@@ -225,8 +225,14 @@ interface Pending {
   reject: (e: Error) => void;
   cleanup: () => void;
   method: string;
+  /** Set for in-flight `session/prompt` so cancel can target one session only. */
+  sessionId?: string;
 }
 
+/** How long we wait for the agent to honour `session/cancel` before force-completing
+ *  that session's prompt locally (other sessions are never touched). */
+export const CANCEL_FORCE_MS = 2_000;
+
 export declare interface GrokClient {
   on(e: "session-update", l: (sessionId: string, update: SessionUpdate) => void): this;
   on(e: "notification", l: (method: string, params: unknown) => void): this;
@@ -258,6 +264,10 @@ export class GrokClient extends EventEmitter {
   private readonly cwd = new Map<string, string>();
   /** Sessions with an in-flight prompt (drives "active"). */
   private readonly running = new Set<string>();
+  /** In-flight prompt request id per session (at most one prompt per session). */
+  private readonly promptReqBySession = new Map<string, number | string>();
+  /** Timers that force-complete a cancelled prompt if the agent is slow. */
+  private readonly cancelForceTimers = new Map<string, NodeJS.Timeout>();
   /** Accumulated assistant text per in-flight turn (flushed to the log on end). */
   private readonly assistantBuf = new Map<string, string>();
   private authMethodId?: string;
@@ -272,6 +282,12 @@ export class GrokClient extends EventEmitter {
   private subagents: SubagentInfo[] = [];
   private pendingStages: PendingStage[] = [];
   permissionHandler?: (params: RequestPermissionParams) => Promise<PermissionOutcome>;
+  /**
+   * Optional hook when a session is user-cancelled (e.g. cancel pending
+   * interactive permission prompts for that session — ACP requires cancelled
+   * outcomes). Must never kill the agent process.
+   */
+  onSessionCancel?: (sessionId: string) => void;
 
   constructor(private readonly opts: GrokClientOptions) {
     super();
@@ -440,8 +456,26 @@ export class GrokClient extends EventEmitter {
     return new Promise<PromptResult>((resolve, reject) => {
       const id = this.nextId++;
       const start = Date.now();
+      // Single-settlement guard: force-cancel, agent response, idle/max timeout,
+      // and failAllPending must never double-resolve/reject this promise.
+      let settled = false;
+      const settleResolve = (v: unknown): void => {
+        if (settled) return;
+        settled = true;
+        this.pending.delete(id);
+        this.finishPrompt(sessionId, id);
+        resolve(v as PromptResult);
+      };
+      const settleReject = (e: Error): void => {
+        if (settled) return;
+        settled = true;
+        this.pending.delete(id);
+        this.finishPrompt(sessionId, id);
+        reject(e);
+      };
       this.lastActivity.set(sessionId, start);
       this.running.add(sessionId);
+      this.promptReqBySession.set(sessionId, id);
       if (this.proc?.pid) this.slog.lock(sessionId, this.proc.pid);
       const userText = this.cleanUserText(content);
       this.slog.logUser(sessionId, userText);
@@ -451,48 +485,47 @@ export class GrokClient extends EventEmitter {
         if (title) this.slog.update(sessionId, { title });
       }
       const watch = setInterval(() => {
+        if (settled) {
+          clearInterval(watch);
+          return;
+        }
         const last = Math.max(this.lastActivity.get(sessionId) ?? start, this.lastActivityAny);
         const idle = Date.now() - last;
         const total = Date.now() - start;
         if (total > this.promptMaxMs) {
-          this.pending.delete(id);
-          this.finishPrompt(sessionId, id);
           clearInterval(watch);
+          // Settle first so cancel()'s force-complete no-ops (prompt already
+          // gone). Still notify the agent — never kill the shared process.
+          settleReject(new Error(`Prompt exceeded the ${Math.round(this.promptMaxMs / 60_000)}min cap`));
           void this.cancel(sessionId);
-          reject(new Error(`Prompt exceeded the ${Math.round(this.promptMaxMs / 60_000)}min cap`));
         } else if (idle > this.promptIdleMs) {
-          this.pending.delete(id);
-          this.finishPrompt(sessionId, id);
           clearInterval(watch);
+          settleReject(new Error(`No agent activity for ${Math.round(idle / 1000)}s — giving up`));
           void this.cancel(sessionId);
-          reject(new Error(`No agent activity for ${Math.round(idle / 1000)}s — giving up`));
         }
       }, 15_000);
       this.pending.set(id, {
-        resolve: (v) => {
-          this.finishPrompt(sessionId, id);
-          resolve(v as PromptResult);
-        },
-        reject: (e) => {
-          this.finishPrompt(sessionId, id);
-          reject(e);
-        },
+        resolve: settleResolve,
+        reject: settleReject,
         cleanup: () => clearInterval(watch),
         method: "session/prompt",
+        sessionId,
       });
       try {
         this.transport!.send({ jsonrpc: "2.0", id, method: "session/prompt", params: { sessionId, prompt: content } });
       } catch (e) {
         clearInterval(watch);
-        this.pending.delete(id);
-        this.finishPrompt(sessionId, id);
-        reject(e as Error);
+        settleReject(e as Error);
       }
     });
   }
 
   /** Clear the running/lock state for a finished turn and flush its transcript. */
-  private finishPrompt(sessionId: string, _id: number): void {
+  private finishPrompt(sessionId: string, id: number | string): void {
+    this.clearCancelForce(sessionId);
+    if (this.promptReqBySession.get(sessionId) === id) {
+      this.promptReqBySession.delete(sessionId);
+    }
     this.running.delete(sessionId);
     this.slog.unlock(sessionId);
     const buf = this.assistantBuf.get(sessionId);
@@ -500,12 +533,68 @@ export class GrokClient extends EventEmitter {
     this.assistantBuf.delete(sessionId);
   }
 
+  /**
+   * Cancel one session's in-flight turn only.
+   *
+   * - Sends ACP `session/cancel` (agent should respond with stopReason cancelled).
+   * - Notifies permission layer so pending interactive prompts get `cancelled`.
+   * - If the agent is slow/hung, force-completes **that session's** pending
+   *   prompt after {@link CANCEL_FORCE_MS} with `stopReason: "cancelled"`.
+   * - Never kills the shared agent process (that would stop every multiplexed
+   *   chat and look like "the bot died").
+   */
   async cancel(sessionId: string): Promise<void> {
+    try {
+      this.onSessionCancel?.(sessionId);
+    } catch (e) {
+      log.debug("onSessionCancel failed:", (e as Error).message);
+    }
     try {
       this.transport?.send({ jsonrpc: "2.0", method: "session/cancel", params: { sessionId } });
     } catch (e) {
-      log.debug("cancel failed:", (e as Error).message);
+      log.debug("cancel notify failed:", (e as Error).message);
     }
+    // Soft cancel only — do not killCurrent/stop. Schedule a session-scoped
+    // force-complete so a stuck agent cannot leave this chat busy forever.
+    this.scheduleCancelForce(sessionId);
+  }
+
+  private clearCancelForce(sessionId: string): void {
+    const t = this.cancelForceTimers.get(sessionId);
+    if (t) {
+      clearTimeout(t);
+      this.cancelForceTimers.delete(sessionId);
+    }
+  }
+
+  private scheduleCancelForce(sessionId: string): void {
+    this.clearCancelForce(sessionId);
+    if (!this.promptReqBySession.has(sessionId)) return;
+    const timer = setTimeout(() => {
+      this.cancelForceTimers.delete(sessionId);
+      this.forceCompleteCancelledPrompt(sessionId);
+    }, CANCEL_FORCE_MS);
+    // Don't keep the process alive solely for cancel force timers.
+    timer.unref?.();
+    this.cancelForceTimers.set(sessionId, timer);
+  }
+
+  /**
+   * Resolve a still-pending prompt for `sessionId` as cancelled. Other sessions'
+   * pending requests are left alone. Safe to call when nothing is pending.
+   * Idempotent: if the prompt already settled (agent responded, idle timeout,
+   * failAllPending), returns false without double-settling.
+   */
+  forceCompleteCancelledPrompt(sessionId: string): boolean {
+    const id = this.promptReqBySession.get(sessionId);
+    if (id === undefined) return false;
+    const p = this.pending.get(id);
+    if (!p || p.method !== "session/prompt" || p.sessionId !== sessionId) return false;
+    log.info(`force-completing cancelled prompt for session ${sessionId.slice(0, 8)} (agent slow or ignored cancel)`);
+    p.cleanup();
+    // settleResolve deletes pending + finishPrompt (single-settlement).
+    p.resolve({ stopReason: "cancelled" } satisfies PromptResult);
+    return true;
   }
 
   async setModel(sessionId: string, modelId: string): Promise<void> {
@@ -644,6 +733,8 @@ export class GrokClient extends EventEmitter {
     if (msg.id !== undefined && msg.id !== null && this.pending.has(msg.id) && msg.method === undefined) {
       const p = this.pending.get(msg.id)!;
       p.cleanup();
+      // Prompt settleResolve/settleReject also delete pending; generic request
+      // pending still needs delete here. Double-delete is a no-op on Map.
       this.pending.delete(msg.id);
       if (msg.error) p.reject(this.toGrokError(msg.error, p.method));
       else p.resolve(msg.result);
@@ -781,12 +872,17 @@ export class GrokClient extends EventEmitter {
   }
 
   private failAllPending(err: Error): void {
-    for (const [, p] of this.pending) {
+    for (const t of this.cancelForceTimers.values()) clearTimeout(t);
+    this.cancelForceTimers.clear();
+    // Snapshot first: prompt settleReject deletes from pending while iterating.
+    const pending = [...this.pending.values()];
+    this.pending.clear();
+    for (const p of pending) {
       p.cleanup();
       p.reject(err);
     }
-    this.pending.clear();
     this.running.clear();
+    this.promptReqBySession.clear();
   }
 
   private visibleText(content: ContentBlock[]): string {
@@ -810,20 +906,26 @@ 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))
+    // Prefer "User task (continued):" before plain "User task:" (continued
+    // contains that substring — lastIndexOf would leave "(continued):…").
+    const cont = "User task (continued):";
+    const ci = t.lastIndexOf(cont);
+    if (ci !== -1) {
+      t = t.slice(ci + cont.length);
+    } else if (
+      /^COMPLEXITY \(decide yourself/i.test(t) ||
+      /^TASK COMPLEXITY:/i.test(t)
     ) {
-      t = t.slice(ti + taskMarker.length);
+      const taskMarker = "User task:";
+      const ti = t.indexOf(taskMarker);
+      if (ti !== -1) 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 = "";
+    if (/^TELEGRAM BRIDGE RESULTS \(system/i.test(t.trim())) t = "";
     t = t.replace(/^\([^\n)]*\)\s*\n+/, "");
     return t.trim();
   }