@moxxy/plugin-channel-whatsapp 0.27.0

package/src/message-gate.ts

@@ -0,0 +1,184 @@
+import { z } from 'zod';
+import { normalizeJid } from './keys.js';
+import type { WaInboundMessage } from './socket.js';
+
+/**
+ * The single inbound gate every session-reaching path goes through (AGENTS.md:
+ * gate EVERY session-reaching path behind pairing; A8: zod-validate inbound
+ * before it touches the session). Pure — the channel feeds it the message plus
+ * its identity/allow-list state and branches on the verdict.
+ *
+ * Order of checks (each is load-bearing):
+ *  1. only `notify` upserts — history syncs / appends are not fresh input.
+ *  2. shape-validate + size-cap the consumed fields (zod).
+ *  3. drop own echoes: Baileys receives this client's OWN outbound sends back
+ *     via `messages.upsert`; without the sent-id check the bot replies to
+ *     itself in a loop.
+ *  4. drop `fromMe` messages outside the owner's self-chat ("Note to Self"):
+ *     those are the owner talking to OTHER people from their phone — the bot
+ *     must never treat someone's private conversation as a prompt.
+ *  5. allow-list by normalized JID: the owner's self-chat is allowed by
+ *     default (seeded by the channel); everything else must be explicitly
+ *     allow-listed. Unauthorized senders are dropped SILENTLY — replying would
+ *     both leak the bot's existence and look like spam (ban risk).
+ */
+
+/** Cap on inbound prompt text (WhatsApp itself allows ~65k). */
+export const MAX_TEXT_CHARS = 16_000;
+/** Cap on a voice note / audio file we will download + buffer for transcription. */
+export const MAX_AUDIO_BYTES = 20 * 1024 * 1024;
+
+const keySchema = z.object({
+  remoteJid: z.string().min(1).max(256),
+  fromMe: z.boolean().nullish(),
+  id: z.string().min(1).max(256).nullish(),
+});
+
+const audioMessageSchema = z.object({
+  mimetype: z.string().max(256).nullish(),
+  fileLength: z.union([z.number(), z.string(), z.object({}).passthrough()]).nullish(),
+  seconds: z.number().nullish(),
+  ptt: z.boolean().nullish(),
+});
+
+export type GateVerdict =
+  | { readonly ok: false; readonly reason: string }
+  | { readonly ok: true; readonly kind: 'text'; readonly jid: string; readonly text: string }
+  | {
+      readonly ok: true;
+      readonly kind: 'audio';
+      readonly jid: string;
+      readonly mimeType: string;
+      readonly declaredBytes: number | null;
+    };
+
+export interface GateState {
+  /** The linked account's own normalized JID (null until the socket opens). */
+  readonly ownJid: string | null;
+  /** Normalized JIDs allowed to drive the session (includes ownJid). */
+  readonly allowedJids: ReadonlySet<string>;
+  /** Message ids of THIS client's own recent sends (echo/loop protection). */
+  readonly isOwnSend: (messageId: string) => boolean;
+}
+
+export function gateInboundMessage(
+  state: GateState,
+  upsertType: string,
+  raw: WaInboundMessage,
+): GateVerdict {
+  if (upsertType !== 'notify') return drop('not a live notify upsert');
+
+  const key = keySchema.safeParse(raw?.key ?? {});
+  if (!key.success) return drop('invalid message key shape');
+  const { remoteJid, fromMe, id } = key.data;
+  if (remoteJid === 'status@broadcast') return drop('status broadcast');
+
+  const jid = normalizeJid(remoteJid);
+  if (!jid) return drop('unparseable chat JID');
+
+  if (id && state.isOwnSend(id)) return drop('own outbound echo');
+
+  if (fromMe) {
+    // Same-account messages: only the owner's self-chat is a prompt surface.
+    if (state.ownJid == null || jid !== state.ownJid) {
+      return drop('own message in a foreign chat');
+    }
+  } else if (!state.allowedJids.has(jid)) {
+    return drop('sender not allow-listed');
+  }
+
+  const content = unwrapMessageContent(raw?.message ?? null);
+  if (!content) return drop('no message content');
+
+  const text = extractText(content);
+  if (text != null) {
+    const trimmed = text.trim();
+    if (trimmed.length === 0) return drop('empty text');
+    if (trimmed.length > MAX_TEXT_CHARS) return drop('text over size cap');
+    return { ok: true, kind: 'text', jid, text: trimmed };
+  }
+
+  const audioRaw = content['audioMessage'];
+  if (audioRaw != null && typeof audioRaw === 'object') {
+    const audio = audioMessageSchema.safeParse(audioRaw);
+    if (!audio.success) return drop('invalid audio message shape');
+    const declaredBytes = toFiniteNumber(audio.data.fileLength);
+    if (declaredBytes != null && declaredBytes > MAX_AUDIO_BYTES) {
+      return drop('audio over size cap');
+    }
+    return {
+      ok: true,
+      kind: 'audio',
+      jid,
+      mimeType: normalizeMime(audio.data.mimetype),
+      declaredBytes,
+    };
+  }
+
+  return drop('unsupported message type');
+}
+
+function drop(reason: string): GateVerdict {
+  return { ok: false, reason };
+}
+
+/**
+ * Unwrap the containers WhatsApp nests real content in (disappearing-message
+ * chats wrap everything in `ephemeralMessage`, view-once in `viewOnceMessage*`).
+ * Bounded depth — malformed nesting must not recurse forever.
+ */
+function unwrapMessageContent(
+  message: Record<string, unknown> | null,
+): Record<string, unknown> | null {
+  let current = message;
+  for (let depth = 0; current != null && depth < 4; depth++) {
+    const wrapper =
+      pickInner(current, 'ephemeralMessage') ??
+      pickInner(current, 'viewOnceMessage') ??
+      pickInner(current, 'viewOnceMessageV2') ??
+      pickInner(current, 'documentWithCaptionMessage');
+    if (!wrapper) return current;
+    current = wrapper;
+  }
+  return current;
+}
+
+function pickInner(
+  container: Record<string, unknown>,
+  field: string,
+): Record<string, unknown> | null {
+  const wrapper = container[field];
+  if (wrapper == null || typeof wrapper !== 'object') return null;
+  const inner = (wrapper as { message?: unknown }).message;
+  return inner != null && typeof inner === 'object' ? (inner as Record<string, unknown>) : null;
+}
+
+function extractText(content: Record<string, unknown>): string | null {
+  const conversation = content['conversation'];
+  if (typeof conversation === 'string') return conversation;
+  const extended = content['extendedTextMessage'];
+  if (extended != null && typeof extended === 'object') {
+    const text = (extended as { text?: unknown }).text;
+    if (typeof text === 'string') return text;
+  }
+  return null;
+}
+
+/** `fileLength` arrives as number, decimal string, or a Long-like object. */
+function toFiniteNumber(value: unknown): number | null {
+  if (typeof value === 'number' && Number.isFinite(value)) return value;
+  if (typeof value === 'string') {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : null;
+  }
+  if (value != null && typeof value === 'object') {
+    const n = Number((value as { toString(): string }).toString());
+    return Number.isFinite(n) ? n : null;
+  }
+  return null;
+}
+
+function normalizeMime(mime: string | null | undefined): string {
+  const trimmed = mime?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : 'audio/ogg; codecs=opus';
+}

