@locusai/locus-telegram 0.21.6

package/dist/ui/format.js

@@ -0,0 +1,100 @@
+/**
+ * Output formatting utilities for Telegram messages.
+ *
+ * Telegram supports a subset of Markdown (MarkdownV2) and HTML.
+ * We use HTML mode for reliability — fewer escaping issues than MarkdownV2.
+ */
+/** Maximum Telegram message length (4096 chars). */
+const MAX_MESSAGE_LENGTH = 4096;
+/** Maximum length for a code block inside a message. */
+const MAX_CODE_LENGTH = 3800;
+/** Escape HTML special characters for Telegram HTML mode. */
+export function escapeHtml(text) {
+    return text
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;");
+}
+/** Wrap text in a code block. */
+export function codeBlock(text, language = "") {
+    const truncated = truncate(text, MAX_CODE_LENGTH);
+    return `<pre><code${language ? ` class="language-${language}"` : ""}>${escapeHtml(truncated)}</code></pre>`;
+}
+/** Wrap text in inline code. */
+export function inlineCode(text) {
+    return `<code>${escapeHtml(text)}</code>`;
+}
+/** Bold text. */
+export function bold(text) {
+    return `<b>${text}</b>`;
+}
+/** Italic text. */
+export function italic(text) {
+    return `<i>${text}</i>`;
+}
+/** Truncate text to a max length, appending "..." if truncated. */
+export function truncate(text, maxLength = MAX_MESSAGE_LENGTH) {
+    if (text.length <= maxLength)
+        return text;
+    return `${text.slice(0, maxLength - 20)}\n\n... (truncated)`;
+}
+/** Split long output into multiple messages if needed. */
+export function splitMessage(text) {
+    if (text.length <= MAX_MESSAGE_LENGTH)
+        return [text];
+    const chunks = [];
+    let remaining = text;
+    while (remaining.length > 0) {
+        if (remaining.length <= MAX_MESSAGE_LENGTH) {
+            chunks.push(remaining);
+            break;
+        }
+        // Try to split at a newline
+        let splitIdx = remaining.lastIndexOf("\n", MAX_MESSAGE_LENGTH);
+        if (splitIdx === -1 || splitIdx < MAX_MESSAGE_LENGTH / 2) {
+            splitIdx = MAX_MESSAGE_LENGTH;
+        }
+        chunks.push(remaining.slice(0, splitIdx));
+        remaining = remaining.slice(splitIdx);
+    }
+    return chunks;
+}
+/** Format a command result as a Telegram message. */
+export function formatCommandResult(command, output, exitCode) {
+    const status = exitCode === 0 ? "✅" : "❌";
+    const header = `${status} ${bold(escapeHtml(command))}`;
+    if (!output.trim()) {
+        return exitCode === 0
+            ? `${header}\n\nCompleted successfully.`
+            : `${header}\n\nFailed with exit code ${exitCode}.`;
+    }
+    return `${header}\n\n${codeBlock(output.trim())}`;
+}
+/** Format a streaming progress message. */
+export function formatStreamingMessage(command, output, isComplete) {
+    const status = isComplete ? "✅" : "⏳";
+    const header = `${status} ${bold(escapeHtml(command))}`;
+    if (!output.trim()) {
+        return `${header}\n\n${italic("Running...")}`;
+    }
+    // Take last N lines for streaming display
+    const lines = output.trim().split("\n");
+    const lastLines = lines.slice(-30).join("\n");
+    return `${header}\n\n${codeBlock(lastLines)}`;
+}
+/** Format an error message. */
+export function formatError(message, detail) {
+    let text = `❌ ${bold("Error")}\n\n${escapeHtml(message)}`;
+    if (detail) {
+        text += `\n\n${codeBlock(detail)}`;
+    }
+    return text;
+}
+/** Format a success message. */
+export function formatSuccess(message) {
+    return `✅ ${escapeHtml(message)}`;
+}
+/** Format an info message. */
+export function formatInfo(message) {
+    return `ℹ️ ${escapeHtml(message)}`;
+}

