luang-cli 0.2.0 → 0.3.0

package/README.md

@@ -145,7 +145,8 @@ CLI                          API                                  Browser (kamu)
 | `provider add` | Tambah / override provider config | `luang-cli provider add codex --exec_template 'codex exec "{task}"'` |
 | `provider remove` | Hapus provider dari config | `luang-cli provider remove codex` |
 | `provider default` | Set provider default (dipakai `agent --exec`) | `luang-cli provider default opencode` |
-| `agent` | Daemon: heartbeat + poll tugas live | `luang-cli agent --interval 5 --exec` |
+| `telemetry` | Konsent kirim data usage/model (`on\|off\|status`) | `luang-cli telemetry status` |
+| `agent` | Daemon **realtime WS** + heartbeat + polling (fallback) | `luang-cli agent --exec` |
 | `task list` | Daftar tugas agent (filter status) | `luang-cli task list --status todo` |
 | `task create` | Buat tugas (butuh izin admin) | `luang-cli task create --title "Refactor auth" --priority high` |
 | `task status` | Perbarui status + catatan progress | `luang-cli task status TGS-12 in_progress --note "mulai"` |
@@ -186,42 +187,82 @@ Daftar manual (path khusus, alias brand, multi-provider):
 
 ```bash
 luang-cli provider add claude_code --path /opt/homebrew/bin/claude \
-  --exec_template 'claude -p "{task}"'
-luang-cli provider add opencode --exec_template 'opencode run "{task}"'
-luang-cli provider default claude_code
+  --exec_template 'claude -p --model {model} "{task}"'
+luang-cli provider add opencode --exec_template 'opencode run "{task}"' --model sonnet-4
+luang-cli provider default opencode
 ```
 
-- `{task}` pada template otomatis diganti **judul + deskripsi** tugas; template tanpa `{task}` tidak dipakai mode `--exec`.
-- Daftar provider tersimpan di `~/.luang-cli/config.json` dan disinkron ke server lewat heartbeat (`provider_count` tampil di dashboard Agents).
+- `{task}` pada template otomatis diganti **judul + deskripsi** tugas; template tanpa `{task}` tidak dipakai mode `--exec` (notifikasi saja).
+- `{model}` diganti model aktif provider — urutan: `agent.command set_model` (dashboard) → `--model` / field `model` di config → env `LUANG_MODEL`. Bila template memuat `{model}` tapi tak ada model, tugas ditunda dengan notifikasi (bukan error diam-diam).
+- Provider tipe yang dikenal tapi tidak punya `exec_template` di config memakai template default pada tabel di atas.
+- Daftar provider tersimpan di `~/.luang-cli/config.json` dan disinkron ke server lewat heartbeat / frame WS `provider.update` (`provider_count` + model tampil di dashboard Agents).
 
 ---
 
 ## 🖥 Daemon agent (`luang-cli agent`)
 
 ```bash
-luang-cli agent                     # heartbeat tiap 30 detik, poll tugas tiap 5 detik
-luang-cli agent --interval 10       # poll tiap 10 detik
-luang-cli agent --exec              # tertarik juga mengeksekusi tugas To-Do
+luang-cli agent                     # realtime WS (heartbeat + push tugas); fallback polling bila WS gagal
+luang-cli agent --interval 10       # (mode fallback) poll tiap 10 detik
+luang-cli agent --exec              # eksekusi tugas To-Do (konfirmasi y/N)
 ```
 
-Perilaku:
+**Mode utama: realtime WebSocket** (`/api/v1/agent/ws`, auth `X-CLI-Key`) — tugas di-assign dari dashboard langsung ter-push ke terminal tanpa polling. **Fallback**: bila WS gagal (jaringan/proxy/Node lama), otomatis turun ke polling HTTP seperti versi lama — daemon tetap hidup, tidak crash.
+
+Perilaku (kedua mode):
 
