@moxxy/plugin-channel-whatsapp 0.27.0

package/src/channel/turn-runner.ts

@@ -0,0 +1,156 @@
+import type { newTurnId } from '@moxxy/core';
+import { FramePump, PlainTurnRenderer, driveTurn, subscribeTurn } from '@moxxy/channel-kit';
+import type { ClientSession as Session } from '@moxxy/sdk';
+import type { WaMessageKey, WhatsAppSocket } from '../socket.js';
+
+/**
+ * Streaming strategy (justified against the Baileys API):
+ *
+ * WhatsApp supports true message edits (a MESSAGE_EDIT protocol send —
+ * `sendMessage(jid, { text, edit: key })`, stable in Baileys since 6.5), so the
+ * channel streams the way Telegram/Slack do: send ONE message on the first
+ * frame, then edit it in place — the user watches a single message grow instead
+ * of a flood of partials that can't be assembled. Two WhatsApp-specific
+ * adjustments:
+ *
+ *  - `editFrameMs` defaults to 3000 (vs 1000 elsewhere): every edit is a full
+ *    outbound protocol message, and high-frequency automated edits are exactly
+ *    the anomalous traffic that gets numbers flagged on an UNOFFICIAL client.
+ *    Fewer, chunkier edits keep the visible behavior close to a human editing
+ *    a message. (WhatsApp's ~15-minute edit window is irrelevant at turn scale.)
+ *
+ *  - overflow splitting happens ONLY on the final frame: while streaming, the
+ *    frame is truncated to {@link WHATSAPP_MAX_MESSAGE_CHARS}; the final flush
+ *    edits the streamed message to the first chunk and sends the tail chunks as
+ *    follow-up messages (mirrors Telegram's split-tails). If a FINAL edit fails
+ *    (edit rejected / message gone), the sink falls back to sending the chunks
+ *    as new messages so the reply is never silently lost.
+ */
+export const WHATSAPP_MAX_MESSAGE_CHARS = 4000;
+export const DEFAULT_EDIT_FRAME_MS = 3000;
+
+/** Split text into ≤maxLen chunks, preferring newline then space boundaries. */
+export function splitWhatsAppText(
+  text: string,
+  maxLen: number = WHATSAPP_MAX_MESSAGE_CHARS,
+): string[] {
+  if (text.length <= maxLen) return [text];
+  const chunks: string[] = [];
+  let rest = text;
+  while (rest.length > maxLen) {
+    const window = rest.slice(0, maxLen);
+    let cut = window.lastIndexOf('\n');
+    if (cut < maxLen * 0.5) cut = window.lastIndexOf(' ');
+    if (cut < maxLen * 0.5) cut = maxLen;
+    chunks.push(rest.slice(0, cut));
+    rest = rest.slice(cut).replace(/^[\n ]/, '');
+  }
+  if (rest.length > 0) chunks.push(rest);
+  return chunks;
+}
+
+export interface TurnRunnerLogger {
+  warn?(msg: string, meta?: Record<string, unknown>): void;
+}
+
+export interface RunWhatsAppTurnDeps {
+  readonly session: Session;
+  readonly socket: WhatsAppSocket;
+  readonly editFrameMs: number;
+  /** Record an outbound message id (echo/loop protection in the gate). */
+  readonly recordSentId: (key: WaMessageKey | null | undefined) => void;
+  readonly logger?: TurnRunnerLogger;
+}
+
+export interface RunWhatsAppTurnOptions {
+  readonly jid: string;
+  readonly text: string;
+  readonly model?: string | undefined;
+  readonly controller: AbortController;
+  /** Pre-minted turn id; the channel records it as an own-turn id (#8). */
+  readonly turnId: ReturnType<typeof newTurnId>;
+}
+
+/**
+ * Drive a single WhatsApp turn end-to-end: subscribe the frame pump to THIS
+ * turn's events (turnId-filtered — `session.log` fans out to every listener, so
+ * a concurrent turn on the same Session would otherwise stream into this chat,
+ * AGENTS.md invariant #8), run the turn, flush the final frame, unwind in
+ * `finally`.
+ */
+export async function runWhatsAppTurn(
+  deps: RunWhatsAppTurnDeps,
+  opts: RunWhatsAppTurnOptions,
+): Promise<void> {
+  const { session, socket, editFrameMs, recordSentId, logger } = deps;
+  const { jid, text, model, controller, turnId } = opts;
+
+  const renderer = new PlainTurnRenderer();
+
+  const sendChunks = async (chunks: ReadonlyArray<string>): Promise<WaMessageKey | null> => {
+    let firstKey: WaMessageKey | null = null;
+    for (const chunk of chunks) {
+      try {
+        const sent = await socket.sendText(jid, chunk);
+        recordSentId(sent?.key);
+        if (!firstKey && sent?.key) firstKey = sent.key;
+      } catch (err) {
+        logger?.warn?.('whatsapp send failed', { err: String(err) });
+      }
+    }
+    return firstKey;
+  };
+
+  const pump = new FramePump<WaMessageKey>({
+    editFrameMs,
+    frame: (final) => {
+      const snapshot = renderer.snapshot();
+      if (final || snapshot.length <= WHATSAPP_MAX_MESSAGE_CHARS) return snapshot;
+      // Streaming frame: hold to one editable message; overflow waits for the
+      // final flush, whose full text differs from this so a last flush is
+      // guaranteed to deliver the tails.
+      return `${snapshot.slice(0, WHATSAPP_MAX_MESSAGE_CHARS - 1)}…`;
+    },
+    emptyFinalText: '(no output)',
+    sink: {
+      send: async (t) => sendChunks(splitWhatsAppText(t)),
+      edit: async (key, t, final) => {
+        const chunks = splitWhatsAppText(t);
+        try {
+          await socket.editText(jid, key, chunks[0]!);
+        } catch (err) {
+          logger?.warn?.('whatsapp edit failed', { err: String(err), final });
+          if (final) {
+            // Never lose the final reply to a failed edit — resend it whole.
+            await sendChunks(chunks);
+            return;
+          }
+          return;
+        }
+        if (final && chunks.length > 1) await sendChunks(chunks.slice(1));
+      },
+    },
+  });
+
+  const unsubscribe = subscribeTurn(session, turnId, (event) => {
+    if (renderer.accept(event)) pump.scheduleEdit();
+  });
+
+  try {
+    await driveTurn(session, {
+      turnId,
+      prompt: text,
+      ...(model ? { model } : {}),
+      signal: controller.signal,
+    });
+    await pump.flush(true);
+  } catch (err) {
+    logger?.warn?.('whatsapp turn failed', {
+      err: err instanceof Error ? err.message : String(err),
+    });
+    await sendChunks([`Turn failed: ${err instanceof Error ? err.message : String(err)}`]);
+  } finally {
+    unsubscribe();
+    pump.dispose();
+  }
+}

