@dreb/telegram 1.16.0

package/dist/config.js

@@ -0,0 +1,77 @@
+/**
+ * Configuration loaded from environment variables.
+ * All secrets must come from env vars — never hardcode tokens.
+ *
+ * If TELEGRAM_BOT_TOKEN is not already set, we auto-load from
+ * ~/.dreb/secrets/telegram.env (the same file the systemd service uses).
+ * This way `node dist/index.js` works without manual env setup.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+/** Default path to the secrets env file */
+export const DEFAULT_SECRETS_FILE = join(homedir(), ".dreb", "secrets", "telegram.env");
+/** Default path to shared provider API keys */
+export const DEFAULT_PROVIDERS_FILE = join(homedir(), ".dreb", "secrets", "providers.env");
+/**
+ * Load KEY=VALUE pairs from a file into process.env (without overwriting).
+ * Handles quoting, comments, and empty lines.
+ */
+function loadEnvFile(path) {
+    if (!existsSync(path))
+        return;
+    const content = readFileSync(path, "utf-8");
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eqIndex = trimmed.indexOf("=");
+        if (eqIndex === -1)
+            continue;
+        const key = trimmed.slice(0, eqIndex).trim();
+        let value = trimmed.slice(eqIndex + 1).trim();
+        // Strip surrounding quotes
+        if ((value.startsWith('"') && value.endsWith('"')) || (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        // Don't overwrite existing env vars (explicit env takes priority)
+        if (!(key in process.env)) {
+            process.env[key] = value;
+        }
+    }
+}
+export function loadConfig(secretsFile = DEFAULT_SECRETS_FILE) {
+    // Auto-load provider API keys (shared with dreb CLI)
+    loadEnvFile(DEFAULT_PROVIDERS_FILE);
+    // Auto-load telegram-specific secrets
+    loadEnvFile(secretsFile);
+    const botToken = process.env.TELEGRAM_BOT_TOKEN;
+    if (!botToken) {
+        throw new Error(`TELEGRAM_BOT_TOKEN not set.\n\n` +
+            `Either:\n` +
+            `  1. Set the environment variable directly, or\n` +
+            `  2. Create ${secretsFile} with:\n\n` +
+            `     TELEGRAM_BOT_TOKEN=your-token-here\n` +
+            `     ALLOWED_USER_IDS=your-user-id-here\n\n` +
+            `     Then: chmod 600 ${secretsFile}`);
+    }
+    const allowedUserIds = (process.env.ALLOWED_USER_IDS || "")
+        .split(",")
+        .filter((id) => id.trim())
+        .map((id) => {
+        const n = Number.parseInt(id.trim(), 10);
+        if (Number.isNaN(n))
+            throw new Error(`Invalid user ID: ${id}`);
+        return n;
+    });
+    return {
+        botToken,
+        allowedUserIds,
+        workingDir: process.env.DREB_WORKING_DIR || process.env.HOME || "/",
+        drebPath: process.env.DREB_PATH || "dreb",
+        serviceName: process.env.DREB_TELEGRAM_SERVICE || "dreb-telegram",
+        provider: process.env.DREB_PROVIDER,
+        model: process.env.DREB_MODEL,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Configuration loaded from environment variables.\n * All secrets must come from env vars — never hardcode tokens.\n *\n * If TELEGRAM_BOT_TOKEN is not already set, we auto-load from\n * ~/.dreb/secrets/telegram.env (the same file the systemd service uses).\n * This way `node dist/index.js` works without manual env setup.\n */\n\nimport { existsSync, readFileSync } from \"node:fs\";\nimport { homedir } from \"node:os\";\nimport { join } from \"node:path\";\n\nexport interface Config {\n\t/** Telegram Bot API token */\n\tbotToken: string;\n\t/** Authorized Telegram user IDs */\n\tallowedUserIds: number[];\n\t/** Working directory for dreb sessions */\n\tworkingDir: string;\n\t/** Path to the dreb CLI binary */\n\tdrebPath: string;\n\t/** Systemd service name for /restart */\n\tserviceName: string;\n\t/** Provider to use for dreb */\n\tprovider?: string;\n\t/** Model to use for dreb */\n\tmodel?: string;\n}\n\n/** Default path to the secrets env file */\nexport const DEFAULT_SECRETS_FILE = join(homedir(), \".dreb\", \"secrets\", \"telegram.env\");\n\n/** Default path to shared provider API keys */\nexport const DEFAULT_PROVIDERS_FILE = join(homedir(), \".dreb\", \"secrets\", \"providers.env\");\n\n/**\n * Load KEY=VALUE pairs from a file into process.env (without overwriting).\n * Handles quoting, comments, and empty lines.\n */\nfunction loadEnvFile(path: string): void {\n\tif (!existsSync(path)) return;\n\n\tconst content = readFileSync(path, \"utf-8\");\n\tfor (const line of content.split(\"\\n\")) {\n\t\tconst trimmed = line.trim();\n\t\tif (!trimmed || trimmed.startsWith(\"#\")) continue;\n\n\t\tconst eqIndex = trimmed.indexOf(\"=\");\n\t\tif (eqIndex === -1) continue;\n\n\t\tconst key = trimmed.slice(0, eqIndex).trim();\n\t\tlet value = trimmed.slice(eqIndex + 1).trim();\n\n\t\t// Strip surrounding quotes\n\t\tif ((value.startsWith('\"') && value.endsWith('\"')) || (value.startsWith(\"'\") && value.endsWith(\"'\"))) {\n\t\t\tvalue = value.slice(1, -1);\n\t\t}\n\n\t\t// Don't overwrite existing env vars (explicit env takes priority)\n\t\tif (!(key in process.env)) {\n\t\t\tprocess.env[key] = value;\n\t\t}\n\t}\n}\n\nexport function loadConfig(secretsFile: string = DEFAULT_SECRETS_FILE): Config {\n\t// Auto-load provider API keys (shared with dreb CLI)\n\tloadEnvFile(DEFAULT_PROVIDERS_FILE);\n\n\t// Auto-load telegram-specific secrets\n\tloadEnvFile(secretsFile);\n\n\tconst botToken = process.env.TELEGRAM_BOT_TOKEN;\n\tif (!botToken) {\n\t\tthrow new Error(\n\t\t\t`TELEGRAM_BOT_TOKEN not set.\\n\\n` +\n\t\t\t\t`Either:\\n` +\n\t\t\t\t`  1. Set the environment variable directly, or\\n` +\n\t\t\t\t`  2. Create ${secretsFile} with:\\n\\n` +\n\t\t\t\t`     TELEGRAM_BOT_TOKEN=your-token-here\\n` +\n\t\t\t\t`     ALLOWED_USER_IDS=your-user-id-here\\n\\n` +\n\t\t\t\t`     Then: chmod 600 ${secretsFile}`,\n\t\t);\n\t}\n\n\tconst allowedUserIds = (process.env.ALLOWED_USER_IDS || \"\")\n\t\t.split(\",\")\n\t\t.filter((id) => id.trim())\n\t\t.map((id) => {\n\t\t\tconst n = Number.parseInt(id.trim(), 10);\n\t\t\tif (Number.isNaN(n)) throw new Error(`Invalid user ID: ${id}`);\n\t\t\treturn n;\n\t\t});\n\n\treturn {\n\t\tbotToken,\n\t\tallowedUserIds,\n\t\tworkingDir: process.env.DREB_WORKING_DIR || process.env.HOME || \"/\",\n\t\tdrebPath: process.env.DREB_PATH || \"dreb\",\n\t\tserviceName: process.env.DREB_TELEGRAM_SERVICE || \"dreb-telegram\",\n\t\tprovider: process.env.DREB_PROVIDER,\n\t\tmodel: process.env.DREB_MODEL,\n\t};\n}\n"]}

package/dist/handlers/buddy.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Telegram buddy handler — creates and configures a BuddyController
+ * with Telegram-specific rendering callbacks and formatting.
+ */
+import type { BuddyState } from "@dreb/coding-agent/buddy";
+import { BuddyController } from "@dreb/coding-agent/buddy";
+import type { Api } from "grammy";
+import type { Config } from "../config.js";
+import type { UserState } from "../types.js";
+import type { SendFn } from "./events.js";
+export declare const SPECIES_EMOJI: Record<string, string>;
+/**
+ * Format a stats panel as a Telegram code block.
+ * Shows stat bars using █ and ░ characters.
+ */
+export declare function formatBuddyStats(state: BuddyState): string;
+/**
+ * Format a buddy speech/reaction message.
+ */
+export declare function formatBuddySpeech(name: string, species: string, text: string): string;
+/**
+ * Create a BuddyController wired up with Telegram-specific callbacks.
+ *
+ * @param send — outbox send function (enqueueSend) for reliable delivery
+ * @param api — grammy Api instance for chat actions and reactions
+ * @param chatId — Telegram chat ID for this user
+ * @param config — bot config (for bridge resolution in hatch/reroll)
+ * @param userState — per-user state (for bridge resolution in hatch/reroll)
+ */
+export declare function createTelegramBuddyController(send: SendFn, api: Api, chatId: number, config: Config, userState: UserState): BuddyController;
+//# sourceMappingURL=buddy.d.ts.map

package/dist/handlers/buddy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buddy.d.ts","sourceRoot":"","sources":["../../src/handlers/buddy.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAkB,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,eAAe,EAAuC,MAAM,0BAA0B,CAAC;AAChG,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAElC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAM1C,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAmBhD,CAAC;AAUF;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAgC1D;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAErF;AAMD;;;;;;;;GAQG;AACH,wBAAgB,6BAA6B,CAC5C,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,SAAS,GAClB,eAAe,CAwCjB","sourcesContent":["/**\n * Telegram buddy handler — creates and configures a BuddyController\n * with Telegram-specific rendering callbacks and formatting.\n */\n\nimport type { BuddyCallbacks, BuddyState } from \"@dreb/coding-agent/buddy\";\nimport { BuddyController, BuddyManager, STAT_NAMES, type Stat } from \"@dreb/coding-agent/buddy\";\nimport type { Api } from \"grammy\";\nimport { ensureBridgeWithSession } from \"../bridge-lifecycle.js\";\nimport type { Config } from \"../config.js\";\nimport type { UserState } from \"../types.js\";\nimport type { SendFn } from \"./events.js\";\n\n// ---------------------------------------------------------------------------\n// Species emoji mapping\n// ---------------------------------------------------------------------------\n\nexport const SPECIES_EMOJI: Record<string, string> = {\n\tDuck: \"🦆\",\n\tGoose: \"🪿\",\n\tBlob: \"🟢\",\n\tCat: \"🐱\",\n\tDragon: \"🐉\",\n\tOctopus: \"🐙\",\n\tOwl: \"🦉\",\n\tPenguin: \"🐧\",\n\tTurtle: \"🐢\",\n\tSnail: \"🐌\",\n\tGhost: \"👻\",\n\tAxolotl: \"🫎\",\n\tCapybara: \"🦫\",\n\tCactus: \"🌵\",\n\tRobot: \"🤖\",\n\tRabbit: \"🐰\",\n\tMushroom: \"🍄\",\n\tChonk: \"🐹\",\n};\n\nfunction speciesEmoji(species: string): string {\n\treturn SPECIES_EMOJI[species] ?? \"🐣\";\n}\n\n// ---------------------------------------------------------------------------\n// Formatting helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Format a stats panel as a Telegram code block.\n * Shows stat bars using █ and ░ characters.\n */\nexport function formatBuddyStats(state: BuddyState): string {\n\tconst emoji = speciesEmoji(state.species);\n\tconst shiny = state.shiny ? \" ✨ SHINY!\" : \"\";\n\tconst maxBar = 10;\n\tconst personality = state.personality.replace(/\\n/g, \" \");\n\tconst backstory = state.backstory.replace(/\\n/g, \" \");\n\tconst hatched = state.hatchedAt ? new Date(state.hatchedAt).toLocaleDateString() : \"unknown\";\n\n\tconst statLines = STAT_NAMES.map((s: string) => {\n\t\tconst value = state.stats[s as Stat];\n\t\tconst filled = Math.round((value / 100) * maxBar);\n\t\tconst bar = \"█\".repeat(filled) + \"░\".repeat(maxBar - filled);\n\t\treturn `│ ${s.padEnd(12)} ${bar} ${value}`;\n\t});\n\n\treturn [\n\t\t`\\`\\`\\``,\n\t\t`╭─ ${emoji} ${state.name} ${shiny} ──────────────────╮`,\n\t\t`│ Species:    ${state.species}`,\n\t\t`│ Rarity:     ${state.rarity}`,\n\t\t`│ Eyes:       ${state.eyeStyle}  Hat: ${state.hat || \"none\"}`,\n\t\t`│ Hatched:    ${hatched}`,\n\t\t`│ Re-rolls:   ${state.rerollCount}`,\n\t\t`│`,\n\t\t`│ Stats:`,\n\t\t...statLines,\n\t\t`│`,\n\t\t`│ Personality: ${personality}`,\n\t\t`│ Backstory:  ${backstory}`,\n\t\t`╰──────────────────────────────────╯`,\n\t\t`\\`\\`\\``,\n\t].join(\"\\n\");\n}\n\n/**\n * Format a buddy speech/reaction message.\n */\nexport function formatBuddySpeech(name: string, species: string, text: string): string {\n\treturn `${speciesEmoji(species)} ${name}: \"${text}\"`;\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a BuddyController wired up with Telegram-specific callbacks.\n *\n * @param send — outbox send function (enqueueSend) for reliable delivery\n * @param api — grammy Api instance for chat actions and reactions\n * @param chatId — Telegram chat ID for this user\n * @param config — bot config (for bridge resolution in hatch/reroll)\n * @param userState — per-user state (for bridge resolution in hatch/reroll)\n */\nexport function createTelegramBuddyController(\n\tsend: SendFn,\n\tapi: Api,\n\tchatId: number,\n\tconfig: Config,\n\tuserState: UserState,\n): BuddyController {\n\tconst manager = new BuddyManager();\n\n\tconst callbacks: BuddyCallbacks = {\n\t\tonSpeech(text: string): void {\n\t\t\tconst name = manager.getName() ?? \"Buddy\";\n\t\t\tconst state = manager.getState();\n\t\t\tconst species = state?.species ?? \"\";\n\t\t\tsend(formatBuddySpeech(name, species, text));\n\t\t},\n\t\tonThinkingStart(): void {\n\t\t\t// Fire-and-forget typing indicator\n\t\t\tapi.sendChatAction(chatId, \"typing\").catch(() => {});\n\t\t},\n\t\tonThinkingEnd(): void {\n\t\t\t// No-op — can't cancel a chat action in Telegram\n\t\t},\n\t\tasync onHatch(_mgr): Promise<BuddyState> {\n\t\t\tconst bridge = await ensureBridgeWithSession(config, userState);\n\t\t\treturn bridge.buddyHatch();\n\t\t},\n\t\tasync onReroll(_mgr): Promise<BuddyState> {\n\t\t\tconst bridge = await ensureBridgeWithSession(config, userState);\n\t\t\treturn bridge.buddyReroll();\n\t\t},\n\t};\n\n\tconst controller = new BuddyController(manager, callbacks, {\n\t\tidleTimeoutMs: 30_000,\n\t\treactionCooldownMs: 60_000,\n\t\tcontextMaxEntries: 20,\n\t\tactivityGateMs: 7_200_000, // 2 hours\n\t\treactionsPerHour: 3,\n\t});\n\n\t// Auto-load buddy from shared buddy.json (same file TUI uses).\n\t// If a buddy exists and is visible, it'll be active immediately.\n\tcontroller.start();\n\n\treturn controller;\n}\n"]}

