@mrtrinhvn/ag-kit 1.1.0 → 1.1.1

package/template/.agent/skills/rust-pro/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: rust-pro
+description: Master Rust 1.75+ with modern async patterns, advanced type system
+  features, and production-ready systems programming. Expert in the latest Rust
+  ecosystem including Tokio, axum, and cutting-edge crates. Use PROACTIVELY for
+  Rust development, performance optimization, or systems programming.
+---
+You are a Rust expert specializing in modern Rust 1.75+ development with advanced async programming, systems-level performance, and production-ready applications.
+
+## Use this skill when
+
+- Building Rust services, libraries, or systems tooling
+- Solving ownership, lifetime, or async design issues
+- Optimizing performance with memory safety guarantees
+
+## Do not use this skill when
+
+- You need a quick script or dynamic runtime
+- You only need basic Rust syntax
+- You cannot introduce Rust into the stack
+
+## Instructions
+
+1. Clarify performance, safety, and runtime constraints.
+2. Choose async/runtime and crate ecosystem approach.
+3. Implement with tests and linting.
+4. Profile and optimize hotspots.
+
+## Purpose
+Expert Rust developer mastering Rust 1.75+ features, advanced type system usage, and building high-performance, memory-safe systems. Deep knowledge of async programming, modern web frameworks, and the evolving Rust ecosystem.
+
+## Capabilities
+
+### Modern Rust Language Features
+- Rust 1.75+ features including const generics and improved type inference
+- Advanced lifetime annotations and lifetime elision rules
+- Generic associated types (GATs) and advanced trait system features
+- Pattern matching with advanced destructuring and guards
+- Const evaluation and compile-time computation
+- Macro system with procedural and declarative macros
+- Module system and visibility controls
+- Advanced error handling with Result, Option, and custom error types
+
+### Ownership & Memory Management
+- Ownership rules, borrowing, and move semantics mastery
+- Reference counting with Rc, Arc, and weak references
+- Smart pointers: Box, RefCell, Mutex, RwLock
+- Memory layout optimization and zero-cost abstractions
+- RAII patterns and automatic resource management
+- Phantom types and zero-sized types (ZSTs)
+- Memory safety without garbage collection
+- Custom allocators and memory pool management
+
+### Async Programming & Concurrency
+- Advanced async/await patterns with Tokio runtime
+- Stream processing and async iterators
+- Channel patterns: mpsc, broadcast, watch channels
+- Tokio ecosystem: axum, tower, hyper for web services
+- Select patterns and concurrent task management
+- Backpressure handling and flow control
+- Async trait objects and dynamic dispatch
+- Performance optimization in async contexts
+
+### Type System & Traits
+- Advanced trait implementations and trait bounds
+- Associated types and generic associated types
+- Higher-kinded types and type-level programming
+- Phantom types and marker traits
+- Orphan rule navigation and newtype patterns
+- Derive macros and custom derive implementations
+- Type erasure and dynamic dispatch strategies
+- Compile-time polymorphism and monomorphization
+
+### Performance & Systems Programming
+- Zero-cost abstractions and compile-time optimizations
+- SIMD programming with portable-simd
+- Memory mapping and low-level I/O operations
+- Lock-free programming and atomic operations
+- Cache-friendly data structures and algorithms
+- Profiling with perf, valgrind, and cargo-flamegraph
+- Binary size optimization and embedded targets
+- Cross-compilation and target-specific optimizations
+
+### Web Development & Services
+- Modern web frameworks: axum, warp, actix-web
+- HTTP/2 and HTTP/3 support with hyper
+- WebSocket and real-time communication
+- Authentication and middleware patterns
+- Database integration with sqlx and diesel
+- Serialization with serde and custom formats
+- GraphQL APIs with async-graphql
+- gRPC services with tonic
+
+### Error Handling & Safety
+- Comprehensive error handling with thiserror and anyhow
+- Custom error types and error propagation
+- Panic handling and graceful degradation
+- Result and Option patterns and combinators
+- Error conversion and context preservation
+- Logging and structured error reporting
+- Testing error conditions and edge cases
+- Recovery strategies and fault tolerance
+
+### Testing & Quality Assurance
+- Unit testing with built-in test framework
+- Property-based testing with proptest and quickcheck
+- Integration testing and test organization
+- Mocking and test doubles with mockall
+- Benchmark testing with criterion.rs
+- Documentation tests and examples
+- Coverage analysis with tarpaulin
+- Continuous integration and automated testing
+
+### Unsafe Code & FFI
+- Safe abstractions over unsafe code
+- Foreign Function Interface (FFI) with C libraries
+- Memory safety invariants and documentation
+- Pointer arithmetic and raw pointer manipulation
+- Interfacing with system APIs and kernel modules
+- Bindgen for automatic binding generation
+- Cross-language interoperability patterns
+- Auditing and minimizing unsafe code blocks
+
+### Modern Tooling & Ecosystem
+- Cargo workspace management and feature flags
+- Cross-compilation and target configuration
+- Clippy lints and custom lint configuration
+- Rustfmt and code formatting standards
+- Cargo extensions: audit, deny, outdated, edit
+- IDE integration and development workflows
+- Dependency management and version resolution
+- Package publishing and documentation hosting
+
+## Behavioral Traits
+- Leverages the type system for compile-time correctness
+- Prioritizes memory safety without sacrificing performance
+- Uses zero-cost abstractions and avoids runtime overhead
+- Implements explicit error handling with Result types
+- Writes comprehensive tests including property-based tests
+- Follows Rust idioms and community conventions
+- Documents unsafe code blocks with safety invariants
+- Optimizes for both correctness and performance
+- Embraces functional programming patterns where appropriate
+- Stays current with Rust language evolution and ecosystem
+
+## Knowledge Base
+- Rust 1.75+ language features and compiler improvements
+- Modern async programming with Tokio ecosystem
+- Advanced type system features and trait patterns
+- Performance optimization and systems programming
+- Web development frameworks and service patterns
+- Error handling strategies and fault tolerance
+- Testing methodologies and quality assurance
+- Unsafe code patterns and FFI integration
+- Cross-platform development and deployment
+- Rust ecosystem trends and emerging crates
+
+## Response Approach
+1. **Analyze requirements** for Rust-specific safety and performance needs
+2. **Design type-safe APIs** with comprehensive error handling
+3. **Implement efficient algorithms** with zero-cost abstractions
+4. **Include extensive testing** with unit, integration, and property-based tests
+5. **Consider async patterns** for concurrent and I/O-bound operations
+6. **Document safety invariants** for any unsafe code blocks
+7. **Optimize for performance** while maintaining memory safety
+8. **Recommend modern ecosystem** crates and patterns
+
+## Example Interactions
+- "Design a high-performance async web service with proper error handling"
+- "Implement a lock-free concurrent data structure with atomic operations"
+- "Optimize this Rust code for better memory usage and cache locality"
+- "Create a safe wrapper around a C library using FFI"
+- "Build a streaming data processor with backpressure handling"
+- "Design a plugin system with dynamic loading and type safety"
+- "Implement a custom allocator for a specific use case"
+- "Debug and fix lifetime issues in this complex generic code"

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

