ctb 1.2.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "ctb",
-	"version": "1.2.1",
+	"version": "1.3.0",
 	"description": "Control Claude Code from Telegram - run multiple bot instances per project",
 	"type": "module",
 	"bin": {

package/src/__tests__/errors.test.ts

@@ -0,0 +1,60 @@
+/**
+ * Unit tests for error formatting.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { formatUserError } from "../errors";
+
+describe("formatUserError", () => {
+	test("formats timeout error", () => {
+		const msg = formatUserError(new Error("Query timeout (180s > 180s limit)"));
+		expect(msg).toContain("took too long");
+		expect(msg).not.toContain("timeout");
+	});
+
+	test("formats rate limit error", () => {
+		const msg = formatUserError(new Error("Too Many Requests: retry after 5"));
+		expect(msg).toContain("busy");
+	});
+
+	test("formats network error", () => {
+		const msg = formatUserError(new Error("ETIMEDOUT"));
+		expect(msg.toLowerCase()).toContain("connection");
+	});
+
+	test("formats generic error with truncation", () => {
+		const longError = "A".repeat(300);
+		const msg = formatUserError(new Error(longError));
+		expect(msg.length).toBeLessThan(250);
+	});
+
+	test("formats cancelled/aborted error", () => {
+		const msg = formatUserError(new Error("Request was cancelled by user"));
+		expect(msg).toContain("cancelled");
+	});
+
+	test("formats unsafe command error", () => {
+		const msg = formatUserError(new Error("unsafe command detected"));
+		expect(msg).toContain("safety");
+	});
+
+	test("formats file access error", () => {
+		const msg = formatUserError(new Error("outside allowed paths"));
+		expect(msg).toContain("file location");
+	});
+
+	test("formats authentication error", () => {
+		const msg = formatUserError(new Error("401 unauthorized"));
+		expect(msg).toContain("Authentication");
+	});
+
+	test("formats ECONNRESET error", () => {
+		const msg = formatUserError(new Error("ECONNRESET"));
+		expect(msg).toContain("Connection");
+	});
+
+	test("handles error with empty message", () => {
+		const msg = formatUserError(new Error(""));
+		expect(msg).toContain("Error");
+	});
+});

package/src/__tests__/events.test.ts

@@ -0,0 +1,43 @@
+/**
+ * Unit tests for event emitter module.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { botEvents } from "../events";
+
+describe("BotEvents", () => {
+	test("emits and receives events", () => {
+		let received = false;
+		const unsubscribe = botEvents.on("sessionRunning", (running) => {
+			received = running;
+		});
+
+		botEvents.emit("sessionRunning", true);
+		expect(received).toBe(true);
+
+		unsubscribe();
+	});
+
+	test("unsubscribe stops receiving events", () => {
+		let count = 0;
+		const unsubscribe = botEvents.on("sessionRunning", () => {
+			count++;
+		});
+
+		botEvents.emit("sessionRunning", true);
+		expect(count).toBe(1);
+
+		unsubscribe();
+
+		botEvents.emit("sessionRunning", true);
+		expect(count).toBe(1);
+	});
+
+	test("getSessionState returns current state", () => {
+		botEvents.emit("sessionRunning", false);
+		expect(botEvents.getSessionState()).toBe(false);
+
+		botEvents.emit("sessionRunning", true);
+		expect(botEvents.getSessionState()).toBe(true);
+	});
+});

package/src/__tests__/session.test.ts

@@ -396,4 +396,77 @@ describe("ClaudeSession", () => {
 			expect(session.canUndo).toBe(false);
 		});
 	});
+
+	describe("session debouncing", () => {
+		test("multiple saveSession calls within debounce window only write once", async () => {
+			let writeCount = 0;
+			// biome-ignore lint/suspicious/noExplicitAny: test mock requires any
+			const originalWrite = (Bun as any).write;
+
+			// Mock Bun.write to count session.json writes
+			// biome-ignore lint/suspicious/noExplicitAny: test mock requires any
+			(Bun as any).write = async (...args: unknown[]) => {
+				if (String(args[0]).includes("session.json")) {
+					writeCount++;
+				}
+				return originalWrite.apply(Bun, args);
+			};
+
+			try {
+				// Set up a session ID to trigger saves
+				session.sessionId = "test-session-debounce-1";
+
+				// Call saveSession multiple times rapidly
+				// @ts-expect-error - accessing private for test
+				session.saveSession();
+				// @ts-expect-error - accessing private for test
+				session.saveSession();
+				// @ts-expect-error - accessing private for test
+				session.saveSession();
+
+				// Immediately after calls, write should not have happened yet (debounced)
+				expect(writeCount).toBe(0);
+
+				// Wait for debounce timeout (500ms + buffer)
+				await Bun.sleep(600);
+
+				// Now exactly one write should have occurred
+				expect(writeCount).toBe(1);
+			} finally {
+				// Restore original Bun.write
+				// biome-ignore lint/suspicious/noExplicitAny: test mock requires any
+				(Bun as any).write = originalWrite;
+			}
+		});
+
+		test("flushSession writes immediately", async () => {
+			let writeCount = 0;
+			// biome-ignore lint/suspicious/noExplicitAny: test mock requires any
+			const originalWrite = (Bun as any).write;
+
+			// Mock Bun.write to count session.json writes
+			// biome-ignore lint/suspicious/noExplicitAny: test mock requires any
+			(Bun as any).write = async (...args: unknown[]) => {
+				if (String(args[0]).includes("session.json")) {
+					writeCount++;
+				}
+				return originalWrite.apply(Bun, args);
+			};
+
+			try {
+				// Set up a session ID to trigger saves
+				session.sessionId = "test-session-flush-1";
+
+				// Call flushSession for immediate write
+				session.flushSession();
+
+				// Write should happen immediately (synchronously)
+				expect(writeCount).toBe(1);
+			} finally {
+				// Restore original Bun.write
+				// biome-ignore lint/suspicious/noExplicitAny: test mock requires any
+				(Bun as any).write = originalWrite;
+			}
+		});
+	});
 });

package/src/__tests__/telegram-api.test.ts

@@ -0,0 +1,80 @@
+/**
+ * Unit tests for Telegram API utilities.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { TelegramApiError, withRetry } from "../telegram-api";
+
+describe("withRetry", () => {
+	test("succeeds on first attempt", async () => {
+		let attempts = 0;
+		const result = await withRetry(async () => {
+			attempts++;
+			return "success";
+		});
+		expect(result).toBe("success");
+		expect(attempts).toBe(1);
+	});
+
+	test("retries on transient failure then succeeds", async () => {
+		let attempts = 0;
+		const result = await withRetry(
+			async () => {
+				attempts++;
+				if (attempts < 3) {
+					throw new Error("Too Many Requests: retry after 1");
+				}
+				return "success";
+			},
+			{ maxRetries: 3, baseDelay: 10 },
+		);
+		expect(result).toBe("success");
+		expect(attempts).toBe(3);
+	});
+
+	test("throws after max retries", async () => {
+		let attempts = 0;
+		await expect(
+			withRetry(
+				async () => {
+					attempts++;
+					throw new Error("Too Many Requests: retry after 1");
+				},
+				{ maxRetries: 2, baseDelay: 10 },
+			),
+		).rejects.toThrow();
+		expect(attempts).toBe(2);
+	});
+
+	test("does not retry non-transient errors", async () => {
+		let attempts = 0;
+		await expect(
+			withRetry(
+				async () => {
+					attempts++;
+					throw new Error("Bad Request: message not found");
+				},
+				{ maxRetries: 3, baseDelay: 10 },
+			),
+		).rejects.toThrow("Bad Request");
+		expect(attempts).toBe(1);
+	});
+});
+
+describe("TelegramApiError", () => {
+	test("isTransient returns true for rate limit errors", () => {
+		const error = new TelegramApiError("Too Many Requests: retry after 5", 429);
+		expect(error.isTransient).toBe(true);
+		expect(error.retryAfter).toBe(5);
+	});
+
+	test("isTransient returns true for network errors", () => {
+		const error = new TelegramApiError("ETIMEDOUT", 0);
+		expect(error.isTransient).toBe(true);
+	});
+
+	test("isTransient returns false for bad request", () => {
+		const error = new TelegramApiError("Bad Request: message not found", 400);
+		expect(error.isTransient).toBe(false);
+	});
+});

package/src/errors.ts

@@ -0,0 +1,58 @@
+/**
+ * User-friendly error message formatting.
+ */
+
+interface ErrorPattern {
+	pattern: RegExp;
+	message: string;
+}
+
+const ERROR_PATTERNS: ErrorPattern[] = [
+	{
+		pattern: /timeout/i,
+		message:
+			"The operation took too long. Try a simpler request or break it into smaller steps.",
+	},
+	{
+		pattern: /too many requests|rate limit|retry after/i,
+		message: "Claude is busy right now. Please wait a moment and try again.",
+	},
+	{
+		pattern: /etimedout|econnreset|enotfound/i,
+		message: "Connection issue. Please check your network and try again.",
+	},
+	{
+		pattern: /cancelled|aborted/i,
+		message: "Request was cancelled.",
+	},
+	{
+		pattern: /unsafe command|blocked/i,
+		message: "That operation isn't allowed for safety reasons.",
+	},
+	{
+		pattern: /file access|outside allowed paths/i,
+		message: "Claude can't access that file location.",
+	},
+	{
+		pattern: /authentication|unauthorized|401/i,
+		message: "Authentication issue. Please check your credentials.",
+	},
+];
+
+/**
+ * Convert technical errors to user-friendly messages.
+ */
+export function formatUserError(error: Error): string {
+	const errorStr = error.message || String(error);
+
+	for (const { pattern, message } of ERROR_PATTERNS) {
+		if (pattern.test(errorStr)) {
+			return message;
+		}
+	}
+
+	// Generic fallback with truncation
+	const truncated =
+		errorStr.length > 200 ? errorStr.slice(0, 200) + "..." : errorStr;
+	return `Error: ${truncated || "An unexpected error occurred"}`;
+}

package/src/events.ts

@@ -0,0 +1,57 @@
+/**
+ * Lightweight event emitter for decoupling modules.
+ * Eliminates circular dependencies between session and utils.
+ */
+
+type EventCallback<T> = (data: T) => void;
+
+interface BotEventsMap {
+	sessionRunning: boolean;
+	stopRequested: undefined;
+	interruptRequested: undefined;
+}
+
+class BotEventEmitter {
+	private listeners = new Map<
+		keyof BotEventsMap,
+		Set<EventCallback<unknown>>
+	>();
+	private sessionRunning = false;
+
+	on<K extends keyof BotEventsMap>(
+		event: K,
+		callback: EventCallback<BotEventsMap[K]>,
+	): () => void {
+		if (!this.listeners.has(event)) {
+			this.listeners.set(event, new Set());
+		}
+		this.listeners.get(event)?.add(callback as EventCallback<unknown>);
+
+		return () => {
+			this.listeners.get(event)?.delete(callback as EventCallback<unknown>);
+		};
+	}
+
+	emit<K extends keyof BotEventsMap>(event: K, data: BotEventsMap[K]): void {
+		if (event === "sessionRunning") {
+			this.sessionRunning = data as boolean;
+		}
+
+		const callbacks = this.listeners.get(event);
+		if (callbacks) {
+			for (const callback of callbacks) {
+				try {
+					callback(data);
+				} catch (error) {
+					console.error(`Event handler error for ${event}:`, error);
+				}
+			}
+		}
+	}
+
+	getSessionState(): boolean {
+		return this.sessionRunning;
+	}
+}
+
+export const botEvents = new BotEventEmitter();

package/src/handlers/streaming.ts

@@ -14,6 +14,7 @@ import {
 	TELEGRAM_SAFE_LIMIT,
 } from "../config";
 import { convertMarkdownToHtml, escapeHtml } from "../formatting";
+import { safeTelegramCall } from "../telegram-api";
 import type { StatusCallback } from "../types";
 
 /**
@@ -87,6 +88,7 @@ export class StreamingState {
 	toolMessages: Message[] = []; // ephemeral tool status messages
 	lastEditTimes = new Map<number, number>(); // segment_id -> last edit time
 	lastContent = new Map<number, string>(); // segment_id -> last sent content
+	toolStartTime: number | null = null; // timestamp when current tool started
 }
 
 /**
@@ -108,6 +110,7 @@ export function createStatusCallback(
 				});
 				state.toolMessages.push(thinkingMsg);
 			} else if (statusType === "tool") {
+				state.toolStartTime = Date.now();
 				const toolMsg = await ctx.reply(content, { parse_mode: "HTML" });
 				state.toolMessages.push(toolMsg);
 			} else if (statusType === "text" && segmentId !== undefined) {
@@ -145,28 +148,28 @@ export function createStatusCallback(
 					if (formatted === state.lastContent.get(segmentId)) {
 						return;
 					}
-					try {
-						await ctx.api.editMessageText(
-							msg.chat.id,
-							msg.message_id,
-							formatted,
-							{
-								parse_mode: "HTML",
-							},
-						);
-						state.lastContent.set(segmentId, formatted);
-					} catch (htmlError) {
-						console.debug("HTML edit failed, trying plain text:", htmlError);
+					const editResult = await safeTelegramCall("editMessage", async () => {
 						try {
 							await ctx.api.editMessageText(
 								msg.chat.id,
 								msg.message_id,
 								formatted,
+								{ parse_mode: "HTML" },
 							);
-							state.lastContent.set(segmentId, formatted);
-						} catch (editError) {
-							console.debug("Edit message failed:", editError);
+							return true;
+						} catch (htmlError) {
+							// HTML parse failed, try plain text
+							console.debug("HTML edit failed, trying plain text:", htmlError);
+							await ctx.api.editMessageText(
+								msg.chat.id,
+								msg.message_id,
+								formatted,
+							);
+							return true;
 						}
+					});
+					if (editResult) {
+						state.lastContent.set(segmentId, formatted);
 					}
 					state.lastEditTimes.set(segmentId, now);
 				}
@@ -181,18 +184,11 @@ export function createStatusCallback(
 					}
 
 					if (formatted.length <= TELEGRAM_MESSAGE_LIMIT) {
-						try {
-							await ctx.api.editMessageText(
-								msg.chat.id,
-								msg.message_id,
-								formatted,
-								{
-									parse_mode: "HTML",
-								},
-							);
-						} catch (error) {
-							console.debug("Failed to edit final message:", error);
-						}
+						await safeTelegramCall("editFinalMessage", () =>
+							ctx.api.editMessageText(msg.chat.id, msg.message_id, formatted, {
+								parse_mode: "HTML",
+							}),
+						);
 					} else {
 						// Too long - delete and split
 						try {

package/src/handlers/text.ts

@@ -5,6 +5,7 @@
 import { spawn } from "node:child_process";
 import type { Context } from "grammy";
 import { ALLOWED_USERS } from "../config";
+import { formatUserError } from "../errors";
 import { isAuthorized, rateLimiter } from "../security";
 import { session } from "../session";
 import {
@@ -194,7 +195,7 @@ export async function handleText(ctx: Context): Promise<void> {
 					await ctx.reply("🛑 Query stopped.");
 				}
 			} else {
-				await ctx.reply(`❌ Error: ${errorStr.slice(0, 200)}`);
+				await ctx.reply(`❌ ${formatUserError(error as Error)}`);
 			}
 			break; // Exit loop after handling error
 		}

package/src/index.ts

@@ -37,6 +37,7 @@ import {
 	handleUndo,
 	handleVoice,
 } from "./handlers";
+import { session } from "./session";
 
 // Create bot instance
 const bot = new Bot(TELEGRAM_TOKEN);
@@ -149,21 +150,38 @@ if (existsSync(RESTART_FILE)) {
 const runner = run(bot);
 
 // Graceful shutdown
-const stopRunner = () => {
-	if (runner.isRunning()) {
-		console.log("Stopping bot...");
-		runner.stop();
-	}
-};
+const SHUTDOWN_TIMEOUT_MS = 5000;
 
-process.on("SIGINT", () => {
-	console.log("Received SIGINT");
-	stopRunner();
-	process.exit(0);
-});
+async function gracefulShutdown(signal: string): Promise<void> {
+	console.log(`\n${signal} received - initiating graceful shutdown...`);
 
-process.on("SIGTERM", () => {
-	console.log("Received SIGTERM");
-	stopRunner();
-	process.exit(0);
-});
+	// Set a hard timeout
+	const forceExit = setTimeout(() => {
+		console.error("Shutdown timeout - forcing exit");
+		process.exit(1);
+	}, SHUTDOWN_TIMEOUT_MS);
+
+	try {
+		// Stop the runner (stops polling)
+		if (runner.isRunning()) {
+			runner.stop();
+			console.log("Bot stopped");
+		}
+
+		// Flush session data
+		session.flushSession();
+		console.log("Session flushed");
+
+		// Clear the timeout and exit cleanly
+		clearTimeout(forceExit);
+		console.log("Shutdown complete");
+		process.exit(0);
+	} catch (error) {
+		console.error("Error during shutdown:", error);
+		clearTimeout(forceExit);
+		process.exit(1);
+	}
+}
+
+process.on("SIGINT", () => gracefulShutdown("SIGINT"));
+process.on("SIGTERM", () => gracefulShutdown("SIGTERM"));

package/src/session.ts

@@ -25,11 +25,14 @@ import {
 	THINKING_KEYWORDS,
 	WORKING_DIR,
 } from "./config";
+import { botEvents } from "./events";
 import { formatToolStatus } from "./formatting";
 import { checkPendingAskUserRequests } from "./handlers/streaming";
 import { checkCommandSafety, isPathAllowed } from "./security";
 import type { SessionData, StatusCallback, TokenUsage } from "./types";
 
+const SESSION_VERSION = 1;
+
 /**
  * Determine thinking token budget based on message keywords.
  * Exported for testing.
@@ -96,6 +99,11 @@ class ClaudeSession {
 	private _queryInstance: Query | null = null;
 	private _userMessageUuids: string[] = [];
 
+	// Debounced session saving
+	private _saveTimeout: ReturnType<typeof setTimeout> | null = null;
+	private _pendingSave = false;
+	private readonly SAVE_DEBOUNCE_MS = 500;
+
 	// Mutable working directory (can be changed with /cd)
 	private _workingDir: string = WORKING_DIR;
 
@@ -105,6 +113,15 @@ class ClaudeSession {
 	private _isProcessing = false;
 	private _wasInterruptedByNewMessage = false;
 
+	constructor() {
+		botEvents.on("interruptRequested", () => {
+			if (this.isRunning) {
+				this.markInterrupt();
+				this.stop();
+			}
+		});
+	}
+
 	get workingDir(): string {
 		return this._workingDir;
 	}
@@ -293,6 +310,7 @@ class ClaudeSession {
 		// Create abort controller for cancellation
 		this.abortController = new AbortController();
 		this.isQueryRunning = true;
+		botEvents.emit("sessionRunning", true);
 		this.stopRequested = false;
 		this.queryStarted = new Date();
 		this.currentTool = null;
@@ -511,6 +529,7 @@ class ClaudeSession {
 			}
 		} finally {
 			this.isQueryRunning = false;
+			botEvents.emit("sessionRunning", false);
 			this.abortController = null;
 			this.queryStarted = null;
 			this.currentTool = null;
@@ -630,13 +649,34 @@ class ClaudeSession {
 	}
 
 	/**
-	 * Save session to disk for resume after restart.
+	 * Save session to disk for resume after restart (debounced).
+	 * Multiple calls within SAVE_DEBOUNCE_MS will only result in one write.
 	 */
 	private saveSession(): void {
 		if (!this.sessionId) return;
 
+		this._pendingSave = true;
+
+		// Clear existing timeout if any
+		if (this._saveTimeout) {
+			clearTimeout(this._saveTimeout);
+		}
+
+		// Schedule the actual write
+		this._saveTimeout = setTimeout(() => {
+			this._doSaveSession();
+		}, this.SAVE_DEBOUNCE_MS);
+	}
+
+	/**
+	 * Actually perform the session write to disk.
+	 */
+	private _doSaveSession(): void {
+		if (!this.sessionId || !this._pendingSave) return;
+
 		try {
 			const data: SessionData = {
+				version: SESSION_VERSION,
 				session_id: this.sessionId,
 				saved_at: new Date().toISOString(),
 				working_dir: this._workingDir,
@@ -645,6 +685,25 @@ class ClaudeSession {
 			console.log(`Session saved to ${SESSION_FILE}`);
 		} catch (error) {
 			console.warn(`Failed to save session: ${error}`);
+		} finally {
+			this._pendingSave = false;
+			this._saveTimeout = null;
+		}
+	}
+
+	/**
+	 * Immediately flush any pending session save to disk.
+	 * Use this for graceful shutdown to ensure session is persisted.
+	 */
+	flushSession(): void {
+		if (this._saveTimeout) {
+			clearTimeout(this._saveTimeout);
+			this._saveTimeout = null;
+		}
+
+		if (this._pendingSave || this.sessionId) {
+			this._pendingSave = true; // Ensure _doSaveSession runs
+			this._doSaveSession();
 		}
 	}
 
@@ -665,6 +724,13 @@ class ClaudeSession {
 				return [false, "Saved session file is empty"];
 			}
 
+			if (data.version !== SESSION_VERSION) {
+				return [
+					false,
+					`Session version mismatch (found v${data.version ?? 0}, expected v${SESSION_VERSION})`,
+				];
+			}
+
 			if (data.working_dir && data.working_dir !== this._workingDir) {
 				return [
 					false,