package/src/channel/voice-handler.ts

@@ -0,0 +1,83 @@
+import type { ClientSession as Session } from '@moxxy/sdk';
+import { MAX_AUDIO_BYTES } from '../message-gate.js';
+import type { WaInboundMessage, WhatsAppSocket } from '../socket.js';
+
+export interface VoiceHandlerDeps {
+  readonly session: Session;
+  readonly socket: WhatsAppSocket;
+  /** Reply into the originating chat (records sent ids for echo protection). */
+  readonly reply: (jid: string, text: string) => Promise<void>;
+  readonly logger?: { warn?(msg: string, meta?: Record<string, unknown>): void };
+}
+
+export interface VoiceHandlerInput {
+  readonly jid: string;
+  readonly mimeType: string;
+  /** The raw upsert message — Baileys needs it to decrypt/download the media. */
+  readonly raw: WaInboundMessage;
+}
+
+/**
+ * Handle an inbound voice note / audio message that already passed the gate
+ * (pairing + allow-list + declared-size cap): require an active Transcriber
+ * (guidance reply when none — mirror of the Telegram voice handler), download
+ * via Baileys' media pipeline, re-check the size cap on the REAL bytes, then
+ * transcribe. Returns the transcript for the caller to run as a normal user
+ * turn, or null when the message was fully handled (guidance/error reply sent).
+ */
+export async function transcribeVoiceMessage(
+  deps: VoiceHandlerDeps,
+  input: VoiceHandlerInput,
+): Promise<string | null> {
+  const { session, socket, reply, logger } = deps;
+  const { jid, mimeType, raw } = input;
+
+  const transcriber = session.transcribers.tryGetActive();
+  if (!transcriber) {
+    await reply(
+      jid,
+      'Heard a voice note, but no speech-to-text backend is configured. Install ' +
+        '@moxxy/plugin-stt-whisper and run `moxxy login openai` (or set OPENAI_API_KEY) ' +
+        'to enable voice input.',
+    );
+    return null;
+  }
+
+  let bytes: Uint8Array;
+  try {
+    bytes = await socket.downloadMedia(raw);
+  } catch (err) {
+    logger?.warn?.('whatsapp voice download failed', {
+      err: err instanceof Error ? err.message : String(err),
+    });
+    await reply(jid, 'Could not download that voice note.');
+    return null;
+  }
+  if (bytes.byteLength > MAX_AUDIO_BYTES) {
+    await reply(
+      jid,
+      `That audio is too large to transcribe (limit ${MAX_AUDIO_BYTES / (1024 * 1024)}MB).`,
+    );
+    return null;
+  }
+
+  let transcript: string;
+  try {
+    transcript = (await transcriber.transcribe(bytes, { mimeType })).text.trim();
+  } catch (err) {
+    logger?.warn?.('whatsapp voice transcription failed', {
+      err: err instanceof Error ? err.message : String(err),
+    });
+    await reply(jid, `Transcription failed: ${err instanceof Error ? err.message : String(err)}`);
+    return null;
+  }
+  if (!transcript) {
+    await reply(jid, 'Could not transcribe the voice note (got empty text).');
+    return null;
+  }
+
+  // Echo what was heard so the user can spot misrecognitions before the agent
+  // acts on it (same contract as the Telegram voice handler).
+  await reply(jid, `heard: ${transcript}`);
+  return transcript;
+}

