synabun 2.0.5 → 2.0.9

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

@@ -1,8 +1,12 @@
 // Main-process side of the WhatsApp Link: forks host.js — the only process
 // that loads Baileys or reads the WhatsApp credentials — speaks protocol.js
-// over IPC, respawns it with backoff, and trips a crash breaker (host.state
-// 'held') when it keeps dying. mode 'inproc' (SYNABUN_WHATSAPP_HOST=inproc)
-// runs host-core inside this process instead: tests and a kill switch.
+// over IPC, and respawns it whenever it dies, for as long as it is wanted:
+// 1 / 5 / 15 / 60 / 300 s, never more than 300 s, the ladder starting over
+// once a host ran for 10 minutes. host.state 'held' is only a host speaking
+// another IPC protocol (an update installed while SynaBun ran): it is killed
+// and stays down until start() again. mode 'inproc'
+// (SYNABUN_WHATSAPP_HOST=inproc) runs host-core inside this process instead:
+// tests and a kill switch.
 //
 // Same shape as lib/pty-host/manager.js and lib/desktop/manager.js, with two
 // deliberate differences: the child gets an ALLOWLISTED environment (no API
@@ -10,15 +14,19 @@
 // redacted before it reaches a log (never inherited).
 //
 // Every method resolves; none rejects. Failures are {ok:false, code, message}.
