instar 0.12.18 → 0.12.19

package/.claude/skills/setup-wizard/skill.md

@@ -179,10 +179,11 @@ Present:
 > What would you like to change?
 
 1. **"Update Telegram setup"** → Jump to Phase 3
-2. **"Change agent personality"** → Jump to Phase 2c
-3. **"Add a user"** → New User Flow
-4. **"View current config"** → Display scenario and settings
-5. **"Something else"** → Free-form request
+2. **"Set up WhatsApp"** → Jump to Phase 4g
+3. **"Change agent personality"** → Jump to Phase 2c
+4. **"Add a user"** → New User Flow
+5. **"View current config"** → Display scenario and settings
+6. **"Something else"** → Free-form request
 
 ---
 
@@ -1110,6 +1111,20 @@ mkdir -p .instar/state/sessions .instar/state/jobs .instar/logs
         "pollIntervalMs": 2000,
         "stallTimeoutMinutes": 5
       }
+    },
+    {
+      "type": "whatsapp",
+      "enabled": true,
+      "config": {
+        "backend": "baileys | business-api",
+        "authorizedNumbers": ["+1XXXXXXXXXX"],
+        "requireConsent": false,
+        "businessApi": {
+          "phoneNumberId": "<from Meta Developer Console>",
+          "accessToken": "<from Meta Developer Console>",
+          "webhookVerifyToken": "<random string you choose>"
+        }
+      }
     }
   ],
   "monitoring": {
@@ -1159,6 +1174,132 @@ Then make it executable:
 chmod +x .claude/scripts/telegram-reply.sh
 ```
 
+### 4g. WhatsApp Setup (Optional)
+
+**WhatsApp is optional.** Unlike Telegram, WhatsApp is an additional communication channel — not the primary interface. Only offer it after Telegram is configured.
+
+Present:
+
+> **Want to add WhatsApp as a second channel?**
+>
+> WhatsApp lets you talk to your agent from your phone's default messaging app. It works alongside Telegram — you'll get cross-platform alerts if either channel disconnects.
+>
+> 1. Yes, set up WhatsApp
+> 2. Skip for now
+>
+> Type a number.
+
+If they choose to skip, move to Phase 4.5. If they want WhatsApp:
+
+#### Step 4g-1: Choose Backend
+
+Present:
+
+> WhatsApp has two connection modes:
+>
+> 1. **Personal (Baileys)** — connects through WhatsApp Web. Works on any machine, no server setup needed. Best for personal use and local development.
+> 2. **Business API** — uses Meta's official Cloud API. Requires a Meta Developer account and a publicly accessible server for webhooks. Best for production deployments.
+>
+> Which one fits your setup?
+
+**If they choose Baileys:**
+
+> Great — Baileys connects through WhatsApp Web, just like scanning a QR code.
+>
+> I need your phone number to authorize messages. Only messages from this number will be processed — everything else is ignored.
+
+Collect their phone number (plain text, NOT AskUserQuestion). Format it with country code (+1XXXXXXXXXX).
+
+Write the config:
+```bash
+node -e "
+const fs = require('fs');
+const p = '<project_dir>/.instar/config.json';
+const c = JSON.parse(fs.readFileSync(p, 'utf-8'));
+c.messaging = c.messaging || [];
+c.messaging.push({
+  type: 'whatsapp',
+  enabled: true,
+  config: {
+    backend: 'baileys',
+    authorizedNumbers: ['<PHONE_NUMBER>'],
+    requireConsent: false
+  }
+});
+fs.writeFileSync(p, JSON.stringify(c, null, 2));
+"
+```
+
+Then tell the user:
+
+> WhatsApp is configured. When you start your agent, it will show a pairing code in the logs. Open WhatsApp on your phone → Settings → Linked Devices → Link a Device, and enter the code.
+>
+> You can also pair later with: `instar whatsapp connect`
+
+**If they choose Business API:**
+
+> The Business API needs three things from your Meta Developer Console:
+> 1. **Phone Number ID** — the ID of your WhatsApp Business phone number
+> 2. **Access Token** — a permanent token from System Users
+> 3. **Webhook Verify Token** — a random string you choose (I can generate one)
+>
+> Do you have a Meta Developer account set up? If not, I can walk you through it, or you can switch to Baileys for now.
+
+If they want to proceed, collect:
+- Phone Number ID (plain text)
+- Access Token (plain text — will be stored in config)
+- Webhook Verify Token (offer to generate: `node -e "console.log(require('crypto').randomBytes(16).toString('hex'))"`)
+- Their WhatsApp phone number for authorization
+
+Check if the server has a public URL:
+
+> Does your server have a public URL? The Business API sends webhooks to your server — it needs to be reachable from the internet.
+>
+> 1. Yes, my server is public (enter URL)
+> 2. No, I'm on a local machine
+>
+> If local: "For local development, I'd recommend switching to Baileys — it works without any server setup. The Business API is designed for cloud deployments. Want to switch to Baileys instead?"
+
+Write the config:
+```bash
+node -e "
+const fs = require('fs');
+const p = '<project_dir>/.instar/config.json';
+const c = JSON.parse(fs.readFileSync(p, 'utf-8'));
+c.messaging = c.messaging || [];
+c.messaging.push({
+  type: 'whatsapp',
+  enabled: true,
+  config: {
+    backend: 'business-api',
+    authorizedNumbers: ['<PHONE_NUMBER>'],
+    requireConsent: false,
+    businessApi: {
+      phoneNumberId: '<PHONE_NUMBER_ID>',
+      accessToken: '<ACCESS_TOKEN>',
+      webhookVerifyToken: '<VERIFY_TOKEN>'
+    }
+  }
+});
+fs.writeFileSync(p, JSON.stringify(c, null, 2));
+"
+```
+
+Tell the user the webhook URL to configure in Meta Developer Console:
+
+> Configure your webhook in the Meta Developer Console:
+> - **URL**: `https://<your-server>/webhooks/whatsapp`
+> - **Verify Token**: `<VERIFY_TOKEN>`
+> - **Subscribe to**: `messages`
+
+#### Step 4g-2: Cross-Platform Alerts
+
+If both Telegram and WhatsApp are configured, mention:
+
+> Since you have both Telegram and WhatsApp, your agent will automatically alert you on one platform if the other disconnects. If WhatsApp goes down, you'll get a message on Telegram (and vice versa).
+
+No additional config needed — CrossPlatformAlerts wires automatically in `server.ts` when both adapters are present.
+
 ## Phase 4.5: Cloud Backup (Recommended)
 
 **SCENARIO GATE:** If `isMultiMachine=true`, cloud backup was already set up in the multi-machine section of Phase 2. **Skip this phase entirely for Scenarios 2, 4, 6, 7.**

package/dashboard/index.html

@@ -203,6 +203,52 @@
     .empty-state .icon { font-size: 32px; margin-bottom: 12px; opacity: 0.5; }
     .empty-state p { font-size: 13px; line-height: 1.5; }
 
+    /* WhatsApp QR panel */
+    .wa-qr-panel {
+      position: fixed;
+      top: 50%;
+      left: 50%;
+      transform: translate(-50%, -50%);
+      background: var(--bg-panel);
+      border: 1px solid var(--border);
+      border-radius: 12px;
+      padding: 24px;
+      z-index: 1000;
+      text-align: center;
+      min-width: 320px;
+      box-shadow: 0 8px 32px rgba(0,0,0,0.6);
+    }
+    .wa-qr-panel h3 { color: var(--text-bright); margin-bottom: 8px; }
+    .wa-qr-panel p { color: var(--text-dim); font-size: 13px; margin-bottom: 16px; }
+    .wa-qr-panel canvas { border-radius: 8px; background: #fff; padding: 12px; }
+    .wa-qr-panel .wa-connected {
+      color: var(--accent);
+      font-size: 14px;
+      padding: 32px 0;
+    }
+    .wa-qr-panel .wa-close {
+      position: absolute; top: 8px; right: 12px;
+      background: none; border: none; color: var(--text-dim);
+      font-size: 18px; cursor: pointer;
+    }
+    .wa-qr-panel .wa-close:hover { color: var(--text-bright); }
+    .wa-qr-backdrop {
+      position: fixed; inset: 0;
+      background: rgba(0,0,0,0.5);
+      z-index: 999;
+    }
+
+    .wa-status-btn {
+      background: none; border: 1px solid var(--border);
+      color: var(--text-dim); padding: 4px 10px; border-radius: 6px;
+      cursor: pointer; font-size: 12px; margin-right: 8px;
+      display: none;
+    }
+    .wa-status-btn:hover { border-color: var(--accent-dim); color: var(--text); }
+    .wa-status-btn.needs-qr { border-color: var(--orange); color: var(--orange); animation: pulse 2s infinite; }
+    .wa-status-btn.connected { border-color: var(--accent-dim); color: var(--accent); }
+    @keyframes pulse { 0%,100% { opacity: 1; } 50% { opacity: 0.5; } }
+
     /* Main panel */
     .main {
       display: flex;
@@ -578,6 +624,7 @@
         <span class="logo">&#x1F990;</span>
         <h1>Instar Dashboard</h1>
       </div>
+      <button class="wa-status-btn" id="waStatusBtn" onclick="toggleQrPanel()">WhatsApp</button>
       <div class="status-badge" id="connStatus">
         <span class="dot"></span>
         <span id="connText">Connected</span>
@@ -633,6 +680,16 @@
     </main>
   </div>
 
+  <!-- WhatsApp QR panel (hidden by default) -->
+  <div class="wa-qr-backdrop" id="waQrBackdrop" style="display:none" onclick="closeQrPanel()"></div>
+  <div class="wa-qr-panel" id="waQrPanel" style="display:none">
+    <button class="wa-close" onclick="closeQrPanel()">&times;</button>
+    <h3>WhatsApp Connection</h3>
+    <p id="waQrMsg">Scan this QR code with WhatsApp to connect</p>
+    <div id="waQrContainer"></div>
+  </div>
+
+  <script src="https://cdn.jsdelivr.net/npm/qrcode@1.5.4/build/qrcode.min.js"></script>
   <script src="https://cdn.jsdelivr.net/npm/@xterm/xterm@5.5.0/lib/xterm.min.js"></script>
   <script src="https://cdn.jsdelivr.net/npm/@xterm/addon-fit@0.10.0/lib/addon-fit.min.js"></script>
   <script>
@@ -681,6 +738,7 @@
             document.getElementById('authOverlay').style.display = 'none';
             document.getElementById('app').style.display = 'grid';
             connectWebSocket();
+            startWaPolling();
           } else {
             showAuthError('Incorrect PIN');
           }
@@ -704,6 +762,7 @@
             document.getElementById('authOverlay').style.display = 'none';
             document.getElementById('app').style.display = 'grid';
             connectWebSocket();
+            startWaPolling();
           }
         })
         .catch(() => {});