package/src/pair-flow.ts

@@ -0,0 +1,133 @@
+import { log, outro, spinner } from '@clack/prompts';
+import QRCode from 'qrcode';
+import { exitAfterPairRequested, type ChannelSubcommandContext } from '@moxxy/sdk';
+import type { VaultStore } from '@moxxy/plugin-vault';
+import { WhatsAppChannel } from './channel.js';
+import { CONSENT_REQUIRED_MESSAGE } from './consent.js';
+import { ensureConsentInteractive } from './consent-prompt.js';
+
+// Tiny zero-dep ANSI dim helper, so this flow stays inside the plugin.
+const ANSI = process.stdout.isTTY && !process.env.NO_COLOR;
+const dim = (s: string): string => (ANSI ? `\x1b[2m${s}\x1b[22m` : s);
+
+/**
+ * Drive the QR device-link pairing flow end-to-end in a terminal — the SAME
+ * mechanism the desktop Channels panel uses (it renders `channel.requestUrl`
+ * from the status file), just rendered inline here.
+ *
+ * Unlike Telegram's one-shot deep link, the Baileys QR payload ROTATES every
+ * ~20-60s while unlinked, so the flow re-renders on every connect-change until
+ * the scan lands.
+ */
+export async function runWhatsAppPairFlow(ctx: ChannelSubcommandContext): Promise<number> {
+  const vault = ctx.deps.vault as VaultStore;
+
+  // Consent gate FIRST — pairing is the moment the account actually links.
+  if (!(await ensureConsentInteractive(vault))) {
+    process.stderr.write(`${CONSENT_REQUIRED_MESSAGE}\n`);
+    return 1;
+  }
+
+  const session = ctx.session;
+  const channel = new WhatsAppChannel({
+    vault,
+    logger: ctx.deps.logger as never,
+  });
+  session.setPermissionResolver(channel.permissionResolver);
+
+  // Subscribe BEFORE start so a fast scan can't race us.
+  let pairedResolve: ((ownerJid: string) => void) | null = null;
+  const paired = new Promise<string>((resolve) => {
+    pairedResolve = resolve;
+  });
+  const unsubscribePaired = channel.onPaired((ownerJid) => {
+    pairedResolve?.(ownerJid);
+    pairedResolve = null;
+  });
+
+  outro(dim('opening WhatsApp pairing window...'));
+  const handle = await channel.start({ session, pair: true });
+
+  const stopChannel = async (): Promise<void> => {
+    unsubscribePaired();
+    try {
+      await handle.stop('pair flow');
+    } catch {
+      /* ignore */
+    }
+  };
+
+  if (channel.connected) {
+    log.info(
+      'A WhatsApp account is already linked. Run `moxxy channels whatsapp unpair` first to link a different one.',
+    );
+    await stopChannel();
+    return 0;
+  }
+
+  // Render every FRESH QR payload (they rotate while unlinked).
+  let lastQr: string | null = null;
+  const renderQr = async (): Promise<void> => {
+    const qr = channel.requestUrl;
+    if (!qr || qr === lastQr) return;
+    lastQr = qr;
+    await printPairQr(qr);
+    log.info(
+      'On your phone: WhatsApp -> Settings -> Linked devices -> Link a device, then scan the QR.',
+    );
+  };
+  const unsubscribeConnect = handle.onConnectChange?.(() => void renderQr()) ?? (() => undefined);
+  await renderQr();
+
+  let stopping = false;
+  const shutdown = async (): Promise<void> => {
+    if (stopping) return;
+    stopping = true;
+    unsubscribeConnect();
+    await stopChannel();
+    await session.close('SIGINT').catch(() => undefined);
+    process.exit(0);
+  };
+  const onSignal = (): void => void shutdown();
+  process.once('SIGINT', onSignal);
+  process.once('SIGTERM', onSignal);
+
+  const spin = spinner();
+  spin.start('Waiting for the scan (the QR refreshes periodically)...');
+  const ownerJid = await paired;
+  spin.stop(`Linked as ${ownerJid}. Your Note-to-Self chat now talks to moxxy.`);
+
+  if (exitAfterPairRequested(ctx)) {
+    // Orchestrated pairing (`moxxy onboard`): hand control back — the caller
+    // starts the channel under its own service afterwards. Our SIGINT
+    // handlers would `process.exit` the orchestrator, so drop them first.
+    unsubscribeConnect();
+    process.removeListener('SIGINT', onSignal);
+    process.removeListener('SIGTERM', onSignal);
+    await stopChannel();
+    return 0;
+  }
+
+  log.info('Channel is running. Press Ctrl+C to stop.');
+  try {
+    await handle.running;
+    return 0;
+  } finally {
+    unsubscribeConnect();
+    process.removeListener('SIGINT', onSignal);
+    process.removeListener('SIGTERM', onSignal);
+  }
+}
+
+/** Render the rotating pairing payload as a scannable terminal QR. */
+async function printPairQr(payload: string): Promise<void> {
+  let qr = '';
+  try {
+    qr = await QRCode.toString(payload, { type: 'terminal', small: true });
+  } catch {
+    qr = '';
+  }
+  // CLI surface — intentional stdout. (The payload itself is an opaque pairing
+  // blob, not a URL, so there is no "open the link" fallback to print.)
+  console.log(['', qr].join('\n'));
+}

