wazap-mcp 0.9.0 → 0.9.2

package/AGENT.md

@@ -0,0 +1,17 @@
+# wazap setup, driven by an agent
+
+You are setting up WhatsApp access for the person you are working with. Use the pairing-code flow (it is plain text); never the QR.
+
+wazap keeps stdout for the MCP protocol and writes every human-readable line to stderr, so read stderr as well: run each command with `2>&1`.
+
+1. Run `npx wazap-mcp status --json`. If `linked` is true, skip to step 5.
+2. Ask the person for their WhatsApp number in international format (e.g. +15550100) and whether the agent may send messages (default: no).
+3. Start the link IN THE BACKGROUND and keep reading its output:
+   `npx wazap-mcp login --phone <number> --no-writes --yes 2>&1` (or `--writes`).
+   Within ~10 s the output contains a line `pairing code: XXXX-XXXX`.
+4. Show the person exactly: "On your phone: WhatsApp → Settings → Linked devices → Link a device → Link with phone number instead → enter XXXX-XXXX". Keep reading the output until `Linked as …` and then `Synced N chats …` appear (up to 3 minutes). If the output says the code expired, run step 3 again.
+5. Register wazap with the client you are running in: `npx wazap-mcp connect <client>` where <client> is claude-code, claude-desktop, cursor, codex, vscode or gemini. Tell the person what the command printed as `Next`.
+6. Verify: `npx wazap-mcp status --json` must show `linked: true` and no failing check. If the client needs a restart, say so; otherwise call the `get_status` tool and then `learn`.
+7. Done when `get_status` returns `connected`. Then offer: "what did I miss on WhatsApp today?"
+
+Errors: every wazap error prints `✗ message` and `→ fix`; do what the fix says, do not retry blindly. One process owns the session, so while the `login` of step 3 runs, no server and no other wazap command may touch the same data dir; two servers on one data dir refuse to start. Stop the other one first.

package/README.md

@@ -19,18 +19,30 @@ WhatsApp multi-device protocol over a WebSocket.
 The npm package is `wazap-mcp`; the command it installs is `wazap`.
 
 ```bash
-npx wazap-mcp login                  # link your account with a pairing code
-npx wazap-mcp connect claude-code    # write the MCP entry for your agent
+npx wazap-mcp setup
 ```
 
+That is the whole install. It links your account, finds the MCP clients
+installed on this machine, writes their config and tells you what to restart.
+
+Or have your agent do it. Paste this:
+
+*Set up WhatsApp for me: run `npx wazap-mcp setup --agent` and follow what it prints.*
+
 Then ask your agent: *"what did I miss on WhatsApp today?"*
 
-`login` asks for your number in international format, prints an 8-character
-code, and you enter it on your phone under **Settings → Linked devices → Link a
-device → Link with phone number instead**. Prefer a QR code? `npx wazap-mcp login --qr`.
+Below are the steps `setup` runs for you. Each is still its own command when you
+want to run it by hand.
+
+`npx wazap-mcp login` shows a QR code; scan it from **Settings → Linked devices
+→ Link a device**. No camera handy, or linking over SSH? `npx wazap-mcp login --phone +15550100`
+prints an 8-character code you type under *Link with phone number instead*.
 It ends by asking whether the agent may send messages; the answer is no unless
 you say yes, and `npx wazap-mcp config writes on` changes it later.
 
+`npx wazap-mcp connect claude-code` writes the MCP entry for one client. The
+table under **Connect a client** has the rest.
+
 `npx wazap-mcp` on its own is safe to run: it prints where you stand and what to do
 next, and starts no server. When something is off, `npx wazap-mcp status` is the
 first thing to run — it checks Node, the data directory, the lock, the