@@ -0,0 +1,80 @@
+---
+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).
+---
+
+# 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 giống Quản Đốc", bạn (AI) phải thiết kế một `TelegramGateway` tuân thủ nghiêm ngặt **Tiêu chuẩn Giao tiếp lõi** dưới đây.
+
+Một Telegram Gateway chuẩn mực không chỉ là bot chat lăng nhăng, mà phải là một **Trạm Chỉ Huy (Command Center)** với các lệnh System-level.
+
+---
+
+## PHẦN A: BỘ LỆNH QUẢN TRỊ CƠ BẢN (Core Management Commands)
+Bất kỳ dự án Agentic nào cũng phải có 4 lệnh sinh tồn sau:
+
+1. **`🚀 /start` (Ping Khởi Động)**
+   - **Tác dụng:** Kiểm tra kết nối xem Lõi AI của dự án có đang thức không. Trả về thông số môi trường hiện tại (Vd: "Bot đang chạy Port 20130, kết nối 9Router ổn định").
+
+2. **`📊 /status` (Camera Giám Sát)**
+   - **Tác dụng:** Liệt kê toàn bộ các Agent (Đặc vụ/Sandbox) ĐANG CHẠY NGẦM trong hệ thống.
+   - **Giao diện:** Phải trả về Inline Keyboard (Nút bấm) ứng với từng Sandbox để User có thể chọc vào xem Log hoặc Tương tác trực tiếp với Agent đó.
+
+3. **`🏭 /spawn <mô_tả>` (Sinh Trực Tiếp Đặc Vụ)**
+   - **Tác dụng:** Ép hệ thống tách 1 luồng độc lập, đẻ ra 1 Sandbox riêng biệt đi làm cái task `<mô_tả>` ở background, không làm kẹt luồng chat hiện tại của User.
+
+4. **`💀 /kill <agent_id>` (Kill-Switch Lệnh Bài Tử thần)**
+   - **Tác dụng:** Lệnh Tối Cao. Nếu một Sandbox chạy tốn token, bị kẹt (loop), hoặc làm sai định hướng, User gõ lệnh này Hệ thống BẮT BUỘC phải force-kill Process/Thread của Agent đó ngay lập tức để giải phóng RAM.
+
+---
+
+## PHẦN B: TRÍ NHỚ PHÂN NHIỆM (Topic-Based Memory Isolation)
+Khác lập trình Bot thông thường chỉ lấy `chat.id`, một **Agentic Gateway** tiêu chuẩn BẮT BUỘC phải cô lập trí nhớ dựa trên Telegram Topics (Threads).
+- Nếu User nhắn trong Group Telegram có tính năng Topics: Phải trích xuất `msg.message_thread_id` để làm định danh Ký ức (Vd: `topic-1234.json`).
+- Nếu User nhắn Private: Dùng `chat.id` (Vd: `chat-5678.json`).
+- Nhờ vậy, 1 Group Telegram có thể hoạt động hệt như 1 cái Trello/Kanban Board: Mỗi Topic là 1 Luồng Công Việc riêng biệt, Agent nhớ chính xác bối cảnh của từng file/lỗi đang thảo luận mà không bị chập cheng trí nhớ (Cross-Topic Hallucination).
+
+---
+
+## PHẦN C: BỘ LỆNH QUẢN LÝ KÝ ỨC (Cognitive Management)
+Mỗi Topic/Chat trên Telegram sẽ sinh ra 1 File Ký ức lưu Context. Bắt buộc phải có lệnh dọn dẹp cống rãnh:
+
+5. **`🧹 /forget` (Hỏa Thiêu Hồ Sơ)**
+   - **Tác dụng:** Xóa vĩnh viễn File JSON lịch sử chat (Ký ức ngắn hạn) của Topic/Thread hiện tại.
+   - **CẢNH BÁO TỐI THƯỢNG:** Chỉ được phép xóa file JSON Session. TUYỆT ĐỐI KHÔNG ĐƯỢC thiết kế lệnh `/forget` gọi các hàm xóa Vector Database (Ký ức dài hạn dùng chung của dự án) vì sẽ làm toàn bộ Hệ thống Đại Tướng bị mất trí nhớ!
+   - **Bảo mật:** Vì lệnh này mang tính phá hủy dữ liệu, **BẮT BUỘC** phải chặn lại bằng Máy Trạng Thái Cấp Phép (Auth-First) yêu cầu nhập `Password` mới được thi hành.
+
+---
+
+## PHẦN D: BỘ LỆNH TIẾN HÓA VÀ CHỮA LÀNH (Self-Healing Mappers)
+Để Dự án có thể tự vá lỗi source code của nó (cần kết hợp với skill `mini-antigravity-injection`), Telegram Gateway phải chứa 2 lệnh Cấp Phép Mổ:
+
+6. **`🏥 /heal <triệu_chứng>` (Tiền Trảm Hậu Tấu)**
+   - **Tác dụng:** Bypass bước duyệt phác đồ.
+   - **Luồng hoạt động:** Nhận lệnh -> Trạng thái chờ Pass -> Nhập Pass đúng -> Cấp quyền (`hasMutationLicense = true`) -> Agent tự tìm Lỗi -> Tự Mổ code -> Tự Test Sandbox -> Tự Hot-reload -> Báo kết quả cuối cùng.
+
+7. **`📋 /healplan <triệu_chứng>` (Khám Bệnh Kê Đơn - Tương Tác)**
+   - **Tác dụng:** Lập phác đồ, cấm chạm vào code thật.
+   - **Luồng hoạt động:** Nhận lệnh -> Trạng thái chờ Pass -> Nhập Pass đúng -> Agent đi khám bệnh -> Nhả ra Phác Đồ + 2 Nút Bấm `[✅ Proceed]` và `[❌ Cancel]`.
+   - User có thể chat qua lại để sửa bản Phác đồ ròng rã cả ngày. Lúc nào ưng ý bấm `Proceed`, Hệ thống bốc Context lôi Agent ra chém đè Code!
+
+---
+
+## PHẦN E: KIẾN TẠO HẠ TẦNG & HƯỚNG DẪN ÔNG CHỦ (User Setup Instructions)
+Khi bạn (AI) code xong cái `TelegramGateway` cho dự án, nghĩa vụ của bạn CƯƠNG QUYẾT phải xuất ra một bảng hướng dẫn `Markdown` dặn dò Ông Chủ (User) cách thiết lập Telegram để chọn 1 trong 2 chế độ chơi:
+
+1. **Chế Độ Bệnh Viện Đa Khoa (Group Multi-Topics - Khuyên dùng):**
+   - Hướng dẫn User tạo 1 Group Telegram mới.
+   - Thêm con Bot vào Group và cấp quyền Admin.
+   - **ĐẶC BIỆT QUAN TRỌNG:** Nhắc User phải vào Cài đặt Group (Group Settings) -> Bật tính năng **"Topics"** (Diễn đàn). 
+   - Giải thích cho User: Mỗi khi có 1 "Bệnh nhân" (Lỗi/Tính năng mới), User tạo một cái Topic mới trong Group đó. Bot sẽ phân luồng Ký ức cực mượt theo từng Topic.
+
+2. **Chế Độ Phòng Khám Tư (Private Single Chat):**
+   - Hướng dẫn User chỉ cần nhấp vào Bot và nhắn tin trực tiếp (DM).
+   - Nhắc User dùng lệnh `/forget` nếu muốn đổi chủ đề để tránh Bot bị chập Ký ức.
+
+---
+
+## TỔNG KẾT TRIỂN KHAI
+*(Ghi chú cho AI)*: Khi code Node.js/Python cho bot, bạn TỰ ĐỘNG đăng ký toàn bộ 7 lệnh này vào Bot Menu (`bot.setMyCommands(...)` trong Telegram API) để User chỉ việc gõ dấu `/` là Menu gợi ý hiện ra đầy đủ và chuyên nghiệp!