package/src/permission.test.ts

@@ -0,0 +1,94 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { PendingToolCall, PermissionContext } from '@moxxy/sdk';
+import {
+  createWhatsAppPermissionController,
+  formatPermissionPrompt,
+  parsePermissionReply,
+} from './permission.js';
+
+const call: PendingToolCall = {
+  callId: 'c1',
+  name: 'write_file',
+  input: { path: '/tmp/x', content: 'hi' },
+} as PendingToolCall;
+const ctx = {} as PermissionContext;
+
+describe('parsePermissionReply', () => {
+  it('maps allow/session/deny synonyms', () => {
+    expect(parsePermissionReply('1')?.mode).toBe('allow');
+    expect(parsePermissionReply('yes')?.mode).toBe('allow');
+    expect(parsePermissionReply('2')?.mode).toBe('allow_session');
+    expect(parsePermissionReply('always')?.mode).toBe('allow_session');
+    expect(parsePermissionReply('3')?.mode).toBe('deny');
+    expect(parsePermissionReply('no')?.mode).toBe('deny');
+  });
+
+  it('returns null for unrecognized replies', () => {
+    expect(parsePermissionReply('maybe later')).toBeNull();
+    expect(parsePermissionReply('')).toBeNull();
+  });
+});
+
+describe('formatPermissionPrompt', () => {
+  it('names the tool and lists the numbered options', () => {
+    const text = formatPermissionPrompt(call);
+    expect(text).toContain('write_file');
+    expect(text).toContain('1 = allow once');
+    expect(text).toContain('3 = deny');
+  });
+});
+
+describe('WhatsAppPermissionController', () => {
+  it('denies immediately when no sender is wired', async () => {
+    const ctrl = createWhatsAppPermissionController();
+    const decision = await ctrl.resolver.check(call, ctx);
+    expect(decision.mode).toBe('deny');
+  });
+
+  it('prompts, then resolves on the operator reply', async () => {
+    const ctrl = createWhatsAppPermissionController();
+    const sent: string[] = [];
+    ctrl.setSender(async (t) => void sent.push(t));
+
+    const pending = ctrl.resolver.check(call, ctx);
+    await vi.waitFor(() => expect(ctrl.hasPending()).toBe(true));
+    expect(sent[0]).toContain('write_file');
+
+    expect(ctrl.offerReply('1')).toBe(true);
+    expect((await pending).mode).toBe('allow');
+    expect(ctrl.hasPending()).toBe(false);
+  });
+
+  it('allow_session skips subsequent prompts for the same tool', async () => {
+    const ctrl = createWhatsAppPermissionController();
+    ctrl.setSender(async () => {});
+    const first = ctrl.resolver.check(call, ctx);
+    await vi.waitFor(() => expect(ctrl.hasPending()).toBe(true));
+    ctrl.offerReply('2');
+    expect((await first).mode).toBe('allow_session');
+
+    // Second call for the same tool name resolves WITHOUT a new prompt.
+    const second = await ctrl.resolver.check(call, ctx);
+    expect(second.mode).toBe('allow_session');
+    expect(ctrl.hasPending()).toBe(false);
+  });
+
+  it('ignores an unrecognized reply (keeps the prompt pending)', async () => {
+    const ctrl = createWhatsAppPermissionController();
+    ctrl.setSender(async () => {});
+    void ctrl.resolver.check(call, ctx);
+    await vi.waitFor(() => expect(ctrl.hasPending()).toBe(true));
+    expect(ctrl.offerReply('huh?')).toBe(false);
+    expect(ctrl.hasPending()).toBe(true);
+  });
+
+  it('abortAll denies in-flight prompts so callers never hang', async () => {
+    const ctrl = createWhatsAppPermissionController();
+    ctrl.setSender(async () => {});
+    const pending = ctrl.resolver.check(call, ctx);
+    await vi.waitFor(() => expect(ctrl.hasPending()).toBe(true));
+    ctrl.abortAll('channel closed');
+    expect((await pending).mode).toBe('deny');
+    expect(ctrl.hasPending()).toBe(false);
+  });
+});

