Agent Zero AI framework
Simplify WhatsApp pairing to one QR-code action
Alessandro0e9ef3727399
diff --git a/plugins/_whatsapp_integration/AGENTS.md b/plugins/_whatsapp_integration/AGENTS.mdindex f1587203a..79ed54f1d 100644--- a/plugins/_whatsapp_integration/AGENTS.md+++ b/plugins/_whatsapp_integration/AGENTS.md@@ -23,10 +23,12 @@## Work Guidance- Coordinate Node bridge changes with Python bridge client and settings UI.+- Pairing starts on one explicit Show QR code action, which enables the draft configuration. Keep QR polling sequential and ignore responses after cancellation or modal cleanup; saving remains owned by the settings wizard.## Verification- Run `node --test tests/test_whatsapp_bridge.mjs` and `pytest tests/test_whatsapp_bridge_manager.py tests/test_whatsapp_number_utils.py tests/test_whatsapp_storage_paths.py` from the repository root.+- Run `node --test tests/test_whatsapp_config_store.mjs` for pairing lifecycle changes; verify the two-column pairing layout and its mobile stack in the WebUI.- Smoke-test dependency install, bridge start, QR pairing, allowed-number filtering, message routing, and replies when practical.## Child DOX Indexdiff --git a/plugins/_whatsapp_integration/README.md b/plugins/_whatsapp_integration/README.mdindex 383ba853b..da6412e6e 100644--- a/plugins/_whatsapp_integration/README.md+++ b/plugins/_whatsapp_integration/README.md@@ -20,10 +20,10 @@ Dependencies are auto-installed on first bridge start if missing.### Configure and pair-1. Enable the plugin in Settings > External > WhatsApp Integration+1. Open Settings > External > WhatsApp Integration2. Configure allowed phone numbers-3. Click Show QR Code and scan with WhatsApp on your phone-4. Send a message from an allowed number to start a chat+3. Click Show QR code, then use WhatsApp > Linked devices > Link a device to scan it. No separate enable step is needed to show the code.+4. Finish the setup wizard to save, then send a message from an allowed number to start a chat5. Use `/project <name>`, `/config <preset>`, or `/send` in WhatsApp to control the active chat directlyThe WhatsApp session persists across restarts in `tmp/whatsapp/session/`. No re-pairing needed unless you disconnect via settings.diff --git a/plugins/_whatsapp_integration/webui/config.html b/plugins/_whatsapp_integration/webui/config.htmlindex 1cb47bb92..f4033e1cf 100644--- a/plugins/_whatsapp_integration/webui/config.html+++ b/plugins/_whatsapp_integration/webui/config.html@@ -45,95 +45,48 @@<template x-if="$store.whatsappConfig.currentStep === 0"><div class="wa-step-panel">- <div class="field">- <div class="field-label">- <div class="field-title">Turn on WhatsApp</div>- <div class="field-description">Enable the local bridge to start.</div>- </div>- <div class="field-control">- <label class="toggle">- <input type="checkbox"- x-model="config.enabled"- @change="$store.whatsappConfig.onEnabledChange()" />- <span class="toggler"></span>- </label>- </div>- </div>-- <template x-if="config.enabled">- <div>- <div class="field">- <div class="field-label">- <div class="field-title">WhatsApp account</div>- <div class="field-description">- <span x-show="!$store.whatsappConfig.disconnectMessage">Click "Show QR code" to pair your WhatsApp account.</span>- <span x-show="$store.whatsappConfig.disconnectMessage"- x-text="$store.whatsappConfig.disconnectMessage"></span>+ <div class="wa-pairing-row">+ <div class="wa-qr-panel">+ <div class="wa-qr-status">Scan to link WhatsApp</div>+ <div class="wa-qr-content">+ <button type="button" class="btn btn-field"+ x-show="!$store.whatsappConfig.qrVisible"+ @click="$store.whatsappConfig.showQr()">Show QR code</button>+ <template x-if="$store.whatsappConfig.qrVisible">+ <div>+ <template x-if="$store.whatsappConfig.qrStatus === 'waiting_scan' && $store.whatsappConfig.qrDataUrl">+ <img :src="$store.whatsappConfig.qrDataUrl" alt="WhatsApp pairing QR code"+ class="wa-qr-image" />+ </template>+ <div role="status" class="wa-qr-message"+ x-show="$store.whatsappConfig.qrStatus !== 'waiting_scan'"+ x-text="$store.whatsappConfig.qrMessage"></div>+ <button type="button" class="btn btn-field"+ x-show="$store.whatsappConfig.qrStatus === 'error'"+ @click="$store.whatsappConfig.showQr()">Try again</button></div>- </div>- <div class="field-control wa-inline-actions">- <button class="btn btn-field" @click="$store.whatsappConfig.showQr()">- Show QR code- </button>- <button class="btn btn-field" @click="$store.whatsappConfig.disconnectAccount()"- :disabled="$store.whatsappConfig.disconnecting">- <span x-show="!$store.whatsappConfig.disconnecting">Disconnect</span>- <span x-show="$store.whatsappConfig.disconnecting">Disconnecting...</span>- </button>- </div>+ </template></div>-- <template x-if="$store.whatsappConfig.qrVisible">- <div class="wa-qr-panel">- <template x-if="$store.whatsappConfig.qrStatus === 'connected'">- <div>- <div class="wa-qr-status ok">Connected</div>- <div class="wa-qr-message" x-text="$store.whatsappConfig.qrMessage"></div>- <button class="btn btn-field" @click="$store.whatsappConfig.hideQr()"- style="margin-top: 12px;">- Close- </button>- </div>- </template>-- <template- x-if="$store.whatsappConfig.qrStatus === 'waiting_scan' && $store.whatsappConfig.qrDataUrl">- <div>- <div class="wa-qr-status">Scan with WhatsApp on your phone</div>- <img :src="$store.whatsappConfig.qrDataUrl" alt="WhatsApp QR Code"- class="wa-qr-image" />- <div class="wa-qr-help">The QR code refreshes automatically.</div>- <button class="btn btn-field" @click="$store.whatsappConfig.hideQr()"- style="margin-top: 12px;">- Cancel- </button>- </div>- </template>-- <template- x-if="$store.whatsappConfig.qrStatus !== 'connected' && !($store.whatsappConfig.qrStatus === 'waiting_scan' && $store.whatsappConfig.qrDataUrl)">- <div>- <div class="wa-qr-status"- x-text="$store.whatsappConfig.qrMessage || 'Connecting...'"></div>- <div class="wa-qr-help"- x-show="$store.whatsappConfig.qrStatus !== 'error'">- Please wait...</div>- <div class="wa-qr-help error"- x-show="$store.whatsappConfig.qrStatus === 'error'"- x-text="$store.whatsappConfig.qrMessage"></div>- <button class="btn btn-field" @click="$store.whatsappConfig.hideQr()"- style="margin-top: 12px;">- Cancel- </button>- </div>- </template>- </div>- </template>+ <button type="button" class="btn btn-field" x-show="$store.whatsappConfig.qrVisible"+ @click="$store.whatsappConfig.hideQr()"+ x-text="$store.whatsappConfig.qrStatus === 'connected' ? 'Close' : 'Hide QR code'"></button>+ </div>+ <div class="wa-pairing-instructions">+ <div class="wa-qr-status">Link your account</div>+ <ol class="wa-pairing-steps">+ <li>Click <strong>Show QR code</strong>.</li>+ <li>Open WhatsApp on your phone and go to <strong>Settings → Linked devices</strong> (Android: <strong>⋮ → Linked devices</strong>).</li>+ <li>Tap <strong>Link a device</strong> and scan the code.</li>+ </ol>+ <p class="wa-qr-help">The QR code refreshes automatically while it is open.</p>+ <p class="wa-qr-help">Choose who can reach your agent below, then finish setup to save.</p>+ <button type="button" class="btn btn-field" x-show="config.enabled"+ @click="$store.whatsappConfig.disconnectAccount()"+ :disabled="$store.whatsappConfig.disconnecting"+ x-text="$store.whatsappConfig.disconnecting ? 'Disconnecting...' : 'Disconnect account'"></button>+ <div role="status" class="wa-qr-help" x-show="$store.whatsappConfig.disconnectMessage"+ x-text="$store.whatsappConfig.disconnectMessage"></div></div>- </template>-- <div class="wa-note" x-show="!config.enabled">- Turn on WhatsApp to pair or switch your account.</div><div class="field">@@ -200,6 +153,22 @@<template x-if="$store.whatsappConfig.currentStep === 1"><div class="wa-step-panel">+ <div class="field">+ <div class="field-label">+ <div class="field-title">Enable WhatsApp</div>+ <div class="field-description">Receive messages from your linked account after saving.</div>+ </div>+ <div class="field-control">+ <label class="toggle">+ <input type="checkbox"+ aria-label="Enable WhatsApp"+ x-model="config.enabled"+ @change="$store.whatsappConfig.onEnabledChange()" />+ <span class="toggler"></span>+ </label>+ </div>+ </div>+<div class="field"><div class="field-label"><div class="field-title">Project</div>@@ -435,28 +404,44 @@font-size: var(--font-size-small);}- .wa-inline-actions {- display: flex;- gap: 0.75rem;- flex-wrap: wrap;+ .wa-pairing-row {+ display: grid;+ grid-template-columns: minmax(16rem, 18rem) minmax(0, 1fr);+ gap: 1rem;+ align-items: stretch;+ margin-bottom: 1rem;}- .wa-qr-panel {- margin-top: 0.25rem;+ .wa-qr-panel,+ .wa-pairing-instructions {padding: 1rem;- border-radius: 14px;- border: 1px solid color-mix(in srgb, var(--color-border) 88%, white 12%);+ border-radius: 0.5rem;background: color-mix(in srgb, var(--color-background) 90%, white 10%);+ }++ .wa-qr-panel {text-align: center;}+ .wa-qr-content {+ min-height: 150px;+ display: flex;+ align-items: center;+ justify-content: center;+ margin-bottom: 0.8rem;+ overflow-wrap: anywhere;+ }+.wa-qr-status {font-weight: 700;margin-bottom: 0.5rem;}- .wa-qr-status.ok {- color: #7ee7a4;+ .wa-pairing-steps {+ margin: 0;+ padding-left: 1.15rem;+ color: var(--color-text-secondary);+ line-height: 1.55;}.wa-qr-message,@@ -467,20 +452,16 @@.wa-qr-help {font-size: var(--font-size-small);- margin-top: 0.4rem;- }-- .wa-qr-help.error {- color: #fca5a5;+ margin-top: 0.8rem;}.wa-qr-image {+ display: block;width: 256px;- height: 256px;+ height: auto;max-width: 100%;- border-radius: 8px;+ border-radius: 0.5rem;background: white;- padding: 4px;}.wa-advanced {@@ -595,6 +576,10 @@}@media (max-width: 640px) {+ .wa-pairing-row {+ grid-template-columns: minmax(0, 1fr);+ }+.wa-summary-card,.wa-step-header,diff --git a/plugins/_whatsapp_integration/webui/whatsapp-config-store.js b/plugins/_whatsapp_integration/webui/whatsapp-config-store.jsindex f236d4ab0..8ce0a1d2f 100644--- a/plugins/_whatsapp_integration/webui/whatsapp-config-store.js+++ b/plugins/_whatsapp_integration/webui/whatsapp-config-store.js@@ -5,7 +5,7 @@ const API_BASE = "/plugins/_whatsapp_integration";const STEPS = [{title: "Pair your account and set access",- description: "Turn on WhatsApp, connect the account, and choose who can reach it.",+ description: "Link WhatsApp with a QR code, then choose who can reach your agent.",},{title: "Choose where conversations go",@@ -44,6 +44,7 @@ export const store = createStore("whatsappConfig", {qrMessage: "",qrDataUrl: null,qrPollTimer: null,+ _qrSession: 0,disconnecting: false,disconnectMessage: "",steps: STEPS,@@ -223,44 +224,51 @@ export const store = createStore("whatsappConfig", {},async showQr() {+ if (!this.config) return;+ this.hideQr();+ this.config.enabled = true;+ this.disconnectMessage = "";this.qrVisible = true;this.qrStatus = "loading";- this.qrMessage = "Starting the WhatsApp bridge...";+ this.qrMessage = "Preparing QR code...";this.qrDataUrl = null;await this.pollQr();- this.qrPollTimer = setInterval(() => this.pollQr(), 3000);},hideQr() {+ this._qrSession += 1;this.qrVisible = false;this.qrDataUrl = null;this.qrStatus = "";if (this.qrPollTimer) {- clearInterval(this.qrPollTimer);+ clearTimeout(this.qrPollTimer);this.qrPollTimer = null;}},- async pollQr() {+ async pollQr(session = this._qrSession) {+ if (!this.qrVisible || session !== this._qrSession) return;try {const response = await API.callJsonApi(`${API_BASE}/qr_code`, {});+ if (!this.qrVisible || session !== this._qrSession) return;this.qrStatus = response.status || "error";this.qrMessage = response.message || "";this.qrDataUrl = response.qr || null;-- if (response.status === "connected" && this.qrPollTimer) {- clearInterval(this.qrPollTimer);- this.qrPollTimer = null;- }} catch (error) {+ if (!this.qrVisible || session !== this._qrSession) return;this.qrStatus = "error";this.qrMessage = String(error);this.qrDataUrl = null;}+ this.qrPollTimer = null;+ if (this.qrStatus !== "connected" && this.qrStatus !== "error") {+ this.qrPollTimer = setTimeout(() => this.pollQr(session), 3000);+ }},async disconnectAccount() {if (!window.confirm("Disconnect this WhatsApp account? You will need to scan a new QR code to reconnect.")) return;+ this.hideQr();this.disconnecting = true;this.disconnectMessage = "";try {diff --git a/tests/test_whatsapp_config_store.mjs b/tests/test_whatsapp_config_store.mjsnew file mode 100644index 000000000..37dc8cc1b--- /dev/null+++ b/tests/test_whatsapp_config_store.mjs@@ -0,0 +1,59 @@+import assert from 'node:assert/strict';+import { readFileSync } from 'node:fs';+import vm from 'node:vm';+import test from 'node:test';++test('one-click pairing enables WhatsApp and polling stops on cancel, error, connection or cleanup', async () => {+ const requests = [];+ const timers = new Map();+ let nextTimer = 0;+ const source = readFileSync(new URL('../plugins/_whatsapp_integration/webui/whatsapp-config-store.js', import.meta.url), 'utf8')+ .replace(/^import .*;\n/gm, '').replace('export const store', 'const store');+ const store = vm.runInNewContext(`${source}\nstore`, {+ createStore: (_name, value) => value,+ API: { callJsonApi: () => new Promise((resolve, reject) => requests.push({ resolve, reject })) },+ setTimeout: fn => { timers.set(++nextTimer, fn); return nextTimer; },+ clearTimeout: id => timers.delete(id),+ });+ store.config = { enabled: false };+ const initial = store.showQr();+ assert.equal(store.config.enabled, true);+ assert.equal(store.qrVisible, true);+ assert.equal(requests.length, 1);+ store.hideQr();+ requests.shift().resolve({ status: 'waiting_scan', qr: 'stale' });+ await initial;+ assert.equal(store.qrDataUrl, null);+ assert.equal(timers.size, 0);++ const old = store.showQr();+ const retry = store.showQr();+ requests.shift().resolve({ status: 'connected' });+ await old;+ assert.equal(store.qrStatus, 'loading');+ requests.shift().resolve({ status: 'waiting_scan', qr: 'current' });+ await retry;+ assert.equal(store.qrDataUrl, 'current');+ assert.equal(timers.size, 1);+ const [id, tick] = [...timers][0];+ timers.delete(id);+ const poll = tick();+ requests.shift().resolve({ status: 'connected' });+ await poll;+ assert.equal(timers.size, 0);+ assert.equal(store.qrStatus, 'connected');++ const failed = store.showQr();+ requests.shift().reject(new Error('Unavailable'));+ await failed;+ assert.equal(store.qrStatus, 'error');+ assert.equal(timers.size, 0);++ const closing = store.showQr();+ store.cleanup();+ requests.shift().resolve({ status: 'waiting_scan', qr: 'closed' });+ await closing;+ assert.equal(store.qrVisible, false);+ assert.equal(store.qrDataUrl, null);+ assert.equal(timers.size, 0);+});