package/src/channel.test.ts

@@ -0,0 +1,344 @@
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { Session, autoAllowResolver, silentLogger } from '@moxxy/core';
+import { FakeProvider, streamingTextReply } from '@moxxy/testing';
+import { definePlugin, defineProvider, defineTranscriber } from '@moxxy/sdk';
+import { defaultModePlugin } from '@moxxy/mode-default';
+import { VaultStore, createStaticKeySource, deriveKey, generateSalt } from '@moxxy/plugin-vault';
+import { WhatsAppChannel } from './channel.js';
+import type {
+  WaConnectionUpdate,
+  WaInboundMessage,
+  WaMessageKey,
+  WaMessagesUpsert,
+  WhatsAppSocket,
+  WhatsAppSocketFactoryOptions,
+} from './socket.js';
+import { createFileAuthStorage } from './auth-state.js';
+import { WHATSAPP_CONSENT_ENV } from './keys.js';
+
+const OWNER = '15550000000@s.whatsapp.net';
+const FRIEND = '15551111111@s.whatsapp.net';
+const STRANGER = '15559999999@s.whatsapp.net';
+
+interface SentRecord {
+  jid: string;
+  text: string;
+}
+
+/** Scriptable in-memory WhatsApp socket — no network, no Baileys. */
+class FakeSocket implements WhatsAppSocket {
+  connCb: ((u: WaConnectionUpdate) => void) | null = null;
+  msgCb: ((u: WaMessagesUpsert) => void) | null = null;
+  readonly sent: SentRecord[] = [];
+  readonly edits: Array<{ jid: string; id: string; text: string }> = [];
+  private jid: string | null = null;
+  private seq = 0;
+  downloadImpl: (m: WaInboundMessage) => Promise<Uint8Array> = async () => new Uint8Array();
+  ended = false;
+
+  userJid(): string | null {
+    return this.jid;
+  }
+  onConnectionUpdate(cb: (u: WaConnectionUpdate) => void): void {
+    this.connCb = cb;
+  }
+  onMessages(cb: (u: WaMessagesUpsert) => void): void {
+    this.msgCb = cb;
+  }
+  async sendText(jid: string, text: string): Promise<{ key: WaMessageKey } | null> {
+    const id = `out-${++this.seq}`;
+    this.sent.push({ jid, text });
+    return { key: { remoteJid: jid, fromMe: true, id } };
+  }
+  async editText(jid: string, key: WaMessageKey, text: string): Promise<void> {
+    this.edits.push({ jid, id: key.id ?? '', text });
+  }
+  async downloadMedia(m: WaInboundMessage): Promise<Uint8Array> {
+    return this.downloadImpl(m);
+  }
+  end(): void {
+    this.ended = true;
+  }
+
+  // ---- test drivers ----
+  open(jid: string): void {
+    this.jid = jid;
+    this.connCb?.({ connection: 'open' });
+  }
+  qr(payload: string): void {
+    this.connCb?.({ qr: payload });
+  }
+  close(err?: unknown): void {
+    this.connCb?.({ connection: 'close', lastDisconnect: err ? { error: err } : undefined });
+  }
+  inbound(message: WaInboundMessage, type = 'notify'): void {
+    this.msgCb?.({ type, messages: [message] });
+  }
+}
+
+function textMsg(remoteJid: string, text: string, fromMe = false, id = `in-${Math.random()}`): WaInboundMessage {
+  return { key: { remoteJid, fromMe, id }, message: { conversation: text } };
+}
+
+let tmp: string;
+let vault: VaultStore;
+let session: Session;
+let provider: FakeProvider;
+
+beforeEach(async () => {
+  tmp = await fs.mkdtemp(path.join(os.tmpdir(), 'mox-wa-chan-'));
+  process.env[WHATSAPP_CONSENT_ENV] = 'yes';
+  vault = new VaultStore({
+    filePath: path.join(tmp, 'vault.json'),
+    keySource: createStaticKeySource(deriveKey('test', generateSalt())),
+  });
+  provider = new FakeProvider({ script: [streamingTextReply(['Hello ', 'world'])] });
+  session = new Session({ cwd: tmp, logger: silentLogger, permissionResolver: autoAllowResolver });
+  session.pluginHost.registerStatic(
+    definePlugin({
+      name: 'shim',
+      providers: [
+        defineProvider({ name: provider.name, models: [...provider.models], createClient: () => provider }),
+      ],
+    }),
+  );
+  session.providers.setActive(provider.name);
+  session.pluginHost.registerStatic(defaultModePlugin);
+});
+
+afterEach(async () => {
+  await session.close('test').catch(() => undefined);
+  // The Baileys auth dir may still be mid-write from a socket that just closed;
+  // a single rm can race it (ENOTEMPTY). Retry briefly, then give up.
+  for (let i = 0; i < 5; i++) {
+    try {
+      await fs.rm(tmp, { recursive: true, force: true });
+      break;
+    } catch {
+      await new Promise((r) => setTimeout(r, 20));
+    }
+  }
+  delete process.env[WHATSAPP_CONSENT_ENV];
+});
+
+function makeChannel(fake: FakeSocket, opts: Partial<{ allowedJids: string[] }> = {}): WhatsAppChannel {
+  return new WhatsAppChannel({
+    vault,
+    editFrameMs: 5,
+    socketFactory: async (_o: WhatsAppSocketFactoryOptions) => fake,
+    // Pre-seeded creds file so start() doesn't demand pair mode.
+    authStorage: seededStorage(),
+    ...(opts.allowedJids ? { allowedJids: opts.allowedJids } : {}),
+  });
+}
+
+/** A storage with a creds record present (simulates an already-linked account). */
+function seededStorage() {
+  const storage = createFileAuthStorage(path.join(tmp, 'auth'));
+  return {
+    ...storage,
+    read: async (k: string) => (k === 'creds' ? '{"me":1}' : storage.read(k)),
+  };
+}
+
+describe('WhatsAppChannel.start', () => {
+  it('refuses to start without consent', async () => {
+    delete process.env[WHATSAPP_CONSENT_ENV];
+    const channel = makeChannel(new FakeSocket());
+    session.setPermissionResolver(channel.permissionResolver);
+    await expect(channel.start({ session, dedicated: true })).rejects.toThrow(/ToS|acknowledg|ban/i);
+  });
+
+  it('refuses to start unlinked outside pair mode', async () => {
+    const fake = new FakeSocket();
+    const channel = new WhatsAppChannel({
+      vault,
+      socketFactory: async () => fake,
+      authStorage: createFileAuthStorage(path.join(tmp, 'empty-auth')),
+    });
+    session.setPermissionResolver(channel.permissionResolver);
+    await expect(channel.start({ session })).rejects.toThrow(/No WhatsApp account is linked/);
+  });
+
+  it('drives a full turn for the owner Note-to-Self chat and streams via edits', async () => {
+    const fake = new FakeSocket();
+    const channel = makeChannel(fake);
+    session.setPermissionResolver(channel.permissionResolver);
+    const handle = await channel.start({ session });
+    fake.open(OWNER);
+
+    fake.inbound(textMsg(OWNER, 'hi', true));
+    await vi.waitFor(() => {
+      const all = [...fake.sent.map((s) => s.text), ...fake.edits.map((e) => e.text)];
+      expect(all.join('')).toContain('Hello world');
+    });
+    expect(channel.connected).toBe(true);
+    await handle.stop('test done');
+  });
+
+  it('runs a turn for an allow-listed friend', async () => {
+    const fake = new FakeSocket();
+    const channel = makeChannel(fake, { allowedJids: [FRIEND] });
+    session.setPermissionResolver(channel.permissionResolver);
+    const handle = await channel.start({ session });
+    fake.open(OWNER);
+
+    fake.inbound(textMsg(FRIEND, 'hey bot'));
+    await vi.waitFor(() => expect(provider.received.length).toBeGreaterThan(0));
+    await handle.stop('test done');
+  });
+
+  it('drops an un-allow-listed stranger with no reply', async () => {
+    const fake = new FakeSocket();
+    const channel = makeChannel(fake);
+    session.setPermissionResolver(channel.permissionResolver);
+    const handle = await channel.start({ session });
+    fake.open(OWNER);
+
+    fake.inbound(textMsg(STRANGER, 'let me in'));
+    // Give the async dispatch a tick; nothing should be sent, no turn should run.
+    await new Promise((r) => setTimeout(r, 20));
+    expect(provider.received.length).toBe(0);
+    expect(fake.sent).toHaveLength(0);
+    await handle.stop('test done');
+  });
+
+  it('does NOT reprocess its own outbound echo (loop protection)', async () => {
+    const fake = new FakeSocket();
+    const channel = makeChannel(fake);
+    session.setPermissionResolver(channel.permissionResolver);
+    const handle = await channel.start({ session });
+    fake.open(OWNER);
+
+    fake.inbound(textMsg(OWNER, 'hi', true));
+    await vi.waitFor(() => expect(fake.sent.length + fake.edits.length).toBeGreaterThan(0));
+    const turnsBefore = provider.received.length;
+
+    // Feed the channel's own last send back as an inbound (fromMe echo).
+    const lastOut = fake.sent[fake.sent.length - 1]!;
+    // Reconstruct the outbound key id: the fake numbers them out-N; grab it via
+    // a fresh send to learn the id shape isn't needed — echo by a known own id.
+    fake.inbound({ key: { remoteJid: OWNER, fromMe: true, id: 'out-1' }, message: { conversation: lastOut.text } });
+    await new Promise((r) => setTimeout(r, 20));
+    expect(provider.received.length).toBe(turnsBefore);
+    await handle.stop('test done');
+  });
+
+  it('transcribes a voice note through the active transcriber, then runs a turn', async () => {
+    // Register a stub transcriber on the session, then activate it.
+    session.pluginHost.registerStatic(
+      definePlugin({
+        name: 'stub-stt',
+        transcribers: [
+          defineTranscriber({
+            name: 'stub',
+            createClient: () => ({
+              name: 'stub',
+              transcribe: async () => ({ text: 'transcribed prompt' }),
+            }),
+          }),
+        ],
+      }),
+    );
+    session.transcribers.setActive('stub');
+
+    const fake = new FakeSocket();
+    fake.downloadImpl = async () => new Uint8Array([1, 2, 3]);
+    const channel = makeChannel(fake);
+    session.setPermissionResolver(channel.permissionResolver);
+    const handle = await channel.start({ session });
+    fake.open(OWNER);
+
+    fake.inbound({
+      key: { remoteJid: OWNER, fromMe: true, id: 'v1' },
+      message: { audioMessage: { mimetype: 'audio/ogg', fileLength: 3, ptt: true } },
+    });
+    await vi.waitFor(() => {
+      expect(fake.sent.some((s) => s.text.includes('heard: transcribed prompt'))).toBe(true);
+    });
+    await vi.waitFor(() => expect(provider.received.length).toBeGreaterThan(0));
+    await handle.stop('test done');
+  });
+
+  it('guides the user when a voice note arrives with no transcriber', async () => {
+    const fake = new FakeSocket();
+    fake.downloadImpl = async () => new Uint8Array([1]);
+    const channel = makeChannel(fake);
+    session.setPermissionResolver(channel.permissionResolver);
+    const handle = await channel.start({ session });
+    fake.open(OWNER);
+
+    fake.inbound({
+      key: { remoteJid: OWNER, fromMe: true, id: 'v2' },
+      message: { audioMessage: { mimetype: 'audio/ogg', fileLength: 1 } },
+    });
+    await vi.waitFor(() => {
+      expect(fake.sent.some((s) => /speech-to-text/i.test(s.text))).toBe(true);
+    });
+    expect(provider.received.length).toBe(0);
+    await handle.stop('test done');
+  });
+
+  it('publishes rotating QR payloads as requestUrl in pair mode', async () => {
+    const fake = new FakeSocket();
+    const channel = new WhatsAppChannel({
+      vault,
+      socketFactory: async () => fake,
+      authStorage: createFileAuthStorage(path.join(tmp, 'pair-auth')),
+    });
+    session.setPermissionResolver(channel.permissionResolver);
+    const handle = await channel.start({ session, pair: true });
+    expect(channel.connected).toBe(false);
+
+    let changes = 0;
+    handle.onConnectChange?.(() => changes++);
+    fake.qr('qr-payload-1');
+    expect(channel.requestUrl).toBe('qr-payload-1');
+    expect(changes).toBe(1);
+
+    // Linking clears the QR and flips connected.
+    fake.open(OWNER);
+    expect(channel.requestUrl).toBeNull();
+    expect(channel.connected).toBe(true);
+    await handle.stop('test done');
+  });
+
+  it('stop() aborts pending permission prompts (no hang)', async () => {
+    const fake = new FakeSocket();
+    const channel = makeChannel(fake);
+    session.setPermissionResolver(channel.permissionResolver);
+    const handle = await channel.start({ session });
+    fake.open(OWNER);
+    // Set a chat as "last served" so the prompt has a target.
+    fake.inbound(textMsg(OWNER, 'hi', true));
+    await vi.waitFor(() => expect(fake.sent.length + fake.edits.length).toBeGreaterThan(0));
+
+    const pending = channel.permissionResolver.check(
+      { callId: 'c1', name: 'write_file', input: {} } as never,
+      {} as never,
+    );
+    await vi.waitFor(() =>
+      expect(fake.sent.some((s) => /Permission needed/.test(s.text))).toBe(true),
+    );
+    await handle.stop('shutdown');
+    expect((await pending).mode).toBe('deny');
+    expect(fake.ended).toBe(true);
+  });
+
+  it('re-pair guidance: a logout in non-pair mode fails the running promise', async () => {
+    const fake = new FakeSocket();
+    const channel = makeChannel(fake);
+    session.setPermissionResolver(channel.permissionResolver);
+    const handle = await channel.start({ session });
+    fake.open(OWNER);
+    const failed = handle.running.then(
+      () => 'resolved',
+      (err: Error) => err.message,
+    );
+    fake.close({ output: { statusCode: 401 } });
+    expect(await failed).toMatch(/logged this device out|re-link/i);
+  });
+});