package/dist/handlers/buddy.js

@@ -0,0 +1,126 @@
+/**
+ * Telegram buddy handler — creates and configures a BuddyController
+ * with Telegram-specific rendering callbacks and formatting.
+ */
+import { BuddyController, BuddyManager, STAT_NAMES } from "@dreb/coding-agent/buddy";
+import { ensureBridgeWithSession } from "../bridge-lifecycle.js";
+// ---------------------------------------------------------------------------
+// Species emoji mapping
+// ---------------------------------------------------------------------------
+export const SPECIES_EMOJI = {
+    Duck: "🦆",
+    Goose: "🪿",
+    Blob: "🟢",
+    Cat: "🐱",
+    Dragon: "🐉",
+    Octopus: "🐙",
+    Owl: "🦉",
+    Penguin: "🐧",
+    Turtle: "🐢",
+    Snail: "🐌",
+    Ghost: "👻",
+    Axolotl: "🫎",
+    Capybara: "🦫",
+    Cactus: "🌵",
+    Robot: "🤖",
+    Rabbit: "🐰",
+    Mushroom: "🍄",
+    Chonk: "🐹",
+};
+function speciesEmoji(species) {
+    return SPECIES_EMOJI[species] ?? "🐣";
+}
+// ---------------------------------------------------------------------------
+// Formatting helpers
+// ---------------------------------------------------------------------------
+/**
+ * Format a stats panel as a Telegram code block.
+ * Shows stat bars using █ and ░ characters.
+ */
+export function formatBuddyStats(state) {
+    const emoji = speciesEmoji(state.species);
+    const shiny = state.shiny ? " ✨ SHINY!" : "";
+    const maxBar = 10;
+    const personality = state.personality.replace(/\n/g, " ");
+    const backstory = state.backstory.replace(/\n/g, " ");
+    const hatched = state.hatchedAt ? new Date(state.hatchedAt).toLocaleDateString() : "unknown";
+    const statLines = STAT_NAMES.map((s) => {
+        const value = state.stats[s];
+        const filled = Math.round((value / 100) * maxBar);
+        const bar = "█".repeat(filled) + "░".repeat(maxBar - filled);
+        return `│ ${s.padEnd(12)} ${bar} ${value}`;
+    });
+    return [
+        `\`\`\``,
+        `╭─ ${emoji} ${state.name} ${shiny} ──────────────────╮`,
+        `│ Species:    ${state.species}`,
+        `│ Rarity:     ${state.rarity}`,
+        `│ Eyes:       ${state.eyeStyle}  Hat: ${state.hat || "none"}`,
+        `│ Hatched:    ${hatched}`,
+        `│ Re-rolls:   ${state.rerollCount}`,
+        `│`,
+        `│ Stats:`,
+        ...statLines,
+        `│`,
+        `│ Personality: ${personality}`,
+        `│ Backstory:  ${backstory}`,
+        `╰──────────────────────────────────╯`,
+        `\`\`\``,
+    ].join("\n");
+}
+/**
+ * Format a buddy speech/reaction message.
+ */
+export function formatBuddySpeech(name, species, text) {
+    return `${speciesEmoji(species)} ${name}: "${text}"`;
+}
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+/**
+ * Create a BuddyController wired up with Telegram-specific callbacks.
+ *
+ * @param send — outbox send function (enqueueSend) for reliable delivery
+ * @param api — grammy Api instance for chat actions and reactions
+ * @param chatId — Telegram chat ID for this user
+ * @param config — bot config (for bridge resolution in hatch/reroll)
+ * @param userState — per-user state (for bridge resolution in hatch/reroll)
+ */
+export function createTelegramBuddyController(send, api, chatId, config, userState) {
+    const manager = new BuddyManager();
+    const callbacks = {
+        onSpeech(text) {
+            const name = manager.getName() ?? "Buddy";
+            const state = manager.getState();
+            const species = state?.species ?? "";
+            send(formatBuddySpeech(name, species, text));
+        },
+        onThinkingStart() {
+            // Fire-and-forget typing indicator
+            api.sendChatAction(chatId, "typing").catch(() => { });
+        },
+        onThinkingEnd() {
+            // No-op — can't cancel a chat action in Telegram
+        },
+        async onHatch(_mgr) {
+            const bridge = await ensureBridgeWithSession(config, userState);
+            return bridge.buddyHatch();
+        },
+        async onReroll(_mgr) {
+            const bridge = await ensureBridgeWithSession(config, userState);
+            return bridge.buddyReroll();
+        },
+    };
+    const controller = new BuddyController(manager, callbacks, {
+        idleTimeoutMs: 30_000,
+        reactionCooldownMs: 60_000,
+        contextMaxEntries: 20,
+        activityGateMs: 7_200_000, // 2 hours
+        reactionsPerHour: 3,
+    });
+    // Auto-load buddy from shared buddy.json (same file TUI uses).
+    // If a buddy exists and is visible, it'll be active immediately.
+    controller.start();
+    return controller;
+}
+//# sourceMappingURL=buddy.js.map

