synabun 2.0.5 → 2.0.7

package/neural-interface/lib/whatsapp/config.js

@@ -10,12 +10,17 @@
 // Two kinds of fields:
 //   user     what Settings edits (update(), validated, versioned: a stale
 //            expectedVersion is a 409 like lib/assistant-config.js)
-//   service  what SynaBun owns (mode, the conversation, the bound owner, the
-//            autonomous window, pause) — written by the service and the
-//            bridge through write(), refused in update().
+//   service  what SynaBun owns (mode, the conversation, the bound owner,
+//            pause) — written by the service and the bridge through
+//            write(), refused in update().
 // Raising the level to 'autonomous' never applies here: update() needs
 // confirmEscalation and answers {pending:true}; the service applies it after
-// the phone answers "ALLOW <code>". Lowering applies at once.
+// the phone answers "ALLOW <code>". Lowering applies at once. Autonomous then
+// stays on until the owner lowers it in Settings, restarts included: there is
+// no time limit. `autonomousUntil` is a legacy field (the end of the 8-hour
+// window of 2.0.5 and before): a level 'autonomous' stored with one was turned
+// on under that rule and is read as 'ask' (migrateLegacyAutonomous), so an
+// update never puts anyone back into Autonomous.
 // `computerUse` is the owner's switch for controlling this Mac from a
 // WhatsApp conversation: off by default, a plain boolean, changed only through
 // update() (Settings on this computer: the guarded PUT /api/whatsapp/config).
@@ -25,9 +30,19 @@
 // Assistant) or { provider, model, effort }. Its shape is checked here; the
 // service checks the model and the effort against the Assistant's catalog
 // before it calls update() (lib/whatsapp/brain.js).
+// Voice notes (lib/whatsapp/transcription.js): `transcriptionEnabled`, the
+// spoken `transcriptionLanguage` ('auto' or a 2-3 letter code) and three
+// paths, '' meaning "find it by itself": the whisper-cli program, the ggml
+// model and FFmpeg. A path is the absolute path of an existing regular file
+// (a program executable), checked when update() stores it and again by the
+// host right before it runs; it is never looked up on PATH. Only update()
+// (Settings on this computer) sets a path: a service write may only clear one,
+// so nothing but the person at this computer chooses what the host runs.
 
 import { LEVELS } from '../remote-policy.js';
 import { cleanBrainChoice } from './brain.js';
+import { TRANSCRIPTION_LANGUAGE_RE } from './protocol.js';
+import { checkToolPath } from './transcription.js';
 
 export const WHATSAPP_CONFIG_KEY = 'whatsapp_config';
 