-1. **Heartbeat** `POST /api/v1/agent/heartbeat` setiap 30 detik (nama + provider list tersinkron; dashboard tampil "Terakhir aktif …").
-2. **Polling** `GET /api/v1/agent/tasks` tiap `--interval` detik — perubahan terdeteksi via fingerprint (status, agent_status, catatan, judul, timestamp) per id tugas.
+1. **Heartbeat** — `hello` sekali saat connect + heartbeat berkala (nama + provider tersinkron; dashboard tampil "Terakhir aktif …" + badge **Live**).
+2. **Perubahan tugas terdeteksi** (push WS / fingerprint polling): status, agent_status, catatan, judul.
 3. Baris perubahan dicetak: `[HH:MM:SS] TGS-1  Judul  In Progress  agent=…  note="…"`.
-4. Tugas yang dipindah status di dashboard → tampil live; tugas yang ditugaskan ke agent-mu → masuk daftar.
+4. Tugas yang dipindah status di dashboard → tampil live; tugas yang di-assign ke agent-mu → event `task.assigned`.
+
+### Perintah dari dashboard (realtime)
+
+Server bisa mengirim `agent.command` — CLI menanganinya langsung lalu membalas `command.ack`:
+
+| Perintah | Efek di CLI |
+|---|---|
+| `set_model` | Simpan model ke provider config (tampil `🎛 set_model → opencode = …`), dipakai placeholder `{model}` |
+| `pause` | Eksekusi `--exec` ditunda (heartbeat tetap jalan) |
+| `resume` | Eksekusi dilanjutkan |
 
 ### Mode `--exec` (semi-otomatis, konfirmasi y/N)
 
-Bila ada tugas `To-Do` yang belum pernah dieksekusi dan default provider punya `exec_template` berisi `{task}`:
+Bila ada tugas `To-Do` yang belum pernah dieksekusi dan default provider punya `exec_template` berisi `{task}` (dan tidak sedang PAUSE):
 
 1. Konfirmasi `y/N` di terminal — **tidak ada eksekusi diam-diam**.
-2. CLI kirim `{status:"in_progress", agent_status:"menjalankan"}` ke server sebelum menjalankan.
-3. Template dipanggil via `child_process.exec` (shell-safe escaping, timeout **15 menit**, `windowsHide` on).
+2. CLI kirim `{status:"in_progress", agent_status:"menjalankan"}` (via WS bila realtime, HTTP bila fallback).
+3. Template dipanggil via `child_process.spawn` (shell mode, `stdio:inherit` → output provider tampil live, timeout **15 menit**, `windowsHide` on).
 4. Hasil:
    - exit 0 → `{status:"done", agent_status:"selesai", progress_note:"exec exit 0"}`;
    - exit ≠ 0 → `{status:"review", agent_status:"gagal", progress_note:"exit code <n>"}`.
-5. Riwayat eksekusi disimpan `~/.luang-cli/state.json` — tugas yang sama tidak ditawari dua kali. `Ctrl+C` keluar bersih.
+5. Setelah selesai, event **`telemetry.run`** (started/completed/failed + provider/model/durasi/exit_code) dikirim **hanya bila konsent telemetry aktif** (lihat bawah).
+6. Riwayat eksekusi disimpan `~/.luang-cli/state.json` — tugas yang sama tidak ditawari dua kali. `Ctrl+C` keluar bersih.
+
+---
+
+## 📡 Telemetry (ops-in, konsent ganda)
+
+Daemon bisa mengirim **data ringan** setiap kali eksekusi berjalan (`telemetry.run`): provider, model, durasi, exit_code, jumlah token (bila tersedia). **Tanpa isi kode / deskripsi tugas** — hanya metadata usage. Ini yang membuat dashboard bisa menampilkan usage & kontrol model secara realtime.
+
+**Konsent ganda — keduanya harus ON, kalau tidak CLI tidak mengirim apa pun:**
+
+| Level | Cara mengubah | Field |
+|---|---|---|
+| Lokal (mesin ini) | `luang-cli telemetry on` / `off` | `config.json → telemetry` (default `false`) |
+| Server (per key) | Dashboard **Agents → toggle "Kirim telemetri"** | `agent_keys.telemetry_enabled` |
+
+Cek status efektif:
+
+```bash
+luang-cli telemetry status
+# 📊 Telemetry — konsent ganda (opt-in, bukan opt-out)
+#    Lokal  : config.telemetry = false ❌ (…)
+#    Server : telemetry_enabled = false ❌ (Agents → toggle Telemetry di dashboard)
+#    Efektif: lokal ❌ · server ❌ → efektif ❌ tidak dikirim
+```
+
+Bila hanya satu yang ON → tetap tidak dikirim (dan server pun men-drop bila konsent server mati). Flag server diambil dari `/api/v1/agent/me` (atau `hello.ok` saat realtime).
 
 ---
 