package/dist/ui/keyboards.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Inline keyboard builders for interactive Telegram responses.
+ *
+ * Keyboards are attached to messages to let users take actions
+ * without typing commands manually.
+ */
+import { InlineKeyboard } from "grammy";
+export declare const CB: {
+    readonly APPROVE_PLAN: "plan:approve";
+    readonly REJECT_PLAN: "plan:reject";
+    readonly SHOW_PLAN_DETAILS: "plan:details";
+    readonly CONFIRM_ACTION: "confirm:yes";
+    readonly CANCEL_ACTION: "confirm:no";
+    readonly VIEW_PR: "pr:view:";
+    readonly VIEW_LOGS: "logs:view";
+    readonly RUN_AGAIN: "run:again:";
+    readonly APPROVE_REVIEW: "review:approve:";
+    readonly REQUEST_CHANGES: "review:changes:";
+    readonly VIEW_DIFF: "review:diff:";
+    readonly RUN_SPRINT: "sprint:run";
+    readonly VIEW_ISSUES: "issues:view";
+    readonly STASH_POP: "stash:pop";
+    readonly STASH_LIST: "stash:list";
+    readonly STASH_DROP: "stash:drop";
+};
+/** Keyboard shown after plan creation. */
+export declare function planKeyboard(): InlineKeyboard;
+/** Keyboard shown after a run completes. */
+export declare function runCompleteKeyboard(issueNumber?: number): InlineKeyboard;
+/** Keyboard shown after review. */
+export declare function reviewKeyboard(prNumber: number): InlineKeyboard;
+/** Confirmation keyboard for destructive operations. */
+export declare function confirmKeyboard(): InlineKeyboard;
+/** Keyboard shown after status check. */
+export declare function statusKeyboard(): InlineKeyboard;
+/** Keyboard for stash operations. */
+export declare function stashKeyboard(): InlineKeyboard;

package/dist/ui/keyboards.js

@@ -0,0 +1,73 @@
+/**
+ * Inline keyboard builders for interactive Telegram responses.
+ *
+ * Keyboards are attached to messages to let users take actions
+ * without typing commands manually.
+ */
+import { InlineKeyboard } from "grammy";
+// ─── Callback Data Prefixes ─────────────────────────────────────────────────
+export const CB = {
+    APPROVE_PLAN: "plan:approve",
+    REJECT_PLAN: "plan:reject",
+    SHOW_PLAN_DETAILS: "plan:details",
+    CONFIRM_ACTION: "confirm:yes",
+    CANCEL_ACTION: "confirm:no",
+    VIEW_PR: "pr:view:",
+    VIEW_LOGS: "logs:view",
+    RUN_AGAIN: "run:again:",
+    APPROVE_REVIEW: "review:approve:",
+    REQUEST_CHANGES: "review:changes:",
+    VIEW_DIFF: "review:diff:",
+    RUN_SPRINT: "sprint:run",
+    VIEW_ISSUES: "issues:view",
+    STASH_POP: "stash:pop",
+    STASH_LIST: "stash:list",
+    STASH_DROP: "stash:drop",
+};
+// ─── Keyboard Builders ──────────────────────────────────────────────────────
+/** Keyboard shown after plan creation. */
+export function planKeyboard() {
+    return new InlineKeyboard()
+        .text("✅ Approve Plan", CB.APPROVE_PLAN)
+        .text("❌ Reject Plan", CB.REJECT_PLAN)
+        .row()
+        .text("📋 Show Details", CB.SHOW_PLAN_DETAILS);
+}
+/** Keyboard shown after a run completes. */
+export function runCompleteKeyboard(issueNumber) {
+    const kb = new InlineKeyboard();
+    kb.text("📄 View Logs", CB.VIEW_LOGS);
+    if (issueNumber) {
+        kb.text("🔄 Run Again", `${CB.RUN_AGAIN}${issueNumber}`);
+    }
+    return kb;
+}
+/** Keyboard shown after review. */
+export function reviewKeyboard(prNumber) {
+    return new InlineKeyboard()
+        .text("✅ Approve", `${CB.APPROVE_REVIEW}${prNumber}`)
+        .text("🔄 Request Changes", `${CB.REQUEST_CHANGES}${prNumber}`)
+        .row()
+        .text("📝 View Diff", `${CB.VIEW_DIFF}${prNumber}`);
+}
+/** Confirmation keyboard for destructive operations. */
+export function confirmKeyboard() {
+    return new InlineKeyboard()
+        .text("✅ Confirm", CB.CONFIRM_ACTION)
+        .text("❌ Cancel", CB.CANCEL_ACTION);
+}
+/** Keyboard shown after status check. */
+export function statusKeyboard() {
+    return new InlineKeyboard()
+        .text("🚀 Run Sprint", CB.RUN_SPRINT)
+        .text("📋 Issues", CB.VIEW_ISSUES)
+        .row()
+        .text("📄 Logs", CB.VIEW_LOGS);
+}
+/** Keyboard for stash operations. */
+export function stashKeyboard() {
+    return new InlineKeyboard()
+        .text("📤 Pop", CB.STASH_POP)
+        .text("📋 List", CB.STASH_LIST)
+        .text("🗑 Drop", CB.STASH_DROP);
+}

