@mazees/mark 5.0.0 → 5.0.2

package/README.md

@@ -1,7 +1,15 @@
-# MARK - Metacognitive Artificial Relational Knowledge (v5.0.0)
+# MARK - Metacognitive Artificial Relational Knowledge
 
-![MARK AI Banner](./assets/banner-repo.png)
-[![Download Terbaru](https://img.shields.io/badge/Download-Versi_Terbaru-blue?style=for-the-badge&logo=windows)](https://github.com/Mazees/mark-agent/releases/)
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Mazees/mark-agent/master/assets/banner-repo.png" alt="MARK AI Banner" width="100%">
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@mazees/mark"><img src="https://img.shields.io/npm/v/@mazees/mark?style=for-the-badge&color=1fb854&logo=npm" alt="npm version"></a>
+  <a href="https://github.com/Mazees/mark-agent"><img src="https://img.shields.io/badge/Platform-Windows_10%2F11-blue?style=for-the-badge&logo=windows" alt="Platform"></a>
+  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D20-339933?style=for-the-badge&logo=node.js" alt="Node.js"></a>
+  <a href="https://github.com/Mazees/mark-agent/releases/"><img src="https://img.shields.io/badge/Download-Releases-blue?style=for-the-badge&logo=github" alt="Download"></a>
+</p>
 
 > **Mark BUKAN sekadar asisten virtual biasa. Mark adalah entitas AI yang dirancang untuk memiliki emosi, bertindak selayaknya manusia, dan memimpin tim agen cerdas.**
 > Lebih dari sekadar chatbot kaku, Mark adalah _Personal AI OS Companion_ yang berjalan di ekosistem lokal Anda—dilengkapi dengan arsitektur modern **Node.js Core + WebUI (React 19 / Vite 7)** dalam antarmuka Microsoft Edge App Mode (dengan fallback otomatis ke browser default) dan CLI Live Activity Monitor (`mark`). Didukung oleh **Centralized SQLite Database**, sistem memori jangka panjang berbasis _Vector Memory_, **Relational Growth System**, **Autonomous Multi-Agent Sub-Agent Engine**, serta **Multi-Session Browser Automation**. Ditenagai oleh _Hybrid AI Engine_, Mark dapat beroperasi secara lokal untuk privasi maksimal, atau menggunakan _Cloud APIs_ untuk mengeksekusi tugas kompleks, menyusun rencana (_Agentic Planning_), mengotomatisasi desktop PC, merangkum video YouTube, mengobservasi layar atau dunia nyata (_Vision_), hingga kendali jarak jauh via **Telegram Bot**.
@@ -13,19 +21,25 @@
 
 ## Fitur Unggulan
 
-- **Arsitektur Decoupled V5 (Node.js Core + Modern WebUI):** Inti aplikasi dipisahkan menjadi server Node.js performa tinggi (`src/server/`) dengan WebSocket Hub (`/stream`) dan antarmuka React 19 / Vite 7 (`src/renderer/`). Berjalan ringan dalam mode Microsoft Edge App Mode terisolasi (dengan fallback otomatis ke browser default) dan CLI Live Activity Monitor (`mark`).
-- **Autonomous Multi-Agent Sub-Agent Engine (Mission Control):** Mark bertindak sebagai _Lead Agent_ yang mampu memecah tugas kompleks dan mendelegasikannya ke banyak **Sub-Agent spesialis** yang bekerja secara paralel di latar belakang. Dilengkapi dengan antarmuka **Mission Control** dan **Live Sub-Agent Intercom HUD** yang menampilkan pemikiran mendalam (_Reasoning Analisis_), langkah eksekusi berkala (_Execution Steps_), dan laporan hasil akhir dengan dukungan penuh Markdown & Syntax Highlighting.
+- **Arsitektur Decoupled (Node.js Core + Modern WebUI):** Inti aplikasi dipisahkan menjadi server Node.js performa tinggi (`src/server/`) dengan WebSocket Hub (`/stream`) dan antarmuka React 19 / Vite 7 (`src/renderer/`). Berjalan ringan dalam mode Microsoft Edge App Mode terisolasi (dengan fallback otomatis ke browser default) dan CLI Live Activity Monitor (`mark`).
+- **Autonomous Multi-Agent Sub-Agent Engine (Mission Control):** Mark bertindak sebagai _Lead Agent_ yang mampu memecah tugas kompleks dan mendelegasikannya ke banyak **Sub-Agent spesialis** yang bekerja secara paralel di latar belakang (`spawn_subagent`, `wait_subagents`). Dilengkapi dengan antarmuka **Mission Control** dan **Live Sub-Agent Intercom HUD** yang menampilkan pemikiran mendalam (_Reasoning Analisis_), langkah eksekusi berkala (_Execution Steps_), dan laporan hasil akhir dengan dukungan penuh Markdown & Syntax Highlighting.
+- **Operator-Style Execution Timeline & Parameter Reason:** Visualisasi langkah eksekusi ReAct bergaya modern operator dengan status badge lipat (_collapsible details_), parameter `reason` terstruktur pada setiap eksekusi tool, dan rendering intervensi pengguna langsung di alur langkah eksekusi (_in-flight user intervention_).
+- **Interactive File Diff Modal & Syntax Safety:** Inspeksi visual perbedaan berkas (_file diff_) sebelum dan sesudah perubahan kode diterapkan. Mendukung peninjauan baris kode yang ditambah/dihapus secara interaktif serta validasi sintaksis otomatis (_syntax validator_) sebelum penulisan ke disk untuk mencegah kerusakan berkas kode.
+- **Kapasitas Konteks Masif (256K Tokens) & Zero-Recalc Caching:** Manajemen konteks cerdas berkapasitas hingga 256.000 token dengan caching token persisten di basis data SQLite. Mencegah komputasi ulang token yang boros sumber daya dan memungkinkan dialog teknis serta analisis repositori kode bervolume besar secara instan.
 - **Centralized SQLite & Real-Time Hybrid Vector Engine:** Seluruh data (memori kognitif, riwayat obrolan, turn pairs, konfigurasi, sub-agent, dan tasks) tersimpan terpusat di `%USERPROFILE%\.config\mark-agent\mark.db` menggunakan `better-sqlite3` dalam WAL mode berkecepatan tinggi. Diindeks secara _real-time_ ke mesin pencari hybrid `@orama/orama` menggunakan model embedding lokal 384-dimensi (`Xenova/paraphrase-multilingual-MiniLM-L12-v2`) via Transformers.js tanpa ketergantungan API luar.
 - **Universal Zero-Hallucination Policy & Strict Groundedness:** Menerapkan kebijakan anti-halusinasi ketat di seluruh ekosistem Mark. Jika data riwayat percakapan lama, berkas kode, atau fakta dokumen tidak ditemukan, Mark wajib jujur mengakuinya dan dilarang keras mengarang informasi, menambah-nambahkan poin fiktif (_anti-extrapolation_), atau berpura-pura mengingat hal yang belum pernah dibahas.
 - **Multi-Session Isolated Browser Automation:** Sistem browser Chromium fisik Mark mendukung sesi independen tanpa batas berbasis `puppeteer-core`. Beberapa Sub-Agent dapat melakukan riset web, menavigasi Google, mengekstrak data, dan mengisi formulir secara bersamaan tanpa saling mengganggu, didukung oleh **Multi-Card Holo Preview** yang menampilkan status visual tiap sesi di antarmuka desktop.
 - **Dynamic Agentic Planning (ReAct Loop):** Mengganti sistem penjawab statis dengan arsitektur penalaran cerdas. Mark mampu memecah masalah, memikirkan strategi, menggunakan _tools_ secara otonom berulang kali, dan mengevaluasi hasilnya sebelum memberikan jawaban akhir yang komprehensif.
 - **Agent Task Workflows (Durable Tasks & Mission Control):** Untuk pekerjaan multi-langkah yang panjang, Mark secara otonom mendekomposisi tugas menjadi tahapan konkret via tool `create_agent_task` (atau dipicu manual via perintah `/task` dan alias `/plan`). Setiap langkah divalidasi, di-checkpoint persisten ke basis data SQLite, dapat di-retry otomatis, dan menghasilkan berkas artefak markdown resmi di folder `Documents/Mark Tasks/<task-id>/` yang terpantau real-time pada komponen antarmuka `DurableTaskBubble` di chat stream.
 - **Zero-Vision Physical PC & Desktop Automation (Windows UIAutomation + C# Daemon):** Menggunakan daemon PowerShell C# persisten (`pc-daemon.ps1`), Mark dapat membaca elemen GUI desktop secara struktural, mengklik koordinat, mengetik teks Unicode, menekan kombinasi _shortcut_, hingga mengelola jendela aplikasi di Windows secara fisik dengan kecepatan tinggi tanpa biaya vision API. Dilengkapi _Floating Security Banner_ dan tombol darurat **Emergency Stop (`Ctrl+Shift+S`)**.
+- **Integrasi Google Workspace Suite & GDrive Share:** Terhubung dengan ekosistem Google Workspace via OAuth2 untuk mengelola Google Calendar (jadwal/agenda), Google Drive (pencarian, pengunggahan, pembagian berkas / _GDrive Share_), dan Gmail (pembacaan serta pengiriman email).
+- **Workspace Tagging (`@workspace`) & Context Clusters:** Dukungan penandaan konteks direktori kerja secara eksplisit (`@workspace`), pencarian semantik file kerja lokal (_Workspace RAG_), dan pengelompokan tool dinamis (_tool clusters_) sesuai kebutuhan tugas.
+- **Developer-Grade Responsive CLI Live Monitor & Auto-Updater:** Antarmuka terminal interaktif yang beradaptasi secara dinamis dengan lebar layar terminal mana pun (`process.stdout.columns`), notifikasi pembaruan resmi otomatis di latar belakang, zero emoji, dan shortcut kontrol cepat (`[u]` buka UI, `[p]` update info, `[c]` bersihkan layar, `[q]` keluar).
 - **Infinite Memory & Injection Knowledge RAG:** Sistem Vector Retrieval-Augmented Generation (RAG) berjalan secara _offline_. Mark menyimpan riwayat memori obrolan masif tanpa batas dan pengguna dapat menambahkan dokumen (.pdf, .docx, .txt, .md) ke dalam _knowledge base_ tanpa membebani _context window_ LLM.
 - **Automatic Memory Groomer (Hippocampus Engine):** Sistem pembersihan dan konsolidasi memori mandiri berbasis _Orama Clustering_ dan _LLM Batch Processing_. Hippocampus Engine mendeteksi klaster memori serupa (`profile` & `preference`) lalu menggabungkannya secara kronologis tanpa kehilangan riwayat penting.
 - **Visualisasi Jaringan Otak (Memory Visualizer):** Antarmuka _Live Feed_ "Mark Neural Core" berbasis grafis Neural Network 2D interaktif (`react-force-graph-2d`) untuk menjelajahi jaringan _Chat History_, _Knowledge Base_, hingga _Document Vault_.
-- **Relational Growth System & Dynamic Persona:** Hubungan Anda dengan Mark dievaluasi layaknya manusia sungguhan melalui 4 parameter krusial (_Warmth, Sarcasm, Trust, Energy_). Tingkat kesopanan, kelancangan (_roasting_), dan kepribadian Mark akan berevolusi organik sesuai gaya komunikasi Anda.
-- **Multi AI Provider (Built-in Gemini / Local / Cloud):** Mark hadir dengan **Google Gemini Engine (Gratis)** sebagai _provider_ bawaan yang siap pakai tanpa API Key. Anda juga memiliki fleksibilitas penuh untuk menggunakan **Local AI** (LM Studio), **Cloud AI** (Groq / Cerebras), maupun _Custom OpenAI-Compatible API_.
+- **Relational Growth System & Tactile Avatar:** Hubungan Anda dengan Mark dievaluasi layaknya manusia sungguhan melalui 4 parameter krusial (_Warmth, Sarcasm, Trust, Energy_) dengan preservasi riwayat mood AI dan respons interaksi visual taktil pada avatar. Tingkat kesopanan, kelancangan (_roasting_), dan kepribadian Mark akan berevolusi organik sesuai gaya komunikasi Anda.
+- **Multi AI Provider (Built-in Gemini / DeepSeek / Local / Cloud):** Mark hadir dengan **Google Gemini Engine (Gratis)** sebagai _provider_ bawaan yang siap pakai tanpa API Key. Anda juga memiliki fleksibilitas penuh untuk menggunakan **DeepSeek Web RPC**, **Local AI** (LM Studio), **Cloud AI** (Groq / Cerebras), maupun _Custom OpenAI-Compatible API_.
 - **Asisten Bot Telegram Mandiri (Telegraf Engine):** Terhubung langsung dengan Telegram Bot API. Mark dapat dikontrol jarak jauh via Telegram, merangkum obrolan, mengunduh MP3 YouTube, mengambil tangkapan layar PC, dan secara otomatis menyinkronkan seluruh balasan & _Awareness Engine_ ke Telegram Admin secara _real-time_.
 - **Proaktif dengan Awareness Engine:** Mark tidak hanya pasif merespons. Mark dapat proaktif menyapa, mengingatkan tugas, atau memutarkan musik di latar belakang saat Anda sedang bersantai atau bekerja fokus.
 
@@ -35,21 +49,25 @@
 
 - **Autonomous Multi-Agent Tools:** `spawn_subagent`, `wait_subagents`, `send_message`, `list_subagents`, `kill_subagent`.
 - **Durable Task Workflow Engine:** `create_agent_task` (pemecahan tugas multi-tahap terstruktur, checkpointing berkala, validasi kelayakan deliverable, dan generasi berkas artefak).
+- **Git Workspace Tools (`git-*`):** `git-status`, `git-diff`, `git-commit`, `git-revert`.
+- **Google Workspace Suite (`google-*` / `gdrive-*` / `gcal-*` / `gmail-*`):** `gdrive-search`, `gdrive-list`, `gdrive-read`, `gdrive-upload`, `gdrive-create`, `gdrive-move`, `gdrive-copy`, `gdrive-share`, `gdrive-info`, `gcal-list`, `gcal-create`, `gcal-delete`, `gmail-search`, `gmail-read`, `gmail-send`, `gmail-mark-read`.
 - **Memory & Recall Tools (`memory-search`):** Pencarian semantik memori, preferensi, catatan teknis, dan pasangan percakapan asli (Turn Pairs) dengan _similarity threshold_ dinamis (`keyword||threshold||limit`, default threshold `0.5`, limit `5`).
 - **Multi-Session Web Browsing (`browser-*`):** `browser-navigate`, `browser-read`, `browser-click`, `browser-type`, `browser-scroll`, `browser-extract`, `browser-ask-user`, `browser-close`.
 - **Desktop Automation (`os-*`):** `os-read`, `os-click`, `os-type`, `os-key`, `os-scroll`, `os-open`, `os-list-windows`, `os-focus-window`.
 - **Native File Handling & PowerShell:** `read-file`, `write-file`, `replace-content`, `delete-file`, `list-dir`, `grep-search`, `run-powershell`.
+- **Background Tasks Engine:** `run-task`, `read-task-output`, `kill-task`, `list-tasks`.
 - **Vision Awareness:** `analyze-screen` (analisis layar multi-monitor) dan `camera-look` (observasi visual webcam).
 - **Interaksi Suara Natural:** Voice Activity Detection (VAD) dengan Groq Whisper STT / Local Whisper dan Edge-TTS (`id-ID-ArdiNeural`).
 - **Perangkum YouTube & YouTube Music:** Transkripsi kilat video YouTube dan pemutar YouTube Music tanpa iklan dengan _ad-blaster_.
 - **Mark Skills System:** Kustomisasi kepribadian dan kapabilitas menggunakan instruksi Markdown (`.md`) dengan pemanggilan slash command (`/nama-skill`) serta native built-in skills (`/task`, `/plan`).
 - **Sistem Plugin Kustom:** Penambahan modul fungsi Node.js baru langsung dari antarmuka pengguna dengan Monaco Editor.
+- **Telegram Bot Integration:** Sinkronisasi notifikasi, pengiriman tangkapan layar, dan kontrol perintah jarak jauh melalui Telegram.
 
 ---
 
 ## Arsitektur Memory Persistence & Integritas Fakta
 
-Arsitektur memori Mark V5 dirancang untuk kontinuitas ingatan jangka panjang (_Long-Term Memory Persistence_) secara lokal tanpa bergantung pada cloud:
+Arsitektur memori Mark dirancang untuk kontinuitas ingatan jangka panjang (_Long-Term Memory Persistence_) secara lokal tanpa bergantung pada cloud:
 
 1. **Episodic Memory (Turn-Pair Vector Index)**:
    - Setiap sesi percakapan dipecah ke dalam unit dialog utuh (Pertanyaan Pengguna + Jawaban AI).
@@ -65,7 +83,7 @@ Arsitektur memori Mark V5 dirancang untuk kontinuitas ingatan jangka panjang (_L
 
 ---
 
-## Arsitektur Proyek (V5)
+## Arsitektur Proyek
 
 ```text
 mark/
@@ -140,12 +158,46 @@ mark/
 ### Persyaratan Sistem
 
 - **Sistem Operasi**: Windows 10/11 (64-bit)
-- **Node.js**: Versi 20 atau lebih baru
+- **Node.js**: Versi 20 atau lebih baru ([Unduh Node.js LTS](https://nodejs.org/))
 - **Browser**: Microsoft Edge (bawaan Windows) atau Google Chrome
 - (Opsional) **LM Studio** untuk model AI lokal _offline_.
 - (Opsional) **API Key Groq / Cerebras** untuk inferensi awan berkecepatan tinggi.
 
-### Menjalankan dari Source Code (Development)
+---
+
+### Cara 1: Instalasi Instan via NPM (Direkomendasikan)
+
+Pasang MARK secara global di sistem Windows Anda melalui PowerShell atau Command Prompt:
+
+```bash
+npm install -g @mazees/mark
+```
+
+Setelah instalasi selesai, luncurkan MARK kapan saja dari folder mana pun di terminal:
+
+```bash
+mark
+```
+
+_MARK Core Server akan langsung aktif, membuka Live Activity Monitor di terminal, dan meluncurkan antarmuka WebUI dalam mode desktop terisolasi (Microsoft Edge App Mode)._
+
+#### Menjalankan Instan Tanpa Instalasi (via npx):
+
+```bash
+npx @mazees/mark
+```
+
+#### Memperbarui ke Versi Terbaru:
+
+```bash
+npm install -g @mazees/mark@latest
+```
+
+---
+
+### Cara 2: Menjalankan dari Source Code (Development / Kontributor)
+
+Jika Anda ingin memodifikasi kode sumber atau berkontribusi pada pengembangan MARK:
 
 1. **Kloning repositori:**
 
@@ -160,15 +212,19 @@ mark/
    npm install
    ```
 
-3. **Jalankan aplikasi (Development):**
+3. **Build antarmuka WebUI:**
 
    ```bash
-   npm start
+   npm run build:ui
    ```
 
-   _Perintah ini akan menyalakan server Node.js Core di port dinamis (default: 3000) dan membuka antarmuka MARK di Microsoft Edge App Mode._
+4. **Jalankan aplikasi (Production mode):**
 
-4. **Menjalankan UI & Server secara terpisah (Dev Mode):**
+   ```bash
+   npm start
+   ```
+
+5. **Menjalankan UI & Server secara terpisah (Dev Mode Hot-Reload):**
 
    ```bash
    # Terminal 1: Core Backend Server
@@ -178,31 +234,17 @@ mark/
    npm run dev:ui
    ```
 
-### Menjalankan Perintah Global `mark` di Terminal
-
-1. **Build WebUI:**
-
-   ```bash
-   npm run build:ui
-   ```
-
-2. **Daftarkan perintah `mark` (Global Symlink):**
+6. **Mendaftarkan perintah `mark` lokal (Global Symlink):**
 
    ```bash
    npm link
    ```
 
-3. **Jalankan dari folder mana saja di terminal:**
-   ```bash
-   mark
-   ```
-   _Perintah ini akan membuka Live Activity Monitor di terminal dan otomatis meluncurkan antarmuka WebUI MARK di layar._
-
 ---
 
-## Panduan Migrasi Data (Versi Sebelumnya ke V5)
-
-Bagi pengguna MARK versi sebelumnya (berbasis Electron/Dexie) yang ingin memindahkan seluruh memori, dokumen, dan riwayat obrolan ke MARK V5 (berbasis SQLite), silakan baca panduan lengkap di [docs/MIGRATION_GUIDE.md](./docs/MIGRATION_GUIDE.md).
+## Panduan Migrasi Basis Data
+ 
+Bagi pengguna MARK versi sebelumnya (berbasis Electron/Dexie) yang ingin memindahkan seluruh memori, dokumen, dan riwayat obrolan ke MARK (berbasis SQLite), silakan baca panduan lengkap di [docs/MIGRATION_GUIDE.md](./docs/MIGRATION_GUIDE.md).
 
 ---