alvin-bot 4.9.2 → 4.9.3

package/CHANGELOG.md

@@ -2,6 +2,42 @@
 
 All notable changes to Alvin Bot are documented here.
 
+## [4.9.3] — 2026-04-11
+
+### 🛠 Two UX bugs found in production after v4.9.2 — now closed
+
+Ali triggered `/cron run Daily Job Alert` after the v4.9.2 deploy and saw 13 minutes of chat silence followed by nothing. Forensics on the live bot revealed two distinct problems on top of an already-successful run:
+
+**1. `subagent-delivery` has been silently dropping every banner for days.** Err.log: `GrammyError: Call to 'sendMessage' failed! (400: Bad Request: can't parse entities: Can't find end of the entity starting at byte offset 2636)`. The daily-job-alert sub-agent produces markdown-dense output (`|` tables, `**bold**`, `\|` escapes, mixed asterisks). Telegram's Markdown parser refuses it, `api.sendMessage(..., parse_mode: "Markdown")` throws, and the bare try/catch in `deliverSubAgentResult` logs + bails. **Result: the user has never seen a sub-agent-delivery banner, even when the underlying run succeeded perfectly and emailed the HTML report correctly.**
+
+Fix in `src/services/subagent-delivery.ts`: new `sendWithMarkdownFallback()` helper that detects the "can't parse entities" pattern and retries the SAME text without `parse_mode`. All three code paths (file-upload case, single-message case, chunked case) now flow through the helper. 3 new tests drive the happy path, non-parse errors, and the chunked path.
+
+**2. `/cron run` had zero proof-of-life for 13 minutes.** The handler used to `await runJobNow(...)` synchronously and reply only when finished. Telegram's typing indicator expires after 5s. Users saw: command sent → typing indicator blip → nothing → nothing → (much later, if at all) result. For cron jobs that take 10-15 min (daily job alert, Perseus health, Polyseus P&L), this is indistinguishable from a dead bot.
+
+Fix — new handler flow:
+
+```
+bot:  🚀 Started *Daily Job Alert* — working…          ← instant ack
+bot:  🔄 Running *Daily Job Alert* · 1m 0s elapsed…    ← edit every 60s
+bot:  🔄 Running *Daily Job Alert* · 2m 0s elapsed…    ← edit
+...
+bot:  ✅ Done — *Daily Job Alert* · 13m 17s             ← final edit
+bot:  ✅ *Daily Job Alert* completed · 13m · 2.6M/28k  ← subagent-delivery
+       [full report body, Markdown-safe with plain-text fallback]
+```
+
+The ticker uses a single `editMessageText` call per minute on the same message — zero notification spam, clean visual progress. Every edit is wrapped with `isHarmlessTelegramError` so the inevitable "message is not modified" races stay silent. The ack itself falls back to plain text if the first `reply` hits a parse error, and the final edit falls back to a fresh plain message if the edit fails.
+
+New module: `src/handlers/cron-progress.ts` with pure helpers — `formatElapsed`, `escapeMarkdown`, `buildTickerText`, `buildDoneText`. 8 tests cover the formatting rules and markdown-safety escapes so future cron jobs with weird names (`weird_job*name`) can't break the ticker.
+
+**186 tests total** (+11 new). All green. Timeouts remain unlimited.
+
+**What you see after this upgrade:**
+- Instant "🚀 Started" ack on `/cron run`
+- Live elapsed-time ticker every minute
+- Final "✅ Done" when the sub-agent finishes
+- A separate banner+body message with the full report — **this time actually delivered**, even when the body contains broken Markdown
+
 ## [4.9.2] — 2026-04-11
 
 ### 🔍 Post-review polish: three edge cases from the strict audit

package/dist/handlers/commands.js

@@ -16,6 +16,9 @@ import { getMCPStatus, getMCPTools, callMCPTool } from "../services/mcp.js";
 import { listCustomTools, executeCustomTool } from "../services/custom-tools.js";
 import { screenshotUrl, extractText, generatePdf, hasPlaywright } from "../services/browser.js";
 import { listJobs, createJob, deleteJob, toggleJob, runJobNow, formatNextRun, humanReadableSchedule } from "../services/cron.js";