-// After a respawn the host receives the last configure, then — if the link
-// was running — connect({purpose:'run'}) again.
+// The run intent (connect({purpose:'run'}), or a fresh link) is kept here
+// before the request leaves, so a host that is still starting, or one that
+// crashed with the request in flight, gets it anyway: every ready replays the
+// last configure, then connect({purpose:'run'}) while the intent stands. Only
+// NOT_LINKED, a terminal state or fatal event of the host (TERMINAL_CONN,
+// DESIRE_KILLERS), stop(), disconnect() and logout() drop it.
 
 import { fork } from 'node:child_process';
 import { mkdirSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
-import { CONN, ERR, EV, LIMITS, OP, PROTOCOL_VERSION, pickPrefs, validateEvent } from './protocol.js';
+import { ADDRESS_KEYS, CONN, ERR, EV, LIMITS, OP, PROTOCOL_VERSION, pickPrefs, validateEvent } from './protocol.js';
 import { resolveWhatsAppPaths } from './paths.js';
-import { redactWa } from './redact.js';
+import { redactLogLine, redactWa } from './redact.js';
 
 const HOST_PATH = fileURLToPath(new URL('./host.js', import.meta.url));
 
@@ -77,7 +85,10 @@ export function hostExecArgv(parent = process.execArgv, { nodeVersion = process.
 
 const PUBLIC_EVENTS = new Set(['state', 'qr', 'pairing_code', 'linked', 'owner_bound', 'inbound', 'ignored', 'throttled', 'fatal']);
 const TERMINAL_CONN = new Set([CONN.LOGGED_OUT, CONN.REPLACED, CONN.FORBIDDEN, CONN.UNLINKED, CONN.LINK_EXPIRED, CONN.ERROR, CONN.LOCKED]);
-const DESIRE_KILLERS = new Set(['LOGGED_OUT', 'REPLACED', 'FORBIDDEN', 'SESSION_ERROR', 'CONFIRM_TIMEOUT', 'RECONNECT_LIMIT', 'LOCKED']);
+// Fatal events that end the run intent: a logout (401, or a session WhatsApp calls invalid), an
+// account refused while linking, an owner never confirmed, a session store held by another process.
+// A saved session never stops on 440, 403 or a generic 500: the host retries those.
+const DESIRE_KILLERS = new Set(['LOGGED_OUT', 'FORBIDDEN', 'CONFIRM_TIMEOUT', 'LOCKED']);
 const LINE_BURST = 60;
 const LINE_WINDOW_MS = 60_000;
 
@@ -114,11 +125,12 @@ export function createWhatsAppManager({
   log = () => {},
   now = () => Date.now(),
   respawnBackoffMs = [1000, 5000, 15000, 60000, 300000],
-  crashLimit = 5,
-  crashWindowMs = 15 * 60_000,
+  respawnMaxMs = 300_000,    // no respawn waits longer, whatever the ladder says
   stableMs = 10 * 60_000,
   requestTimeoutMs = 15_000,
   sendTimeoutMs = 90_000,
+  // send_file: a read of up to 100 MiB and its upload. Past it the delivery is uncertain (never retried).
+  sendFileTimeoutMs = 120_000,
   readyTimeoutMs = 20_000,
   env = process.env,
   platform = process.platform,
@@ -135,7 +147,6 @@ export function createWhatsAppManager({
   let core = null;
   let token = null;          // identity of the current host (child or inproc core)
   let ready = false;
-  let hadReady = false;
   let hostState = 'stopped';
   let hostPid = null;
   let restarts = 0;
@@ -143,10 +154,10 @@ export function createWhatsAppManager({
   let heldReason = null;
   let launchError = null;    // why the current launch failed before its ready event
   let configured = Promise.resolve(); // the configure replayed on ready
-  let exitTimes = [];
   let failIdx = 0;
   let startedAt = 0;
   let respawnTimer = null;
+  let respawnAt = null;      // when the next host starts, while hostState is 'backoff'
   let readyTimer = null;
   let stoppedByUser = true;
   let lastPrefs = null;
@@ -175,8 +186,11 @@ export function createWhatsAppManager({
     const conn = { ...connCache };
     if (hostState === 'held') conn.state = CONN.HELD;
     else if (hostState === 'stopped') conn.state = CONN.IDLE;
+    // host.retryInMs: how long until the next host starts. While the link is wanted, conn says
+    // "reconnecting" with the same wait (set when the respawn was scheduled, like the host's own retryInMs).
+    const retryInMs = hostState === 'backoff' && respawnAt !== null ? Math.max(0, respawnAt - now()) : null;
     return {
-      host: { state: hostState, pid: hostPid, restarts, lastError },
+      host: { state: hostState, pid: hostPid, restarts, lastError, retryInMs },
       conn,
       runtime: { ...runtimeInfo },
     };
@@ -225,7 +239,7 @@ export function createWhatsAppManager({
   function request(op, fields = {}, { timeoutMs = requestTimeoutMs } = {}) {
     return new Promise((resolve) => {
       if (hostState === 'held') {
-        resolve(fail(ERR.HELD, heldReason || lastError || 'the WhatsApp host is held after repeated crashes'));
+        resolve(fail(ERR.HELD, heldReason || lastError || 'the WhatsApp host speaks another protocol version'));
         return;
       }
       if (hostState === 'stopped') {
@@ -280,6 +294,7 @@ export function createWhatsAppManager({
 
   // ── Host → manager ──
 
+  /** An incompatible host (another IPC protocol): no respawn until start() again. */
   function hold(reason) {
     heldReason = reason;
     lastError = reason;
@@ -287,6 +302,7 @@ export function createWhatsAppManager({
     desired = null;
     clearTimeout(respawnTimer);
     respawnTimer = null;
+    respawnAt = null;
     failAll(ERR.HELD, reason);
     resolveReadyWaiters(false);
     say(`[whatsapp] host held: ${reason}`, 'warn');
@@ -315,19 +331,17 @@ export function createWhatsAppManager({
         ready = true;
         hostPid = m.pid;
         hostState = 'running';
+        respawnAt = null;
         runtimeInfo = { ...m.runtime };
         connCache = { ...m.conn };
-        const replay = hadReady;
-        hadReady = true;
+        // Every ready, the first one included: the configure first, then the run intent.
         configured = lastPrefs
           ? request(OP.CONFIGURE, { prefs: lastPrefs }).then((r) => { if (!r.ok) say(`[whatsapp] configure failed: ${r.message}`, 'warn'); })
           : Promise.resolve();
+        // A connect that waited for this host carries the intent itself.
+        const connectWaiting = queue.some((q) => q.op === OP.CONNECT && pending.has(q.reqId));
         flushQueue();
-        if (replay && desired) {
-          request(OP.CONNECT, { ...desired }).then((r) => {
-            if (!r.ok) say(`[whatsapp] reconnect after a host restart failed: ${r.code}`, 'warn');
-          });
-        }
+        if (desired && !connectWaiting) resumeRun(source);
         resolveReadyWaiters(true);
         emitState();
         return;
@@ -348,7 +362,8 @@ export function createWhatsAppManager({
         emitState();
         return;
       case EV.LOG:
-        say(`[whatsapp-host] ${redactWa(m.message)}`, m.level === 'error' ? 'error' : m.level === 'warn' ? 'warn' : 'info');
+        // send_file's audit line keeps its path legible (redact.js fileAuditLine checks its exact shape).
+        say(`[whatsapp-host] ${redactLogLine(m.message)}`, m.level === 'error' ? 'error' : m.level === 'warn' ? 'warn' : 'info');
         return;
       case EV.FATAL:
         if (DESIRE_KILLERS.has(m.code)) desired = null;
@@ -368,6 +383,19 @@ export function createWhatsAppManager({
     }
   }
 
+  /** After `configured`, connect the wanted link on the host that just became ready (`me`). */
+  function resumeRun(me) {
+    configured.then(() => {
+      if (token !== me || !ready || stoppedByUser || !desired) return;
+      const intent = desired;
+      request(OP.CONNECT, { ...intent }).then((r) => {
+        if (r.ok) return;
+        if (r.code === ERR.NOT_LINKED && desired === intent) desired = null;
+        say(`[whatsapp] connecting after the host started failed: ${r.code}`, 'warn');
+      });
+    });
+  }
+
   // ── Lifecycle ──
 
   function allowLine() {
@@ -404,6 +432,9 @@ export function createWhatsAppManager({
   function launch() {
     clearTimeout(respawnTimer);
     respawnTimer = null;
+    respawnAt = null;
+    // The respawn wait is over: a host starting now has no "next try" to show.
+    if (connCache.retryInMs !== null) connCache = { ...connCache, retryInMs: null };
     ready = false;
     hostPid = null;
     launchError = null;
@@ -492,21 +523,18 @@ export function createWhatsAppManager({
       emitState();
       return;
     }
+    // A crash is never final: respawn on the ladder, for as long as the host is wanted.
     const reason = `exited (code ${code}, signal ${signal})`;
     lastError = launchError || `the WhatsApp host ${reason}`;
     launchError = null;
     const t = now();
-    exitTimes = exitTimes.filter((x) => t - x < crashWindowMs);
-    exitTimes.push(t);
-    if (exitTimes.length >= crashLimit) {
-      hold(`the WhatsApp host crashed ${exitTimes.length} times in ${Math.round(crashWindowMs / 60_000)} minutes`);
-      return;
-    }
     if (startedAt && t - startedAt >= stableMs) failIdx = 0;
-    const delay = respawnBackoffMs[Math.min(failIdx, respawnBackoffMs.length - 1)] ?? 0;
+    const delay = Math.min(respawnMaxMs, Math.max(0, respawnBackoffMs[Math.min(failIdx, respawnBackoffMs.length - 1)] ?? 0));
     failIdx += 1;
     restarts += 1;
     hostState = 'backoff';
+    respawnAt = t + delay;
+    if (desired) connCache = { ...connCache, retryInMs: delay };
     say(`[whatsapp] host ${reason}; restarting in ${delay} ms`, 'warn');
     emitState();
     respawnTimer = setTimeout(() => {
@@ -517,12 +545,16 @@ export function createWhatsAppManager({
 
   // ── Public API ──
 
-  async function start(prefs) {
+  /**
+   * Start the host (at once, also while a respawn is pending). `resume: false` drops the run intent
+   * first: a host started to log out (Unlink) must not reconnect the link on its ready.
+   */
+  async function start(prefs, { resume = true } = {}) {
     if (prefs !== undefined) lastPrefs = { ...(lastPrefs || {}), ...pickPrefs(prefs) };
+    if (!resume) desired = null;
     stoppedByUser = false;
     if (hostState === 'held') {
       heldReason = null;
-      exitTimes = [];
       failIdx = 0;
       hostState = 'stopped';
     }
@@ -544,8 +576,13 @@ export function createWhatsAppManager({
     const fields = { purpose };
     if (connMode) fields.mode = connMode;
     if (link) fields.link = { method: link.method === 'code' ? 'code' : 'qr', ...(link.phone ? { phone: String(link.phone) } : {}) };
+    // The intent before the request: a host that is not ready yet, or that dies with the request
+    // in flight, connects on its next ready. Only "nothing is linked" ends it here. A host that was
+    // stopped or is held gets no ready of its own: whatever starts it next asks for what it wants.
+    const intent = purpose === 'run' && hostState !== 'stopped' && hostState !== 'held' ? { purpose: 'run', ...(connMode ? { mode: connMode } : {}) } : null;
+    if (intent) desired = intent;
     const res = await request(OP.CONNECT, fields);
-    if (res.ok && purpose === 'run') desired = { purpose: 'run', ...(connMode ? { mode: connMode } : {}) };
+    if (intent && !res.ok && res.code === ERR.NOT_LINKED && desired === intent) desired = null;
     return res;
   }
 
@@ -554,6 +591,7 @@ export function createWhatsAppManager({
     desired = null;
     clearTimeout(respawnTimer);
     respawnTimer = null;
+    respawnAt = null;
     clearTimeout(readyTimer);
     readyTimer = null;
     resolveReadyWaiters(false);
@@ -595,6 +633,7 @@ export function createWhatsAppManager({
     desired = null;
     clearTimeout(respawnTimer);
     respawnTimer = null;
+    respawnAt = null;
     clearTimeout(readyTimer);
     readyTimer = null;
     if (child) { try { child.kill('SIGTERM'); } catch {} }
@@ -623,6 +662,27 @@ export function createWhatsAppManager({
       if (typeof text !== 'string') return Promise.resolve(fail(ERR.BAD_REQUEST, 'text must be a string'));
       return request(OP.SEND, { text, ...(replyTo ? { replyTo } : {}) }, { timeoutMs: sendTimeoutMs });
     },
+    /**
+     * A local file to the owner (send_file): exactly one request, never retried here or anywhere,
+     * and never queued for a host that is not up yet (HOST_UNAVAILABLE: nothing was sent). A TIMEOUT,
+     * or a host that exits with the request in flight, may come after WhatsApp took the file: those
+     * answers carry `uncertain: true`. Only { path, caption?, as? } travel: an address key is
+     * ADDRESS_FORBIDDEN, any other key BAD_REQUEST.
+     */
+    sendFile: async (fields = {}) => {
+      if (!isPlainObject(fields)) return fail(ERR.BAD_REQUEST, 'send_file takes { path, caption?, as? }');
+      const address = ADDRESS_KEYS.find((key) => Object.hasOwn(fields, key));
+      if (address) return fail(ERR.ADDRESS_FORBIDDEN, `send_file never takes an address ('${address}')`);
+      const extra = Object.keys(fields).find((key) => !['path', 'caption', 'as'].includes(key));
+      if (extra) return fail(ERR.BAD_REQUEST, `send_file has an unknown field '${extra.slice(0, 40)}'`);
+      if (!ready) return fail(ERR.HOST_UNAVAILABLE, 'the WhatsApp host is not running: nothing was sent');
+      const out = { path: fields.path };
+      if (fields.caption !== undefined && fields.caption !== null) out.caption = fields.caption;
+      if (fields.as !== undefined && fields.as !== null) out.as = fields.as;
+      const result = await request(OP.SEND_FILE, out, { timeoutMs: sendFileTimeoutMs });
+      if (!result.ok && (result.code === ERR.TIMEOUT || result.code === ERR.HOST_UNAVAILABLE)) result.uncertain = true;
+      return result;
+    },
     react: (id, name) => request(OP.REACT, { id, reaction: name ?? null }, { timeoutMs: sendTimeoutMs }),
     presence: (state) => request(OP.PRESENCE, { state }),
     markRead: (ids) => request(OP.READ, { ids: Array.isArray(ids) ? ids.slice(0, LIMITS.MAX_READ_IDS) : [] }),

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

@@ -9,8 +9,16 @@
 //               session to a second machine (that ends in connectionReplaced).
 //   runtimeDir  the Baileys runtime, installed on demand from the pinned
 //               lockfile in ./connector (never in a SynaBun package.json).
+//   transcriptionDir  voice notes (transcription.js): where the user puts
+//               whisper.cpp (bin/), FFmpeg (bin/) and the model, plus the
+//               private scratch folder of each note. A sibling of runtimeDir:
+//               outside every backup. SynaBun never downloads anything here.
 //   stagingDir  where the installer builds the next runtime before swapping.
 //   logsDir     SynaBun's shared log folder.
+//   dataHome    DATA_HOME itself: a file the Assistant sends from WhatsApp is
+//               never taken from it or from waHome, save SynaBun's generated
+//               media (local-file.js protectedPlaces); SynaBun's backup
+//               archives are refused by name wherever the backup folder is.
 //
 // Pure: no filesystem access, so callers and tests can resolve any platform.
 
@@ -31,7 +39,7 @@ export function isInside(candidate, parent, platform = process.platform) {
 /**
  * @param {{dataHome: string, env?: Record<string,string|undefined>, platform?: string, extraBackupRoots?: string[]}} opts
  *   `extraBackupRoots`: folders a backup copies besides BACKUP_DATA_DIRS (server.js' additional entries).
- * @returns {{waHome:string, defaultWaHome:string, authDir:string, runtimeDir:string, stagingDir:string, logsDir:string,
+ * @returns {{dataHome:string, waHome:string, defaultWaHome:string, authDir:string, runtimeDir:string, transcriptionDir:string, stagingDir:string, logsDir:string,
  *   installLogPath:string, installLockPath:string, npmCacheDir:string, backupRoots:string[], warnings:string[]}}
  */
 export function resolveWhatsAppPaths({ dataHome, env = process.env, platform = process.platform, extraBackupRoots = [] } = {}) {
@@ -66,10 +74,12 @@ export function resolveWhatsAppPaths({ dataHome, env = process.env, platform = p
 
   const runtimeRoot = p.join(home, 'runtime');
   return {
+    dataHome: home,
     waHome,
     defaultWaHome,
     authDir: p.join(waHome, 'auth'),
     runtimeDir: p.join(runtimeRoot, 'whatsapp'),
+    transcriptionDir: p.join(runtimeRoot, 'whatsapp-transcription'),
     stagingDir: p.join(runtimeRoot, 'whatsapp.staging'),
     logsDir: p.join(dataDir, 'logs'),
     installLogPath: p.join(dataDir, 'whatsapp', 'install.log'),

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

@@ -9,13 +9,15 @@
 //                 'inbound'|'ignored'|'throttled'|'fatal'|'log', ...}
 //
 // Addressing: no op that makes the host talk to WhatsApp carries an address.
-// send/react/presence/read always reach the bound owner (sendToOwner in
-// host-core.js is the only sendMessage call site) and validateOp rejects any
+// send/send_file/react/presence/read always reach the bound owner (sendToOwner
+// in host-core.js is the only sendMessage call site) and validateOp rejects any
 // address-shaped key on them. Events never carry a JID or a phone number: the
 // schemas below are closed, so a stray field fails validation instead of
 // leaking. The single exception is the claim_start reply, whose wa.me link
 // holds the dedicated account's own number for the local settings tab.
 
+import path from 'node:path';
+
 export const PROTOCOL_VERSION = 1;
 
 export const OP = Object.freeze({
@@ -28,6 +30,8 @@ export const OP = Object.freeze({
   CLAIM_CANCEL: 'claim_cancel',
   OWNER_RESET: 'owner_reset',
   SEND: 'send',
+  // A local file to the owner as a WhatsApp attachment (local-file.js reads and checks it in the host).
+  SEND_FILE: 'send_file',
   REACT: 'react',
   PRESENCE: 'presence',
   READ: 'read',
@@ -52,7 +56,12 @@ export const EV = Object.freeze({
   LOG: 'log',
 });
 
-/** conn.state values. `held` is set by the manager (crash breaker), never by the host. */
+/**
+ * conn.state values. `held` is set by the manager (a host speaking another
+ * IPC protocol: an update installed while SynaBun ran), never by the host.
+ * The host no longer stops in `replaced` or `forbidden` for a saved session
+ * (440 and 403 are retried: CONN_WARNINGS); only a link attempt still ends there.
+ */
 export const CONN = Object.freeze({
   IDLE: 'idle',
   UNLINKED: 'unlinked',
@@ -91,6 +100,10 @@ export const ERR = Object.freeze({
   PAUSED: 'PAUSED',
   THROTTLED: 'THROTTLED',
   TOO_LONG: 'TOO_LONG',
+  // send_file (local-file.js): a protected location, over the size limit, or not a readable regular file.
+  FILE_FORBIDDEN: 'FILE_FORBIDDEN',
+  FILE_TOO_LARGE: 'FILE_TOO_LARGE',
+  FILE_INVALID: 'FILE_INVALID',
   BAD_TARGET: 'BAD_TARGET',
   BAD_PHONE: 'BAD_PHONE',
   CLAIM_INACTIVE: 'CLAIM_INACTIVE',
@@ -103,15 +116,46 @@ export const ERR = Object.freeze({
   INTERNAL: 'INTERNAL',
 });
 
+/**
+ * Disconnect codes a saved session keeps retrying at the longest delay while
+ * Settings shows a warning: 440 connectionReplaced (another copy uses the
+ * session) and 403 forbidden (the account is refused). The host picks the
+ * delay by this table (baileys-adapter.js classifyDisconnect), the service the
+ * warning, from conn.lastDisconnect.code.
+ */
+export const CONN_WARNINGS = Object.freeze({ 440: 'replaced', 403: 'forbidden' });
+
 export const LIMITS = Object.freeze({
   MAX_TEXT: 3500,
   MAX_INBOUND_TEXT: 8192,
   MAX_IMAGE_BYTES: 5242880,
   MAX_IMAGES: 4,
   MAX_READ_IDS: 20,
+  // Voice notes (transcription.js): declared and actual size, declared and decoded duration.
+  MAX_AUDIO_BYTES: 20 * 1024 * 1024,
+  MAX_AUDIO_SECONDS: 600,
+  // send_file (local-file.js): the path and caption the op takes; a photo, video or audio file above
+  // MAX_FILE_MEDIA_BYTES goes as a document; nothing above MAX_FILE_BYTES is read.
+  MAX_FILE_PATH: 2048,
+  MAX_FILE_CAPTION: 1024,
+  MAX_FILE_MEDIA_BYTES: 16 * 1024 * 1024,
+  MAX_FILE_BYTES: 100 * 1024 * 1024,
 });
 
-/** Keys that name a WhatsApp recipient. None may appear on send/react/presence/read. */
+/** send_file `as`: auto (by extension), or the form asked for (a native form must match the extension). */
+export const FILE_SEND_AS = Object.freeze(['auto', 'document', 'image', 'video', 'audio']);
+
+/**
+ * The text of a transcribed voice note starts with this marker, then the
+ * transcript (one line), then "\n" and the caption when there is one. The
+ * inbound message also carries `voice: true`: spoken words are an ordinary
+ * message, never a command, an ALLOW code or the answer to an approval.
+ */
+export const VOICE_MARKER = '[Voice note transcript]';
+/** transcriptionLanguage: 'auto' (whisper.cpp detects it) or a 2-3 letter lowercase language code. */
+export const TRANSCRIPTION_LANGUAGE_RE = /^(?:auto|[a-z]{2,3})$/;
+
+/** Keys that name a WhatsApp recipient. None may appear on send/send_file/react/presence/read. */
 export const ADDRESS_KEYS = Object.freeze(['jid', 'to', 'remoteJid', 'chat', 'number', 'participant', 'recipient']);
 
 /** Status reactions the bridge may set on an owner message (null clears it). */
@@ -127,7 +171,7 @@ export const MODES = Object.freeze(['self', 'dedicated']);
 export const SELF_TRIGGERS = Object.freeze(['all', 'prefix']);
 export const DEFAULT_PREFIX = 'sb';
 
-const ADDRESSLESS_OPS = new Set([OP.SEND, OP.REACT, OP.PRESENCE, OP.READ]);
+const ADDRESSLESS_OPS = new Set([OP.SEND, OP.SEND_FILE, OP.REACT, OP.PRESENCE, OP.READ]);
 const MSG_ID_RE = /^[A-Za-z0-9._:+/=-]{1,128}$/;
 const PREFIX_RE = /^[^\s]{1,16}$/;
 
@@ -180,10 +224,21 @@ function checkObject(v, spec) {
 
 // ── Prefs (configure) ──
 
+// A tool path the user set in Settings: '' (found by itself) or an absolute path. Whether the file
+// exists and runs is checked where it is used (transcription.js), right before it runs.
+const toolPath = () => (v, p) => (!p || v === undefined ? null
+  : typeof v !== 'string' || v.length > 4096 || /[\u0000-\u001f]/.test(v) || (v !== '' && !path.isAbsolute(v)) ? "must be '' or an absolute path" : null);
+
 const PREFS_SPEC = {
   mode: t.optOneOf(MODES),
   selfTrigger: t.optOneOf(SELF_TRIGGERS),
   prefix: (v, p) => (!p || v === undefined ? null : typeof v !== 'string' || !PREFIX_RE.test(v) ? 'must be 1-16 non-space characters' : null),
+  // Voice notes (transcription.js); a host that was never configured transcribes nothing.
+  transcriptionEnabled: t.optBool(),
+  transcriptionLanguage: (v, p) => (!p || v === undefined ? null : typeof v !== 'string' || !TRANSCRIPTION_LANGUAGE_RE.test(v) ? "must be 'auto' or a 2-3 letter language code" : null),
+  transcriptionEnginePath: toolPath(),
+  transcriptionModelPath: toolPath(),
+  transcriptionFfmpegPath: toolPath(),
 };
 export const PREF_KEYS = Object.freeze(Object.keys(PREFS_SPEC));
 
@@ -212,6 +267,7 @@ const OP_SPECS = {
   [OP.CLAIM_CANCEL]: {},
   [OP.OWNER_RESET]: {},
   [OP.SEND]: { text: t.str(LIMITS.MAX_TEXT * 4), replyTo: (v, p) => (!p || v === undefined || v === null ? null : typeof v !== 'string' || !MSG_ID_RE.test(v) ? 'must be a message id' : null) },
+  [OP.SEND_FILE]: { path: t.str(LIMITS.MAX_FILE_PATH), caption: t.optStr(LIMITS.MAX_FILE_CAPTION), as: t.optOneOf(FILE_SEND_AS) },
   [OP.REACT]: { id: t.msgId(), reaction: (v, p) => (!p ? 'is required' : v === null || Object.hasOwn(REACTIONS, v) ? null : `must be one of ${Object.keys(REACTIONS).join('|')} or null`) },
   [OP.PRESENCE]: { state: t.oneOf(['composing', 'paused']) },
   [OP.READ]: {
@@ -294,6 +350,10 @@ export const INBOUND_SPEC = {
   owner: (v, p) => (!p ? 'is required' : v === true ? null : 'must be true'),
   // Delivered after an offline spell (messages.upsert 'append'); `ts` says when it was sent.
   backlog: t.optBool(),
+  // A voice note transcribed on this computer: `text` is VOICE_MARKER + the transcript (+ "\n" + the caption).
+  voice: t.optBool(),
+  // …of an audio file, not a note recorded in WhatsApp: its words may be anyone's (the turn is capped like a picture's).
+  audioFile: t.optBool(),
 };
 
 const EVENT_SPECS = {

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

@@ -121,6 +121,69 @@ export function redactWa(value) {
   return text;
 }
 
+/**
+ * A local file path for the send_file audit line and its Activity row: credentials, QR payloads,
+ * JIDs, codes and phone numbers are redacted as in redactWa, but not the key-shape heuristics
+ * (HEX_RE, B64_RE), which read most real paths (`/Users/<you>/App2/…`, a run id folder) as key
+ * material and would leave nothing of the path to audit. Paths only: never for message text.
+ */
+export function redactFilePath(value) {
+  let text = typeof value === 'string' ? value : String(value ?? '');
+  if (!text) return '';
+  text = redactCredentials(text);
+  text = text.replace(QR_URL_RE, '[qr]').replace(QR_REF_RE, '[qr]');
+  text = text.replace(JID_RE, (_m, user, server) => tagFor(user, server));
+  text = text.replace(ALLOW_CODE_RE, (_m, word) => `${word} [code]`);
+  text = text.replace(CLAIM_CODE_RE, '[code]').replace(PAIRING_DASH_RE, '[code]');
+  text = text.replace(NUMBER_RE, (run) => (DATE_LIKE_RE.test(run) ? run : '[number]'));
+  return text.slice(0, 2048);
+}
+
+// A run of key-shaped characters inside a path, between separators, dashes, underscores, dots and spaces.
+const PATH_KEY_RUN_RE = /[A-Za-z0-9+=]{24,}/g;
+
+/**
+ * A path the Assistant asked for and SynaBun refused (its Activity row): redactFilePath, and any run of
+ * 24 or more hex or key-shaped characters between the path's separators, dashes, underscores, dots and
+ * spaces masked too, because the text came from the model and need not name a file at all. Ordinary
+ * names stay readable (their words are short); a real file's canonical path keeps redactFilePath alone.
+ */
+export function redactRequestedPath(value) {
+  return redactFilePath(value).replace(PATH_KEY_RUN_RE, (run) => (/^[0-9a-fA-F]+$/.test(run) || looksLikeKey(run) ? '[key]' : run));
+}
+
+const FILE_AUDIT_PREFIX = '[whatsapp] file send ';
+const FILE_AUDIT_TYPES = new Set(['document', 'image', 'video', 'audio']);
+const MASKED_CHAT_RE = /^(?:••••|••\d{2}|••••\d{4}|linked id ••[A-Za-z0-9]{0,2})$/;
+
+/**
+ * The send_file audit line (host-core.js noteFileSend), checked field by field: exactly
+ * { path, size, chat, type } with a masked chat and a known form, the path through
+ * redactFilePath. → the line, or null for anything else (which gets redactWa like every log line).
+ */
+export function fileAuditLine(message) {
+  const text = typeof message === 'string' ? message : '';
+  if (!text.startsWith(FILE_AUDIT_PREFIX)) return null;
+  let entry;
+  try { entry = JSON.parse(text.slice(FILE_AUDIT_PREFIX.length)); } catch { return null; }
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return null;
+  const keys = Object.keys(entry);
+  if (keys.length !== 4 || keys.join(',') !== 'path,size,chat,type') return null;
+  if (typeof entry.path !== 'string' || !Number.isSafeInteger(entry.size) || entry.size < 0 || typeof entry.chat !== 'string' || !MASKED_CHAT_RE.test(entry.chat) || !FILE_AUDIT_TYPES.has(entry.type)) return null;
+  return `${FILE_AUDIT_PREFIX}${JSON.stringify({ path: redactFilePath(entry.path), size: entry.size, chat: entry.chat, type: entry.type })}`;
+}
+
+/**
+ * One log line on its way to SynaBun's log (manager.js, service.js): redactWa, except a send_file
+ * audit line (after the host's "[whatsapp-host] " tag or not), which fileAuditLine checks and keeps.
+ */
+export function redactLogLine(message) {
+  const text = typeof message === 'string' ? message : String(message ?? '');
+  const tag = text.startsWith('[whatsapp-host] ') ? '[whatsapp-host] ' : '';
+  const audit = fileAuditLine(text.slice(tag.length));
+  return audit ? `${tag}${audit}` : redactWa(text);
+}
+
 /** A phone number for display: never more than the last four digits. */
 export function maskNumber(digits) {
   const d = String(digits ?? '').replace(/\D/g, '');