package/dist/handlers/buddy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buddy.js","sourceRoot":"","sources":["../../src/handlers/buddy.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Telegram buddy handler — creates and configures a BuddyController\n * with Telegram-specific rendering callbacks and formatting.\n */\n\nimport type { BuddyCallbacks, BuddyState } from \"@dreb/coding-agent/buddy\";\nimport { BuddyController, BuddyManager, STAT_NAMES, type Stat } from \"@dreb/coding-agent/buddy\";\nimport type { Api } from \"grammy\";\nimport { ensureBridgeWithSession } from \"../bridge-lifecycle.js\";\nimport type { Config } from \"../config.js\";\nimport type { UserState } from \"../types.js\";\nimport type { SendFn } from \"./events.js\";\n\n// ---------------------------------------------------------------------------\n// Species emoji mapping\n// ---------------------------------------------------------------------------\n\nexport const SPECIES_EMOJI: Record<string, string> = {\n\tDuck: \"🦆\",\n\tGoose: \"🪿\",\n\tBlob: \"🟢\",\n\tCat: \"🐱\",\n\tDragon: \"🐉\",\n\tOctopus: \"🐙\",\n\tOwl: \"🦉\",\n\tPenguin: \"🐧\",\n\tTurtle: \"🐢\",\n\tSnail: \"🐌\",\n\tGhost: \"👻\",\n\tAxolotl: \"🫎\",\n\tCapybara: \"🦫\",\n\tCactus: \"🌵\",\n\tRobot: \"🤖\",\n\tRabbit: \"🐰\",\n\tMushroom: \"🍄\",\n\tChonk: \"🐹\",\n};\n\nfunction speciesEmoji(species: string): string {\n\treturn SPECIES_EMOJI[species] ?? \"🐣\";\n}\n\n// ---------------------------------------------------------------------------\n// Formatting helpers\n// ---------------------------------------------------------------------------\n\n/**\n * Format a stats panel as a Telegram code block.\n * Shows stat bars using █ and ░ characters.\n */\nexport function formatBuddyStats(state: BuddyState): string {\n\tconst emoji = speciesEmoji(state.species);\n\tconst shiny = state.shiny ? \" ✨ SHINY!\" : \"\";\n\tconst maxBar = 10;\n\tconst personality = state.personality.replace(/\\n/g, \" \");\n\tconst backstory = state.backstory.replace(/\\n/g, \" \");\n\tconst hatched = state.hatchedAt ? new Date(state.hatchedAt).toLocaleDateString() : \"unknown\";\n\n\tconst statLines = STAT_NAMES.map((s: string) => {\n\t\tconst value = state.stats[s as Stat];\n\t\tconst filled = Math.round((value / 100) * maxBar);\n\t\tconst bar = \"█\".repeat(filled) + \"░\".repeat(maxBar - filled);\n\t\treturn `│ ${s.padEnd(12)} ${bar} ${value}`;\n\t});\n\n\treturn [\n\t\t`\\`\\`\\``,\n\t\t`╭─ ${emoji} ${state.name} ${shiny} ──────────────────╮`,\n\t\t`│ Species:    ${state.species}`,\n\t\t`│ Rarity:     ${state.rarity}`,\n\t\t`│ Eyes:       ${state.eyeStyle}  Hat: ${state.hat || \"none\"}`,\n\t\t`│ Hatched:    ${hatched}`,\n\t\t`│ Re-rolls:   ${state.rerollCount}`,\n\t\t`│`,\n\t\t`│ Stats:`,\n\t\t...statLines,\n\t\t`│`,\n\t\t`│ Personality: ${personality}`,\n\t\t`│ Backstory:  ${backstory}`,\n\t\t`╰──────────────────────────────────╯`,\n\t\t`\\`\\`\\``,\n\t].join(\"\\n\");\n}\n\n/**\n * Format a buddy speech/reaction message.\n */\nexport function formatBuddySpeech(name: string, species: string, text: string): string {\n\treturn `${speciesEmoji(species)} ${name}: \"${text}\"`;\n}\n\n// ---------------------------------------------------------------------------\n// Factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create a BuddyController wired up with Telegram-specific callbacks.\n *\n * @param send — outbox send function (enqueueSend) for reliable delivery\n * @param api — grammy Api instance for chat actions and reactions\n * @param chatId — Telegram chat ID for this user\n * @param config — bot config (for bridge resolution in hatch/reroll)\n * @param userState — per-user state (for bridge resolution in hatch/reroll)\n */\nexport function createTelegramBuddyController(\n\tsend: SendFn,\n\tapi: Api,\n\tchatId: number,\n\tconfig: Config,\n\tuserState: UserState,\n): BuddyController {\n\tconst manager = new BuddyManager();\n\n\tconst callbacks: BuddyCallbacks = {\n\t\tonSpeech(text: string): void {\n\t\t\tconst name = manager.getName() ?? \"Buddy\";\n\t\t\tconst state = manager.getState();\n\t\t\tconst species = state?.species ?? \"\";\n\t\t\tsend(formatBuddySpeech(name, species, text));\n\t\t},\n\t\tonThinkingStart(): void {\n\t\t\t// Fire-and-forget typing indicator\n\t\t\tapi.sendChatAction(chatId, \"typing\").catch(() => {});\n\t\t},\n\t\tonThinkingEnd(): void {\n\t\t\t// No-op — can't cancel a chat action in Telegram\n\t\t},\n\t\tasync onHatch(_mgr): Promise<BuddyState> {\n\t\t\tconst bridge = await ensureBridgeWithSession(config, userState);\n\t\t\treturn bridge.buddyHatch();\n\t\t},\n\t\tasync onReroll(_mgr): Promise<BuddyState> {\n\t\t\tconst bridge = await ensureBridgeWithSession(config, userState);\n\t\t\treturn bridge.buddyReroll();\n\t\t},\n\t};\n\n\tconst controller = new BuddyController(manager, callbacks, {\n\t\tidleTimeoutMs: 30_000,\n\t\treactionCooldownMs: 60_000,\n\t\tcontextMaxEntries: 20,\n\t\tactivityGateMs: 7_200_000, // 2 hours\n\t\treactionsPerHour: 3,\n\t});\n\n\t// Auto-load buddy from shared buddy.json (same file TUI uses).\n\t// If a buddy exists and is visible, it'll be active immediately.\n\tcontroller.start();\n\n\treturn controller;\n}\n"]}