@@ -44,6 +59,11 @@ export const USER_DEFAULTS = Object.freeze({
   strictWorkerApprovals: false,
   computerUse: false,
   brain: null,
+  transcriptionEnabled: true,
+  transcriptionLanguage: 'auto',
+  transcriptionEnginePath: '',
+  transcriptionModelPath: '',
+  transcriptionFfmpegPath: '',
 });
 
 export const SERVICE_DEFAULTS = Object.freeze({
@@ -51,7 +71,7 @@ export const SERVICE_DEFAULTS = Object.freeze({
   sessionId: null,
   previousSessionIds: Object.freeze([]),
   owner: null,              // { masked, boundAt, via } — never a number
-  autonomousUntil: null,    // epoch ms while an autonomous window is open
+  autonomousUntil: null,    // legacy: the end of 2.0.5's 8-hour Autonomous window; always null now (migrateLegacyAutonomous)
   paused: false,
   pausedBy: null,           // 'desktop' | 'phone'
   version: 0,
@@ -68,6 +88,11 @@ export const ROTATIONS = Object.freeze(['idle6h', 'daily', 'never']);
 export const SELF_TRIGGERS = Object.freeze(['all', 'prefix']);
 export const MODES = Object.freeze(['self', 'dedicated']);
 export const REPLY_LABEL_MAX = 24;
+/** The voice-note settings the host gets (service prefsOf → protocol.js PREFS_SPEC). */
+export const TRANSCRIPTION_FIELDS = Object.freeze(['transcriptionEnabled', 'transcriptionLanguage', 'transcriptionEnginePath', 'transcriptionModelPath', 'transcriptionFfmpegPath']);
+/** The path fields and what each must name (transcription.js checkToolPath). */
+export const TOOL_PATH_FIELDS = Object.freeze({ transcriptionEnginePath: 'program', transcriptionModelPath: 'file', transcriptionFfmpegPath: 'program' });
+const TOOL_PATH_MAX = 4096;
 
 const RANK = Object.freeze({ 'read-only': 0, ask: 1, autonomous: 2 });
 
@@ -81,6 +106,28 @@ function configError(field, message, { code = 'CONFIG_INVALID', status = 400 } =
   return error;
 }
 
+/** A tool path's shape: '' (find it by itself) or an absolute path of one line; undefined when it has neither shape. */
+function cleanToolPath(value) {
+  if (value === null || value === undefined) return '';
+  if (typeof value !== 'string') return undefined;
+  const text = value.trim();
+  if (!text) return '';
+  if (text.length > TOOL_PATH_MAX || /[\u0000-\u001f\u007f]/.test(text)) return undefined;
+  return checkToolPath(text, 'program', { fs: SHAPE_ONLY_FS }) === 'not_absolute' ? undefined : text;
+}
+// checkToolPath against nothing on disk: only its shape rules run (absolute, not a network path).
+const SHAPE_ONLY_FS = Object.freeze({ statSync: () => { throw new Error('shape only'); }, accessSync: () => {}, constants: {} });
+
+const TOOL_PATH_PROBLEMS = Object.freeze({
+  not_absolute: 'must be an absolute path (it is never looked up on PATH)',
+  network: 'must be a path on this computer, not on a network share',
+  missing: 'names a file that does not exist',
+  not_file: 'must name a regular file',
+  not_executable: process.platform === 'win32' ? 'must name a program (.exe)' : 'names a file that is not executable (chmod +x it)',
+  unreadable: 'names a file this account cannot read',
+  empty: 'names an empty file',
+});
+
 /** A reply label: printable, one line, 1-24 characters; '' → null (the mode's default label). */
 function cleanLabel(value) {
   if (value === null || value === undefined) return null;
@@ -102,6 +149,8 @@ const CHECKS = {
   activityText: (v) => typeof v === 'boolean',
   strictWorkerApprovals: (v) => typeof v === 'boolean',
   computerUse: (v) => typeof v === 'boolean',
+  transcriptionEnabled: (v) => typeof v === 'boolean',
+  transcriptionLanguage: (v) => typeof v === 'string' && TRANSCRIPTION_LANGUAGE_RE.test(v),
 };
 const MESSAGES = {
   enabled: 'enabled must be true or false',
@@ -116,10 +165,21 @@ const MESSAGES = {
   strictWorkerApprovals: 'strictWorkerApprovals must be true or false',
   computerUse: 'computerUse must be true or false',
   brain: 'brain must be null (same as the Assistant) or { provider, model, effort } with a provider of claude-code, codex or opencode',
+  transcriptionEnabled: 'transcriptionEnabled must be true or false',
+  transcriptionLanguage: "transcriptionLanguage must be 'auto' or a 2-3 letter lowercase language code, such as en or pt",
+  transcriptionEnginePath: 'transcriptionEnginePath must be empty (find whisper-cli by itself) or the absolute path of the whisper-cli program',
+  transcriptionModelPath: 'transcriptionModelPath must be empty (ggml-small.bin in the transcription folder) or the absolute path of a whisper.cpp model file',
+  transcriptionFfmpegPath: 'transcriptionFfmpegPath must be empty (find ffmpeg by itself) or the absolute path of the ffmpeg program',
 };
 
-/** Validate a user patch (Settings fields only). → the cleaned patch; throws 400 CONFIG_INVALID {field}. */
-export function validateConfigPatch(patch = {}) {
+/** Whether a tool path can be used on this computer: null, or why not (transcription.js checkToolPath). */
+const defaultCheckPath = (value, kind) => checkToolPath(value, kind);
+
+/**
+ * Validate a user patch (Settings fields only). → the cleaned patch; throws 400 CONFIG_INVALID {field}.
+ * `checkPath(value, kind)` → null or a problem: how a tool path is checked on disk (tests pass a fake).
+ */
+export function validateConfigPatch(patch = {}, { checkPath = defaultCheckPath } = {}) {
   if (!isPlainObject(patch)) throw configError('config', 'config must be an object');
   const out = {};
   for (const [key, value] of Object.entries(patch)) {
@@ -138,6 +198,14 @@ export function validateConfigPatch(patch = {}) {
       out.brain = brain;
       continue;
     }
+    if (TOOL_PATH_FIELDS[key]) {
+      const toolPath = cleanToolPath(value);
+      if (toolPath === undefined) throw configError(key, MESSAGES[key]);
+      const problem = toolPath ? checkPath(toolPath, TOOL_PATH_FIELDS[key]) : null;
+      if (problem) throw configError(key, `${key} ${TOOL_PATH_PROBLEMS[problem] || 'names a file that cannot be used'}: ${toolPath}`);
+      out[key] = toolPath;
+      continue;
+    }
     if (!CHECKS[key](value)) throw configError(key, MESSAGES[key]);
     out[key] = value;
   }
@@ -157,13 +225,28 @@ function cleanOwner(value) {
   return { masked, boundAt: toMs(value.boundAt), via: value.via === 'claim' ? 'claim' : 'self_confirm' };
 }
 
+/**
+ * A level 'autonomous' stored with an `autonomousUntil` (any value but null) was turned on under
+ * the 8-hour rule of 2.0.5 and before, whether that window is still open or not: it does not
+ * become Autonomous without a time limit. → the stored value as level 'ask' with no
+ * autonomousUntil, or null when `stored` is not such a value. Autonomous stored with
+ * autonomousUntil null is today's state and stays.
+ */
+export function migrateLegacyAutonomous(stored) {
+  if (!isPlainObject(stored) || stored.level !== 'autonomous') return null;
+  if (stored.autonomousUntil === null || stored.autonomousUntil === undefined) return null;
+  return { ...stored, level: 'ask', autonomousUntil: null };
+}
+
 /** Defaults + stored values; a bad stored value falls back to its default, field by field. */
 export function effectiveConfig(stored = {}) {
-  const raw = isPlainObject(stored) ? stored : {};
+  const raw = isPlainObject(stored) ? migrateLegacyAutonomous(stored) || stored : {};
   const out = {};
   for (const key of USER_FIELDS) {
     if (key === 'replyLabel') { const label = cleanLabel(raw.replyLabel); out.replyLabel = label === undefined ? null : label; continue; }
     if (key === 'brain') { const brain = cleanBrainChoice(raw.brain); out.brain = brain === undefined ? null : brain; continue; }
+    // A stored path keeps its shape only: whether the file still works is the host's check, right before it runs.
+    if (TOOL_PATH_FIELDS[key]) { const toolPath = cleanToolPath(raw[key]); out[key] = toolPath === undefined ? '' : toolPath; continue; }
     out[key] = raw[key] !== undefined && CHECKS[key](raw[key]) ? raw[key] : USER_DEFAULTS[key];
   }
   out.mode = MODES.includes(raw.mode) ? raw.mode : SERVICE_DEFAULTS.mode;
@@ -172,7 +255,7 @@ export function effectiveConfig(stored = {}) {
     ? raw.previousSessionIds.map((id) => (typeof id === 'string' ? id : id?.id)).filter((id) => typeof id === 'string' && id).slice(0, 10)
     : [];
   out.owner = cleanOwner(raw.owner);
-  out.autonomousUntil = toMs(raw.autonomousUntil);
+  out.autonomousUntil = null; // legacy: Autonomous has no time limit (migrateLegacyAutonomous)
   out.paused = raw.paused === true;
   out.pausedBy = out.paused && (raw.pausedBy === 'desktop' || raw.pausedBy === 'phone') ? raw.pausedBy : null;
   out.version = Number.isSafeInteger(raw.version) && raw.version >= 0 ? raw.version : 0;
@@ -181,18 +264,23 @@ export function effectiveConfig(stored = {}) {
   return out;
 }
 
-/** 'autonomous' only while its window is open; an expired window reads as 'ask'. */
-export function currentLevel(config, now = Date.now()) {
-  if (config?.level !== 'autonomous') return LEVELS.includes(config?.level) ? config.level : 'ask';
-  return toMs(config.autonomousUntil) > now ? 'autonomous' : 'ask';
+/**
+ * The configured level ('ask' when it is not a known one). Autonomous has no time limit: it
+ * holds until the owner lowers it. A legacy 8-hour Autonomous (migrateLegacyAutonomous) is 'ask'.
+ */
+export function currentLevel(config) {
+  if (migrateLegacyAutonomous(config)) return 'ask';
+  return LEVELS.includes(config?.level) ? config.level : 'ask';
 }
 
 /**
  * @param {object} deps
  * @param {(key:string)=>string|null} deps.get   getKvConfig
  * @param {(key:string, value:string)=>void} deps.set  setKvConfig
+ * @param {() => void} [deps.onLegacyAutonomous]  a legacy 8-hour Autonomous was stored as Ask (once, after it was saved)
+ * @param {(value:string, kind:'program'|'file') => string|null} [deps.checkPath]  how update() checks a tool path on disk
  */
-export function createWhatsAppConfigStore({ get, set, ttlMs = 3000, now = Date.now, log = () => {} } = {}) {
+export function createWhatsAppConfigStore({ get, set, ttlMs = 3000, now = Date.now, log = () => {}, onLegacyAutonomous = null, checkPath = defaultCheckPath } = {}) {
   let cache = null; // { at, value }
 
   function readStored() {
@@ -202,12 +290,34 @@ export function createWhatsAppConfigStore({ get, set, ttlMs = 3000, now = Date.n
     if (!raw) return {};
     try {
       const value = JSON.parse(raw);
-      return isPlainObject(value) ? value : {};
+      return isPlainObject(value) ? migrateStored(value) : {};
     } catch (error) {
       log('whatsapp:config-corrupt', error?.message || String(error));
       return {};
     }
   }
+  /**
+   * A legacy 8-hour Autonomous (migrateLegacyAutonomous) found by any read is stored as Ask at
+   * once, with the version bumped (an open Settings tab reloads before it saves), and reported
+   * once. A store that cannot be written still reads it as Ask, and tries again at the next read.
+   */
+  function migrateStored(value) {
+    const migrated = migrateLegacyAutonomous(value);
+    if (!migrated) return value;
+    const version = Number.isSafeInteger(value.version) && value.version >= 0 ? value.version : 0;
+    const next = { ...migrated, version: version + 1 };
+    try {
+      if (typeof set !== 'function') return next;
+      set(WHATSAPP_CONFIG_KEY, JSON.stringify(next));
+    } catch (error) {
+      log('whatsapp:config-unwritable', `the earlier Autonomous could not be stored as Ask: ${error?.message || String(error)}`);
+      return next;
+    }
+    cache = null;
+    log('whatsapp:config-migrated', 'Autonomous from an earlier version (8-hour window) ended; the level is Ask');
+    try { onLegacyAutonomous?.(); } catch {}
+    return next;
+  }
   function persist(value) {
     if (typeof set === 'function') set(WHATSAPP_CONFIG_KEY, JSON.stringify(value));
     cache = null;
@@ -221,8 +331,8 @@ export function createWhatsAppConfigStore({ get, set, ttlMs = 3000, now = Date.n
 
   /**
    * Service-owned write: service fields, internal state and user fields the
-   * service decides (the confirmed autonomous level, its expiry). A change to
-   * a user field bumps the version so an open Settings tab reloads first.
+   * service decides (the confirmed autonomous level). A change to a user field
+   * bumps the version so an open Settings tab reloads first.
    */
   function write(patch = {}) {
     if (!isPlainObject(patch)) return read();
@@ -239,6 +349,10 @@ export function createWhatsAppConfigStore({ get, set, ttlMs = 3000, now = Date.n
       if (key === 'version') continue;
       // Computer use is turned on by the person at this computer only (update()); the service may only turn it off.
       if (key === 'computerUse' && value !== false) { log('whatsapp:config-ignored', 'computerUse is turned on in Settings only'); continue; }
+      // What the host runs (whisper-cli, FFmpeg) and the model it loads are chosen in Settings only; a service write may clear them.
+      if (TOOL_PATH_FIELDS[key] && value !== '' && value !== null) { log('whatsapp:config-ignored', `${key} is set in Settings only`); continue; }
+      // A legacy field: Autonomous has no time limit, so nothing writes an expiry (only null, which clears it).
+      if (key === 'autonomousUntil' && value !== null) { log('whatsapp:config-ignored', 'autonomousUntil is a legacy field: Autonomous has no time limit'); continue; }
       next[key] = value;
       if (USER_FIELDS.includes(key) && JSON.stringify(effectiveConfig(next)[key]) !== JSON.stringify(before[key])) userChanged = true;
     }
@@ -253,7 +367,7 @@ export function createWhatsAppConfigStore({ get, set, ttlMs = 3000, now = Date.n
    * level waits for the phone (the service holds the escalation).
    */
   function update(patch = {}, { expectedVersion = null, confirmEscalation = false } = {}) {
-    const clean = validateConfigPatch(patch);
+    const clean = validateConfigPatch(patch, { checkPath });
     const stored = readStored();
     const current = effectiveConfig(stored);
     if (expectedVersion !== null && expectedVersion !== undefined && Number(expectedVersion) !== current.version) {
@@ -263,7 +377,7 @@ export function createWhatsAppConfigStore({ get, set, ttlMs = 3000, now = Date.n
     }
     let pending = false;
     if (clean.level !== undefined) {
-      const effective = currentLevel(current, now());
+      const effective = currentLevel(current);
       if (clean.level === 'autonomous') {
         if (effective !== 'autonomous') {
           if (confirmEscalation !== true) throw configError('level', 'Autonomous needs a second confirmation on this computer, then an ALLOW code from your phone.', { code: 'CONFIRM_REQUIRED' });
@@ -271,7 +385,7 @@ export function createWhatsAppConfigStore({ get, set, ttlMs = 3000, now = Date.n
         }
         delete clean.level;
       } else if (RANK[clean.level] < RANK[effective] || clean.level !== current.level) {
-        // Lowering (or leaving an expired autonomous) applies at once and closes the window.
+        // Lowering applies at once (and clears the legacy autonomousUntil).
         clean.autonomousUntil = null;
       }
     }

package/neural-interface/lib/whatsapp/fake-baileys.js

@@ -1,14 +1,16 @@
 // Fake Baileys runtime for tests and SYNABUN_WHATSAPP_FAKE=1. Exports the same
 // names as connector/entry.mjs, with a socket that implements exactly the
 // surface baileys-adapter.js and host-core.js use, plus `fake`: a controller
-// that plays the phone side (scan, inbound from the owner or a stranger, text
-// or image, disconnect by reason name, forbidden, crash) and records every
-// outgoing call so tests can assert who the host talked to.
+// that plays the phone side (scan, inbound from the owner or a stranger, text,
+// image or voice note, disconnect by reason name, forbidden, crash), closes the socket
+// with the errors Baileys 7.0.0-rc14 builds (a stream error, a WebSocket
+// error, a connection failure), can make socket construction throw, and
+// records every outgoing call so tests can assert who the host talked to.
 //
 // Module state is per process: call fake.reset() between tests.
 
 import { EventEmitter } from 'node:events';
-import { randomBytes } from 'node:crypto';
+import { createHash, randomBytes } from 'node:crypto';
 import { FALLBACK_CODEC } from './auth-store.js';
 
 export const BAILEYS_VERSION = 'fake';
@@ -102,13 +104,17 @@ export function getContentType(content) {
 }
 
 export async function downloadMediaMessage(message, _type, _options, ctx) {
-  const img = normalizeMessageContent(message?.message)?.imageMessage;
-  if (!img) throw new Error('not a media message');
-  if (img.fakeFail) {
+  const content = normalizeMessageContent(message?.message);
+  const media = content?.imageMessage || content?.audioMessage;
+  if (!media) throw new Error('not a media message');
+  state.downloads += 1;
+  // A download that never answers (the adapter's 30 s timeout).
+  if (media.fakeHang) return new Promise(() => {});
+  if (media.fakeFail) {
     if (ctx?.reuploadRequest) await ctx.reuploadRequest(message);
     throw Object.assign(new Error('fake download failed'), { status: 404 });
   }
-  return Buffer.from(img.fakeData || []);
+  return Buffer.from(media.fakeData || []);
 }
 
 export async function fetchLatestBaileysVersion() {
@@ -137,6 +143,9 @@ const state = {
   ignoredByJid: 0,
   latestVersion: [2, 3000, 1027934701],
   failNextSend: false,
+  failSockets: 0,           // makeWASocket throws this many more times
+  socketFailures: 0,
+  downloads: 0,             // downloadMediaMessage calls (a refused voice note is never downloaded)
   seq: 0,
   account: { pn: '15550001111', lid: '99887766554433', name: 'Fake Account' },
   people: {
@@ -145,10 +154,11 @@ const state = {
   },
 };
 
-function boom(statusCode, message = 'fake disconnect') {
+function boom(statusCode, message = 'fake disconnect', data = undefined) {
   const err = new Error(message);
   err.isBoom = true;
   err.output = { statusCode, payload: { statusCode, message } };
+  if (data !== undefined) err.data = data;
   return err;
 }
 
@@ -199,16 +209,32 @@ function makeSocket(config) {
         throw new Error('fake send failure');
       }
       const id = `FAKEOUT${++state.seq}`;
+      // A file (whatsapp_send_file): what Baileys would upload, recorded by size and hash, never the bytes.
+      const media = ['document', 'image', 'video', 'audio'].find((key) => content && Buffer.isBuffer(content[key])) || null;
       state.sent.push({
         jid,
-        kind: content?.react ? 'react' : content?.text !== undefined ? 'text' : 'other',
+        kind: content?.react ? 'react' : content?.text !== undefined ? 'text' : media || 'other',
         text: content?.text,
         react: content?.react ? { text: content.react.text, keyId: content.react.key?.id, keyJid: content.react.key?.remoteJid } : undefined,
         linkPreview: content?.linkPreview,
         quotedId: options?.quoted?.key?.id ?? null,
+        ...(media ? {
+          file: {
+            bytes: content[media].length,
+            sha256: createHash('sha256').update(content[media]).digest('hex'),
+            mimetype: content.mimetype ?? null,
+            fileName: content.fileName ?? null,
+            caption: content.caption ?? null,
+            ptt: content.ptt ?? null,
+            keys: Object.keys(content).sort(),
+            jpegThumbnail: Object.hasOwn(content, 'jpegThumbnail') ? content.jpegThumbnail : 'absent',
+          },
+        } : {}),
         at: Date.now(),
       });
-      const message = content?.react ? { reactionMessage: content.react } : { extendedTextMessage: { text: content?.text ?? '' } };
+      const message = content?.react ? { reactionMessage: content.react }
+        : media ? { [`${media}Message`]: { mimetype: content.mimetype ?? null, fileLength: content[media].length, ...(content.fileName ? { fileName: content.fileName } : {}), ...(content.caption ? { caption: content.caption } : {}) } }
+          : { extendedTextMessage: { text: content?.text ?? '' } };
       return { key: { remoteJid: jid, fromMe: true, id }, message, messageTimestamp: Math.floor(Date.now() / 1000) };
     },
     requestPairingCode: async (phone) => {
@@ -263,6 +289,11 @@ function makeSocket(config) {
 }
 
 export function makeWASocket(config) {
+  if (state.failSockets > 0) {
+    state.failSockets -= 1;
+    state.socketFailures += 1;
+    throw new Error('fake socket construction failure');
+  }
   const sock = makeSocket(config);
   state.sockets.push(sock);
   return sock;
@@ -274,13 +305,32 @@ function current() {
   return sock;
 }
 
-function buildContent({ text, image, forwarded, quoted }) {
+function buildContent({ text, image, audio, forwarded, quoted }) {
   const contextInfo = forwarded || quoted
     ? {
       ...(forwarded ? { isForwarded: true, forwardingScore: 1 } : {}),
       ...(quoted ? { stanzaId: quoted.id, quotedMessage: { conversation: quoted.text ?? '' } } : {}),
     }
     : undefined;
+  if (audio) {
+    // A voice note (ptt, OGG/Opus) or an audio file; `seconds` / `fileLength` are what the message declares
+    // (null leaves it out). A caption is not something WhatsApp offers on audio: `text` plays one anyway.
+    const data = Buffer.isBuffer(audio.data) ? audio.data : Buffer.from(audio.base64 || '', 'base64');
+    return {
+      audioMessage: {
+        mimetype: audio.mimetype || 'audio/ogg; codecs=opus',
+        ptt: audio.ptt !== false,
+        ...(audio.seconds === null ? {} : { seconds: audio.seconds ?? 3 }),
+        ...(audio.fileLength === null ? {} : { fileLength: audio.fileLength ?? data.length }),
+        ...(text ? { caption: text } : {}),
+        url: 'https://fake.invalid/media',
+        fakeData: data,
+        fakeFail: !!audio.fail,
+        fakeHang: !!audio.hang,
+        ...(contextInfo ? { contextInfo } : {}),
+      },
+    };
+  }
   if (image) {
     const data = Buffer.isBuffer(image.data) ? image.data : Buffer.from(image.base64 || '', 'base64');
     return {
@@ -315,6 +365,9 @@ export const fake = {
     state.versionFetches = 0;
     state.ignoredByJid = 0;
     state.failNextSend = false;
+    state.failSockets = 0;
+    state.socketFailures = 0;
+    state.downloads = 0;
     state.latestVersion = [2, 3000, 1027934701];
     state.seq = 0;
     state.account = { pn: '15550001111', lid: '99887766554433', name: 'Fake Account' };
@@ -346,7 +399,7 @@ export const fake = {
    * (epoch ms, default now) is when the phone sent it.
    */
   inbound({
-    from = 'self', text, image = null, device = 0, type = 'notify', addressing = 'pn', id, forwarded = false, quoted = null,
+    from = 'self', text, image = null, audio = null, device = 0, type = 'notify', addressing = 'pn', id, forwarded = false, quoted = null,
     requestId, noStanza = false, stanzaFrom, content, stub, at = null, offline = null,
   } = {}) {
     const sock = current();
@@ -364,7 +417,7 @@ export const fake = {
       key: { remoteJid: chatJid, remoteJidAlt: fromMe ? undefined : chatAlt, fromMe, id: msgId, addressingMode: lid ? 'lid' : 'pn' },
       messageTimestamp: ts,
       pushName: 'fake',
-      message: stub ? undefined : content || buildContent({ text, image, forwarded, quoted }),
+      message: stub ? undefined : content || buildContent({ text, image, audio, forwarded, quoted }),
       ...(stub ? { messageStubType: 1 } : {}),
     };
     const stanzaSender = stanzaFrom || senderJid;
@@ -395,6 +448,32 @@ export const fake = {
   forbidden() {
     return fake.disconnect('forbidden');
   },
+  /**
+   * A <stream:error> the way Baileys rc14 closes on it (getErrorCodeFromStreamError + the
+   * CB:stream:error handler): "Stream Errored (<first child tag>)", the code from the node's
+   * own `code` attribute, else 440 for <conflict>, else 500; the child node in `data`.
+   */
+  streamError({ tag = 'unknown', code = null } = {}) {
+    const statusCode = Number(code) || (tag === 'conflict' ? DisconnectReason.connectionReplaced : DisconnectReason.badSession);
+    const reason = statusCode === DisconnectReason.restartRequired ? 'restart required' : tag;
+    current().end(boom(statusCode, `Stream Errored (${reason})`, { tag, attrs: code ? { code: String(code) } : {} }));
+    return { ok: true };
+  },
+  /** A WebSocket error the way mapWebSocketError wraps it: 500 unless getCodeFromWSError places it. */
+  wsError({ message = 'socket hang up', code = 500 } = {}) {
+    current().end(boom(Number(code) || 500, `WebSocket Error (${message})`, { message }));
+    return { ok: true };
+  },
+  /** A <failure> node (CB:failure): "Connection Failure", its `reason` attribute or 500. */
+  connectionFailure({ reason = null } = {}) {
+    current().end(boom(Number(reason) || 500, 'Connection Failure', reason ? { reason: String(reason) } : {}));
+    return { ok: true };
+  },
+  /** The next `n` makeWASocket calls throw (a socket that cannot even be built). */
+  failNextSocket(n = 1) {
+    state.failSockets = Math.max(0, Number(n) || 0);
+    return { ok: true };
+  },
   crash() {
     setImmediate(() => { throw new Error('fake runtime crash'); });
     return { ok: true };
@@ -412,6 +491,8 @@ export const fake = {
       reads: state.reads.map((r) => ({ ...r })),
       pairingRequests: [...state.pairingRequests],
       logouts: state.logouts,
+      socketFailures: state.socketFailures,
+      downloads: state.downloads,
       versionFetches: state.versionFetches,
       ignoredByJid: state.ignoredByJid,
       account: { ...state.account },
@@ -427,6 +508,10 @@ export const fake = {
       inbound: () => fake.inbound(args),
       disconnect: () => fake.disconnect(args.reason),
       forbidden: () => fake.forbidden(),
+      streamError: () => fake.streamError(args),
+      wsError: () => fake.wsError(args),
+      connectionFailure: () => fake.connectionFailure(args),
+      failNextSocket: () => fake.failNextSocket(args.n ?? 1),
       crash: () => fake.crash(),
       failNextSend: () => fake.failNextSend(),
       snapshot: () => fake.snapshot(),