@rubytech/create-maxy 1.0.439 → 1.0.441

package/payload/platform/plugins/whatsapp/PLUGIN.md

@@ -0,0 +1,36 @@
+---
+name: whatsapp
+description: WhatsApp messaging channel — Baileys QR pairing, DM/group policy enforcement, inbound routing, outbound messaging.
+tools:
+  - whatsapp-login-start
+  - whatsapp-login-wait
+  - whatsapp-status
+  - whatsapp-disconnect
+  - whatsapp-send
+---
+
+# WhatsApp
+
+Activate when the user asks about WhatsApp — connecting, linking, checking status, managing accounts, DM policies, group policies, or sending messages.
+
+## What this unlocks
+
+- QR-code-based WhatsApp pairing via Baileys (linked device)
+- Multi-account support (personal + business numbers)
+- Inbound message routing (admin phone → admin agent, public → public agent)
+- Group messaging with mention gating and per-group activation
+- DM policy enforcement (open, pairing, allowlist, disabled)
+- Voice note normalization (OGG Opus via ffmpeg)
+- Auto-reconnection with exponential backoff
+
+## Skills
+
+| Skill | Purpose |
+|-------|---------|
+| [connect-whatsapp](skills/connect-whatsapp/SKILL.md) | Conversational WhatsApp pairing — QR generation, scanning, status confirmation |
+
+## References
+
+| Reference | Topics |
+|-----------|--------|
+| [channels-whatsapp.md](references/channels-whatsapp.md) | Architecture, DM/group policies, reconnection, voice notes, outbound policy |

package/payload/platform/plugins/whatsapp/mcp/dist/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * WhatsApp MCP server — exposes WhatsApp lifecycle tools to the admin agent.
+ *
+ * Tools call the platform's Hono API routes (localhost) which manage the
+ * Baileys connection lifecycle in the server process.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/payload/platform/plugins/whatsapp/mcp/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/payload/platform/plugins/whatsapp/mcp/dist/index.js