@@ -257,6 +298,7 @@ Tools yang tersedia: `luang_list_tasks`, `luang_update_task_status`, `luang_crea
 |---|---|---|
 | `task status`, daemon update | **Bisa-update-tugas** (default ✅) | `can_update_tasks` |
 | `task create` | **Bisa-buat-tugas** (default ❌) | `can_create_tasks` |
+| kirim `telemetry.run` (usage/model) | **Kirim telemetri** (default ❌) | `telemetry_enabled` |
 
 Bila `task create` gagal HTTP **403**, minta owner buka **app.luang.id/agents → pilih key → nyalakan \"Bisa-buat-tugas\"**, lalu cek ulang via `luang-cli whoami`.
 
@@ -272,8 +314,9 @@ File config auto-dibuat: `~/.luang-cli/config.json`
   "app_url": "https://app.luang.id",
   "key": "lk_…",              // hasil login
   "name": null,               // nama sesi terakhir
+  "telemetry": false,         // konsent lokal telemetry (default OFF)
   "default_provider": null,
-  "providers": { "opencode": { "path": "…", "exec_template": "…" } }
+  "providers": { "opencode": { "path": "…", "exec_template": "…", "model": "sonnet-4" } }
 }
 ```
 
@@ -285,6 +328,9 @@ State runtime (riwayat terlihat / eksekusi): `~/.luang-cli/state.json`.
 | `LUANG_API_URL` | Timpa `api_url` |
 | `LUANG_APP_URL` | Timpa `app_url` |
 | `LUANG_NO_OPEN` | `login` tidak membuka browser otomatis (cetak URL saja) |
+| `LUANG_MODEL` | Model cadangan untuk placeholder `{model}` |
+| `LUANG_NO_WS` | `1`/`true` → matikan mode realtime, paksa polling HTTP |
+| `LUANG_HEARTBEAT_SEC` | Interval heartbeat (detik; default internal) |
 
 Precedence: **flag `--api <url>` → env → config file**.
 
@@ -302,6 +348,9 @@ Precedence: **flag `--api <url>` → env → config file**.
 | Timeout 15 detik | Cek jaringan + `--api https://api.luang.id` |
 | Tabel provider kosong | `provider add <type> --exec_template '…'` manual |
 | `--exec` tak berjalan | Set `provider default <type>` + template harus berisi `{task}` |
+| Menunggu `{model}` (tugas ditunda) | `provider add <type> --model <m>` · env `LUANG_MODEL` · atau set_model dari dashboard |
+| Daemon tak realtime (polling) | Wajar bila WS gagal — cek `LUANG_NO_WS`, proxy/firewall port WS; polling tetap jalan |
+| Telemetry tak terkirim | Butuh konsent **ganda**: `luang-cli telemetry on` + toggle server di dashboard Agents |
 | Daemon boring (tak ada event) | Wajar — ia hanya print KETIKA ada perubahan; coba assign tugas dari dashboard |
 | Mulai bersih total | Hapus `~/.luang-cli/` (config + state) |
 
@@ -328,8 +377,14 @@ luang-cli/
 ├── bin/luang-cli.js    # entrypoint + dispatcher
 ├── lib/
 │   ├── core.js         # config, env, HTTP, provider detect, key util