package/dist/handlers/events.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Event display — translates RPC agent events into Telegram messages.
+ *
+ * Manages an ephemeral status message that shows tool use, task lists,
+ * and subagent activity. Text from the agent is sent as permanent messages.
+ */
+import type { Api } from "grammy";
+import type { TrackedAgent } from "../types.js";
+import { DebouncedEditor } from "../util/telegram.js";
+/** Callback to queue a message for delivery — never blocks the event chain */
+export type SendFn = (text: string, long?: boolean) => void;
+/**
+ * RPC events include both core AgentEvent and session-specific events
+ * (tasks_update, background_agent_*, auto_compaction_*).
+ * We type loosely here since the RPC client types onEvent as AgentEvent
+ * but actually forwards all AgentSessionEvent types.
+ */
+type RpcEvent = {
+    type: string;
+    [key: string]: any;
+};
+export interface EventDisplayState {
+    /** Chat ID to send messages to */
+    chatId: number;
+    /** Message ID to reply to */
+    replyToId: number;
+    /** Ephemeral status message ID (edited in-place) */
+    statusMessageId: number | null;
+    /** Tool messages accumulated since last text */
+    toolsSinceText: string[];
+    /** Total tool count */
+    toolCount: number;
+    /** All text blocks received */
+    textBlocks: string[];
+    /** Current task list */
+    tasks: Array<{
+        id: string;
+        title: string;
+        status: string;
+    }>;
+    /** Background agents */
+    backgroundAgents: Map<string, TrackedAgent>;
+    /** Whether agent has finished */
+    done: boolean;
+    /** Debounced editor instance */
+    editor: DebouncedEditor;
+    /** Whether auto-retry is in progress (Layer 1: reactive — set by auto_retry_start) */
+    retryInProgress: boolean;
+    /** Whether a retry is expected (Layer 2: predictive — set by agent_end when error looks retryable) */
+    pendingRetry: boolean;
+    /** Current retry attempt number for display */
+    retryAttempt: number;
+    /** Buddy controller — receives agent events for context + reactions */
+    buddyController?: any;
+}
+/**
+ * Create a fresh event display state for a new agent run.
+ */
+export declare function createEventDisplay(api: Api, chatId: number, replyToId: number, statusMessageId: number | null): EventDisplayState;
+/**
+ * Process an agent event and update the display.
+ */
+export declare function handleAgentEvent(send: SendFn, api: Api, state: EventDisplayState, event: RpcEvent): Promise<void>;
+export {};
+//# sourceMappingURL=events.d.ts.map