+import { resolveJobByNameOrId } from "../services/cron-resolver.js";
+import { buildTickerText, buildDoneText, escapeMarkdown } from "./cron-progress.js";
+import { isHarmlessTelegramError } from "../util/telegram-error-filter.js";
 import { storePassword, revokePassword, getSudoStatus, verifyPassword } from "../services/sudo.js";
 import { config } from "../config.js";
 import { BOT_VERSION } from "../version.js";
@@ -1442,11 +1445,25 @@ export function registerCommands(bot) {
             return;
         }
         // /cron run <name-or-id>
+        //
+        // UX contract:
+        //   1. Instantly post a "🚀 Started …" message so the user knows
+        //      the command was received.
+        //   2. Every 60s edit that message with the elapsed-time ticker
+        //      so the chat shows proof-of-life during 10+ min sub-agent
+        //      runs (the Daily Job Alert takes ~13 min in production).
+        //   3. When runJobNow returns, edit the same message into a
+        //      final "✅ Done" / "❌ error" / "⏳ already running" state.
+        //   4. The heavy lifting (banner + full body + chunking) stays in
+        //      subagent-delivery.ts — which now has a Markdown→plain-text
+        //      fallback so it actually reaches the user.
         if (arg.startsWith("run ")) {
             const nameOrId = arg.slice(4).trim();
-            await ctx.api.sendChatAction(ctx.chat.id, "typing");
-            const outcome = await runJobNow(nameOrId);
-            if (outcome.status === "not-found") {
+            // Resolve up-front so we can show the real job name in the
+            // "Started" ack, and so we handle the not-found case BEFORE
+            // spending a Telegram round-trip on a pointless placeholder.
+            const resolved = resolveJobByNameOrId(listJobs(), nameOrId);
+            if (!resolved) {
                 const jobs = listJobs();
                 const hint = jobs.length > 0
                     ? `\n\nAvailable:\n${jobs.slice(0, 10).map(j => `• ${j.name}`).join("\n")}`
@@ -1454,15 +1471,80 @@ export function registerCommands(bot) {
                 await ctx.reply(`❌ No job matches <code>${nameOrId}</code>.${hint}`, { parse_mode: "HTML" });
                 return;
             }
-            if (outcome.status === "already-running") {
-                await ctx.reply(`⏳ Job "${outcome.job.name}" is already running — not starting a duplicate. ` +
-                    `Wait for the current run to finish, or /subagents cancel to abort it.`);
-                return;
+            const jobName = resolved.name;
+            const startedAt = Date.now();
+            // Post initial ack — we'll edit THIS message for the ticker and
+            // the final state.
+            let ackMessageId = null;
+            try {
+                const ack = await ctx.reply(`🚀 Started *${escapeMarkdown(jobName)}* — working…`, { parse_mode: "Markdown" });
+                ackMessageId = ack.message_id;
+            }
+            catch (err) {
+                // If even the initial ack fails, fall back to plain text so
+                // the user still knows we received the command.
+                try {
+                    const ack = await ctx.reply(`🚀 Started ${jobName} — working…`);
+                    ackMessageId = ack.message_id;
+                }
+                catch { /* give up on the ack — run still fires below */ }
+            }
+            const chatId = ctx.chat.id;
+            // Progress ticker: edit the ack message with elapsed time every
+            // 60s. Errors from editMessageText (including the harmless
+            // "message is not modified") are swallowed via the central filter.
+            const ticker = setInterval(async () => {
+                if (ackMessageId === null)
+                    return;
+                const elapsed = Math.floor((Date.now() - startedAt) / 1000);
+                try {
+                    await ctx.api.editMessageText(chatId, ackMessageId, buildTickerText(jobName, elapsed), { parse_mode: "Markdown" });
+                }
+                catch (err) {
+                    if (!isHarmlessTelegramError(err)) {
+                        console.warn(`[cron:run] ticker edit failed:`, err);
+                    }
+                }
+            }, 60_000);
+            let outcome;
+            try {
+                outcome = await runJobNow(nameOrId);
+            }
+            finally {
+                clearInterval(ticker);
+            }
+            // Final state — edit the ack message one last time.
+            const elapsed = Math.floor((Date.now() - startedAt) / 1000);
+            const finalText = (() => {
+                if (outcome.status === "not-found") {
+                    // Shouldn't happen — we already resolved successfully above —
+                    // but handle it for completeness.
+                    return `❌ ${escapeMarkdown(jobName)} — not found (race?)`;
+                }
+                if (outcome.status === "already-running") {
+                    return buildDoneText(outcome.job.name, elapsed, { ok: true, skipped: true });
+                }
+                return buildDoneText(outcome.job.name, elapsed, {
+                    ok: !outcome.error,
+                    error: outcome.error,
+                });
+            })();
+            if (ackMessageId !== null) {
+                try {
+                    await ctx.api.editMessageText(chatId, ackMessageId, finalText, { parse_mode: "Markdown" });
+                }
+                catch (err) {
+                    if (!isHarmlessTelegramError(err)) {
+                        // Last-ditch fallback: post as a new plain message so the
+                        // user sees the result even if the edit failed.
+                        await ctx.reply(finalText).catch(() => { });
+                    }
+                }
+            }
+            else {
+                // We never got an ack message id — just post fresh
+                await ctx.reply(finalText, { parse_mode: "Markdown" }).catch(() => ctx.reply(finalText));
             }
-            const output = outcome.output
-                ? `\`\`\`\n${outcome.output.slice(0, 2000)}\n\`\`\``
-                : "(no output)";
-            await ctx.reply(`🔧 Job "${outcome.job.name}" executed:\n${output}${outcome.error ? `\n\n❌ ${outcome.error}` : ""}`, { parse_mode: "Markdown" });
             return;
         }
         await ctx.reply("Unknown cron command. Use /cron for help.");

package/dist/handlers/cron-progress.js

@@ -0,0 +1,52 @@
+/**
+ * Pure helpers for the /cron run progress ticker.
+ *
+ * Separated from commands.ts so the formatting and safety rules can be
+ * unit-tested without standing up the entire grammy Context. The command
+ * handler wires these into a setInterval that edits a single Telegram
+ * message once per tick, giving the user visible proof-of-life during
+ * long-running (10+ min) cron jobs.
+ *
+ * See test/cron-progress-ticker.test.ts for the contract.
+ */
+/** Human-readable elapsed time — adapts unit to magnitude. */
+export function formatElapsed(seconds) {
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    const remSec = seconds % 60;
+    if (minutes < 60)
+        return `${minutes}m ${remSec}s`;
+    const hours = Math.floor(minutes / 60);
+    const remMin = minutes % 60;
+    return `${hours}h ${remMin}m`;
+}
+/**
+ * Escape Markdown-breaking characters in untrusted display strings so
+ * an edit-message call can safely use `parse_mode: Markdown` without
+ * triggering "can't parse entities" — the exact bug that killed every
+ * daily-job-alert banner for days.
+ *
+ * We use Telegram Markdown (v1) escape rules: only `*`, `_`, `[`, `` ` ``.
+ * The rest flow through unchanged.
+ */
+export function escapeMarkdown(text) {
+    return text.replace(/([*_[\]`])/g, "\\$1");
+}
+/** Intermediate ticker text: "🔄 Running *name* · 2m 5s elapsed…" */
+export function buildTickerText(jobName, elapsedSeconds) {
+    const safe = escapeMarkdown(jobName);
+    return `🔄 Running *${safe}* · ${formatElapsed(elapsedSeconds)} elapsed…`;
+}
+/** Final ticker state: "✅ Done — *name* · 13m 17s" (or ❌ / ⏳). */
+export function buildDoneText(jobName, elapsedSeconds, outcome) {
+    const safe = escapeMarkdown(jobName);
+    if (outcome.skipped) {
+        return `⏳ *${safe}* is already running — not starting a duplicate`;
+    }
+    if (!outcome.ok) {
+        const errLine = outcome.error ? `\n\n${outcome.error.slice(0, 500)}` : "";
+        return `❌ *${safe}* — ${formatElapsed(elapsedSeconds)}${errLine}`;
+    }
+    return `✅ Done — *${safe}* · ${formatElapsed(elapsedSeconds)}`;
+}

package/dist/services/subagent-delivery.js

@@ -10,6 +10,35 @@
  * module with a fake bot via __setBotApiForTest.
  */
 import { getVisibility } from "./subagents.js";
+/**
+ * Telegram's Markdown parser rejects unbalanced or unexpected entities
+ * (stray `*`, `_`, un-escaped `|` in tables, etc.). Sub-agent outputs
+ * mix all of these. When we hit one of these errors, retry the same
+ * content as plain text so the user still sees the result instead of
+ * a silent drop.
+ */
+function isTelegramParseError(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const e = err;
+    const haystack = `${e.message ?? ""} ${e.description ?? ""}`;
+    return /can't parse entities|can't find end of the entity/i.test(haystack);
+}
+/**
+ * Send a Markdown message with an automatic plain-text retry on parse
+ * errors. Any other error propagates to the caller's outer catch.
+ */
+async function sendWithMarkdownFallback(api, chatId, text) {
+    try {
+        await api.sendMessage(chatId, text, { parse_mode: "Markdown" });
+    }
+    catch (err) {
+        if (!isTelegramParseError(err))
+            throw err;
+        console.warn(`[subagent-delivery] Markdown parse failed, retrying as plain text`);
+        await api.sendMessage(chatId, text);
+    }
+}
 const MAX_TG_CHUNK = 3800; // below Telegram's 4096 limit with headroom
 const FILE_UPLOAD_THRESHOLD = 20_000; // switch to .md file upload above this
 let injectedApi = null;
@@ -243,7 +272,7 @@ export async function deliverSubAgentResult(info, result, opts = {}) {
     try {
         // Case 1: very long output → file upload with a short banner
         if (body.length > FILE_UPLOAD_THRESHOLD) {
-            await api.sendMessage(info.parentChatId, banner, { parse_mode: "Markdown" });
+            await sendWithMarkdownFallback(api, info.parentChatId, banner);
             try {
                 const { InputFile } = await import("grammy");
                 const buf = Buffer.from(body, "utf-8");
@@ -257,12 +286,14 @@ export async function deliverSubAgentResult(info, result, opts = {}) {
         }
         // Case 2: fits in a single message → banner + body joined
         if (body.length + banner.length + 2 <= MAX_TG_CHUNK) {
-            await api.sendMessage(info.parentChatId, `${banner}\n\n${body}`, { parse_mode: "Markdown" });
+            await sendWithMarkdownFallback(api, info.parentChatId, `${banner}\n\n${body}`);
             return;
         }
         // Case 3: medium output → banner as its own message, body chunked
-        await api.sendMessage(info.parentChatId, banner, { parse_mode: "Markdown" });
+        await sendWithMarkdownFallback(api, info.parentChatId, banner);
         for (let i = 0; i < body.length; i += MAX_TG_CHUNK) {
+            // Body chunks are always sent as plain text — markdown across
+            // arbitrary chunk boundaries would be inconsistent anyway.
             await api.sendMessage(info.parentChatId, body.slice(i, i + MAX_TG_CHUNK));
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alvin-bot",
-  "version": "4.9.2",
+  "version": "4.9.3",
   "description": "Alvin Bot — Your personal AI agent on Telegram, WhatsApp, Discord, Signal, and Web.",
   "type": "module",
   "main": "dist/index.js",

package/test/cron-progress-ticker.test.ts

@@ -0,0 +1,76 @@
+/**
+ * Fix #15 (B) — /cron run must give visible feedback during long runs.
+ *
+ * Regression from production: a 13-minute Daily Job Alert run showed
+ * the user ZERO feedback between trigger time and completion. The
+ * sub-agent was actually working (and eventually succeeded), but the
+ * Telegram chat was silent for the whole duration.
+ *
+ * This test doesn't exercise grammy directly — it tests the pure
+ * helper that drives the live progress message so we can verify the
+ * formatting, cadence math, and safety edges in isolation.
+ */
+import { describe, it, expect } from "vitest";
+import { formatElapsed, buildTickerText, buildDoneText } from "../src/handlers/cron-progress.js";
+
+describe("formatElapsed (Fix #15B)", () => {
+  it("formats seconds under a minute", () => {
+    expect(formatElapsed(0)).toBe("0s");
+    expect(formatElapsed(45)).toBe("45s");
+    expect(formatElapsed(59)).toBe("59s");
+  });
+
+  it("formats minutes+seconds above a minute", () => {
+    expect(formatElapsed(60)).toBe("1m 0s");
+    expect(formatElapsed(61)).toBe("1m 1s");
+    expect(formatElapsed(125)).toBe("2m 5s");
+    expect(formatElapsed(797)).toBe("13m 17s"); // real prod duration
+  });
+
+  it("formats hours+minutes above 60m", () => {
+    expect(formatElapsed(3600)).toBe("1h 0m");
+    expect(formatElapsed(3660)).toBe("1h 1m");
+  });
+});
+
+describe("buildTickerText (Fix #15B)", () => {
+  it("shows job name and elapsed time in the running state", () => {
+    const text = buildTickerText("Daily Job Alert", 125);
+    expect(text).toContain("Daily Job Alert");
+    expect(text).toContain("2m 5s");
+    expect(text).toMatch(/🔄|running/i);
+  });
+
+  it("escapes markdown-breaking characters in the job name", () => {
+    // Underscores and asterisks in job names would otherwise break
+    // the Markdown edit and trigger "can't parse entities".
+    const text = buildTickerText("weird_job*name", 10);
+    expect(text).not.toContain("_job*"); // no raw unescaped asterisk
+    // We expect some form of escaping — back-slashes are fine
+    expect(text).toMatch(/weird/);
+  });
+});
+
+describe("buildDoneText (Fix #15B)", () => {
+  it("shows green check for a clean completion", () => {
+    const text = buildDoneText("Daily Job Alert", 797, { ok: true });
+    expect(text).toContain("✅");
+    expect(text).toContain("Daily Job Alert");
+    expect(text).toContain("13m 17s");
+  });
+
+  it("shows red cross and error excerpt for a failure", () => {
+    const text = buildDoneText("Daily Job Alert", 10, {
+      ok: false,
+      error: "Sub-agent cancelled: timeout",
+    });
+    expect(text).toContain("❌");
+    expect(text).toContain("timeout");
+  });
+
+  it("shows warning for an already-running skip", () => {
+    const text = buildDoneText("Daily Job Alert", 0, { ok: true, skipped: true });
+    expect(text).toContain("⏳");
+    expect(text).toMatch(/already running|in progress/i);
+  });
+});

package/test/subagent-delivery-markdown-fallback.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Fix #15 (A) — subagent-delivery must retry without parse_mode when
+ * Telegram rejects the Markdown entities.
+ *
+ * Real regression: Daily Job Alert banners have been silently failing
+ * with "Bad Request: can't parse entities: Can't find end of the entity"
+ * every single day since the subagent-delivery module shipped. The
+ * result text contains mixed `|`, `**`, `\|`, emoji, and asterisks that
+ * Telegram's Markdown parser chokes on. The code currently logs the
+ * error and drops the delivery, so the user never sees the banner.
+ *
+ * Contract: when `sendMessage(..., parse_mode: Markdown)` throws with
+ * the "can't parse entities" pattern, retry the SAME text WITHOUT
+ * `parse_mode`. Any other error still logs + bails.
+ *
+ * This file uses a minimal bot-api stub so we can drive both the happy
+ * path and the parse-error path deterministically.
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { deliverSubAgentResult, __setBotApiForTest } from "../src/services/subagent-delivery.js";
+import type { SubAgentInfo, SubAgentResult } from "../src/services/subagents.js";
+
+interface Sent {
+  chatId: number;
+  text: string;
+  parseMode?: string;
+}
+
+function makeInfo(overrides: Partial<SubAgentInfo> = {}): SubAgentInfo {
+  return {
+    id: "id-1",
+    name: "Daily Job Alert",
+    status: "completed",
+    startedAt: 0,
+    depth: 0,
+    source: "cron",
+    parentChatId: 42,
+    ...overrides,
+  };
+}
+
+function makeResult(output: string): SubAgentResult {
+  return {
+    id: "id-1",
+    name: "Daily Job Alert",
+    status: "completed",
+    output,
+    tokensUsed: { input: 1000, output: 200 },
+    duration: 60_000,
+  };
+}
+
+beforeEach(() => {
+  __setBotApiForTest(null);
+});
+
+describe("deliverSubAgentResult Markdown fallback (Fix #15)", () => {
+  it("retries without parse_mode when Telegram rejects entity parsing", async () => {
+    const sent: Sent[] = [];
+    let callCount = 0;
+
+    __setBotApiForTest({
+      sendMessage: async (chatId: number, text: string, opts?: Record<string, unknown>) => {
+        callCount++;
+        const parseMode = opts?.parse_mode as string | undefined;
+        // First call (Markdown) throws the real production error
+        if (callCount === 1 && parseMode === "Markdown") {
+          const err = Object.assign(
+            new Error("Call to 'sendMessage' failed! (400: Bad Request: can't parse entities: Can't find end of the entity starting at byte offset 2636)"),
+            {
+              description: "Bad Request: can't parse entities: Can't find end of the entity starting at byte offset 2636",
+              error_code: 400,
+            },
+          );
+          throw err;
+        }
+        sent.push({ chatId, text, parseMode });
+        return { message_id: 1 };
+      },
+      sendDocument: async () => ({}),
+    });
+
+    const info = makeInfo();
+    const result = makeResult("This **has** | broken markdown \\| entities that fail Markdown parsing");
+
+    await deliverSubAgentResult(info, result);
+
+    // Must have retried at least once WITHOUT parse_mode
+    const plainAttempt = sent.find((s) => s.parseMode === undefined);
+    expect(plainAttempt).toBeDefined();
+    expect(plainAttempt?.text).toContain("Daily Job Alert");
+    expect(plainAttempt?.text).toContain("broken markdown");
+  });
+
+  it("does NOT retry for non-parse errors (e.g. chat not found)", async () => {
+    let callCount = 0;
+    __setBotApiForTest({
+      sendMessage: async () => {
+        callCount++;
+        const err = Object.assign(new Error("Forbidden: bot was blocked by the user"), {
+          description: "Forbidden: bot was blocked by the user",
+          error_code: 403,
+        });
+        throw err;
+      },
+      sendDocument: async () => ({}),
+    });
+
+    await deliverSubAgentResult(makeInfo(), makeResult("some text"));
+
+    // Should have tried once and given up — no retry
+    expect(callCount).toBe(1);
+  });
+
+  it("chunked delivery also retries without parse_mode on parse errors", async () => {
+    const sent: Sent[] = [];
+    let callCount = 0;
+
+    __setBotApiForTest({
+      sendMessage: async (chatId: number, text: string, opts?: Record<string, unknown>) => {
+        callCount++;
+        const parseMode = opts?.parse_mode as string | undefined;
+        // First banner attempt fails — should retry without parse_mode
+        if (callCount === 1 && parseMode === "Markdown") {
+          const err = Object.assign(
+            new Error("400: Bad Request: can't parse entities"),
+            { description: "can't parse entities", error_code: 400 },
+          );
+          throw err;
+        }
+        sent.push({ chatId, text, parseMode });
+        return { message_id: callCount };
+      },
+      sendDocument: async () => ({}),
+    });
+
+    const info = makeInfo();
+    // Large body forces the chunked path
+    const result = makeResult("x".repeat(5000));
+
+    await deliverSubAgentResult(info, result);
+
+    // At least one plain-text delivery must have landed
+    expect(sent.length).toBeGreaterThan(0);
+    expect(sent.some((s) => s.parseMode === undefined)).toBe(true);
+  });
+});