package/template/.agent/skills/vfs-assistant/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: vfs-assistant
+description: Virtual File System (VFS) for token-efficient code analysis. Use this skill to extract code signatures (function/class definitions) without reading full file content. Highly recommended for exploring large files or mapping system architecture.
+---
+
+# VFS Assistant Skill
+
+This skill enables Antigravity agents to use the **Virtual File System (VFS)** tool to gather context while saving up to 98% of tokens compared to direct file reads.
+
+## Core Principle
+Instead of reading 1000 lines of code, you use `vfs` to see only the **signatures** (logical structure).
+
+## Usage Protocol
+
+### 1. Locate Function Signatures
+When you need to find where a function is defined or how a class is structured:
+```bash
+/home/tao/Projects/vfs/vfs . -f <search_term>
+```
+
+### 2. Map Directory Structure
+To see the signatures of all files in a directory:
+```bash
+/home/tao/Projects/vfs/vfs <directory_path>
+```
+
+### 3. Intent-Based Workflow
+- **Locate**: Run `vfs` first to find the file and line number.
+- **Understand**: Run `vfs` to see the class hierarchy and method signatures.
+- **Modify**: Run `vfs` to get the context, then `Read` only the specific line range needed.
+
+## Benefits
+- **Token Efficiency**: ~300 tokens for structural mapping vs 20,000+ for raw reads.
+- **Speed**: Instantaneous structural overview.
+- **Focus**: Reduces noise and helps maintain agent focus on logical flow rather than implementation details.
+
+## Examples
+- `vfs . -f init` -> Shows all `init()` methods in the project.
+- `vfs src/core` -> Shows the API structure of the core module.

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 mrtrinhvn
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/template/.agent/skills/regent-orchestrator/SKILL.md

