wazap-mcp 0.9.7 → 0.10.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 23 tools any MCP client can
+chats, messages, media, contacts, groups — behind 24 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
@@ -82,7 +82,7 @@ it would write.
 | `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)) |
+| 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)) |
 
 ### Other MCP clients
 
@@ -189,6 +189,7 @@ manifest, the icon and a fresh production `node_modules`, then packs them with
 | `get_contact` | read | Name, number, about text, profile picture. |
 | `get_group_info` | read | Participants, admins, announcement mode, invite link (when you are admin). |
 | `download_media` | read | Save an attachment to disk; small images also come back inline. |
+| `transcribe_audio` | read | Turn a voice note or audio message into text, with the local or the API provider. |
 | `send_message` | write | Send text, optionally as a reply, with @-mentions. |
 | `send_media` | write | Send an image, video, audio, voice note or document from a path or URL. |
 | `send_poll` | write | Send a poll with 2–12 options. |
@@ -202,10 +203,91 @@ manifest, the icon and a fresh production `node_modules`, then packs them with
 | `manage_group` | write | Add, remove, promote, demote, leave, rename, invite links. |
 
 Every message comes back with a non-empty `text`: media and system messages
-carry a placeholder such as `[image] caption`, `[voice message]`, `[deleted]` or
+carry a placeholder such as `[image] caption`, `[voice message · 0:42]`, `[deleted]` or
 `[poll] Pizza or pasta?`. Timestamps are ISO 8601 with the machine's UTC offset,
 alongside a human `age` like `2h ago`.
 
+## Voice messages
+
+A voice note is the one message an agent cannot read. Switch transcription on and
+it becomes text: `[voice message · 0:42] "sunt la notar, ajung în 20 de minute"`,
+with the bare words also in a `transcript` field. `get_recent_messages` and
+`search_messages` see that text, so a voice note becomes findable by what was
+said in it.
+
+Pick a provider once, in `wazap setup` or later:
+
+```bash
+wazap config transcribe local     # free and private, one 574 MB model on disk
+wazap config transcribe openai    # cheap and fast, the audio leaves this machine
+wazap config transcribe off
+```
+
+| | `local` | `openai` |
+| --- | --- | --- |
+| Runs | whisper.cpp, here | any OpenAI-compatible `/audio/transcriptions` |
+| Costs | nothing | per minute of audio, on your key |
+| Privacy | the audio never leaves this machine | **the audio leaves this machine** |
+| Needs | `whisper-cpp` and `ffmpeg`, plus a model | an API key |
+
+### Local, with whisper.cpp
+
+```bash
+brew install whisper-cpp ffmpeg      # macOS; elsewhere build whisper.cpp, install ffmpeg from your package manager
+wazap transcribe download            # fetch and verify the model
+wazap transcribe test recording.ogg  # prove it before you trust it
+```
+
+Models land in `<data-dir>/models/` and are checked against a SHA-256 pinned in
+the source; an interrupted download resumes where it stopped.
+
+| `WAZAP_WHISPER_MODEL` | File | Size |
+| --- | --- | --- |
+| `turbo` (default) | `ggml-large-v3-turbo-q5_0.bin` | 574 MB |
+| `large-v3` | `ggml-large-v3-q5_0.bin` | 1.08 GB |
+| `medium` | `ggml-medium-q5_0.bin` | 539 MB |
+
+`turbo` is the default because it is the smallest model that still gets Romanian
+right. `medium` and below drop diacritics and mangle names, which is worse than
+no transcript at all: a missing transcript is a question, a wrong name is a wrong
+answer. `large-v3` is the same accuracy for several times the wait.
+
+### An API, OpenAI-compatible
+
+`wazap config transcribe openai` asks for the key without echoing it and stores
+it in `<data-dir>/.env`. The default endpoint is OpenAI; Groq works unchanged:
+
+```bash
+WAZAP_TRANSCRIBE_URL=https://api.groq.com/openai/v1
+WAZAP_TRANSCRIBE_MODEL=whisper-large-v3-turbo
+```
+
+**With this provider the audio leaves your machine.** Every voice note wazap
+transcribes is uploaded to that endpoint. If that is not acceptable, use `local`,
+which uploads nothing.
+
+The key is treated as a secret rather than as a setting:
+
+- It is never accepted as a command-line argument, because an argument lands in
+  your shell history and in `ps`.
+- The prompt echoes nothing, not even asterisks.
+- It is stored only in `<data-dir>/.env`, mode `0600`.
+- `status`, `status --json`, `config` and `get_status` show at most
+  `api key: set (…abcd)`.
+- A provider's own error message has the key stripped out of it before wazap
+  prints it.
+- A plain-`http` `WAZAP_TRANSCRIBE_URL` is refused unless it points back at this
+  machine.
+
+### Without being asked
+
+With a provider configured, incoming voice notes of up to ten minutes are
+transcribed in the background as they arrive, one at a time, never holding up a
+message. The transcript is cached by message id and persisted, so a voice note is
+transcribed once and not again after a restart. Audio *files* are left alone,
+since one can be an hour long; call `transcribe_audio(message_id)` for those.
+`WAZAP_TRANSCRIBE_AUTO=0` keeps the tool and stops the background work.
+
 ## Skills
 
 wazap ships five [Agent Skills](https://agentskills.io) that teach an agent the workflows behind the tools, not just the tools:
@@ -277,9 +359,11 @@ created `0700` with credentials written `0600`:
   auth/         WhatsApp credentials — treat this like a password
   media/        downloads from download_media
   history/      per-chat message history, so a restart is not amnesia
+  models/       whisper.cpp models, when transcription runs locally
   store.json    chat-list snapshot
   server.lock   pid of the running server
   daemon.json   loopback endpoint a second wazap bridges to
+  oauth.json    registered agents and hashed OAuth grants, when OAuth is on
   .env          optional settings, see .env.example
 ```
 