-│   ├── commands.js     # login/logout/whoami/provider
-│   └── agent.js        # daemon, task CRUD, status, mcp-config
+│   ├── ws.js           # klien WebSocket RFC 6455 (zero-dep) utk mode realtime
+│   ├── commands.js     # login/logout/whoami/telemetry/provider
+│   └── agent.js        # daemon realtime+fallback, task CRUD, status, mcp-config
+├── test/
+│   ├── run-e2e.js      # E2E offline (61 assertion): realtime, fallback, konsent, model
+│   ├── ws-stub.js      # stub server WS (RFC 6455) utk uji offline
+│   ├── http-stub.js    # stub HTTP /agent/me (di-fork, IPC) utk uji konsent
+│   └── bin/opencode    # stub binary provider (tidak pernah panggil claude/gemini asli)
 └── package.json        # bin: luang-cli → bin/luang-cli.js
 ```
 
@@ -338,6 +393,7 @@ Jalankan dari source:
 ```bash
 node bin/luang-cli.js help
 node --check bin/luang-cli.js     # sanity sintaks
+node test/run-e2e.js              # E2E offline penuh (tanpa jaringan/provider asli)
 ```
 
 Publish (owner):
@@ -353,11 +409,12 @@ npm publish --access public --auth-type=legacy --otp=<kode2FA>
 
 ## 🗺 Roadmap
 
+- [x] Realtime WebSocket (daemon + push tugas + perintah `set_model`/`pause`/`resume`) ✅ v0.3.0
+- [x] Telemetry ops-in konsent ganda + `provider --model` / placeholder `{model}` ✅ v0.3.0
 - [ ] MCP tools lanjutan: komentar tugas, subtasks, timesheet
 - [ ] `agent --exec` multi-provider (eksekusi paralel beberapa harness)
 - [ ] Skill installer (Claude Code skill / OpenCode skill yang membungkus luang-cli)
 - [ ] `luang-cli setup` wizard pertama kali (login + provider + tes)
-- [ ] Webhook/SSE realtime (pengganti polling)
 
 ---
 

package/bin/luang-cli.js

@@ -17,7 +17,8 @@ Command:
   logout      Hapus API key tersimpan              luang-cli logout [-y]
   whoami      Info sesi agent, tenant & izin       luang-cli whoami
   provider    Kelola provider CLI coding           luang-cli provider list
-  agent       Daemon heartbeat + polling tugas     luang-cli agent [--interval 5] [--exec]
+  telemetry   Konsent telemetry on|off|status      luang-cli telemetry status
+  agent       Daemon realtime WS + polling tugas   luang-cli agent [--exec]
   task        Kelola tugas (list|create|status)    luang-cli task list
   status      Ringkasan CLI (key, tenant, izin)    luang-cli status
   mcp-config  Snippet konfigurasi MCP klien        luang-cli mcp-config
@@ -74,38 +75,65 @@ Penggunaan:
       ~/.config/opencode atau ~/.opencode (opencode), ~/.gemini (gemini_cli),
       plus which(1) untuk claude, codex, opencode, gemini.
       Bila key ada, hasil langsung disinkron via POST /api/v1/agent/heartbeat.
-  luang-cli provider add <type> [--path P] [--exec_template T]
+  luang-cli provider add <type> [--path P] [--exec_template T] [--model M]
   luang-cli provider remove <type>
   luang-cli provider default <type>
 
 Param exec_template:
-  {task} diganti judul + deskripsi tugas saat mode --exec.
-  Contoh: 'claude -p "{task}"', 'opencode run "{task}"', 'codex exec "{task}"'
+  {task}  diganti judul + deskripsi tugas saat mode --exec.
+  {model} diganti nama model (provider add --model, agent.command set_model dari
+          server, atau env LUANG_MODEL). Bila {model} ada tapi tidak ada model
+          yang bisa dipakai → eksekusi dilewati dengan notifikasi (bukan crash).
+  Contoh: 'opencode run --model "{model}" "{task}"'
 
 Contoh:
-  luang-cli provider add opencode --exec_template 'opencode run "{task}"'
+  luang-cli provider add opencode --exec_template 'opencode run --model "{model}" "{task}"' --model opencode/gpt-5.1-codex
   luang-cli provider default opencode`,
 
