wazap-mcp 0.9.6 → 0.9.8

package/README.md

@@ -180,8 +180,8 @@ manifest, the icon and a fresh production `node_modules`, then packs them with
 | `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. |
@@ -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,6 +359,7 @@ 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
@@ -382,6 +465,14 @@ Claude Code, Claude Desktop, Cursor, Codex, VS Code and any client with an "MCP
 | `WAZAP_HOST` / `WAZAP_PORT` | `127.0.0.1` / `8766` | HTTP bind address. |
 | `WAZAP_READ_TOKEN` / `WAZAP_WRITE_TOKEN` | unset | HTTP bearer tokens. |
 | `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`.
 
@@ -404,6 +495,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/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,11 @@ 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 { 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 +243,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());
@@ -594,6 +665,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

@@ -28,9 +28,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 +90,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" },
@@ -142,6 +148,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 +162,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,28 @@
 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 { 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,
+    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 +107,68 @@ function checkWrites(config) {
         detail: `${config.readOnly ? "off" : "on"} (${config.sources.readOnly})`,
     };
 }
+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
@@ -46,7 +51,9 @@ Options:
 
 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_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 +87,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);