ctb 1.1.0 → 1.3.0

package/package.json

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

package/src/__tests__/cli.test.ts

@@ -180,6 +180,7 @@ describe("CLI argument parsing", () => {
 		dir?: string;
 		help?: boolean;
 		version?: boolean;
+		tut?: boolean;
 	} {
 		const options: {
 			token?: string;
@@ -187,6 +188,7 @@ describe("CLI argument parsing", () => {
 			dir?: string;
 			help?: boolean;
 			version?: boolean;
+			tut?: boolean;
 		} = {};
 
 		for (const arg of args) {
@@ -194,6 +196,8 @@ describe("CLI argument parsing", () => {
 				options.help = true;
 			} else if (arg === "--version" || arg === "-v") {
 				options.version = true;
+			} else if (arg === "tut" || arg === "tutorial") {
+				options.tut = true;
 			} else if (arg.startsWith("--token=")) {
 				options.token = arg.slice(8);
 			} else if (arg.startsWith("--users=")) {
@@ -222,6 +226,14 @@ describe("CLI argument parsing", () => {
 		expect(parseArgs(["-v"])).toEqual({ version: true });
 	});
 
+	test("parses tut command", () => {
+		expect(parseArgs(["tut"])).toEqual({ tut: true });
+	});
+
+	test("parses tutorial command", () => {
+		expect(parseArgs(["tutorial"])).toEqual({ tut: true });
+	});
+
 	test("parses --token option", () => {
 		const result = parseArgs(["--token=my-bot-token"]);
 		expect(result.token).toBe("my-bot-token");

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

@@ -0,0 +1,472 @@
+/**
+ * Unit tests for session module - model, cost, thinking, and plan mode features.
+ */
+
+import { beforeEach, describe, expect, test } from "bun:test";
+import { ClaudeSession, getThinkingLevel } from "../session";
+
+describe("getThinkingLevel", () => {
+	// Default keywords from config.ts:
+	// THINKING_KEYWORDS: "think,pensa,ragiona"
+	// THINKING_DEEP_KEYWORDS: "ultrathink,think hard,pensa bene"
+
+	describe("deep thinking triggers", () => {
+		test("triggers on 'think hard'", () => {
+			expect(getThinkingLevel("Please think hard about this")).toBe(50000);
+		});
+
+		test("triggers on 'ultrathink'", () => {
+			expect(getThinkingLevel("ultrathink about the problem")).toBe(50000);
+		});
+
+		test("triggers on 'pensa bene' (Italian)", () => {
+			expect(getThinkingLevel("pensa bene prima di rispondere")).toBe(50000);
+		});
+
+		test("is case insensitive", () => {
+			expect(getThinkingLevel("THINK HARD about this")).toBe(50000);
+			expect(getThinkingLevel("ULTRATHINK")).toBe(50000);
+		});
+	});
+
+	describe("normal thinking triggers", () => {
+		test("triggers on 'think'", () => {
+			expect(getThinkingLevel("Let me think about this")).toBe(10000);
+		});
+
+		test("triggers on 'pensa' (Italian)", () => {
+			expect(getThinkingLevel("pensa a questo problema")).toBe(10000);
+		});
+
+		test("triggers on 'ragiona' (Italian)", () => {
+			expect(getThinkingLevel("ragiona sul codice")).toBe(10000);
+		});
+
+		test("is case insensitive", () => {
+			expect(getThinkingLevel("THINK about it")).toBe(10000);
+			expect(getThinkingLevel("PENSA attentamente")).toBe(10000);
+		});
+	});
+
+	describe("no thinking triggers", () => {
+		test("returns 0 for simple messages", () => {
+			expect(getThinkingLevel("Hello")).toBe(0);
+			expect(getThinkingLevel("What time is it?")).toBe(0);
+			expect(getThinkingLevel("Show me the file")).toBe(0);
+		});
+
+		test("returns 0 for empty string", () => {
+			expect(getThinkingLevel("")).toBe(0);
+		});
+
+		test("returns 0 for unrelated words", () => {
+			expect(getThinkingLevel("analyze this code")).toBe(0);
+			expect(getThinkingLevel("consider the options")).toBe(0);
+			expect(getThinkingLevel("evaluate this approach")).toBe(0);
+		});
+	});
+
+	describe("priority", () => {
+		test("deep triggers take precedence over normal", () => {
+			// "think hard" should trigger deep (50000), not normal "think" (10000)
+			expect(getThinkingLevel("think hard")).toBe(50000);
+		});
+	});
+});
+
+describe("ClaudeSession", () => {
+	let session: ClaudeSession;
+
+	beforeEach(() => {
+		session = new ClaudeSession();
+	});
+
+	describe("model selection", () => {
+		test("defaults to sonnet", () => {
+			expect(session.currentModel).toBe("sonnet");
+		});
+
+		test("can be set to opus", () => {
+			session.currentModel = "opus";
+			expect(session.currentModel).toBe("opus");
+		});
+
+		test("can be set to haiku", () => {
+			session.currentModel = "haiku";
+			expect(session.currentModel).toBe("haiku");
+		});
+
+		test("can switch between models", () => {
+			session.currentModel = "opus";
+			expect(session.currentModel).toBe("opus");
+
+			session.currentModel = "haiku";
+			expect(session.currentModel).toBe("haiku");
+
+			session.currentModel = "sonnet";
+			expect(session.currentModel).toBe("sonnet");
+		});
+	});
+
+	describe("forceThinking", () => {
+		test("defaults to null", () => {
+			expect(session.forceThinking).toBeNull();
+		});
+
+		test("can be set to specific token count", () => {
+			session.forceThinking = 10000;
+			expect(session.forceThinking).toBe(10000);
+		});
+
+		test("can be set to 0 (off)", () => {
+			session.forceThinking = 0;
+			expect(session.forceThinking).toBe(0);
+		});
+
+		test("can be set to deep (50000)", () => {
+			session.forceThinking = 50000;
+			expect(session.forceThinking).toBe(50000);
+		});
+	});
+
+	describe("planMode", () => {
+		test("defaults to false", () => {
+			expect(session.planMode).toBe(false);
+		});
+
+		test("can be toggled on", () => {
+			session.planMode = true;
+			expect(session.planMode).toBe(true);
+		});
+
+		test("can be toggled off", () => {
+			session.planMode = true;
+			session.planMode = false;
+			expect(session.planMode).toBe(false);
+		});
+	});
+
+	describe("token usage tracking", () => {
+		test("starts with zero totals", () => {
+			expect(session.totalInputTokens).toBe(0);
+			expect(session.totalOutputTokens).toBe(0);
+			expect(session.totalCacheReadTokens).toBe(0);
+		});
+
+		test("can accumulate input tokens", () => {
+			session.totalInputTokens += 1000;
+			session.totalInputTokens += 500;
+			expect(session.totalInputTokens).toBe(1500);
+		});
+
+		test("can accumulate output tokens", () => {
+			session.totalOutputTokens += 2000;
+			session.totalOutputTokens += 800;
+			expect(session.totalOutputTokens).toBe(2800);
+		});
+
+		test("can accumulate cache read tokens", () => {
+			session.totalCacheReadTokens += 500;
+			session.totalCacheReadTokens += 300;
+			expect(session.totalCacheReadTokens).toBe(800);
+		});
+	});
+
+	describe("estimateCost", () => {
+		describe("sonnet pricing", () => {
+			test("calculates zero cost for zero tokens", () => {
+				const cost = session.estimateCost();
+				expect(cost.inputCost).toBe(0);
+				expect(cost.outputCost).toBe(0);
+				expect(cost.total).toBe(0);
+			});
+
+			test("calculates cost for 1M input tokens", () => {
+				session.totalInputTokens = 1_000_000;
+				const cost = session.estimateCost();
+				expect(cost.inputCost).toBe(3); // $3 per 1M input
+				expect(cost.outputCost).toBe(0);
+				expect(cost.total).toBe(3);
+			});
+
+			test("calculates cost for 1M output tokens", () => {
+				session.totalOutputTokens = 1_000_000;
+				const cost = session.estimateCost();
+				expect(cost.inputCost).toBe(0);
+				expect(cost.outputCost).toBe(15); // $15 per 1M output
+				expect(cost.total).toBe(15);
+			});
+
+			test("calculates combined cost", () => {
+				session.totalInputTokens = 500_000;
+				session.totalOutputTokens = 100_000;
+				const cost = session.estimateCost();
+				expect(cost.inputCost).toBe(1.5); // $3 * 0.5
+				expect(cost.outputCost).toBe(1.5); // $15 * 0.1
+				expect(cost.total).toBe(3);
+			});
+		});
+
+		describe("opus pricing", () => {
+			beforeEach(() => {
+				session.currentModel = "opus";
+			});
+
+			test("calculates cost for 1M input tokens", () => {
+				session.totalInputTokens = 1_000_000;
+				const cost = session.estimateCost();
+				expect(cost.inputCost).toBe(15); // $15 per 1M input
+			});
+
+			test("calculates cost for 1M output tokens", () => {
+				session.totalOutputTokens = 1_000_000;
+				const cost = session.estimateCost();
+				expect(cost.outputCost).toBe(75); // $75 per 1M output
+			});
+
+			test("calculates combined cost", () => {
+				session.totalInputTokens = 100_000;
+				session.totalOutputTokens = 50_000;
+				const cost = session.estimateCost();
+				expect(cost.inputCost).toBe(1.5); // $15 * 0.1
+				expect(cost.outputCost).toBe(3.75); // $75 * 0.05
+				expect(cost.total).toBe(5.25);
+			});
+		});
+
+		describe("haiku pricing", () => {
+			beforeEach(() => {
+				session.currentModel = "haiku";
+			});
+
+			test("calculates cost for 1M input tokens", () => {
+				session.totalInputTokens = 1_000_000;
+				const cost = session.estimateCost();
+				expect(cost.inputCost).toBe(0.25); // $0.25 per 1M input
+			});
+
+			test("calculates cost for 1M output tokens", () => {
+				session.totalOutputTokens = 1_000_000;
+				const cost = session.estimateCost();
+				expect(cost.outputCost).toBe(1.25); // $1.25 per 1M output
+			});
+
+			test("calculates combined cost", () => {
+				session.totalInputTokens = 4_000_000;
+				session.totalOutputTokens = 800_000;
+				const cost = session.estimateCost();
+				expect(cost.inputCost).toBe(1); // $0.25 * 4
+				expect(cost.outputCost).toBe(1); // $1.25 * 0.8
+				expect(cost.total).toBe(2);
+			});
+		});
+
+		describe("small token counts", () => {
+			test("calculates fractional costs", () => {
+				session.totalInputTokens = 1000;
+				session.totalOutputTokens = 500;
+				const cost = session.estimateCost();
+				expect(cost.inputCost).toBeCloseTo(0.003, 5); // $3 * 0.001
+				expect(cost.outputCost).toBeCloseTo(0.0075, 5); // $15 * 0.0005
+				expect(cost.total).toBeCloseTo(0.0105, 5);
+			});
+		});
+	});
+
+	describe("kill", () => {
+		test("resets sessionId", async () => {
+			session.sessionId = "test-session-123";
+			await session.kill();
+			expect(session.sessionId).toBeNull();
+		});
+
+		test("resets lastActivity", async () => {
+			session.lastActivity = new Date();
+			await session.kill();
+			expect(session.lastActivity).toBeNull();
+		});
+
+		test("resets token totals", async () => {
+			session.totalInputTokens = 10000;
+			session.totalOutputTokens = 5000;
+			session.totalCacheReadTokens = 2000;
+			await session.kill();
+			expect(session.totalInputTokens).toBe(0);
+			expect(session.totalOutputTokens).toBe(0);
+			expect(session.totalCacheReadTokens).toBe(0);
+		});
+
+		test("resets planMode", async () => {
+			session.planMode = true;
+			await session.kill();
+			expect(session.planMode).toBe(false);
+		});
+
+		test("resets forceThinking", async () => {
+			session.forceThinking = 50000;
+			await session.kill();
+			expect(session.forceThinking).toBeNull();
+		});
+
+		test("preserves currentModel", async () => {
+			session.currentModel = "opus";
+			await session.kill();
+			expect(session.currentModel).toBe("opus");
+		});
+	});
+
+	describe("isActive", () => {
+		test("returns false when no sessionId", () => {
+			expect(session.isActive).toBe(false);
+		});
+
+		test("returns true when sessionId exists", () => {
+			session.sessionId = "test-session-123";
+			expect(session.isActive).toBe(true);
+		});
+	});
+
+	describe("workingDir", () => {
+		test("can get working directory", () => {
+			expect(typeof session.workingDir).toBe("string");
+		});
+
+		test("setWorkingDir changes directory", () => {
+			const newDir = "/tmp/test-dir";
+			session.setWorkingDir(newDir);
+			expect(session.workingDir).toBe(newDir);
+		});
+
+		test("setWorkingDir clears sessionId", () => {
+			session.sessionId = "test-session-123";
+			session.setWorkingDir("/tmp/new-dir");
+			expect(session.sessionId).toBeNull();
+		});
+	});
+
+	describe("stop", () => {
+		test("returns false when nothing is running", async () => {
+			const result = await session.stop();
+			expect(result).toBe(false);
+		});
+	});
+
+	describe("interrupt flags", () => {
+		test("markInterrupt and consumeInterruptFlag work together", () => {
+			expect(session.consumeInterruptFlag()).toBe(false);
+			session.markInterrupt();
+			expect(session.consumeInterruptFlag()).toBe(true);
+			expect(session.consumeInterruptFlag()).toBe(false); // Consumed
+		});
+	});
+
+	describe("processing state", () => {
+		test("startProcessing returns cleanup function", () => {
+			expect(session.isRunning).toBe(false);
+			const cleanup = session.startProcessing();
+			expect(session.isRunning).toBe(true);
+			cleanup();
+			expect(session.isRunning).toBe(false);
+		});
+	});
+
+	describe("undo/checkpointing", () => {
+		test("canUndo is false by default", () => {
+			expect(session.canUndo).toBe(false);
+		});
+
+		test("undoCheckpoints is 0 by default", () => {
+			expect(session.undoCheckpoints).toBe(0);
+		});
+
+		test("undo fails when no session active", async () => {
+			const [success, message] = await session.undo();
+			expect(success).toBe(false);
+			expect(message).toContain("No active session");
+		});
+
+		test("kill resets checkpoints", async () => {
+			// Simulate having checkpoints (by accessing private property for testing)
+			// @ts-expect-error - accessing private for test
+			session._userMessageUuids = ["uuid1", "uuid2"];
+			expect(session.undoCheckpoints).toBe(2);
+
+			await session.kill();
+			expect(session.undoCheckpoints).toBe(0);
+			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);
+	});
+});