package/dist/handlers/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/handlers/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAElC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD,OAAO,EAAE,eAAe,EAAmB,MAAM,qBAAqB,CAAC;AAEvE,gFAA8E;AAC9E,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AAE5D;;;;;GAKG;AACH,KAAK,QAAQ,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,CAAC;AAmErD,MAAM,WAAW,iBAAiB;IACjC,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,6BAA6B;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,gDAAgD;IAChD,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,uBAAuB;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,wBAAwB;IACxB,KAAK,EAAE,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5D,wBAAwB;IACxB,gBAAgB,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC5C,iCAAiC;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,gCAAgC;IAChC,MAAM,EAAE,eAAe,CAAC;IACxB,wFAAsF;IACtF,eAAe,EAAE,OAAO,CAAC;IACzB,wGAAsG;IACtG,YAAY,EAAE,OAAO,CAAC;IACtB,+CAA+C;IAC/C,YAAY,EAAE,MAAM,CAAC;IACrB,yEAAuE;IACvE,eAAe,CAAC,EAAE,GAAG,CAAC;CACtB;AAaD;;GAEG;AACH,wBAAgB,kBAAkB,CACjC,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,MAAM,EACd,SAAS,EAAE,MAAM,EACjB,eAAe,EAAE,MAAM,GAAG,IAAI,GAC5B,iBAAiB,CAgBnB;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACrC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,GAAG,EACR,KAAK,EAAE,iBAAiB,EACxB,KAAK,EAAE,QAAQ,GACb,OAAO,CAAC,IAAI,CAAC,CA6Qf","sourcesContent":["/**\n * Event display — translates RPC agent events into Telegram messages.\n *\n * Manages an ephemeral status message that shows tool use, task lists,\n * and subagent activity. Text from the agent is sent as permanent messages.\n */\n\nimport { existsSync } from \"node:fs\";\nimport type { Api } from \"grammy\";\nimport { InputFile } from \"grammy\";\nimport type { TrackedAgent } from \"../types.js\";\nimport { extractSendFiles } from \"../util/files.js\";\nimport { DebouncedEditor, log, safeDelete } from \"../util/telegram.js\";\n\n/** Callback to queue a message for delivery — never blocks the event chain */\nexport type SendFn = (text: string, long?: boolean) => void;\n\n/**\n * RPC events include both core AgentEvent and session-specific events\n * (tasks_update, background_agent_*, auto_compaction_*).\n * We type loosely here since the RPC client types onEvent as AgentEvent\n * but actually forwards all AgentSessionEvent types.\n */\ntype RpcEvent = { type: string; [key: string]: any };\n\n// Tool emoji mapping (tool names are lowercase in definitions)\nconst TOOL_EMOJI: Record<string, string> = {\n\tbash: \"🔧\",\n\tread: \"📖\",\n\tedit: \"✏️\",\n\twrite: \"📝\",\n\tgrep: \"🔎\",\n\tfind: \"🔍\",\n\tls: \"📂\",\n\tweb_search: \"🌐\",\n\tweb_fetch: \"🌐\",\n\tsubagent: \"🤖\",\n\ttasks_update: \"📋\",\n\tskill: \"⚡\",\n};\n\nfunction toolEmoji(name: string): string {\n\treturn TOOL_EMOJI[name] || \"🔧\";\n}\n\n/** Format a tool call for display */\nfunction formatTool(name: string, args: Record<string, any>): string {\n\tconst emoji = toolEmoji(name);\n\tswitch (name) {\n\t\tcase \"bash\": {\n\t\t\tconst cmd = args.command || \"\";\n\t\t\treturn `${emoji} *bash*\\n\\`${cmd.slice(0, 500)}\\``;\n\t\t}\n\t\tcase \"read\":\n\t\t\treturn `${emoji} *read*: \\`${args.path || \"?\"}\\``;\n\t\tcase \"edit\":\n\t\t\treturn `${emoji} *edit*: \\`${args.path || \"?\"}\\``;\n\t\tcase \"write\":\n\t\t\treturn `${emoji} *write*: \\`${args.path || \"?\"}\\``;\n\t\tcase \"grep\":\n\t\t\treturn `${emoji} *grep*: \\`${args.pattern || \"?\"}\\``;\n\t\tcase \"find\":\n\t\t\treturn `${emoji} *find*: \\`${args.pattern || \"?\"}\\``;\n\t\tcase \"ls\":\n\t\t\treturn `${emoji} *ls*: \\`${args.path || \".\"}\\``;\n\t\tcase \"web_search\":\n\t\t\treturn `${emoji} *web\\\\_search*: ${args.query || \"?\"}`;\n\t\tcase \"web_fetch\":\n\t\t\treturn `${emoji} *web\\\\_fetch*: ${(args.url || \"?\").slice(0, 80)}`;\n\t\tcase \"subagent\":\n\t\t\treturn `${emoji} *subagent* (${args.agent || \"?\"}): ${(args.task || args.tasks?.[0]?.task || \"?\").slice(0, 200)}`;\n\t\tcase \"skill\":\n\t\t\treturn `${emoji} *skill*: ${args.skill || \"?\"}`;\n\t\tdefault:\n\t\t\treturn `${emoji} *${name}*`;\n\t}\n}\n\n/** Format task list as checklist */\nfunction formatTaskList(tasks: Array<{ id: string; title: string; status: string }>): string {\n\tif (!tasks.length) return \"📋 *Tasks*: (empty)\";\n\tconst lines = [\"📋 *Tasks*:\"];\n\tfor (const task of tasks) {\n\t\tif (task.status === \"completed\") lines.push(`  ✅ ${task.title}`);\n\t\telse if (task.status === \"in_progress\") lines.push(`  🔄 ${task.title}`);\n\t\telse lines.push(`  ⬜ ${task.title}`);\n\t}\n\treturn lines.join(\"\\n\");\n}\n\nexport interface EventDisplayState {\n\t/** Chat ID to send messages to */\n\tchatId: number;\n\t/** Message ID to reply to */\n\treplyToId: number;\n\t/** Ephemeral status message ID (edited in-place) */\n\tstatusMessageId: number | null;\n\t/** Tool messages accumulated since last text */\n\ttoolsSinceText: string[];\n\t/** Total tool count */\n\ttoolCount: number;\n\t/** All text blocks received */\n\ttextBlocks: string[];\n\t/** Current task list */\n\ttasks: Array<{ id: string; title: string; status: string }>;\n\t/** Background agents */\n\tbackgroundAgents: Map<string, TrackedAgent>;\n\t/** Whether agent has finished */\n\tdone: boolean;\n\t/** Debounced editor instance */\n\teditor: DebouncedEditor;\n\t/** Whether auto-retry is in progress (Layer 1: reactive — set by auto_retry_start) */\n\tretryInProgress: boolean;\n\t/** Whether a retry is expected (Layer 2: predictive — set by agent_end when error looks retryable) */\n\tpendingRetry: boolean;\n\t/** Current retry attempt number for display */\n\tretryAttempt: number;\n\t/** Buddy controller — receives agent events for context + reactions */\n\tbuddyController?: any;\n}\n\n/**\n * Check if an error message looks retryable (overloaded, rate limit, server errors).\n * Mirrors the core's _isRetryableError check as a defensive Layer 2.\n */\nconst RETRYABLE_ERROR_PATTERN =\n\t/overloaded|provider.?returned.?error|rate.?limit|too many requests|429|500|502|503|504|service.?unavailable|server.?error|internal.?error|network.?error|connection.?error|connection.?refused|other side closed|fetch failed|upstream.?connect|reset before headers|socket hang up|timed? out|timeout|terminated|retry delay/i;\n\nfunction isRetryableError(errorMessage: string): boolean {\n\treturn RETRYABLE_ERROR_PATTERN.test(errorMessage);\n}\n\n/**\n * Create a fresh event display state for a new agent run.\n */\nexport function createEventDisplay(\n\tapi: Api,\n\tchatId: number,\n\treplyToId: number,\n\tstatusMessageId: number | null,\n): EventDisplayState {\n\treturn {\n\t\tchatId,\n\t\treplyToId,\n\t\tstatusMessageId,\n\t\ttoolsSinceText: [],\n\t\ttoolCount: 0,\n\t\ttextBlocks: [],\n\t\ttasks: [],\n\t\tbackgroundAgents: new Map(),\n\t\tdone: false,\n\t\teditor: new DebouncedEditor(api),\n\t\tretryInProgress: false,\n\t\tpendingRetry: false,\n\t\tretryAttempt: 0,\n\t};\n}\n\n/**\n * Process an agent event and update the display.\n */\nexport async function handleAgentEvent(\n\tsend: SendFn,\n\tapi: Api,\n\tstate: EventDisplayState,\n\tevent: RpcEvent,\n): Promise<void> {\n\tswitch (event.type) {\n\t\tcase \"tool_execution_start\": {\n\t\t\tconst name = event.toolName || \"?\";\n\t\t\tconst args = event.args || {};\n\t\t\tstate.toolCount++;\n\n\t\t\t// tasks_update is shown via the separate tasks_update event — skip from tool summary\n\t\t\tif (name !== \"tasks_update\") {\n\t\t\t\tconst toolMsg = formatTool(name, args);\n\t\t\t\tstate.toolsSinceText.push(toolMsg);\n\t\t\t}\n\n\t\t\t// Update status with tool count and recent tools\n\t\t\tupdateStatus(state);\n\t\t\tbreak;\n\t\t}\n\n\t\tcase \"tool_execution_end\": {\n\t\t\t// Feed event to buddy controller for context capture + error reactions\n\t\t\tstate.buddyController?.handleEvent(event);\n\t\t\tbreak;\n\t\t}\n\n\t\tcase \"message_end\": {\n\t\t\tconst msg = event.message;\n\n\t\t\t// Show subagent results — the parent agent references these but the\n\t\t\t// Telegram user can't see them otherwise. Send the full content.\n\t\t\tif (msg?.role === \"toolResult\" && msg?.toolName === \"subagent\") {\n\t\t\t\tconst content = msg?.content;\n\t\t\t\tif (content && Array.isArray(content)) {\n\t\t\t\t\tfor (const block of content) {\n\t\t\t\t\t\tif (block.type === \"text\" && block.text?.trim()) {\n\t\t\t\t\t\t\tsend(`🤖 *Subagent result:*\\n${block.text.trim()}`, true);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\t}\n\n\t\t\t// Show background agent completion results — these arrive as user\n\t\t\t// messages injected by agent-session.ts via prompt()/steer() and\n\t\t\t// contain the actual subagent output the model sees.\n\t\t\tif (msg?.role === \"user\") {\n\t\t\t\tconst content = msg?.content;\n\t\t\t\tif (content && Array.isArray(content)) {\n\t\t\t\t\tfor (const block of content) {\n\t\t\t\t\t\tif (block.type === \"text\" && block.text?.includes(\"<background-agent-complete>\")) {\n\t\t\t\t\t\t\t// Extract the content between the XML tags\n\t\t\t\t\t\t\tconst match = block.text.match(\n\t\t\t\t\t\t\t\t/<background-agent-complete>\\n?([\\s\\S]*?)\\n?<\\/background-agent-complete>/,\n\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\tif (match?.[1]?.trim()) {\n\t\t\t\t\t\t\t\tsend(`🤖 *Background agent complete:*\\n${match[1].trim()}`, true);\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\tbreak;\n\t\t\t}\n\n\t\t\t// Only display assistant messages — user messages are echoed back by RPC\n\t\t\tif (msg?.role !== \"assistant\") break;\n\t\t\tconst content = msg?.content;\n\t\t\tif (!content || !Array.isArray(content)) break;\n\n\t\t\tfor (const block of content) {\n\t\t\t\t// Display thinking blocks (collapsed summary)\n\t\t\t\tif (block.type === \"thinking\" && block.thinking?.trim() && !block.redacted) {\n\t\t\t\t\tconst thinking = block.thinking.trim();\n\t\t\t\t\tsend(`💭 _${thinking}_`, true);\n\t\t\t\t}\n\n\t\t\t\tif (block.type === \"text\" && block.text?.trim()) {\n\t\t\t\t\tconst text = block.text.trim();\n\n\t\t\t\t\t// Flush accumulated tools as permanent summary\n\t\t\t\t\tif (state.toolsSinceText.length > 0) {\n\t\t\t\t\t\tconst summary = `📋 *${state.toolsSinceText.length} tools*:\\n${state.toolsSinceText.join(\"\\n\")}`;\n\t\t\t\t\t\tsend(summary, true);\n\t\t\t\t\t\tstate.toolsSinceText = [];\n\t\t\t\t\t}\n\n\t\t\t\t\t// Send the text as a permanent message\n\t\t\t\t\tstate.textBlocks.push(text);\n\n\t\t\t\t\t// Check for file send markers\n\t\t\t\t\tconst [cleanText, filePaths] = extractSendFiles(text);\n\t\t\t\t\tif (cleanText) {\n\t\t\t\t\t\tsend(cleanText, true);\n\t\t\t\t\t}\n\n\t\t\t\t\t// Send any requested files (silently skip non-existent paths —\n\t\t\t\t\t// the pattern may appear in explanatory text)\n\t\t\t\t\tfor (const filePath of filePaths) {\n\t\t\t\t\t\ttry {\n\t\t\t\t\t\t\tif (existsSync(filePath)) {\n\t\t\t\t\t\t\t\tawait api.sendDocument(state.chatId, new InputFile(filePath));\n\t\t\t\t\t\t\t}\n\t\t\t\t\t\t} catch (e) {\n\t\t\t\t\t\t\tlog(`[EVENTS] Failed to send file ${filePath}: ${e}`);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t\t// Feed event to buddy controller for context capture + reactions\n\t\t\tstate.buddyController?.handleEvent(event);\n\t\t\tbreak;\n\t\t}\n\n\t\tcase \"tasks_update\": {\n\t\t\tstate.tasks = (event as any).tasks || [];\n\t\t\tupdateStatus(state);\n\t\t\tbreak;\n\t\t}\n\n\t\tcase \"background_agent_start\": {\n\t\t\tconst { agentId, agentType, taskSummary } = event as any;\n\t\t\tstate.backgroundAgents.set(agentId, {\n\t\t\t\tagentId,\n\t\t\t\tagentType,\n\t\t\t\ttaskSummary,\n\t\t\t\tstartTime: Date.now(),\n\t\t\t});\n\t\t\tupdateStatus(state);\n\t\t\tbreak;\n\t\t}\n\n\t\tcase \"background_agent_end\": {\n\t\t\tconst { agentId } = event as any;\n\t\t\tstate.backgroundAgents.delete(agentId);\n\t\t\t// Background agents completing does not end the parent's turn.\n\t\t\t// Only agent_end sets done — same as TUI behavior.\n\t\t\tupdateStatus(state);\n\t\t\tbreak;\n\t\t}\n\n\t\tcase \"auto_compaction_start\": {\n\t\t\tupdateStatusText(state, \"🗜 _Compacting context..._\");\n\t\t\tbreak;\n\t\t}\n\n\t\tcase \"auto_compaction_end\": {\n\t\t\tconst result = (event as any).result;\n\t\t\tif (result) {\n\t\t\t\tconst before = result.tokensBefore || 0;\n\t\t\t\tconst msg = `🗜 Context compacted (was ${Math.round(before / 1000)}k tokens)`;\n\t\t\t\tsend(msg);\n\t\t\t}\n\t\t\tbreak;\n\t\t}\n\n\t\t// =====================================================================\n\t\t// Auto-retry — prevents agent_end from marking done during retries\n\t\t// =====================================================================\n\n\t\tcase \"auto_retry_start\": {\n\t\t\tconst { attempt, maxAttempts, delayMs, errorMessage } = event as any;\n\t\t\tstate.retryInProgress = true;\n\t\t\tstate.pendingRetry = false; // Layer 1 has taken over from Layer 2\n\t\t\tstate.retryAttempt = attempt;\n\t\t\tconst delaySec = Math.round(delayMs / 1000);\n\t\t\tconst shortErr = errorMessage?.length > 80 ? `${errorMessage.slice(0, 80)}…` : errorMessage;\n\t\t\tupdateStatusText(state, `🔄 _Retrying (${attempt}/${maxAttempts}) in ${delaySec}s — ${shortErr || \"error\"}_`);\n\t\t\tbreak;\n\t\t}\n\n\t\tcase \"auto_retry_end\": {\n\t\t\tconst { success, attempt, finalError } = event as any;\n\t\t\tstate.retryInProgress = false;\n\t\t\tstate.retryAttempt = 0;\n\t\t\tif (!success && finalError) {\n\t\t\t\t// Max retries exhausted — show final error\n\t\t\t\tsend(`❌ _Retry failed (${attempt} attempts):_ ${finalError}`, true);\n\t\t\t}\n\t\t\t// On success, the retry's agent_start/agent_end cycle will handle display normally\n\t\t\tbreak;\n\t\t}\n\n\t\tcase \"agent_end\": {\n\t\t\t// Flush any remaining tools\n\t\t\tif (state.toolsSinceText.length > 0) {\n\t\t\t\tconst summary = `📋 *${state.toolsSinceText.length} tools*:\\n${state.toolsSinceText.join(\"\\n\")}`;\n\t\t\t\tsend(summary, true);\n\t\t\t\tstate.toolsSinceText = [];\n\t\t\t}\n\n\t\t\t// Check for error in agent_end messages\n\t\t\tconst errorMsg = (event.messages as any[])?.find(\n\t\t\t\t(m: any) => m.stopReason === \"error\" || m.stopReason === \"aborted\",\n\t\t\t);\n\n\t\t\t// Layer 2 (defensive): If this error looks retryable and we're not already\n\t\t\t// tracking a retry via Layer 1, don't mark done — the core will auto-retry\n\t\t\t// and emit a new agent_start/agent_end cycle.\n\t\t\tconst errorIsRetryable = errorMsg?.errorMessage && isRetryableError(errorMsg.errorMessage);\n\n\t\t\tif (errorMsg?.errorMessage) {\n\t\t\t\t// Suppress the scary error message during retry — user already saw the\n\t\t\t\t// auto_retry_start status. Only show the error if retry tracking missed it\n\t\t\t\t// (defensive: shouldn't happen, but better than silence).\n\t\t\t\tif (!state.retryInProgress && !errorIsRetryable) {\n\t\t\t\t\tconst provider = errorMsg.provider ? `${errorMsg.provider}/${errorMsg.model}` : \"\";\n\t\t\t\t\tconst prefix = provider ? `${provider}: ` : \"\";\n\t\t\t\t\tconst errLower = errorMsg.errorMessage.toLowerCase();\n\t\t\t\t\tconst hint =\n\t\t\t\t\t\terrLower.includes(\"connection\") || errLower.includes(\"timeout\") || errLower.includes(\"network\")\n\t\t\t\t\t\t\t? \"\\n_Provider may be down — try /model to switch._\"\n\t\t\t\t\t\t\t: \"\";\n\t\t\t\t\tsend(`❌ ${prefix}${errorMsg.errorMessage}${hint}`, true);\n\t\t\t\t}\n\t\t\t} else if (state.textBlocks.length === 0 && state.backgroundAgents.size === 0) {\n\t\t\t\t// Only show \"(No response)\" when truly done — not between agent cycles\n\t\t\t\tif (!state.retryInProgress && !errorIsRetryable) {\n\t\t\t\t\tsend(\"(No response)\");\n\t\t\t\t}\n\t\t\t}\n\n\t\t\t// Feed event to buddy controller for context capture + reactions\n\t\t\tstate.buddyController?.handleEvent(event);\n\n\t\t\t// Don't mark done if auto-retry is in progress (Layer 1) or the error\n\t\t\t// looks retryable (Layer 2 — defensive catch in case events were missed).\n\t\t\t// The core will emit a new agent_start/agent_end cycle for the retry.\n\t\t\tif (state.retryInProgress || errorIsRetryable) {\n\t\t\t\t// Signal that a retry is expected — the completion check in\n\t\t\t\t// ensureSubscribed needs this because it runs in the eventChain\n\t\t\t\t// BEFORE auto_retry_start has been processed.\n\t\t\t\tif (errorIsRetryable) state.pendingRetry = true;\n\t\t\t\t// Reset per-cycle state for the next agent loop\n\t\t\t\tstate.textBlocks = [];\n\t\t\t\tstate.toolCount = 0;\n\t\t\t\tbreak;\n\t\t\t}\n\n\t\t\t// If background agents are still running, keep the subscription alive\n\t\t\t// and reset per-cycle state for the next agent loop\n\t\t\tif (state.backgroundAgents.size > 0) {\n\t\t\t\tstate.textBlocks = [];\n\t\t\t\tstate.toolCount = 0;\n\t\t\t\tbreak;\n\t\t\t}\n\n\t\t\t// Delete ephemeral status before signaling done\n\t\t\tif (state.statusMessageId) {\n\t\t\t\tawait state.editor.flush(state.chatId, state.statusMessageId);\n\t\t\t\tawait safeDelete(api, state.chatId, state.statusMessageId);\n\t\t\t\tstate.statusMessageId = null;\n\t\t\t}\n\n\t\t\t// Clean up editor\n\t\t\tstate.editor.clear();\n\n\t\t\t// Signal done AFTER cleanup — waitForCompletion checks this flag,\n\t\t\t// so setting it last ensures status message is deleted before DONE is sent\n\t\t\tstate.done = true;\n\t\t\tbreak;\n\t\t}\n\n\t\t// Handle error responses that leak through RPC (async prompt errors)\n\t\tcase \"response\": {\n\t\t\tconst resp = event as any;\n\t\t\tif (!resp.success && resp.error) {\n\t\t\t\tsend(`❌ ${resp.error}`, true);\n\t\t\t}\n\t\t\tbreak;\n\t\t}\n\t}\n}\n\n/**\n * Build and push a status update to the ephemeral message.\n */\nfunction updateStatus(state: EventDisplayState): void {\n\tif (!state.statusMessageId) return;\n\n\tconst parts: string[] = [];\n\n\t// Tool count header\n\tif (state.toolCount > 0) {\n\t\tparts.push(`🔧 *Tool ${state.toolCount}*`);\n\t}\n\n\t// Task list\n\tif (state.tasks.length > 0) {\n\t\tparts.push(formatTaskList(state.tasks));\n\t}\n\n\t// Background agents\n\tif (state.backgroundAgents.size > 0) {\n\t\tfor (const agent of state.backgroundAgents.values()) {\n\t\t\tparts.push(`🤖 *${agent.agentType}*: ${agent.taskSummary.slice(0, 200)}`);\n\t\t}\n\t}\n\n\t// Recent tools (last 5)\n\tif (state.toolsSinceText.length > 0) {\n\t\tconst recent = state.toolsSinceText.slice(-5);\n\t\tparts.push(recent.join(\"\\n\\n\"));\n\t}\n\n\tif (parts.length === 0) return;\n\n\tconst text = parts.join(\"\\n\\n\").slice(0, 4000);\n\tstate.editor.edit(state.chatId, state.statusMessageId, text);\n}\n\nfunction updateStatusText(state: EventDisplayState, text: string): void {\n\tif (!state.statusMessageId) return;\n\tstate.editor.edit(state.chatId, state.statusMessageId, text);\n}\n"]}