@@ -122,7 +134,7 @@ wazap ships five [Agent Skills](https://agentskills.io) that teach an agent the
 
 | Skill | What the agent does |
 | --- | --- |
-| `wazap-setup` | Diagnose with `wazap status`, link by pairing code, connect a client with `wazap connect`, repair an expired session |
+| `wazap-setup` | Diagnose with `wazap status`, link by QR or pairing code, connect a client with `wazap connect`, repair an expired session |
 | `whatsapp-inbox` | "What did I miss?" Triage into *needs you / FYI / noise*, ranked, plus forgotten replies. Read-only |
 | `whatsapp-recall` | "Find the invoice Dan sent." Search with query variants, page back in time, download and read the file. Read-only |
 | `whatsapp-groups` | Catch up on a 300-message group: decisions, dates, what is asked of you. Read-only |
@@ -218,7 +230,7 @@ Run wazap on a server of your own when the agent is not on your laptop: another
 ```bash
 npm install -g wazap-mcp
 sudo useradd --system --home /var/lib/wazap --create-home wazap
-sudo -u wazap WAZAP_DATA_DIR=/var/lib/wazap wazap login --phone +40722123456   # pairing code works over SSH
+sudo -u wazap WAZAP_DATA_DIR=/var/lib/wazap wazap login --phone +15550100   # pairing code works over SSH
 sudo -u wazap tee /var/lib/wazap/.env >/dev/null <<END
 WAZAP_READ_TOKEN=$(openssl rand -hex 32)
 WAZAP_WRITE_TOKEN=$(openssl rand -hex 32)
@@ -235,7 +247,7 @@ The unit binds loopback only. Put TLS in front with the two-line [`deploy/Caddyf
 ```bash
 git clone https://github.com/razvangirgiz/wazap && cd wazap
 printf 'WAZAP_READ_TOKEN=%s\nWAZAP_WRITE_TOKEN=%s\n' $(openssl rand -hex 32) $(openssl rand -hex 32) > .env
-docker compose run --rm wazap login --phone +40722123456   # once; the session lands in the wazap-data volume
+docker compose run --rm wazap login --phone +15550100   # once; the session lands in the wazap-data volume
 docker compose up -d
 curl -s http://127.0.0.1:8766/healthz
 ```

package/dist/auth-state.js

@@ -106,7 +106,10 @@ export function readLinkedAccount(dir) {
     catch {
         throw new WazapError("SESSION_CORRUPT", `Stored credentials in ${dir} are unreadable.`, RESET_FIX);
     }
-    if (!creds.registered || !creds.me?.id)
+    // Baileys itself treats an account with `me` as linked (socket.js: `if (!creds.me)`
+    // pairs a device, else logs in). `registered` is only ever set by the
+    // pairing-code flow, so a QR-linked session would look unlinked forever.
+    if (!creds.me?.id)
         return null;
     const number = creds.me.id.split(":")[0].split("@")[0];
     return { id: `${number}@s.whatsapp.net`, name: creds.me.name || "", number };

package/dist/banner.js

@@ -1,7 +1,13 @@
-export const BANNER = `██╗    ██╗ █████╗ ███████╗ █████╗ ██████╗
+import { brand, dim } from "./ui.js";
+export const BANNER_ART = `██╗    ██╗ █████╗ ███████╗ █████╗ ██████╗
 ██║    ██║██╔══██╗╚══███╔╝██╔══██╗██╔══██╗
 ██║ █╗ ██║███████║  ███╔╝ ███████║██████╔╝
 ██║███╗██║██╔══██║ ███╔╝  ██╔══██║██╔═══╝
 ╚███╔███╔╝██║  ██║███████╗██║  ██║██║
- ╚══╝╚══╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝
-WhatsApp for your AI agent.`;
+ ╚══╝╚══╝ ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝`;
+export const TAGLINE = "WhatsApp for your AI agent.";
+export const BANNER = `${BANNER_ART}\n${TAGLINE}`;
+/** Painted per line, so a wrapped terminal cannot bleed the colour onward. */
+export function banner() {
+    return `${BANNER_ART.split("\n").map(brand).join("\n")}\n${dim(TAGLINE)}`;
+}

package/dist/cli.js

@@ -5,10 +5,10 @@ import makeWASocket, { DisconnectReason, } from "baileys";
 import qrcode from "qrcode";
 import qrcodeTerminal from "qrcode-terminal";
 import { clearAuth, readLinkedAccount, useAtomicAuthState } from "./auth-state.js";
-import { BANNER } from "./banner.js";
+import { banner } from "./banner.js";
 import { BAILEYS_VERSION, WAZAP_VERSION, paths } from "./config.js";
-import { CONNECT_HINT } from "./connect.js";
-import { checkLine, runChecks } from "./doctor.js";
+import { connectNext } from "./connect.js";
+import { checkLine, checkLines, runChecks } from "./doctor.js";
 import { RELINK_FIX, WazapError, asWazapError } from "./errors.js";
 import { normalizePhone } from "./ids.js";
 import { lockHolder, releaseLock, writeLock } from "./lock.js";
@@ -16,6 +16,7 @@ import { log, logError, say } from "./logger.js";
 import { formatAge } from "./messages.js";
 import { runHttp, runStdio } from "./server.js";
 import { applyWrites } from "./settings.js";
+import { bold, box, brand, humanLayout, dim, fail, info, maskNumber, next, ok, shortPath, spinner, step, tilde, warn, } from "./ui.js";
 import { WA_BROWSER, WhatsAppService } from "./whatsapp.js";
 const LOGIN_TIMEOUT_MS = 120_000;
 const LIVE_TIMEOUT_MS = 15_000;
@@ -66,24 +67,8 @@ export async function runStatus(config) {
             process.exit(0);
         return report;
     }
-    say(`data dir: ${report.data_dir}`);
-    if (unreadable) {
-        say("linked: no (credentials unreadable — run `wazap logout` then `wazap login`)");
-    }
-    else if (account) {
-        say("linked: yes");
-        say(`account: ${describeAccount(account)}`);
-    }
-    else {
-        say("linked: no");
-    }
-    say(`wazap: ${report.wazap_version}`);
-    say(`baileys: ${report.baileys_version}`);
-    say(report.server_pid === null ? "server: not running" : `server: running (pid ${report.server_pid})`);
-    say("");
-    say("checks:");
-    for (const check of report.checks)
-        say(checkLine(check));
+    for (const line of humanLayout() ? richStatus(report) : plainStatus(report))
+        say(line);
     if (report.live) {
         say("");
         for (const line of liveLines(report.live))
@@ -92,6 +77,40 @@ export async function runStatus(config) {
     }
     return report;
 }
+/** Today's phrasing, kept verbatim so pipes and log captures keep parsing. */
+function plainStatus(report) {
+    const lines = [`data dir: ${report.data_dir}`];
+    if (!report.credentials_readable) {
+        lines.push("linked: no (credentials unreadable — run `wazap logout` then `wazap login`)");
+    }
+    else if (report.account) {
+        lines.push("linked: yes", `account: ${describeAccount(report.account)}`);
+    }
+    else {
+        lines.push("linked: no");
+    }
+    lines.push(`wazap: ${report.wazap_version}`, `baileys: ${report.baileys_version}`, report.server_pid === null ? "server: not running" : `server: running (pid ${report.server_pid})`, "", "checks:", ...report.checks.map(checkLine));
+    return lines;
+}
+const LABEL_WIDTH = 8;
+function row(label, value) {
+    return `${dim(label.padEnd(LABEL_WIDTH))}  ${value}`;
+}
+function richStatus(report) {
+    const account = !report.credentials_readable
+        ? "credentials unreadable"
+        : report.account
+            ? describeAccount(report.account)
+            : "not linked";
+    return [
+        `${bold(`wazap ${report.wazap_version}`)}${dim(` · baileys ${report.baileys_version}`)}`,
+        row("data dir", tilde(report.data_dir)),
+        row("account", account),
+        row("server", report.server_pid === null ? "not running" : `running (pid ${report.server_pid})`),
+        "",
+        ...report.checks.flatMap(checkLines),
+    ];
+}
 function liveLines(live) {
     if (!live.reachable)
         return [`live: no connection (${live.reason ?? "unknown"})`];
@@ -114,13 +133,13 @@ async function runLiveProbe(config) {
     const deadline = Date.now() + LIVE_TIMEOUT_MS;
     try {
         await wa.start();
-        let info = wa.getStatus();
-        while (!SETTLED_STATUSES.includes(info.status) && Date.now() < deadline) {
+        let probe = wa.getStatus();
+        while (!SETTLED_STATUSES.includes(probe.status) && Date.now() < deadline) {
             await sleep(250);
-            info = wa.getStatus();
+            probe = wa.getStatus();
         }
-        if (info.status !== "connected") {
-            return { reachable: false, chats: null, last_message_age: null, reason: info.last_error ?? info.status };
+        if (probe.status !== "connected") {
+            return { reachable: false, chats: null, last_message_age: null, reason: probe.last_error ?? probe.status };
         }
         // listChats waits on its own sync gate, which would outlast the deadline.
         const chats = await Promise.race([
@@ -144,32 +163,32 @@ async function runLiveProbe(config) {
 }
 /** Bare `wazap` at a terminal: where you stand, and the one command to run next. */
 export async function runGreet(config) {
-    say(BANNER);
+    say(banner());
     say("");
     const report = await runStatus(config);
     say("");
     if (report.server_pid !== null) {
-        say(`A server is already running (pid ${report.server_pid}).`);
+        say(info(`A server is already running (pid ${report.server_pid}).`));
         return;
     }
     if (!report.credentials_readable) {
-        say("Next: wazap logout   (then wazap login)");
+        say(next("wazap logout", "(then wazap login)"));
         return;
     }
     say(report.linked
-        ? 'Next: wazap connect claude-code   (then ask your agent: "what did I miss on WhatsApp today?")'
-        : "Next: wazap login");
+        ? next("wazap connect claude-code", '(then ask your agent: "what did I miss on WhatsApp today?")')
+        : next("wazap login"));
 }
 export async function runServe(config) {
     const p = paths(config.dataDir);
     const running = lockHolder(p.lockFile);
     if (running !== null) {
-        say(`wazap is already running (pid ${running}) using ${config.dataDir}. Stop it first or use --data-dir.`);
+        say(fail(`wazap is already running (pid ${running}) using ${config.dataDir}. Stop it first or use --data-dir.`));
         process.exit(2);
     }
     // Loopback with no token only gets runHttp's warning; off-loopback is refused.
     if (config.transport === "http" && !config.readToken && !LOOPBACK_HOSTS.includes(config.httpHost)) {
-        say(`Refusing to serve ${config.httpHost} without a token. Set WAZAP_READ_TOKEN, or bind 127.0.0.1.`);
+        say(fail(`Refusing to serve ${config.httpHost} without a token. Set WAZAP_READ_TOKEN, or bind 127.0.0.1.`));
         process.exit(1);
     }
     mkdirSync(config.dataDir, { recursive: true, mode: 0o700 });
@@ -192,45 +211,193 @@ export async function runServe(config) {
     else
         await runStdio(wa, config);
 }
+export function stepper(total) {
+    let n = 0;
+    return (title) => say(step(++n, total, title));
+}
 export async function runLogin(config) {
     const p = paths(config.dataDir);
+    say(banner());
     const linked = readLinkedAccount(p.authDir);
     if (linked) {
-        say(`Already linked as ${describeAccount(linked)}. Run \`wazap logout\` to relink.`);
-        return;
-    }
-    const phone = config.loginQr ? null : normalizePhone(config.loginPhone ?? (await askPhone()));
-    let requested = false;
-    const onQr = async (qr, sock) => {
-        if (phone === null) {
-            qrcodeTerminal.generate(qr, { small: true }, (art) => say(art));
-            await qrcode.toFile(p.qrFile, qr);
-            say(`WhatsApp → Settings → Linked devices → Link a device, then scan the code above (also saved to ${p.qrFile}).`);
-            return;
-        }
-        if (requested)
-            return;
-        requested = true;
-        const code = await sock.requestPairingCode(phone);
         say("");
-        say("WhatsApp → Settings → Linked devices → Link a device → Link with phone number instead");
-        say("");
-        say(`    ${code.slice(0, 4)}-${code.slice(4)}`);
+        say(ok(`Already linked as ${describeAccount(linked)}`));
+        say(info("Run `wazap logout` to relink."));
         say("");
+        say(connectNext());
+        return;
+    }
+    await linkAndSync(config, stepper(config.loginCode ? 4 : 3));
+    say("");
+    say(connectNext());
+    process.exit(0);
+}
+/**
+ * Pairing owns the session the way the server does, so the lock is held from
+ * here until the history has landed. Writes are offered after it is released:
+ * that question edits .env, not the session, and it waits on a human.
+ */
+export async function linkAndSync(config, announce = () => { }) {
+    const p = paths(config.dataDir);
+    const running = lockHolder(p.lockFile);
+    if (running !== null) {
+        say(fail(`wazap is running (pid ${running}). Stop it first (or quit the client that launched it), then run this again.`));
+        process.exit(1);
+    }
+    mkdirSync(config.dataDir, { recursive: true, mode: 0o700 });
+    writeLock(p.lockFile);
+    const release = () => releaseLock(p.lockFile);
+    const onInterrupt = () => {
+        release();
+        process.exit(130);
+    };
+    const onTerminate = () => {
+        release();
+        process.exit(143);
     };
-    const sock = await linkSession(p.authDir, { deadline: Date.now() + LOGIN_TIMEOUT_MS, onQr });
-    const account = await settledAccount(sock, p.authDir);
-    say(`Linked ✅ as ${describeAccount(account)}`);
-    await sock.end(undefined);
+    process.on("exit", release);
+    process.on("SIGINT", onInterrupt);
+    process.on("SIGTERM", onTerminate);
+    try {
+        let phone = null;
+        if (config.loginCode) {
+            announce("Your number");
+            phone = config.loginPhone === undefined ? await askPhone() : normalizePhone(config.loginPhone);
+            say(ok(maskNumber(phone)));
+        }
+        const deadline = Date.now() + LOGIN_TIMEOUT_MS;
+        const waiting = new Countdown(deadline);
+        announce("Link your phone");
+        let requested = false;
+        const onQr = async (qr, sock) => {
+            if (phone === null) {
+                qrcodeTerminal.generate(qr, { small: true }, (art) => say(art));
+                await qrcode.toFile(p.qrFile, qr);
+                say(`  Scan it with WhatsApp → Settings → Linked devices → Link a device (also saved to ${shortPath(p.qrFile)})`);
+                say(dim("  Prefer typing a code? Press Ctrl+C and run `wazap login --phone +15550100`."));
+                say("");
+                waiting.start();
+                return;
+            }
+            if (requested)
+                return;
+            requested = true;
+            const code = await sock.requestPairingCode(phone);
+            const pretty = `${code.slice(0, 4)}-${code.slice(4)}`;
+            if (!humanLayout())
+                say(`pairing code: ${pretty}`);
+            say("  On your phone: WhatsApp → Settings → Linked devices → Link a device → Link with phone number instead");
+            say("");
+            say(box(pretty));
+            say("");
+            waiting.start();
+        };
+        let account;
+        try {
+            const sock = await linkSession(p.authDir, { deadline, onQr });
+            account = await settledAccount(sock, p.authDir);
+            await sock.end(undefined);
+        }
+        catch (err) {
+            waiting.stop();
+            throw err;
+        }
+        waiting.stop(ok(`Linked as ${describeAccount(account)}`));
+        announce("Sync your chats");
+        await syncAfterLink(config);
+    }
+    finally {
+        release();
+        process.off("exit", release);
+        process.off("SIGINT", onInterrupt);
+        process.off("SIGTERM", onTerminate);
+    }
+    announce("Permissions");
     await offerWrites(config);
-    say(CONNECT_HINT);
-    process.exit(0);
+}
+const HISTORY_WAIT_MS = 90_000;
+const HISTORY_QUIET_MS = 3_000;
+/**
+ * WhatsApp sends the chat history exactly once, right after pairing, to the
+ * socket that paired. The link socket has no store, so the real service takes
+ * over here and stays up until the history has landed and gone quiet.
+ */
+async function syncAfterLink(config) {
+    const wa = new WhatsAppService(config);
+    const spin = spinner("Syncing your chats…");
+    try {
+        await wa.start();
+        const deadline = Date.now() + HISTORY_WAIT_MS;
+        let seen = "";
+        let quietSince = Date.now();
+        while (Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, 500));
+            const counts = wa.storeCounts();
+            const key = `${counts.chats}/${counts.contacts}/${counts.messages}`;
+            spin.update(`Syncing your chats…  ${counts.chats} chats, ${counts.contacts} contacts, ${counts.messages} messages`);
+            if (!wa.hasHistory())
+                continue;
+            if (key !== seen) {
+                seen = key;
+                quietSince = Date.now();
+            }
+            else if (Date.now() - quietSince >= HISTORY_QUIET_MS) {
+                break;
+            }
+        }
+    }
+    finally {
+        const counts = wa.storeCounts();
+        const got = wa.hasHistory();
+        await wa.stop();
+        spin.stop(got
+            ? ok(`Synced ${counts.chats} chats, ${counts.contacts} contacts, ${counts.messages} messages`)
+            : warn("No history arrived in 90s. The server keeps listening; if chats stay empty, run `wazap logout` then `wazap login`."));
+    }
+}
+/**
+ * The spinner shown while WhatsApp is asked to accept the code, counting the
+ * pairing code down to the deadline it expires on.
+ */
+class Countdown {
+    deadline;
+    #spinner = null;
+    #ticker = null;
+    #stopped = false;
+    constructor(deadline) {
+        this.deadline = deadline;
+    }
+    /** No-op once stopped: the socket can settle while the code request is still in flight. */
+    start() {
+        if (this.#stopped)
+            return;
+        this.#spinner = spinner(this.#line());
+        this.#ticker = setInterval(() => this.#spinner?.update(this.#line()), 1_000);
+        this.#ticker.unref();
+    }
+    stop(final) {
+        this.#stopped = true;
+        if (this.#ticker !== null)
+            clearInterval(this.#ticker);
+        this.#ticker = null;
+        if (this.#spinner === null) {
+            if (final !== undefined)
+                say(final);
+            return;
+        }
+        this.#spinner.stop(final);
+        this.#spinner = null;
+    }
+    #line() {
+        const left = Math.max(0, Math.round((this.deadline - Date.now()) / 1_000));
+        return `Waiting for your phone…  (expires in ${Math.floor(left / 60)}:${String(left % 60).padStart(2, "0")})`;
+    }
 }
 export async function runLogout(config) {
     const p = paths(config.dataDir);
     const running = lockHolder(p.lockFile);
     if (running !== null) {
-        say(`wazap is running (pid ${running}). Stop it first, then run \`wazap logout\`.`);
+        say(fail(`wazap is running (pid ${running}). Stop it first.`));
         process.exit(1);
     }
     let linked = null;
@@ -243,7 +410,7 @@ export async function runLogout(config) {
         unreadable = true;
     }
     if (!linked && !unreadable) {
-        say("Not linked.");
+        say(info("Not linked."));
         return;
     }
     if (linked) {
@@ -253,17 +420,34 @@ export async function runLogout(config) {
             await withDeadline(sock.logout(), deadline, "WhatsApp did not confirm the unlink in time.");
         }
         catch (err) {
-            logError("unlink from WhatsApp", err);
-            say("Could not tell WhatsApp to unlink; remove this device from your phone if it is still listed.");
+            if (alreadyUnlinked(err)) {
+                say(info("WhatsApp had already unlinked this device."));
+            }
+            else {
+                logError("unlink from WhatsApp", err);
+                say(warn("Could not tell WhatsApp to unlink; remove this device from your phone if it is still listed."));
+            }
         }
     }
     clearAuth(p.authDir);
     rmSync(p.storeFile, { force: true });
-    say("Logged out. Local credentials deleted.");
+    say(ok("Logged out. Local credentials deleted."));
     process.exit(0);
 }
-function describeAccount(account) {
-    return account.name ? `${account.name} (${account.number})` : account.number;
+/**
+ * WhatsApp answers 401 both when a pairing code was wrong and when the phone has
+ * already removed this device. At logout the second reading is the true one, so
+ * the pairing-time wording must not surface as an error here.
+ */
+export function alreadyUnlinked(err) {
+    if (err instanceof WazapError)
+        return err.code === "SESSION_EXPIRED";
+    return err?.output?.statusCode === DisconnectReason.loggedOut;
+}
+/** The number is masked: a status screenshot should not carry it. */
+export function describeAccount(account) {
+    const number = maskNumber(account.number);
+    return account.name ? `${account.name} (${number})` : number;
 }
 /**
  * Writes stay off unless the user says otherwise, so a fresh link cannot message
@@ -276,10 +460,10 @@ export async function offerWrites(config) {
     }
     if (config.assumeYes || !process.stdin.isTTY)
         return;
-    const answer = await ask("Allow the agent to send messages, react and manage chats? [y/N] ");
+    const answer = await ask(`${brand("?")} Allow the agent to send messages, react and manage chats? [y/N] `);
     applyWrites(config, /^y(es)?$/i.test(answer.trim()));
 }
-async function ask(question) {
+export async function ask(question) {
     const rl = createInterface({ input: process.stdin, output: process.stderr });
     try {
         return await rl.question(question);
@@ -288,8 +472,20 @@ async function ask(question) {
         rl.close();
     }
 }
-function askPhone() {
-    return ask("Phone number in international format (e.g. +40722123456): ");
+const PHONE_ATTEMPTS = 3;
+/** A typo costs another prompt, not the whole login. */
+async function askPhone() {
+    for (let attempt = 1;; attempt++) {
+        const answer = await ask(`${brand("?")} WhatsApp number, international format (e.g. +15550100): `);
+        try {
+            return normalizePhone(answer);
+        }
+        catch (err) {
+            if (attempt === PHONE_ATTEMPTS)
+                throw err;
+            say(fail("Use international format, e.g. +15550100"));
+        }
+    }
 }
 /**
  * A socket run until it is open, retrying across the restart WhatsApp demands

package/dist/config.js

@@ -23,6 +23,7 @@ export function paths(dataDir) {
 const COMMAND_ARGS = {
     serve: [0],
     login: [0],
+    setup: [0],
     status: [0],
     logout: [0],
     connect: [1],
@@ -63,11 +64,14 @@ export function parseCli(argv = process.argv.slice(2)) {
                 port: { type: "string" },
                 phone: { type: "string" },
                 qr: { type: "boolean" },
+                code: { type: "boolean" },
                 "dry-run": { type: "boolean" },
                 live: { type: "boolean" },
                 json: { type: "boolean" },
                 writes: { type: "boolean" },
                 "no-writes": { type: "boolean" },
+                agent: { type: "boolean" },
+                client: { type: "string", multiple: true },
                 yes: { type: "boolean", short: "y" },
                 help: { type: "boolean", short: "h" },
                 version: { type: "boolean", short: "v" },
@@ -130,8 +134,10 @@ export function parseCli(argv = process.argv.slice(2)) {
             live: values.live === true,
             json: values.json === true,
             loginPhone: values.phone,
-            loginQr: values.qr === true,
+            loginCode: values.code === true || values.phone !== undefined,
             writesAnswer: values.writes === true ? true : values["no-writes"] === true ? false : null,
+            agent: values.agent === true,
+            clients: values.client ?? [],
             assumeYes: values.yes === true,
         },
     };

package/dist/connect.js

@@ -1,10 +1,11 @@
 import { spawnSync } from "node:child_process";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { delimiter, dirname, join, resolve } from "node:path";
+import { basename, delimiter, dirname, join, resolve } from "node:path";
 import { defaultDataDir } from "./config.js";
 import { WazapError } from "./errors.js";
 import { say } from "./logger.js";
+import { dim, fail, fix, info, next, nextHint, ok, shortPath } from "./ui.js";
 function claudeDesktopFile() {
     if (process.platform === "darwin") {
         return join(homedir(), "Library", "Application Support", "Claude", "claude_desktop_config.json");
@@ -22,6 +23,7 @@ export const CLIENTS = [
         format: "command",
         keyPath: [],
         next: "Run `claude mcp list` to confirm.",
+        detect: (probe) => probe.onPath("claude"),
     },
     {
         name: "claude-desktop",
@@ -30,6 +32,7 @@ export const CLIENTS = [
         format: "json",
         keyPath: ["mcpServers", "whatsapp"],
         next: "Restart Claude Desktop.",
+        detect: (probe) => probe.exists(dirname(claudeDesktopFile())),
     },
     {
         name: "cursor",
@@ -38,6 +41,7 @@ export const CLIENTS = [
         format: "json",
         keyPath: ["mcpServers", "whatsapp"],
         next: "Reload the Cursor window.",
+        detect: (probe) => probe.exists(join(homedir(), ".cursor")),
     },
     {
         name: "codex",
@@ -46,6 +50,7 @@ export const CLIENTS = [
         format: "toml",
         keyPath: ["mcp_servers", "whatsapp"],
         next: "Restart Codex.",
+        detect: (probe) => probe.exists(join(homedir(), ".codex")),
     },
     {
         name: "vscode",
@@ -55,6 +60,7 @@ export const CLIENTS = [
         keyPath: ["servers", "whatsapp"],
         extra: { type: "stdio" },
         next: "Written to ./.vscode/mcp.json for this workspace. Reload the VS Code window.",
+        detect: (probe) => probe.onPath("code"),
     },
     {
         name: "gemini",
@@ -63,21 +69,30 @@ export const CLIENTS = [
         format: "json",
         keyPath: ["mcpServers", "whatsapp"],
         next: "Restart the Gemini CLI.",
+        detect: (probe) => probe.exists(join(homedir(), ".gemini")),
     },
 ];
 export const CLIENT_NAMES = CLIENTS.map((client) => client.name).join(", ");
-export const CONNECT_HINT = `Next: wazap connect claude-code   (or ${CLIENTS.slice(1)
+const OTHER_CLIENTS = CLIENTS.slice(1)
     .map((client) => client.name)
-    .join(", ")})`;
+    .join(", ");
+export function connectNext() {
+    return next("wazap connect claude-code", `(or ${OTHER_CLIENTS})`);
+}
 export function isNpxPath(binPath) {
     return /[\\/]_npx[\\/]/.test(binPath);
 }
-const PATH_NAMES = process.platform === "win32" ? ["wazap.cmd", "wazap"] : ["wazap"];
-export function onPath(pathEnv, exists = existsSync) {
+const PATH_EXTENSIONS = process.platform === "win32" ? [".cmd", ".exe", ""] : [""];
+export function commandOnPath(name, pathEnv = process.env.PATH ?? "", exists = existsSync) {
     return pathEnv
         .split(delimiter)
         .filter(Boolean)
-        .some((dir) => PATH_NAMES.some((name) => exists(join(dir, name))));
+        .some((dir) => PATH_EXTENSIONS.some((ext) => exists(join(dir, `${name}${ext}`))));
+}
+export const REAL_PROBES = { exists: existsSync, onPath: (command) => commandOnPath(command) };
+/** The installed clients, in table order. */
+export function detectClients(probe = REAL_PROBES) {
+    return CLIENTS.filter((client) => client.detect(probe));
 }
 /**
  * How the client should launch wazap, from how it was launched now: through
@@ -88,7 +103,7 @@ export function onPath(pathEnv, exists = existsSync) {
 export function launcher(binPath, pathEnv, exists) {
     if (isNpxPath(binPath))
         return { command: "npx", args: ["-y", "wazap-mcp"] };
-    if (onPath(pathEnv, exists))
+    if (commandOnPath("wazap", pathEnv, exists))
         return { command: "wazap", args: [] };
     return { command: "node", args: [resolve(binPath)] };
 }
@@ -105,14 +120,21 @@ const WRITERS = {
     json: writeJsonEntry,
     toml: writeTomlEntry,
 };
-export function runConnect(config) {
-    const name = config.args[0] ?? "";
+export function findClient(name) {
     const spec = CLIENTS.find((client) => client.name === name);
     if (!spec) {
         throw new WazapError("INVALID_ID", `Unknown client "${name}".`, `Pick one of: ${CLIENT_NAMES}`);
     }
+    return spec;
+}
+export function connectClient(spec, config) {
     WRITERS[spec.format](spec, mcpEntry(config), config.dryRun);
 }
+export function runConnect(config) {
+    const spec = findClient(config.args[0] ?? "");
+    connectClient(spec, config);
+    say(nextHint(spec.next));
+}
 /** Null only when the file is absent; an unreadable file must never be overwritten. */
 function readTextOrNull(file) {
     try {
@@ -153,7 +175,9 @@ function writeJsonEntry(spec, entry, dryRun) {
     }
     const value = { ...spec.extra, command: entry.command, args: entry.args };
     setIn(doc, spec.keyPath, value);
-    apply(spec, file, `${JSON.stringify(doc, null, 2)}\n`, current, dryRun, JSON.stringify(value, null, 2));
+    // Indent 1 collapsed to one line: short enough to read, still spaced like JSON.
+    const shown = JSON.stringify(value, null, 1).replace(/\n\s*/g, " ");
+    apply(spec, file, `${JSON.stringify(doc, null, 2)}\n`, current, dryRun, shown);
 }
 function writeTomlEntry(spec, entry, dryRun) {
     const file = spec.file();
@@ -180,43 +204,45 @@ function spliceTomlTable(text, header, block) {
     const merged = [...lines.slice(0, start), ...block.trimEnd().split("\n"), ...lines.slice(end)].join("\n");
     return merged.endsWith("\n") ? merged : `${merged}\n`;
 }
-function apply(spec, file, next, current, dryRun, shown) {
+function apply(spec, file, content, current, dryRun, shown) {
+    const where = shortPath(file);
+    const entry = shown.split("\n").map((line) => `  ${dim(line)}`);
     if (dryRun) {
-        say(`${spec.describe}: would write ${file}`);
-        say(shown);
-        say(`Next: ${spec.next}`);
+        say(info(`${spec.describe} \u00b7 would write ${where}`));
+        for (const line of entry)
+            say(line);
         return;
     }
-    if (next === current) {
-        say(`${spec.describe}: ${file} already has this entry.`);
-        say(`Next: ${spec.next}`);
+    if (content === current) {
+        say(ok(`${spec.describe} \u00b7 ${where} already has this entry`));
         return;
     }
     mkdirSync(dirname(file), { recursive: true });
-    if (current !== null && !existsSync(`${file}.bak`))
+    let backup = "";
+    if (current !== null && !existsSync(`${file}.bak`)) {
         copyFileSync(file, `${file}.bak`);
-    writeFileSync(file, next);
-    say(`${spec.describe}: wrote ${file}`);
-    say(shown);
-    say(`Next: ${spec.next}`);
+        backup = `  (backup: ${basename(file)}.bak)`;
+    }
+    writeFileSync(file, content);
+    say(ok(`${spec.describe} \u00b7 wrote ${where}${backup}`));
+    for (const line of entry)
+        say(line);
 }
 function runClientCommand(spec, entry, dryRun) {
     const argv = ["mcp", "add", "whatsapp", "--", entry.command, ...entry.args];
     const shown = `claude ${argv.join(" ")}`;
     if (dryRun) {
-        say(`${spec.describe}: would run`);
-        say(shown);
-        say(`Next: ${spec.next}`);
+        say(info(`${spec.describe} \u00b7 would run`));
+        say(`  ${dim(shown)}`);
         return;
     }
     const result = spawnSync("claude", argv, { stdio: "inherit" });
     if (result.error !== undefined) {
-        say("`claude` is not on PATH. Run this yourself where Claude Code is installed:");
-        say(shown);
+        say(fail("`claude` is not on PATH."));
+        say(fix(`Run this where Claude Code is installed: ${shown}`));
         process.exit(1);
     }
     if (result.status !== 0)
         process.exit(result.status ?? 1);
-    say(`${spec.describe}: registered the whatsapp MCP server.`);
-    say(`Next: ${spec.next}`);
+    say(ok(`${spec.describe} \u00b7 registered via claude mcp add`));
 }

package/dist/doctor.js

@@ -2,7 +2,10 @@ import { accessSync, constants, statSync } from "node:fs";
 import { readLinkedAccount } from "./auth-state.js";
 import { WAZAP_VERSION, paths } from "./config.js";
 import { lockHolder, lockPid } from "./lock.js";
+import { dim, fail, fix, green, info, ok, red } from "./ui.js";
 export const MARK = { ok: "✓", fail: "✗", info: "–" };
+const GLYPH = { ok, fail, info };
+const TINT = { ok: green, fail: red, info: dim };
 const UPDATE_TIMEOUT_MS = 2_000;
 const MIN_NODE_MAJOR = 20;
 const CHECKS = [checkNode, checkDataDir, checkLock, checkCredentials, checkWrites, checkUpdate];
@@ -12,8 +15,19 @@ export async function runChecks(config) {
         checks.push(await check(config));
     return checks;
 }
+/**
+ * One line, everything on it. What pipes, logs and captured output get. Colour
+ * wraps the whole line rather than just the glyph: an escape landing between
+ * the mark and the name would split phrases that callers grep for.
+ */
 export function checkLine(check) {
-    return `${MARK[check.state]} ${check.name}: ${check.detail}${check.fix ? ` — ${check.fix}` : ""}`;
+    const body = `${MARK[check.state]} ${check.name}: ${check.detail}${check.fix ? ` — ${check.fix}` : ""}`;
+    return TINT[check.state](body);
+}
+/** The same check for a human: no colon, and the repair on its own line. */
+export function checkLines(check) {
+    const head = GLYPH[check.state](`${check.name} ${check.detail}`);
+    return check.fix === undefined ? [head] : [head, fix(check.fix)];
 }
 function checkNode() {
     const version = process.versions.node;
@@ -66,9 +80,10 @@ function checkCredentials(config) {
     const authDir = paths(config.dataDir).authDir;
     try {
         const account = readLinkedAccount(authDir);
+        // The number is deliberately absent: status is the thing people screenshot.
         return account === null
             ? { name: "credentials", state: "info", detail: "no account linked yet" }
-            : { name: "credentials", state: "ok", detail: `readable (${account.number})` };
+            : { name: "credentials", state: "ok", detail: "readable" };
     }
     catch (err) {
         const wazap = err;

package/dist/errors.js

@@ -17,7 +17,7 @@ export const ERROR_GUIDE = {
     SESSION_CORRUPT: "Stored credentials are unreadable. Tell the user to run `npx wazap-mcp logout` then `npx wazap-mcp login`.",
     NOT_CONNECTED: "The socket is still connecting or reconnecting. Call get_status, wait, retry once.",
     SYNC_IN_PROGRESS: "History sync has not finished. Retry in a few seconds; earlier messages may be missing until then.",
-    INVALID_PHONE: "The number is not in international format. Ask the user for a number with a country code, e.g. +40722123456.",
+    INVALID_PHONE: "The number is not in international format. Ask the user for a number with a country code, e.g. +15550100.",
     INVALID_ID: "The id is not a WhatsApp chat, contact or group id. Use an id exactly as returned by another tool.",
     NOT_ON_WHATSAPP: "That number has no WhatsApp account. Do not retry; confirm the number with the user.",
     CHAT_NOT_FOUND: "No such chat is known. Call list_chats or search_contacts to get a valid chat_id.",

package/dist/ids.js

@@ -1,5 +1,5 @@
 import { WazapError } from "./errors.js";
-const PHONE_EXAMPLE = "Use international format, e.g. +40722123456";
+const PHONE_EXAMPLE = "Use international format, e.g. +15550100";
 /** Digits of a phone number in international format, or INVALID_PHONE. */
 export function normalizePhone(input) {
     const digits = input.trim().replace(/^\+/, "").replace(/[\s\-().]/g, "");

package/dist/index.js

@@ -3,14 +3,17 @@ import { BANNER } from "./banner.js";
 import { runGreet, runLogin, runLogout, runServe, runStatus } from "./cli.js";
 import { WAZAP_VERSION, parseCli, pickDefaultAction } from "./config.js";
 import { CLIENT_NAMES, runConnect } from "./connect.js";
+import { runSetup } from "./setup.js";
 import { runConfig } from "./settings.js";
 import { WazapError } from "./errors.js";
 import { say } from "./logger.js";
+import { fail, fix } from "./ui.js";
 const USAGE = `${BANNER}
 
 Usage:
   wazap [serve] [--http] [--host <host>] [--port <port>]   Run the MCP server (default: stdio)
-  wazap login [--phone +40722123456] [--qr]                Link a WhatsApp account
+  wazap login [--phone +15550100] [--code]              Link a WhatsApp account (QR by default)
+  wazap setup [--agent] [--client <name>]                  Link, connect your client and finish, in one command
   wazap connect <client> [--dry-run]                       Register wazap with an MCP client
   wazap config [writes on|off]                             Show the effective settings, or allow/refuse writes
   wazap status [--live] [--json]                           Check the install, the session and the server
@@ -24,8 +27,10 @@ Options:
   --http              Serve Streamable HTTP instead of stdio
   --host <host>       HTTP bind address (default 127.0.0.1)
   --port <port>       HTTP port (default 8766)
-  --phone <number>    Phone number in international format, for login
-  --qr                Log in by QR code instead of a pairing code
+  --code              Log in with an 8-character pairing code instead of the QR
+  --phone <number>    Your number in international format; implies --code
+  --agent             With setup: print the procedure for an AI agent on stdout, then exit
+  --client <name>     With setup: connect this client instead of the detected ones (repeatable)
   --dry-run           With connect: print what would be written, and write nothing
   --live              With status: reach WhatsApp for real, then close the connection
   --json              With status: print the whole report as one JSON object on stdout
@@ -61,6 +66,9 @@ async function main() {
         case "login":
             await runLogin(config);
             return;
+        case "setup":
+            await runSetup(config);
+            return;
         case "connect":
             runConnect(config);
             return;
@@ -76,13 +84,8 @@ async function main() {
     }
 }
 main().catch((err) => {
-    if (err instanceof WazapError) {
-        say(err.message);
-        if (err.fix)
-            say(err.fix);
-    }
-    else {
-        say(err instanceof Error ? err.message : String(err));
-    }
+    say(fail(err instanceof Error ? err.message : String(err)));
+    if (err instanceof WazapError && err.fix)
+        say(fix(err.fix));
     process.exit(1);
 });

package/dist/settings.js

@@ -4,6 +4,7 @@ import { paths } from "./config.js";
 import { WazapError } from "./errors.js";
 import { lockHolder } from "./lock.js";
 import { say } from "./logger.js";
+import { dim, ok, shortPath, warn } from "./ui.js";
 /** Replace `KEY=` in place, keeping every other line, or append it. */
 export function setEnvSetting(envFile, key, value) {
     let text = "";
@@ -51,7 +52,7 @@ export function runConfig(config) {
         for (const row of SETTINGS)
             say(`${row.label}: ${row.value(config)} (${config.sources[row.source]})`);
         say("");
-        say("Change writes with `wazap config writes on|off`.");
+        say(dim("Change writes with `wazap config writes on|off`."));
         return;
     }
     const [setting, value] = config.args;
@@ -64,11 +65,11 @@ export function runConfig(config) {
 export function applyWrites(config, allowWrites) {
     const p = paths(config.dataDir);
     setEnvSetting(p.envFile, "WAZAP_READ_ONLY", allowWrites ? "0" : "1");
-    say(allowWrites
-        ? `writes: on — the agent can send messages, react and manage chats. Turn it off with \`wazap config writes off\`.`
-        : `writes: off — the agent can only read. Turn it on with \`wazap config writes on\`.`);
-    say(`Stored in ${p.envFile}.`);
+    say(ok(allowWrites
+        ? "writes: on — the agent can send messages, react and manage chats. Turn it off with `wazap config writes off`."
+        : "writes: off — the agent can only read. Turn it on with `wazap config writes on`."));
+    say(dim(`Stored in ${shortPath(p.envFile)}.`));
     const running = lockHolder(p.lockFile);
     if (running !== null)
-        say(`A server is running (pid ${running}); restart it for this to apply.`);
+        say(warn(`A server is running (pid ${running}); restart it for this to apply.`));
 }

package/dist/setup.js

@@ -0,0 +1,83 @@
+import { readFileSync } from "node:fs";
+import { readLinkedAccount } from "./auth-state.js";
+import { banner } from "./banner.js";
+import { ask, describeAccount, linkAndSync, stepper } from "./cli.js";
+import { paths } from "./config.js";
+import { CLIENTS, connectClient, connectNext, detectClients, findClient } from "./connect.js";
+import { say } from "./logger.js";
+import { brand, fail, info, ok } from "./ui.js";
+export async function runSetup(config) {
+    // The whole output is the document and this command never serves, so stdout is
+    // the right channel. AGENT.md sits at the package root, which is what `files`
+    // publishes.
+    if (config.agent) {
+        process.stdout.write(readFileSync(new URL("../AGENT.md", import.meta.url), "utf8"));
+        return;
+    }
+    say(banner());
+    const announce = stepper(3);
+    announce("Link");
+    const account = readLinkedAccount(paths(config.dataDir).authDir);
+    if (account)
+        say(ok(`Already linked as ${describeAccount(account)}`));
+    else
+        await linkAndSync(config);
+    announce("Connect");
+    const chosen = await chooseClients(config);
+    if (chosen.length === 0) {
+        say(info("No client connected yet."));
+        say(connectNext());
+    }
+    for (const spec of chosen)
+        connectClient(spec, config);
+    announce("Finish");
+    say(ok("Setup complete"));
+    for (const spec of chosen)
+        say(info(spec.next));
+    say("");
+    say('Ask your agent: "what did I miss on WhatsApp today?"');
+}
+const CHOICE_ATTEMPTS = 3;
+/**
+ * The whole table is printed, not only what was found: that is what makes the
+ * numbers and "all" mean something, and it lets someone pick a client the
+ * probes missed.
+ */
+async function chooseClients(config) {
+    if (config.clients.length > 0)
+        return config.clients.map(findClient);
+    const detected = detectClients();
+    if (config.assumeYes || process.stdin.isTTY !== true)
+        return detected;
+    CLIENTS.forEach((spec, index) => {
+        say(`  ${index + 1}. [${detected.includes(spec) ? "x" : " "}] ${spec.describe}`);
+    });
+    const suggested = detected.map((spec) => CLIENTS.indexOf(spec) + 1).join(",");
+    for (let attempt = 1;; attempt++) {
+        const answer = await ask(`${brand("?")} Connect to: [${suggested}] (enter to accept, or type numbers, "all", "none") `);
+        const picked = parseChoice(answer, detected);
+        if (picked !== null)
+            return picked;
+        if (attempt === CHOICE_ATTEMPTS)
+            return detected;
+        say(fail('Type numbers from the list, "all", or "none".'));
+    }
+}
+/** Null when the answer names something that is not on the list. */
+export function parseChoice(answer, detected) {
+    const text = answer.trim();
+    if (text === "")
+        return [...detected];
+    if (/^all$/i.test(text))
+        return [...CLIENTS];
+    if (/^none$/i.test(text))
+        return [];
+    const picked = new Set();
+    for (const token of text.split(/[\s,]+/)) {
+        const n = Number(token);
+        if (!Number.isInteger(n) || n < 1 || n > CLIENTS.length)
+            return null;
+        picked.add(CLIENTS[n - 1]);
+    }
+    return [...picked];
+}

package/dist/tools.js

@@ -32,7 +32,7 @@ contacts and groups. Call get_status first if anything looks wrong.
 
 ## Identifiers
 - chat_id — individual: \`<digits>@s.whatsapp.net\`; group: \`<id>@g.us\`. A phone
-  number in international format (+40722123456 or 40722123456) also works. Pass
+  number in international format (+15550100 or 15550100) also works. Pass
   ids back exactly as a tool returned them.
 - message_id — the full id from read_messages / search_messages. Needed for
   get_message, download_media, react_to_message, edit_message, forward_message,

package/dist/ui.js

@@ -0,0 +1,185 @@
+/**
+ * Every ANSI escape wazap emits lives here. Helpers return plain text when
+ * colour is off, so piped and captured output keeps the same visible words.
+ */
+import { homedir } from "node:os";
+import { sep } from "node:path";
+const RESET = "\x1b[0m";
+const CLEAR_LINE = "\r\x1b[2K";
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const FRAME_MS = 80;
+/** stderr carries every human-readable line, so stderr decides colour. */
+export function colorEnabled() {
+    const forced = process.env.FORCE_COLOR;
+    if (forced !== undefined)
+        return forced !== "0";
+    const disabled = process.env.NO_COLOR;
+    if (disabled !== undefined && disabled !== "")
+        return false;
+    return process.stderr.isTTY === true;
+}
+/**
+ * Whether to draw for a person rather than for a pipe. Deliberately not
+ * colorEnabled(): NO_COLOR at a terminal still wants the roomy layout, and
+ * FORCE_COLOR in a pipe must not reshape output something else is parsing.
+ */
+export function humanLayout() {
+    return process.stderr.isTTY === true;
+}
+function paint(code, text) {
+    return colorEnabled() ? `${code}${text}${RESET}` : text;
+}
+function brandCode() {
+    const rich = (process.env.TERM ?? "").includes("256color") || /truecolor|24bit/i.test(process.env.COLORTERM ?? "");
+    return rich ? "\x1b[38;5;42m" : "\x1b[32m";
+}
+export function brand(text) {
+    return paint(brandCode(), text);
+}
+export function dim(text) {
+    return paint("\x1b[2m", text);
+}
+export function bold(text) {
+    return paint("\x1b[1m", text);
+}
+export function red(text) {
+    return paint("\x1b[31m", text);
+}
+export function yellow(text) {
+    return paint("\x1b[33m", text);
+}
+/** Anything the user is meant to type. */
+export function cmd(text) {
+    return paint("\x1b[36m", text);
+}
+export function green(text) {
+    return paint("\x1b[32m", text);
+}
+export function ok(text) {
+    return `${green("✓")} ${text}`;
+}
+export function fail(text) {
+    return `${red("✗")} ${text}`;
+}
+export function info(text) {
+    return `${dim("–")} ${text}`;
+}
+export function warn(text) {
+    return `${yellow("!")} ${text}`;
+}
+/** A repair the user can run, under the line that reported the problem. */
+export function fix(text) {
+    return `  ${yellow(`→ ${text}`)}`;
+}
+export function step(n, total, title) {
+    return `\nStep ${n} of ${total} · ${bold(title)}`;
+}
+function charWidth(code) {
+    if (code >= 0x0300 && code <= 0x036f)
+        return 0;
+    const wide = (code >= 0x1100 && code <= 0x115f) ||
+        (code >= 0x2e80 && code <= 0xa4cf) ||
+        (code >= 0xac00 && code <= 0xd7a3) ||
+        (code >= 0xf900 && code <= 0xfaff) ||
+        (code >= 0xfe30 && code <= 0xfe6f) ||
+        (code >= 0xff00 && code <= 0xff60) ||
+        (code >= 0xffe0 && code <= 0xffe6) ||
+        (code >= 0x1f300 && code <= 0x1f64f) ||
+        (code >= 0x1f900 && code <= 0x1f9ff);
+    return wide ? 2 : 1;
+}
+export function width(text) {
+    let total = 0;
+    for (const char of text)
+        total += charWidth(char.codePointAt(0));
+    return total;
+}
+export function box(text) {
+    const rule = "─".repeat(width(text) + 2);
+    return [`  ╭${rule}╮`, `  │ ${text} │`, `  ╰${rule}╯`].join("\n");
+}
+function nextLine(action, tail) {
+    return humanLayout() ? `Next  ${action}${tail}` : `Next: ${action}${tail}`;
+}
+/** A command to type. */
+export function next(command, note) {
+    return nextLine(cmd(command), note === undefined ? "" : `   ${dim(note)}`);
+}
+/** An instruction to follow. Not cyan: cyan means "type this". */
+export function nextHint(instruction) {
+    return nextLine(bold(instruction), "");
+}
+export function tilde(path) {
+    const home = homedir();
+    if (home === "")
+        return path;
+    if (path === home)
+        return "~";
+    return path.startsWith(home + sep) ? `~${path.slice(home.length)}` : path;
+}
+/** Home-relative for a human; pipes and tests get the path they can act on. */
+export function shortPath(path) {
+    return humanLayout() ? tilde(path) : path;
+}
+/** All but the first three digits, so a screenshot cannot leak the number. */
+export function maskNumber(digits) {
+    const kept = digits.slice(0, 3);
+    const body = kept + "x".repeat(Math.max(0, digits.length - kept.length));
+    const groups = (body.slice(2).match(/.{1,3}/g) ?? []).join(" ");
+    return `+${body.slice(0, 2)}${groups === "" ? "" : ` ${groups}`}`;
+}
+/** A wrapped line would outlive the erase, which clears one physical line. */
+function clamp(text) {
+    const room = (process.stderr.columns ?? 80) - 2;
+    if (width(text) <= room)
+        return text;
+    let out = "";
+    let used = 0;
+    for (const char of text) {
+        const size = charWidth(char.codePointAt(0));
+        if (used + size > room - 1)
+            break;
+        out += char;
+        used += size;
+    }
+    return `${out}…`;
+}
+/**
+ * Animated only at a terminal: a `\r` rewrite is noise in a pipe, so there the
+ * text is printed once and the final line replaces nothing.
+ */
+export function spinner(text) {
+    if (process.stderr.isTTY !== true) {
+        process.stderr.write(`${text}\n`);
+        return {
+            update: () => { },
+            stop: (final) => {
+                if (final !== undefined)
+                    process.stderr.write(`${final}\n`);
+            },
+        };
+    }
+    let current = text;
+    let frame = 0;
+    const render = () => {
+        process.stderr.write(`${CLEAR_LINE}${brand(FRAMES[frame % FRAMES.length])} ${clamp(current)}`);
+    };
+    render();
+    const timer = setInterval(() => {
+        frame++;
+        render();
+    }, FRAME_MS);
+    timer.unref();
+    return {
+        update: (next) => {
+            current = next;
+            render();
+        },
+        stop: (final) => {
+            clearInterval(timer);
+            process.stderr.write(CLEAR_LINE);
+            if (final !== undefined)
+                process.stderr.write(`${final}\n`);
+        },
+    };
+}

package/dist/whatsapp.js

@@ -165,6 +165,7 @@ export class WhatsAppService {
     account = null;
     lastInboundAt = null;
     initialSyncDone = false;
+    historyReceived = false;
     syncDeadline = null;
     syncWaiters = [];
     historyWaiters = [];
@@ -231,6 +232,13 @@ export class WhatsAppService {
         await this.flushStore();
         this.teardownSocket();
     }
+    /** True once WhatsApp has delivered at least one history-sync batch. */
+    hasHistory() {
+        return this.historyReceived;
+    }
+    storeCounts() {
+        return { chats: this.store.chats.size, contacts: this.store.contacts.size, messages: this.store.messages.size };
+    }
     getStatus() {
         const info = {
             status: this.status,
@@ -255,7 +263,7 @@ export class WhatsAppService {
         return this.guarded(async () => {
             this.ensureConnected();
             await this.waitForSync();
-            const chats = [...this.store.chats.values()]
+            const chats = this.knownChats()
                 .filter((chat) => this.matchesChatFilter(chat, filter))
                 .sort((a, b) => this.chatActivity(b) - this.chatActivity(a))
                 .slice(0, limit)
@@ -727,6 +735,7 @@ export class WhatsAppService {
                 this.ingestChat(chat);
             const stored = this.ingestMessages(messages ?? []);
             void this.appendHistory(stored);
+            this.historyReceived = true;
             this.releaseHistoryWaiters();
             if (isLatest === true || progress === 100)
                 this.markSyncDone();
@@ -1136,8 +1145,24 @@ export class WhatsAppService {
         const last = ring && ring.length > 0 ? this.store.messages.get(ring[ring.length - 1]) : undefined;
         return last ?? null;
     }
+    /**
+     * Every chat WhatsApp described, plus one for any chat that only ever
+     * arrived as messages: a chat with messages must never be invisible.
+     */
+    knownChats() {
+        const chats = [...this.store.chats.values()];
+        for (const jid of this.store.byChat.keys()) {
+            if (!this.store.chats.has(jid))
+                chats.push({ id: jid });
+        }
+        return chats;
+    }
     chatActivity(chat) {
-        return protoNumber(chat.conversationTimestamp) ?? 0;
+        const described = protoNumber(chat.conversationTimestamp);
+        if (described !== undefined && described !== null)
+            return described;
+        const last = this.lastMessageOf(this.canonical(chat.id ?? ""));
+        return last ? Math.floor(messageTimestampMs(last) / 1000) : 0;
     }
     matchesChatFilter(chat, filter) {
         const archived = Boolean(chat.archived);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wazap-mcp",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "WhatsApp for your AI agent. MCP server over Baileys: pairing-code login, 22 tools, stdio or token-protected HTTP.",
   "license": "MIT",
   "author": "Răzvan Girgiz",
@@ -27,6 +27,7 @@
   "files": [
     "dist",
     "README.md",
+    "AGENT.md",
     "LICENSE"
   ],
   "scripts": {