wazap-mcp 0.13.0 → 0.14.0

package/README.md

@@ -8,7 +8,7 @@
 ```
 
 **WhatsApp for your AI agent.** An MCP server that puts your WhatsApp account —
-chats, messages, media, contacts, groups — behind 31 tools any MCP client can
+chats, messages, media, contacts, groups — behind 33 tools any MCP client can
 call. Pairing-code login, no browser, no phone-number reseller, ~20 MB of RAM.
 
 Built on [Baileys](https://github.com/WhiskeySockets/Baileys), which speaks the
@@ -44,10 +44,11 @@ and it is missing, and to restart Claude Desktop itself once it has connected it
 | 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` |
+| Grok Bot | [Grok Bot / remote MCP](#grok-bot--remote-mcp) |
 | 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`.
+Each local harness registers the server. Grok Bot is a URL you paste. Linking
+the WhatsApp account is a separate, one-time step: `npx wazap-mcp login`.
 
 Or have your agent do it. Paste this:
 
@@ -89,8 +90,28 @@ it would write.
 | `gemini` | `~/.gemini/settings.json` |
 | `windsurf` | `~/.codeium/windsurf/mcp_config.json` |
 | `opencode` | `mcp.whatsapp` in `~/.config/opencode/opencode.json` |
+| Grok Bot | client's MCP URL field: `http://<host>:<port>/mcp` with header `Authorization: Bearer <token>` (see [Grok Bot / remote MCP](#grok-bot--remote-mcp)) |
 | anything remote | client's MCP URL field: `https://your-host/mcp` with header `Authorization: Bearer <token>`, or just the URL once [OAuth](#hosted-agents-oauth) is on (see [Self-host](#self-host)) |
 
+### Grok Bot / remote MCP
+
+Grok Bot is an HTTP MCP client. It does not launch wazap over stdio.
+
+1. On the machine that will run wazap, `npx wazap-mcp login` until the CLI says the account is linked. `get_status` and `link_account` are MCP tools; they need HTTP already serving (step 3) and Grok already connected (step 4).
+2. Answer writes yes or no at login. Writes stay on when `WAZAP_READ_ONLY` is unset. A Bearer write token is not writes being enabled. If write tools are missing, you need writes on (`wazap config writes on` and restart) and a write Bearer on this session. Config alone is not enough on HTTP.
+3. Serve HTTP with a read token:
+
+```bash
+WAZAP_READ_TOKEN=$(openssl rand -hex 32) \
+npx wazap-mcp serve --http
+```
+
+Set `WAZAP_WRITE_TOKEN` too only if this client should send, and put that value in the header in step 4.
+
+4. In Grok Bot, add an MCP server at `http://<host>:<port>/mcp` with header `Authorization: Bearer <token>`. Then call `learn`, then `get_status`. `connected` means the WhatsApp socket is up. This session can send only when write tools are registered (`write_tools: true`, or send tools appear in the tool list). Then read.
+
+`wazap setup` asks `Remote client (Grok Bot / HTTP MCP)?` and prints the same URL and header. Answering yes does not start `expose`.
+
 ### Other MCP clients
 
 Cursor and VS Code install from a link:
@@ -251,8 +272,9 @@ them. `--dry-run` prints the plan and touches nothing.
 | Tool | Kind | What it does |
 | --- | --- | --- |
 | `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. |
-| `link_account` | read | Pair the account without a terminal: returns the code to type into the phone. Registered in read-only mode too. |
+| `get_status` | read | Connection status, sync state, linked account, named-contact count, versions, data dir. Top-level fields are the default account; `accounts` lists every live one. Optional `account_id` on this and every other tool. |
+| `list_accounts` | read | Every configured account: id, name, status, masked phone, owner name, writes policy. Call this first when more than one account is linked. |
+| `link_account` | read | Pair an account that already exists (`wazap account add`). Returns the code to type into the phone. Registered in read-only mode too. |
 | `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; `types` narrows to one or more message types, e.g. `["call"]`; `include_previews` attaches a small image of each photo. |
 | `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, `include_previews` attaches a small image of each photo, `compact` halves it for a routine catch-up. |
@@ -278,6 +300,7 @@ them. `--dry-run` prints the plan and touches nothing.
 | `forward_message` | write | Draft a forward to another chat. Does not send. |
 | `confirm_send` | write | Send a draft after the user has seen the preview and said yes. |
 | `delete_message` | write | Retract your own message, within WhatsApp's 2-day window. |
+| `set_profile_picture` | write | Set the linked account's own profile photo from a local path or URL. Hits WhatsApp immediately. |
 | `manage_chat` | write | Archive, pin, mute (8h by default), mark read/unread. |
 | `create_group` | write | Create a group and add participants. |
 | `manage_group` | write | Add, remove, promote, demote, leave, rename, invite links. |
@@ -465,12 +488,15 @@ trace, so an agent can decide whether to retry, ask the user, or stop.
 | `CHAT_NOT_FOUND` / `MESSAGE_NOT_FOUND` / `CONTACT_NOT_FOUND` / `GROUP_NOT_FOUND` | Unknown id. |
 | `NOT_A_PARTICIPANT` / `NOT_ADMIN` / `GROUP_ANNOUNCEMENT_ONLY` | Group permissions. |
 | `MEDIA_UNAVAILABLE` | WhatsApp expired the file, or it was never synced here. |
-| `FILE_NOT_FOUND` / `FILE_TOO_LARGE` / `URL_FETCH_FAILED` | Outbound media problems. |
+| `FILE_NOT_FOUND` / `FILE_TOO_LARGE` / `URL_FETCH_FAILED` / `INVALID_IMAGE` | Outbound media problems. |
 | `TEXT_TOO_LONG` | Over WhatsApp's message limit. |
 | `EDIT_WINDOW_EXPIRED` / `RETRACT_WINDOW_EXPIRED` / `NOT_OWN_MESSAGE` | WhatsApp's own limits on editing and deleting. |
 | `READ_ONLY` | wazap is running read-only. |
 | `RATE_LIMITED` | Too many writes; `fix` says how long to wait. |
 | `DRAFT_NOT_FOUND` / `DRAFT_EXPIRED` | The preview was already sent, unknown, or older than 15 minutes. Draft again. |
+| `AMBIGUOUS_ACCOUNT` | More than one account could handle this, or a write named a chat no account knows. Pass `account_id`. |
+| `ACCOUNT_NOT_FOUND` | No account with that id. Run `wazap account add`, or call `list_accounts`. |
+| `ACCOUNT_DISABLED` | That account is disabled. `wazap account enable <id>` and restart. |
 | `TIMEOUT` / `WHATSAPP_ERROR` | WhatsApp did not answer, or rejected the operation. |
 
 ## Data directory
@@ -518,13 +544,16 @@ server of its own rather than a bridge, and is refused the same way.
 
 ## Read-only mode
 
-Writes are opt-in. `login` asks once and stores the answer in
-`<data-dir>/.env`; `wazap config writes on|off` changes it, and `wazap config`
-alone prints every effective setting with where it came from.
+Writes are opt-in at `login` (the question defaults to no and stores the
+answer in `<data-dir>/.env`). `wazap config writes on|off` changes it later.
+`wazap config` and `wazap status` print the effective setting and where it
+came from. If that line says off, write tools are not registered: run
+`wazap config writes on` and restart the server.
 
-`WAZAP_READ_ONLY=1` or `wazap serve --read-only` does not register the write
-tools at all. The agent never sees them, so it cannot message anyone from your
-number even by mistake — useful when the linked account is your personal one.
+An unset `WAZAP_READ_ONLY` and `WAZAP_READ_ONLY=0` both register write tools
+(`wazap config` then says "writes: on"). `WAZAP_READ_ONLY=1` or
+`wazap serve --read-only` does not register them at all. The agent never
+sees them, so it cannot message anyone from your number even by mistake.
 
 Writes are also rate limited to `WAZAP_RATE_LIMIT` per minute (default 20, `0`
 disables). Sending faster than a human is how accounts get banned.
@@ -541,10 +570,13 @@ Streamable HTTP at `/mcp`, with a health check at `/healthz`. That check answers
 `{ ok, status, since }`. It turns 503 once the socket has been anything but
 connected for two minutes, so a tunnel or a monitor sees a real outage rather
 than a reconnect in progress. Two bearer tokens:
-the read token gets the read tools, the write token also unlocks the write
-tools, so a leaked read token can never message anyone. wazap refuses to bind a
-non-loopback address without a read token. Agents that cannot carry a header
-sign in with [OAuth](#hosted-agents-oauth) instead.
+the read token gets the read tools, the write token can unlock the write
+tools. A leaked read token can never message anyone. A write token is not
+the same as writes being enabled: if the server is read-only, even a write
+token session has no write tools. `get_status` says so and how to turn
+writes on. wazap refuses to bind a non-loopback address without a read
+token. Agents that cannot carry a header sign in with
+[OAuth](#hosted-agents-oauth) instead.
 
 ## Self-host
 
@@ -644,12 +676,42 @@ What to know before exposing it:
 - A read grant never sees a write tool, whatever scope the agent requested.
   The radio button on the consent page is the only thing that decides.
 
+## Outbound webhook
+
+A live inbound message can POST to one URL. Off by default. History sync
+is not posted. The only event is `message_received`.
+
+```bash
+npx wazap-mcp config webhook on    # asks for URL + secret (secret is not echoed)
+npx wazap-mcp webhook test         # POST a probe event
+npx wazap-mcp config webhook off
+```
+
+On without a URL or secret fails `wazap status`, doctor and setup. A failed
+delivery retries twice (200 ms, then 500 ms), then sets `webhook.last_error`
+and leaves WhatsApp and MCP running.
+
+HMAC: `X-Wazap-Signature` is `sha256=<hex>`, HMAC-SHA256 of the exact raw
+JSON body with `WAZAP_WEBHOOK_SECRET`. Verify that raw body, not a
+re-serialized object. HTTPS only, except `http://` on loopback.
+
+```json
+{
+  "event": "message_received",
+  "from": "+15550100",
+  "chat_id": "15550100@s.whatsapp.net",
+  "ts": "2026-09-08T14:00:00+00:00",
+  "text": "hello, or a short preview",
+  "message_id": "false_15550100@s.whatsapp.net_3EB0…"
+}
+```
+
 ## Settings
 
 | Variable | Default | Meaning |
 | --- | --- | --- |
 | `WAZAP_DATA_DIR` | `~/.wazap` | Where everything is stored. |
-| `WAZAP_READ_ONLY` | `0` | Do not register the write tools. |
+| `WAZAP_READ_ONLY` | unset (`0`) | `1` does not register the write tools. Unset and `0` both do. |
 | `WAZAP_SYNC_FULL_HISTORY` | `0` | Ask WhatsApp for a fuller history sync. |
 | `WAZAP_PERSIST_HISTORY` | `1` | Keep chats and messages across restarts. |
 | `WAZAP_RATE_LIMIT` | `20` | Write tool calls per minute; `0` disables. |
@@ -667,6 +729,9 @@ What to know before exposing it:
 | `WAZAP_TRANSCRIBE_API_KEY` | unset | API key; `OPENAI_API_KEY` is the fallback. Never a flag. |
 | `WAZAP_TRANSCRIBE_URL` | `https://api.openai.com/v1` | OpenAI-compatible base URL. |
 | `WAZAP_TRANSCRIBE_MODEL` | `gpt-4o-mini-transcribe` | Model at that URL. |
+| `WAZAP_WEBHOOK` | `off` | `on` posts live inbound messages to the webhook URL. |
+| `WAZAP_WEBHOOK_URL` | unset | HTTPS endpoint. `http://` only on loopback. |
+| `WAZAP_WEBHOOK_SECRET` | unset | Shared secret for `X-Wazap-Signature`. Never a flag. |
 
 Flags beat environment variables, which beat `<data-dir>/.env`.
 

package/dist/account-cli.js

@@ -0,0 +1,132 @@
+import { AccountRegistry } from "./accounts.js";
+import { readLinkedAccount } from "./auth-state.js";
+import { ask, leftoverFix } from "./cli.js";
+import { ACCOUNT_USAGE, MIGRATE_USAGE, accountPaths, paths } from "./config.js";
+import { WazapError } from "./errors.js";
+import { lockHolder } from "./lock.js";
+import { say } from "./logger.js";
+import { rollbackMigration } from "./migrate.js";
+import { brand, info, maskNumber, ok } from "./ui.js";
+function parseAccountVerb(verb) {
+    switch (verb) {
+        case "list":
+        case "add":
+        case "remove":
+        case "enable":
+        case "disable":
+            return verb;
+        default:
+            throw new WazapError("INVALID_ID", `Unknown account command "${verb ?? ""}".`, ACCOUNT_USAGE);
+    }
+}
+/** 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;
+}
+export function describeStatusAccount(row) {
+    const flag = row.enabled ? "enabled" : "disabled";
+    const who = row.account === null ? "not linked" : describeAccount(row.account);
+    return `${row.id}  ${flag}  ${who}`;
+}
+export function accountRows(config) {
+    const registry = AccountRegistry.load(config.dataDir);
+    return registry.all().map((record) => {
+        let linked = null;
+        try {
+            linked = readLinkedAccount(accountPaths(config.dataDir, record.id).authDir);
+        }
+        catch {
+            linked = null;
+        }
+        return {
+            id: record.id,
+            name: record.name,
+            enabled: record.enabled,
+            default: record.id === registry.defaultId(),
+            account: linked,
+        };
+    });
+}
+export async function runAccount(config) {
+    const [rawVerb, id] = config.args;
+    const verb = parseAccountVerb(rawVerb);
+    switch (verb) {
+        case "list":
+            if (id !== undefined)
+                throw new WazapError("INVALID_ID", `Cannot run \`wazap account list ${id}\`.`, ACCOUNT_USAGE);
+            listAccounts(config);
+            return;
+        case "add":
+            if (id === undefined)
+                throw new WazapError("INVALID_ID", "Missing account id.", ACCOUNT_USAGE);
+            addAccount(config, id);
+            return;
+        case "remove":
+            if (id === undefined)
+                throw new WazapError("INVALID_ID", "Missing account id.", ACCOUNT_USAGE);
+            await removeAccount(config, id);
+            return;
+        case "enable":
+            if (id === undefined)
+                throw new WazapError("INVALID_ID", "Missing account id.", ACCOUNT_USAGE);
+            enableAccount(config, id, true);
+            return;
+        case "disable":
+            if (id === undefined)
+                throw new WazapError("INVALID_ID", "Missing account id.", ACCOUNT_USAGE);
+            enableAccount(config, id, false);
+            return;
+        default: {
+            const _exhaustive = verb;
+            return _exhaustive;
+        }
+    }
+}
+function listAccounts(config) {
+    for (const row of accountRows(config)) {
+        say(`${describeStatusAccount(row)}${row.default ? "  (default)" : ""}`);
+    }
+}
+function addAccount(config, id) {
+    const record = AccountRegistry.load(config.dataDir).add(id, config.accountName);
+    say(ok(`Account "${record.id}" added.`));
+}
+async function removeAccount(config, id) {
+    const registry = AccountRegistry.load(config.dataDir);
+    if (registry.get(id) === undefined) {
+        throw new WazapError("INVALID_ID", `No account "${id}".`, "Run `wazap account list`");
+    }
+    const running = lockHolder(paths(config.dataDir).lockFile);
+    if (running !== null) {
+        throw new WazapError("INVALID_ID", `wazap is running (pid ${running}).`, leftoverFix(running));
+    }
+    if (!config.assumeYes) {
+        if (process.stdin.isTTY !== true) {
+            throw new WazapError("INVALID_ID", `Refusing to delete account "${id}" without --yes.`, "Re-run with --yes");
+        }
+        const answer = await ask(`${brand("?")} Delete account "${id}" and its local data? [y/N] `);
+        if (!/^y(es)?$/i.test(answer.trim())) {
+            say(info("Cancelled."));
+            return;
+        }
+    }
+    registry.remove(id);
+    say(ok(`Account "${id}" removed.`));
+}
+function enableAccount(config, id, enabled) {
+    const registry = AccountRegistry.load(config.dataDir);
+    if (enabled)
+        registry.enable(id);
+    else
+        registry.disable(id);
+    say(ok(`Account "${id}" ${enabled ? "enabled" : "disabled"}.`));
+}
+export function runMigrate(config) {
+    const [verb] = config.args;
+    if (verb !== "rollback") {
+        throw new WazapError("INVALID_ID", `Cannot run \`wazap migrate ${config.args.join(" ")}\`.`, MIGRATE_USAGE);
+    }
+    rollbackMigration(config.dataDir);
+    say(ok("Rolled back the data-dir layout."));
+}

package/dist/account-hub.js

@@ -0,0 +1,131 @@
+/**
+ * One process, N WhatsApp sockets. The registry names the accounts; this holds
+ * a live service for each enabled one, with its own reconnect loop and write
+ * bucket. MCP tools resolve a service per call.
+ */
+import { accountPaths } from "./config.js";
+import { WazapError } from "./errors.js";
+import { logError } from "./logger.js";
+import { WhatsAppService } from "./whatsapp.js";
+const FIX_ENABLE = "Run `wazap account enable <id>` or `wazap account add <id>`";
+function bind(id, wa) {
+    return { id, wa };
+}
+function readSingletonId(wa) {
+    try {
+        const id = wa.getStatus().account_id;
+        return typeof id === "string" && id.length > 0 ? id : "default";
+    }
+    catch {
+        return "default";
+    }
+}
+function readSingletonName(wa, fallback) {
+    try {
+        const name = wa.getStatus().account_name;
+        return typeof name === "string" && name.length > 0 ? name : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}
+/** One live service as a hub, so existing tests can keep passing a stub `wa`. */
+export function singletonSource(wa) {
+    const id = readSingletonId(wa);
+    const binding = bind(id, wa);
+    const self = () => ({
+        id,
+        name: readSingletonName(wa, id),
+        enabled: true,
+        owner: null,
+    });
+    return {
+        binding: (requested) => (requested === id ? binding : undefined),
+        defaultBinding: () => binding,
+        bindings: () => [binding],
+        findByChat: (jid) => (typeof wa.hasChat === "function" && wa.hasChat(jid) ? [binding] : []),
+        findByMessage: (mid) => (typeof wa.hasMessage === "function" && wa.hasMessage(mid) ? [binding] : []),
+        findByDraft: (did) => (typeof wa.hasDraft === "function" && wa.hasDraft(did) ? [binding] : []),
+        record: (requested) => (requested === id ? self() : undefined),
+        records: () => [self()],
+    };
+}
+export class AccountHub {
+    services = new Map();
+    known = new Map();
+    givenUp = new Set();
+    primary;
+    primaryId;
+    /** Process exit hook. Fires only after every enabled account has given up. */
+    onGiveUp = null;
+    constructor(config, registry) {
+        for (const account of registry.all()) {
+            this.known.set(account.id, { ...account });
+        }
+        const enabled = registry.all().filter((account) => account.enabled);
+        if (enabled.length === 0) {
+            throw new WazapError("INVALID_ID", "No enabled account to serve.", FIX_ENABLE);
+        }
+        for (const account of enabled) {
+            const wa = new WhatsAppService(config, account, accountPaths(config.dataDir, account.id));
+            wa.onGiveUp = () => this.noteGiveUp(account.id);
+            this.services.set(account.id, wa);
+        }
+        const firstId = enabled[0].id;
+        this.primaryId = this.services.has(registry.defaultId()) ? registry.defaultId() : firstId;
+        this.primary = this.services.get(this.primaryId);
+    }
+    async start() {
+        await Promise.all([...this.services].map(([id, wa]) => wa.start().catch((err) => {
+            logError(`whatsapp start ${id}`, err);
+            this.noteGiveUp(id);
+        })));
+    }
+    async stop() {
+        await Promise.all([...this.services.values()].map((wa) => wa.stop()));
+    }
+    get(id) {
+        return this.services.get(id);
+    }
+    default() {
+        return this.primary;
+    }
+    all() {
+        return [...this.services.values()];
+    }
+    binding(id) {
+        const wa = this.services.get(id);
+        return wa === undefined ? undefined : bind(id, wa);
+    }
+    defaultBinding() {
+        return bind(this.primaryId, this.primary);
+    }
+    bindings() {
+        return [...this.services].map(([id, wa]) => bind(id, wa));
+    }
+    findByChat(jid) {
+        return this.bindings().filter((row) => row.wa.hasChat(jid));
+    }
+    findByMessage(id) {
+        return this.bindings().filter((row) => row.wa.hasMessage(id));
+    }
+    findByDraft(id) {
+        return this.bindings().filter((row) => row.wa.hasDraft(id));
+    }
+    record(id) {
+        const found = this.known.get(id);
+        return found === undefined ? undefined : { ...found };
+    }
+    records() {
+        return [...this.known.values()].map((account) => ({ ...account }));
+    }
+    noteGiveUp(id) {
+        if (this.givenUp.has(id))
+            return;
+        this.givenUp.add(id);
+        logError("whatsapp", `account ${id}: reconnects exhausted`);
+        if (this.givenUp.size < this.services.size)
+            return;
+        this.onGiveUp?.();
+    }
+}

package/dist/account-resolve.js

@@ -0,0 +1,137 @@
+/**
+ * Per-call account resolution and the list/status overlays that need the hub.
+ * Tool handlers stay in tools.ts.
+ */
+import { WazapError } from "./errors.js";
+import { maskNumber } from "./ui.js";
+const FIX_ADD_ACCOUNT = "Run `wazap account add`";
+const FIX_PASS_ACCOUNT = "Pass account_id";
+function ok(text, structured) {
+    return { content: [{ type: "text", text }], structuredContent: structured };
+}
+export function stringArg(args, key) {
+    const value = args[key];
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+export function attachAccountId(result, accountId) {
+    return { ...result, structuredContent: { ...(result.structuredContent ?? {}), account_id: accountId } };
+}
+/** Write tools register when any live account allows writes. */
+export function anyAccountAllowsWrites(hub) {
+    return hub.bindings().some((row) => row.wa.getStatus().read_only !== true);
+}
+function pickFromMatches(matches, write, hub, what) {
+    if (matches.length === 1)
+        return matches[0];
+    if (matches.length > 1) {
+        throw new WazapError("AMBIGUOUS_ACCOUNT", `Several accounts have that ${what}: ${matches.map((row) => row.id).join(", ")}.`, FIX_PASS_ACCOUNT);
+    }
+    if (write) {
+        throw new WazapError("AMBIGUOUS_ACCOUNT", `No account knows that ${what}.`, FIX_PASS_ACCOUNT);
+    }
+    return hub.defaultBinding();
+}
+function resolveGivenId(hub, requested, toolName) {
+    const record = hub.record(requested);
+    const live = hub.binding(requested);
+    if (record !== undefined && !record.enabled) {
+        throw new WazapError("ACCOUNT_DISABLED", `Account "${requested}" is disabled.`, `Run \`wazap account enable ${requested}\` and restart the server`);
+    }
+    if (live === undefined) {
+        const fix = toolName === "link_account" ? FIX_ADD_ACCOUNT : `${FIX_ADD_ACCOUNT}, or call list_accounts`;
+        throw new WazapError("ACCOUNT_NOT_FOUND", `No account "${requested}".`, fix);
+    }
+    return live;
+}
+export function resolveToolAccount(hub, args, tool) {
+    if (tool.name === "list_accounts")
+        return hub.defaultBinding();
+    const requested = stringArg(args, "account_id");
+    if (requested !== undefined)
+        return resolveGivenId(hub, requested, tool.name);
+    const live = hub.bindings();
+    if (live.length === 1)
+        return live[0];
+    const chatId = stringArg(args, "chat_id") ?? stringArg(args, "group_id") ?? stringArg(args, "contact_id");
+    const messageId = stringArg(args, "message_id");
+    const draftId = stringArg(args, "draft_id");
+    if (chatId !== undefined)
+        return pickFromMatches(hub.findByChat(chatId), tool.write, hub, "chat");
+    if (messageId !== undefined)
+        return pickFromMatches(hub.findByMessage(messageId), tool.write, hub, "message");
+    if (draftId !== undefined)
+        return pickFromMatches(hub.findByDraft(draftId), false, hub, "draft");
+    return hub.defaultBinding();
+}
+function listedFromStatus(s, enabled, id = s.account_id) {
+    return {
+        id,
+        name: s.account_name,
+        status: s.status,
+        phone_masked: s.account ? maskNumber(s.account.number) : null,
+        owner_name: s.account?.name ?? null,
+        write_tools: !s.read_only,
+        enabled,
+    };
+}
+function listedFromRecord(record) {
+    return {
+        id: record.id,
+        name: record.name,
+        status: record.enabled ? "disconnected" : "disabled",
+        phone_masked: null,
+        owner_name: null,
+        write_tools: false,
+        enabled: record.enabled,
+    };
+}
+function renderAccountLines(rows) {
+    return rows.map((row) => {
+        const who = row.owner_name ? `${row.owner_name}${row.phone_masked ? ` (${row.phone_masked})` : ""}` : "not linked";
+        const writes = row.write_tools ? "writes on" : "writes off";
+        const flag = row.enabled ? row.status : "disabled";
+        return `- **${row.id}** (${row.name}) · ${flag} · ${who} · ${writes}`;
+    });
+}
+export function renderListAccounts(hub) {
+    const accounts = [];
+    for (const record of hub.records()) {
+        const live = hub.binding(record.id);
+        accounts.push(live === undefined ? listedFromRecord(record) : listedFromStatus(live.wa.getStatus(), record.enabled, live.id));
+    }
+    const text = [`# Accounts (${accounts.length})`, "", ...renderAccountLines(accounts)].join("\n");
+    return ok(text, { count: accounts.length, default: hub.defaultBinding().id, accounts });
+}
+function webhookStatusLine(webhook) {
+    if (!webhook.enabled)
+        return "- **webhook**: off";
+    if (!webhook.valid)
+        return `- **webhook**: invalid${webhook.last_error ? ` · ${webhook.last_error}` : ""}`;
+    return `- **webhook**: on${webhook.last_error ? ` · last error: ${webhook.last_error}` : ""}`;
+}
+/** The get_status body: `write_tools` is this session's, not the process default. */
+export function renderGetStatus(s, writeTools, hub) {
+    const account = s.account ? `${s.account.name || "(no name)"} (${s.account.number})` : "none";
+    const writeLine = writeTools
+        ? "registered"
+        : s.read_only
+            ? "not registered (server is read-only; run `wazap config writes on` and restart)"
+            : "not registered (this session used a read token)";
+    const accounts = hub.bindings().map((row) => listedFromStatus(row.wa.getStatus(), true, row.id));
+    const text = [
+        `# WhatsApp: ${s.status} (sync: ${s.sync})`,
+        `- **account**: ${account}`,
+        `- **last message received**: ${s.last_message_received_at ?? "never"}`,
+        `- **contacts named**: ${s.contacts_named}`,
+        `- **data dir**: ${s.data_dir} · **read-only**: ${s.read_only} · **write tools**: ${writeLine} · **rate limit**: ${s.rate_limit}/min`,
+        `- **versions**: wazap ${s.wazap_version}, baileys ${s.baileys_version}`,
+        s.pairing ? `- **pairing code**: ${s.pairing.code} for ${s.pairing.phone_masked}, until ${s.pairing.expires_at}` : null,
+        webhookStatusLine(s.webhook),
+        s.last_error ? `- **last error**: ${s.last_error}` : null,
+        s.hint ? `- **hint**: ${s.hint}` : null,
+        accounts.length > 1 ? `- **accounts**: ${accounts.map((row) => row.id).join(", ")}` : null,
+    ]
+        .filter((line) => line !== null)
+        .join("\n");
+    return ok(text, { ...s, write_tools: writeTools, accounts });
+}