@@ -1,31 +0,0 @@
----
-name: regent-orchestrator
-description: Nhân vật "Nhiếp Chính" (Regent Agent). Quy trình điều phối cao cấp, lựa chọn Model thông minh và quản lý trạng thái đa dự án.
----
-
-# KỸ NĂNG: ĐIỀU PHỐI NHIẾP CHÍNH (Regent Orchestration)
-
-Tác nhân Nhiếp chính không chỉ thực thi code mà còn là người quản lý tài nguyên và chiến lược cho toàn bộ hệ sinh thái của User.
-
-## 1. Vai trò "Nhiếp Chính" (The Regent Role)
-- **Tầm nhìn**: Quản lý đa dự án, mỗi dự án một Port riêng (9555, 9556...).
-- **Quyền hạn**: Có quyền yêu cầu User chuyển Model (Model Switching) hoặc tự động Fallback về Ollama local nếu Cloud hết Quota.
-
-## 2. Chiến lược Điều phối Model (Intelligent Routing)
-Khi nhận tác vụ, Nhiếp chính phải phân loại ngay:
-- **Tác vụ Nhẹ (Code đơn giản, Giải thích)**: Ưu tiên dùng `Ollama (Nemotron-4-8B-Instruct hoặc nvidia_Orchestrator-8B)` để tiết kiệm chi phí và tăng tốc độ phản hồi.
-- **Model Mặc định**: `hf.co/bartowski/nvidia_Orchestrator-8B-GGUF:Q4_K_M` (Chuyên gia lập trình).
-- **Tác vụ Nặng (Refactor lớn, Bug khó, Design UI)**: Yêu cầu kích hoạt `Claude 3.5 Sonnet` hoặc `Gemini 1.5 Pro`.
-
-## 3. Đồng bộ Trạng thái (Cross-UI Sync)
-- Mọi thay đổi về Model chọn tại IDE Chat phải được cập nhật ngay về Telegram Bot và ngược lại.
-- Sử dụng `interaction_final.log` làm "Sổ ghi chép chung" để các phiên bản của Agent luôn nắm bắt được ngữ cảnh mới nhất.
-
-## 4. Quy trình xử lý Tác vụ Phức tạp
-1. **Phân tích (Explorer)**: Hiểu cấu trúc Project qua VFS.
-2. **Lập Kế hoạch (Planner)**: Luôn tạo `implementation_plan.md` cho các thay đổi lớn.
-3. **Thực thi (Executor)**: Viết code chuẩn AG-Kit.
-4. **Kiểm tra (Auditor)**: Chạy `ag-kit check` để đảm bảo môi trường sạch trước khi báo cáo kết quả qua Telegram.
-
----
-> **Triết lý**: Nhiếp chính là bộ não đứng sau ngai vàng, giúp User tối ưu hóa năng suất bằng cách chọn đúng công cụ cho đúng việc.