@@ -0,0 +1,128 @@
+/**
+ * WhatsApp MCP server — exposes WhatsApp lifecycle tools to the admin agent.
+ *
+ * Tools call the platform's Hono API routes (localhost) which manage the
+ * Baileys connection lifecycle in the server process.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const PLATFORM_PORT = 19201;
+const BASE_URL = `http://127.0.0.1:${PLATFORM_PORT}`;
+const server = new McpServer({
+    name: "maxy-whatsapp",
+    version: "0.1.0",
+});
+async function callApi(path, method = "POST", body) {
+    const res = await fetch(`${BASE_URL}${path}`, {
+        method,
+        headers: body ? { "Content-Type": "application/json" } : undefined,
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    return res.json();
+}
+function textResult(text, isError = false) {
+    return {
+        content: [{ type: "text", text }],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+// ─── whatsapp-login-start ──────────────────────────────────────────────
+server.tool("whatsapp-login-start", "Start WhatsApp QR code pairing. Initiates a Baileys WebSocket, generates a QR code for the user to scan with their phone. Returns QR data for rendering inline via render-component.", {
+    accountId: z.string().optional().describe('Account ID (default: "default")'),
+    force: z.boolean().optional().describe("Force re-link even if already connected"),
+}, async ({ accountId, force }) => {
+    try {
+        const result = await callApi("/api/whatsapp/login/start", "POST", { accountId, force });
+        if (result.error)
+            return textResult(`Login start failed: ${result.error}`, true);
+        let response = result.message;
+        if (result.qrRaw) {
+            response += `\n\nQR data (render inline): ${result.qrRaw}`;
+        }
+        if (result.selfPhone) {
+            response += `\nLinked phone: ${result.selfPhone}`;
+        }
+        return textResult(response);
+    }
+    catch (err) {
+        return textResult(`Login start failed: ${err instanceof Error ? err.message : String(err)}`, true);
+    }
+});
+// ─── whatsapp-login-wait ───────────────────────────────────────────────
+server.tool("whatsapp-login-wait", "Wait for WhatsApp QR code to be scanned and connection to be established. Call after whatsapp-login-start. Polls for up to 60 seconds.", {
+    accountId: z.string().optional().describe('Account ID (default: "default")'),
+    timeoutMs: z.number().optional().describe("Max wait time in ms (default: 60000)"),
+}, async ({ accountId, timeoutMs }) => {
+    try {
+        const result = await callApi("/api/whatsapp/login/wait", "POST", { accountId, timeoutMs });
+        if (result.error)
+            return textResult(`Login wait failed: ${result.error}`, true);
+        let response = result.message;
+        if (result.connected && result.selfPhone) {
+            response += `\nLinked phone: ${result.selfPhone}`;
+        }
+        return textResult(response);
+    }
+    catch (err) {
+        return textResult(`Login wait failed: ${err instanceof Error ? err.message : String(err)}`, true);
+    }
+});
+// ─── whatsapp-status ───────────────────────────────────────────────────
+server.tool("whatsapp-status", "Get WhatsApp connection status for all linked accounts. Shows connected/disconnected state, linked phone number, and reconnection attempts.", {}, async () => {
+    try {
+        const result = await callApi("/api/whatsapp/status", "GET");
+        if (result.error)
+            return textResult(`Status check failed: ${result.error}`, true);
+        const accounts = result.accounts ?? [];
+        if (accounts.length === 0) {
+            return textResult("No WhatsApp accounts configured. Say \"connect WhatsApp\" to get started.");
+        }
+        const lines = accounts.map((a) => {
+            const status = a.connected ? "✓ Connected" : "✗ Disconnected";
+            const phone = a.selfPhone ? ` (${a.selfPhone})` : "";
+            const name = a.accountName ? ` — ${a.accountName}` : "";
+            const error = a.lastError ? ` — ${a.lastError}` : "";
+            const retries = a.reconnectAttempts > 0 ? ` [${a.reconnectAttempts} reconnect attempts]` : "";
+            return `${a.accountId}${name}: ${status}${phone}${error}${retries}`;
+        });
+        return textResult(lines.join("\n"));
+    }
+    catch (err) {
+        return textResult(`Status check failed: ${err instanceof Error ? err.message : String(err)}`, true);
+    }
+});
+// ─── whatsapp-disconnect ───────────────────────────────────────────────
+server.tool("whatsapp-disconnect", "Disconnect a WhatsApp account. Closes the Baileys WebSocket connection cleanly.", {
+    accountId: z.string().optional().describe('Account ID to disconnect (default: "default")'),
+}, async ({ accountId }) => {
+    try {
+        const result = await callApi("/api/whatsapp/disconnect", "POST", { accountId });
+        if (result.error)
+            return textResult(`Disconnect failed: ${result.error}`, true);
+        return textResult(`WhatsApp account "${result.accountId}" disconnected.`);
+    }
+    catch (err) {
+        return textResult(`Disconnect failed: ${err instanceof Error ? err.message : String(err)}`, true);
+    }
+});
+// ─── whatsapp-send ─────────────────────────────────────────────────────
+server.tool("whatsapp-send", "Send a WhatsApp message to a phone number or group. The target can be an E.164 phone number or a WhatsApp group JID.", {
+    to: z.string().describe("Target phone number (E.164) or group JID"),
+    text: z.string().describe("Message text to send"),
+    accountId: z.string().optional().describe('Account to send from (default: "default")'),
+}, async ({ to, text, accountId }) => {
+    try {
+        const result = await callApi("/api/whatsapp/send", "POST", { to, text, accountId });
+        if (result.error)
+            return textResult(`Send failed: ${result.error}`, true);
+        return textResult(`Message sent via WhatsApp${result.messageId ? ` (ID: ${result.messageId})` : ""}`);
+    }
+    catch (err) {
+        return textResult(`Send failed: ${err instanceof Error ? err.message : String(err)}`, true);
+    }
+});
+// ─── Start server ──────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);
+//# sourceMappingURL=index.js.map

package/payload/platform/plugins/whatsapp/mcp/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/payload/platform/plugins/whatsapp/mcp/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@maxy/whatsapp",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  }
+}

package/payload/platform/plugins/whatsapp/references/channels-whatsapp.md

@@ -0,0 +1,329 @@
+# WhatsApp Channels
+
+Taskmaster supports two WhatsApp connection methods via Baileys multi-account:
+
+| Provider | Use Case | Connection |
+|----------|----------|------------|
+| **baileys** (default) | All WhatsApp accounts — personal and business | WebSocket via QR code (linked device) |
+| **cloud** | Enterprise — Meta's official API | Meta Graph API + webhooks |
+
+## Primary Architecture: Multi-Account Baileys
+
+Most users will have two Baileys accounts (two phone numbers, both linked via QR):
+
+| Account | Purpose |
+|---------|---------|
+| **Personal** | Admin self-chat, groups, personal contacts |
+| **Business** | Customer-facing DMs (can be WhatsApp Business app or regular WhatsApp) |
+
+WhatsApp Business **app** vs personal WhatsApp is irrelevant from Taskmaster's perspective — Baileys connects to both identically via QR. The Business app just adds business profile, catalog, and labels in the phone UI.
+
+**Linked device note:** The primary phone must come online periodically (~every 14 days) to keep the Baileys linked-device session alive. It does NOT need to be on 24/7.
+
+## Managing Accounts via UI
+
+The Setup page (`/setup`) supports multi-account management in its status dashboard (shown after initial setup is complete):
+
+- **Add Account:** Click "+ Add WhatsApp Account" below the status dashboard, enter a name (e.g. "Business"), and scan the QR code to link
+- **Relink:** Each account has its own relink button (rotate icon) that shows a per-account QR code inline
+- **Remove:** Each account (except the last one) has a remove button (X icon) that disconnects and removes the account from config
+- **Per-account QR:** QR codes appear inline under the specific account being linked
+
+The initial first-run wizard flow stays single-account. Multi-account is managed from the status dashboard that appears once setup is complete.
+
+## Multi-Account Config Example
+
+```yaml
+channels:
+  whatsapp:
+    allowFrom:
+      - "+447490553305"    # Admin phone (routes to admin agent)
+    accounts:
+      personal:
+        provider: baileys
+        name: "Personal"
+        selfChatMode: true
+      business:
+        provider: baileys
+        name: "Business"
+```
+
+Both accounts are linked via QR in the Channels UI. Outbound routing (`src/web/outbound-routing.ts`) selects the right account automatically:
+
+| Target | Account | Reason |
+|--------|---------|--------|
+| Admin/allowFrom phones | Personal | Admin's own number |
+| Self-chat | Personal | Admin talking to themselves |
+| Group messages | Personal or Business | Whichever is in the group |
+| Customer DMs | Business (preferred), Personal (fallback) | Dedicated business number |
+| Inbound replies | Same account that received | Closures capture the right provider |
+
+## Cloud API (Enterprise)
+
+Full Cloud API support is implemented for enterprise users who need:
+- Verified green checkmark badge
+- Message templates for proactive outreach
+- No phone dependency at all
+- Higher throughput limits
+
+**Important:** Cloud API requires a **different number** from any Baileys-linked number. A single number cannot be on both — Meta's Cloud API takes exclusive control of the number (no app access, no groups).
+
+Cloud API code lives in:
+- `src/web/providers/cloud/` — CloudApiProvider, Graph API client, webhooks
+- `src/web/auto-reply/cloud-monitor.ts` — Cloud API reconnection loop
+- Channel plugin in `extensions/whatsapp/src/channel.ts` — provider-aware branching
+
+Cloud API requirements: Meta Business Account, System User Access Token, Cloudflare Tunnel for webhooks (`src/infra/tunnel.ts`). Webhook endpoint: `/webhook/whatsapp`.
+
+## Baileys Risk Profile
+
+Baileys uses the same WebSocket protocol as WhatsApp Web/Desktop linked devices. Meta cannot blanket-block it without breaking their own official clients for hundreds of millions of users.
+
+**Responsibility model:** Taskmaster and its other users are not at risk — bans are per-number, targeting individual accounts for abusive behaviour. Users should be told: *"Don't use this for bulk messaging or spam. Meta may ban your number for abusive patterns. Normal business conversations are fine."*
+
+- Normal conversational use (replies, scheduling, quotes) = effectively zero risk
+- Ack reactions, typing indicators, and reply delays mimic real linked-device behaviour
+- Risk increases only with spam patterns: mass messaging, rapid-fire sends to unknown contacts, broadcasting
+- If a user's number is banned, it's between them and Meta — other Taskmaster users are unaffected
+- Cloud API code is available as a fallback for enterprise users who want official Meta support
+
+## WhatsApp Outbound Policy — No Automated Broadcasts
+
+**WhatsApp's Terms of Service explicitly prohibit automated bulk/broadcast messaging.** This applies to both Baileys and Cloud API connections. Violations result in permanent number bans with no appeal.
+
+Taskmaster enforces this at multiple levels:
+
+1. **Broadcast action blocked** — The `message broadcast` action (which sends to multiple targets) always excludes WhatsApp as a target channel, regardless of config. This is a hard block that cannot be overridden.
+2. **Agent tool suppression** — When an agent session is on WhatsApp, the `broadcast` action is removed from the message tool schema entirely. Agents cannot invoke it.
+3. **Broadcast disabled by default** — `tools.message.broadcast.enabled` defaults to `false`. Even when enabled for other channels (Discord, Telegram, Slack), WhatsApp remains blocked.
+
+**What IS allowed on WhatsApp:**
+- Replying to incoming messages (the core use case)
+- Sending messages to a single known contact via the `send` action
+- Heartbeat/scheduled messages to the admin's own number
+- Owner outbound mirroring (detecting manual WhatsApp Web sends)
+
+**What is NOT allowed:**
+- Sending the same message to multiple WhatsApp contacts in a loop
+- Any form of automated outreach to contacts who have not messaged first
+- Using the broadcast action with WhatsApp as a target channel
+- Building "campaign" or "blast" workflows that target WhatsApp contacts
+
+## DM Policy & Access Control
+
+**Precise definitions — these terms are NOT interchangeable:**
+
+| Term | Definition | Code |
+|------|-----------|------|
+| **Self phone** | The WhatsApp account's own phone number (the phone that scanned the QR code). Self-chat only. | `isSamePhone = params.from === params.selfE164` |
+| **Admin phones** | Phones with explicit peer bindings (`match.peer.kind === "dm"`, `match.peer.id === phone`) for this WhatsApp account in `cfg.bindings`. These are phones added via the Admins page or auto-paired on QR link. A phone is admin if it has a specific binding — not just because it's in `allowFrom`. | Binding lookup in `cfg.bindings` |
+| **Paired phones** | Phones in the pairing store (`storeAllowFrom`) that completed the pairing handshake. Subset of explicitly allowed phones. | `readChannelAllowFromStore("whatsapp")` |
+| **Public/unknown** | Any phone that is not self, not admin-bound, and not explicitly in `allowFrom` (non-wildcard). | Everything else |
+
+**`dmPolicy` behaviour (per-account, set via Setup toggle):**
+
+| Policy | Self phone | Admin phones (explicit binding) | Explicitly allowed (non-wildcard) | Public/unknown |
+|--------|-----------|-------------------------------|----------------------------------|----------------|
+| `"open"` | Allowed | Allowed | Allowed | Allowed |
+| `"pairing"` | Allowed | Allowed | Allowed | Pairing reply sent |
+| `"allowlist"` | Allowed | Allowed | Allowed | Blocked |
+| `"disabled"` | Allowed | Allowed | Blocked | **Blocked** |
+
+**Admin phones always have the same access as self phone.** An explicit peer binding (`match.peer.kind === "dm"`, `match.peer.id === phone`) bypasses dmPolicy entirely — the phone is allowed in every mode. The binding check runs once before any policy-specific logic.
+
+The "Public facing" toggle on Setup switches between `"open"` (on) and `"disabled"` (off). When disabled, only self-phone and admin-bound phones get through. Everyone else is blocked.
+
+**Key file:** `src/web/inbound/access-control.ts` — `checkInboundAccessControl()`.
+
+**Config path:** Per-account at `channels.whatsapp.accounts.{accountId}.dmPolicy`. Falls back to `channels.whatsapp.dmPolicy`. The UI toggle writes to the per-account path with `skipRestart: true` (no gateway restart needed — `channels.whatsapp` prefix is `kind: "none"` in config-reload rules).
+
+## Public Agent Settings Modal
+
+When WhatsApp is connected, a gear icon appears inline next to the "WhatsApp" label in the Setup dashboard. Clicking it opens a "Public Agent Settings" modal containing: **Agent responds** master toggle, Model selector, and Thinking level selector. This keeps the main dashboard row clean while giving access to all WhatsApp configuration.
+
+**Agent responds toggle** — master on/off switch controlling both DMs and groups simultaneously. When enabled, writes `dmPolicy: "open"` + `allowFrom: ["*"]` + `groupPolicy: "open"`. When disabled, writes `dmPolicy: "disabled"` + `groupPolicy: "disabled"`. Individual group activation is configured per-chat in the WhatsApp tab of the chat view. All groups default to `"off"` (no response) until explicitly configured.
+
+## Per-Account Model Selector
+
+The Public Agent Settings modal includes a **Model** dropdown that sets the default AI model for the selected account's public agent. This controls which model responds to customer messages on WhatsApp.
+
+**Options:** Default (global fallback), Opus, Sonnet, Haiku — filtered against the available model catalog.
+
+**Config path:** `agents.list[{publicAgentId}].model` — uses the existing per-agent model override mechanism. When "Default" is selected, the override is removed and the global `agents.defaults.model` applies.
+
+**How it works:**
+1. UI resolves the selected workspace's public agent ID (e.g. `joes-coffee-public`)
+2. On change, writes the model to config via `writeAgentModelToConfig` (two params: agentId + model)
+3. Config stored in `agents.list[{agentId}].model` in `~/.taskmaster/taskmaster.json`
+4. No gateway restart needed — `agents` prefix has `kind: "none"` reload rule (read dynamically)
+
+**Runtime model resolution — config is the single source of truth.** Every model read (LLM API call, `/status` display, chat UI initial load) calls `loadConfig()` fresh and resolves via `resolveDefaultModelForAgent({ cfg, agentId })`. There are no session-level model overrides — the model is always read from config at the point of use.
+
+**Key files:**
+| File | Purpose |
+|------|---------|
+| `ui/src/ui/views/setup.ts` | Model dropdown rendering (`renderWhatsAppModelSelector`) |
+| `ui/src/ui/app-render.ts` | State resolution + change handler |
+| `src/agents/agent-model-config.ts` | `writeAgentModelToConfig()` — writes per-agent model to config |
+| `src/agents/model-selection.ts` | `resolveDefaultModelForAgent()` — runtime resolution |
+| `src/agents/agent-scope.ts` | `resolveAgentModelPrimary()` — reads per-agent config |
+| `src/auto-reply/reply/get-reply-run.ts` | Fresh config read before LLM call |
+| `src/auto-reply/reply/commands-status.ts` | Fresh config read for `/status` display |
+| `src/gateway/session-utils.ts` | `resolveSessionModelRef()` — fresh config read for chat UI |
+
+## Per-Account Thinking Level Selector
+
+The Public Agent Settings modal includes a **Thinking** dropdown that sets the default thinking level for the selected account's public agent. This controls how deeply the agent reasons before responding to customer messages.
+
+**Options:** Off, Minimal, Low, Medium, High.
+
+**Config path:** `agents.list[{publicAgentId}].thinkingLevel` — uses the per-agent thinking override mechanism (same pattern as model). When "Off" is selected, the override is removed and the global default applies.
+
+**How it works:**
+1. UI resolves the selected workspace's public agent ID (e.g. `joes-coffee-public`)
+2. On change, writes the thinking level to config via `writeAgentThinkingToConfig` (two params: agentId + thinkingLevel)
+3. Config stored in `agents.list[{agentId}].thinkingLevel` in `~/.taskmaster/taskmaster.json`
+4. No gateway restart needed — `agents` prefix has `kind: "none"` reload rule (read dynamically)
+
+**Runtime thinking resolution — config is the single source of truth.** Every thinking level read calls `loadConfig()` fresh and resolves via `resolveThinkingDefault({ cfg, provider, model, catalog, agentId })`. There are no session-level thinking overrides — thinking is always read from config at the point of use.
+
+**Key files:**
+| File | Purpose |
+|------|---------|
+| `ui/src/ui/views/setup.ts` | Thinking dropdown rendering (`renderWhatsAppThinkingSelector`) |
+| `ui/src/ui/app-render.ts` | State resolution + change handler |
+| `src/agents/agent-model-config.ts` | `writeAgentThinkingToConfig()` — writes per-agent thinking to config |
+| `src/agents/model-selection.ts` | `resolveThinkingDefault()` — runtime resolution (checks per-agent first) |
+| `src/agents/agent-scope.ts` | `resolveAgentThinkingLevel()` — reads per-agent config |
+
+## Owner Outbound Mirroring
+
+When the business owner sends a WhatsApp message directly via WhatsApp Web (not through the agent), Baileys detects the echo with `key.fromMe = true`. The inbound monitor (`src/web/inbound/monitor.ts`) checks `access.isOwnerOutbound` and calls `mirrorOwnerReplyToSession()`, which writes a `[Owner reply] {body}` delivery-mirror into the public agent's session transcript via `appendAssistantMessageToSessionTranscript`. This ensures the public agent knows about the owner's direct intervention when the customer next replies.
+
+The same path is used when an **admin agent** sends to a customer via the `message` tool (cross-agent echo): `fireCrossAgentEcho` in `src/infra/outbound/cross-agent-echo.ts` resolves the public agent's session key and delegates to `mirrorOwnerReplyToSession`. For established sessions the mirror is written to disk immediately; for first-contact customers with no session yet, an ephemeral system event is queued instead.
+
+### Agent-sent echo suppression
+
+Every outbound Baileys message echoes back as a `fromMe` `messages.upsert` event. To prevent the monitor from treating agent-sent echoes as manual owner messages, all send paths must track message IDs via `trackAgentSentMessage(id)` in `src/web/inbound/dedupe.ts`. The monitor then checks `isAgentSentMessage(id)` before calling `mirrorOwnerReplyToSession`.
+
+There are two send paths — both must track IDs:
+- **IPC send API** (`src/web/inbound/send-api.ts`): used by the message tool, gateway RPC, and `sendPoll`. Tracks IDs after `sock.sendMessage`.
+- **Auto-reply closures** (`monitor.ts` lines 390-401): the `reply()` and `sendMedia()` functions on `WebInboundMessage`, used by `deliverWebReply`. Track IDs after `sock.sendMessage`.
+
+The dedupe cache (`agentSentMessages`) has a 2-minute TTL and 500-entry cap, which is sufficient because Baileys echoes arrive within seconds.
+
+**Key files:**
+| File | Purpose |
+|------|---------|
+| `src/web/inbound/monitor.ts` | Detects `fromMe` echoes, calls `mirrorOwnerReplyToSession`; auto-reply `reply`/`sendMedia` closures |
+| `src/web/inbound/owner-mirror.ts` | `mirrorOwnerReplyToSession()` — canonical implementation |
+| `src/web/inbound/access-control.ts` | `isOwnerOutbound` flag for `fromMe` DMs |
+| `src/web/inbound/send-api.ts` | IPC send path — tracks agent-sent message IDs |
+| `src/web/inbound/dedupe.ts` | `trackAgentSentMessage` / `isAgentSentMessage` — echo suppression cache |
+| `src/infra/outbound/cross-agent-echo.ts` | Adapter: agent tool → `mirrorOwnerReplyToSession` |
+
+## Offline Message Recovery
+
+Baileys is a WhatsApp Web protocol client. When the gateway is offline, WhatsApp's servers hold incoming messages and push them back as history (`append`-type `messages.upsert` events) when Baileys reconnects — so the system self-recovers automatically on restart. These replayed messages are stored in the UI message cache and marked as read, but **not** dispatched to the agent (no auto-reply on catch-up). The recovery window is determined entirely by WhatsApp's server-side delivery queue (approximately 30 days); `syncFullHistory: false` only prevents requesting full chat history on first pairing and does not restrict this window.
+
+## Voice Notes (PTT)
+
+Outbound TTS audio is sent as native WhatsApp PTT (Push-To-Talk) voice notes. The pipeline:
+
+1. **TTS output format:** `resolveOutputFormat("whatsapp")` returns Opus (OGG container) instead of MP3 (`src/tts/tts.ts`)
+2. **ffmpeg normalization:** `normalizePttAudio()` re-encodes to WhatsApp-native format — OGG Opus, 48 kHz, mono, 64 kbps, VoIP mode (`src/media/ptt-normalize.ts`)
+3. **Baileys metadata:** `music-metadata` and `audio-decode` npm packages compute `seconds` (duration) and `waveform` fields for the PTT message. Without these, WhatsApp renders audio as a generic file attachment.
+4. **Send:** `ptt: true` flag on the audio message, no caption (voice IS the content)
+
+**System dependency:** ffmpeg must be on PATH. Installed automatically by `install.sh` (fresh) and `postinstall.js` (upgrades). Best-effort — if ffmpeg is unavailable, the original audio is sent as-is.
+
+**Key files:**
+| File | Purpose |
+|------|---------|
+| `src/media/ptt-normalize.ts` | ffmpeg re-encoding to WhatsApp-native OGG Opus |
+| `src/web/auto-reply/deliver-reply.ts` | Auto-reply path (calls normalizePttAudio for audio) |
+| `src/web/inbound/send-api.ts` | Baileys send wrapper (sets `ptt: true`) |
+| `src/tts/tts.ts` | TTS output format resolution (Opus for WhatsApp) |
+
+## Session Credentials (Baileys Auth)
+
+Baileys stores WhatsApp session credentials (linked-device state) on disk. The auth directory contains `creds.json` (session keys) and Signal protocol pre-keys.
+
+**Path resolution** (`src/web/accounts.ts` → `resolveWhatsAppAuthDir`):
+
+| Priority | Path | When |
+|----------|------|------|
+| 1. Explicit config | `channels.whatsapp.accounts.{id}.authDir` | User overrides in config |
+| 2. Default | `~/.taskmaster/credentials/whatsapp/{accountId}/` | Normal operation |
+| 3. Legacy fallback | `~/.taskmaster/credentials/` | Old single-account installs (only if creds exist here and not at default path) |
+
+The state dir (`~/.taskmaster/`) can be overridden via `TASKMASTER_STATE_DIR` env var; the credentials subdirectory via `TASKMASTER_OAUTH_DIR`.
+
+**Diagnostics on the Pi:**
+
+```bash
+# List all WhatsApp auth directories
+ls -la ~/.taskmaster/credentials/whatsapp/
+
+# Check if credentials exist for an account
+ls ~/.taskmaster/credentials/whatsapp/default/creds.json
+
+# Check credential freshness (should be recent if just linked)
+stat ~/.taskmaster/credentials/whatsapp/default/creds.json
+```
+
+If `creds.json` is missing, the session was never linked or was deleted. If it exists but WhatsApp rejects it (401), the session was invalidated (cleared from phone, expired after 14 days offline, or account banned).
+
+**Key files:** `src/web/accounts.ts` (resolveWhatsAppAuthDir), `src/config/paths.ts` (resolveOAuthDir, resolveStateDir), `src/web/session.ts` (enqueueSaveCreds — writes creds on update).
+
+## Disconnect Reasons
+
+Baileys disconnect errors carry a numeric status code mapped to `DisconnectReason`. The monitor translates these to user-facing messages via `humanizeWhatsAppError()` in `src/web/auto-reply/monitor.ts`.
+
+| Status | Baileys Reason | Meaning | Auto-reconnect? |
+|--------|---------------|---------|-----------------|
+| 401 | loggedOut | Session removed from phone or expired | No — re-link required |
+| 401 + "conflict" | connectionReplaced (server override) | Another WhatsApp Web session took over | Yes |
+| 403 | forbidden | Number banned or restricted | No |
+| 408 | connectionLost / timedOut | Network interruption or timeout | Yes |
+| 428 | connectionClosed | Server closed the connection | Yes |
+| 440 | connectionReplaced | Another session replaced this one | Yes |
+| 500 | badSession | Corrupted session data | No — re-link required |
+| 515 | restartRequired | Server requests reconnection | Yes |
+
+**Conflict vs logout (401 ambiguity):** WhatsApp's server can send a stream error with code 401 and reason "conflict" — Baileys normally maps "conflict" to 440, but the server's explicit `code` attribute overrides the mapping. The monitor checks for "conflict" in the error message to distinguish this from a true logout.
+
+## Reconnection: Setup Failures vs Runtime Disconnects
+
+The reconnection loop in `monitorWebChannel` handles two distinct failure modes:
+
+| Failure Mode | When | Example | Handling |
+|-------------|------|---------|----------|
+| **Runtime disconnect** | After a successful connection drops | 408 (connectionLost), 428 (connectionClosed) | `listener.onClose` resolves → backoff retry |
+| **Setup failure** | Connection never establishes | 405 (Method Not Allowed), 503 (service unavailable) | `monitorWebInbox` throws → caught by try-catch → same backoff retry |
+
+Both paths use the same backoff policy (2s → 30s, 12 max attempts) and the same loggedOut detection. A 401 status only triggers logout if the error message does NOT contain "conflict" (see Disconnect Reasons above). Setup failures log as `"web reconnect: connection setup failed"` instead of `"web reconnect: connection closed"`.
+
+Without the setup-failure handling, a transient WhatsApp server rejection (e.g., 405 during a protocol update) would kill the channel permanently — the error would escape the reconnection loop, and only a gateway restart could recover.
+
+## Provider Architecture
+
+```
+src/web/
+├── outbound-routing.ts  # Multi-account outbound routing logic
+├── active-listener.ts   # Per-account listener registry (listActiveWebAccountIds, etc.)
+├── outbound.ts          # Outbound send (routes through outbound-routing)
+├── providers/
+│   ├── types.ts         # WhatsAppProvider interface
+│   ├── factory.ts       # createWhatsAppProvider()
+│   ├── baileys/         # BaileysProvider (wraps monitorWebInbox)
+│   └── cloud/           # CloudApiProvider (parked — enterprise)
+└── auto-reply/
+    ├── monitor.ts       # Baileys reconnection loop (monitorWebChannel)
+    ├── cloud-monitor.ts # Cloud API reconnection loop (monitorCloudChannel)
+    └── monitor/
+        └── on-message.ts # Shared message handler (used by both providers)
+
+extensions/whatsapp/src/
+└── channel.ts           # Channel plugin (provider-aware throughout)
+```

package/payload/platform/plugins/whatsapp/skills/connect-whatsapp/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: connect-whatsapp
+description: Guide the user through connecting WhatsApp via QR code pairing. Renders QR inline, polls for completion, confirms connection, and sets up admin/public bindings.
+---
+
+# Connect WhatsApp
+
+Conversational flow for linking a WhatsApp account to Maxy via Baileys QR pairing.
+
+## When to activate
+
+User says anything about connecting, linking, setting up, or adding WhatsApp.
+
+## Prerequisites
+
+Call `whatsapp-status` first to check the current state. If already connected, tell the user and offer to relink.
+
+## Flow
+
+1. **Initiate pairing** — call `whatsapp-login-start`. If the account is already linked and the user didn't say "relink", inform them and stop.
+
+2. **Show QR code** — the tool returns QR data. Use `render-component` to display the QR code inline in the chat. Tell the user: "Open WhatsApp on your phone → Settings → Linked Devices → Link a Device → Scan this QR code."
+
+3. **Wait for scan** — call `whatsapp-login-wait`. This polls for up to 60 seconds. While waiting, tell the user you're watching for the scan.
+
+4. **Confirm connection** — when pairing completes, the tool returns the linked phone number. Confirm: "WhatsApp connected as {phone}. Messages from your phone route to this admin chat. Messages from other numbers route to the public agent."
+
+5. **Verify** — call `whatsapp-status` to confirm the connection is live.
+
+## Relinking
+
+If the user says "relink WhatsApp" or the status shows disconnected with a 401 error:
+1. Call `whatsapp-login-start` with `force: true` to clear old credentials and generate a fresh QR
+2. Follow the same flow as above
+
+## Troubleshooting
+
+- **QR expired** — generate a new one with `whatsapp-login-start`
+- **Phone not scanning** — ensure the phone has internet, WhatsApp is updated, and the user is in Linked Devices
+- **Keeps disconnecting** — check `whatsapp-status` for error details. A 401 means re-link is needed. Repeated transient errors suggest network issues on the device.
+
+## Language
+
+Use plain English:
+- "QR code" not "Baileys pairing token"
+- "Link your phone" not "initiate WebSocket connection"
+- "WhatsApp is connected" not "Baileys socket is open"