@@ -330,7 +414,8 @@ npx wazap-mcp serve --http --host 0.0.0.0 --port 8766
 Streamable HTTP at `/mcp`, with a health check at `/healthz`. 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.
+non-loopback address without a read token. Agents that cannot carry a header
+sign in with [OAuth](#hosted-agents-oauth) instead.
 
 ## Self-host
 
@@ -365,9 +450,63 @@ curl -s http://127.0.0.1:8766/healthz
 
 The container publishes `8766` on loopback only; add the same TLS proxy in front. Upgrading is `git pull && docker compose up -d --build`; the volume keeps the session.
 
+### From a machine without a public address
+
+A laptop or a box behind NAT can still serve hosted agents through a tunnel, with no port opened and TLS done at the edge. With [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) and a domain on Cloudflare:
+
+```bash
+cloudflared tunnel login
+cloudflared tunnel create wazap
+cloudflared tunnel route dns wazap wazap.example.com
+cloudflared tunnel run --url http://127.0.0.1:8766 wazap
+```
+
+wazap keeps binding loopback; only the tunnel reaches it. Set `WAZAP_PUBLIC_URL=https://wazap.example.com` for OAuth and keep `cloudflared` running the way you keep wazap running (a systemd unit, a launchd agent). Tailscale Funnel or ngrok work the same way: whatever ends at `https://your-host` with `/mcp` behind it.
+
 ### Which clients can reach it
 
-Claude Code, Claude Desktop, Cursor, Codex, VS Code and any client with an "MCP URL + header" field connect with the bearer token. claude.ai Connectors require OAuth rather than a static token, so they cannot use a self-hosted wazap yet. Keep the read token in clients that only need to read; hand out the write token deliberately.
+Claude Code, Claude Desktop, Cursor, Codex, VS Code, Poke and any client with an "MCP URL + header" field connect with the bearer token. Keep the read token in clients that only need to read; hand out the write token deliberately.
+
+claude.ai Connectors, ChatGPT and some hosted agents will not take a static header. They want OAuth, which is the next section.
+
+### Hosted agents (OAuth)
+
+Two more lines in the same `.env` turn wazap into its own OAuth 2.1 server:
+
+```bash
+WAZAP_PUBLIC_URL=https://wazap.example.com
+WAZAP_OAUTH_PASSWORD=$(openssl rand -base64 18)
+```
+
+Then give an agent nothing but `https://wazap.example.com/mcp`. It finds the
+authorization server at `/.well-known/oauth-protected-resource/mcp`, registers
+itself (RFC 7591, so there is no client id to paste anywhere), and sends you to
+a page on your own host that asks two things: the password above, and whether
+this agent may only read or also send. A refresh token keeps the agent signed
+in until you revoke it; access tokens rotate every 24 hours on their own.
+
+Tested against the flow claude.ai, ChatGPT and Poke use: S256 PKCE, public
+clients, `/token` with refresh, `/revoke`. The bearer tokens keep working next
+to it, so a laptop client on a header and a hosted agent on OAuth share one
+server.
+
+What to know before exposing it:
+
+- `WAZAP_PUBLIC_URL` must be `https` and a bare origin, no path: the
+  endpoints live at its root. The password travels to it.
+- The password is the whole identity layer. Use a long one. A consent page
+  takes three wrong guesses and is gone; five from one address lock that
+  address out for fifteen minutes; twenty from anywhere close the page for
+  everyone for fifteen minutes.
+- With OAuth on, `/mcp` never answers an unauthenticated request, whether or
+  not a read token is set.
+- Grants live in `<data-dir>/oauth.json` as hashes. Delete the file to sign
+  every agent out at once, running server included; `wazap status` lists who
+  holds one. Disconnecting an agent on its side revokes its refresh token and
+  every access token it minted. A refresh token unused for ninety days is
+  dropped.
+- 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.
 
 ## Settings
 
@@ -381,7 +520,17 @@ Claude Code, Claude Desktop, Cursor, Codex, VS Code and any client with an "MCP
 | `WAZAP_TRANSPORT` | `stdio` | `stdio` or `http`. |
 | `WAZAP_HOST` / `WAZAP_PORT` | `127.0.0.1` / `8766` | HTTP bind address. |
 | `WAZAP_READ_TOKEN` / `WAZAP_WRITE_TOKEN` | unset | HTTP bearer tokens. |
+| `WAZAP_PUBLIC_URL` | unset | The `https` address agents reach the server at. With the password, turns OAuth on. |
+| `WAZAP_OAUTH_PASSWORD` | unset | What the consent page asks for. At least 8 characters. |
 | `WAZAP_NO_UPDATE_CHECK` | `0` | `1` stops `status` asking npm for a newer version. |
+| `WAZAP_TRANSCRIBE` | `off` | `local`, `openai` or `off`. |
+| `WAZAP_TRANSCRIBE_AUTO` | `1` | Transcribe incoming voice notes in the background. |
+| `WAZAP_TRANSCRIBE_LANGUAGE` | `auto` | Spoken language, e.g. `ro`. |
+| `WAZAP_WHISPER_MODEL` | `turbo` | `turbo`, `large-v3` or `medium`. |
+| `WAZAP_WHISPER_BIN` | unset | Path to a whisper.cpp binary that is not on `PATH`. |
+| `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. |
 
 Flags beat environment variables, which beat `<data-dir>/.env`.
 

package/dist/cli.js

@@ -1,4 +1,5 @@
 import { randomBytes } from "node:crypto";
+import { once } from "node:events";
 import { mkdirSync, rmSync } from "node:fs";
 import { createInterface } from "node:readline/promises";
 import { setTimeout as sleep } from "node:timers/promises";
@@ -16,10 +17,12 @@ import { RELINK_FIX, WazapError, asWazapError } from "./errors.js";
 import { normalizePhone } from "./ids.js";
 import { lockHolder, releaseLock, writeLock } from "./lock.js";
 import { log, logError, say } from "./logger.js";
-import { formatAge } from "./messages.js";
+import { clockLabel, formatAge } from "./messages.js";
 import { RateLimiter } from "./ratelimit.js";
+import { oauthProblem } from "./oauth.js";
 import { runHttp, runStdio, startLoopbackEndpoint } from "./server.js";
 import { applyWrites } from "./settings.js";
+import { MODELS, downloadModel, maskKey, modelSpec, readTranscribeSettings, stripPasted, transcribeFile, transcribeReady, } from "./transcribe/index.js";
 import { bold, box, brand, humanLayout, dim, fail, fix, info, maskNumber, next, ok, shortPath, spinner, step, tilde, warn, } from "./ui.js";
 import { WA_BROWSER, WhatsAppService } from "./whatsapp.js";
 const LOGIN_TIMEOUT_MS = 120_000;
@@ -241,6 +244,75 @@ export async function runContacts(config) {
         releaseLock(p.lockFile);
     }
 }
+const MIB = 1024 * 1024;
+function mib(bytes) {
+    return Math.round(bytes / MIB);
+}
+/** `wazap transcribe download` and `wazap transcribe test <audio file>`. */
+export async function runTranscribe(config) {
+    const [verb, file] = config.args;
+    const settings = readTranscribeSettings(process.env, config.dataDir);
+    if (verb === "download" && file === undefined) {
+        await downloadTranscribeModel(settings, modelSpec(config.modelName ?? settings.model));
+        return;
+    }
+    if (verb === "test" && file !== undefined) {
+        await testTranscribe(settings, file);
+        return;
+    }
+    throw new WazapError("INVALID_ID", `Cannot run \`wazap transcribe ${config.args.join(" ")}\`.`, "Run `wazap transcribe download` or `wazap transcribe test <audio file>`");
+}
+/**
+ * Also `setup`'s download step. A model already on disk is re-hashed rather than
+ * trusted, which is why the line starts as a check and only then becomes a fetch.
+ */
+export async function downloadTranscribeModel(settings, spec) {
+    const spin = spinner(`Checking ${spec.file}…`);
+    try {
+        const result = await downloadModel(settings.modelsDir, spec, (progress) => {
+            const percent = Math.floor((progress.received / progress.total) * 100);
+            spin.update(`Downloading ${spec.file} — ${mib(progress.received)} / ${mib(progress.total)} MiB (${percent}%)`);
+        });
+        spin.stop(ok(`${spec.file} (${mib(spec.bytes)} MiB) ${result.alreadyPresent ? "already present" : "verified"}`));
+    }
+    catch (err) {
+        spin.stop();
+        throw err;
+    }
+}
+/** What identifies each provider on screen. Keyed like PROVIDERS, never branched on. */
+const PROVIDER_ROWS = {
+    local: (settings) => [
+        ["provider", "local (whisper.cpp)"],
+        ["model", MODELS[settings.model].file],
+    ],
+    openai: (settings) => [
+        ["provider", `openai (${new URL(settings.baseUrl).host})`],
+        ["model", settings.apiModel],
+        ["key", maskKey(settings.apiKey)],
+    ],
+};
+async function testTranscribe(settings, file) {
+    const readiness = await transcribeReady(settings);
+    const provider = settings.provider;
+    if (provider === null || !readiness.ok) {
+        throw new WazapError("TRANSCRIBE_UNAVAILABLE", readiness.detail, readiness.fix);
+    }
+    for (const [label, value] of PROVIDER_ROWS[provider](settings))
+        say(row(label, value));
+    say(row("language", settings.language));
+    say("");
+    const started = Date.now();
+    const spin = spinner(`Transcribing ${shortPath(file)}…`);
+    const transcript = await transcribeFile(settings, file).finally(() => spin.stop());
+    const facts = [
+        `transcribed in ${((Date.now() - started) / 1000).toFixed(1)}s`,
+        transcript.language,
+        transcript.duration_seconds === undefined ? undefined : clockLabel(transcript.duration_seconds),
+    ];
+    say(ok(facts.filter((fact) => fact !== undefined).join(" · ")));
+    say(`"${transcript.text}"`);
+}
 /** Bare `wazap` at a terminal: where you stand, and the one command to run next. */
 export async function runGreet(config) {
     say(banner());
@@ -279,6 +351,13 @@ export async function runServe(config) {
             say(fail(`Refusing to serve ${config.httpHost} without a token. Set WAZAP_READ_TOKEN, or bind 127.0.0.1.`));
             process.exit(1);
         }
+        if (config.transport === "http") {
+            const problem = oauthProblem(config);
+            if (problem) {
+                say(fail(problem));
+                process.exit(1);
+            }
+        }
         mkdirSync(config.dataDir, { recursive: true, mode: 0o700 });
         if (writeLock(p.lockFile)) {
             claimed = true;
@@ -594,6 +673,27 @@ export async function ask(question) {
         rl.close();
     }
 }
+/**
+ * A secret typed at the prompt, echoed nowhere: not as characters, not as stars.
+ * readline is given no output stream at all, which is the only mute that holds
+ * on current Node — overriding `_writeToOutput` no longer reaches the interface's
+ * own writer. `terminal` still follows the real stdin, so a TTY goes into raw
+ * mode (the kernel stops echoing too) and a pipe reads one line for a script.
+ */
+export async function askSecret(question) {
+    const rl = createInterface({ input: process.stdin, output: undefined, terminal: process.stdin.isTTY === true });
+    process.stderr.write(question);
+    try {
+        // End of input answers nothing rather than hanging the command, and the
+        // caller refuses an empty secret.
+        const answered = rl.question("").catch(() => "");
+        return stripPasted(await Promise.race([answered, once(rl, "close").then(() => "")]));
+    }
+    finally {
+        rl.close();
+        process.stderr.write("\n");
+    }
+}
 const PHONE_ATTEMPTS = 3;
 /** A typo costs another prompt, not the whole login. */
 async function askPhone() {

package/dist/config.js

@@ -16,6 +16,7 @@ export function paths(dataDir) {
         storeFile: join(dataDir, "store.json"),
         lockFile: join(dataDir, "server.lock"),
         daemonFile: join(dataDir, "daemon.json"),
+        oauthFile: join(dataDir, "oauth.json"),
         envFile: join(dataDir, ".env"),
         qrFile: join(dataDir, "qr.png"),
     };
@@ -28,9 +29,13 @@ const COMMAND_ARGS = {
     status: [0],
     logout: [0],
     connect: [1],
-    config: [0, 2],
+    // A third positional is only ever someone typing the API key after
+    // `config transcribe openai`. It is accepted here so runConfig can refuse it
+    // with the reason, rather than with a generic arity complaint.
+    config: [0, 2, 3],
     contacts: [1],
     skills: [2],
+    transcribe: [1, 2],
 };
 const COMMANDS = Object.keys(COMMAND_ARGS);
 export function defaultDataDir() {
@@ -86,6 +91,8 @@ export function parseCli(argv = process.argv.slice(2)) {
                 "no-writes": { type: "boolean" },
                 agent: { type: "boolean" },
                 client: { type: "string", multiple: true },
+                model: { type: "string" },
+                transcribe: { type: "string" },
                 yes: { type: "boolean", short: "y" },
                 help: { type: "boolean", short: "h" },
                 version: { type: "boolean", short: "v" },
@@ -134,6 +141,8 @@ export function parseCli(argv = process.argv.slice(2)) {
             httpPort: values.port ? asInt(values.port, 8766) : asInt(process.env.WAZAP_PORT, 8766),
             readToken: (process.env.WAZAP_READ_TOKEN ?? "").trim() || null,
             writeToken: (process.env.WAZAP_WRITE_TOKEN ?? "").trim() || null,
+            publicUrl: (process.env.WAZAP_PUBLIC_URL ?? "").trim().replace(/\/+$/, "") || null,
+            oauthPassword: process.env.WAZAP_OAUTH_PASSWORD || null,
             share: !asBool(process.env.WAZAP_NO_SHARE, false),
             rateLimitPerMinute: asInt(process.env.WAZAP_RATE_LIMIT, 20),
             sources: {
@@ -142,6 +151,7 @@ export function parseCli(argv = process.argv.slice(2)) {
                 readOnly: sourceOf("WAZAP_READ_ONLY", values["read-only"] === true),
                 transport: sourceOf("WAZAP_TRANSPORT", values.http === true),
                 rateLimit: sourceOf("WAZAP_RATE_LIMIT", false),
+                transcribe: sourceOf("WAZAP_TRANSCRIBE", false),
             },
             command,
             explicitCommand: first !== undefined,
@@ -155,6 +165,8 @@ export function parseCli(argv = process.argv.slice(2)) {
             agent: values.agent === true,
             clients: values.client ?? [],
             assumeYes: values.yes === true,
+            modelName: values.model,
+            transcribeChoice: values.transcribe,
         },
     };
 }

package/dist/doctor.js

@@ -1,18 +1,30 @@
 import { accessSync, constants, statSync } from "node:fs";
 import { readLinkedAccount } from "./auth-state.js";
 import { WAZAP_VERSION, paths } from "./config.js";
+import { asWazapError } from "./errors.js";
 import { lockHolder, lockPid } from "./lock.js";
+import { oauthProblem, readGrants } from "./oauth.js";
+import { MODELS, findWhisper, localProvider, maskKey, modelPath, readTranscribeSettings, which, } from "./transcribe/index.js";
 import { dim, fail, fix, green, info, ok, red } from "./ui.js";
 export const MARK = { ok: "✓", fail: "✗", info: "–" };
 const GLYPH = { ok, fail, info };
 const TINT = { ok: green, fail: red, info: dim };
 const UPDATE_TIMEOUT_MS = 2_000;
 const MIN_NODE_MAJOR = 20;
-const CHECKS = [checkNode, checkDataDir, checkLock, checkCredentials, checkWrites, checkUpdate];
+const CHECKS = [
+    checkNode,
+    checkDataDir,
+    checkLock,
+    checkCredentials,
+    checkWrites,
+    checkOAuth,
+    checkTranscribe,
+    checkUpdate,
+];
 export async function runChecks(config) {
     const checks = [];
     for (const check of CHECKS)
-        checks.push(await check(config));
+        checks.push(...[await check(config)].flat());
     return checks;
 }
 /**
@@ -97,6 +109,85 @@ function checkWrites(config) {
         detail: `${config.readOnly ? "off" : "on"} (${config.sources.readOnly})`,
     };
 }
+/** Only when OAuth is configured: whether it can start, and who is signed in. */
+function checkOAuth(config) {
+    if (!config.publicUrl && !config.oauthPassword)
+        return [];
+    const problem = oauthProblem(config);
+    if (problem)
+        return [{ name: "oauth", state: "fail", detail: problem, fix: "edit <data-dir>/.env" }];
+    if (config.transport !== "http") {
+        return [{ name: "oauth", state: "info", detail: "configured, but only served with WAZAP_TRANSPORT=http" }];
+    }
+    const grants = readGrants(paths(config.dataDir).oauthFile);
+    if (grants.length === 0) {
+        return [{ name: "oauth", state: "info", detail: `on at ${config.publicUrl}, no agent signed in yet` }];
+    }
+    const who = grants.map((g) => `${g.client} (${g.scopes.join("+")})`).join(", ");
+    return [{ name: "oauth", state: "ok", detail: `on at ${config.publicUrl}; signed in: ${who}` }];
+}
+const TRANSCRIBE_OFF_FIX = "run `wazap config transcribe local` to transcribe voice messages";
+const DOWNLOAD_FIX = "run `wazap transcribe download`";
+const KEY_FIX = "run `wazap config transcribe openai`";
+const MIB = 1024 * 1024;
+/** What each provider needs before it can run. Keyed like PROVIDERS. */
+const TRANSCRIBE_CHECKS = {
+    local: localChecks,
+    openai: openaiChecks,
+};
+async function checkTranscribe(config) {
+    let settings;
+    try {
+        settings = readTranscribeSettings(process.env, config.dataDir);
+    }
+    catch (err) {
+        // A stale WAZAP_TRANSCRIBE_URL or provider name in someone's .env is exactly
+        // what status is for, so the refusal is reported rather than thrown.
+        const failure = asWazapError(err);
+        return { name: "transcribe", state: "fail", detail: failure.message, fix: failure.fix };
+    }
+    if (settings.provider === null)
+        return { name: "transcribe", state: "info", detail: "off", fix: TRANSCRIBE_OFF_FIX };
+    return TRANSCRIBE_CHECKS[settings.provider](settings);
+}
+function fileSize(path) {
+    try {
+        return statSync(path).size;
+    }
+    catch {
+        return null;
+    }
+}
+async function localChecks(settings) {
+    const whisper = findWhisper(settings);
+    const ffmpeg = which("ffmpeg");
+    const spec = MODELS[settings.model];
+    const size = fileSize(modelPath(settings.modelsDir, spec));
+    // ready() reports only the first problem and looks at the binaries before the
+    // model, so its fix is the platform's install hint whenever one is missing.
+    const install = (await localProvider.ready(settings)).fix;
+    return [
+        { name: "transcribe", state: "ok", detail: "local (whisper.cpp)" },
+        whisper === null
+            ? { name: "whisper", state: "fail", detail: "not found", fix: install }
+            : { name: "whisper", state: "ok", detail: whisper },
+        ffmpeg === null
+            ? { name: "ffmpeg", state: "fail", detail: "not found", fix: install }
+            : { name: "ffmpeg", state: "ok", detail: "found" },
+        size === null
+            ? { name: "model", state: "fail", detail: `${spec.file} is not downloaded`, fix: DOWNLOAD_FIX }
+            : { name: "model", state: "ok", detail: `${spec.file} (${Math.round(size / MIB)} MiB)` },
+    ];
+}
+/** maskKey is the only thing that ever renders the key, here and everywhere else. */
+function openaiChecks(settings) {
+    return [
+        { name: "transcribe", state: "ok", detail: `openai (${settings.apiModel} at ${new URL(settings.baseUrl).host})` },
+        settings.apiKey === null
+            ? { name: "api key", state: "fail", detail: maskKey(null), fix: KEY_FIX }
+            : { name: "api key", state: "ok", detail: maskKey(settings.apiKey) },
+    ];
+}
 /** Version comparison over the numeric release fields; prereleases sort as their release. */
 export function isNewer(candidate, current) {
     const parts = (version) => version.split(/[.\-+]/, 3).map((piece) => Number.parseInt(piece, 10) || 0);

package/dist/errors.js

@@ -37,6 +37,8 @@ export const ERROR_GUIDE = {
     NOT_OWN_MESSAGE: "This action only works on messages the linked account sent. Do not retry.",
     READ_ONLY: "wazap runs read-only, so writes are refused. Tell the user to restart without WAZAP_READ_ONLY.",
     RATE_LIMITED: "Too many writes too fast. Wait the number of seconds in the fix, then retry once.",
+    TRANSCRIBE_UNAVAILABLE: "Transcription is off, or its binaries or model are missing. Tell the user to run the command in the fix; do not retry.",
+    TRANSCRIBE_FAILED: "The transcription provider ran and failed. Read the message; retry once at most.",
     TIMEOUT: "WhatsApp did not answer in time. Retry once; if it fails again, call get_status.",
     WHATSAPP_ERROR: "WhatsApp rejected the operation. Read the message; do not blindly retry.",
 };

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { BANNER } from "./banner.js";
-import { runContacts, runGreet, runLogin, runLogout, runServe, runStatus } from "./cli.js";
+import { runContacts, runGreet, runLogin, runLogout, runServe, runStatus, runTranscribe } 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";
@@ -17,7 +17,10 @@ Usage:
   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 config [writes on|off] [transcribe local|openai|off]
+                                                           Show the effective settings, or change one
+  wazap transcribe download [--model <alias>]              Fetch the whisper.cpp model into the data dir
+  wazap transcribe test <audio file>                       Transcribe a local file with the configured provider
   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
@@ -35,6 +38,8 @@ 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)
+  --transcribe <how>  With setup: answer the transcription question (local, openai or off)
+  --model <alias>     With transcribe download: turbo (default), large-v3 or medium
   --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
@@ -45,8 +50,11 @@ Options:
   -v, --version       Show the version
 
 Environment: WAZAP_DATA_DIR, WAZAP_READ_ONLY, WAZAP_SYNC_FULL_HISTORY, WAZAP_PERSIST_HISTORY,
-WAZAP_TRANSPORT, WAZAP_HOST, WAZAP_PORT, WAZAP_READ_TOKEN, WAZAP_WRITE_TOKEN, WAZAP_RATE_LIMIT,
-WAZAP_NO_SHARE, WAZAP_NO_UPDATE_CHECK.
+WAZAP_TRANSPORT, WAZAP_HOST, WAZAP_PORT, WAZAP_READ_TOKEN, WAZAP_WRITE_TOKEN, WAZAP_PUBLIC_URL,
+WAZAP_OAUTH_PASSWORD, WAZAP_RATE_LIMIT,
+WAZAP_NO_SHARE, WAZAP_NO_UPDATE_CHECK, WAZAP_TRANSCRIBE, WAZAP_TRANSCRIBE_AUTO,
+WAZAP_TRANSCRIBE_LANGUAGE, WAZAP_TRANSCRIBE_API_KEY, WAZAP_TRANSCRIBE_URL, WAZAP_TRANSCRIBE_MODEL,
+WAZAP_WHISPER_MODEL, WAZAP_WHISPER_BIN.
 An optional <data-dir>/.env is loaded if present.`;
 async function main() {
     const invocation = parseCli();
@@ -80,7 +88,10 @@ async function main() {
             runSkills(config);
             return;
         case "config":
-            runConfig(config);
+            await runConfig(config);
+            return;
+        case "transcribe":
+            await runTranscribe(config);
             return;
         case "contacts":
             await runContacts(config);