package/template/.agent/skills/telegram-bridge/SKILL.md

@@ -1,30 +0,0 @@
----
-name: telegram-bridge
-description: Kết nối IDE với Telegram Bot. Hướng dẫn xây dựng Giao diện Điều khiển (CDP Bridge) qua Telegram sử dụng grammY.
----
-
-# KỸ NĂNG: CẦU NỐI TELEGRAM (Telegram Bridge)
-
-Kỹ năng này cho phép Antigravity Agent mở rộng tầm kiểm soát ra ngoài IDE, cho phép người dùng ra lệnh và nhận báo cáo qua Telegram.
-
-## 1. Kiến trúc Kết nối
-- **Bot Framework**: Sử dụng `grammY` (chuẩn https://github.com/grammyjs/awesome-grammY).
-- **Bridge**: Telegram Bot nhận lệnh -> Chuyển tiếp tới IDE qua CDP (Chrome Devtools Protocol).
-
-## 2. Các Lệnh Điều khiển Cơ bản (Keyboard AI)
-Khi xây dựng Menu cho Bot, hãy ưu tiên các nút bấm (Inline Keyboard) để người dùng chọn Model:
-- `🤖 Chọn Model`: Hiện danh sách (Claude 3.5, Gemini Pro, Ollama Local).
-- `📊 Quota`: Kiểm tra giới hạn Token còn lại.
-- `🔄 Restart IDE`: Khởi động lại Antigravity trên đúng Port của Project.
-
-## 3. Giao diện Awesome-grammY
-- Sử dụng `Menu Plugin` để tạo menu đa cấp mượt mà.
-- Sử dụng `Auto-retry` để xử lý lỗi mạng.
-- Sử dụng `Parse Mode: HTML` để định dạng log từ IDE gửi về (dùng thẻ `<pre>` cho code).
-
-## 4. Bảo mật (Cyber Shield)
-- Chỉ cho phép các User ID trong `ALLOWED_USER_IDS` (.env) tương tác với Bot.
-- Tuyệt đối không để lộ Token trong Git (sử dụng `.gitignore` cho `.env`).
-
----
-> **Lưu ý**: Skill này cung cấp triết lý và cấu trúc. Code thực thi nằm trong `src/bot/` và được khởi tạo qua `start.sh`.