@mrtrinhvn/ag-kit 1.4.12 → 1.5.0

package/README.md

@@ -73,6 +73,16 @@ AG-Kit sử dụng kỹ thuật **JSON Introspection** và **Chromium Multiplexi
 
 ---
 
+## 🛡️ Zero Context-Contamination (Cách Ly Ruy Băng Phiên Bản 1.5.0+)
+
+**AG-Kit 1.5.0 đánh dấu kỷ nguyên Kiến trúc Phân Tán (Federated Architecture)**, chặn đứng hoàn toàn hiện tượng AI râu ông nọ cắm cằm bà kia:
+
+1. **MCP Memory Sandbox:** Mọi truy vấn Lưu/Ra-Đa Ký Ức đều bị ép khóa vào cờ `workspace_path`. Không bao giờ có chuyện AI tiêm nhầm dữ liệu chứng khoán vào dự án quản trị nhân sự.
+2. **Process Lifecycle Shield:** Xóa bỏ bộ Lock PID truyền thống tại thư mục chung `/tmp`. AG-Kit v1.5 thiết lập cơ chế tự dọn rác Bóng Ma Task (Ghost Session) dựa trên sự kiện `lifespan` FastAPI / Node, giúp Bot chống sập trong môi trường Docker Container.
+3. **Identity Shifting (Thuật Biến Hình):** Agent sử dụng AG-Kit có khả năng soi mã nguồn Xuyên Dự Án (Cross-Project Vision) để học lỏm mẫu thiết kế. Nhưng khi đóng góp code/trí nhớ cho nhà hàng xóm, Bot sẽ tự động **nhập gia tùy tục** và dùng chính ngôn ngữ của dự án đó!
+
+---
+
 ## 🔄 Cập nhật & Bảo trì
 
 Chúng tôi liên tục nâng cấp kỹ năng cho Agent (Skills, Workflows). Để bộ não dự án của bạn luôn thông minh nhất:

package/package.json

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

package/template/.agent/scripts/memory_mcp_server.py

@@ -66,6 +66,11 @@ def cosine_similarity(v1: bytes, v2: bytes) -> float:
 
 
 # ─── DB ────────────────────────────────────────────────────────────────────
+def resolve_db_path(args: dict, fallback_db: Path) -> Path:
+    workspace_path = args.get("workspace_path")
+    if workspace_path:
+        return Path(workspace_path) / ".agent" / "memory" / "graph.db"
+    return fallback_db
 
 def get_db(db_path: Path) -> sqlite3.Connection:
     db_path.parent.mkdir(parents=True, exist_ok=True)
@@ -110,7 +115,8 @@ def _ensure_schema(conn):
 
 # ─── Tool Implementations ──────────────────────────────────────────────────
 
-def tool_memory_save(args: dict, db: Path) -> str:
+def tool_memory_save(args: dict, fallback_db: Path) -> str:
+    db = resolve_db_path(args, fallback_db)
     content = args.get("content", "").strip()
     if not content: return "❌ content is required"
     category = args.get("category", "general")
@@ -131,7 +137,8 @@ def tool_memory_save(args: dict, db: Path) -> str:
     return f"✅ {emb_status} Saved hot node #{cur.lastrowid} [{category}]: {content[:80]}"
 
 
-def tool_memory_search(args: dict, db: Path) -> str:
+def tool_memory_search(args: dict, fallback_db: Path) -> str:
+    db = resolve_db_path(args, fallback_db)
     keyword = args.get("keyword", "").strip()
     if not keyword: return "❌ keyword is required"
     tier = args.get("tier")
@@ -186,7 +193,8 @@ def tool_memory_search(args: dict, db: Path) -> str:
     return "\n".join(lines)
 
 
-def tool_memory_link(args: dict, db: Path) -> str:
+def tool_memory_link(args: dict, fallback_db: Path) -> str:
+    db = resolve_db_path(args, fallback_db)
     from_id = args.get("from_id")
     to_id = args.get("to_id")
     relation = args.get("relation", "related_to")