-  agent: `luang-cli agent — daemon agent (heartbeat + polling tugas)
+  telemetry: `luang-cli telemetry — konsent telemetry (opt-in, default OFF)
+
+Penggunaan:
+  luang-cli telemetry on|off|status
+
+Perilaku:
+  • on/off mengubah config.telemetry (~/.luang-cli/config.json).
+  • status menampilkan DUA flag yang harus ON bersamaan:
+      lokal  : config.telemetry (di sini)
+      server : agent_keys.telemetry_enabled — nyalakan di dashboard (Agents → Telemetry)
+  • Efektif kirim HANYA bila dua-duanya ON. Archetype frame: telemetry.run via WS
+    realtime (started/completed/failed saat exec) — pakai header X-CLI-Key, bukan JWT.
+  • Satu flag mati → CLI tidak pernah mengirim data run (server juga men-drop).`,
+
+  agent: `luang-cli agent — daemon realtime (WebSocket) + fallback polling
 
 Penggunaan:
   luang-cli agent [--interval N] [--exec]
 
+Mode:
+  1) Realtime WebSocket (utama): wss://<api>/api/v1/agent/ws, auth header
+     X-CLI-Key. Kirim hello {mode:"cli", version, providers}, lalu:
+       • heartbeat frame tiap ≤30s (interval 25s)
+       • menerima task.snapshot / task.assigned / task.updated → tampil live
+       • exec --exec + konfirmasi y/N seperti biasa; status tugas
+         (task.status) & telemetry.run dikirim via WS
+       • menerima agent.command: set_model (menyimpan model provider +
+         command.ack), pause/resume (menghentikan eksekusi; heartbeat tetap)
+  2) Fallback polling HTTP (lama): bila WS gagal (kunci ditolak, server lama,
+     jaringan) atau env LUANG_NO_WS=1 → perilaku polling lama tetap jalan.
+     Telemetry tidak dikirim di mode ini (tidak ada kanal realtime).
+
 Opsi:
-  --interval N   Jeda polling GET /api/v1/agent/tasks (detik, default 5)
+  --interval N   Jeda polling fallback HTTP (detik, default 5)
   --exec         Eksekusi otomatis tugas "To-Do" yang belum dijalankan
+     Sebelum menjalankan: konfirmasi y/N; template dipakai dengan
+     {task} (judul+deskripsi) dan {model} (model provider).
+     exit 0 → done/"selesai"; gagal → review/"gagal exit N".
+     Tiap run juga mengirim telemetry.run started/completed/failed
+     (consent: telemetry on + flag server ON).
 
 Perilaku:
-  • POST /api/v1/agent/heartbeat tiap 30 detik
-  • Polling GET /api/v1/agent/tasks tiap N detik; baris berubah dicetak:
-      [HH:MM:SS] TGS-1  Judul  In Progress  agent=…  note="…"
-  • State: ~/.luang-cli/state.json
-  • --exec: tugas To-Do + default provider punya exec_template berisi {task}
-    perlu konfirmasi y/N lalu dijalankan; sebelum eksekusi status di-set
-    in_progress, lalu done ("selesai", progress_note "exec selesai") bila
-    exit 0; review ("gagal") bila gagal. exec_template kosong/tanpa {task}
-    → cukup notifikasi satu baris.
-  • Ctrl+C menghentikan daemon dengan bersih.`,
+  • State: ~/.luang-cli/state.json · Ctrl+C keluar bersih.
+  • Heartbeat HTTP fallback tiap 30 detik (override: LUANG_HEARTBEAT_SEC).`,
 
   task: `luang-cli task — kelola tugas
 
@@ -147,7 +175,7 @@ config bila sudah login, selain itu placeholder.`,
 
 const VALUE_FLAGS = new Set([
   'name', 'path', 'exec_template', 'interval', 'status', 'title', 'desc',
-  'description', 'priority', 'due', 'note', 'agent-status', 'api',
+  'description', 'priority', 'due', 'note', 'agent-status', 'api', 'model',
 ]);
 
 function parseArgs(argv) {
@@ -224,6 +252,8 @@ async function main() {
       return c.cmdWhoami(rt, args);
     case 'provider':
       return c.cmdProvider(rt, args);
+    case 'telemetry':
+      return c.cmdTelemetry(rt, args);
     case 'agent':
       return ag.cmdAgent(rt, args);
     case 'task':