@@ -1021,6 +1080,102 @@
       return div.innerHTML;
     }
 
+    // ── WhatsApp QR ────────────────────────────────────────────
+    let waQrInterval = null;
+    let waQrVisible = false;
+    let waConfigured = false;
+
+    function startWaPolling() {
+      if (waQrInterval) return;
+      pollWaQr(); // Immediate first poll
+      waQrInterval = setInterval(pollWaQr, 3000);
+    }
+
+    function stopWaPolling() {
+      if (waQrInterval) {
+        clearInterval(waQrInterval);
+        waQrInterval = null;
+      }
+    }
+
+    function pollWaQr() {
+      if (!token) return;
+      fetch('/whatsapp/qr', { headers: { 'Authorization': `Bearer ${token}` } })
+        .then(r => {
+          if (r.status === 503) { waConfigured = false; updateWaButton(); return null; }
+          if (!r.ok) return null;
+          waConfigured = true;
+          return r.json();
+        })
+        .then(data => {
+          if (!data) return;
+          updateWaButton(data);
+          if (waQrVisible) renderQrPanel(data);
+        })
+        .catch(() => {});
+    }
+
+    function updateWaButton(data) {
+      const btn = document.getElementById('waStatusBtn');
+      if (!waConfigured) { btn.style.display = 'none'; return; }
+      btn.style.display = 'inline-block';
+      if (data && data.qr) {
+        btn.className = 'wa-status-btn needs-qr';
+        btn.textContent = 'WhatsApp: Scan QR';
+      } else if (data && data.state === 'connected') {
+        btn.className = 'wa-status-btn connected';
+        btn.textContent = 'WhatsApp: ' + (data.phoneNumber || 'Connected');
+      } else if (data) {
+        btn.className = 'wa-status-btn';
+        btn.textContent = 'WhatsApp: ' + (data.state || 'Unknown');
+      }
+    }
+
+    function toggleQrPanel() {
+      waQrVisible ? closeQrPanel() : openQrPanel();
+    }
+
+    function openQrPanel() {
+      waQrVisible = true;
+      document.getElementById('waQrBackdrop').style.display = 'block';
+      document.getElementById('waQrPanel').style.display = 'block';
+      pollWaQr(); // Fresh data
+    }
+
+    function closeQrPanel() {
+      waQrVisible = false;
+      document.getElementById('waQrBackdrop').style.display = 'none';
+      document.getElementById('waQrPanel').style.display = 'none';
+    }
+
+    function renderQrPanel(data) {
+      const container = document.getElementById('waQrContainer');
+      const msg = document.getElementById('waQrMsg');
+
+      if (data.state === 'connected') {
+        msg.textContent = 'Connected to ' + (data.phoneNumber || 'WhatsApp');
+        container.innerHTML = '<div class="wa-connected">Connected</div>';
+        return;
+      }
+
+      if (data.qr) {
+        msg.textContent = 'Scan this QR code with WhatsApp to connect';
+        container.innerHTML = '';
+        if (typeof QRCode !== 'undefined') {
+          const canvas = document.createElement('canvas');
+          container.appendChild(canvas);
+          QRCode.toCanvas(canvas, data.qr, { width: 256, margin: 1 }, function(err) {
+            if (err) container.innerHTML = '<p style="color:var(--red)">Failed to render QR</p>';
+          });
+        } else {
+          container.innerHTML = '<p style="color:var(--text-dim)">QR library not loaded</p>';
+        }
+      } else {
+        msg.textContent = 'WhatsApp status: ' + (data.state || 'disconnected');
+        container.innerHTML = '<p style="color:var(--text-dim)">Waiting for QR code...</p>';
+      }
+    }
+
     // ── Keyboard shortcuts ───────────────────────────────────
     document.addEventListener('keydown', (e) => {
       // Ctrl+C when terminal focused but not input

package/dist/cli.js

@@ -277,6 +277,11 @@ program
     .option('--user <user>', 'User name (non-interactive)')
     .option('--telegram-token <token>', 'Telegram bot token (non-interactive)')
     .option('--telegram-group <group>', 'Telegram group/chat ID (non-interactive)')
+    .option('--whatsapp-backend <backend>', 'WhatsApp backend: baileys or business-api (non-interactive)')
+    .option('--whatsapp-phone <phone>', 'WhatsApp authorized phone number (non-interactive)')
+    .option('--whatsapp-phone-number-id <id>', 'Business API phone number ID (non-interactive)')
+    .option('--whatsapp-access-token <token>', 'Business API access token (non-interactive)')
+    .option('--whatsapp-verify-token <token>', 'Business API webhook verify token (non-interactive)')
     .option('--scenario <number>', 'Scenario number 1-8 (non-interactive)')
     .action(async (opts) => {
     const [major, minor] = process.versions.node.split('.').map(Number);
@@ -318,6 +323,22 @@ addCmd
     .option('--credentials-file <path>', 'Path to Google OAuth credentials JSON file')
     .option('--token-file <path>', 'Path to store Gmail auth token')
     .action((opts) => addEmail(opts));
+addCmd
+    .command('whatsapp')
+    .description('Add WhatsApp messaging adapter')
+    .option('--backend <backend>', 'Backend: baileys (free, QR auth) or business-api (paid, Meta API)', 'baileys')
+    .option('--auth-method <method>', 'Auth method: qr (scan code) or pairing-code (8-digit code)', 'qr')
+    .option('--phone <number>', 'Phone number for pairing code auth (E.164 format: +1234567890)')
+    .option('--authorized <numbers>', 'Comma-separated authorized phone numbers (E.164). Empty = allow all.')
+    .option('--encrypt', 'Encrypt auth credentials at rest (recommended)')
+    .option('--phone-number-id <id>', 'Meta Phone Number ID (Business API)')
+    .option('--access-token <token>', 'Meta access token (Business API)')
+    .option('--webhook-verify-token <token>', 'Webhook verification token (Business API)')
+    .option('--webhook-port <port>', 'Webhook port if different from server port (Business API)', parseInt)
+    .action(async (opts) => {
+    const { addWhatsApp } = await import('./commands/whatsapp.js');
+    return addWhatsApp(opts);
+});
 addCmd
     .command('sentry')
     .description('Add Sentry error monitoring')
@@ -1140,6 +1161,36 @@ program
     .description('Diagnose multi-machine health and connectivity')
     .option('-d, --dir <path>', 'Project directory')
     .action(doctor);
+// ── Channels ─────────────────────────────────────────────────────
+const channelsCmd = program
+    .command('channels')
+    .description('Manage messaging channel adapters');
+channelsCmd
+    .command('login <adapter>')
+    .description('Authenticate a messaging adapter (e.g., whatsapp)')
+    .option('-d, --dir <path>', 'Project directory')
+    .option('--method <method>', 'Auth method: qr or pairing-code', 'qr')
+    .option('--phone <number>', 'Phone number for pairing code auth')
+    .action(async (adapter, opts) => {
+    const { channelLogin } = await import('./commands/whatsapp.js');
+    return channelLogin(adapter, opts);
+});
+channelsCmd
+    .command('doctor [adapter]')
+    .description('Diagnose messaging adapter health')
+    .option('-d, --dir <path>', 'Project directory')
+    .action(async (adapter, opts) => {
+    const { channelDoctor } = await import('./commands/whatsapp.js');
+    return channelDoctor(adapter, opts);
+});
+channelsCmd
+    .command('status')
+    .description('Show status of all configured messaging adapters')
+    .option('-d, --dir <path>', 'Project directory')
+    .action(async (opts) => {
+    const { channelStatus } = await import('./commands/whatsapp.js');
+    return channelStatus(opts);
+});
 // ── System Review ────────────────────────────────────────────────
 program
     .command('review')