luang-cli 0.1.0 → 0.3.0

package/lib/agent.js

@@ -1,9 +1,19 @@
 'use strict';
 
-// lib/agent.js — daemon agent, task list/create/status, status ringkas,
-// dan mcp-config. Bagian lanjutan dari lib/commands.js.
-
-const { exec } = require('child_process');
+// lib/agent.js — daemon agent: realtime WebSocket (docs/agent-realtime-ws.md),
+// fallback polling HTTP lama, task list/create/status, status ringkas, mcp-config.
+// Bagian lanjutan dari lib/commands.js.
+
+const { spawn } = require('child_process');
+const pkg = require('../package.json');
+
+// lib/ws bisa gagal dimuat di Node yang sangat tua → daemon tetap jalan via polling.
+let wsLib = null;
+try {
+  wsLib = require('./ws');
+} catch (e) {
+  wsLib = null;
+}
 
 const core = require('./core');
 const c = require('./commands');
@@ -12,8 +22,11 @@ const {
   apiRequest,
   loadState,
   saveState,
+  saveConfig,
   collectProviders,
+  heartbeatProviders,
   DEFAULT_TEMPLATES,
+  DISPLAY_NAMES,
   STATE_FILE,
   CONFIG_DIR,
   fmtWhen,
@@ -25,6 +38,9 @@ const {
 
 const STATUS_LABELS = { todo: 'To-Do', in_progress: 'In Progress', review: 'Review', done: 'Done' };
 
+const WS_PATH = '/api/v1/agent/ws'; // kontrak: docs/agent-realtime-ws.md §1
+const REALTIME_GUARD_MS = 12000;    // beri waktu beberapa percobaan WS sebelum fallback
+
 // ── agent (daemon) ───────────────────────────────────────────────────────────
 
 function stampNow() {
@@ -41,22 +57,42 @@ function taskIdFingerprint(t) {
 function printTaskLine(t, tag) {
   const code = c.taskIdOf(t) || '?';
   let tail = '';
-  if (t.agent_status) tail += `agent=${t.agent_status}`;
-  if (t.agent_progress_note) tail += (tail ? ' ' : '') + `note="${t.agent_progress_note}"`;
-  console.log(`[${stampNow()}] ${code}  ${trunc(t.title, 40)}  ${t.status || '-'}  ${tail}${tag ? `  ${trunc(tag, 20)}` : ''}`);
+  if (t.agent_status) tail += `[${t.agent_status}]`;
+  if (t.agent_progress_note) tail += (tail ? ' ' : '') + t.agent_progress_note;
+  const stamp = tag ? `  (${stampNow()} ${trunc(tag, 16)})` : '';
+  console.log(`${code}  ${trunc(t.title, 36)}  ${t.status || '-'}  ${tail}${stamp}`.replace(/\s+$/, ''));
+}
+
+// Masukkan satu tugas ke cache state; true bila berubah (sesuai fingerprint).
+function ingestTaskIntoState(t, state) {
+  const id = c.taskIdOf(t);
+  if (!id) return false;
+  const fp = taskIdFingerprint(t);
+  const cur = t.agent_updated_at || t.updated_at || null;
+  const prev = state.tasks[id];
+  const changed = !prev || prev.fp !== fp || (!prev.fp && prev.updated_at !== cur);
+  if (changed) state.tasks[id] = { updated_at: cur, fp, title: t.title, status: t.status };
+  return changed;
 }
 
-function buildExecCommand(tpl, taskText) {
+function buildExecCommand(tpl, taskText, rawModel) {
   if (!tpl || !tpl.includes('{task}')) return null;
+  let t = tpl;
+  if (t.includes('{model}')) {
+    // {model} diisi dari model provider (config/agent.command), fallback env LUANG_MODEL.
+    const model = String(rawModel || process.env.LUANG_MODEL || '').trim();
+    if (!model || !/^[\w.:+/-]+$/.test(model)) return null; // tanpa model → pemanggil menampilkan notifikasi
+    t = t.split('{model}').join(model);
+  }
   let q;
-  if (tpl.includes('"{task}"')) {
+  if (t.includes('"{task}"')) {
     q = taskText.replace(/(["`\\$])/g, '\\$1'); // escape untuk kutip ganda
-  } else if (tpl.includes("'{task}'")) {
+  } else if (t.includes("'{task}'")) {
     q = taskText.replace(/'/g, `'\\''`); // escape untuk kutip tunggal
   } else {
     q = taskText.replace(/(["`\\$\n])/g, ' '); // {task} tanpa kutip → rapikan
   }
-  return tpl.replaceAll('{task}', q);
+  return t.replaceAll('{task}', q);
 }
 
 function runExecChild(cmd, setChild) {
@@ -64,13 +100,18 @@ function runExecChild(cmd, setChild) {
   return new Promise((resolve) => {
     let child = null;
     try {
-      child = exec(cmd, { maxBuffer: 8 * 1024 * 1024, timeout: EXEC_TIMEOUT_MS, windowsHide: true });
+      // stdio inherit → output provider (mis. "opencode run") tampil live di terminal.
+      child = spawn(cmd, [], { shell: true, stdio: 'inherit', windowsHide: true });
     } catch (e) {
       resolve(1);
       return;
     }
     if (setChild) setChild(child);
+    const killer = setTimeout(() => {
+      try { child.kill('SIGKILL'); } catch (e) { /* abaikan */ }
+    }, EXEC_TIMEOUT_MS);
     const fin = (code) => {
+      clearTimeout(killer);
       if (setChild) setChild(null);
       resolve(typeof code === 'number' ? code : 1);
     };
@@ -79,12 +120,119 @@ function runExecChild(cmd, setChild) {
   });
 }
 
-async function tryExecTask(rt, tasks, state, execCfg, current) {
+// ── Kanal transport ────────────────────────────────────────────────────────────
+// 'ws' → kirim via frame WS (task.status / command.ack / telemetry.run)
+// 'http' → perilaku lama: task status lewat POST /agent/tasks/:ref/status
+
+function makeConsent(cfg) {
+  return {
+    local: cfg.telemetry === true, // config.telemetry — opt-in lokal
+    server: null,                  // telemetry_enabled dari hello.ok (server)
+    noticed: false,
+  };
+}
+
+// Pemberitahuan konsent: sekali saja per sesi daemon (spek: never send + notice).
+function noticeConsentOnce(consent) {
+  if (consent.noticed) return;
+  consent.noticed = true;
+  const l = consent.local === true ? 'lokal ✅' : 'lokal ❌ (luang-cli telemetry on)';
+  const s =
+    consent.server === true
+      ? 'server ✅'
+      : consent.server === false
+        ? 'server ❌ (nyalakan Telemetry di dashboard Agents)'
+        : 'server ? (info belum diterima)';
+  console.log(`ℹ️  Telemetry TIDAK dikirim (${l} · ${s}) — consent ganda harus ON bersamaan.`);
+}
+
+function tokensMaybe(cfg) {
+  const out = {};
+  const pick = (envName, cfgVal) => {
+    const e = process.env[envName];
+    if (e !== undefined && String(e).trim() !== '') {
+      const n = Number(e);
+      if (Number.isFinite(n)) return n;
+    }
+    if (typeof cfgVal === 'number' && Number.isFinite(cfgVal)) return cfgVal;
+    return null;
+  };
+  const tin = pick('LUANG_TOKENS_IN', cfg.tokens_in);
+  const tout = pick('LUANG_TOKENS_OUT', cfg.tokens_out);
+  if (tin !== null) out.tokens_in = tin;
+  if (tout !== null) out.tokens_out = tout;
+  return out;
+}
+
+function makeChannel(kind, opts) {
+  const { rt, ws, consent } = opts;
+  const ch = {
+    kind,
+    rt,
+    ws,
+    consent,
+    paused: false, // dari agent.command pause/resume
+    latestTasks: [],
+    execChain: Promise.resolve(),
+    // Update status tugas; label dipakai untuk pesan error HTTP mode saja.
+    sendStatus(code, body, label) {
+      if (kind === 'ws' && this.ws) {
+        try {
+          this.ws.send({ type: 'task.status', ts: Date.now(), data: { ref: String(code), ...body } });
+        } catch (e) {
+          console.error(`⚠️  Gagal kirim task.status: ${e.message}`);
+        }
+        return;
+      }
+      apiRequest(this.rt, 'POST', `/api/v1/agent/tasks/${encodeURIComponent(String(code))}/status`, { body })
+        .catch((e) => console.error(`⚠️  Gagal ${label || 'update status tugas'}: ${e.message}`));
+    },
+    ack(commandId, ok, message) {
+      if (kind !== 'ws' || !this.ws) return;
+      const data = { command_id: commandId, ok: !!ok };
+      if (message) data.message = String(message);
+      try {
+        this.ws.send({ type: 'command.ack', ts: Date.now(), data });
+      } catch (e) {
+        console.error(`⚠️  Gagal kirim command.ack: ${e.message}`);
+      }
+    },
+    // Telemetry.run — HANYA realtime; tanpa consent → didrop di CLI + notice sekali.
+    telemetry(payload) {
+      if (kind !== 'ws') return;
+      if (!(consent.local === true && consent.server === true)) {
+        noticeConsentOnce(consent);
+        return;
+      }
+      try {
+        this.ws.send({ type: 'telemetry.run', ts: Date.now(), data: payload });
+      } catch (e) {
+        console.error(`⚠️  Gagal kirim telemetry.run: ${e.message}`);
+      }
+    },
+  };
+  return ch;
+}
+
+async function tryExecTask(ch, tasks, state, execCfg, current) {
+  if (ch.paused) return false; // di-pause server → exec tidak dijalankan
   const cand = tasks.find((t) => c.statusInputNorm(t.status) === 'todo' && !state.executed[c.taskIdOf(t)]);
   if (!cand) return false;
   const code = c.taskIdOf(cand);
   const taskText = `${cand.title || ''}${cand.description ? ' — ' + cand.description : ''}`;
-  const cmdStr = buildExecCommand(execCfg.template, taskText);
+  if (execCfg.template && execCfg.template.includes('{model}')) {
+    const model = String(execCfg.model || process.env.LUANG_MODEL || '').trim();
+    if (!model) {
+      // template memuat {model} tapi tidak ada model yang bisa dipakai → dilewati dengan notifikasi
+      state.executed[code] = true;
+      saveState(state);
+      console.log(
+        `⏭  ${code} menunggu (To-Do) — template memuat {model} tapi belum ada model. Set: provider add ${execCfg.type || '<type>'} --model <m>, server agent.command set_model, atau env LUANG_MODEL.`,
+      );
+      return true;
+    }
+  }
+  const cmdStr = buildExecCommand(execCfg.template, taskText, execCfg.model);
   if (!cmdStr) {
     // exec_template kosong / tanpa {task} → hanya notifikasi satu baris (spec)
     state.executed[code] = true; // tandai agar tidak nag lagi
@@ -107,78 +255,296 @@ async function tryExecTask(rt, tasks, state, execCfg, current) {
     saveState(state);
     return true;
   }
-  // Spesifikasi: mulai → body {status:"in_progress"} saja.
-  try {
-    await apiRequest(rt, 'POST', `/api/v1/agent/tasks/${encodeURIComponent(code)}/status`, {
-      body: { status: 'in_progress' },
-    });
-  } catch (e) {
-    console.error(`⚠️  Gagal set in_progress: ${e.message}`);
-  }
+  const model = String(execCfg.model || process.env.LUANG_MODEL || '') || undefined;
+  const toks = tokensMaybe(ch.rt.cfg);
+  const baseTel = { task_ref: code, task_code: code, provider: execCfg.type, model };
+  const t0 = Date.now();
+  // Spesifikasi: sebelum eksekusi, tandai in_progress dengan agent_status "menjalankan".
+  ch.sendStatus(code, { status: 'in_progress', agent_status: 'menjalankan' }, 'set in_progress');
+  ch.telemetry({ ...baseTel, status: 'started', ...toks });
   const exitCode = await runExecChild(cmdStr, (child) => {
     current.child = child;
   });
   const ok = exitCode === 0;
-  // Spesifikasi: exit 0 → {status:"done", agent_status:"selesai", progress_note:"exec selesai"};
-  // selain itu → {status:"review", agent_status:"gagal"}.
+  // Spesifikasi: exit 0 → {status:"done", agent_status:"selesai", progress_note:"exec exit 0"};
+  // selain itu → {status:"review", agent_status:"gagal", progress_note:"exit code N"}.
+  ch.sendStatus(
+    code,
+    ok
+      ? { status: 'done', agent_status: 'selesai', progress_note: 'exec exit 0' }
+      : { status: 'review', agent_status: 'gagal', progress_note: `exit code ${exitCode}` },
+    'update status tugas',
+  );
+  ch.telemetry({
+    ...baseTel,
+    status: ok ? 'completed' : 'failed',
+    exit_code: exitCode,
+    duration_ms: Date.now() - t0,
+    ...toks,
+  });
+  console.log(ok ? `✅ ${code} selesai (exit 0)` : `⚠️  ${code} gagal (exit ${exitCode}) → review`);
+  return true;
+}
+
+// Rantai eksekusi: event datang serentak → anak antre, tidak dobel.
+function runExecMaybe(ch, state, execCfg, current) {
+  ch.execChain = ch.execChain
+    .then(() => tryExecTask(ch, ch.latestTasks, state, execCfg, current))
+    .then((acted) => {
+      if (acted) saveState(state);
+    })
+    .catch(() => {});
+  return ch.execChain;
+}
+
+// ── Encode waktu/config untuk WS ──────────────────────────────────────────────
+
+function wsRealtimeUrl(apiUrl) {
   try {
-    await apiRequest(rt, 'POST', `/api/v1/agent/tasks/${encodeURIComponent(code)}/status`, {
-      body: ok
-        ? { status: 'done', agent_status: 'selesai', progress_note: 'exec selesai' }
-        : { status: 'review', agent_status: 'gagal' },
-    });
+    const u = new URL(String(apiUrl));
+    if (u.protocol !== 'https:' && u.protocol !== 'http:') return null;
+    u.protocol = u.protocol === 'https:' ? 'wss:' : 'ws:';
+    let p = u.pathname.replace(/\/+$/, '');
+    p = p.endsWith('/api/v1') ? p + '/agent/ws' : p + '/api/v1/agent/ws';
+    u.pathname = p;
+    u.search = '';
+    return u.toString();
   } catch (e) {
-    console.error(`⚠️  Gagal update status tugas: ${e.message}`);
+    return null;
   }
-  console.log(ok ? `✅ ${code} selesai (exit 0)` : `⚠️  ${code} gagal (exit ${exitCode}) → review`);
-  return true;
 }
 
-async function cmdAgent(rt, args) {
-  if (!rt.key) return c.errExit('Belum login — jalankan `luang-cli login` atau set LUANG_KEY.');
-  const flags = args.flags;
-  let intervalSec = Number(flags.interval);
-  if (!intervalSec || intervalSec < 1) intervalSec = 5;
-  if (intervalSec > 3600) intervalSec = 3600;
-  const doExec = flags.exec === true;
+function canRealtime(rt) {
+  if (!wsLib) return false;
+  if (['1', 'true', 'yes'].includes(String(process.env.LUANG_NO_WS || '').toLowerCase())) return false;
+  return !!rt.key && !!wsRealtimeUrl(rt.apiUrl);
+}
 
-  const execCfg = { type: rt.cfg.default_provider, template: null };
-  if (doExec) {
-    const p = collectProviders(rt.cfg).find((x) => x.provider_type === rt.cfg.default_provider);
-    if (p && p.exec_template && p.exec_template.includes('{task}')) {
-      execCfg.template = p.exec_template;
+// providers untuk hello: kontrak WS pakai {type, exec_template?, model?}
+function providersForHello(cfg) {
+  return collectProviders(cfg).map((p) => {
+    const o = { type: p.provider_type };
+    if (p.exec_template) o.exec_template = String(p.exec_template);
+    if (p.model) o.model = String(p.model);
+    return o;
+  });
+}
+
+function hbIntervalMs() {
+  let s = Number(process.env.LUANG_HEARTBEAT_SEC);
+  if (!s || !Number.isFinite(s) || s < 3) s = 25; // WS default 25s (kontrak: ≤30s)
+  return Math.min(Math.floor(s), 60) * 1000;
+}
+
+// agent.command dari server: set_model | pause | resume → command.ack
+function handleAgentCommand(d, ctx) {
+  const { ch, rt, execCfg, state, current } = ctx;
+  const id = d.command_id || 'cmd';
+  const cmd = String(d.command || '').toLowerCase();
+  if (cmd === 'set_model') {
+    const type = d.provider || rt.cfg.default_provider;
+    const model = typeof d.model === 'string' ? d.model.trim() : '';
+    if (!type) {
+      ch.ack(id, false, 'Provider tidak diketahui & default provider belum di-set — jalankan: luang-cli provider default <type>');
+      return;
     }
+    if (!model || !/^[\w.:+/-]+$/.test(model)) {
+      ch.ack(id, false, `Model tidak valid: ${JSON.stringify(d.model)}`);
+      return;
+    }
+    const cur = (rt.cfg.providers && rt.cfg.providers[type]) || {};
+    rt.cfg.providers[type] = {
+      ...cur,
+      provider_type: type,
+      display_name: cur.display_name || DISPLAY_NAMES[type] || type,
+      model,
+    };
+    saveConfig(rt.cfg);
+    if (!execCfg.type || execCfg.type === type) execCfg.model = model;
+    console.log(`🎛  Perintah server: set_model → ${type} = ${model} (tersimpan)`);
+    ch.ack(id, true, `Model "${model}" tersimpan untuk provider ${type}`);
+    runExecMaybe(ch, state, execCfg, current); // tugas pending mungkin baru bisa jalan
+  } else if (cmd === 'pause') {
+    ch.paused = true;
+    console.log('⏸  Perintah server: PAUSE — eksekusi ditunda (heartbeat tetap).');
+    ch.ack(id, true, 'paused');
+  } else if (cmd === 'resume') {
+    ch.paused = false;
+    console.log('▶️  Perintah server: RESUME — eksekusi tugas dilanjutkan.');
+    ch.ack(id, true, 'resumed');
+    runExecMaybe(ch, state, execCfg, current);
+  } else {
+    ch.ack(id, false, `Perintah tidak dikenal: ${cmd}`);
   }
+}
 
-  const state = loadState();
-  const current = { child: null };
-  let running = true;
+// ── Mode realtime (WS) ────────────────────────────────────────────────────────
 
-  console.log('🤖 Agent Luang aktif');
+function runAgentRealtime(rt, opts) {
+  const { execCfg, state, current, doExec } = opts;
+  const wsUrl = wsRealtimeUrl(rt.apiUrl);
+  if (!wsUrl) return Promise.resolve('fatal');
+  const ws = new wsLib.WsClient(wsUrl, { headers: { 'X-CLI-Key': rt.key } });
+  current.ws = ws;
+  const consent = makeConsent(rt.cfg);
+  const ch = makeChannel('ws', { rt, ws, consent });
+
+  console.log('🤖 Agent Luang aktif (realtime WebSocket)');
+  console.log(`   WS        : ${wsUrl}`);
   console.log(`   API       : ${rt.apiUrl}`);
-  console.log(`   Poll      : setiap ${intervalSec} detik · heartbeat setiap 30 detik`);
-  console.log(`   Eksekusi  : ${doExec ? (execCfg.template ? `aktif (${execCfg.type})` : 'diminta tapi nonaktif — default provider belum punya exec_template berisi {task}') : 'nonaktif'}`);
+  console.log(`   Heartbeat : frame tiap ≤30s (interval ${Math.round(hbIntervalMs() / 1000)}s)`);
+  console.log(`   Eksekusi  : ${doExec ? (execCfg.template ? `aktif (${execCfg.type}${execCfg.model ? ` · model ${execCfg.model}` : ''})` : 'diminta tapi nonaktif — default provider belum punya exec_template berisi {task}') : 'nonaktif'}`);
+  console.log(`   Telemetry : ${consent.local === true ? 'config ON (butuh flag server ON juga)' : 'OFF (luang-cli telemetry on)'}`);
   console.log(`   State     : ${STATE_FILE}`);
   console.log('   Hentikan  : Ctrl+C');
   console.log('');
+  console.log('⏳ Menunggu handshake realtime…');
 
-  process.on('SIGINT', () => {
-    running = false;
-    if (current.child) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let established = false;
+    let firstSync = true;
+    let hbTimer = null;
+
+    const settle = (v) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(guard);
+      if (hbTimer) {
+        clearInterval(hbTimer);
+        hbTimer = null;
+      }
+      if (v !== 'ok') ws.close(); // beres: jangan reconnect setelah fallback
+      resolve(v);
+    };
+
+    const guard = setTimeout(() => {
+      if (!established) settle('fallback');
+    }, REALTIME_GUARD_MS);
+
+    ws.on('open', () => {
       try {
-        current.child.kill('SIGINT');
+        ws.send({ type: 'hello', ts: Date.now(), data: { mode: 'cli', version: pkg.version, providers: providersForHello(rt.cfg) } });
       } catch (e) {
-        // abaikan
+        console.error(`⚠️  Gagal kirim hello: ${e.message}`);
       }
-    }
-    console.log('\n👋 Agent dihentikan.');
-    process.exit(0);
+      if (established) console.log(`🔌 WS terhubung ulang (${stampNow()}) — hello dikirim ulang`);
+    });
+    ws.on('reconnecting', ({ delay, reason }) => {
+      console.log(`🔁 WS terputus (${trunc(String(reason), 40)}) — mencoba ulang dalam ${(delay / 1000).toFixed(1)}s…`);
+    });
+    ws.on('error', () => {
+      // Gagal sambung sebelum/fallback cukup jelas dari fallback notice; setelah isi, event reconnects sudah dicetak.
+    });
+    ws.on('fatal', (e) => {
+      console.error(`❌ WS ditolak server: ${e.message}`);
+      settle('fatal');
+    });
+
+    hbTimer = setInterval(() => {
+      try {
+        ws.send({ type: 'heartbeat', ts: Date.now(), data: {} });
+      } catch (e) {
+        // ws lib mengantre saat reconnect; biarkan
+      }
+    }, hbIntervalMs());
+
+    ws.on('message', (raw) => {
+      let msg;
+      try {
+        msg = JSON.parse(raw);
+      } catch (e) {
+        return; // pesan invalid → abaikan (server yang benar tidak mengirim ini)
+      }
+      if (!msg || typeof msg.type !== 'string') return;
+      const d = msg.data && typeof msg.data === 'object' ? msg.data : {};
+      const ctx = { ch, rt, execCfg, state, current };
+
+      if (msg.type === 'hello.ok') {
+        consent.server = d.telemetry_enabled === true;
+        if (!established) {
+          established = true;
+          clearTimeout(guard);
+          console.log(`🔌 Realtime aktif · key #${d.key_id ?? '-'} · user #${d.user_id ?? '-'}${d.server_time ? ` · server_time ${d.server_time}` : ''}`);
+          console.log('   Event live: task.snapshot / task.assigned / task.updated · agent.command');
+          if (consent.local === true && consent.server === true) {
+            console.log('📈 Telemetry consent ON (lokal ✅ · server ✅) — event run dikirim realtime.');
+          } else {
+            noticeConsentOnce(consent);
+          }
+        }
+        return;
+      }
+      if (!established) return;
+
+      if (msg.type === 'task.snapshot') {
+        const tasks = c.normalizeTaskList(d);
+        let dirty = false;
+        const seen = new Set();
+        for (const t of tasks) {
+          const id = c.taskIdOf(t);
+          if (!id) continue;
+          seen.add(id);
+          if (ingestTaskIntoState(t, state)) {
+            dirty = true;
+            printTaskLine(t, firstSync ? 'sinkron awal' : 'berubah');
+          }
+        }
+        for (const id of Object.keys(state.tasks)) {
+          if (!seen.has(id)) {
+            delete state.tasks[id];
+            dirty = true;
+          }
+        }
+        firstSync = false;
+        ch.latestTasks = tasks;
+        if (dirty) saveState(state);
+        runExecMaybe(ch, state, execCfg, current);
+      } else if (msg.type === 'task.updated' || msg.type === 'task.assigned') {
+        const t = d.task && typeof d.task === 'object' ? d.task : d.id ? d : null;
+        if (!t) return;
+        if (ingestTaskIntoState(t, state)) {
+          printTaskLine(t, msg.type === 'task.assigned' ? 'di-assign' : 'berubah');
+          saveState(state);
+        }
+        const id = c.taskIdOf(t);
+        const i = ch.latestTasks.findIndex((x) => c.taskIdOf(x) === id);
+        if (i >= 0) ch.latestTasks[i] = t;
+        else ch.latestTasks.push(t);
+        runExecMaybe(ch, state, execCfg, current);
+      } else if (msg.type === 'agent.command') {
+        handleAgentCommand(d, ctx);
+      } else if (msg.type === 'error') {
+        console.error(`⚠️  WS server error: ${d.code || '-'} ${trunc(String(d.message || ''), 120)}`);
+      }
+      // heartbeat / agent.online / lainnya diabaikan (bukan untuk CLI)
+    });
+
+    ws.connect();
   });
+}
+
+// ── Mode polling (fallback, perilaku lama) ───────────────────────────────────
+
+async function runAgentPolling(rt, opts) {
+  const { intervalSec, doExec, execCfg, state, current } = opts;
+  const ch = makeChannel('http', { rt });
+  let running = true;
+
+  console.log('🤖 Agent Luang aktif');
+  console.log(`   API       : ${rt.apiUrl}`);
+  console.log(`   Poll      : setiap ${intervalSec} detik · heartbeat setiap 30 detik`);
+  console.log('   Realtime  : nonaktif — polling HTTP (WS gagal/dimatikan)');
+  console.log('   Telemetry : tidak dikirim (mode polling tanpa kanal realtime)');
+  console.log(`   Eksekusi  : ${doExec ? (execCfg.template ? `aktif (${execCfg.type})` : 'diminta tapi nonaktif — default provider belum punya exec_template berisi {task}') : 'nonaktif'}`);
+  console.log(`   State     : ${STATE_FILE}`);
+  console.log('   Hentikan  : Ctrl+C');
+  console.log('');
 
   const heartbeat = async (label) => {
     try {
       await apiRequest(rt, 'POST', '/api/v1/agent/heartbeat', {
-        body: { providers: core.heartbeatProviders(collectProviders(rt.cfg)) },
+        body: { providers: heartbeatProviders(collectProviders(rt.cfg)) },
       });
       console.log(`📡 ${label} terkirim`);
     } catch (e) {
@@ -186,24 +552,26 @@ async function cmdAgent(rt, args) {
     }
   };
 
-  const hbInterval = setInterval(() => {
+  let hbTimer = setInterval(() => {
     if (running) heartbeat('Heartbeat');
-  }, 30000);
+  }, hbIntervalSec() * 1000);
 
   let first = true;
-  while (running) {
+  let runningLoop = true;
+  while (runningLoop) {
     let tasks;
     try {
       const res = await apiRequest(rt, 'GET', '/api/v1/agent/tasks');
       tasks = c.normalizeTaskList(res);
     } catch (e) {
       if (e instanceof ApiError && (e.status === 401 || e.status === 403)) {
-        clearInterval(hbInterval);
+        clearInterval(hbTimer);
+        runningLoop = false;
         console.error(`❌ Key ditolak server (HTTP ${e.status}): ${e.message}`);
         console.error('   Cek: luang-cli whoami · login ulang: luang-cli login');
         return 1;
       }
-      console.error(`⚠️  Poll gagal: ${e.message} — coba lagi dalam ${intervalSec} detik…`);
+      console.log(`⚠️  Poll gagal: ${e.message} — coba lagi dalam ${intervalSec} detik…`);
       await sleep(intervalSec * 1000);
       continue;
     }
@@ -214,21 +582,11 @@ async function cmdAgent(rt, args) {
       const id = c.taskIdOf(t);
       if (!id) continue;
       seen.add(id);
-      const cur = t.agent_updated_at || t.updated_at || null;
-      const fp = taskIdFingerprint(t);
-      const prev = state.tasks[id];
-      // berubah bila tidak ada cache, atau fingerprint (status/agent_status/note/waktu) berbeda
-      const changed =
-        !prev ||
-        prev.fp !== fp ||
-        (!prev.fp && prev.updated_at !== cur);
-      if (changed) {
-        state.tasks[id] = { updated_at: cur, fp, title: t.title, status: t.status };
+      if (ingestTaskIntoState(t, state)) {
         dirty = true;
         printTaskLine(t, first ? 'baru dipantau' : 'berubah');
       }
     }
-    // bersihkan cache untuk tugas yang tak lagi dikirim server
     for (const id of Object.keys(state.tasks)) {
       if (!seen.has(id)) {
         delete state.tasks[id];
@@ -237,18 +595,82 @@ async function cmdAgent(rt, args) {
     }
     first = false;
     if (dirty) saveState(state);
+    ch.latestTasks = tasks;
 
     if (doExec) {
-      const acted = await tryExecTask(rt, tasks, state, execCfg, current);
+      const acted = await tryExecTask(ch, tasks, state, execCfg, current);
       if (acted) saveState(state);
     }
 
     await sleep(intervalSec * 1000);
   }
-  clearInterval(hbInterval);
+  clearInterval(hbTimer);
   return 0;
 }
 
+function hbIntervalSec() {
+  let s = Number(process.env.LUANG_HEARTBEAT_SEC);
+  if (!s || !Number.isFinite(s) || s < 3) s = 30; // HTTP polling: 30s (perilaku lama)
+  return Math.min(Math.floor(s), 3600);
+}
+
+async function cmdAgent(rt, args) {
+  if (!rt.key) return c.errExit('Belum login — jalankan `luang-cli login` atau set LUANG_KEY.');
+  const flags = args.flags;
+  let intervalSec = Number(flags.interval);
+  if (!intervalSec || intervalSec < 1) intervalSec = 5;
+  if (intervalSec > 3600) intervalSec = 3600;
+  const doExec = flags.exec === true;
+
+  const execCfg = { type: rt.cfg.default_provider, template: null, model: null };
+  if (doExec) {
+    const p = collectProviders(rt.cfg).find((x) => x.provider_type === rt.cfg.default_provider);
+    if (p && p.exec_template && p.exec_template.includes('{task}')) execCfg.template = p.exec_template;
+    if (p && p.model) execCfg.model = p.model;
+  }
+
+  const state = loadState();
+  const current = { child: null, ws: null };
+
+  process.on('SIGINT', () => {
+    if (current.child) {
+      try {
+        current.child.kill('SIGINT');
+      } catch (e) {
+        // abaikan
+      }
+    }
+    if (current.ws) {
+      try {
+        current.ws.close();
+      } catch (e) {
+        // abaikan
+      }
+    }
+    console.log('\n👋 Agent dihentikan.');
+    process.exit(0);
+  });
+
+  // 1) Realtime WebSocket — enhancement, bukan syarat (kontrak §5).
+  if (canRealtime(rt)) {
+    const mode = await runAgentRealtime(rt, { doExec, execCfg, state, current });
+    if (mode === 'ok') return 0; // sampai Ctrl+C (process.exit pada handler)
+    console.log('');
+    if (mode === 'fatal') {
+      console.log('❌ Server menolak/menyediakan WS — beralih ke fallback polling HTTP.');
+    } else {
+      console.log('⚠️  WS gagal terhubung dalam batas waktu — beralih ke fallback polling HTTP.');
+    }
+    console.log('');
+  } else if (!wsLib) {
+    console.log('⚠️  lib/ws tidak tersedia di Node ini — beralih ke fallback polling HTTP.');
+    console.log('');
+  }
+
+  // 2) Fallback polling HTTP klasik.
+  return runAgentPolling(rt, { intervalSec, doExec, execCfg, state, current });
+}
+
 // ── task list / create / status ──────────────────────────────────────────────
 
 async function cmdTaskList(rt, args) {
@@ -382,15 +804,18 @@ async function cmdStatus(rt) {
     console.log('   ➡️  Mulai: luang-cli login');
     return 0;
   }
+  let d = null;
   try {
     const me = await apiRequest(rt, 'GET', '/api/v1/agent/me');
-    const d = (me && me.data) || {};
+    d = (me && me.data) || {};
     console.log(`   Sesi : ${d.name || '-'} (${d.key_id || 'key-?'}) · status ${d.status || '-'}`);
     console.log(`   Tenant: ${d.tenant_slug || d.tenant_id || '-'}`);
     console.log(`   Izin : update-tugas ${d.can_update_tasks ? '✅' : '❌'} · buat-tugas ${d.can_create_tasks ? '✅' : '❌'}`);
+    console.log(`   Telemetry: ${c.telemetryConsentLabel(rt.cfg.telemetry === true, d.telemetry_enabled === true)} (ubah lokal: telemetry on|off)`);
     console.log(`   Provider server: ${c.providersLabel(d.providers)}`);
   } catch (e) {
     console.log(`   ⚠️  /me gagal: ${e.message}`);
+    console.log(`   Telemetry: ${c.telemetryConsentLabel(rt.cfg.telemetry === true, null)}`);
   }
   const list = collectProviders(rt.cfg);
   console.log(`   Default provider: ${rt.cfg.default_provider || '(belum di-set)'}`);
@@ -421,4 +846,4 @@ async function cmdMcpConfig(rt) {
   return 0;
 }
 
-module.exports = { cmdAgent, cmdTask, cmdStatus, cmdMcpConfig, buildExecCommand, runExecChild };
+module.exports = { cmdAgent, cmdTask, cmdStatus, cmdMcpConfig, buildExecCommand, runExecChild, wsRealtimeUrl, canRealtime, providersForHello, hbIntervalMs, makeChannel, handleAgentCommand, ingestTaskIntoState };