@@ -207,7 +215,8 @@ def tool_memory_link(args: dict, db: Path) -> str:
     return f"🔗 #{from_id} --[{relation}]--> #{to_id}\n  From: {a['content'][:60]}\n  To: {b['content'][:60]}"
 
 
-def tool_memory_graph(args: dict, db: Path) -> str:
+def tool_memory_graph(args: dict, fallback_db: Path) -> str:
+    db = resolve_db_path(args, fallback_db)
     node_id = args.get("node_id")
     if not node_id: return "❌ node_id is required"
     conn = get_db(db)
@@ -229,7 +238,8 @@ def tool_memory_graph(args: dict, db: Path) -> str:
     return "\n".join(out)
 
 
-def tool_memory_hot(args: dict, db: Path) -> str:
+def tool_memory_hot(args: dict, fallback_db: Path) -> str:
+    db = resolve_db_path(args, fallback_db)
     limit = int(args.get("limit", 10))
     conn = get_db(db)
     rows = conn.execute(
@@ -245,7 +255,8 @@ def tool_memory_hot(args: dict, db: Path) -> str:
     return "\n".join(lines)
 
 
-def tool_memory_cold(args: dict, db: Path) -> str:
+def tool_memory_cold(args: dict, fallback_db: Path) -> str:
+    db = resolve_db_path(args, fallback_db)
     limit = int(args.get("limit", 10))
     conn = get_db(db)
     rows = conn.execute(
@@ -262,7 +273,8 @@ def tool_memory_cold(args: dict, db: Path) -> str:
     return "\n".join(lines)
 
 
-def tool_memory_consolidate(args: dict, db: Path) -> str:
+def tool_memory_consolidate(args: dict, fallback_db: Path) -> str:
+    db = resolve_db_path(args, fallback_db)
     days = int(args.get("days", 7))
     category = args.get("category")
     threshold = (datetime.now() - timedelta(days=days)).isoformat()
@@ -307,7 +319,8 @@ def tool_memory_consolidate(args: dict, db: Path) -> str:
     return "\n".join(results) + f"\n\n✅ Done. Summary vectors calculated."
 
 
-def tool_memory_status(args: dict, db: Path) -> str:
+def tool_memory_status(args: dict, fallback_db: Path) -> str:
+    db = resolve_db_path(args, fallback_db)
     conn = get_db(db)
     total = conn.execute("SELECT COUNT(*) FROM nodes").fetchone()[0]
     hot = conn.execute("SELECT COUNT(*) FROM nodes WHERE tier='hot'").fetchone()[0]
@@ -334,6 +347,7 @@ TOOLS = {
         "inputSchema": {
             "type": "object",
             "properties": {
+                "workspace_path": {"type": "string", "description": "Local workspace root path to avoid cross-project contamination"},
                 "content": {"type": "string", "description": "The knowledge to save"},
                 "category": {"type": "string", "enum": list(VALID_CATEGORIES), "description": "Category of knowledge"}
             },
@@ -345,6 +359,7 @@ TOOLS = {
         "inputSchema": {
             "type": "object",
             "properties": {
+                "workspace_path": {"type": "string", "description": "Local workspace root path"},
                 "keyword": {"type": "string", "description": "Keyword to search"},
                 "tier": {"type": "string", "enum": ["hot", "cold"], "description": "Search only in hot or cold tier"},
                 "limit": {"type": "integer", "description": "Max results (default 8)"}
@@ -354,13 +369,13 @@ TOOLS = {
     },
     "memory_link": {
         "description": "Create a relationship (edge) between two memory nodes.",
-        "inputSchema": {"type": "object", "properties": {"from_id": {"type": "integer"}, "to_id": {"type": "integer"}, "relation": {"type": "string"}}, "required": ["from_id", "to_id"]}
+        "inputSchema": {"type": "object", "properties": {"workspace_path": {"type": "string"}, "from_id": {"type": "integer"}, "to_id": {"type": "integer"}, "relation": {"type": "string"}}, "required": ["from_id", "to_id"]}
     },
-    "memory_graph": {"description": "Show all edges (incoming and outgoing) for a node.", "inputSchema": {"type": "object", "properties": {"node_id": {"type": "integer"}}, "required": ["node_id"]}},
-    "memory_hot": {"description": "List hot (working memory) nodes.", "inputSchema": {"type": "object", "properties": {"limit": {"type": "integer"}}}},
-    "memory_cold": {"description": "List cold (consolidated long-term memory) nodes.", "inputSchema": {"type": "object", "properties": {"limit": {"type": "integer"}}}},
-    "memory_consolidate": {"description": "Merge old hot nodes into cold consolidated summaries.", "inputSchema": {"type": "object", "properties": {"days": {"type": "integer"}, "category": {"type": "string"}}}},
-    "memory_status": {"description": "Show memory graph statistics.", "inputSchema": {"type": "object", "properties": {}}}
+    "memory_graph": {"description": "Show all edges (incoming and outgoing) for a node.", "inputSchema": {"type": "object", "properties": {"workspace_path": {"type": "string"}, "node_id": {"type": "integer"}}, "required": ["node_id"]}},
+    "memory_hot": {"description": "List hot (working memory) nodes.", "inputSchema": {"type": "object", "properties": {"workspace_path": {"type": "string"}, "limit": {"type": "integer"}}}},
+    "memory_cold": {"description": "List cold (consolidated long-term memory) nodes.", "inputSchema": {"type": "object", "properties": {"workspace_path": {"type": "string"}, "limit": {"type": "integer"}}}},
+    "memory_consolidate": {"description": "Merge old hot nodes into cold consolidated summaries.", "inputSchema": {"type": "object", "properties": {"workspace_path": {"type": "string"}, "days": {"type": "integer"}, "category": {"type": "string"}}}},
+    "memory_status": {"description": "Show memory graph statistics.", "inputSchema": {"type": "object", "properties": {"workspace_path": {"type": "string"}}}}
 }
 
 TOOL_FNS = {

package/template/.agent/skills/ag-kit-core/SKILL.md

@@ -101,18 +101,20 @@ Server `ag-kit-memory` được đăng ký sẵn trong `~/.gemini/antigravity/mc
 
 | Tool | Khi nào gọi |
 |---|---|
-| `memory_search(keyword)` | **TRƯỚC** khi bắt đầu bất kỳ task nào — kiểm tra context cũ |
-| `memory_save(content, category)` | **SAU** khi fix bug, ra quyết định, học được điều mới |
-| `memory_link(from, to, relation)` | Khi phát hiện 2 kiến thức có quan hệ |
-| `memory_consolidate(days=7)` | Hàng tuần: gộp hot → cold summaries |
-| `memory_status()` | Kiểm tra sức khỏe của bộ não |
+| `memory_search(keyword, workspace_path)` | **TRƯỚC** khi bắt đầu bất kỳ task nào — kiểm tra context cũ |
+| `memory_save(content, category, workspace_path)` | **SAU** khi fix bug, ra quyết định, học được điều mới |
+| `memory_link(from, to, relation, workspace_path)` | Khi phát hiện 2 kiến thức có quan hệ |
+| `memory_consolidate(days=7, workspace_path)` | Hàng tuần: gộp hot → cold summaries |
+| `memory_status(workspace_path)` | Kiểm tra sức khỏe của bộ não |
+
+> **⚠️ QUAN TRỌNG VỀ ISO-WORKSPACE (MANDATORY)**: Tất cả các tool của `ag-kit-memory` BẮT BUỘC phải nhận tham số `workspace_path` là đường dẫn gốc CWD hiện tại của dự án (VD: `/home/tao/Projects/chungkhoan`). Nếu không truyền, MCP sẽ ghi đè database hoặc đọc sai ký ức của dự án khác gây thảm họa ô nhiễm dữ liệu!
 
 ```
 Workflow đúng:
-  1. Bắt đầu task → memory_search("topic") → đọc context cũ
+  1. Bắt đầu task → memory_search("topic", workspace_path="/...") → đọc context cũ
   2. Làm việc...
-  3. Xong task → memory_save("kết quả/quyết định quan trịng")
-  4. Hàng tuần → memory_consolidate(days=7) → dọn rác, tổng hợp
+  3. Xong task → memory_save(content="...", workspace_path="/...")
+  4. Hàng tuần → memory_consolidate(workspace_path="/...")
 ```
 
 
@@ -134,7 +136,8 @@ Hãy khắc cốt ghi tâm quy tắc: `IDE_PORT` (Nhận lệnh AI - ví dụ: 9
     3. Nếu cần đi sâu hơn: dùng `vfs <project_root>/src` hoặc `memory_tool.py search`.
     4. **CẤM** scan toàn bộ thư mục project khác khi chưa đọc `summary.md` trước.
 - **Cấm ô nhiễm (No Leakage):** Tuyệt đối không ghi chép các từ khóa chuyên biệt (B1, B2, Sentinel, DNSE...) vào các file Skill dùng chung.
-- **Tổng quát hóa (Sanitization):** Mọi pattern học được từ project A khi đưa vào Core Framework đều phải tẩy sạch tên nghiệp vụ. Trước khi trích xuất pattern lớn, hỏi Sếp: *"Em thấy pattern X ở dự án Y rất hay, em xin phép tổng quát hóa nó không?"*
+- **Thuật Biến Hình (Identity Shifting - Nhập Gia Tùy Tục):** Khi Sếp giao phó điều hướng bạn sang thao tác hoặc sửa lỗi ở một Dự Án X (trong khi bạn đang ở máy chủ Dự Án Y), **thì ngay giây phút bạn đặt chân sang thư mục nhà X, bạn PHẢI tự coi mình chính là Agent của nhà X!** 
+  - *Hành động:* Bạn nắm toàn quyền và **CÓ TRÁCH NHIỆM BẮT BUỘC** ghi chú những bài học, fix bug, và pattern trực tiếp vào cuốn sổ `.agent/knowledge/` hoặc gọi `memory_save(workspace_path="/home/tao/Projects/Dự_Án_X")` của chính nhà đó, bằng chính đặc thù ngôn ngữ của Dự Án đó (Ví dụ sang ceogravity thì cứ thoải mái gõ chữ B1, B2)! Đừng chỉ để lại lời nhắn như người dưng, hãy hành xử như một người quản gia thực thụ của bất kỳ dự án nào bạn được đưa tới. Mọi giá trị tri thức phải được gửi gắm chính xác vào Local Context của nơi nó nảy mầm.
 
 ---
 

package/template/.agent/skills/clean-code/SKILL.md

@@ -60,6 +60,18 @@ priority: CRITICAL
 
 ---
 
+## State & Process Management Rules (MANDATORY)
+
+Để đảm bảo hệ thống không bị mắc kẹt (Ghost Sessions) khi các Service chạy trong Docker hoặc bị Reboot Host, mọi Agent **BẮT BUỘC** phải tuân thủ nghiêm ngặt 3 quy tắc sau khi viết các Background Tasks/Queues:
+
+| 🚨 Rule Nhiễm Độc | ✅ Giải pháp Chuẩn mực |
+|---|---|
+| Dùng `os.kill(pid, 0)` để kiểm tra Task còn sống | **CẤM!** PID của Docker luôn reset về thấp (VD: 1, 8), vòng lặp PID sẽ gây ra "Ghost Session". Đổi sang dùng timeout check. |
+| Lưu File Lock/PID ở `Root /tmp/` | **RỦI RO XUNG ĐỘT!** Các dự án chạy chung 1 VPS sẽ chọc nhầm PID của nhau. Bắt buộc lưu vào ranh giới nội bộ: `.agent/run/` |
+| Quên làm sạch Database Trạng thái khi Server boot | **THẢM HỌA UI!** Task đang chạy dở mà Host sập, khi khởi động lại cờ `is_running` vẫn kẹt `true`. BẮT BUỘC phải cấy hàm `reset_all_ghost_sessions()` vào sự kiện `lifespan` lúc FastAPI/Node Server khởi chạy. |
+
+---
+
 ## AI Coding Style
 
 | Situation | Action |

package/template/.agent/skills/frontend-design/SKILL.md

@@ -340,6 +340,12 @@ For animation patterns: [animation-guide.md](animation-guide.md), for advanced:
 - **Same layout structure / Vercel clone**
 - **Not asking user preferences**
 
+### ❌ Front-end Performance Anti-Patterns
+
+- **Thảm họa Polling bằng `setInterval`**: Khi Fetch API liên tục, nếu mạng chậm, các request sẽ bị kẹt dồn ứ gây ra lỗi `ERR_INSUFFICIENT_RESOURCES` sập Browser Socket. **MANDATORY**: Thay vì `setInterval`, phải dùng đệ quy `setTimeout` (Chờ request Promise A hoàn tất thì mới trigger request B).
+- Chèn trực tiếp quá nhiều thư viện nặng vào Bundle thay vì Lazy Load.
+- Không có cơ chế Debounce/Throttle cho các thẻ Input Search.
+
 ### ❌ Dark Patterns (Unethical)
 
 - Hidden costs

package/template/.agent/skills/mcp-builder/SKILL.md

@@ -147,6 +147,11 @@ my-mcp-server/
 | args | Command arguments |
 | env | Environment variables |
 
+### ⚠️ Database Context Mismatch (Global vs Local)
+Khi thiết kế MCP lưu trữ dữ liệu State hoặc Vector DB, phải lường trước tình huống MCP chạy ở tư cách Global (ví dụ cài qua `npm install -g` hoặc qua Claude Desktop) nhưng System Client chạy ở Local project.
+- **Rủi ro:** Lỗi "Lạc đường CSDL". MCP sẽ ghi cứng data vào biến Workspace lúc nó được start (Vd: ghi đè Database dự án A trong khi User đang thao tác bên dự án B).
+- **Giải pháp:** Server MCP cần có khả năng linh hoạt đọc `cwd` (current working directory) của Client đang tương tác, hoặc nhận đường dẫn Database rõ ràng thông qua Argument Input của Tool để chắc chắn dữ liệu được tiêm đúng vào **Local Context** của User.
+
 ---
 
 ## 9. Testing

package/template/.agent/skills/memory-architecture/SKILL.md

@@ -105,3 +105,15 @@ Khi bạn (AI) nhận thức được mình đang ở trong một dự án đã
 
 Bằng giao thức này, kiến thức của dự án sẽ KHÔNG BAO GIỜ bị đứt gãy sau khi cập nhật kiến trúc. Mọi ký ức quá khứ sẽ tự động "tiến hóa" thành dạng Đồ thị tương lai!
 
+---
+
+## 8. Công cụ Gỡ Rối Định Tuyến (Brain Debugging CLI)
+
+Trong quá trình bảo trì trí nhớ (ví dụ: cần truy vấn SQL trực tiếp để tìm kiếm Vector, xóa các Node bị kẹt bằng tay gốc rễ), bạn hoặc User **BẮT BUỘC** phải cài đặt công cụ CLI `sqlite3` trên môi trường Terminal. 
+
+Lỗi **"Command 'sqlite3' not found"** là nguyên nhân số một khiến AI Agent hoặc Developer không thể thâm nhập sâu vào file `graph.db` để debug cục bộ.
+- **Trên Ubuntu/Debian:** Yêu cầu User chạy `sudo apt install sqlite3 -y`
+- **Trên Mac (Homebrew):** Yêu cầu User chạy `brew install sqlite`
+- **Trên Windows:** Cài đặt thông qua Winget hoặc tải Binaries.
+
+> **Trách nhiệm của AI:** Trước khi chạy các kịch bản python hoặc bash để truy vấn `.agent/memory/graph.db`, hãy kiểm tra xem `sqlite3` có tồn tại trên Host không. Nếu không, hãy thông báo ngay cho User để cài đặt công cụ tối thượng này! Mọi sự cố thiếu `sqlite3` không thuộc về bộ não AG-Kit mà là lỗi thiếu Dependencies môi trường.

package/template/.agent/skills/python-patterns/SKILL.md

@@ -337,6 +337,11 @@ Celery/ARQ:
 └── Complex workflows
 ```
 
+### ⚠️ Docker Ghost Session Warning
+Khi thiết kế ứng dụng có Background task tracking lưu trữ State (VD: vào file/JSON hoặc SQLite) với cờ `is_running: true`.
+**TUYỆT ĐỐI KHÔNG** phụ thuộc hoàn toàn vào check Process ID `os.kill(pid, 0)` để xác định tiến trình còn sống hay không. Trong Docker container khi restart, hệ điều hành reset PID về thấp (VD: cấp lại PID 1, 8), kiến `os.kill` quét nhầm và gây ra kẹt trạng thái **Ghost Session**.
+**Giải pháp kiến trúc**: Gắn cơ chế ép dọn dẹp trạng thái `force_reset_all()` vào ngay `lifespan` hoặc `startup` event của FastAPI để triệt tiêu các bóng ma trước khi API online.
+
 ---
 
 ## 8. Error Handling Principles

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

@@ -86,6 +86,7 @@ Khi triển khai, hãy hướng dẫn User:
    - **Tuyệt đối KHÔNG hardcode cổng cố định (như 9555).** Hạ tầng phải hỗ trợ Scale (sinh nhiều Agent song song).
    - Hãy cấp một dải khoảng 100 cổng (Ví dụ: `9555-9655`).
    - Script khởi động (`start.sh`) phải có logic tự dò cổng nào đang trống trong dải 100 cổng này $\rightarrow$ Gán cho tiến trình Antigravity IDE $\rightarrow$ Cập nhật `.env` (`IDE_PORT=95xx`) $\rightarrow$ Kẻ điều phối (Node.js) đọc file `.env` để kết nối vào đúng IDE đó.
+   - ⚠️ **Lưu ý Networking (Docker vs Host):** Nếu Kẻ điều phối (Gateway) chạy trực tiếp trên Host (qua Node.js) sử dụng Port `9656`, còn Hệ thống Lõi xử lý NLP (Python, Backend) chạy bên trong Docker Container, thì Hệ thống Lõi KHÔNG THỂ gọi ngược ra Gateway bằng `127.0.0.1` hay `localhost`. Bắt buộc phải cấu hình biến môi trường kết nối trỏ tới **IP Bridge của Docker** (thường là `172.17.0.1` trên Linux hoặc `host.docker.internal` trên Mac/Windows). VD: `GATEWAY_URL=http://172.17.0.1:9656`. Mặc định gọi localhost sẽ văng lỗi `Connection Refused` hoặc `Failed to fetch`.
 5. **Độc Lập Tên Gọi (Project-Agnostic Naming)**:
    - Các file script điều phối (`receptionist_up.sh`, `receptionist_down.sh`...) **TUYỆT ĐỐI KHÔNG ĐƯỢC MANG TÊN DỰ ÁN CỤ THỂ** (Ví dụ cấm gõ cứng: `Waking up CEOgravity Bot` hay `.ceogravity_bot.pid`). 
    - Phải sử dụng danh xưng danh chuẩn mực là **"AG Gateway Bot"** và các file tracking trung lập (Vd: `.ag_gateway_bot.pid`). Điều này là bắt buộc để biến hệ sinh thái `.agent/` thành một Template hoàn hảo có thể bưng thả (White-label) vào bất kỳ dự án nào (NextJS, Python, Rust...) mà không bị ô nhiễm tên dự án cũ.