package/src/permission.ts

@@ -0,0 +1,114 @@
+import {
+  createDeferredPermissionResolver,
+  type DeferredPermissionResolver,
+  type PendingToolCall,
+  type PermissionDecision,
+} from '@moxxy/sdk';
+
+/**
+ * Human-in-the-loop permissions over plain WhatsApp messages. Baileys has no
+ * reliable interactive buttons on multi-device, so the prompt is text: the
+ * channel sends a numbered question into the owner's chat and interprets the
+ * owner's NEXT short reply (`1`/`yes` allow once, `2`/`always` allow for the
+ * session, `3`/`no` deny) — the same capture-next-message mechanism Telegram
+ * uses for approval follow-up text.
+ *
+ * Built ON `createDeferredPermissionResolver` (never re-implement the pending
+ * tracking — the audit caught a TUI hang from exactly that): the sdk scaffold
+ * owns session-allows + abort-on-stop; this wrapper only owns the reply
+ * queue + parsing.
+ */
+export interface WhatsAppPermissionController {
+  readonly resolver: DeferredPermissionResolver;
+  /** Wire the outbound sender once the socket is up (null on teardown). */
+  setSender(send: ((text: string) => Promise<void>) | null): void;
+  /** True while a prompt is awaiting the owner's reply. */
+  hasPending(): boolean;
+  /** Offer an owner message as a reply; true when it resolved a prompt. */
+  offerReply(text: string): boolean;
+  /** Deny every in-flight prompt (channel stop / session reset). */
+  abortAll(reason?: string): void;
+}
+
+interface PendingPrompt {
+  readonly resolve: (decision: PermissionDecision) => void;
+}
+
+export function parsePermissionReply(text: string): PermissionDecision | null {
+  const v = text.trim().toLowerCase();
+  if (v === '1' || v === 'yes' || v === 'y' || v === 'allow') {
+    return { mode: 'allow', reason: 'owner approved via WhatsApp' };
+  }
+  if (v === '2' || v === 'always') {
+    return { mode: 'allow_session', reason: 'owner approved for session via WhatsApp' };
+  }
+  if (v === '3' || v === 'no' || v === 'n' || v === 'deny') {
+    return { mode: 'deny', reason: 'owner denied via WhatsApp' };
+  }
+  return null;
+}
+
+export function formatPermissionPrompt(call: PendingToolCall): string {
+  let input = '';
+  try {
+    input = JSON.stringify(call.input ?? {});
+  } catch {
+    input = '(unserializable input)';
+  }
+  if (input.length > 400) input = `${input.slice(0, 400)}…`;
+  return (
+    `Permission needed: tool *${call.name}*\n` +
+    `${input}\n\n` +
+    'Reply: 1 = allow once, 2 = allow for session, 3 = deny'
+  );
+}
+
+export function createWhatsAppPermissionController(): WhatsAppPermissionController {
+  // FIFO of prompts awaiting a reply. Tool calls within a turn are sequential,
+  // so this is ~1 deep; the queue is defensive against overlap.
+  const pending: PendingPrompt[] = [];
+  let sender: ((text: string) => Promise<void>) | null = null;
+
+  const resolver = createDeferredPermissionResolver({
+    name: 'whatsapp',
+    prompt: (call) =>
+      new Promise<PermissionDecision>((resolve, reject) => {
+        if (!sender) {
+          resolve({ mode: 'deny', reason: 'whatsapp channel not connected' });
+          return;
+        }
+        pending.push({ resolve });
+        sender(formatPermissionPrompt(call)).catch((err: unknown) => {
+          const idx = pending.findIndex((p) => p.resolve === resolve);
+          if (idx >= 0) pending.splice(idx, 1);
+          reject(err instanceof Error ? err : new Error(String(err)));
+        });
+      }),
+  });
+
+  return {
+    resolver,
+    setSender(send) {
+      sender = send;
+    },
+    hasPending() {
+      return pending.length > 0;
+    },
+    offerReply(text) {
+      if (pending.length === 0) return false;
+      const decision = parsePermissionReply(text);
+      if (!decision) return false;
+      const prompt = pending.shift()!;
+      prompt.resolve(decision);
+      return true;
+    },
+    abortAll(reason = 'channel closed') {
+      // Resolve OUR pending prompt promises (deny) so the sdk scaffold's outer
+      // promises settle, then clear the scaffold's own in-flight set too.
+      for (const prompt of pending.splice(0)) {
+        prompt.resolve({ mode: 'deny', reason });
+      }
+      resolver.abortAll(reason);
+    },
+  };
+}

