@mrtrinhvn/ag-kit 1.1.6 → 1.1.9

package/bin/cli.js

@@ -1,12 +1,32 @@
 #!/usr/bin/env node
-
 const { program } = require('commander');
 const fs = require('fs');
 const path = require('path');
+const net = require('net');
 
 const TEMPLATE_DIR = path.join(__dirname, '..', 'template');
 const TARGET_AGENT_DIR = path.join(process.cwd(), '.agent');
 
+function isPortAvailable(port) {
+  return new Promise((resolve) => {
+    const server = net.createServer();
+    server.once('error', () => resolve(false));
+    server.once('listening', () => {
+      server.close();
+      resolve(true);
+    });
+    server.listen(port, '127.0.0.1');
+  });
+}
+
+async function findNextAvailablePort(startPort) {
+  let port = startPort;
+  while (!(await isPortAvailable(port))) {
+    port++;
+  }
+  return port;
+}
+
 // Helper copy đệ quy
 function copyRecursiveSync(src, dest) {
   const exists = fs.existsSync(src);
@@ -75,20 +95,35 @@ program.command('init')
       copyRecursiveSync(srcAgent, TARGET_AGENT_DIR);
       // Ghi lại version vào .agent/.version
       fs.writeFileSync(path.join(TARGET_AGENT_DIR, '.version'), pkg.version);
-      console.log('\x1b[32m✅ Đã cài ráp thành công thư mục .agent vào Project!\x1b[0m');
+      console.log(`\x1b[32m✅ Đã cài ráp thành công thư mục .agent (phiên bản v${pkg.version}) vào Project!\x1b[0m`);
       
-      // Khởi tạo .env nếu chưa có
+      // Khởi động .env nếu chưa có
       const envPath = path.join(process.cwd(), '.env');
-      if (!fs.existsSync(envPath)) {
-        fs.writeFileSync(envPath, 'CDP_PORT=9555\n');
-        console.log('\x1b[34mℹ️  Đã tạo file .env mẫu với CDP_PORT=9555\x1b[0m');
-      } else {
-        const envContent = fs.readFileSync(envPath, 'utf-8');
-        if (!envContent.includes('CDP_PORT=')) {
-          fs.appendFileSync(envPath, '\nCDP_PORT=9555\n');
-          console.log('\x1b[34mℹ️  Đã thêm cấu hình CDP_PORT=9555 vào file .env hiện tại\x1b[0m');
+      (async () => {
+        const idePort = await findNextAvailablePort(9555);
+        const bridgePort = await findNextAvailablePort(idePort + 1);
+
+        if (!fs.existsSync(envPath)) {
+          const envTemplate = `# --- Remote Orchestration (Golden Combo) ---\nIDE_PORT=${idePort}\nBRIDGE_PORT=${bridgePort}\n\nPROJECT_NAME=ag-project\n`;
+          fs.writeFileSync(envPath, envTemplate);
+          console.log(`\x1b[34mℹ️  Đã tạo .env với IDE_PORT=${idePort} và BRIDGE_PORT=${bridgePort}\x1b[0m`);
+        } else {
+          let envContent = fs.readFileSync(envPath, 'utf-8');
+          let changed = false;
+          if (!envContent.includes('IDE_PORT=')) {
+            envContent += `\nIDE_PORT=${idePort}\n`;
+            changed = true;
+          }
+          if (!envContent.includes('BRIDGE_PORT=')) {
+            envContent += `BRIDGE_PORT=${bridgePort}\n`;
+            changed = true;
+          }
+          if (changed) {
+            fs.writeFileSync(envPath, envContent);
+            console.log(`\x1b[34mℹ️  Đã bổ sung cổng tự động: IDE_PORT=${idePort}, BRIDGE_PORT=${bridgePort}\x1b[0m`);
+          }
         }
-      }
+      })();
     } else {
       console.log('\x1b[33m⚠️ Thư mục .agent đã tồn tại.\x1b[0m');
       const vPath = path.join(TARGET_AGENT_DIR, '.version');
@@ -97,7 +132,7 @@ program.command('init')
         if (installedVersion !== pkg.version) {
           console.log(`\x1b[35m👉 Phát hiện phiên bản cũ (v${installedVersion}). Hãy dùng lệnh "ag-kit update" để cập nhật lên v${pkg.version}.\x1b[0m`);
         } else {
-          console.log('\x1b[34mℹ️  Bạn đang sử dụng phiên bản khớp với bộ công cụ (v${pkg.version}).\x1b[0m');
+          console.log(`\x1b[34mℹ️  Bạn đang sử dụng phiên bản khớp với bộ công cụ (v${pkg.version}).\x1b[0m`);
         }
       } else {
         console.log('\x1b[35m👉 Hãy dùng lệnh "ag-kit update" để đồng bộ cấu trúc mới.\x1b[0m');
@@ -112,11 +147,12 @@ program.command('update')
   .action(() => {
     console.log('\x1b[36m🔄 Đang cập nhật siêu luân xa Lập trình (AG-Kit)...\x1b[0m');
     const srcAgent = path.join(TEMPLATE_DIR, '.agent');
-    if (!fs.existsSync(TARGET_AGENT_DIR)) {
-      console.log('\x1b[31m❌ Không tìm thấy thư mục .agent. Hãy chạy "ag-kit init" trước.\x1b[0m');
-      return;
+    const vPath = path.join(TARGET_AGENT_DIR, '.version');
+    let oldVersion = '0.0.0';
+    if (fs.existsSync(vPath)) {
+      oldVersion = fs.readFileSync(vPath, 'utf-8').trim();
     }
-    
+
     // Chỉ cập nhật não bộ chuẩn (Agents, Skills, Workflows, Scripts, Rules)
     // Tôn trọng dữ liệu Knowledge của dự án đang có
     ['agents', 'skills', 'workflows', 'scripts', 'rules'].forEach(folder => {
@@ -129,8 +165,9 @@ program.command('update')
 
     migrateLegacyMemories();
     // Cập nhật version vào .agent/.version
-    fs.writeFileSync(path.join(TARGET_AGENT_DIR, '.version'), pkg.version);
-    console.log('\x1b[32m✅ Cập nhật thành công 100% Cấu trúc kỹ năng siêu cấp!\x1b[0m');
+    fs.writeFileSync(vPath, pkg.version);
+    console.log(`\x1b[32m✅ Cập nhật thành công! Phiên bản hiện tại: v${oldVersion} -> v${pkg.version}\x1b[0m`);
+    console.log('\x1b[34m⚡️ Toàn bộ cấu trúc kỹ năng đã được đồng bộ.\x1b[0m');
   });
 
 program.command('check')
@@ -243,10 +280,13 @@ program.command('status')
   });
 
 
-if (process.argv.length <= 2) {
+async function runInteractiveMenu() {
   const inquirer = require('inquirer');
+  console.clear();
   console.log('\x1b[35m\n🧠 ANTIGRAVITY KIT - BẢNG ĐIỀU KHIỂN TÁC VỤ\x1b[0m');
-  inquirer.prompt([
+  console.log('\x1b[34m━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\x1b[0m');
+
+  const { action } = await inquirer.prompt([
     {
       type: 'list',
       name: 'action',
@@ -260,10 +300,37 @@ if (process.argv.length <= 2) {
         { name: '❌ Thoát', value: 'exit' }
       ]
     }
-  ]).then(answers => {
-    if (answers.action !== 'exit') {
-      program.parse([process.argv[0], process.argv[1], answers.action]);
+  ]);
+
+  if (action === 'exit') {
+    console.log('\x1b[36m👋 Tạm biệt! Hợp tác vui vẻ.\x1b[0m\n');
+    process.exit(0);
+  }
+
+  // Thực thi command
+  console.log('\n\x1b[34m--- ĐANG THỰC THI ---\x1b[0m');
+  
+  // Chúng ta parse lại command với action đã chọn
+  // Lưu ý: commander parse() trả về promise với parseAsync
+  await program.parseAsync([process.argv[0], process.argv[1], action]);
+  
+  console.log('\n\x1b[34m--- HOÀN TẤT TÁC VỤ ---\x1b[0m');
+  
+  const { resume } = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'resume',
+      message: 'Nhấn Enter để quay lại Menu quản trị...'
     }
+  ]);
+
+  return runInteractiveMenu();
+}
+
+if (process.argv.length <= 2) {
+  runInteractiveMenu().catch(err => {
+    console.error('\x1b[31m❌ Lỗi thực thi Menu:\x1b[0m', err);
+    process.exit(1);
   });
 } else {
   program.parse(process.argv);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mrtrinhvn/ag-kit",
-  "version": "1.1.6",
+  "version": "1.1.9",
   "description": "Antigravity Kit Base Framework - Generic Agentic AI Programming Core",
   "main": "index.js",
   "bin": {

package/template/.agent/knowledge/tele-agentic-standard.md

@@ -1,32 +1,30 @@
 # TIÊU CHUẨN GIAO TIẾP TẬP TRUNG (TELE-AGENTIC STANDARD)
 
-Dự án này áp dụng mô hình **Cổng Agentic Hợp Nhất (Unified Agentic Gateway)**, nơi IDE, Bot Telegram và Nhóm Telegram kết nối thành một "Bộ não" duy nhất.
+Hệ thống kế thừa tinh hoa từ các tiêu chuẩn điều khiển từ xa: **Remoat**, **LazyGravity** và tối ưu token **VFS**.
 
 ## 📡 KIẾN TRÚC "COMBO VÀNG" (GOLDEN COMBO)
 
-Hệ thống được vận hành bởi 3 trụ cột:
-1.  **IDE (Antigravity)**: Đóng vai trò là **Node Tham gia (Participant)**. Không chỉ để gõ code mà còn là Dashboard trực quan.
-2.  **Telegram Bot/Groups**: Đóng vai trò là **Cổng Giao tiếp & Phê duyệt (Gateway)**.
-3.  **CDP Bridge (`ag_portal_bridge.js`)**: Đóng vai trò là **Hệ thần kinh (Nervous System)** kết nối 2 thành phần trên.
+Hệ thống được vận hành bởi 3 trụ cột (Nguồn: [Remoat Strategy](https://github.com/optimistengineer/Remoat)):
+1.  **IDE Participant**: Antigravity đóng vai trò là thực thể thực thi duy nhất, khởi động ở chế độ Debug (`--remote-debugging-port=9555`).
+2.  **Telegram Gateway**: Cổng giao tiếp tập trung qua Bot & Group Topics (Nguồn: [LazyGravity Patterns](https://github.com/tokyoweb3/LazyGravity)).
+3.  **CDP Bridge**: Cầu nối WebSocket kết nối "Lễ tân" (Bot) và "Quản đốc" (IDE).
 
-### 1. Phân Lập Trí Nhớ Theo Topic (Group Topics)
-Nhóm Telegram được chia thành các Topic để cô lập bối cảnh:
--   **Topic 🔴 Surgery (Phẫu thuật)**: Chuyên dụng cho các lệnh `/heal` và workflow `@brain-surgeon`.
--   **Topic 🟢 Signals (Tín hiệu)**: Hiển thị lệnh mua/bán từ AI.
--   **Topic 🔵 General (Tổng quan)**: Quản trị hệ thống, lệnh `/status`.
+### 1. Phân Lập Trí Nhớ (Topic Memory)
+Sử dụng Telegram Topics để cô lập bối cảnh công việc. Lựa chọn Topic phù hợp giúp Agent không bị "loạn não" giữa các Task khác nhau.
 
-### 2. Giao Diện IDE Portal (HUD)
-IDE nạp file `scripts/ag_hud.js` qua CDP để hiển thị:
--   **Gen/WinRate**: Chỉ số tiến hóa của AI Brain.
--   **Stall Alert**: Cảnh báo đỏ khi AI ngừng tiến bộ.
--   **Doctor Call**: Nút bấm kích hoạt Logic tự chữa lành.
+### 2. Giao Diện Premium (Aesthetics)
+Dựa trên [awesome-grammY](https://github.com/grammyjs/awesome-grammY), giao diện phải đủ sang trọng (Premium) và rõ ràng:
+- **Dashboard**: Lệnh `/status` hiển thị bảng sức khỏe AI chuyên sâu.
+- **Micro-interactions**: Nút bấm Inline với ID ngắn (ShortID) để quản trị nhanh trên Mobile.
 
-## 🛠️ QUY TRÌNH VẬN HÀNH (OPERATIONAL LOOP)
+## 🛠️ CHIẾN LƯỢC TOÀN DIỆN (STRATEGIC PROTOCOL)
 
-1.  **Phát hiện (Detect)**: `LearningService` phát hiện lỗi/stall -> Cập nhật `ai_state.json`.
-2.  **Cảnh báo (Alert)**: Bridge đẩy dữ liệu lên HUD IDE (Cảnh báo đỏ) và Bot gửi tin nhắn Telegram Group.
-3.  **Phê duyệt (Approve)**: Người dùng nhấn nút trên HUD hoặc Telegram Callback.
-4.  **Hành động (Act)**: IDE Agent (Antigravity) tự động kích hoạt workflow `/debug` để sửa code.
+1.  **Tiết kiệm Token (VFS Protocol)**: PHẢI sử dụng công cụ [vfs](https://github.com/TrNgTien/vfs) để quét cấu trúc mã nguồn trước khi đọc file. Kỹ thuật này giúp tiết kiệm 98% chi phí vận hành.
+2.  **Model Selection (Local vs Cloud)**:
+    - Sử dụng **Local Models** (Ollama Host) cho các bước phân tích, tìm lỗi và lập phác đồ (Regent mode).
+    - Sử dụng **Cloud Models** (Claude/Gemini) cho bước ghi mã nguồn (Implementation) và giải quyết logic cực khó.
+3.  **Scripts Đồng Bộ**: Hệ thống phải đi kèm bộ đôi `start.sh` (khởi chạy bot + debugger) và `stop_bot.sh` (tắt an toàn).
 
 ---
-*Tham chiếu: .agent/skills/telegram-agentic-gateway*
+*Tham chiếu Skill: .agent/skills/telegram-agentic-gateway*
+*Nguồn gốc Kiến thức: Remoat, LazyGravity, VFS, grammY.*

package/template/.agent/scripts/port_utils.sh

@@ -0,0 +1,67 @@
+#!/bin/bash
+
+# --- Port Management Utility (Golden V4) ---
+# Finds free ports and updates .env to ensure consistent project-wide communication.
+
+ENV_FILE=".env"
+
+# Logic tìm cổng trống
+function find_free_port() {
+    local port=$1
+    while netstat -atn | grep -q ":$port "; do
+        port=$((port + 1))
+    done
+    echo $port
+}
+
+# Cập nhật hoặc thêm cổng vào .env
+function update_env_port() {
+    local key=$1
+    local value=$2
+    
+    if grep -q "^${key}=" "$ENV_FILE"; then
+        # OS-compatible sed (Linux/macOS)
+        if [[ "$OSTYPE" == "darwin"* ]]; then
+            sed -i '' "s/^${key}=.*/${key}=${value}/" "$ENV_FILE"
+        else
+            sed -i "s/^${key}=.*/${key}=${value}/" "$ENV_FILE"
+        fi
+    else
+        echo "${key}=${value}" >> "$ENV_FILE"
+    fi
+}
+
+# --- Main Logic ---
+# 1. Đọc cổng hiện tại
+if [ -f "$ENV_FILE" ]; then
+    source "$ENV_FILE"
+fi
+
+ORIGINAL_IDE_PORT=${IDE_PORT:-9555}
+ORIGINAL_BRIDGE_PORT=${BRIDGE_PORT:-9556}
+
+# 2. Kiểm tra xung đột (IDE_PORT)
+# Nếu cổng IDE bận, và không phải là do IDE của chính dự án này chiếm giữ (kiểm tra qua /json endpoint)
+PORT_TAKEN=false
+if netstat -atn | grep -q ":$ORIGINAL_IDE_PORT "; then
+    # Kiểm tra xem folder dự án hiện tại có nằm trong danh sách tab/window của IDE không
+    if ! curl -s "http://127.0.0.1:$ORIGINAL_IDE_PORT/json" | grep -q "$PROJECT_DIR" > /dev/null 2>&1; then
+        PORT_TAKEN=true
+    fi
+fi
+
+if [ "$PORT_TAKEN" = true ]; then
+    echo "⚠️  Xung đột PORT phaát hieện! Đang tìm cổng mới..."
+    NEW_IDE_PORT=$(find_free_port $ORIGINAL_IDE_PORT)
+    NEW_BRIDGE_PORT=$(find_free_port $((NEW_IDE_PORT + 1)))
+    
+    update_env_port "IDE_PORT" "$NEW_IDE_PORT"
+    update_env_port "BRIDGE_PORT" "$NEW_BRIDGE_PORT"
+    
+    echo "✅ Đã cập nhật .env: IDE_PORT=$NEW_IDE_PORT, BRIDGE_PORT=$NEW_BRIDGE_PORT"
+    export IDE_PORT=$NEW_IDE_PORT
+    export BRIDGE_PORT=$NEW_BRIDGE_PORT
+else
+    export IDE_PORT=$ORIGINAL_IDE_PORT
+    export BRIDGE_PORT=$ORIGINAL_BRIDGE_PORT
+fi

package/template/.agent/scripts/receptionist_down.sh

@@ -0,0 +1,37 @@
+#!/bin/bash
+
+# --- Antigravity Unified Shutdown (Agent-Defined V3) ---
+# Dọn dẹp trạm gác theo Port Isolation.
+
+PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$PROJECT_DIR"
+
+if [ -f .env ]; then
+    source .env
+fi
+
+BRIDGE_PORT=${BRIDGE_PORT:-9556}
+
+echo "════════════════════════════════════════════════════"
+echo "  🚑 SHUTTING DOWN GATEWAY [$BRIDGE_PORT]..."
+echo "════════════════════════════════════════════════════"
+
+# 1. Tắt Portal Bridge (HUD)
+BRIDGE_PID_FILE=".portal_bridge_${BRIDGE_PORT}.pid"
+if [ -f "$BRIDGE_PID_FILE" ]; then
+    PID=$(cat "$BRIDGE_PID_FILE")
+    echo "[1/2] 🧪 Stopping Portal Bridge [$BRIDGE_PORT] (PID: $PID)..."
+    kill $PID 2>/dev/null && rm "$BRIDGE_PID_FILE"
+    echo "      ✅ Bridge stopped."
+else
+    echo "[1/2] 🧪 Portal Bridge on port $BRIDGE_PORT not running."
+fi
+
+# 2. Tắt Docker Backend (Bot)
+echo "[2/2] 🤖 Stopping Receptionist (Docker)..."
+docker compose -f docker-compose.dev.yml stop ck-backend-dev
+echo "      ✅ Bot stopped."
+
+echo "════════════════════════════════════════════════════"
+echo "✅ SYSTEM IDLE."
+echo "════════════════════════════════════════════════════"

package/template/.agent/scripts/receptionist_up.sh

@@ -0,0 +1,53 @@
+#!/bin/bash
+
+# --- Antigravity Unified Receptionist (Agent-Defined V4) ---
+# Trạm gác hợp nhất: Bot + Portal Bridge (HUD) + Monitor Dashboard.
+# Hỗ trợ Đa dự án & Tự động xử lý Cổng (Smart Port Orchestration).
+
+# 1. Load Cấu hình & Xử lý Cổng Thông minh
+PROJECT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$PROJECT_DIR"
+
+if [ -f .agent/scripts/port_utils.sh ]; then
+    source .agent/scripts/port_utils.sh
+else
+    source .env
+    export IDE_PORT=${IDE_PORT:-9555}
+    export BRIDGE_PORT=${BRIDGE_PORT:-9556}
+fi
+
+echo "════════════════════════════════════════════════════"
+echo "  🚑 AGENTIC GATEWAY - PORTAL [$BRIDGE_PORT]"
+echo "════════════════════════════════════════════════════"
+
+# 1. Kiểm tra Cổng IDE (CDP)
+echo -n "[1/4] 🛰️  Checking IDE Portal (Port $IDE_PORT)... "
+if curl -s http://127.0.0.1:$IDE_PORT/json/version > /dev/null; then
+    echo "✅ READY."
+else
+    echo "❌ NOT FOUND."
+    echo "      👉 Please start Antigravity in Debug mode on port $IDE_PORT"
+fi
+
+# 2. Khởi động Portal Bridge (HUD Injector)
+echo "[2/4] 🧪 Injected Golden HUD Bridge... "
+BRIDGE_PID_FILE=".portal_bridge_${BRIDGE_PORT}.pid"
+
+# Tắt bridge cũ nếu đang chạy trên port này
+if [ -f "$BRIDGE_PID_FILE" ]; then
+    kill $(cat "$BRIDGE_PID_FILE") 2>/dev/null
+fi
+
+nohup node scripts/ag_portal_bridge.js > ".portal_bridge_${BRIDGE_PORT}.log" 2>&1 &
+echo $! > "$BRIDGE_PID_FILE"
+echo "      ✅ Bridge running (PID: $(cat "$BRIDGE_PID_FILE") on Port $BRIDGE_PORT)"
+
+# 3. Khởi động Bot (Tùy chỉnh theo dự án)
+echo "[3/4] 🤖 Waking up Agent Bot... "
+# [TEMPLATE_NOTE]: Sếp hãy gõ lệnh khởi động Bot của mình vào đây.
+# Ví dụ: docker compose up -d (nếu dùng docker) hoặc npx tsx src/index.ts (nếu dùng local)
+echo "      ⚠️  Vui lòng cấu hình lệnh khởi động Bot trong .agent/scripts/receptionist_up.sh"
+
+# 4. Monitor
+echo "[4/4] 📊 Ready."
+echo "----------------------------------------------------"

package/template/.agent/skills/knowledge-management/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: knowledge-management
-description: Hệ thống tư duy và giao thức duy trì tri thức (Systems Thinking & Knowledge Retention). MANDATORY cho việc duy trì tính nhất quán của kiến trúc, ghi chép tri thức tích hợp (API characteristics) và đảm bảo cập nhật mã nguồn hoàn chỉnh, đồng bộ. **QUY TẮC TỐI THƯỢNG: Khi cập nhật ag-kit, phải đồng bộ sang thư mục `template/`.**
+description: Hệ thống tư duy và giao thức duy trì tri thức (Systems Thinking & Knowledge Retention). **QUY TẮC CỐI THƯỢNG: Khi cập nhật ag-kit, phải đồng bộ sang thư mục `template/`. Khi cập nhật Skills, BẮT BUỘC phải đảm bảo tính toàn vẹn cấu trúc (Indexing A, B, C... không được nhảy cóc).**
 allowed-tools: Read, Write, Glob, Grep
 ---
 

package/template/.agent/skills/telegram-agentic-gateway/SKILL.md

@@ -1,50 +1,67 @@
 ---
 name: telegram-agentic-gateway
-description: Tiêu chuẩn Giao tiếp Telegram (Telegram Gateway) cho các Agentic Projects. Cung cấp bộ lệnh chuẩn mực (Core Commands) để Quản lý Agent, Quản lý Ký ức và Cấp phép Tự Chữa Lành (Self-Healing).
+description: Tiêu chuẩn Giao tiếp Telegram (Telegram Gateway) cho các Agentic Projects. Cổng điều phối hợp nhất IDE, Bot và Ký ức.
 ---
 
 # KỸ NĂNG: XÂY DỰNG TRẠM ĐIỀU HÀNH TELEGRAM (Telegram Agentic Gateway)
 
-Khi User yêu cầu "Tạo kênh giao tiếp Telegram" hoặc "Làm cho dự án này điều khiển được qua Telegram", bạn (AI) phải thiết kế một `TelegramGateway` chuyên nghiệp, tích hợp tinh hoa từ các dự án **Remoat**, **LazyGravity** và framework **grammY**.
-
-## PHẦN A: BỘ LỆNH QUẢN TRỊ SINH TỒN (Core Management)
-Mọi Gateway phải có các lệnh điều khiển hệ thống sau:
-1. **`/start`**: Kiểm tra kết nối, trả về thông số Port (CDP) và trạng thái Bot.
-2. **`/status`**: Liệt kê các Agent/Sandbox đang chạy. Sử dụng Inline Keyboard để tương tác.
-3. **`/stop`**: Dừng khẩn cấp quá trình AI đang sinh code hoặc thực thi (Sử dụng `Page.stopLoading` qua CDP).
-4. **`/screenshot`**: Chụp ảnh màn hình IDE (qua CDP `Page.captureScreenshot`) để giám sát trực quan từ xa.
-
-## PHẦN B: TRÍ NHỚ PHÂN NHIỆM (Topic-Based Isolation)
-Bắt buộc phải cô lập trí nhớ dựa trên **Telegram Topics** (Threads) để chống hiện tượng chập cheng ký ức:
-- Sử dụng `msg.message_thread_id` làm định danh cho file context (Vd: `topic-123.json`).
-- Mỗi Topic trong Group Telegram tương ứng với một luồng công việc/tính năng riêng biệt.
-
-## PHẦN C: QUẢN LÝ MÔ HÌNH & TIẾT KIỆM TOKEN (Model Routing)
-Tích hợp chiến lược chuyển đổi model linh hoạt:
-- **`/model`**: Hiển thị menu chọn Model (Cloud vs Local).
-- **Ưu tiên Local**: Sử dụng **Ollama** cho các tác vụ giải thích hoặc refactor nhỏ để bảo vệ quota Cloud.
-- **VFS Integration**: Luôn tuân thủ giao thức **VFS (Virtual File System)** để tiết kiệm 98% token khi đọc code (Cấu hình tại `GEMINI.md`).
-
-## PHẦN D: PHẪU THUẬT NÃO AI (Self-Healing & Multi-Agent)
-Để dự án tự vá lỗi (kết hợp `mini-antigravity-injection`):
-1. **`/heal`**: Cấp quyền tự mổ (Mutation License).
-2. **`/healplan`**: Yêu cầu Agent lập phác đồ chữa bệnh và chờ lệnh `Proceed` từ User.
-
-## PHẦN E: GIAO DIỆN PREMIUM (grammY Aesthetics)
-Lấy cảm hứng từ `awesome-grammY`:
-- Sử dụng `<b>`, `━━━━━`, và Emoji chuyên nghiệp.
-- **Short Callback Data**: Map ID dài vào `shortIdMap` để bypass giới hạn 64 bytes của Telegram.
-
-## PHẦN F: KIẾN TẠO HẠ TẦNG (Deployment Guide)
-Hướng dẫn User thiết lập:
-1. **Group with Topics**: Tạo Group, thêm Bot làm Admin, bật tính năng Topics.
-2. **Environment**: Cấu hình `.env` khớp với `start.sh` và `stop_bot.sh`.
-   - `IDE_PORT`: Mặc định 9555 (Remote Debugging port).
-   - `ALLOWED_USER_IDS`: Danh sách trắng ID người dùng.
-
----
-**Nguồn tham khảo & Ảnh hưởng:**
-- [Remoat](https://github.com/optimistengineer/remoat) - Remote Command & Control.
-- [LazyGravity](https://github.com/tokyoweb3/LazyGravity) - Multi-project & Session management.
-- [grammY](https://grammy.dev/) - Modern Bot Framework.
-- [VFS](https://github.com/TrNgTien/vfs) - Virtual File System for Token Efficiency.
+Khi triển khai "Cổng điều khiển Telegram", bạn (AI) phải thiết kế một `TelegramGateway` chuyên nghiệp, tuân thủ nghiêm ngặt cấu trúc **7 Phôi (7 Layers)** dưới đây. Tuyệt đối không được bỏ sót hoặc làm xáo trộn thứ tự các mục khi cập nhật.
+
+---
+
+## PHẦN A: BỘ LỆNH QUẢN TRỊ SINH TỒN (Core Commands)
+Mọi Gateway phải hỗ trợ các lệnh điều khiển hệ thống sau:
+1. **`/start`**: Kiểm tra kết nối. Trả về thông số `IDE_PORT` (CDP), trạng thái Node/Ollama và phiên bản Agent.
+2. **`/status` (Dashboard)**: Hiển thị bảng điều khiển Premium về sức khỏe AI, các Agent đang chạy ngầm và Task hiện tại.
+3. **`/model`**: Menu chọn Model linh hoạt. Cho phép chuyển đổi giữa **Local Ollama** (tiết kiệm token) và **Cloud models** (tác vụ phức tạp).
+4. **`/screenshot` (Visual Support)**: Chụp màn hình IDE qua CDP (`Page.captureScreenshot`).
+5. **`/heal` / `/healplan`**: Luồng tự chữa lành (Self-Healing) tích hợp phê duyệt người dùng.
+
+---
+
+## PHẦN B: TRÍ NHỚ PHÂN NHIỆM (Context Isolation)
+Kế thừa từ tiêu chuẩn **LazyGravity**, bắt buộc cô lập trí nhớ dựa trên **Telegram Topics** (Threads):
+- Trích xuất `msg.message_thread_id` để định danh file context (Vd: `topic_123.json`).
+- Mỗi Topic là một bộ não làm việc riêng biệt, ngăn chặn hiện tượng chập cheng ký ức giữa các tác vụ khác nhau.
+
+---
+
+## PHẦN C: GIAO DIỆN PREMIUM (UI/UX Standards)
+Tuân thủ tiêu chuẩn thẩm mỹ của [awesome-grammY](https://github.com/grammyjs/awesome-grammY):
+- **Cấu trúc khối**: Sử dụng `<b>` cho Header, ký tự `━━━━━` làm phân cách.
+- **Emoji Logic**: ✅ Active, 🚨 Warning, 🛠️ Debugging, 🏥 Surgery.
+- **ShortID Mapping**: Vì Telegram giới hạn callback data (64 bytes), hãy map ID dài vào biến tạm và nhả ra mã ngắn (Vd: `sess_1`).
+
+---
+
+## PHẦN D: CHIẾN LƯỢC TIẾT KIỆM TOKEN (Model & VFS Strategy)
+Tối ưu chi phí vận hành thông qua Token Efficiency:
+1. **VFS First (Virtual File System)**: Tuyệt đối không đọc file thô hàng ngàn dòng. PHẢI dùng kỹ năng `vfs-assistant` để quét chữ ký (signatures) trước. (Nguồn: [vfs](https://github.com/TrNgTien/vfs)).
+2. **Regent Agent (Chế độ Nhiếp chính)**: Sử dụng các model Local (Ollama) cho các bước phân tích bối cảnh, refactor nhỏ. Chỉ dùng Cloud cho bước Implementation cuối cùng.
+
+---
+
+## PHẦN E: CỔNG PORTAL IDE & CDP (Golden Loop Participant)
+Biến IDE thành một thực thể tham gia trực tiếp dự án (Participant):
+1. **Remoat Strategy**: IDE Antigravity **BẮT BUỘC** khởi động với `--remote-debugging-port=9555`.
+2. **HUD Injection**: Tiêm `ag_hud.js` vào IDE qua CDP để hiển thị chỉ số sức khỏe AI (Gen, WinRate) trực quan trong không gian code.
+3. **Bidirectional Sync**: Đồng bộ trạng thái từ Bot -> IDE (HUD) và ngược lại một cách liên tục.
+
+---
+
+## PHẦN F: THIẾT LẬP HẠ TẦNG (Deployment & Scripts)
+1. **Group Creation**: Tạo Telegram Group, thêm Bot làm Admin, bật tính năng Multi-Topics.
+2. **Environment (.env)**: Phải cấu hình thống nhất `IDE_PORT`, `TELEGRAM_BOT_TOKEN`, `ALLOWED_USER_IDS` và `OLLAMA_HOST`.
+3. **Standard Scripts**: Sử dụng bộ đôi `start.sh` (khởi chạy bot + gateway) và `stop_bot.sh` (tắt an toàn).
+
+---
+
+## PHẦN G: NGUỒN GỐC TRI THỨC (Knowledge Roots)
+Mọi kỹ năng đều có nguồn gốc rõ ràng, không được làm mất gốc kiến thức:
+- **[Remoat](https://github.com/optimistengineer/Remoat)**: Remote Management & CDP Control.
+- **[LazyGravity](https://github.com/tokyoweb3/LazyGravity)**: Project Coordination & Session Isolation.
+- **[vfs](https://github.com/TrNgTien/vfs)**: Token Efficiency standard.
+- **[grammY Aesthetics](https://github.com/grammyjs/awesome-grammY)**: UI/UX standards.
+
+---
+*(Ghi chú cho AI)*: Khi cập nhật Template, BẮT BUỘC phải kiểm tra toàn vẹn cấu trúc (A -> G), không được tạo các mục nhảy cóc.

package/template/.env.example

@@ -12,11 +12,15 @@ ALLOWED_USER_IDS="123456789,987654321"
 # ID Chat/Group được phép hoạt động (Để tránh Bot bị kéo vào group lạ)
 ALLOWED_CHAT_IDS="-100123456789"
 
-# [Cấu Hình IDE]
+# [Cấu Hình IDE & Remote]
 # Cổng Debug của Antigravity (Mặc định là 9555)
 # Phải khớp với tham số --remote-debugging-port khi mở Editor
 IDE_PORT=9555
 
+# Cổng của Portal Bridge (Mặc định là 9556)
+# Phải khớp với script start.sh và bot callback
+BRIDGE_PORT=9556
+
 # Tên dự án để Bot tự động tìm kiếm target phù hợp trong CDP
 PROJECT_NAME="ceogravity"
 

package/template/scripts/ag_hud.js

@@ -0,0 +1,162 @@
+/**
+ * Antigravity Golden HUD - Medical/Trading Theme
+ * Purpose: Inject a premium status dashboard into the IDE.
+ */
+export const AG_HUD_JS = `(async () => {
+    const HUD_ID = 'antigravity-golden-hud';
+    if (document.getElementById(HUD_ID)) return "ALREADY_EXISTS";
+
+    // 1. Create Styles
+    const style = document.createElement('style');
+    style.innerHTML = \`
+        #\${HUD_ID} {
+            position: fixed;
+            top: 15px;
+            right: 15px;
+            z-index: 999999;
+            background: rgba(10, 10, 10, 0.85);
+            backdrop-filter: blur(12px);
+            border: 1px solid rgba(255, 255, 255, 0.1);
+            border-radius: 12px;
+            padding: 12px;
+            width: 280px;
+            color: #fff;
+            font-family: 'Inter', system-ui, sans-serif;
+            box-shadow: 0 8px 32px rgba(0,0,0,0.5);
+            transition: all 0.3s ease;
+            user-select: none;
+        }
+        #\${HUD_ID}:hover {
+            border-color: #4caf50;
+            box-shadow: 0 0 20px rgba(76, 175, 80, 0.2);
+        }
+        #\${HUD_ID} .header {
+            display: flex;
+            align-items: center;
+            justify-content: space-between;
+            margin-bottom: 10px;
+            font-weight: 700;
+            letter-spacing: 0.5px;
+        }
+        #\${HUD_ID} .status-dot {
+            width: 8px;
+            height: 8px;
+            border-radius: 50%;
+            background: #4caf50;
+            display: inline-block;
+            margin-right: 6px;
+            animation: pulse 2s infinite;
+        }
+        @keyframes pulse {
+            0% { transform: scale(1); opacity: 1; }
+            50% { transform: scale(1.5); opacity: 0.5; }
+            100% { transform: scale(1); opacity: 1; }
+        }
+        #\${HUD_ID} .metric {
+            display: flex;
+            justify-content: space-between;
+            font-size: 12px;
+            margin-bottom: 6px;
+            color: #ccc;
+        }
+        #\${HUD_ID} .metric b { color: #fff; }
+        #\${HUD_ID} .action-btn {
+            background: #1a1a1a;
+            border: 1px solid #333;
+            color: #4caf50;
+            font-size: 11px;
+            padding: 6px;
+            border-radius: 6px;
+            width: 100%;
+            margin-top: 8px;
+            cursor: pointer;
+            text-align: center;
+            font-weight: 600;
+            transition: all 0.2s;
+        }
+        #\${HUD_ID} .action-btn:hover {
+            background: #4caf50;
+            color: #000;
+        }
+        #\${HUD_ID} .surgery-alert {
+            background: rgba(244, 67, 54, 0.2);
+            border: 1px solid #f44336;
+            color: #f44336;
+            padding: 8px;
+            border-radius: 8px;
+            font-size: 11px;
+            margin-top: 10px;
+            display: none;
+            animation: shake 0.5s infinite;
+        }
+        @keyframes shake {
+            0% { transform: translateX(0); }
+            25% { transform: translateX(2px); }
+            50% { transform: translateX(0); }
+            75% { transform: translateX(-2px); }
+            100% { transform: translateX(0); }
+        }
+    \`;
+    document.head.appendChild(style);
+
+    // 2. Create UI
+    const hud = document.createElement('div');
+    hud.id = HUD_ID;
+    hud.innerHTML = \`
+        <div class="header">
+            <span>🧠 CORE AGENT B1</span>
+            <span id="ag-status"><span class="status-dot"></span>ONLINE</span>
+        </div>
+        <div class="metric">AI Evolution: <b id="ag-gen">GEN-439</b></div>
+        <div class="metric">Win Rate: <b id="ag-win">47.7%</b></div>
+        <div class="metric">Current Phase: <b id="ag-phase">5m VSA Trading</b></div>
+        
+        <div class="surgery-alert" id="ag-alert">
+            🛑 <b>DOCTOR CALL REQUIRED!</b><br>AI Learning Stalled. Surgery needed.
+        </div>
+        
+        <div id="ag-toast" style="display:none; background:rgba(33, 150, 243, 0.9); color:#fff; padding:8px; border-radius:8px; margin-top:10px; font-size:11px; border-left:4px solid #0d47a1; backdrop-filter: blur(8px); box-shadow: 0 4px 12px rgba(0,0,0,0.3);">
+            <b>💬 TELEGRAM:</b> <span id="ag-toast-msg"></span>
+        </div>
+        
+        <div class="action-btn" id="ag-btn-surgery">🏥 START BRAIN SURGERY</div>
+    \`;
+    document.body.appendChild(hud);
+
+    // 3. Logic to update from Bridge
+    window.addEventListener('ag-portal-update', (e) => {
+        const data = e.detail;
+        if (data.gen) document.getElementById('ag-gen').innerText = data.gen;
+        if (data.win) document.getElementById('ag-win').innerText = data.win;
+        if (data.phase) document.getElementById('ag-phase').innerText = data.phase;
+        
+        const alert = document.getElementById('ag-alert');
+        if (data.status === 'DOCTOR_REQUIRED' || data.status === 'STALLED') {
+            alert.style.display = 'block';
+            document.getElementById('ag-status').innerHTML = '<span class="status-dot" style="background:#f44336"></span>REPAIR';
+        } else {
+            alert.style.display = 'none';
+            document.getElementById('ag-status').innerHTML = '<span class="status-dot" style="background:#4caf50"></span>ONLINE';
+        }
+    });
+
+    window.addEventListener('ag-portal-alert', (e) => {
+        const data = e.detail;
+        const toast = document.getElementById('ag-toast');
+        const toastMsg = document.getElementById('ag-toast-msg');
+        
+        toastMsg.innerText = data.message || "New message from Telegram.";
+        toast.style.display = 'block';
+        if (data.color) toast.style.background = data.color;
+        
+        // Auto-hide after 10 seconds
+        setTimeout(() => { toast.style.display = 'none'; }, 10000);
+    });
+
+    document.getElementById('ag-btn-surgery').onclick = () => {
+        console.log("AG_PORTAL_ACTION:START_SURGERY");
+        document.getElementById('ag-btn-surgery').innerText = "🚑 REQUESTING SURGEON...";
+    };
+
+    return "GOLDEN_HUD_INJECTED";
+})()`;

package/template/scripts/ag_portal_bridge.js

@@ -0,0 +1,141 @@
+import WebSocket from 'ws';
+import fs from 'fs';
+import path from 'path';
+import fetch from 'node-fetch';
+import http from 'http';
+import { fileURLToPath } from 'url';
+import dotenv from 'dotenv';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+dotenv.config({ path: path.join(__dirname, '../.env') });
+
+const HUD_JS_FILE = path.join(__dirname, 'ag_hud.js');
+const STATE_FILE = path.join(__dirname, '../backend/data/ai_state.json');
+const REQUEST_FILE = path.join(__dirname, '../backend/data/remote_requests.json');
+const IDE_PORT = process.env.IDE_PORT || 9555;
+const BRIDGE_PORT = process.env.BRIDGE_PORT || 9556;
+
+let globalWs = null;
+
+async function getWsUrl() {
+    try {
+        const resp = await fetch(`http://127.0.0.1:${IDE_PORT}/json/version`);
+        const data = await resp.json();
+        return data.webSocketDebuggerUrl;
+    } catch (err) {
+        return null;
+    }
+}
+
+async function injectHud(ws) {
+    const hudJsContent = fs.readFileSync(HUD_JS_FILE, 'utf8');
+    const script = hudJsContent.match(/export const AG_HUD_JS = `([\s\S]*)`;/)[1];
+
+    const message = {
+        id: 1,
+        method: "Runtime.evaluate",
+        params: {
+            expression: script,
+            awaitPromise: true,
+            userGesture: true
+        }
+    };
+    ws.send(JSON.stringify(message));
+}
+
+async function updateHud(ws, state) {
+    const updateEvent = {
+        id: Date.now(),
+        method: "Runtime.evaluate",
+        params: {
+            expression: `window.dispatchEvent(new CustomEvent('ag-portal-update', { detail: ${JSON.stringify(state)} }));`
+        }
+    };
+    ws.send(JSON.stringify(updateEvent));
+}
+
+async function pushInstantAlert(ws, alertData) {
+    const alertEvent = {
+        id: Date.now(),
+        method: "Runtime.evaluate",
+        params: {
+            expression: `window.dispatchEvent(new CustomEvent('ag-portal-alert', { detail: ${JSON.stringify(alertData)} }));`
+        }
+    };
+    ws.send(JSON.stringify(alertEvent));
+}
+
+function startHttpServer() {
+    const server = http.createServer((req, res) => {
+        if (req.method === 'POST' && (req.url === '/alert' || req.url === '/update')) {
+            let body = '';
+            req.on('data', chunk => { body += chunk; });
+            req.on('end', async () => {
+                try {
+                    const data = JSON.parse(body);
+                    if (globalWs && globalWs.readyState === WebSocket.OPEN) {
+                        if (req.url === '/alert') {
+                            await pushInstantAlert(globalWs, data);
+                        } else {
+                            await updateHud(globalWs, data);
+                        }
+                        res.writeHead(200, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ status: 'ok' }));
+                    } else {
+                        res.writeHead(503, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({ error: 'Bridge not connected to IDE' }));
+                    }
+                } catch (e) {
+                    res.writeHead(400, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: 'Invalid JSON' }));
+                }
+            });
+        } else {
+            res.writeHead(404);
+            res.end();
+        }
+    });
+
+    server.listen(BRIDGE_PORT, '0.0.0.0', () => {
+        console.log(`📡  Instant Alert Server listening on port ${BRIDGE_PORT}`);
+    });
+}
+
+async function startBridge() {
+    console.log(`🛰️  Connecting to Antigravity Portal on port ${IDE_PORT}...`);
+    
+    const wsUrl = await getWsUrl();
+    if (!wsUrl) {
+        console.log("❌ IDE is not running or port 9555 is closed.");
+        process.exit(1);
+    }
+
+    const ws = new WebSocket(wsUrl);
+    globalWs = ws;
+
+    ws.on('open', async () => {
+        console.log("✅ Bridge Established. Injecting Golden HUD...");
+        await injectHud(ws);
+        
+        // Start HTTP server for instant pushes
+        startHttpServer();
+        
+        // Background polling for legacy state compatibility
+        setInterval(async () => {
+            if (fs.existsSync(STATE_FILE)) {
+                const state = JSON.parse(fs.readFileSync(STATE_FILE, 'utf8'));
+                await updateHud(ws, state);
+            }
+        }, 5000);
+    });
+
+    ws.on('message', (data) => {
+        const msg = JSON.parse(data);
+    });
+
+    ws.on('error', (err) => {
+        console.error("❌ WS Error:", err);
+    });
+}
+
+startBridge();

package/template/start.sh

@@ -1,25 +1,22 @@
 #!/bin/bash
+# start.sh - Khởi động Cổng Agentic (Remoat + LazyGravity standard)
 
-# 🧠 ANTIGRAVITY STARTUP SCRIPT (Standard v1.1.5)
-# --------------------------------------------------
-# Script này khởi động Antigravity Bot với cấu hình từ .env
-
-# 1. Load configuration
-if [ -f .env ]; then
-  export $(grep -v '^#' .env | xargs)
-else
-  echo "❌ Lỗi: Không tìm thấy file .env. Vui lòng tạo từ .env.example"
-  exit 1
+# 1. Kiểm tra .env
+if [ ! -f .env ]; then
+    echo "❌ Lỗi: Không tìm thấy file .env. Vui lòng tạo dựa trên .env.example"
+    exit 1
 fi
 
-# 2. Defaults
-IDE_PORT=${IDE_PORT:-9555}
-PROJECT_NAME=${PROJECT_NAME:-"ceogravity"}
+# 2. Đọc cấu hình
+source .env
 
-echo "🚀 Đang khởi động Antigravity Gateway..."
-echo "📂 Dự án: $PROJECT_NAME"
-echo "🔌 Cổng Debug: $IDE_PORT"
+# 3. Khởi động IDE ở chế độ Debug (nếu chưa chạy)
+# Lưu ý: User nên chạy ./launch_remote_ide.sh trước hoặc script này sẽ kiểm tra port
+nc -z localhost ${IDE_PORT:-9555}
+if [ $? -ne 0 ]; then
+    echo "⚠️ Cảnh báo: Cổng CDP ${IDE_PORT:-9555} chưa mở. Đang chờ Antigravity khởi động..."
+fi
 
-# 3. Start Bot (Sử dụng tsx để chạy TypeScript trực tiếp)
-# Ghi chú: Đảm bảo Antigravity IDE đã được mở với --remote-debugging-port=$IDE_PORT
-npx tsx src/index.ts
+# 4. Khởi động Bridge và Bot (Agent-Defined)
+echo "🚀 Khởi động Lễ tân trực chiến (Agentic Gateway)..."
+bash .agent/scripts/receptionist_up.sh

package/template/stop_bot.sh

@@ -1,17 +1,9 @@
 #!/bin/bash
+# stop_bot.sh - Hạ cánh an toàn (Remoat + LazyGravity standard)
 
-# 🛑 ANTIGRAVITY STOP SCRIPT (Standard v1.1.5)
-# --------------------------------------------------
+echo "🛑 Đang tắt toàn bộ trạm điều hành Agentic..."
 
-# Tìm và giết các tiến trình liên quan đến bot
-echo "🛑 Đang dừng Antigravity Gateway..."
+# Gọi script hạ cánh tiêu chuẩn (Agent-Defined)
+bash .agent/scripts/receptionist_down.sh
 
-# Tìm PID của tsx src/index.ts
-PIDS=$(pgrep -f "tsx src/index.ts")
-
-if [ -z "$PIDS" ]; then
-  echo "⚠️ Không tìm thấy tiến trình Bot đang chạy."
-else
-  kill $PIDS
-  echo "✅ Đã dừng Bot (PIDs: $PIDS)"
-fi
+echo "✅ Đã dọn dẹp xong."