package/dist/ui/messages.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Predefined response message templates for common bot interactions.
+ *
+ * All messages use HTML formatting for Telegram.
+ */
+export declare function welcomeMessage(): string;
+export declare function planCreatedMessage(planOutput: string): string;
+export declare function planApprovedMessage(): string;
+export declare function planRejectedMessage(): string;
+export declare function runStartedMessage(target: string): string;
+export declare function runCompletedMessage(target: string, prNumber?: number): string;
+export declare function runFailedMessage(target: string, error: string): string;
+export declare function reviewStartedMessage(prNumber: number): string;
+export declare function reviewCompletedMessage(prNumber: number, output: string): string;
+export declare function gitCommitMessage(message: string, hash: string): string;
+export declare function gitBranchCreatedMessage(name: string): string;
+export declare function gitCheckoutMessage(branch: string): string;
+export declare function gitStashMessage(action: string): string;
+export declare function prCreatedMessage(prNumber: number, url: string): string;
+export declare function serviceStatusMessage(status: string, pid: number | null, uptime: number | null, memory: number | null, restarts: number): string;
+export declare function serviceNotRunningMessage(): string;

package/dist/ui/messages.js

@@ -0,0 +1,155 @@
+/**
+ * Predefined response message templates for common bot interactions.
+ *
+ * All messages use HTML formatting for Telegram.
+ */
+import { bold, codeBlock, escapeHtml, italic } from "./format.js";
+// ─── Welcome & Help ─────────────────────────────────────────────────────────
+export function welcomeMessage() {
+    return [
+        `${bold("🤖 Locus Telegram Bot")}`,
+        "",
+        "Control your Locus agent directly from Telegram.",
+        "",
+        `${bold("Locus Commands")}`,
+        "/run [issue#...] — Execute issues",
+        "/status — Dashboard view",
+        "/issues [filters] — List issues",
+        "/issue <#> — Show issue details",
+        "/sprint [sub] — Sprint management",
+        "/plan [args] — AI planning",
+        "/review <pr#> — Code review",
+        "/iterate <pr#> — Re-execute with feedback",
+        "/discuss [topic] — AI discussion",
+        "/exec [prompt] — REPL / one-shot",
+        "/logs — View logs",
+        "/config [path] — View config",
+        "/artifacts — View artifacts",
+        "",
+        `${bold("Git Commands")}`,
+        "/gitstatus — Git status",
+        "/stage [files|.] — Stage files",
+        "/commit <message> — Commit changes",
+        "/stash [pop|list|drop] — Stash operations",
+        "/branch [name] — List/create branches",
+        "/checkout <branch> — Switch branch",
+        "/diff — Show diff",
+        "/pr <title> — Create pull request",
+        "",
+        `${bold("Service Commands")}`,
+        "/service start|stop|restart|status|logs",
+        "",
+        "/help — Show this message",
+    ].join("\n");
+}
+// ─── Plan Messages ──────────────────────────────────────────────────────────
+export function planCreatedMessage(planOutput) {
+    return [
+        `📋 ${bold("Plan Created")}`,
+        "",
+        codeBlock(planOutput),
+        "",
+        italic("Use the buttons below to approve or reject the plan."),
+    ].join("\n");
+}
+export function planApprovedMessage() {
+    return `✅ ${bold("Plan Approved")} — Proceeding with execution.`;
+}
+export function planRejectedMessage() {
+    return `❌ ${bold("Plan Rejected")} — No changes will be made.`;
+}
+// ─── Run Messages ───────────────────────────────────────────────────────────
+export function runStartedMessage(target) {
+    return `🚀 ${bold("Run Started")} — ${escapeHtml(target)}`;
+}
+export function runCompletedMessage(target, prNumber) {
+    const lines = [`✅ ${bold("Run Completed")} — ${escapeHtml(target)}`];
+    if (prNumber) {
+        lines.push("", `Pull Request: #${prNumber}`);
+    }
+    return lines.join("\n");
+}
+export function runFailedMessage(target, error) {
+    return [
+        `❌ ${bold("Run Failed")} — ${escapeHtml(target)}`,
+        "",
+        codeBlock(error),
+    ].join("\n");
+}
+// ─── Review Messages ────────────────────────────────────────────────────────
+export function reviewStartedMessage(prNumber) {
+    return `🔍 ${bold("Reviewing")} PR #${prNumber}...`;
+}
+export function reviewCompletedMessage(prNumber, output) {
+    return [
+        `✅ ${bold("Review Complete")} — PR #${prNumber}`,
+        "",
+        codeBlock(output),
+    ].join("\n");
+}
+// ─── Git Messages ───────────────────────────────────────────────────────────
+export function gitCommitMessage(message, hash) {
+    return [
+        `✅ ${bold("Committed")}`,
+        "",
+        `Message: ${escapeHtml(message)}`,
+        `Hash: ${escapeHtml(hash)}`,
+    ].join("\n");
+}
+export function gitBranchCreatedMessage(name) {
+    return `✅ Branch ${bold(escapeHtml(name))} created.`;
+}
+export function gitCheckoutMessage(branch) {
+    return `✅ Switched to branch ${bold(escapeHtml(branch))}.`;
+}
+export function gitStashMessage(action) {
+    return `✅ ${bold("Stash")} — ${escapeHtml(action)} completed.`;
+}
+export function prCreatedMessage(prNumber, url) {
+    return [
+        `✅ ${bold("Pull Request Created")}`,
+        "",
+        `PR #${prNumber}: ${escapeHtml(url)}`,
+    ].join("\n");
+}
+// ─── Service Messages ───────────────────────────────────────────────────────
+export function serviceStatusMessage(status, pid, uptime, memory, restarts) {
+    const uptimeStr = uptime ? formatUptime(uptime) : "N/A";
+    const memoryStr = memory ? formatMemory(memory) : "N/A";
+    return [
+        `🤖 ${bold("Locus Telegram Bot")}`,
+        "",
+        `Status: ${bold(status)}`,
+        `PID: ${pid ?? "N/A"}`,
+        `Uptime: ${uptimeStr}`,
+        `Memory: ${memoryStr}`,
+        `Restarts: ${restarts}`,
+    ].join("\n");
+}
+export function serviceNotRunningMessage() {
+    return [
+        `⚠️ ${bold("Bot Not Running")}`,
+        "",
+        "Start the bot with:",
+        `${bold("locus pkg telegram start")}`,
+    ].join("\n");
+}
+// ─── Helpers ────────────────────────────────────────────────────────────────
+function formatUptime(startTimeMs) {
+    const diff = Date.now() - startTimeMs;
+    const seconds = Math.floor(diff / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    if (days > 0)
+        return `${days}d ${hours % 24}h`;
+    if (hours > 0)
+        return `${hours}h ${minutes % 60}m`;
+    if (minutes > 0)
+        return `${minutes}m ${seconds % 60}s`;
+    return `${seconds}s`;
+}
+function formatMemory(bytes) {
+    const mb = bytes / (1024 * 1024);
+    return `${mb.toFixed(1)} MB`;
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@locusai/locus-telegram",
+  "version": "0.21.6",
+  "description": "Remote-control Locus via Telegram with full CLI mapping, git operations, and PM2 management",
+  "type": "module",
+  "bin": {
+    "locus-telegram": "./bin/locus-telegram.js"
+  },
+  "locus": {
+    "displayName": "Telegram",
+    "description": "Remote-control your Locus agent from Telegram",
+    "commands": [
+      "telegram"
+    ],
+    "version": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome lint .",
+    "format": "biome format --write ."
+  },
+  "dependencies": {
+    "@locusai/sdk": "0.21.6",
+    "grammy": "^1.35.0",
+    "pm2": "^6.0.5"
+  },
+  "devDependencies": {
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT"
+}

package/src/bot.ts

@@ -0,0 +1,256 @@
+/**
+ * Bot instance — sets up grammy bot, registers middleware, commands,
+ * and callback query handlers.
+ */
+
+import { createLogger } from "@locusai/sdk";
+import { Bot } from "grammy";
+import {
+  handleBranch,
+  handleCheckout,
+  handleCommit,
+  handleDiff,
+  handleGitStatus,
+  handlePR,
+  handleStage,
+  handleStash,
+} from "./commands/git.js";
+import { handleLocusCommand } from "./commands/locus.js";
+import { handleService } from "./commands/service.js";
+import type { TelegramConfig } from "./config.js";
+import { formatInfo, formatSuccess } from "./ui/format.js";
+import { CB } from "./ui/keyboards.js";
+import { welcomeMessage } from "./ui/messages.js";
+
+const logger = createLogger("telegram");
+
+// ─── Bot Factory ────────────────────────────────────────────────────────────
+
+export function createBot(config: TelegramConfig): Bot {
+  const bot = new Bot(config.botToken);
+
+  // ── Auth Middleware ─────────────────────────────────────────────────────
+  bot.use(async (ctx, next) => {
+    const chatId = ctx.chat?.id;
+    if (!chatId || !config.allowedChatIds.includes(chatId)) {
+      logger.warn("Unauthorized access attempt", {
+        chatId,
+        from: ctx.from?.username,
+      });
+      return; // silently ignore
+    }
+    await next();
+  });
+
+  // ── Help / Start ────────────────────────────────────────────────────────
+  bot.command("start", async (ctx) => {
+    await ctx.reply(welcomeMessage(), { parse_mode: "HTML" });
+  });
+
+  bot.command("help", async (ctx) => {
+    await ctx.reply(welcomeMessage(), { parse_mode: "HTML" });
+  });
+
+  // ── Locus CLI Commands ──────────────────────────────────────────────────
+  const locusCommands = [
+    "run",
+    "status",
+    "issues",
+    "issue",
+    "sprint",
+    "plan",
+    "review",
+    "iterate",
+    "discuss",
+    "exec",
+    "logs",
+    "config",
+    "artifacts",
+  ];
+
+  for (const cmd of locusCommands) {
+    bot.command(cmd, async (ctx) => {
+      const args = parseArgs(ctx.message?.text ?? "", cmd);
+      await handleLocusCommand(ctx, cmd, args);
+    });
+  }
+
+  // ── Git Commands ────────────────────────────────────────────────────────
+  bot.command("gitstatus", async (ctx) => {
+    await handleGitStatus(ctx);
+  });
+
+  bot.command("stage", async (ctx) => {
+    const args = parseArgs(ctx.message?.text ?? "", "stage");
+    await handleStage(ctx, args);
+  });
+
+  bot.command("commit", async (ctx) => {
+    const args = parseArgs(ctx.message?.text ?? "", "commit");
+    await handleCommit(ctx, args);
+  });
+
+  bot.command("stash", async (ctx) => {
+    const args = parseArgs(ctx.message?.text ?? "", "stash");
+    await handleStash(ctx, args);
+  });
+
+  bot.command("branch", async (ctx) => {
+    const args = parseArgs(ctx.message?.text ?? "", "branch");
+    await handleBranch(ctx, args);
+  });
+
+  bot.command("checkout", async (ctx) => {
+    const args = parseArgs(ctx.message?.text ?? "", "checkout");
+    await handleCheckout(ctx, args);
+  });
+
+  bot.command("diff", async (ctx) => {
+    await handleDiff(ctx);
+  });
+
+  bot.command("pr", async (ctx) => {
+    const args = parseArgs(ctx.message?.text ?? "", "pr");
+    await handlePR(ctx, args);
+  });
+
+  // ── Service Commands ────────────────────────────────────────────────────
+  bot.command("service", async (ctx) => {
+    const args = parseArgs(ctx.message?.text ?? "", "service");
+    await handleService(ctx, args);
+  });
+
+  // ── Callback Query Handlers ─────────────────────────────────────────────
+  registerCallbackHandlers(bot);
+
+  // ── Fallback ────────────────────────────────────────────────────────────
+  bot.on("message:text", async (ctx) => {
+    // Treat non-command text as a locus exec prompt
+    const text = ctx.message.text;
+    if (text.startsWith("/")) return; // unknown command — ignore
+
+    await handleLocusCommand(ctx, "exec", [text]);
+  });
+
+  return bot;
+}
+
+// ─── Callback Query Handlers ────────────────────────────────────────────────
+
+function registerCallbackHandlers(bot: Bot): void {
+  // Plan callbacks
+  bot.callbackQuery(CB.APPROVE_PLAN, async (ctx) => {
+    await ctx.answerCallbackQuery({ text: "Plan approved!" });
+    await ctx.editMessageReplyMarkup({ reply_markup: undefined });
+    await ctx.reply(formatSuccess("Plan approved. Starting execution..."), {
+      parse_mode: "HTML",
+    });
+    // Trigger the run
+    await handleLocusCommand(ctx, "run", []);
+  });
+
+  bot.callbackQuery(CB.REJECT_PLAN, async (ctx) => {
+    await ctx.answerCallbackQuery({ text: "Plan rejected." });
+    await ctx.editMessageReplyMarkup({ reply_markup: undefined });
+    await ctx.reply(formatInfo("Plan rejected. No changes will be made."), {
+      parse_mode: "HTML",
+    });
+  });
+
+  bot.callbackQuery(CB.SHOW_PLAN_DETAILS, async (ctx) => {
+    await ctx.answerCallbackQuery();
+    await handleLocusCommand(ctx, "plan", ["--show"]);
+  });
+
+  // Run callbacks
+  bot.callbackQuery(CB.VIEW_LOGS, async (ctx) => {
+    await ctx.answerCallbackQuery();
+    await handleLocusCommand(ctx, "logs", ["--lines", "30"]);
+  });
+
+  bot.callbackQuery(/^run:again:(\d+)$/, async (ctx) => {
+    const issue = ctx.match[1];
+    await ctx.answerCallbackQuery({ text: `Re-running issue #${issue}` });
+    await ctx.editMessageReplyMarkup({ reply_markup: undefined });
+    await handleLocusCommand(ctx, "run", [issue]);
+  });
+
+  // Review callbacks
+  bot.callbackQuery(/^review:approve:(\d+)$/, async (ctx) => {
+    const pr = ctx.match[1];
+    await ctx.answerCallbackQuery({ text: "Approving PR..." });
+    await ctx.editMessageReplyMarkup({ reply_markup: undefined });
+    await ctx.reply(formatSuccess(`Approved PR #${pr}`), {
+      parse_mode: "HTML",
+    });
+  });
+
+  bot.callbackQuery(/^review:changes:(\d+)$/, async (ctx) => {
+    const pr = ctx.match[1];
+    await ctx.answerCallbackQuery();
+    await ctx.editMessageReplyMarkup({ reply_markup: undefined });
+    await ctx.reply(
+      formatInfo(
+        `Requesting changes on PR #${pr}. Reply with your feedback and I'll pass it along via /iterate ${pr}`
+      ),
+      { parse_mode: "HTML" }
+    );
+  });
+
+  bot.callbackQuery(/^review:diff:(\d+)$/, async (ctx) => {
+    const pr = ctx.match[1];
+    await ctx.answerCallbackQuery();
+    await handleLocusCommand(ctx, "review", [pr, "--diff"]);
+  });
+
+  // Status callbacks
+  bot.callbackQuery(CB.RUN_SPRINT, async (ctx) => {
+    await ctx.answerCallbackQuery({ text: "Starting sprint run..." });
+    await ctx.editMessageReplyMarkup({ reply_markup: undefined });
+    await handleLocusCommand(ctx, "run", []);
+  });
+
+  bot.callbackQuery(CB.VIEW_ISSUES, async (ctx) => {
+    await ctx.answerCallbackQuery();
+    await handleLocusCommand(ctx, "issues", []);
+  });
+
+  // Stash callbacks
+  bot.callbackQuery(CB.STASH_POP, async (ctx) => {
+    await ctx.answerCallbackQuery();
+    await handleStash(ctx, ["pop"]);
+  });
+
+  bot.callbackQuery(CB.STASH_LIST, async (ctx) => {
+    await ctx.answerCallbackQuery();
+    await handleStash(ctx, ["list"]);
+  });
+
+  bot.callbackQuery(CB.STASH_DROP, async (ctx) => {
+    await ctx.answerCallbackQuery();
+    await handleStash(ctx, ["drop"]);
+  });
+
+  // Confirmation callbacks
+  bot.callbackQuery(CB.CONFIRM_ACTION, async (ctx) => {
+    await ctx.answerCallbackQuery({ text: "Confirmed!" });
+    await ctx.editMessageReplyMarkup({ reply_markup: undefined });
+  });
+
+  bot.callbackQuery(CB.CANCEL_ACTION, async (ctx) => {
+    await ctx.answerCallbackQuery({ text: "Cancelled." });
+    await ctx.editMessageReplyMarkup({ reply_markup: undefined });
+    await ctx.reply(formatInfo("Action cancelled."), { parse_mode: "HTML" });
+  });
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/** Parse arguments from a Telegram command message. */
+function parseArgs(text: string, command: string): string[] {
+  // Remove the /command part (handles @botname suffix too)
+  const prefixRegex = new RegExp(`^/${command}(@\\S+)?\\s*`);
+  const rest = text.replace(prefixRegex, "").trim();
+  if (!rest) return [];
+  return rest.split(/\s+/);
+}