agentgram 2.0.0 → 2.0.4

package/dist/index.js

@@ -6,13 +6,8 @@ var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __esm = (fn, res, err) => function __init() {
-  if (err) throw err[0];
-  try {
-    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
-  } catch (e) {
-    throw err = [e], e;
-  }
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -394,12 +389,11 @@ function getGlobalConfigDir() {
   return AGENTGRAM_CONFIG_DIR;
 }
 function ensureConfigDirs() {
-  const dir = getGlobalConfigDir();
-  const stateDir = path2.join(dir, "state");
   try {
     if (!fs2.existsSync(AGENTGRAM_CONFIG_DIR)) fs2.mkdirSync(AGENTGRAM_CONFIG_DIR, { recursive: true, mode: 448 });
-    if (!fs2.existsSync(path2.join(AGENTGRAM_CONFIG_DIR, "state"))) {
-      fs2.mkdirSync(path2.join(AGENTGRAM_CONFIG_DIR, "state"), { recursive: true, mode: 448 });
+    const stateDir = path2.join(AGENTGRAM_CONFIG_DIR, "state");
+    if (!fs2.existsSync(stateDir)) {
+      fs2.mkdirSync(stateDir, { recursive: true, mode: 448 });
     }
     const legacyConfig = path2.join(LEGACY_CONFIG_DIR, "config.json");
     const agentgramConfig = path2.join(AGENTGRAM_CONFIG_DIR, "config.json");
@@ -477,7 +471,7 @@ var init_config_manager = __esm({
           engine: "opencode",
           denyPatterns: [],
           allowedPaths: [],
-          workspaces: [resolvedTarget],
+          workspaces: resolvedTarget.startsWith(os.tmpdir()) ? [] : [resolvedTarget],
           extra: {}
         };
         this.load();
@@ -527,13 +521,17 @@ var init_config_manager = __esm({
         if (Array.isArray(data.deny_patterns)) this.config.denyPatterns = data.deny_patterns.map(String);
         if (Array.isArray(data.allowed_paths)) this.config.allowedPaths = data.allowed_paths.map(String);
         if (Array.isArray(data.workspaces)) {
+          this.config.workspaces = [];
           for (const w of data.workspaces) {
             const resolved = path2.resolve(String(w));
-            if (!this.config.workspaces.includes(resolved)) {
+            if (fs2.existsSync(resolved) && !resolved.startsWith(os.tmpdir()) && !this.config.workspaces.includes(resolved)) {
               this.config.workspaces.push(resolved);
             }
           }
         }
+        if (fs2.existsSync(this.config.targetDir) && !this.config.targetDir.startsWith(os.tmpdir()) && !this.config.workspaces.includes(this.config.targetDir)) {
+          this.config.workspaces.unshift(this.config.targetDir);
+        }
       }
       saveGlobal() {
         ensureConfigDirs();
@@ -586,6 +584,16 @@ var init_config_manager = __esm({
         }
         return true;
       }
+      removeWorkspace(workspace) {
+        const resolved = path2.resolve(workspace);
+        const idx = this.config.workspaces.indexOf(resolved);
+        if (idx !== -1) {
+          this.config.workspaces.splice(idx, 1);
+          this.saveGlobal();
+          return true;
+        }
+        return false;
+      }
       validate() {
         const errors = [];
         const isTelegram = !this.config.channel || this.config.channel === "telegram";
@@ -605,7 +613,7 @@ var init_config_manager = __esm({
 });
 
 // src/telegram/telegram-client.ts
-function escapeHtml2(text) {
+function escapeHtml(text) {
   if (!text) return "";
   return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
 }
@@ -774,8 +782,8 @@ function toTelegramMarkup(keyboard) {
     inline_keyboard: keyboard.rows.map(
       (row) => row.map((btn) => ({
         text: btn.text,
-        callback_data: btn.callbackData,
-        url: btn.url
+        callback_data: btn.callbackData ?? void 0,
+        url: btn.url ?? void 0
       }))
     )
   };
@@ -788,8 +796,8 @@ function fromTelegramMarkup(markup) {
     rows: markup.inline_keyboard.map(
       (row) => row.map((btn) => ({
         text: btn.text,
-        callbackData: btn.callback_data,
-        url: btn.url
+        callbackData: btn.callback_data ?? void 0,
+        url: btn.url ?? void 0
       }))
     )
   };
@@ -971,7 +979,7 @@ var init_console_adapter = __esm({
           timestamp: Date.now()
         };
       }
-      async editMessage(recipientId, messageId, text, options) {
+      async editMessage(_recipientId, messageId, text, options) {
         const cleanText = text.replace(/<[^>]+>/g, "").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">");
         console.log(`
 \x1B[33m[Update #${messageId}]\x1B[0m ${cleanText}`);
@@ -1240,30 +1248,36 @@ var init_opencode_client = __esm({
         const actualPort = port > 0 ? port : await getFreePort();
         const proc = child_process.spawn(
           "opencode",
-          ["serve", "--port", String(actualPort), "--hostname", "127.0.0.1"],
+          ["serve", "--port", String(actualPort), "--hostname", "127.0.0.1", "--pure"],
           {
             cwd: targetDir,
             env: {
               ...process.env,
               OPENCODE_SERVER_PASSWORD: password
             },
-            stdio: ["ignore", "pipe", "pipe"]
+            stdio: ["ignore", "ignore", "ignore"]
           }
         );
         const client = new _OpenCodeClient(`http://127.0.0.1:${actualPort}`, password, targetDir);
         let ready = false;
-        for (let i = 0; i < 30; i++) {
+        for (let i = 0; i < 60; i++) {
+          if (proc.exitCode !== null) {
+            throw new Error(`OpenCode process exited early with code ${proc.exitCode}`);
+          }
           try {
             await client.request("GET", "/global/health");
             ready = true;
             break;
           } catch {
-            await new Promise((r) => setTimeout(r, 500));
+            await new Promise((r) => setTimeout(r, 1e3));
           }
         }
         if (!ready) {
-          proc.kill();
-          throw new Error(`OpenCode server failed to start on port ${actualPort}`);
+          try {
+            proc.kill("SIGTERM");
+          } catch {
+          }
+          throw new Error(`OpenCode server failed to start on port ${actualPort} within 60s`);
         }
         client.serverProcess = proc;
         return { client, proc, port: actualPort };
@@ -1342,6 +1356,12 @@ var init_opencode_adapter = __esm({
         this.client.on("event", this.boundEventHandler);
         this.client.connectEventStream();
       }
+      async listModels() {
+        return this.client.listModels();
+      }
+      async listAgents() {
+        return this.client.listAgents();
+      }
     };
   }
 });
@@ -1567,6 +1587,10 @@ var init_i18n = __esm({
         btn_handoff: "\u{1F501} Handoff",
         btn_help: "\u2753 Help",
         btn_language: "\u{1F310} Language",
+        btn_back: "\u2B05\uFE0F Back",
+        btn_all_models: "\u27A1\uFE0F All Models",
+        btn_favorites: "\u2B50 Favorites",
+        btn_next: "\u27A1\uFE0F Next",
         // Permission Buttons
         perm_allow_once: "\u2705 Allow Once",
         perm_always_allow: "\u267E\uFE0F Always Allow",
@@ -1612,6 +1636,10 @@ var init_i18n = __esm({
         btn_handoff: "\u{1F501} \u062A\u0633\u0644\u064A\u0645",
         btn_help: "\u2753 \u0645\u0633\u0627\u0639\u062F\u0629",
         btn_language: "\u{1F310} \u0627\u0644\u0644\u063A\u0629",
+        btn_back: "\u2B05\uFE0F \u0631\u062C\u0648\u0639",
+        btn_all_models: "\u27A1\uFE0F \u0627\u0644\u0645\u0632\u064A\u062F",
+        btn_favorites: "\u2B50 \u0627\u0644\u0645\u0641\u0636\u0644\u0629",
+        btn_next: "\u27A1\uFE0F \u0627\u0644\u062A\u0627\u0644\u064A",
         // Permission Buttons
         perm_allow_once: "\u2705 \u0645\u0631\u0629 \u0648\u0627\u062D\u062F\u0629",
         perm_always_allow: "\u267E\uFE0F \u0633\u0645\u0627\u062D \u062F\u0627\u0626\u0645\u0627\u064B",
@@ -1645,6 +1673,315 @@ var init_i18n = __esm({
   }
 });
 
+// src/domain/model-catalog.ts
+function formatModelName(modelId) {
+  const parts = modelId.split("/");
+  const base = parts[parts.length - 1] || modelId;
+  return base.replace(/-free$/i, "").split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+}
+function resolveModelMetadata(modelId) {
+  if (!modelId) {
+    return {
+      id: "default",
+      name: "Default Model",
+      provider: "Default",
+      contextWindow: "128k",
+      tag: "Default Engine Model"
+    };
+  }
+  if (KNOWN_MODELS[modelId]) {
+    return KNOWN_MODELS[modelId];
+  }
+  const lower = modelId.toLowerCase();
+  for (const [key, meta] of Object.entries(KNOWN_MODELS)) {
+    if (lower === key.toLowerCase() || lower.endsWith(`/${key.toLowerCase()}`)) {
+      return { ...meta, id: modelId };
+    }
+  }
+  if (lower.includes("gemini-1.5-pro") || lower.includes("gemini-2.0-pro")) {
+    return {
+      id: modelId,
+      name: formatModelName(modelId),
+      provider: "Google",
+      contextWindow: "2M",
+      tag: "Ultra-Long Context (2M)",
+      tier: "flagship"
+    };
+  }
+  if (lower.includes("gemini")) {
+    return {
+      id: modelId,
+      name: formatModelName(modelId),
+      provider: "Google",
+      contextWindow: "1M",
+      tag: "1M Tokens Multimodal",
+      tier: "standard"
+    };
+  }
+  if (lower.includes("claude-3-5") || lower.includes("sonnet") || lower.includes("haiku") || lower.includes("opus")) {
+    return {
+      id: modelId,
+      name: formatModelName(modelId),
+      provider: "Anthropic",
+      contextWindow: "200k",
+      tag: "SOTA Coding & Tool Use",
+      tier: "flagship"
+    };
+  }
+  if (lower.includes("deepseek-r1") || lower.includes("reasoner")) {
+    return {
+      id: modelId,
+      name: formatModelName(modelId),
+      provider: "DeepSeek",
+      contextWindow: "128k",
+      tag: "Deep Reasoning CoT",
+      tier: "flagship"
+    };
+  }
+  if (lower.includes("deepseek")) {
+    return {
+      id: modelId,
+      name: formatModelName(modelId),
+      provider: "DeepSeek",
+      contextWindow: "128k",
+      tag: "High-Speed Coding & Logic",
+      tier: "flagship"
+    };
+  }
+  if (lower.includes("o3")) {
+    return {
+      id: modelId,
+      name: formatModelName(modelId),
+      provider: "OpenAI",
+      contextWindow: "200k",
+      tag: "Advanced Math & Code",
+      tier: "flagship"
+    };
+  }
+  if (lower.includes("o1") || lower.includes("gpt-4")) {
+    return {
+      id: modelId,
+      name: formatModelName(modelId),
+      provider: "OpenAI",
+      contextWindow: "128k",
+      tag: "Omni Reasoning & Logic",
+      tier: "flagship"
+    };
+  }
+  if (lower.includes("qwen") || lower.includes("llama") || lower.includes("mistral")) {
+    return {
+      id: modelId,
+      name: formatModelName(modelId),
+      provider: "Open Weights",
+      contextWindow: "128k",
+      tag: "Open-Source Architecture",
+      tier: "standard"
+    };
+  }
+  if (lower.includes("free") || lower.includes("space-bunny") || lower.includes("longcat") || lower.includes("mimo")) {
+    return {
+      id: modelId,
+      name: formatModelName(modelId),
+      provider: "OpenCode Free",
+      contextWindow: "128k",
+      tag: "Community Free Model",
+      tier: "free"
+    };
+  }
+  return {
+    id: modelId,
+    name: formatModelName(modelId),
+    provider: "AI Provider",
+    contextWindow: "128k",
+    tag: "General Intelligence"
+  };
+}
+function getStandardModelCatalog() {
+  return Object.keys(KNOWN_MODELS);
+}
+var KNOWN_MODELS;
+var init_model_catalog = __esm({
+  "src/domain/model-catalog.ts"() {
+    "use strict";
+    KNOWN_MODELS = {
+      // Anthropic
+      "claude-3-5-sonnet-20241022": {
+        id: "claude-3-5-sonnet-20241022",
+        name: "Claude 3.5 Sonnet (v2)",
+        provider: "Anthropic",
+        contextWindow: "200k",
+        tag: "Coding Champion & Tool Use",
+        tier: "flagship"
+      },
+      "claude-3-5-sonnet": {
+        id: "claude-3-5-sonnet",
+        name: "Claude 3.5 Sonnet",
+        provider: "Anthropic",
+        contextWindow: "200k",
+        tag: "Coding & Agentic Automation",
+        tier: "flagship"
+      },
+      "claude-3-5-haiku": {
+        id: "claude-3-5-haiku",
+        name: "Claude 3.5 Haiku",
+        provider: "Anthropic",
+        contextWindow: "200k",
+        tag: "Ultra-Fast & Smart",
+        tier: "standard"
+      },
+      "claude-3-opus": {
+        id: "claude-3-opus",
+        name: "Claude 3 Opus",
+        provider: "Anthropic",
+        contextWindow: "200k",
+        tag: "Deep Reasoning & Synthesis",
+        tier: "flagship"
+      },
+      // OpenAI
+      "gpt-4o": {
+        id: "gpt-4o",
+        name: "GPT-4o (Omni)",
+        provider: "OpenAI",
+        contextWindow: "128k",
+        tag: "Multimodal Flagship",
+        tier: "flagship"
+      },
+      "gpt-4o-mini": {
+        id: "gpt-4o-mini",
+        name: "GPT-4o Mini",
+        provider: "OpenAI",
+        contextWindow: "128k",
+        tag: "High Speed & Efficiency",
+        tier: "standard"
+      },
+      "o1": {
+        id: "o1",
+        name: "OpenAI o1",
+        provider: "OpenAI",
+        contextWindow: "128k",
+        tag: "Deep CoT Reflection & Logic",
+        tier: "flagship"
+      },
+      "o1-mini": {
+        id: "o1-mini",
+        name: "OpenAI o1-mini",
+        provider: "OpenAI",
+        contextWindow: "128k",
+        tag: "Math & STEM Reasoning",
+        tier: "standard"
+      },
+      "o3-mini": {
+        id: "o3-mini",
+        name: "OpenAI o3-mini",
+        provider: "OpenAI",
+        contextWindow: "200k",
+        tag: "High-Performance Math & Code",
+        tier: "flagship"
+      },
+      // Google Gemini
+      "gemini-1.5-pro": {
+        id: "gemini-1.5-pro",
+        name: "Gemini 1.5 Pro",
+        provider: "Google",
+        contextWindow: "2M",
+        tag: "Massive 2M Tokens Repo Context",
+        tier: "flagship"
+      },
+      "gemini-1.5-flash": {
+        id: "gemini-1.5-flash",
+        name: "Gemini 1.5 Flash",
+        provider: "Google",
+        contextWindow: "1M",
+        tag: "Fast 1M Window & Multimodal",
+        tier: "standard"
+      },
+      "gemini-2.0-flash": {
+        id: "gemini-2.0-flash",
+        name: "Gemini 2.0 Flash",
+        provider: "Google",
+        contextWindow: "1M",
+        tag: "Next-Gen Realtime Multimodal",
+        tier: "flagship"
+      },
+      // DeepSeek
+      "deepseek-chat": {
+        id: "deepseek-chat",
+        name: "DeepSeek V3",
+        provider: "DeepSeek",
+        contextWindow: "128k",
+        tag: "SOTA Coding & Architecture",
+        tier: "flagship"
+      },
+      "deepseek-reasoner": {
+        id: "deepseek-reasoner",
+        name: "DeepSeek R1",
+        provider: "DeepSeek",
+        contextWindow: "128k",
+        tag: "Open CoT Reasoning Engine",
+        tier: "flagship"
+      },
+      // OpenCode Community Free Models
+      "opencode/deepseek-v4.1-flash-free": {
+        id: "opencode/deepseek-v4.1-flash-free",
+        name: "DeepSeek v4.1 Flash",
+        provider: "OpenCode Free",
+        contextWindow: "128k",
+        tag: "Fast Free Coding Agent",
+        tier: "free"
+      },
+      "opencode/space-bunny-free": {
+        id: "opencode/space-bunny-free",
+        name: "Space Bunny Free",
+        provider: "OpenCode Free",
+        contextWindow: "128k",
+        tag: "Community Automation Agent",
+        tier: "free"
+      },
+      "opencode/glm-5.3-flash-free": {
+        id: "opencode/glm-5.3-flash-free",
+        name: "GLM 5.3 Flash Free",
+        provider: "OpenCode Free",
+        contextWindow: "128k",
+        tag: "High Concurrency Coding",
+        tier: "free"
+      },
+      "opencode/nemotron-3-ultra-free": {
+        id: "opencode/nemotron-3-ultra-free",
+        name: "Nemotron 3 Ultra Free",
+        provider: "OpenCode Free",
+        contextWindow: "128k",
+        tag: "NVIDIA Hardware Accelerated",
+        tier: "free"
+      },
+      "opencode/mimo-v2.6-flash-free": {
+        id: "opencode/mimo-v2.6-flash-free",
+        name: "Mimo v2.6 Flash Free",
+        provider: "OpenCode Free",
+        contextWindow: "128k",
+        tag: "Lightweight Quick Edits",
+        tier: "free"
+      },
+      "opencode/longcat-2.5-preview-free": {
+        id: "opencode/longcat-2.5-preview-free",
+        name: "LongCat 2.5 Preview",
+        provider: "OpenCode Free",
+        contextWindow: "128k",
+        tag: "Long Context Free Preview",
+        tier: "free"
+      },
+      // Open Weights
+      "qwen2.5-coder-32b": {
+        id: "qwen2.5-coder-32b",
+        name: "Qwen 2.5 Coder 32B",
+        provider: "Alibaba",
+        contextWindow: "128k",
+        tag: "Open-Weights Coding Champion",
+        tier: "flagship"
+      }
+    };
+  }
+});
+
 // src/control-room/control-room.ts
 function parseCallback(data) {
   if (data.startsWith("pm:")) {
@@ -1699,18 +2036,21 @@ function permissionKeyboard(permId, lang = "en") {
     inline_keyboard: rows
   };
 }
-var fs3, path3, SYSTEM_HEADER, ControlRoom;
+var fs3, os2, path3, child_process3, SYSTEM_HEADER, ControlRoom;
 var init_control_room = __esm({
   "src/control-room/control-room.ts"() {
     "use strict";
     fs3 = __toESM(require("fs"));
+    os2 = __toESM(require("os"));
     path3 = __toESM(require("path"));
+    child_process3 = __toESM(require("child_process"));
     init_telegram_client();
     init_opencode_client();
     init_telegram_adapter();
     init_opencode_adapter();
     init_policy();
     init_i18n();
+    init_model_catalog();
     SYSTEM_HEADER = (targetDir) => `
 BRIDGE RULES (highest priority):
 - Primary project workspace: ${targetDir}.
@@ -1736,6 +2076,7 @@ BRIDGE RULES (highest priority):
       alwaysAllowedPerms = /* @__PURE__ */ new Set();
       missionCardMsgId = null;
       updateTimer = null;
+      activeSkill = null;
       isListening = false;
       constructor(arg1, arg2, arg3) {
         if ("channel" in arg1 && "engine" in arg1) {
@@ -1786,13 +2127,23 @@ BRIDGE RULES (highest priority):
         });
       }
       async start() {
-        await this.engine.connect();
+        try {
+          await this.engine.connect();
+        } catch (err) {
+          console.warn("\u26A0\uFE0F Warning: Engine connection failed at startup:", err.message);
+        }
         this.isListening = true;
-        await this.channel.sendMessage(
-          this.allowedChatId,
-          t("welcome", this.language, { target: escapeHtml2(this.targetDir) }),
-          { replyMarkup: this.getMainKeyboard() }
-        );
+        if (this.allowedChatId && this.allowedChatId.trim()) {
+          try {
+            await this.channel.sendMessage(
+              this.allowedChatId,
+              t("welcome", this.language, { target: escapeHtml(this.targetDir) }),
+              { replyMarkup: this.getMainKeyboard() }
+            );
+          } catch (err) {
+            console.warn("\u26A0\uFE0F Warning: Could not deliver initial welcome card:", err.message);
+          }
+        }
         await this.channel.startListening({
           onMessage: async (msg) => {
             if (this.channel.id === "telegram" && this.allowedChatId && msg.chatId !== this.allowedChatId) {
@@ -1826,20 +2177,57 @@ BRIDGE RULES (highest priority):
         if (text === "/start" || text === "/help") {
           await this.channel.sendMessage(
             this.allowedChatId,
-            `\u26A1 <b>AgentGram v2.0.0</b>
+            `\u26A1 <b>AgentGram v2.0.0 \xB7 Mission Control</b>
 ${t("help_title", this.language)}`,
             { replyMarkup: this.getMainKeyboard() }
           );
           return;
         }
+        if (text === "/status" || text === "st") {
+          await this.sendStatusReport();
+          return;
+        }
+        if (text === "/agents") {
+          await this.sendAgentsMenu();
+          return;
+        }
+        if (text === "/models") {
+          await this.sendModelsMenu();
+          return;
+        }
         if (text === "/mode") {
           await this.sendModeMenu();
           return;
         }
+        if (text === "/sessions") {
+          await this.sendSessionsMenu();
+          return;
+        }
+        if (text === "/new") {
+          this.activeRun = null;
+          await this.channel.sendMessage(
+            this.allowedChatId,
+            "\u2728 <b>New Session Ready</b> \u2014 send your prompt to start.",
+            { replyMarkup: this.getMainKeyboard() }
+          );
+          return;
+        }
         if (text === "/diff") {
           await this.sendDiff();
           return;
         }
+        if (text === "/skills") {
+          await this.sendSkillsMenu();
+          return;
+        }
+        if (text === "/usage") {
+          await this.sendUsageReport();
+          return;
+        }
+        if (text === "/handoff") {
+          await this.sendHandoffReport();
+          return;
+        }
         if (text === "/stop") {
           await this.abortCurrentRun();
           return;
@@ -1865,7 +2253,7 @@ ${t("help_title", this.language)}`,
         if (hits.length > 0) {
           await this.channel.sendMessage(
             this.allowedChatId,
-            t("policy_denied", this.language, { hits: escapeHtml2(hits.slice(0, 3).join(", ")) })
+            t("policy_denied", this.language, { hits: escapeHtml(hits.slice(0, 3).join(", ")) })
           );
           return;
         }
@@ -1874,7 +2262,7 @@ ${t("help_title", this.language)}`,
           await this.channel.sendMessage(
             this.allowedChatId,
             t("prompt_injection_blocked", this.language, {
-              reason: escapeHtml2(detection.reason),
+              reason: escapeHtml(detection.reason),
               confidence: Math.round(detection.confidence * 100)
             })
           );
@@ -1915,12 +2303,18 @@ ${t("help_title", this.language)}`,
           );
           this.missionCardMsgId = cardMsg.messageId;
           this.startMissionCardTicker();
-          const sanitized = this.policy.sanitizePrompt(promptText);
+          let finalPrompt = promptText;
+          if (this.activeSkill) {
+            finalPrompt = `[Active Skill: ${this.activeSkill}]
+${promptText}`;
+            this.activeSkill = null;
+          }
+          const sanitized = this.policy.sanitizePrompt(finalPrompt);
           await this.engine.submitPrompt(sessionId, sanitized, this.currentAgent, this.currentModel);
         } catch (err) {
           await this.channel.sendMessage(
             this.allowedChatId,
-            `\u274C Error: ${escapeHtml2(err.message)}`
+            `\u274C Error: ${escapeHtml(err.message)}`
           );
         }
       }
@@ -1951,29 +2345,108 @@ ${t("help_title", this.language)}`,
           }
           return;
         }
+        if (data === "menu:home" || data === "home") {
+          await this.channel.sendMessage(
+            this.allowedChatId,
+            t("welcome", this.language, { target: escapeHtml(this.targetDir) }),
+            { replyMarkup: this.getMainKeyboard() }
+          );
+          return;
+        }
+        if (data === "menu:ag") {
+          await this.sendAgentsMenu();
+          return;
+        }
+        if (data.startsWith("ag:")) {
+          const agent = data.slice(3);
+          this.currentAgent = agent;
+          this.cfgManager.config.defaultAgent = agent;
+          this.cfgManager.saveGlobal();
+          await this.channel.sendMessage(
+            this.allowedChatId,
+            `\u{1F9E0} Agent changed to: <b>${escapeHtml(agent)}</b>`,
+            { replyMarkup: this.getMainKeyboard() }
+          );
+          return;
+        }
+        if (data === "menu:md") {
+          await this.sendModelsMenu(0);
+          return;
+        }
+        if (data.startsWith("pg:")) {
+          const page = parseInt(data.slice(3), 10) || 0;
+          await this.sendModelsMenu(page);
+          return;
+        }
+        if (data.startsWith("md:raw:")) {
+          const model = data.slice(7);
+          if (model) {
+            this.currentModel = model;
+            this.cfgManager.config.defaultModel = model;
+            this.cfgManager.saveGlobal();
+            await this.channel.sendMessage(
+              this.allowedChatId,
+              `\u{1F916} Model changed to: <b>${escapeHtml(model)}</b>`,
+              { replyMarkup: this.getMainKeyboard() }
+            );
+          }
+          return;
+        }
+        if (data.startsWith("md:")) {
+          const idx = parseInt(data.slice(3), 10);
+          const model = this.cfgManager.config.favoriteModels[idx];
+          if (model) {
+            this.currentModel = model;
+            this.cfgManager.config.defaultModel = model;
+            this.cfgManager.saveGlobal();
+            await this.channel.sendMessage(
+              this.allowedChatId,
+              `\u{1F916} Model changed to: <b>${escapeHtml(model)}</b>`,
+              { replyMarkup: this.getMainKeyboard() }
+            );
+          }
+          return;
+        }
+        if (data === "menu:mo") {
+          await this.sendModeMenu();
+          return;
+        }
         if (data.startsWith("mo:")) {
           const mode = data.slice(3);
           if (["read", "build", "auto"].includes(mode)) {
             this.currentMode = mode;
-            if (messageId !== void 0) {
-              await this.channel.sendMessage(
-                this.allowedChatId,
-                `\u{1F512} Mode changed to: <b>${mode}</b>`
-              );
-            }
+            await this.channel.sendMessage(
+              this.allowedChatId,
+              `\u{1F512} Mode changed to: <b>${mode}</b>`,
+              { replyMarkup: this.getMainKeyboard() }
+            );
           }
           return;
         }
-        if (data === "stop") {
-          await this.abortCurrentRun();
+        if (data === "menu:se") {
+          await this.sendSessionsMenu();
           return;
         }
-        if (data === "diff") {
-          await this.sendDiff();
+        if (data === "new") {
+          this.activeRun = null;
+          await this.channel.sendMessage(
+            this.allowedChatId,
+            "\u2728 <b>New Session Ready</b> \u2014 send your prompt to start fresh.",
+            { replyMarkup: this.getMainKeyboard() }
+          );
           return;
         }
-        if (data === "menu:mo") {
-          await this.sendModeMenu();
+        if (data.startsWith("se:")) {
+          const sid = data.slice(3);
+          await this.channel.sendMessage(
+            this.allowedChatId,
+            `\u{1F4C2} Resumed session: <code>${escapeHtml(sid)}</code>`,
+            { replyMarkup: this.getMainKeyboard() }
+          );
+          return;
+        }
+        if (data === "st") {
+          await this.sendStatusReport();
           return;
         }
         if (data === "menu:ws") {
@@ -1987,6 +2460,69 @@ ${t("help_title", this.language)}`,
           if (target) {
             await this.switchWorkspace(target);
           }
+          return;
+        }
+        if (data === "diff") {
+          await this.sendDiff();
+          return;
+        }
+        if (data === "menu:sk") {
+          await this.sendSkillsMenu(0);
+          return;
+        }
+        if (data.startsWith("skpage:")) {
+          const page = parseInt(data.slice(7), 10) || 0;
+          await this.sendSkillsMenu(page);
+          return;
+        }
+        if (data.startsWith("sk:")) {
+          const sk = data.slice(3);
+          this.activeSkill = sk;
+          await this.channel.sendMessage(
+            this.allowedChatId,
+            `\u{1F9F0} Selected Skill: <b>${escapeHtml(sk)}</b> \u2014 send your task to execute with this skill.`,
+            { replyMarkup: this.getMainKeyboard() }
+          );
+          return;
+        }
+        if (data === "us") {
+          await this.sendUsageReport();
+          return;
+        }
+        if (data === "menu:lg") {
+          await this.sendLanguageMenu();
+          return;
+        }
+        if (data.startsWith("lang:")) {
+          const lang = data.slice(5);
+          if (lang === "en" || lang === "ar") {
+            this.language = lang;
+            this.cfgManager.config.language = lang;
+            this.cfgManager.saveGlobal();
+            await this.channel.sendMessage(
+              this.allowedChatId,
+              t("lang_changed", this.language),
+              { replyMarkup: this.getMainKeyboard() }
+            );
+          }
+          return;
+        }
+        if (data === "ho") {
+          await this.sendHandoffReport();
+          return;
+        }
+        if (data === "hp") {
+          await this.channel.sendMessage(
+            this.allowedChatId,
+            `\u26A1 <b>AgentGram Commands & Mission Control</b>
+${t("help_title", this.language)}`,
+            { replyMarkup: this.getMainKeyboard() }
+          );
+          return;
+        }
+        if (data === "stop") {
+          await this.abortCurrentRun();
+          return;
         }
       }
       async handleEngineEvent(event) {
@@ -2006,7 +2542,7 @@ ${t("help_title", this.language)}`,
           if (decision === "reject") {
             await this.engine.replyPermission(permId, "reject");
             if (reason) {
-              await this.channel.sendMessage(this.allowedChatId, `\u26D4 ${escapeHtml2(reason)}`);
+              await this.channel.sendMessage(this.allowedChatId, `\u26D4 ${escapeHtml(reason)}`);
             }
             return;
           }
@@ -2014,9 +2550,9 @@ ${t("help_title", this.language)}`,
           await this.channel.sendMessage(
             this.allowedChatId,
             t("permission_prompt", this.language, {
-              tool: escapeHtml2(tool),
-              pattern: escapeHtml2(String(props.patterns || "*")),
-              details: cmd ? `<code>${escapeHtml2(cmd.slice(0, 150))}</code>` : ""
+              tool: escapeHtml(tool),
+              pattern: escapeHtml(String(props.patterns || "*")),
+              details: cmd ? `<code>${escapeHtml(cmd.slice(0, 150))}</code>` : ""
             }),
             { replyMarkup: kb }
           );
@@ -2057,11 +2593,11 @@ ${t("help_title", this.language)}`,
         const statusText = run.done ? "Finished" : run.busy ? "Executing" : "Waiting";
         return `
 \u26A1 <b>AgentGram \xB7 Live Mission Control</b>
-Agent: \u{1F9E0} <code>${escapeHtml2(run.agent)}</code> (${escapeHtml2(this.engine.name)}) | Mode: \u{1F512} <b>${run.mode}</b>
-Channel: \u{1F4E1} <b>${escapeHtml2(this.channel.name)}</b>
+Agent: \u{1F9E0} <code>${escapeHtml(run.agent)}</code> (${escapeHtml(this.engine.name)}) | Mode: \u{1F512} <b>${run.mode}</b>
+Channel: \u{1F4E1} <b>${escapeHtml(this.channel.name)}</b>
 Status: ${statusIcon} <b>${statusText}</b> \xB7 \u23F3 ${elapsed}s
 Commands: \u2699\uFE0F ${run.cmds} \xB7 Files: \u{1F4DD} ${run.files.size}
-Workspace: \u{1F4C1} <code>${escapeHtml2(path3.basename(this.targetDir))}</code>
+Workspace: \u{1F4C1} <code>${escapeHtml(path3.basename(this.targetDir))}</code>
 `.trim();
       }
       async updateMissionCard(final = false) {
@@ -2080,49 +2616,382 @@ Workspace: \u{1F4C1} <code>${escapeHtml2(path3.basename(this.targetDir))}</code>
         } catch {
         }
       }
+      /**
+       * The complete, feature-rich 5-row interactive home keyboard with all 14 buttons.
+       */
       getMainKeyboard() {
         const rows = [
           [
-            { text: t("btn_stop", this.language), callback_data: "stop" },
-            { text: t("btn_diff", this.language), callback_data: "diff" },
+            { text: t("btn_agents", this.language), callback_data: "menu:ag" },
+            { text: t("btn_models", this.language), callback_data: "menu:md" },
             { text: t("btn_mode", this.language), callback_data: "menu:mo" }
           ],
           [
+            { text: t("btn_sessions", this.language), callback_data: "menu:se" },
+            { text: t("btn_new", this.language), callback_data: "new" },
+            { text: t("btn_stop", this.language), callback_data: "stop" }
+          ],
+          [
+            { text: t("btn_status", this.language), callback_data: "st" },
             { text: t("btn_workspaces", this.language), callback_data: "menu:ws" },
+            { text: t("btn_diff", this.language), callback_data: "diff" }
+          ],
+          [
+            { text: t("btn_skills", this.language), callback_data: "menu:sk" },
+            { text: t("btn_usage", this.language), callback_data: "us" },
             { text: t("btn_language", this.language), callback_data: "menu:lg" }
+          ],
+          [
+            { text: t("btn_handoff", this.language), callback_data: "ho" },
+            { text: t("btn_help", this.language), callback_data: "hp" }
           ]
         ];
+        return this.wrapKeyboard(rows);
+      }
+      wrapKeyboard(rows) {
+        const cleanRows = rows.map(
+          (r) => r.map((btn) => ({
+            text: stripHtml(btn.text).replace(/^[⚡\s]+/, "").trim(),
+            callback_data: btn.callback_data
+          }))
+        );
         return {
-          rows: rows.map(
+          rows: cleanRows.map(
             (r) => r.map((btn) => ({
               text: btn.text,
               callbackData: btn.callback_data,
               callback_data: btn.callback_data
             }))
           ),
-          inline_keyboard: rows
+          inline_keyboard: cleanRows
         };
       }
+      async sendAgentsMenu() {
+        const agents = ["build", "delegate", "explorer", "code-review"];
+        const rows = [];
+        let currentRow = [];
+        for (const a of agents) {
+          const isCurrent = a === this.currentAgent;
+          currentRow.push({
+            text: `${isCurrent ? "\u25CF " : ""}${a}`,
+            callback_data: `ag:${a}`
+          });
+          if (currentRow.length === 2) {
+            rows.push(currentRow);
+            currentRow = [];
+          }
+        }
+        if (currentRow.length > 0) rows.push(currentRow);
+        rows.push([{ text: t("btn_back", this.language), callback_data: "menu:home" }]);
+        await this.channel.sendMessage(
+          this.allowedChatId,
+          t("select_agent", this.language, { agent: escapeHtml(this.currentAgent) }),
+          { replyMarkup: this.wrapKeyboard(rows) }
+        );
+      }
+      async sendModelsMenu(page = 0) {
+        const favs = this.cfgManager.config.favoriteModels || [];
+        let engineModels = [];
+        if (typeof this.engine.listModels === "function") {
+          try {
+            const raw = await this.engine.listModels();
+            engineModels = (raw || []).map((m) => m.id);
+          } catch {
+          }
+        }
+        const standardCatalog = getStandardModelCatalog();
+        const combinedSet = /* @__PURE__ */ new Set([...favs, ...engineModels, ...standardCatalog]);
+        const allModels = Array.from(combinedSet);
+        const rest = allModels.filter((m) => !favs.includes(m));
+        const pageSize = 6;
+        const pool = page === 0 ? favs : rest.slice((page - 1) * pageSize, page * pageSize);
+        const totalPages = Math.ceil(rest.length / pageSize) || 1;
+        const rows = pool.map((m, idx) => {
+          const meta = resolveModelMetadata(m);
+          const isCurrent = m === this.currentModel;
+          const cleanName = meta.name.length > 20 ? meta.name.slice(0, 18) + "\u2026" : meta.name;
+          return [
+            {
+              text: `${isCurrent ? "\u25CF " : ""}${cleanName} \xB7 ${meta.contextWindow}`,
+              callback_data: page === 0 ? `md:${idx}` : `md:raw:${m}`
+            }
+          ];
+        });
+        if (page === 0) {
+          if (rest.length > 0) {
+            rows.push([{ text: t("btn_all_models", this.language), callback_data: "pg:1" }]);
+          }
+          rows.push([{ text: t("btn_back", this.language), callback_data: "menu:home" }]);
+        } else {
+          const pagRow = [
+            { text: t("btn_favorites", this.language), callback_data: "pg:0" }
+          ];
+          if (rest.length > page * pageSize) {
+            pagRow.push({ text: t("btn_next", this.language), callback_data: `pg:${page + 1}` });
+          }
+          rows.push(pagRow);
+          rows.push([{ text: t("btn_back", this.language), callback_data: "menu:md" }]);
+        }
+        const curMeta = resolveModelMetadata(this.currentModel);
+        let cardText = this.language === "ar" ? `\u{1F916} <b>\u0646\u0645\u0627\u0630\u062C \u0627\u0644\u0630\u0643\u0627\u0621 \u0627\u0644\u0627\u0635\u0637\u0646\u0627\u0639\u064A \u0648\u0645\u0633\u0627\u062D\u0629 \u0627\u0644\u0633\u064A\u0627\u0642</b> ${page > 0 ? `(\u0635\u0641\u062D\u0629 ${page} \u0645\u0646 ${totalPages})` : "(\u0627\u0644\u0645\u0641\u0636\u0644\u0629)"}
+\u0627\u0644\u0646\u0645\u0648\u0630\u062C \u0627\u0644\u0646\u0634\u0637: <b>${escapeHtml(curMeta.name)}</b> (<code>${escapeHtml(curMeta.contextWindow)}</code>)
+
+` : `\u{1F916} <b>AI Models & Context Windows</b> ${page > 0 ? `(Page ${page} of ${totalPages})` : "(Favorites)"}
+Active: <b>${escapeHtml(curMeta.name)}</b> (<code>${escapeHtml(curMeta.contextWindow)}</code>)
+
+`;
+        for (const m of pool) {
+          const meta = resolveModelMetadata(m);
+          const isCurrent = m === this.currentModel;
+          cardText += `${isCurrent ? "\u25CF" : "\u2022"} <b>${escapeHtml(meta.name)}</b> (<code>${escapeHtml(meta.provider)}</code>)
+`;
+          cardText += `  <code>\u0627\u0644\u0633\u064A\u0627\u0642: ${escapeHtml(meta.contextWindow)} | ${escapeHtml(meta.tag)}</code>
+`;
+        }
+        cardText += this.language === "ar" ? `
+<i>\u0627\u0636\u063A\u0637 \u0639\u0644\u0649 \u0623\u064A \u0646\u0645\u0648\u0630\u062C \u0623\u062F\u0646\u0627\u0647 \u0644\u0644\u062A\u0628\u062F\u064A\u0644 \u0625\u0644\u064A\u0647 \u0641\u0648\u0631\u0627\u064B:</i>` : `
+<i>Tap any model below to activate immediately:</i>`;
+        await this.channel.sendMessage(
+          this.allowedChatId,
+          cardText.trim(),
+          { replyMarkup: this.wrapKeyboard(rows) }
+        );
+      }
       async sendModeMenu() {
         const rows = [
           [
-            { text: "\u{1F512} Read-Only", callback_data: "mo:read" },
-            { text: "\u{1F528} Build (Interactive)", callback_data: "mo:build" },
-            { text: "\u26A1 Auto Mode", callback_data: "mo:auto" }
+            { text: `${this.currentMode === "read" ? "\u25CF " : ""}\u{1F512} Read-Only`, callback_data: "mo:read" },
+            { text: `${this.currentMode === "build" ? "\u25CF " : ""}\u{1F528} Build (Interactive)`, callback_data: "mo:build" },
+            { text: `${this.currentMode === "auto" ? "\u25CF " : ""}\u26A1 Auto Mode`, callback_data: "mo:auto" }
+          ],
+          [
+            { text: t("btn_back", this.language), callback_data: "menu:home" }
           ]
         ];
-        const kb = {
-          rows: rows.map(
-            (r) => r.map((b) => ({ text: b.text, callbackData: b.callback_data, callback_data: b.callback_data }))
-          ),
-          inline_keyboard: rows
-        };
         await this.channel.sendMessage(
           this.allowedChatId,
           t("select_mode", this.language, { mode: this.currentMode }),
-          { replyMarkup: kb }
+          { replyMarkup: this.wrapKeyboard(rows) }
+        );
+      }
+      async sendSessionsMenu() {
+        const rows = [
+          [{ text: "\u2728 " + t("btn_new", this.language), callback_data: "new" }]
+        ];
+        if (this.activeRun && this.activeRun.sessionId) {
+          rows.unshift([{
+            text: `\u25CF Session: ${this.activeRun.sessionId.slice(0, 16)}\u2026`,
+            callback_data: `se:${this.activeRun.sessionId}`
+          }]);
+        }
+        rows.push([{ text: t("btn_back", this.language), callback_data: "menu:home" }]);
+        await this.channel.sendMessage(
+          this.allowedChatId,
+          `\u{1F4C2} <b>Active Sessions</b>
+Current: <code>${escapeHtml(this.activeRun?.sessionId || "None (New)")}</code>`,
+          { replyMarkup: this.wrapKeyboard(rows) }
         );
       }
+      async sendStatusReport() {
+        let branch = "unknown";
+        let dirtyCount = 0;
+        try {
+          const bRes = child_process3.spawnSync("git", ["branch", "--show-current"], {
+            cwd: this.targetDir,
+            encoding: "utf-8",
+            timeout: 5e3
+          });
+          if (bRes.status === 0) branch = bRes.stdout.trim() || "main";
+          const sRes = child_process3.spawnSync("git", ["status", "--porcelain"], {
+            cwd: this.targetDir,
+            encoding: "utf-8",
+            timeout: 5e3
+          });
+          if (sRes.status === 0) {
+            dirtyCount = sRes.stdout.trim().split("\n").filter(Boolean).length;
+          }
+        } catch {
+        }
+        const isBusy = this.activeRun && this.activeRun.busy ? "\u{1F7E2} Running" : "\u23F8 Idle";
+        const text = `
+\u{1F4CA} <b>System & Mission Control Status</b>
+\u{1F4C1} Workspace: <b>${escapeHtml(path3.basename(this.targetDir))}</b>
+<code>${escapeHtml(this.targetDir)}</code>
+\u{1F9E0} Agent: <b>${escapeHtml(this.currentAgent)}</b> (${escapeHtml(this.engine.name)})
+\u{1F916} Model: <b>${escapeHtml(this.currentModel || "Default")}</b>
+\u{1F512} Mode: <b>${escapeHtml(this.currentMode)}</b>
+\u{1F4E1} Channel: <b>${escapeHtml(this.channel.name)}</b>
+\u{1F4C2} Session: <code>${escapeHtml(this.activeRun?.sessionId || "None (Ready)")}</code>
+\u23F3 Status: <b>${isBusy}</b>
+\u{1F33F} Git Branch: <code>${escapeHtml(branch)}</code> \xB7 Modified files: <b>${dirtyCount}</b>
+`.trim();
+        await this.channel.sendMessage(this.allowedChatId, text, {
+          replyMarkup: this.getMainKeyboard()
+        });
+      }
+      getAllAvailableSkills() {
+        const candidates = [
+          path3.join(this.targetDir, ".agents", "skills"),
+          path3.join(this.targetDir, "docs", "ai", "skills"),
+          path3.join(this.targetDir, ".gemini", "skills")
+        ];
+        const map = /* @__PURE__ */ new Map();
+        for (const dir of candidates) {
+          if (!fs3.existsSync(dir)) continue;
+          try {
+            const items = fs3.readdirSync(dir, { withFileTypes: true });
+            for (const item of items) {
+              if (!item.isDirectory() && !item.isSymbolicLink()) continue;
+              if (item.name.startsWith(".")) continue;
+              const raw = item.name;
+              const clean = raw.replace(/^\d+-/, "");
+              if (!map.has(clean)) {
+                let desc;
+                const skillMd = path3.join(dir, raw, "SKILL.md");
+                if (fs3.existsSync(skillMd)) {
+                  try {
+                    const head = fs3.readFileSync(skillMd, "utf-8").slice(0, 600);
+                    const m = head.match(/description:\s*["']?([^"'\n\r]+)/i);
+                    if (m && m[1]) {
+                      desc = m[1].replace(/^[>"\s]+|[<"\s]+$/g, "").trim();
+                    }
+                  } catch {
+                  }
+                }
+                map.set(clean, {
+                  id: clean,
+                  name: clean,
+                  description: desc
+                });
+              }
+            }
+          } catch {
+          }
+        }
+        if (map.size === 0) {
+          const defaults = [
+            "frontend",
+            "query-performance",
+            "erp-debug",
+            "security-audit",
+            "git-hygiene",
+            "financial-expert",
+            "rveta-core",
+            "laravel-architecture"
+          ];
+          defaults.forEach((d) => map.set(d, { id: d, name: d }));
+        }
+        return Array.from(map.values()).sort((a, b) => a.name.localeCompare(b.name));
+      }
+      async sendSkillsMenu(page = 0) {
+        const allSkills = this.getAllAvailableSkills();
+        const pageSize = 8;
+        const totalPages = Math.ceil(allSkills.length / pageSize) || 1;
+        const safePage = Math.min(Math.max(0, page), totalPages - 1);
+        const pool = allSkills.slice(safePage * pageSize, (safePage + 1) * pageSize);
+        const rows = [];
+        let currentRow = [];
+        for (const sk of pool) {
+          const isCurrent = sk.name === this.activeSkill;
+          currentRow.push({
+            text: `${isCurrent ? "\u25CF " : ""}\u{1F9F0} ${sk.name}`,
+            callback_data: `sk:${sk.name}`
+          });
+          if (currentRow.length === 2) {
+            rows.push(currentRow);
+            currentRow = [];
+          }
+        }
+        if (currentRow.length > 0) rows.push(currentRow);
+        const pagRow = [];
+        if (safePage > 0) {
+          pagRow.push({ text: "\u2B05\uFE0F \u0627\u0644\u0633\u0627\u0628\u0642", callback_data: `skpage:${safePage - 1}` });
+        }
+        if (safePage < totalPages - 1) {
+          pagRow.push({ text: "\u27A1\uFE0F \u0627\u0644\u0645\u0632\u064A\u062F \u0645\u0646 \u0627\u0644\u0645\u0647\u0627\u0631\u0627\u062A", callback_data: `skpage:${safePage + 1}` });
+        }
+        if (pagRow.length > 0) {
+          rows.push(pagRow);
+        }
+        rows.push([{ text: t("btn_back", this.language), callback_data: "menu:home" }]);
+        let cardText = this.language === "ar" ? `\u{1F9F0} <b>\u0645\u0647\u0627\u0631\u0627\u062A \u0648\u0643\u0644\u0627\u0621 \u0627\u0644\u0630\u0643\u0627\u0621 \u0627\u0644\u0627\u0635\u0637\u0646\u0627\u0639\u064A (Agent Skills)</b> (\u0635\u0641\u062D\u0629 ${safePage + 1} \u0645\u0646 ${totalPages} \xB7 \u0625\u062C\u0645\u0627\u0644\u064A ${allSkills.length} \u0645\u0647\u0627\u0631\u0629)
+\u0627\u0644\u0645\u0647\u0627\u0631\u0629 \u0627\u0644\u0645\u0641\u0639\u0644\u0629: <b>${escapeHtml(this.activeSkill || "\u0628\u062F\u0648\u0646 (\u0648\u0643\u064A\u0644 \u0639\u0627\u0645)")}</b>
+
+` : `\u{1F9F0} <b>Available Agent Skills</b> (Page ${safePage + 1} of ${totalPages} \xB7 Total: ${allSkills.length})
+Active: <b>${escapeHtml(this.activeSkill || "None (Standard Agent)")}</b>
+
+`;
+        for (const sk of pool) {
+          const isCurrent = sk.name === this.activeSkill;
+          const descSnippet = sk.description ? sk.description.slice(0, 60) + (sk.description.length > 60 ? "\u2026" : "") : "\u0645\u0647\u0627\u0631\u0629 \u0645\u062A\u062E\u0635\u0635\u0629";
+          cardText += `${isCurrent ? "\u25CF" : "\u2022"} <b>${escapeHtml(sk.name)}</b>
+`;
+          cardText += `  <code>${escapeHtml(descSnippet)}</code>
+`;
+        }
+        cardText += this.language === "ar" ? `
+<i>\u0627\u062E\u062A\u0631 \u0627\u0644\u0645\u0647\u0627\u0631\u0629 \u0644\u062A\u0648\u062C\u064A\u0647 \u0627\u0644\u0648\u0643\u064A\u0644 \u0627\u0644\u0628\u0631\u0645\u062C\u064A \u0644\u0644\u0639\u0645\u0644 \u0628\u0647\u0627 \u0641\u0648\u0631\u0627\u064B:</i>` : `
+<i>Select a skill to prime the agent for execution:</i>`;
+        await this.channel.sendMessage(
+          this.allowedChatId,
+          cardText.trim(),
+          { replyMarkup: this.wrapKeyboard(rows) }
+        );
+      }
+      async sendUsageReport() {
+        const cfg = this.cfgManager.config;
+        const text = `
+\u{1F4C8} <b>Resource Usage & Quotas</b>
+\u2022 Daily Limit: <b>${cfg.dailyLimit} tasks</b>
+\u2022 Task Timeout: <b>${Math.round(cfg.runTimeout / 60)} minutes</b>
+\u2022 Workspace ID: <code>${escapeHtml(this.cfgManager.workspaceId)}</code>
+\u2022 Platform: <b>${os2.platform()} (${os2.arch()})</b>
+`.trim();
+        await this.channel.sendMessage(this.allowedChatId, text, {
+          replyMarkup: this.getMainKeyboard()
+        });
+      }
+      async sendLanguageMenu() {
+        const cur = this.language;
+        const rows = [
+          [{ text: `${cur === "en" ? "\u25CF " : ""}\u{1F1FA}\u{1F1F8} English`, callback_data: "lang:en" }],
+          [{ text: `${cur === "ar" ? "\u25CF " : ""}\u{1F1F8}\u{1F1E6} \u0627\u0644\u0639\u0631\u0628\u064A\u0629`, callback_data: "lang:ar" }],
+          [{ text: t("btn_back", this.language), callback_data: "menu:home" }]
+        ];
+        await this.channel.sendMessage(
+          this.allowedChatId,
+          t("select_language", this.language),
+          { replyMarkup: this.wrapKeyboard(rows) }
+        );
+      }
+      async sendHandoffReport() {
+        let branch = "unknown";
+        let dirtyLines = [];
+        let commits = [];
+        try {
+          const b = child_process3.spawnSync("git", ["branch", "--show-current"], { cwd: this.targetDir, encoding: "utf-8", timeout: 5e3 });
+          if (b.status === 0) branch = b.stdout.trim() || "main";
+          const s = child_process3.spawnSync("git", ["status", "--porcelain"], { cwd: this.targetDir, encoding: "utf-8", timeout: 5e3 });
+          if (s.status === 0) dirtyLines = s.stdout.trim().split("\n").filter(Boolean);
+          const c = child_process3.spawnSync("git", ["log", "-5", "--oneline"], { cwd: this.targetDir, encoding: "utf-8", timeout: 5e3 });
+          if (c.status === 0) commits = c.stdout.trim().split("\n").filter(Boolean);
+        } catch {
+        }
+        const dirtyPreview = dirtyLines.slice(0, 10).map((l) => `  ${l}`).join("\n") || "  (Clean working tree)";
+        const commitsPreview = commits.map((c) => `  ${c}`).join("\n") || "  (No commits)";
+        const text = `
+<b>HANDOFF \u2014 Resume task in another tool</b>
+Repo: <code>${escapeHtml(this.targetDir)}</code> (Branch: <code>${escapeHtml(branch)}</code>)
+Uncommitted files: <b>${dirtyLines.length}</b>
+<pre><code>${escapeHtml(dirtyPreview)}</code></pre>
+Last commits:
+<pre><code>${escapeHtml(commitsPreview)}</code></pre>
+Agent: <b>${escapeHtml(this.currentAgent)}</b> | Mode: <b>${escapeHtml(this.currentMode)}</b>
+`.trim();
+        await this.channel.sendMessage(this.allowedChatId, text, {
+          replyMarkup: this.getMainKeyboard()
+        });
+      }
       async sendWorkspaceMenu() {
         const workspaces = this.cfgManager.config.workspaces;
         const rows = workspaces.map((ws, i) => [
@@ -2131,16 +3000,11 @@ Workspace: \u{1F4C1} <code>${escapeHtml2(path3.basename(this.targetDir))}</code>
             callback_data: `ws:${i}`
           }
         ]);
-        const kb = {
-          rows: rows.map(
-            (r) => r.map((b) => ({ text: b.text, callbackData: b.callback_data, callback_data: b.callback_data }))
-          ),
-          inline_keyboard: rows
-        };
+        rows.push([{ text: t("btn_back", this.language), callback_data: "menu:home" }]);
         await this.channel.sendMessage(
           this.allowedChatId,
-          t("select_workspace", this.language, { ws: escapeHtml2(this.targetDir) }),
-          { replyMarkup: kb }
+          t("select_workspace", this.language, { ws: escapeHtml(this.targetDir) }),
+          { replyMarkup: this.wrapKeyboard(rows) }
         );
       }
       async switchWorkspace(newPath) {
@@ -2148,14 +3012,14 @@ Workspace: \u{1F4C1} <code>${escapeHtml2(path3.basename(this.targetDir))}</code>
         if (!fs3.existsSync(resolved)) {
           await this.channel.sendMessage(
             this.allowedChatId,
-            t("ws_not_found", this.language, { path: escapeHtml2(resolved) })
+            t("ws_not_found", this.language, { path: escapeHtml(resolved) })
           );
           return;
         }
         if (this.activeRun && this.activeRun.busy) {
           await this.channel.sendMessage(
             this.allowedChatId,
-            t("ws_busy", this.language, { ws: escapeHtml2(this.targetDir) })
+            t("ws_busy", this.language, { ws: escapeHtml(this.targetDir) })
           );
           return;
         }
@@ -2170,8 +3034,8 @@ Workspace: \u{1F4C1} <code>${escapeHtml2(path3.basename(this.targetDir))}</code>
         await this.channel.sendMessage(
           this.allowedChatId,
           t("ws_changed", this.language, {
-            name: escapeHtml2(path3.basename(resolved)),
-            ws: escapeHtml2(resolved),
+            name: escapeHtml(path3.basename(resolved)),
+            ws: escapeHtml(resolved),
             branch: "main",
             dirty: "0"
           }),
@@ -2186,7 +3050,7 @@ Workspace: \u{1F4C1} <code>${escapeHtml2(path3.basename(this.targetDir))}</code>
             return;
           }
           const preview = diff.length <= 3500 ? diff : diff.slice(0, 3500) + "\n\u2026 (truncated)";
-          await this.channel.sendMessage(this.allowedChatId, `<pre><code>${escapeHtml2(preview)}</code></pre>`);
+          await this.channel.sendMessage(this.allowedChatId, `<pre><code>${escapeHtml(preview)}</code></pre>`);
         } catch (err) {
           await this.channel.sendMessage(this.allowedChatId, `\u274C Diff error: ${err.message}`);
         }
@@ -2211,36 +3075,36 @@ function getEntryPoint() {
   if (fs4.existsSync(distEntry)) return distEntry;
   return path4.join(root, "bin", "agentgram.js");
 }
-var os2, path4, fs4, import_node_child_process, MACOS_PLIST_NAME, LEGACY_MACOS_PLIST_NAME, MACOS_PLIST_DIR, MACOS_PLIST_PATH, LEGACY_MACOS_PLIST_PATH, LINUX_SERVICE_NAME, LEGACY_LINUX_SERVICE_NAME, LINUX_SERVICE_DIR, LINUX_SERVICE_PATH, LEGACY_LINUX_SERVICE_PATH, ServiceManager;
+var os3, path4, fs4, import_node_child_process, MACOS_PLIST_NAME, LEGACY_MACOS_PLIST_NAME, MACOS_PLIST_DIR, MACOS_PLIST_PATH, LEGACY_MACOS_PLIST_PATH, LINUX_SERVICE_NAME, LEGACY_LINUX_SERVICE_NAME, LINUX_SERVICE_DIR, LINUX_SERVICE_PATH, LEGACY_LINUX_SERVICE_PATH, ServiceManager;
 var init_service_manager = __esm({
   "src/service/service-manager.ts"() {
     "use strict";
-    os2 = __toESM(require("os"));
+    os3 = __toESM(require("os"));
     path4 = __toESM(require("path"));
     fs4 = __toESM(require("fs"));
     import_node_child_process = require("child_process");
     MACOS_PLIST_NAME = "com.agentgram.plist";
     LEGACY_MACOS_PLIST_NAME = "com.rumuze.edit.plist";
-    MACOS_PLIST_DIR = path4.join(os2.homedir(), "Library", "LaunchAgents");
+    MACOS_PLIST_DIR = path4.join(os3.homedir(), "Library", "LaunchAgents");
     MACOS_PLIST_PATH = path4.join(MACOS_PLIST_DIR, MACOS_PLIST_NAME);
     LEGACY_MACOS_PLIST_PATH = path4.join(MACOS_PLIST_DIR, LEGACY_MACOS_PLIST_NAME);
     LINUX_SERVICE_NAME = "agentgram.service";
     LEGACY_LINUX_SERVICE_NAME = "rumuze-edit.service";
-    LINUX_SERVICE_DIR = path4.join(os2.homedir(), ".config", "systemd", "user");
+    LINUX_SERVICE_DIR = path4.join(os3.homedir(), ".config", "systemd", "user");
     LINUX_SERVICE_PATH = path4.join(LINUX_SERVICE_DIR, LINUX_SERVICE_NAME);
     LEGACY_LINUX_SERVICE_PATH = path4.join(LINUX_SERVICE_DIR, LEGACY_LINUX_SERVICE_NAME);
     ServiceManager = class {
       static install(targetDir) {
-        const platform3 = os2.platform();
+        const platform4 = os3.platform();
         const nodeExec = process.execPath;
         const script = getEntryPoint();
         const resolvedTarget = path4.resolve(targetDir || process.cwd());
-        const logDir = path4.join(os2.homedir(), ".config", "agentgram");
+        const logDir = path4.join(os3.homedir(), ".config", "agentgram");
         try {
           if (!fs4.existsSync(logDir)) fs4.mkdirSync(logDir, { recursive: true, mode: 448 });
         } catch {
         }
-        if (platform3 === "darwin") {
+        if (platform4 === "darwin") {
           try {
             if (!fs4.existsSync(MACOS_PLIST_DIR)) {
               fs4.mkdirSync(MACOS_PLIST_DIR, { recursive: true });
@@ -2248,7 +3112,7 @@ var init_service_manager = __esm({
             (0, import_node_child_process.spawnSync)("launchctl", ["unload", MACOS_PLIST_PATH]);
             (0, import_node_child_process.spawnSync)("launchctl", ["unload", LEGACY_MACOS_PLIST_PATH]);
             let pathEnv = process.env.PATH || "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin";
-            const opencodeBin = path4.join(os2.homedir(), ".opencode", "bin");
+            const opencodeBin = path4.join(os3.homedir(), ".opencode", "bin");
             if (!pathEnv.includes(opencodeBin)) {
               pathEnv = `${opencodeBin}:${pathEnv}`;
             }
@@ -2299,11 +3163,16 @@ var init_service_manager = __esm({
           } catch (err) {
             return { success: false, message: err.message };
           }
-        } else if (platform3 === "linux") {
+        } else if (platform4 === "linux") {
           try {
             if (!fs4.existsSync(LINUX_SERVICE_DIR)) {
               fs4.mkdirSync(LINUX_SERVICE_DIR, { recursive: true });
             }
+            let pathEnv = process.env.PATH || "/usr/local/bin:/usr/bin:/bin";
+            const opencodeBin = path4.join(os3.homedir(), ".opencode", "bin");
+            if (!pathEnv.includes(opencodeBin)) {
+              pathEnv = `${opencodeBin}:${pathEnv}`;
+            }
             const unitContent = `[Unit]
 Description=AgentGram AI Telegram Mission Control
 After=network.target
@@ -2311,6 +3180,7 @@ After=network.target
 [Service]
 Type=simple
 WorkingDirectory=${resolvedTarget}
+Environment="PATH=${pathEnv}"
 ExecStart=${nodeExec} ${script} start --dir ${resolvedTarget}
 Restart=always
 RestartSec=5
@@ -2333,12 +3203,12 @@ WantedBy=default.target
         }
         return {
           success: false,
-          message: `Background service automation is not currently supported on OS: ${platform3}`
+          message: `Background service automation is not currently supported on OS: ${platform4}`
         };
       }
       static uninstall() {
-        const platform3 = os2.platform();
-        if (platform3 === "darwin") {
+        const platform4 = os3.platform();
+        if (platform4 === "darwin") {
           for (const p of [MACOS_PLIST_PATH, LEGACY_MACOS_PLIST_PATH]) {
             if (fs4.existsSync(p)) {
               (0, import_node_child_process.spawnSync)("launchctl", ["unload", p]);
@@ -2349,11 +3219,12 @@ WantedBy=default.target
             }
           }
           return { success: true, message: "Uninstalled macOS launchd service." };
-        } else if (platform3 === "linux") {
-          for (const [name, p] of [
+        } else if (platform4 === "linux") {
+          const services = [
             [LINUX_SERVICE_NAME, LINUX_SERVICE_PATH],
             [LEGACY_LINUX_SERVICE_NAME, LEGACY_LINUX_SERVICE_PATH]
-          ]) {
+          ];
+          for (const [name, p] of services) {
             if (fs4.existsSync(p)) {
               (0, import_node_child_process.spawnSync)("systemctl", ["--user", "stop", name]);
               (0, import_node_child_process.spawnSync)("systemctl", ["--user", "disable", name]);
@@ -2366,11 +3237,11 @@ WantedBy=default.target
           (0, import_node_child_process.spawnSync)("systemctl", ["--user", "daemon-reload"]);
           return { success: true, message: "Uninstalled Linux systemd service." };
         }
-        return { success: false, message: `Unsupported OS: ${platform3}` };
+        return { success: false, message: `Unsupported OS: ${platform4}` };
       }
       static status() {
-        const platform3 = os2.platform();
-        if (platform3 === "darwin") {
+        const platform4 = os3.platform();
+        if (platform4 === "darwin") {
           const res = (0, import_node_child_process.spawnSync)("launchctl", ["list"], { encoding: "utf-8" });
           const running = res.stdout && (res.stdout.includes("com.agentgram") || res.stdout.includes("com.rumuze.edit")) || false;
           const installed = fs4.existsSync(MACOS_PLIST_PATH) || fs4.existsSync(LEGACY_MACOS_PLIST_PATH);
@@ -2378,10 +3249,10 @@ WantedBy=default.target
           return {
             installed,
             running,
-            system: platform3,
+            system: platform4,
             path: installed ? activePath : void 0
           };
-        } else if (platform3 === "linux") {
+        } else if (platform4 === "linux") {
           const res = (0, import_node_child_process.spawnSync)("systemctl", ["--user", "is-active", LINUX_SERVICE_NAME], {
             encoding: "utf-8"
           });
@@ -2399,11 +3270,11 @@ WantedBy=default.target
           return {
             installed,
             running,
-            system: platform3,
+            system: platform4,
             path: installed ? activePath : void 0
           };
         }
-        return { installed: false, running: false, system: platform3 };
+        return { installed: false, running: false, system: platform4 };
       }
     };
   }
@@ -2459,9 +3330,9 @@ function getPidFilePath() {
 }
 function checkOpenCodeCli() {
   try {
-    const isWin = os3.platform() === "win32";
+    const isWin = os4.platform() === "win32";
     const cmd = isWin ? "where" : "which";
-    const res = child_process3.spawnSync(cmd, ["opencode"], { encoding: "utf-8" });
+    const res = child_process4.spawnSync(cmd, ["opencode"], { encoding: "utf-8" });
     return res.status === 0 && res.stdout.trim().length > 0;
   } catch {
     return false;
@@ -2690,7 +3561,7 @@ Please run ${C.bold}${C.cyan}agentgram init${C.reset} to set up your Telegram cr
       "--engine",
       selectedEngine
     ];
-    const child = child_process3.spawn(process.execPath, spawnArgs, {
+    const child = child_process4.spawn(process.execPath, spawnArgs, {
       cwd: targetDir,
       detached: true,
       stdio: ["ignore", out, err],
@@ -2723,15 +3594,22 @@ Please run ${C.bold}${C.cyan}agentgram init${C.reset} to set up your Telegram cr
   let engineAdapter;
   let spawnedOc;
   if (selectedEngine === "opencode") {
-    try {
-      info("Spawning private OpenCode server on loopback...");
-      spawnedOc = await OpenCodeClient.spawnServer(targetDir);
-      engineAdapter = new OpenCodeAdapter(spawnedOc.client, targetDir);
-      success(`OpenCode server online (port: ${spawnedOc.port}).`);
-    } catch (err) {
-      error(`Could not spawn OpenCode server: ${err.message}`);
-      log(`Make sure OpenCode is installed: ${C.cyan}npm i -g opencode-ai${C.reset}`);
-      process.exit(1);
+    const envUrl = process.env.OPENCODE_URL;
+    if (envUrl) {
+      info(`Connecting to configured OpenCode server at: ${C.cyan}${envUrl}${C.reset}`);
+      const ocClient = new OpenCodeClient(envUrl, process.env.OPENCODE_SERVER_PASSWORD, targetDir);
+      engineAdapter = new OpenCodeAdapter(ocClient, targetDir);
+    } else {
+      try {
+        info("Spawning private OpenCode server on loopback...");
+        spawnedOc = await OpenCodeClient.spawnServer(targetDir);
+        engineAdapter = new OpenCodeAdapter(spawnedOc.client, targetDir);
+        success(`OpenCode server online (port: ${spawnedOc.port}).`);
+      } catch (err) {
+        warn(`Could not spawn OpenCode server: ${err.message}`);
+        warn("Resilience mode active: Falling back to Shell CLI Engine so Telegram bot connects immediately.");
+        engineAdapter = new ShellEngineAdapter({ workspaceDir: targetDir, cliCommand: "sh" });
+      }
     }
   } else if (selectedEngine === "shell" || selectedEngine === "sh" || selectedEngine === "bash") {
     engineAdapter = new ShellEngineAdapter({ workspaceDir: targetDir, cliCommand: "sh" });
@@ -2823,7 +3701,7 @@ function cmdStatus() {
     info(`System Service (${svc.system}): Not installed`);
   }
   try {
-    const ps = child_process3.spawnSync("pgrep", ["-fl", "opencode serve"], { encoding: "utf-8" });
+    const ps = child_process4.spawnSync("pgrep", ["-fl", "opencode serve"], { encoding: "utf-8" });
     if (ps.status === 0 && ps.stdout.trim()) {
       success(`OpenCode Server: Active (${ps.stdout.trim().split("\n")[0]})`);
     } else {
@@ -2924,15 +3802,15 @@ async function runCli(argv = process.argv.slice(2)) {
       process.exit(1);
   }
 }
-var fs5, os3, path5, readline2, child_process3, VERSION, C;
+var fs5, os4, path5, readline2, child_process4, VERSION, C;
 var init_cli = __esm({
   "src/cli/index.ts"() {
     "use strict";
     fs5 = __toESM(require("fs"));
-    os3 = __toESM(require("os"));
+    os4 = __toESM(require("os"));
     path5 = __toESM(require("path"));
     readline2 = __toESM(require("readline"));
-    child_process3 = __toESM(require("child_process"));
+    child_process4 = __toESM(require("child_process"));
     init_config_manager();
     init_telegram_client();
     init_opencode_client();
@@ -2944,7 +3822,7 @@ var init_cli = __esm({
     init_shell_adapter();
     init_registry2();
     init_service_manager();
-    VERSION = "2.0.0";
+    VERSION = "2.0.4";
     C = {
       reset: "\x1B[0m",
       bold: "\x1B[1m",
@@ -2985,7 +3863,7 @@ __export(index_exports, {
   computeWorkspaceId: () => computeWorkspaceId,
   decidePermission: () => decidePermission,
   ensureConfigDirs: () => ensureConfigDirs,
-  escapeHtml: () => escapeHtml2,
+  escapeHtml: () => escapeHtml,
   fromTelegramMarkup: () => fromTelegramMarkup,
   getEntryPoint: () => getEntryPoint,
   getFreePort: () => getFreePort,