wazap-mcp 0.9.5 → 0.9.7

package/README.md

@@ -25,6 +25,23 @@ 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 the path your harness prefers
+
+| Harness | Fastest path |
+| --- | --- |
+| Claude Code | `/plugin marketplace add razvangirgiz/wazap`, then `/plugin install wazap@wazap` |
+| Claude Desktop | download `wazap-<version>.mcpb` from [Releases](https://github.com/razvangirgiz/wazap/releases) and double-click it |
+| Gemini CLI | `gemini extensions install https://github.com/razvangirgiz/wazap` |
+| Cursor | the [Install in Cursor](#other-mcp-clients) badge, then `npx wazap-mcp skills install cursor` |
+| VS Code | the [Install in VS Code](#other-mcp-clients) badge |
+| Codex CLI | `npx wazap-mcp connect codex`, then `npx wazap-mcp skills install codex` |
+| OpenCode | `npx wazap-mcp connect opencode`, then `npx wazap-mcp skills install opencode` |
+| Windsurf | `npx wazap-mcp connect windsurf` |
+| Anything else | the MCP entry `npx -y wazap-mcp` over stdio, or a [self-hosted](#self-host) URL |
+
+Each of those registers the server. Linking the WhatsApp account is a separate,
+one-time step in every one of them: `npx wazap-mcp login`.
+
 Or have your agent do it. Paste this:
 
 *Set up WhatsApp for me: run `npx wazap-mcp setup --agent` and follow what it prints.*
@@ -63,11 +80,25 @@ it would write.
 | `codex` | `[mcp_servers.whatsapp]` in `~/.codex/config.toml` |
 | `vscode` | `./.vscode/mcp.json`, for the current workspace |
 | `gemini` | `~/.gemini/settings.json` |
+| `windsurf` | `~/.codeium/windsurf/mcp_config.json` |
+| `opencode` | `mcp.whatsapp` in `~/.config/opencode/opencode.json` |
 | anything remote | client's MCP URL field: `https://your-host/mcp` with header `Authorization: Bearer <token>` (see [Self-host](#self-host)) |
 
-Any MCP client works the same way: the command is `npx -y wazap-mcp`, the transport
-is stdio. Tell the agent to call `learn` first — it returns the id formats, the
-workflows and every error code with what to do about it.
+### Other MCP clients
+
+Cursor and VS Code install from a link:
+
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.png)](cursor://anysphere.cursor-deeplink/mcp/install?name=whatsapp&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIndhemFwLW1jcCJdfQ)
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](vscode:mcp/install?%7B%22name%22%3A%22whatsapp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22wazap-mcp%22%5D%7D)
+
+Both carry the same entry `connect` writes. Where a custom scheme is stripped
+before you can click it, VS Code also takes
+[the https form](https://insiders.vscode.dev/redirect/mcp/install?name=whatsapp&config=%7B%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22wazap-mcp%22%5D%7D).
+`node scripts/badges.mjs` reprints all three.
+
+Any other MCP client works the same way: the command is `npx -y wazap-mcp`, the
+transport is stdio. Tell the agent to call `learn` first — it returns the id
+formats, the workflows and every error code with what to do about it.
 
 <details>
 <summary>The raw entries, for editing by hand</summary>
@@ -83,8 +114,9 @@ workflows and every error code with what to do about it.
 }
 ```
 
-Claude Desktop, Cursor and Gemini CLI take exactly that. VS Code nests it under
-`servers` and wants a `"type": "stdio"` alongside `command`. Codex CLI is TOML:
+Claude Desktop, Cursor, Gemini CLI and Windsurf take exactly that. VS Code nests
+it under `servers` and wants a `"type": "stdio"` alongside `command`. Codex CLI
+is TOML:
 
 ```toml
 [mcp_servers.whatsapp]
@@ -92,10 +124,55 @@ command = "npx"
 args = ["-y", "wazap-mcp"]
 ```
 
+OpenCode takes the command and its arguments as one array, under `mcp`:
+
+```json
+{
+  "mcp": {
+    "whatsapp": { "type": "local", "command": ["npx", "-y", "wazap-mcp"] }
+  }
+}
+```
+
 </details>
 
 The `skills/` folder follows the [Agent Skills](https://agentskills.io) format, so Codex, Cursor and other skill-aware agents can load the same five skills.
 
+### Gemini CLI
+
+```bash
+gemini extensions install https://github.com/razvangirgiz/wazap
+```
+
+That reads `gemini-extension.json` at the repo root, so it registers the MCP
+server and loads `GEMINI.md` — the five skills below, concatenated, because the
+Gemini CLI takes one context file per extension rather than a skills directory.
+`wazap connect gemini` writes the server alone, without the context.
+
+`GEMINI.md` is generated: `npm run context:build` rebuilds it from
+`skills/*/SKILL.md`, and a test fails if the two have drifted, so a workflow is
+only ever edited in its skill.
+
+### Claude Desktop, without a terminal
+
+Download `wazap-<version>.mcpb` from [Releases](https://github.com/razvangirgiz/wazap/releases)
+and double-click it. Claude Desktop installs the server, its Node dependencies
+and the icon, and shows two settings: **Read-only**, ticked, and **Data
+directory**, empty. `wazap connect claude-desktop` does the same job by editing
+`claude_desktop_config.json`, and needs `npx` at launch; the bundle does not.
+
+Linking the account still needs a terminal once: `npx wazap-mcp login`. The
+bundle reads the session that login writes to `~/.wazap`.
+
+Untick **Read-only** to let Claude send. It ships ticked because a bundle that
+can message people from your number before you have said so is the wrong
+default, and because the setting cannot be left unanswered: the manifest format
+has no way to omit an argument, so the box you see is the answer the server gets.
+
+Build it yourself with `npm run bundle:mcpb`, which stages `dist/`, the
+manifest, the icon and a fresh production `node_modules`, then packs them with
+[`@anthropic-ai/mcpb`](https://github.com/modelcontextprotocol/mcpb).
+
 ## Tools
 
 | Tool | Kind | What it does |
@@ -103,8 +180,8 @@ The `skills/` folder follows the [Agent Skills](https://agentskills.io) format,
 | `learn` | read | The guide to every tool, id format and error code. Call it first. |
 | `get_status` | read | Connection status, sync state, linked account, named-contact count, versions, data dir. |
 | `list_chats` | read | Conversations newest-first; filter `all`/`unread`/`groups`/`individual`/`archived`. |
-| `read_messages` | read | Messages in a chat; `before` pages further back, pulling older history from the phone. |
-| `get_recent_messages` | read | Everything from the last N hours, grouped by chat. The catch-up tool. `include_system` adds WhatsApp's own notices. |
+| `read_messages` | read | Messages in a chat; `before` pages further back, pulling older history from the phone; `types` narrows to one or more message types, e.g. `["call"]`. |
+| `get_recent_messages` | read | Everything from the last N hours, grouped by chat. The catch-up tool. `include_system` adds WhatsApp's own notices, `types` narrows to one or more message types. |
 | `search_messages` | read | Text search across the locally held messages. |
 | `get_message` | read | One message in full, with its quoted message and reactions. |
 | `search_contacts` | read | Find contacts by name or number. |
@@ -148,7 +225,22 @@ Install everything (server and skills) as a Claude Code plugin:
 /plugin install wazap@wazap
 ```
 
-Or copy `skills/<name>/` into any skills directory your agent reads.
+Every other harness gets them with one command:
+
+```bash
+npx wazap-mcp skills install codex     # or cursor, opencode, agents
+```
+
+| Harness | Where the five directories land |
+| --- | --- |
+| `claude-code` | nowhere — the plugin above already carries them |
+| `codex` | `~/.agents/skills/`, the directory Codex documents for user skills. Cursor and OpenCode read it too |
+| `cursor` | `~/.cursor/skills/` |
+| `opencode` | `~/.config/opencode/skills/` |
+| `agents` | `./.agents/skills/`, in the current project, for anything that reads the cross-tool convention |
+
+Re-running overwrites, so an upgrade is the same command. `--dry-run` lists
+what it would copy.
 
 ## Errors
 
@@ -312,6 +404,12 @@ Flags beat environment variables, which beat `<data-dir>/.env`.
   state sync, and only to a connection asking for it from scratch. If contacts
   read as phone numbers and `get_status` shows `contacts_named: 0`, ask for it
   again with the `sync_contacts` tool or `wazap contacts resync`.
+- **Calls are WhatsApp calls only.** A call shows up as a message with
+  `type: "call"`, carrying its kind, direction, outcome and duration. WhatsApp's
+  own call log and the missed-call notices arrive on their own; a call that
+  starts and ends while wazap is running is recorded live, so calls placed or
+  received while it is stopped can be missing entirely. A cellular call from the
+  phone's dialler is never visible, on any device.
 - **Your phone must stay reachable.** A linked device stops receiving once the
   phone has been offline long enough; `get_status` says so in `hint`.
 

package/dist/calls.js

@@ -0,0 +1,153 @@
+/**
+ * Live calls. Baileys reports a call as a stream of status events and never as
+ * a message, so this folds that stream into one entry per call and hands back a
+ * synthetic WAMessage the ordinary store path can carry. Pure: no timers, no
+ * socket, no store, so a test can drive it by feeding events and a clock.
+ */
+import { proto } from "baileys";
+/** A ringing call nobody answered and nobody hung up: the terminal event was lost. */
+const RING_TIMEOUT_MS = 2 * 60_000;
+/**
+ * An answered call is not expired at the ring timeout, which would invent a
+ * two-minute duration for a conversation still going on. It is only cut loose
+ * once it has run longer than any real call does.
+ */
+const ANSWERED_CAP_MS = 6 * 3_600_000;
+/**
+ * How many settled call ids to remember. They are what makes a repeated
+ * terminal event store nothing twice, and the process is long-lived, so the set
+ * has to forget its oldest eventually rather than grow for the whole session.
+ */
+const SETTLED_MEMORY = 500;
+/** Marks a stored message as one wazap tracked itself. See `isTrackedCall`. */
+const TRACKED_ID_PREFIX = "call_";
+const OUTCOME_CODES = {
+    answered: proto.Message.CallLogMessage.CallOutcome.CONNECTED,
+    rejected: proto.Message.CallLogMessage.CallOutcome.REJECTED,
+    missed: proto.Message.CallLogMessage.CallOutcome.MISSED,
+    unanswered: proto.Message.CallLogMessage.CallOutcome.MISSED,
+};
+function noAnswer(direction) {
+    return direction === "outgoing" ? "unanswered" : "missed";
+}
+/**
+ * `from` arrives as a LID as often as a phone jid, and either can carry a
+ * device suffix, so only the user part of the two jids is comparable.
+ */
+function samePerson(one, other) {
+    const user = (jid) => (jid.split("@")[0] ?? "").split(":")[0] ?? "";
+    const left = user(one);
+    return left.length > 0 && left === user(other);
+}
+export class CallTracker {
+    calls = new Map();
+    settled = new Set();
+    get pending() {
+        return this.calls.size;
+    }
+    /** The entry to store once the call reaches a terminal state, else null. */
+    observe(event, ownJid, now) {
+        if (!event.id || this.settled.has(event.id))
+            return null;
+        const call = this.calls.get(event.id) ?? this.begin(event, ownJid, now);
+        call.lastSeen = now;
+        switch (event.status) {
+            case "accept":
+                call.acceptedAt = now;
+                return null;
+            case "reject":
+                return this.finish(call, "rejected");
+            case "timeout":
+                return this.finish(call, noAnswer(call.direction));
+            case "terminate":
+                return call.acceptedAt === undefined
+                    ? this.finish(call, noAnswer(call.direction))
+                    : this.finish(call, "answered", Math.round((now - call.acceptedAt) / 1000));
+            default:
+                return null;
+        }
+    }
+    /** Entries for calls whose terminal event never arrived. */
+    expire(now) {
+        const done = [];
+        for (const call of [...this.calls.values()]) {
+            if (call.acceptedAt === undefined) {
+                if (now - call.lastSeen >= RING_TIMEOUT_MS)
+                    done.push(this.finish(call, noAnswer(call.direction)));
+            }
+            else if (now - call.acceptedAt >= ANSWERED_CAP_MS) {
+                done.push(this.finish(call, "answered", Math.round((now - call.acceptedAt) / 1000)));
+            }
+        }
+        return done;
+    }
+    /**
+     * An event for an unknown call-id starts a pending call from whatever it
+     * carries, so a restart in the middle of one still records something. Only
+     * the offer names isVideo and the group, which is why baileys replays them
+     * from its own cache onto the later events of the same call.
+     */
+    begin(event, ownJid, now) {
+        const offered = event.date instanceof Date ? event.date.getTime() : Number.NaN;
+        const chat = (event.isGroup ? (event.groupJid ?? event.chatId) : event.chatId) || event.from;
+        const call = {
+            callId: event.id,
+            chatId: chat,
+            at: Number.isFinite(offered) ? offered : now,
+            kind: event.isVideo ? "video" : "voice",
+            direction: samePerson(event.from, ownJid) ? "outgoing" : "incoming",
+            lastSeen: now,
+        };
+        this.calls.set(event.id, call);
+        return call;
+    }
+    finish(call, outcome, durationSeconds) {
+        this.calls.delete(call.callId);
+        this.settled.add(call.callId);
+        if (this.settled.size > SETTLED_MEMORY) {
+            const oldest = this.settled.values().next().value;
+            if (oldest !== undefined)
+                this.settled.delete(oldest);
+        }
+        return {
+            callId: call.callId,
+            chatId: call.chatId,
+            at: call.at,
+            kind: call.kind,
+            direction: call.direction,
+            outcome,
+            ...(durationSeconds === undefined ? {} : { durationSeconds }),
+        };
+    }
+}
+/**
+ * True for a message this tracker built. The tracker emits one entry per call
+ * id, so two of these are always two different calls however close together
+ * they fall, which is the one thing a dedupe by timestamp cannot know.
+ */
+export function isTrackedCall(raw) {
+    return (raw.key?.id ?? "").startsWith(TRACKED_ID_PREFIX);
+}
+/**
+ * The entry as WhatsApp would have logged it, so snapshot, history JSONL, views
+ * and list_chats all carry a live call with no machinery of their own. The
+ * fields have to survive an encode/decode round trip, because that is what
+ * persistence does to it.
+ */
+export function callMessage(entry) {
+    return {
+        key: {
+            remoteJid: entry.chatId,
+            fromMe: entry.direction === "outgoing",
+            id: `${TRACKED_ID_PREFIX}${entry.callId}`,
+        },
+        messageTimestamp: Math.floor(entry.at / 1000),
+        message: {
+            callLogMesssage: {
+                isVideo: entry.kind === "video",
+                callOutcome: OUTCOME_CODES[entry.outcome],
+                ...(entry.durationSeconds === undefined ? {} : { durationSecs: entry.durationSeconds }),
+            },
+        },
+    };
+}

package/dist/config.js

@@ -30,6 +30,7 @@ const COMMAND_ARGS = {
     connect: [1],
     config: [0, 2],
     contacts: [1],
+    skills: [2],
 };
 const COMMANDS = Object.keys(COMMAND_ARGS);
 export function defaultDataDir() {
@@ -44,6 +45,17 @@ function asInt(value, fallback) {
     const n = Number.parseInt((value ?? "").trim(), 10);
     return Number.isFinite(n) ? n : fallback;
 }
+/**
+ * A user_config slot the person never filled in reaches us as the literal
+ * `${user_config.data_dir}`: the Claude Desktop bundle substitutes what it has
+ * and leaves the rest alone. An unanswered question is not a data directory.
+ */
+function dropUnfilledTemplates() {
+    for (const [key, value] of Object.entries(process.env)) {
+        if (key.startsWith("WAZAP_") && /^\$\{[^}]*\}$/.test(value ?? ""))
+            delete process.env[key];
+    }
+}
 /**
  * A human at a terminal running bare `wazap` wants to see where they stand, not
  * a silent MCP server on stdin. Everything else serves, including `wazap serve`.
@@ -88,6 +100,7 @@ export function parseCli(argv = process.argv.slice(2)) {
         return { kind: "help" };
     if (values.version)
         return { kind: "version" };
+    dropUnfilledTemplates();
     const [first, ...args] = positionals;
     if (first !== undefined && !COMMANDS.includes(first)) {
         throw new WazapError("INVALID_ID", `Unknown command "${first}".`, "Run `wazap --help`");

package/dist/connect.js

@@ -58,7 +58,7 @@ export const CLIENTS = [
         file: () => join(process.cwd(), ".vscode", "mcp.json"),
         format: "json",
         keyPath: ["servers", "whatsapp"],
-        extra: { type: "stdio" },
+        value: (entry) => ({ type: "stdio", ...entry }),
         next: "Written to ./.vscode/mcp.json for this workspace. Reload the VS Code window.",
         detect: (probe) => probe.onPath("code"),
     },
@@ -71,6 +71,27 @@ export const CLIENTS = [
         next: "Restart the Gemini CLI.",
         detect: (probe) => probe.exists(join(homedir(), ".gemini")),
     },
+    {
+        name: "windsurf",
+        describe: "Windsurf",
+        file: () => join(homedir(), ".codeium", "windsurf", "mcp_config.json"),
+        format: "json",
+        keyPath: ["mcpServers", "whatsapp"],
+        next: "Refresh the MCP servers in Windsurf's Cascade panel.",
+        detect: (probe) => probe.exists(join(homedir(), ".codeium", "windsurf")),
+    },
+    {
+        name: "opencode",
+        describe: "OpenCode",
+        file: () => join(homedir(), ".config", "opencode", "opencode.json"),
+        format: "json",
+        keyPath: ["mcp", "whatsapp"],
+        // OpenCode takes one array where the others take a command and its args,
+        // and its schema refuses anything else under the key.
+        value: (entry) => ({ type: "local", command: [entry.command, ...entry.args] }),
+        next: "Restart OpenCode.",
+        detect: (probe) => probe.exists(join(homedir(), ".config", "opencode")),
+    },
 ];
 export const CLIENT_NAMES = CLIENTS.map((client) => client.name).join(", ");
 const OTHER_CLIENTS = CLIENTS.slice(1)
@@ -173,7 +194,7 @@ function writeJsonEntry(spec, entry, dryRun) {
         }
         doc = parsed;
     }
-    const value = { ...spec.extra, command: entry.command, args: entry.args };
+    const value = spec.value?.(entry) ?? { command: entry.command, args: entry.args };
     setIn(doc, spec.keyPath, value);
     // 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, " ");

package/dist/index.js

@@ -3,6 +3,7 @@ import { BANNER } from "./banner.js";
 import { runContacts, runGreet, runLogin, runLogout, runServe, runStatus } from "./cli.js";
 import { WAZAP_VERSION, parseCli, pickDefaultAction } from "./config.js";
 import { CLIENT_NAMES, runConnect } from "./connect.js";
+import { SKILL_TARGET_NAMES, runSkills } from "./skills.js";
 import { runSetup } from "./setup.js";
 import { runConfig } from "./settings.js";
 import { WazapError } from "./errors.js";
@@ -15,12 +16,14 @@ Usage:
   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 skills install <harness> [--dry-run]               Copy the five skills into a harness
   wazap config [writes on|off]                             Show the effective settings, or allow/refuse writes
   wazap contacts resync                                    Fetch the phone's address book from WhatsApp again
   wazap status [--live] [--json]                           Check the install, the session and the server
   wazap logout                                             Unlink and delete local credentials
 
 Clients for wazap connect: ${CLIENT_NAMES}.
+Harnesses for wazap skills install: ${SKILL_TARGET_NAMES}.
 
 Options:
   --data-dir <path>   Where wazap keeps its data (default ~/.wazap, or $WAZAP_DATA_DIR)
@@ -32,7 +35,7 @@ Options:
   --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
+  --dry-run           With connect or skills install: 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
   --writes            Allow the agent to write, without login asking
@@ -73,6 +76,9 @@ async function main() {
         case "connect":
             runConnect(config);
             return;
+        case "skills":
+            runSkills(config);
+            return;
         case "config":
             runConfig(config);
             return;

package/dist/messages.js

@@ -165,6 +165,83 @@ function stubKind(raw) {
         return "deleted";
     return stub === proto.WebMessageInfo.StubType.UNKNOWN ? undefined : "system";
 }
+const CALL_OUTCOMES = {
+    [proto.Message.CallLogMessage.CallOutcome.CONNECTED]: "answered",
+    [proto.Message.CallLogMessage.CallOutcome.ACCEPTED_ELSEWHERE]: "answered",
+    [proto.Message.CallLogMessage.CallOutcome.ONGOING]: "answered",
+    [proto.Message.CallLogMessage.CallOutcome.REJECTED]: "rejected",
+    [proto.Message.CallLogMessage.CallOutcome.MISSED]: "no answer",
+    [proto.Message.CallLogMessage.CallOutcome.FAILED]: "no answer",
+    [proto.Message.CallLogMessage.CallOutcome.SILENCED_BY_DND]: "no answer",
+    [proto.Message.CallLogMessage.CallOutcome.SILENCED_UNKNOWN_CALLER]: "no answer",
+};
+const CALL_STUB_KINDS = {
+    [proto.WebMessageInfo.StubType.CALL_MISSED_VOICE]: "voice",
+    [proto.WebMessageInfo.StubType.CALL_MISSED_VIDEO]: "video",
+    [proto.WebMessageInfo.StubType.CALL_MISSED_GROUP_VOICE]: "voice",
+    [proto.WebMessageInfo.StubType.CALL_MISSED_GROUP_VIDEO]: "video",
+};
+function settle(outcome, direction) {
+    if (outcome !== "no answer")
+        return outcome;
+    return direction === "outgoing" ? "unanswered" : "missed";
+}
+/**
+ * Calls never reach the RULES table: `getContentType` looks for a key
+ * containing "Message" and the proto field is spelled `callLogMesssage`, so it
+ * reports undefined and a call arriving next to messageContextInfo would render
+ * as "[system message]". Hence this runs before the table, not inside it.
+ */
+export function callInfo(raw) {
+    const direction = raw.key?.fromMe ? "outgoing" : "incoming";
+    const content = unwrapEnvelopes(raw.message);
+    const logged = content?.callLogMesssage;
+    if (logged) {
+        const outcome = settle(CALL_OUTCOMES[logged.callOutcome ?? -1] ?? "no answer", direction);
+        const seconds = protoNumber(logged.durationSecs);
+        const participants = (logged.participants ?? []).flatMap((one) => (one.jid ? [one.jid] : []));
+        return {
+            kind: logged.isVideo ? "video" : "voice",
+            direction,
+            outcome,
+            ...(outcome === "answered" && seconds !== undefined && seconds > 0 ? { duration_seconds: seconds } : {}),
+            ...(participants.length > 0 ? { participants } : {}),
+        };
+    }
+    const stub = CALL_STUB_KINDS[raw.messageStubType ?? -1];
+    if (stub)
+        return { kind: stub, direction, outcome: settle("no answer", direction) };
+    if (content?.call != null)
+        return { kind: "voice", direction, outcome: settle("no answer", direction) };
+    return undefined;
+}
+/**
+ * Baileys' own stand-in for a group call offer. It says a call happened and
+ * nothing else, so anything that names an outcome outranks it.
+ */
+export function isCallPlaceholder(raw) {
+    const content = unwrapEnvelopes(raw.message);
+    return content?.call != null && content.callLogMesssage == null;
+}
+function durationLabel(seconds) {
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 60)
+        return `${minutes} min`;
+    const hours = Math.floor(minutes / 60);
+    const rest = minutes % 60;
+    return rest === 0 ? `${hours}h` : `${hours}h ${rest} min`;
+}
+/** An outcome you caused reads as a suffix; one that happened to you is an adjective. */
+export function callText(info) {
+    const duration = info.duration_seconds === undefined ? "" : ` · ${durationLabel(info.duration_seconds)}`;
+    if (info.direction === "outgoing") {
+        return `[outgoing ${info.kind} call${info.outcome === "answered" ? duration : ` · ${info.outcome}`}]`;
+    }
+    const adjective = info.outcome === "answered" ? "" : `${info.outcome} `;
+    return `[${adjective}${info.kind} call${duration}]`;
+}
 function resolve(value, content) {
     return typeof value === "function" ? value(content) : value;
 }
@@ -199,6 +276,8 @@ export function isStubEvent(raw) {
     return stubKind(raw) !== undefined;
 }
 export function messageType(raw) {
+    if (callInfo(raw))
+        return "call";
     const stub = stubKind(raw);
     if (stub === "deleted")
         return "deleted";
@@ -210,6 +289,11 @@ export function messageType(raw) {
 }
 /** Never empty: media and system messages get a placeholder like "[sticker]". */
 export function messageText(raw) {
+    const call = callInfo(raw);
+    // The placeholder only says a group call was offered, so naming an outcome
+    // ("missed") would claim something the payload never carried.
+    if (call)
+        return isCallPlaceholder(raw) ? "[group call]" : callText(call);
     const content = unwrapEnvelopes(raw.message);
     const { rule, content: node } = ruleFor(content);
     if (rule === UNKNOWN) {
@@ -295,6 +379,7 @@ export function buildMessageView(raw, ctx) {
     const media = mediaInfo(raw);
     const context = contextInfo(raw);
     const quoted = context?.quotedMessage ? quotedView(context, ctx) : undefined;
+    const call = callInfo(raw);
     const view = {
         message_id: messageIdFor(raw.key, ctx.chatId),
         chat_id: ctx.chatId,
@@ -316,6 +401,11 @@ export function buildMessageView(raw, ctx) {
         view.media = media;
     if (quoted)
         view.quoted = quoted;
+    if (call) {
+        view.call = call.participants
+            ? { ...call, participants: call.participants.map((jid) => ctx.canonical(jid)) }
+            : call;
+    }
     if (ctx.reactions.length > 0)
         view.reactions = ctx.reactions;
     return view;

package/dist/skills.js

@@ -0,0 +1,90 @@
+import { cpSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { WazapError } from "./errors.js";
+import { say } from "./logger.js";
+import { info, next, nextHint, ok, shortPath } from "./ui.js";
+/**
+ * Each path is the one that harness's own docs name today. Codex is the
+ * one that moved: `~/.codex/skills` still loads, but its docs call that
+ * location deprecated and put user skills in `~/.agents/skills`, which Cursor
+ * and OpenCode read too.
+ */
+export const SKILL_TARGETS = [
+    {
+        name: "claude-code",
+        describe: "Claude Code",
+        dir: null,
+        next: "/plugin marketplace add razvangirgiz/wazap",
+    },
+    {
+        name: "codex",
+        describe: "Codex CLI",
+        dir: () => join(homedir(), ".agents", "skills"),
+        next: "Restart Codex. Cursor and OpenCode read this directory too.",
+    },
+    {
+        name: "cursor",
+        describe: "Cursor",
+        dir: () => join(homedir(), ".cursor", "skills"),
+        next: "Reload the Cursor window.",
+    },
+    {
+        name: "opencode",
+        describe: "OpenCode",
+        dir: () => join(homedir(), ".config", "opencode", "skills"),
+        next: "Restart OpenCode.",
+    },
+    {
+        name: "agents",
+        describe: "This project, any agent",
+        dir: () => join(process.cwd(), ".agents", "skills"),
+        next: "Commit .agents/skills to share them with whoever clones this repo.",
+    },
+];
+export const SKILL_TARGET_NAMES = SKILL_TARGETS.map((target) => target.name).join(", ");
+/** The `skills/` folder shipped in the npm package, next to `dist/`. */
+function packagedSkills() {
+    return fileURLToPath(new URL("../skills", import.meta.url));
+}
+function skillNames() {
+    try {
+        return readdirSync(packagedSkills(), { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        throw new WazapError("FILE_NOT_FOUND", "This wazap install ships no skills/ directory.", "Upgrade with `npm i -g wazap-mcp@latest`, or run this from a checkout.");
+    }
+}
+function findSkillTarget(name) {
+    const target = SKILL_TARGETS.find((candidate) => candidate.name === name);
+    if (!target) {
+        throw new WazapError("INVALID_ID", `Unknown harness "${name}".`, `Pick one of: ${SKILL_TARGET_NAMES}`);
+    }
+    return target;
+}
+export function runSkills(config) {
+    if (config.args[0] !== "install") {
+        throw new WazapError("INVALID_ID", `Unknown skills command "${config.args[0]}".`, "Run `wazap skills install <harness>`");
+    }
+    const target = findSkillTarget(config.args[1] ?? "");
+    if (target.dir === null) {
+        say(info(`${target.describe} loads these skills from the wazap plugin, along with the MCP server.`));
+        say(next(target.next));
+        return;
+    }
+    const dir = target.dir();
+    const names = skillNames();
+    say(info(`${target.describe} · ${config.dryRun ? "would copy into" : "copying into"} ${shortPath(dir)}`));
+    for (const name of names) {
+        // Overwriting is the point: this is how an upgrade reaches an already
+        // installed harness, and re-running it must land in the same place.
+        if (!config.dryRun)
+            cpSync(join(packagedSkills(), name), join(dir, name), { recursive: true, force: true });
+        say(`  ${ok(name)}`);
+    }
+    say(nextHint(target.next));
+}

package/dist/tools.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { asWazapError, ERROR_GUIDE } from "./errors.js";
+import { MESSAGE_TYPES } from "./wa-types.js";
 function tool(def) {
     return { ...def, handler: def.handler };
 }
@@ -25,6 +26,10 @@ const messageId = z
     .string()
     .min(5)
     .describe('Message id from read_messages / search_messages / get_message, e.g. "false_4072...@s.whatsapp.net_3EB0..."');
+const messageTypes = z
+    .array(z.enum([...MESSAGE_TYPES]))
+    .optional()
+    .describe('Keep only these message types; omit for every type. The limit counts matching messages, so ["call"] returns that many calls, not that many messages of which some are calls.');
 const GUIDE = `# wazap — WhatsApp for your AI agent
 
 Read/write access to the user's linked WhatsApp account: chats, messages, media,
@@ -61,6 +66,11 @@ which look like a phone number and are not one.
 WhatsApp's own notices (device linking, group membership, encryption) have
 \`type: "system"\` and are left out of get_recent_messages unless you pass
 include_system: true.
+A WhatsApp call is a message with \`type: "call"\` carrying
+\`call: {kind, direction, outcome, duration_seconds}\`, reading as
+"[voice call · 6 min]" or "[missed voice call]".
+read_messages and get_recent_messages take \`types\` to narrow to a subset of
+these types, e.g. \`types: ["call"]\` for the call log of a chat.
 \`timestamp\` is ISO 8601 with the machine's UTC offset, \`age\` is human-readable.
 
 ## Errors
@@ -142,11 +152,12 @@ older history when the local store runs out, which takes a few seconds.`,
             chat_id: chatId,
             limit: z.number().int().min(1).max(200).default(20).describe("Maximum number of messages (1-200)"),
             before: messageId.optional().describe("Return the messages immediately older than this message_id"),
+            types: messageTypes,
         },
         write: false,
-        handler: async ({ chat_id, limit, before }, wa) => {
-            const result = await wa.readMessages(chat_id, limit, before);
-            return ok(renderMessages(`Messages in ${chat_id}`, result.data), synced(result, { chat_id, count: result.data.length, messages: result.data }));
+        handler: async ({ chat_id, limit, before, types }, wa) => {
+            const result = await wa.readMessages(chat_id, limit, before, types);
+            return ok(renderMessages(`Messages in ${chat_id}`, result.data), synced(result, { chat_id, types, count: result.data.length, messages: result.data }));
         },
     }),
     tool({
@@ -166,15 +177,17 @@ out so the counts are conversation; pass include_system to see them.`,
                 .boolean()
                 .default(false)
                 .describe("Include WhatsApp's own system notices, which are excluded from the bodies and the counts by default"),
+            types: messageTypes,
         },
         write: false,
-        handler: async ({ hours, filter, include_system }, wa) => {
-            const result = await wa.getRecentMessages(hours, filter, include_system);
+        handler: async ({ hours, filter, include_system, types }, wa) => {
+            const result = await wa.getRecentMessages(hours, filter, include_system, types);
             const messageCount = result.data.reduce((n, c) => n + c.messages.length, 0);
             return ok(renderConversations(result.data, hours), synced(result, {
                 hours,
                 filter,
                 include_system,
+                types,
                 conversation_count: result.data.length,
                 message_count: messageCount,
                 conversations: result.data,

package/dist/wa-types.js

@@ -1,2 +1,20 @@
 /** Public shapes of the WhatsApp service: what the MCP tools and the CLI consume. */
-export {};
+/** The zod enum the tools expose derives from this, so the two cannot drift. */
+export const MESSAGE_TYPES = [
+    "text",
+    "image",
+    "video",
+    "audio",
+    "voice",
+    "document",
+    "sticker",
+    "location",
+    "contact",
+    "poll",
+    "reaction",
+    "deleted",
+    "view_once",
+    "call",
+    "system",
+    "unknown",
+];

package/dist/whatsapp.js

@@ -10,11 +10,12 @@ import { isAbsolute, join } from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import makeWASocket, { ALL_WA_PATCH_NAMES, Browsers, DisconnectReason, downloadMediaMessage, jidNormalizedUser, proto, } from "baileys";
 import { readLinkedAccount, useAtomicAuthState } from "./auth-state.js";
+import { CallTracker, callMessage, isTrackedCall } from "./calls.js";
 import { BAILEYS_VERSION, paths, WAZAP_VERSION } from "./config.js";
 import { asWazapError, RELINK_FIX, RESET_FIX, WazapError } from "./errors.js";
 import { isGroupId, isNoiseJid, resolveChatId } from "./ids.js";
 import { log, logError } from "./logger.js";
-import { buildMessageView, isControlMessage, isStubEvent, isoWithOffset, mediaInfo, messageIdFor, messageText, messageTimestampMs, protoNumber, } from "./messages.js";
+import { buildMessageView, callInfo, isCallPlaceholder, isControlMessage, isStubEvent, isoWithOffset, mediaInfo, messageIdFor, messageText, messageTimestampMs, messageType, protoNumber, } from "./messages.js";
 /** Reconnect pacing. A closed socket used to be retried instantly, which turns
  * any persistent rejection into a login storm — WhatsApp answers that by
  * throttling the account and refusing to link *any* new device to it, phone
@@ -35,6 +36,10 @@ const STALE_INBOUND_MS = 24 * 3_600_000;
 const MAX_MESSAGES_PER_CHAT = 1_000;
 const PERSIST_MESSAGES_PER_CHAT = 120;
 const STORE_SAVE_DEBOUNCE_MS = 20_000;
+const CALL_SWEEP_MS = 30_000;
+/** The same call reaches the store up to three ways; only nearness in time tells them apart. */
+const CALL_DEDUPE_WINDOW_MS = 60_000;
+const CALL_DEDUPE_SCAN = 20;
 const HISTORY_STORE_CAP_PER_CHAT = 2_000;
 const DIR_MODE = 0o700;
 const FILE_MODE = 0o600;
@@ -121,13 +126,35 @@ class Store {
             ring.sort((a, b) => this.seconds(a) - this.seconds(b));
         while (ring.length > MAX_MESSAGES_PER_CHAT) {
             const dropped = ring.shift();
-            if (dropped) {
-                this.messages.delete(dropped);
-                this.chatOf.delete(dropped);
-                this.edited.delete(dropped);
-                this.reactions.delete(dropped);
-            }
+            if (dropped)
+                this.forget(dropped);
+        }
+    }
+    /** The tail of a chat, newest first. */
+    recent(chatJid, count) {
+        const ring = this.byChat.get(chatJid) ?? [];
+        const tail = [];
+        for (let i = ring.length - 1; i >= 0 && tail.length < count; i--) {
+            const sid = ring[i];
+            const raw = this.messages.get(sid);
+            if (raw)
+                tail.push({ sid, raw });
         }
+        return tail;
+    }
+    /** Forget one message entirely, its place in the chat included. */
+    dropMessage(sid) {
+        const ring = this.byChat.get(this.chatOf.get(sid) ?? "");
+        const at = ring?.indexOf(sid) ?? -1;
+        if (ring && at !== -1)
+            ring.splice(at, 1);
+        this.forget(sid);
+    }
+    forget(sid) {
+        this.messages.delete(sid);
+        this.chatOf.delete(sid);
+        this.edited.delete(sid);
+        this.reactions.delete(sid);
     }
     reactionsFor(sid) {
         const map = this.reactions.get(sid);
@@ -227,6 +254,7 @@ export class WhatsAppService {
     historyWaiters = [];
     storeDirty = false;
     storeSaveTimer = null;
+    callSweepTimer = null;
     persistedLoaded = false;
     contactResyncTried = false;
     blocked = new Set();
@@ -238,6 +266,7 @@ export class WhatsAppService {
     /** The same, for naming only, and it holds more. See `learnLidPhone`. */
     lidPhones = new Map();
     store = new Store();
+    calls = new CallTracker();
     paths;
     constructor(config) {
         this.config = config;
@@ -289,6 +318,7 @@ export class WhatsAppService {
         this.storeSaveTimer = null;
         this.reconnectTimer = null;
         this.syncDeadline = null;
+        this.stopCallSweep();
         this.releaseWaiters();
         await this.flushStore();
         this.teardownSocket();
@@ -361,7 +391,7 @@ export class WhatsAppService {
             return this.synced(chats);
         });
     }
-    readMessages(chatId, limit, before) {
+    readMessages(chatId, limit, before, types) {
         return this.guarded(async () => {
             const sock = this.ensureConnected();
             const jid = this.resolveId(chatId);
@@ -369,19 +399,19 @@ export class WhatsAppService {
             await this.learnParticipants(jid);
             await this.learnLidPhones([jid]);
             if (before === undefined) {
-                const ring = this.store.byChat.get(jid) ?? [];
+                const ring = this.ofTypes(this.store.byChat.get(jid) ?? [], types);
                 return this.synced(this.viewsFor(ring.slice(-limit), jid));
             }
             const anchor = this.messageOrThrow(before);
-            let older = this.olderThan(jid, before, limit);
+            let older = this.olderThan(jid, before, limit, types);
             if (older.length === 0) {
                 await this.fetchOlder(sock, anchor, limit);
-                older = this.olderThan(jid, before, limit);
+                older = this.olderThan(jid, before, limit, types);
             }
             return this.synced(this.viewsFor(older, jid));
         });
     }
-    getRecentMessages(hours, filter, includeSystem = false) {
+    getRecentMessages(hours, filter, includeSystem = false, types) {
         return this.guarded(async () => {
             this.ensureConnected();
             await this.waitForSync();
@@ -402,7 +432,7 @@ export class WhatsAppService {
                 });
                 if (recent.length === 0)
                     continue;
-                const messages = this.viewsFor(recent, jid).filter((view) => includeSystem || view.type !== "system");
+                const messages = this.viewsFor(this.ofTypes(recent, types), jid).filter((view) => includeSystem || view.type !== "system");
                 if (messages.length === 0)
                     continue;
                 conversations.push({
@@ -838,6 +868,18 @@ export class WhatsAppService {
                 this.markSyncDone();
             this.markStoreDirty();
         });
+        sock.ev.on("call", ([call]) => {
+            if (generation !== this.generation || !call)
+                return;
+            // WhatsApp addresses a call node by LID as often as by number, and ownJid
+            // is only ever the number, so an outgoing call reads as incoming unless
+            // the two are brought into the same form first.
+            const from = this.canonical(call.from);
+            const entry = this.calls.observe({ ...call, from }, this.ownJid(), Date.now());
+            if (entry)
+                this.storeCall(entry);
+            this.armCallSweep();
+        });
         sock.ev.on("lid-mapping.update", (mapping) => this.learnLid(mapping.lid, mapping.pn));
         sock.ev.on("chats.upsert", (chats) => {
             for (const chat of chats)
@@ -1364,12 +1406,26 @@ export class WhatsAppService {
     viewsFor(sids, chatJid) {
         return sids.filter((sid) => this.store.messages.has(sid)).map((sid) => this.viewOf(sid, chatJid));
     }
-    olderThan(chatJid, before, limit) {
+    /** Absent and empty both mean every type: narrowing is opt-in, never a default. */
+    ofTypes(sids, types) {
+        if (types === undefined || types.length === 0)
+            return sids;
+        return sids.filter((sid) => {
+            const raw = this.store.messages.get(sid);
+            return raw !== undefined && types.includes(messageType(raw));
+        });
+    }
+    /**
+     * The anchor is found in the unfiltered ring, so paging never depends on the
+     * filter, and `limit` then counts messages the caller asked for rather than
+     * messages we are about to throw away.
+     */
+    olderThan(chatJid, before, limit, types) {
         const ring = this.store.byChat.get(chatJid) ?? [];
         const at = ring.indexOf(before);
         if (at <= 0)
             return [];
-        return ring.slice(Math.max(0, at - limit), at);
+        return this.ofTypes(ring.slice(0, at), types).slice(-limit);
     }
     async fetchOlder(sock, anchor, limit) {
         const seconds = Math.floor(messageTimestampMs(anchor) / 1000);
@@ -1499,11 +1555,74 @@ export class WhatsAppService {
             if (isNoiseJid(jid) || isControlMessage(raw))
                 continue;
             this.learnPushName(raw, jid);
-            this.store.putMessage(messageIdFor(raw.key, jid), jid, raw);
+            const sid = messageIdFor(raw.key, jid);
+            if (!this.keepOverEarlierCall(raw, jid, sid))
+                continue;
+            this.store.putMessage(sid, jid, raw);
             stored.push(raw);
         }
         return stored;
     }
+    /**
+     * One call can reach the store three ways: wazap's own tracker, the stub
+     * baileys synthesises on a timeout, and WhatsApp's later call-log message.
+     * Each carries a different id, so only nearness in time pairs them up, and
+     * whichever says more about the call is the one worth keeping. The history
+     * reload runs it too: the JSONL still holds the line the loser wrote before
+     * it was dropped, and a restart would otherwise bring the pair back.
+     */
+    keepOverEarlierCall(raw, chatJid, sid) {
+        const info = callInfo(raw);
+        if (!info)
+            return true;
+        const at = messageTimestampMs(raw);
+        for (const known of this.store.recent(chatJid, CALL_DEDUPE_SCAN)) {
+            if (known.sid === sid)
+                continue;
+            const other = callInfo(known.raw);
+            if (!other)
+                continue;
+            // A redial inside the window is two calls, and wazap knows it built both.
+            if (isTrackedCall(raw) && isTrackedCall(known.raw))
+                continue;
+            if (Math.abs(messageTimestampMs(known.raw) - at) > CALL_DEDUPE_WINDOW_MS)
+                continue;
+            if (callDetail(raw, info) <= callDetail(known.raw, other))
+                return false;
+            this.store.dropMessage(known.sid);
+            return true;
+        }
+        return true;
+    }
+    /** A live call goes in the way any message does, so everything downstream carries it. */
+    storeCall(entry) {
+        const stored = this.ingestMessages([callMessage(entry)]);
+        if (stored.length === 0)
+            return;
+        void this.appendHistory(stored);
+        this.markStoreDirty();
+    }
+    /**
+     * Only while a call is in flight: a call whose terminal event never arrives
+     * would otherwise sit pending forever, and a timer with nothing to do would
+     * otherwise keep ticking for the life of the process.
+     */
+    armCallSweep() {
+        if (this.callSweepTimer || this.calls.pending === 0)
+            return;
+        this.callSweepTimer = setInterval(() => {
+            for (const entry of this.calls.expire(Date.now()))
+                this.storeCall(entry);
+            if (this.calls.pending === 0)
+                this.stopCallSweep();
+        }, CALL_SWEEP_MS);
+        this.callSweepTimer.unref();
+    }
+    stopCallSweep() {
+        if (this.callSweepTimer)
+            clearInterval(this.callSweepTimer);
+        this.callSweepTimer = null;
+    }
     learnPushName(raw, chatJid) {
         const name = raw.pushName?.trim();
         if (!name || raw.key.fromMe)
@@ -1624,6 +1743,8 @@ export class WhatsAppService {
             const jid = this.canonical(raw.key.remoteJid);
             if (isNoiseJid(jid) || isControlMessage(raw))
                 continue;
+            if (!this.keepOverEarlierCall(raw, jid, record.sid))
+                continue;
             this.store.putMessage(record.sid, jid, raw);
             loaded++;
         }
@@ -1674,6 +1795,12 @@ const ADMIN_ACTIONS = new Set([
 const PARTICIPANT_ACTIONS = new Set(["add", "remove", "promote", "demote"]);
 /** WhatsApp answers "cannot add, invite them instead" with these codes. */
 const INVITE_NEEDED_CODES = new Set(["403", "409"]);
+/** How much a call message says. A duration is the most it can carry. */
+function callDetail(raw, info) {
+    if (info.duration_seconds !== undefined)
+        return 2;
+    return isCallPlaceholder(raw) ? 0 : 1;
+}
 function lidKey(lid) {
     return `${jidNormalizedUser(lid).split("@")[0]}@lid`;
 }

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "wazap-mcp",
-  "version": "0.9.5",
+  "version": "0.9.7",
+  "mcpName": "io.github.razvangirgiz/wazap",
   "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",
@@ -26,6 +27,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "README.md",
     "AGENT.md",
     "LICENSE"
@@ -36,7 +38,11 @@
     "dev": "tsx src/index.ts",
     "typecheck": "tsc --noEmit",
     "test": "npm run build && node --test test/*.test.mjs",
-    "prepublishOnly": "npm run build && npm test"
+    "prepublishOnly": "npm run build && npm test",
+    "registry:validate": "node scripts/validate-server-json.mjs",
+    "bundle:mcpb": "node scripts/bundle-mcpb.mjs",
+    "icon": "node scripts/make-icon.mjs",
+    "context:build": "node scripts/build-context.mjs"
   },
   "engines": {
     "node": ">=20"

package/skills/wazap-setup/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: wazap-setup
+description: Install, link or repair the WhatsApp connection. Use when the user wants to connect WhatsApp to Claude, when a WhatsApp tool returns NOT_LINKED, SESSION_EXPIRED or SESSION_CORRUPT, when `get_status` is anything but connected, or when the user asks how wazap works with Claude Desktop, Claude Code or HTTP.
+---
+
+# wazap setup
+
+wazap links the user's own WhatsApp account as a "linked device" and exposes it as MCP tools. The phone must stay online; the link needs the user's hands once.
+
+## Diagnose first
+
+Run `npx wazap-mcp status` and branch on its output. It never contacts WhatsApp, so it is safe at any point.
+
+| `status` says | Do |
+| --- | --- |
+| `wazap: command not found` / npx fails | Node 20+ is required. `node --version`; install from nodejs.org if older. |
+| `linked: no` | Go to **Link**. |
+| `linked: yes`, `server: running` | The server is up. If tools still fail, call `get_status` and follow its `fix`. |
+| `linked: yes`, `server: not running` | Go to **Connect a client**. |
+
+Below those lines is a `checks:` section. Every `✗` carries the command that
+fixes it; run that command rather than improvising.
+
+| `checks:` line | What it means |
+| --- | --- |
+| `✗ node` | The Node version is below 20. Nothing else will work until it is upgraded. |
+| `✗ data dir` | Missing, not a directory, mode other than 0700, or not writable. The line names the `chmod` to run. |
+| `– lock: stale` | A previous server died without cleaning up. Harmless; the next start reclaims it. |
+| `✓ lock: held` | A server is running. Do not run `logout` or `status --live`; ask through the client with `get_status`. |
+| `✗ credentials` | Unreadable. `npx wazap-mcp logout` then `npx wazap-mcp login`. |
+| `writes: off` | Write tools are not registered. Enabling them is **Allow writes**. |
+| `– update` | A newer wazap exists, or the check could not reach npm. Never blocking. |
+
+`npx wazap-mcp status --live` reaches WhatsApp for real and reports whether the
+phone is reachable, how many chats synced and how old the last message is. It
+refuses while a server holds the lock, because one process owns the session.
+`--json` gives the same report as one object.
+
+## Link
+
+Run `npx wazap-mcp setup --agent` and follow what it prints.
+
+That procedure starts `login` in the background and reads the
+`pairing code: XXXX-XXXX` line out of its output, so the user is left with the
+one part of linking a machine cannot do, typing the code into the phone.
+
+`SESSION_EXPIRED` means the phone removed the device: run `npx wazap-mcp login` again. `SESSION_CORRUPT` means unreadable credentials: `npx wazap-mcp logout` then `npx wazap-mcp login`.
+
+## Connect a client
+
+Run `npx wazap-mcp connect <client>`, where the client is one of `claude-code`,
+`claude-desktop`, `cursor`, `codex`, `vscode` or `gemini`. It writes the entry,
+keeps whatever else is in the file, backs it up once, and prints the next step
+(restart, reload window, or `claude mcp list`). Running it twice is safe.
+
+- Add `--dry-run` first if the user wants to see the entry before it is written.
+- Claude Code users can install this plugin instead, which registers the server.
+- Remote clients (claude.ai, another machine) need HTTP mode with tokens; follow "HTTP mode" in the wazap README rather than improvising.
+
+Done when `get_status` returns `status: "connected"`. Then call `learn` once before using the other tools.
+
+## Allow writes
+
+Writes are off unless the user said yes at `login`. The write tools are then not
+registered at all, so the agent cannot see them.
+
+Turn them on with `npx wazap-mcp config writes on`, off again with
+`npx wazap-mcp config writes off`. Both edit `WAZAP_READ_ONLY` in
+`<data-dir>/.env`; a running server has to be restarted for the change to take
+effect. `npx wazap-mcp config` alone prints every effective setting and where it
+came from, which is how you tell a flag from an `.env` line.
+
+## Limits the user should hear once
+
+Baileys is an unofficial WhatsApp client; Meta can flag accounts, so heavy automated sending is the user's risk. One process owns the session: two wazap servers on the same data dir refuse to start.

package/skills/whatsapp-groups/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: whatsapp-groups
+description: Catch up on a busy WhatsApp group. Use when the user asks what happened in a group, what was decided, what they are being asked to do there, or for a summary of a thread with many messages. Read-only.
+---
+
+# WhatsApp group catch-up
+
+Deliverable: decisions, dates, and what is asked of the user, in that order, with the chatter gone. A 300-message thread should compress to a screen.
+
+## Load the whole window
+
+1. Resolve the group with `list_chats` `filter: "groups"` (match on name; ask if two match). `get_group_info` once for the participant names and who the admins are; use names, not numbers, in the summary.
+2. `read_messages` with `limit: 200`. If the oldest message is still inside the window the user asked for, call again with `before` set to that oldest `message_id`, until the window is covered. Done loading when the oldest message you hold is older than the window, or WhatsApp returns no more.
+3. Note which messages quote or mention the user: `quoted.sender` equal to the user, the user's name in `text`, or `sender` addressing them directly. These are the **asks**.
+
+## Extract
+
+Work through the messages once and collect:
+
+- **Decisions**: something agreed or announced by an admin or by the people it concerns ("ok, Saturday at 10 then").
+- **Dates and deadlines**: any concrete day, time, or "by Friday", with what it is for.
+- **Asks of the user**: every mention or reply to them, plus open questions nobody answered that fall on the user. A `call` message in the group after one of these, with `call.outcome` `answered`, means the user was on that group call: say so and treat the ask as probably handled, the way `whatsapp-inbox` does.
+- **Open threads**: questions still without an answer, for anyone.
+- **Polls**: the question and options (`[poll] …`); wazap cannot read votes, so say that if the user asks who voted.
+
+Skip greetings, reactions, stickers, and messages that only acknowledge.
+
+## Report
+
+```
+Bloc 12 — 312 messages since Monday
+
+Decided
+- Roof repair goes to Tehnoplast, 18,400 lei, vote closed Wednesday.
+- Water off Thursday 09:00–13:00.
+
+Dates
+- Fri 15 Mar: pay share (1,150 lei) to the association account.
+
+You
+- Mihai asked (Tue) if you can be home Thursday for the plumber. Unanswered.
+
+Open
+- Nobody confirmed who holds the basement key.
+```
+
+End with the message count and the window covered, so the user knows what the summary stands on. Replying in the group is the `whatsapp-send` skill's job; here, offer it only for the *You* items.

package/skills/whatsapp-inbox/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: whatsapp-inbox
+description: Triage the user's WhatsApp. Use when they ask what they missed, what's unread, who is waiting on a reply, what needs attention today, or whom they forgot to answer. Read-only; it sends nothing and marks nothing read.
+---
+
+# WhatsApp inbox triage
+
+Deliverable: a short, ranked list of what needs the user, with everything else compressed to one line. The user should finish reading in under a minute.
+
+## Collect
+
+1. `get_recent_messages` with the window the user implied (default 24h; "this week" = 168). If the result says `sync: "in_progress"`, wait 5 seconds and call it again once.
+2. `list_chats` with `filter: "unread"` to catch chats whose activity predates the window.
+3. For follow-ups ("whom did I forget"): in `list_chats` results, an individual chat whose `last_message.from_me` is false and older than 2 days is an unanswered conversation. Read its last 5 messages with `read_messages` to confirm something was actually asked.
+
+Done collecting when every chat with unread messages appears in exactly one bucket below.
+
+## Triage
+
+Sort each chat into one bucket:
+
+- **Needs you**: a direct question to the user, a request, a mention of the user in a group (`sender` is not the user and the text addresses them or quotes one of their messages), or money/dates/decisions awaiting them.
+- **Probably handled by call**: a *Needs you* candidate the user has since called. See *Calls* below.
+- **FYI**: information with no ask. Shipping updates, "ok thanks", group chatter that reached a conclusion.
+- **Noise**: promotions, broadcast lists, groups the user is muted in (`muted_until` in the future), forwards without a question.
+
+Rank *Needs you* by: people over groups, older unanswered over newer, money and deadlines first.
+
+### Calls
+
+A call after someone's ask is evidence the user dealt with it. For every *Needs you* candidate from an individual chat, look for a `call` message in that chat newer than the ask: the calls already in the window, or `read_messages` on that chat with `types: ["call"]`. A call whose `call.outcome` is `answered` moves the item to *Probably handled by call*, carrying when it was and how long it ran, and ending in a question, because the call may have been about something else:
+
+`Ana — asked about Thursday 10:00; you spoke for 6 min on Tue 14:10. Confirm?`
+
+Missed, rejected and unanswered calls are evidence of nothing, and those items stay in *Needs you*.
+
+## Report
+
+```
+Needs you (3)
+1. Ana — asks if Thursday 10:00 works for the notary. 5h ago.
+2. Bloc 12 group — Mihai needs your vote on the roof quote by Friday. 1d ago.
+3. Dan — sent the contract PDF, waiting for your comments. 2d ago.
+
+Probably handled by call (1)
+1. Ana — asked about Thursday 10:00; you spoke for 6 min on Tue 14:10. Confirm?
+
+FYI: Curier (delivered), Mama (photos), Team (retro moved to Tuesday).
+Noise: 4 promo chats.
+```
+
+End the report with: *Handled any of these by phone outside WhatsApp? Tell me and I will drop them.* wazap sees WhatsApp calls and never cellular ones, so a call from the phone's own dialler leaves no trace here. Whatever the user answers is authoritative for the rest of the session: drop what they name and do not raise it again.
+
+One line per item: who, what they want, how old. Include the `chat_id` only if the user is likely to act through another tool next. Offer to draft replies only for *Needs you* items; drafting and sending belong to the `whatsapp-send` skill.

package/skills/whatsapp-recall/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: whatsapp-recall
+description: Find something in the user's WhatsApp history. Use when they ask for an address, invoice, photo, document, link, phone number, date or a thing someone said or sent, or "what did X say about Y". Read-only.
+---
+
+# WhatsApp recall
+
+Deliverable: the exact message or file, quoted with who sent it and when, or a clear "not found" that says where you looked.
+
+## Narrow, then search
+
+1. If a person or group is named, resolve it with `search_contacts` (people) or `list_chats` with `filter: "groups"` (groups) and search inside that `chat_id`. Searching one chat beats searching everything.
+2. `search_messages` with the user's words. If nothing matches, run two more variants before giving up: a synonym or the other language the user writes in, and a narrower fragment (a street name instead of "the address", "factura" instead of "the invoice from March").
+3. Media has no searchable text beyond its caption and the `[image]`/`[document] name.pdf` placeholder. For "the photo of…" or "the PDF", search the placeholder and filename words, or `read_messages` on the chat with `limit: 100` and scan `type` and `media.filename`.
+4. Older than what is loaded: `read_messages` with `before` set to the oldest `message_id` you have, repeatedly, until the date the user remembers is covered or WhatsApp returns nothing more.
+
+Done searching when you have a match, or all three query variants and the pagination step came back empty.
+
+## Deliver
+
+- A message: quote the text verbatim, then sender, chat, timestamp. Example: *"Str. Lunii 14, ap. 3, interfon 31" — Ana, 12 Mar 14:05.*
+- A file or photo: `download_media` on the message, then open the saved file with your file-reading tool and answer from its contents when the user asked a question about it (an amount, a clause, a date). Give the saved path so the user can open it.
+- A link: return the URL as sent; do not fetch it unless asked.
+- Several candidates: list up to 5 with sender and date and ask which one, rather than guessing.
+- Not found: say which chats and which phrases you tried, and whether `MEDIA_UNAVAILABLE` blocked a download (the sender must resend).

package/skills/whatsapp-send/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: whatsapp-send
+description: Send, reply, forward, share a file, react, or create a poll on WhatsApp on the user's behalf. Use for any request that results in an outgoing WhatsApp message. Drafts first and sends after the user approves; messages leave from the user's own account and cannot be unsent.
+---
+
+# WhatsApp send
+
+A message sent here is indistinguishable from one the user typed. The rail: **the user sees recipient and exact text, says yes, then it goes.** One approval covers one message to one chat.
+
+## Resolve the recipient
+
+1. `search_contacts` with the name. Exactly one match: use its `chat_id`. Several: list them with numbers and ask. None: ask for the number in international format; `NOT_ON_WHATSAPP` means the number is wrong, not that you should retry.
+2. Groups come from `list_chats` with `filter: "groups"`. Before posting, `get_group_info`; if `announcement_only` is true and the user is not admin, say so instead of trying.
+3. A reply to a specific message needs its `message_id` from `read_messages`; pass it as `reply_to` so the quote shows.
+
+## Draft
+
+1. `read_messages` on the chat, `limit: 20`, and match the register already in use: language (Romanian or English), formality, emoji, length. A two-line chat gets a two-line reply.
+2. Write the message as the user, first person, without a signature or "sent by an assistant".
+3. Files: `send_media` needs a local `file_path` that exists on the machine running wazap, or a public URL. Check the path before drafting; pick `as_document: true` for PDFs and anything the recipient should keep at original quality, `as_voice: true` only for audio meant as a voice note.
+
+## Confirm, then send
+
+Show exactly this and wait for a yes:
+
+```
+To: Ana (+40 722 …)
+"Joi la 10 e perfect, ne vedem la notar. Aduc eu actele."
+```
+
+Send on the user's yes with `send_message` / `send_media` / `send_poll` / `send_location` / `forward_message`, and report the result with the `message_id` so the user can follow up with `edit_message` (own messages, 15 minutes) or `delete_message`.
+
+Approval is per message, even after "just send it" for a batch, when the recipient is a group, a number not in the user's contacts, or the content contains money, dates, or commitments. For a batch of plain messages the user already approved as a list, send them one by one and stop at the first error; `RATE_LIMITED` means wait the seconds in `fix`, then continue.
+
+## Out of scope
+
+`delete_message` with `for_everyone` and `manage_group` remove/leave run only on an explicit ask naming the message or person. Bulk sends to people who did not write first are the user's account at risk of a WhatsApp ban; say that once and let them decide.