package/src/setup-wizard.ts

@@ -0,0 +1,162 @@
+import { cancel, intro, isCancel, log, note, outro, select, text } from '@clack/prompts';
+import type { ChannelSubcommandContext } from '@moxxy/sdk';
+import { moxxyPath } from '@moxxy/sdk/server';
+import type { VaultStore } from '@moxxy/plugin-vault';
+import { createFileAuthStorage, hasStoredCreds } from './auth-state.js';
+import { ensureConsentInteractive } from './consent-prompt.js';
+import {
+  WHATSAPP_ALLOWED_JIDS_KEY,
+  WHATSAPP_AUTH_DIR,
+  WHATSAPP_OWNER_JID_KEY,
+  parseAllowedJids,
+} from './keys.js';
+import { runWhatsAppPairFlow } from './pair-flow.js';
+
+// Tiny zero-dep ANSI helpers so the wizard stays inside the plugin.
+const ANSI = process.stdout.isTTY && !process.env.NO_COLOR;
+const bold = (s: string): string => (ANSI ? `\x1b[1m${s}\x1b[22m` : s);
+const dim = (s: string): string => (ANSI ? `\x1b[2m${s}\x1b[22m` : s);
+
+interface State {
+  readonly linked: boolean;
+  readonly ownerJid: string | null;
+  readonly allowedJids: ReadonlyArray<string>;
+}
+
+type Action = 'pair' | 'unpair' | 'allow-list' | 'start' | 'quit';
+
+/**
+ * Interactive WhatsApp setup menu (the channel's `interactiveCommand`).
+ *
+ * The FIRST step — before any menu — is the consent gate: this channel rides an
+ * UNOFFICIAL WhatsApp client; the wizard states the ToS/ban risk plainly and
+ * requires a typed "yes" before anything else. No acknowledgment, no menu.
+ */
+export async function runWhatsAppWizard(ctx: ChannelSubcommandContext): Promise<number> {
+  const vault = ctx.deps.vault as VaultStore;
+  intro(bold('moxxy whatsapp setup'));
+
+  if (!(await ensureConsentInteractive(vault))) {
+    cancel('cancelled.');
+    return 1;
+  }
+
+  while (true) {
+    const state = await readState(vault);
+    printStatus(state);
+    const action = await pickAction(state);
+    if (action === null) {
+      cancel('cancelled.');
+      return 0;
+    }
+    if (action === 'quit') {
+      outro(dim('done.'));
+      return 0;
+    }
+    if (action === 'pair') {
+      return await runWhatsAppPairFlow(ctx);
+    }
+    if (action === 'unpair') {
+      await unpairLocal(vault);
+      log.success(
+        'Local credentials cleared. Also remove the device on your phone: WhatsApp -> Settings -> Linked devices.',
+      );
+      continue;
+    }
+    if (action === 'allow-list') {
+      await editAllowList(vault, state.allowedJids);
+      continue;
+    }
+    if (action === 'start') {
+      log.info('Starting the channel. Press Ctrl+C to stop.');
+      outro(dim('handing off to the channel...'));
+      return ctx.startChannel();
+    }
+  }
+}
+
+/** Clear the rotating auth-state dir + the persisted owner identity. */
+export async function unpairLocal(vault: VaultStore): Promise<boolean> {
+  const storage = createFileAuthStorage(moxxyPath(WHATSAPP_AUTH_DIR));
+  const had = await hasStoredCreds(storage);
+  await storage.clear();
+  await vault.delete(WHATSAPP_OWNER_JID_KEY).catch(() => undefined);
+  return had;
+}
+
+async function readState(vault: VaultStore): Promise<State> {
+  const storage = createFileAuthStorage(moxxyPath(WHATSAPP_AUTH_DIR));
+  return {
+    linked: await hasStoredCreds(storage),
+    ownerJid: await vault.get(WHATSAPP_OWNER_JID_KEY),
+    allowedJids: parseAllowedJids(await vault.get(WHATSAPP_ALLOWED_JIDS_KEY)),
+  };
+}
+
+function printStatus(state: State): void {
+  const lines: string[] = [];
+  lines.push(`Linked       ${state.linked ? bold(state.ownerJid ?? 'yes') : dim('no')}`);
+  lines.push(
+    `Allow-list   ${
+      state.allowedJids.length > 0
+        ? bold(state.allowedJids.join(', '))
+        : dim('only your own Note-to-Self chat')
+    }`,
+  );
+  note(lines.join('\n'), 'status');
+}
+
+async function pickAction(state: State): Promise<Action | null> {
+  const options: Array<{ value: Action; label: string; hint?: string }> = [];
+  if (state.linked) {
+    options.push({
+      value: 'start',
+      label: 'Start the channel',
+      hint: 'runs forever - Ctrl+C to stop',
+    });
+    options.push({
+      value: 'unpair',
+      label: 'Unpair (forget local credentials)',
+      hint: 'also remove the device under Linked devices on the phone',
+    });
+  } else {
+    options.push({
+      value: 'pair',
+      label: 'Link a WhatsApp account (scan QR)',
+      hint: 'WhatsApp -> Settings -> Linked devices -> Link a device',
+    });
+  }
+  options.push({
+    value: 'allow-list',
+    label: 'Edit the JID allow-list',
+    hint: 'who besides your own Note-to-Self chat may talk to the agent',
+  });
+  options.push({ value: 'quit', label: 'Quit' });
+
+  const choice = await select<Action>({ message: 'What do you want to do?', options });
+  if (isCancel(choice)) return null;
+  return choice as Action;
+}
+
+async function editAllowList(
+  vault: VaultStore,
+  current: ReadonlyArray<string>,
+): Promise<void> {
+  note(
+    'Comma-separated JIDs, e.g. 15551234567@s.whatsapp.net (a group JID ends in\n' +
+      '@g.us — allow-listing a group trusts EVERYONE in it). Empty input clears the\n' +
+      'list; your own Note-to-Self chat is always allowed.',
+    'allow-list',
+  );
+  const answer = await text({
+    message: 'Allowed JIDs',
+    initialValue: current.join(', '),
+    placeholder: '15551234567@s.whatsapp.net',
+  });
+  if (isCancel(answer)) return;
+  const parsed = parseAllowedJids(String(answer));
+  await vault.set(WHATSAPP_ALLOWED_JIDS_KEY, JSON.stringify(parsed), ['whatsapp']);
+  log.success(
+    parsed.length > 0 ? `Allow-list saved (${parsed.length} JIDs).` : 'Allow-list cleared.',
+  );
+}