whatsapp-pi 1.0.46 → 1.0.47

package/README.md

@@ -8,7 +8,7 @@ A WhatsApp integration extension for the **[Pi Coding Agent](https://github.com/
 
 [![GitHub](https://img.shields.io/badge/github-repo-black.svg?style=flat-square&logo=github)](https://github.com/RaphaCastelloes/whatsapp-pi)
 
-Pi is a powerful agentic AI coding assistant that operates in your terminal. This extension allows you to chat and pair-program with your Pi agent directly through WhatsApp, featuring message filtering, allow-listing, and reliable message delivery.
+Pi is a powerful agentic AI coding assistant that operates in your terminal. This extension allows you to chat and pair-program with your Pi agent directly through WhatsApp, featuring message filtering, allow-listing, recents/history browsing, message detail/reply, group-only binding, and reliable message delivery.
 
 ## Features
 
@@ -16,10 +16,14 @@ Pi is a powerful agentic AI coding assistant that operates in your terminal. Thi
 - **Allow List**: Control which numbers can interact with Pi
   - Add contacts with optional names for easy identification
   - View ignored numbers (not in allow list) and add them when needed
+  - Manage aliases and print allowed numbers from the menu
+- **Recents & History**: Browse recent conversations, inspect full message history, and reply from message detail view
 - **Reliable Messaging**: Queue-based message sending with retry logic
-- **TUI Integration**: Menu-driven interface for managing connections and contacts
+- **TUI Integration**: Menu-driven interface for managing connections, contacts, and recent chats
+- **Group-Only Mode**: Bind the agent to a single WhatsApp group with `--whatsapp-group`
 - **Media Support**: 
   - **Vision Analysis**: Automatically forwards WhatsApp images to Pi for analysis.
+  - **Audio Transcription**: Transcribes voice notes when Whisper is installed.
   - **Document Handling**: Downloads and stores documents (PDF, text) for agent access.
 
 ## Prerequisites
@@ -46,10 +50,10 @@ pi install npm:whatsapp-pi
 pi
 ```
 
-After connecting WhatsApp once from the menu and scanning the QR code, you can start Pi with auto-connect enabled:
-```bash
-pi --whatsapp-pi-online
-```
+After connecting WhatsApp once from the menu and scanning the QR code, you can start Pi with auto-connect enabled:
+```bash
+pi --whatsapp-pi-online
+```
 
 3. Use the menu to connect WhatsApp and manage allowed/blocked numbers
 
@@ -69,15 +73,15 @@ npm install
 pi -e whatsapp-pi.ts
 ```
 
-For verbose mode (shows Baileys trace logs for debugging):
-```bash
-pi -e whatsapp-pi.ts --verbose
-```
-
-To test startup auto-connect locally after you have already paired WhatsApp:
-```bash
-pi -e whatsapp-pi.ts --whatsapp-pi-online
-```
+For verbose mode (shows Baileys trace logs for debugging):
+```bash
+pi -e whatsapp-pi.ts --verbose
+```
+
+To test startup auto-connect locally after you have already paired WhatsApp:
+```bash
+pi -e whatsapp-pi.ts --whatsapp-pi-online
+```
 
 ## Commands
 
@@ -87,12 +91,21 @@ pi -e whatsapp-pi.ts --whatsapp-pi-online
 - **Connect / Reconnect WhatsApp** - Start WhatsApp connection using saved credentials when available; QR code appears only if pairing is required
 - **Disconnect WhatsApp** - Stop WhatsApp connection
 - **Logoff (Delete Session)** - Remove all credentials and session data
+- **Recents** - Open recent conversations, view history, and reply
 - **Allowed Numbers** - Manage contacts that can interact with Pi
 - **Blocked Numbers** - View ignored numbers and manage them
 
 ### Allowed Numbers Management
 - **Add Number** - Add a new contact to the allow list (format: +5511999999999)
-- **Select a contact** - Open a submenu with **Send Message**, **Remove Number**, and **Back**
+- **Select a contact** - Open a submenu with **History**, **Send Message**, **Print Number**, alias actions, **Remove Number**, and **Back**
+- **Back** - Return to main menu
+
+### Recents Management
+- **History** - Open full message history for that conversation
+- **Send Message** - Send a new message without Pi suffix
+- **Reply** - Open message detail, then press `R` to reply
+- **Allow Number** - Move a recent sender into the allow list
+- **Remove Alias** - Clear saved alias for that sender
 - **Back** - Return to main menu
 
 ### Blocked Numbers Management
@@ -106,11 +119,11 @@ pi -e whatsapp-pi.ts --whatsapp-pi-online
 ```
 src/
 ├── models/          # Type definitions
-├── services/        # Core services (WhatsApp, Session, MessageSender)
-└── ui/              # Menu handlers
+├── services/        # Core services (WhatsApp, Session, Recents, Media)
+└── ui/              # Menu handlers and TUI views
 
-specs/               # Feature specifications
-tests/               # Unit and integration tests
+tests/
+└── unit/            # Unit tests
 ```
 
 ## Development
@@ -122,15 +135,13 @@ npm test
 
 ## Implementation Notes
 
-### Recent Feature Updates (2026-04)
-
-- **Auto-Connect Support**: Use the `--whatsapp-pi-online` flag to automatically connect to WhatsApp on startup if you have a valid active session.
-- **Vision Analysis**: Images sent via WhatsApp are automatically downloaded and forwarded to the Pi agent as base64, enabling vision-based interactions.
-- **Document Message Support**: 
-  - WhatsApp documents (PDFs, text files, etc.) are downloaded and saved to `./.pi-data/whatsapp/documents/`.
-  - The Pi agent receives a notification with the file path and metadata.
-- **Full US-English Localization**: All user-facing menus, TUI notifications, console logs, and agent communication headers have been localized to `en-US` for a consistent experience.
-- **Intelligent Message Filtering**: 
-  - **Loop Prevention**: The bot automatically ignores any message ending with the `π` symbol, preventing infinite loops between instances.
-  - **Manual Interaction**: Users can now interact with the bot from their own WhatsApp account; the bot will process `fromMe` messages as long as they don't contain the bot's signature.
-- **Storage Management**: All persistent data (auth state, documents, config) is centralized in the `.pi-data/` directory.
+### Recent Feature Updates (2026-05)
+
+- **Auto-Connect Support**: Use the `--whatsapp-pi-online` flag to connect on startup when credentials already exist.
+- **Group-Only Mode**: Use `--whatsapp-group <jid>` to bind Pi to a single WhatsApp group.
+- **Recents Store**: Recent conversations and message history are persisted in `~/.pi/whatsapp-pi/recents/recents.json`.
+- **Message Detail / Reply**: Open a message from history to inspect full content and reply with `R`.
+- **Media Support**: Images are forwarded for vision analysis, audio is transcribed with Whisper, and documents are saved under `./.pi-data/whatsapp/documents/`.
+- **Session Handling**: Saved state, allow list, and startup reconnects are restored automatically when available.
+- **Intelligent Message Filtering**: Messages ending with `π` are ignored to prevent bot loops.
+- **Storage Management**: Persistent data lives under `.pi-data/` plus the recents store in the user home directory.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whatsapp-pi",
-  "version": "1.0.46",
+  "version": "1.0.47",
   "type": "module",
   "description": "WhatsApp integration extension for Pi",
   "main": "whatsapp-pi.ts",
@@ -32,7 +32,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@whiskeysockets/baileys": "^6.11.0",
+    "baileys": "^6.7.21",
     "pino": "^10.3.1",
     "qrcode-terminal": "^0.12.0"
   },

package/src/models/whatsapp.types.ts

@@ -18,12 +18,9 @@ export interface IncomingMessage {
     timestamp: number;
 }
 
-export type MessageOrigin = 'agent' | 'menu';
-
 export interface MessageRequest {
     recipientJid: string;
     text: string;
-    origin?: MessageOrigin;
     options?: {
         maxRetries?: number;
         priority?: 'high' | 'normal';

package/src/services/audio.service.ts

@@ -1,4 +1,4 @@
-import { downloadContentFromMessage } from '@whiskeysockets/baileys';
+import { downloadContentFromMessage } from 'baileys';
 import { exec } from 'node:child_process';
 import { promisify } from 'node:util';
 import { writeFile, mkdir } from 'node:fs/promises';

package/src/services/incoming-media.service.ts

@@ -1,4 +1,4 @@
-import { downloadContentFromMessage } from '@whiskeysockets/baileys';
+import { downloadContentFromMessage } from 'baileys';
 import { mkdir, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { AudioService } from './audio.service.js';
@@ -102,7 +102,7 @@ export class IncomingMediaService {
     }
 
     private async saveDocument(fileName: string, buffer: Buffer): Promise<string> {
-        const sanitized = fileName.replace(/[^a-z0-9._-]/gi, '_');
+        const sanitized = fileName.replace(/[^a-z0-9._-]/gi, '_');
         const savedFileName = `${Date.now()}_${sanitized}`;
         const documentDir = join(process.cwd(), '.pi-data', 'whatsapp', 'documents');
         const absolutePath = join(documentDir, savedFileName);

package/src/services/incoming-message.resolver.ts

@@ -1,4 +1,4 @@
-import { extractMessageContent } from '@whiskeysockets/baileys';
+import { extractMessageContent } from 'baileys';
 
 export type IncomingResolution =
     | { kind: 'text'; text: string }

package/src/services/message.sender.ts

@@ -1,5 +1,13 @@
 import { WhatsAppService } from './whatsapp.service.js';
 import { MessageRequest, MessageResult, WhatsAppError } from '../models/whatsapp.types.js';
+import { appendFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const LOG_FILE = join(homedir(), '.pi', 'whatsapp-pi', 'whatsapp-pi.log');
+function fileLog(msg: string) {
+    try { appendFileSync(LOG_FILE, `[${new Date().toISOString()}] [MessageSender] ${msg}\n`); } catch {}
+}
 
 export class MessageSender {
     private whatsappService: WhatsAppService;
@@ -37,7 +45,10 @@ export class MessageSender {
      * @returns Promise resolving to a result object indicating success or failure.
      */
     public async send(request: MessageRequest): Promise<MessageResult> {
-        const maxRetries = request.options?.maxRetries ?? 3;
+        const isGroup = request.recipientJid.endsWith('@g.us');
+        // Groups need more retries because the first send bootstraps
+        // the Signal sender-key session (causes "No sessions" on first attempts)
+        const maxRetries = isGroup ? 5 : (request.options?.maxRetries ?? 3);
         let attempts = 0;
         let lastError: unknown = null;
 
@@ -53,12 +64,18 @@ export class MessageSender {
                     throw new WhatsAppError('SOCKET_NOT_INIT', 'WhatsApp socket not initialized');
                 }
 
-                // 3. Send the message
-                const shouldAppendPi = request.origin !== 'menu';
-                const response = await socket.sendMessage(request.recipientJid, {
-                    text: shouldAppendPi ? `${request.text} π` : request.text
+                // 3. Pre-load group metadata on first attempt
+                if (isGroup && attempts === 1) {
+                    await this.whatsappService.prepareGroupSession(request.recipientJid);
+                }
+
+                // 4. Send the message
+                // Note: Branding π is applied here to ensure consistency
+                const response = await socket.sendMessage(request.recipientJid, { 
+                    text: `${request.text} π` 
                 });
 
+                fileLog(`SUCCESS sending to ${request.recipientJid} on attempt ${attempts}`);
                 return {
                     success: true,
                     messageId: response?.key?.id,
@@ -66,19 +83,24 @@ export class MessageSender {
                 };
             } catch (error: unknown) {
                 lastError = error;
-                console.error(`[MessageSender] Attempt ${attempts} failed for ${request.recipientJid}: ${error instanceof Error ? error.message : String(error)}`);
+                const errorMsg = error instanceof Error ? error.message : String(error);
+                fileLog(`Attempt ${attempts}/${maxRetries} FAILED for ${request.recipientJid}: ${errorMsg}`);
+                console.error(`[MessageSender] Attempt ${attempts} failed for ${request.recipientJid}: ${errorMsg}`);
                 
                 // Specific handling for non-retryable errors
                 if (error instanceof WhatsAppError && error.code === 'TIMEOUT') {
                     break;
                 }
 
-                // 4. Backoff before retry
+                // 5. Backoff before retry
                 if (attempts < maxRetries) {
-                    const backoff = Math.pow(2, attempts) * 1000;
-                    if (this.whatsappService.isVerbose()) {
-                        console.log(`[MessageSender] Retrying in ${backoff}ms...`);
-                    }
+                    // "No sessions" in groups needs much longer waits —
+                    // Baileys syncs sender-keys in the background between retries
+                    const isNoSessions = errorMsg.includes('No sessions');
+                    const baseBackoff = (isGroup && isNoSessions) ? 5000 : 1000;
+                    const backoff = Math.pow(2, attempts) * baseBackoff;
+                    fileLog(`Retrying in ${backoff / 1000}s...`);
+                    console.log(`[MessageSender] Retrying in ${backoff / 1000}s...`);
                     await this.sleep(backoff);
                 }
             }

package/src/services/recents.service.ts

@@ -137,6 +137,8 @@ export class RecentsService {
     }
 
     private normalizeNumber(input: string): string {
+        // Group JIDs should be stored as-is
+        if (input.endsWith('@g.us')) return input;
         const cleaned = input.replace(/@s\.whatsapp\.net$/, '');
         if (cleaned.startsWith('+')) {
             return cleaned;

package/src/services/session.manager.ts

@@ -1,33 +1,46 @@
-import { useMultiFileAuthState } from '@whiskeysockets/baileys';
-import { join } from 'path';
-import { readFile, writeFile, mkdir, rm, rename } from 'fs/promises';
+import { useMultiFileAuthState } from 'baileys';
+import { join } from 'path';
+import { readFile, writeFile, mkdir, rm, rename } from 'fs/promises';
 import { homedir } from 'os';
 import { SessionStatus } from '../models/whatsapp.types.js';
 
-export interface Contact {
-    number: string;
-    name?: string;
-}
-
-export class SessionManager {
-    // Data is stored in the user's home directory to persist across updates
-    private readonly baseDir: string;
-    private readonly authStateDir: string;
-    private readonly configPath: string;
+export interface Contact {
+    number: string;
+    name?: string;
+}
+
+export class SessionManager {
+    // Data is stored in the user's home directory to persist across updates
+    private readonly baseDir = join(homedir(), '.pi', 'whatsapp-pi');
+    private authStateDir = join(this.baseDir, 'auth');
+    private readonly configPath = join(this.baseDir, 'config.json');
+
+    static isGroupJid(jid: string): boolean {
+        return jid.endsWith('@g.us');
+    }
+
+    /**
+     * Sets a group-specific auth directory so each agent bound to a group
+     * registers as its own WhatsApp linked device.
+     */
+    setGroupJidForAuth(groupJid: string) {
+        const sanitized = groupJid.replace(/[^a-zA-Z0-9]/g, '_');
+        this.authStateDir = join(this.baseDir, `auth-${sanitized}`);
+    }
 
     private status: SessionStatus = 'logged-out';
     private allowList: Contact[] = [];
     private blockList: Contact[] = [];
     private ignoredNumbers: Contact[] = [];
     private hasAuthState = false;
-    private openaiKey: string = '';
-    private visionModel: string = 'gpt-4o';
-
-    constructor(baseDir = join(homedir(), '.pi', 'whatsapp-pi')) {
-        this.baseDir = baseDir;
-        this.authStateDir = join(this.baseDir, 'auth');
-        this.configPath = join(this.baseDir, 'config.json');
-    }
+    private openaiKey: string = '';
+    private visionModel: string = 'gpt-4o';
+
+    constructor(baseDir = join(homedir(), '.pi', 'whatsapp-pi')) {
+        this.baseDir = baseDir;
+        this.authStateDir = join(this.baseDir, 'auth');
+        this.configPath = join(this.baseDir, 'config.json');
+    }
 
     private async ensureStorageDirectories() {
         await mkdir(this.baseDir, { recursive: true });
@@ -39,17 +52,17 @@ export class SessionManager {
             await this.ensureStorageDirectories();
             await this.loadConfig();
             await this.syncAuthStateFromDisk();
-        } catch {
-            // Initialization is best-effort; callers can continue with defaults.
-        }
+        } catch {
+            // Initialization is best-effort; callers can continue with defaults.
+        }
     }
 
-    private async loadConfig() {
-        try {
-            const data = await readFile(this.configPath, 'utf-8');
-            const { config, recovered } = this.parseConfig(data);
-            
-            const cleanContact = (item: any): Contact | null => {
+    private async loadConfig() {
+        try {
+            const data = await readFile(this.configPath, 'utf-8');
+            const { config, recovered } = this.parseConfig(data);
+            
+            const cleanContact = (item: any): Contact | null => {
                 if (typeof item === 'string') return { number: item };
                 if (item && typeof item === 'object') {
                     let num = item.number;
@@ -68,92 +81,92 @@ export class SessionManager {
             this.blockList = (config.blockList || []).map(cleanContact).filter(Boolean) as Contact[];
             this.ignoredNumbers = (config.ignoredNumbers || []).map(cleanContact).filter(Boolean) as Contact[];
             this.status = config.status || 'logged-out';
-            this.hasAuthState = Boolean(config.hasAuthState);
-            this.openaiKey = config.openaiKey || '';
-            this.visionModel = config.visionModel || 'gpt-4o';
-
-            if (recovered) {
-                await this.saveConfig();
-            }
-        } catch {
-            // File not found is fine
-        }
-    }
-
-    private parseConfig(data: string): { config: any; recovered: boolean } {
-        try {
-            return { config: JSON.parse(data), recovered: false };
-        } catch (error) {
-            const objectEnd = this.findFirstJsonObjectEnd(data);
-            if (objectEnd < 0) {
-                throw error;
-            }
-
-            return {
-                config: JSON.parse(data.slice(0, objectEnd + 1)),
-                recovered: true
-            };
-        }
-    }
-
-    private findFirstJsonObjectEnd(data: string): number {
-        let depth = 0;
-        let inString = false;
-        let escaped = false;
-
-        for (let i = 0; i < data.length; i++) {
-            const char = data[i];
-
-            if (inString) {
-                if (escaped) {
-                    escaped = false;
-                } else if (char === '\\') {
-                    escaped = true;
-                } else if (char === '"') {
-                    inString = false;
-                }
-                continue;
-            }
-
-            if (char === '"') {
-                inString = true;
-                continue;
-            }
-
-            if (char === '{') {
-                depth++;
-            } else if (char === '}') {
-                depth--;
-                if (depth === 0) {
-                    return i;
-                }
-            }
-        }
-
-        return -1;
-    }
-
-    public async saveConfig() {
-        const tempPath = `${this.configPath}.${process.pid}.${Date.now()}.tmp`;
-        try {
-            this.hasAuthState = this.hasAuthState || await this.hasCredentialsFile();
-            const config = {
-                allowList: this.allowList,
-                blockList: this.blockList,
-                ignoredNumbers: this.ignoredNumbers,
+            this.hasAuthState = Boolean(config.hasAuthState);
+            this.openaiKey = config.openaiKey || '';
+            this.visionModel = config.visionModel || 'gpt-4o';
+
+            if (recovered) {
+                await this.saveConfig();
+            }
+        } catch {
+            // File not found is fine
+        }
+    }
+
+    private parseConfig(data: string): { config: any; recovered: boolean } {
+        try {
+            return { config: JSON.parse(data), recovered: false };
+        } catch (error) {
+            const objectEnd = this.findFirstJsonObjectEnd(data);
+            if (objectEnd < 0) {
+                throw error;
+            }
+
+            return {
+                config: JSON.parse(data.slice(0, objectEnd + 1)),
+                recovered: true
+            };
+        }
+    }
+
+    private findFirstJsonObjectEnd(data: string): number {
+        let depth = 0;
+        let inString = false;
+        let escaped = false;
+
+        for (let i = 0; i < data.length; i++) {
+            const char = data[i];
+
+            if (inString) {
+                if (escaped) {
+                    escaped = false;
+                } else if (char === '\\') {
+                    escaped = true;
+                } else if (char === '"') {
+                    inString = false;
+                }
+                continue;
+            }
+
+            if (char === '"') {
+                inString = true;
+                continue;
+            }
+
+            if (char === '{') {
+                depth++;
+            } else if (char === '}') {
+                depth--;
+                if (depth === 0) {
+                    return i;
+                }
+            }
+        }
+
+        return -1;
+    }
+
+    public async saveConfig() {
+        const tempPath = `${this.configPath}.${process.pid}.${Date.now()}.tmp`;
+        try {
+            this.hasAuthState = this.hasAuthState || await this.hasCredentialsFile();
+            const config = {
+                allowList: this.allowList,
+                blockList: this.blockList,
+                ignoredNumbers: this.ignoredNumbers,
                 status: this.status,
                 hasAuthState: this.hasAuthState,
-                openaiKey: this.openaiKey,
-                visionModel: this.visionModel
-            };
-            await mkdir(this.baseDir, { recursive: true });
-            await writeFile(tempPath, JSON.stringify(config, null, 2));
-            await rename(tempPath, this.configPath);
-        } catch (error) {
-            await rm(tempPath, { force: true }).catch(() => {});
-            console.error('Failed to save config:', error);
-        }
-    }
+                openaiKey: this.openaiKey,
+                visionModel: this.visionModel
+            };
+            await mkdir(this.baseDir, { recursive: true });
+            await writeFile(tempPath, JSON.stringify(config, null, 2));
+            await rename(tempPath, this.configPath);
+        } catch (error) {
+            await rm(tempPath, { force: true }).catch(() => {});
+            console.error('Failed to save config:', error);
+        }
+    }
 
     getAllowList(): Contact[] {
         return this.allowList;
@@ -275,10 +288,10 @@ export class SessionManager {
         }
     }
 
-    public async isRegistered(): Promise<boolean> {
-        await this.syncAuthStateFromDisk();
-        return this.hasAuthState;
-    }
+    public async isRegistered(): Promise<boolean> {
+        await this.syncAuthStateFromDisk();
+        return this.hasAuthState;
+    }
 
     async markAuthStateAvailable() {
         if (!this.hasAuthState) {
@@ -292,27 +305,27 @@ export class SessionManager {
         return await useMultiFileAuthState(this.authStateDir);
     }
 
-    private async syncAuthStateFromDisk() {
-        const nextHasAuthState = await this.hasCredentialsFile();
-        const nextStatus = nextHasAuthState || this.status !== 'connected'
-            ? this.status
-            : 'disconnected';
-
-        if (nextHasAuthState !== this.hasAuthState || nextStatus !== this.status) {
-            this.hasAuthState = nextHasAuthState;
-            this.status = nextStatus;
-            await this.saveConfig();
-        }
-    }
-
-    private async hasCredentialsFile(): Promise<boolean> {
-        try {
-            await readFile(join(this.authStateDir, 'creds.json'));
-            return true;
-        } catch {
-            return false;
-        }
-    }
+    private async syncAuthStateFromDisk() {
+        const nextHasAuthState = await this.hasCredentialsFile();
+        const nextStatus = nextHasAuthState || this.status !== 'connected'
+            ? this.status
+            : 'disconnected';
+
+        if (nextHasAuthState !== this.hasAuthState || nextStatus !== this.status) {
+            this.hasAuthState = nextHasAuthState;
+            this.status = nextStatus;
+            await this.saveConfig();
+        }
+    }
+
+    private async hasCredentialsFile(): Promise<boolean> {
+        try {
+            await readFile(join(this.authStateDir, 'creds.json'));
+            return true;
+        } catch {
+            return false;
+        }
+    }
 
     async deleteAuthState() {
         try {

package/src/services/whatsapp-pi.logger.ts

@@ -1,27 +1,48 @@
+import { appendFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
 export class WhatsAppPiLogger {
-    constructor(private verbose = false) {}
+    private logFile: string;
+
+    constructor(private verbose = false) {
+        const logDir = join(homedir(), '.pi', 'whatsapp-pi');
+        try { mkdirSync(logDir, { recursive: true }); } catch {}
+        this.logFile = join(logDir, 'whatsapp-pi.log');
+    }
 
     setVerbose(verbose: boolean) {
         this.verbose = verbose;
     }
 
+    private writeToFile(level: string, message: string, args: unknown[]) {
+        const timestamp = new Date().toISOString();
+        const extra = args.length ? ' ' + args.map(a => String(a)).join(' ') : '';
+        const line = `[${timestamp}] [${level}] ${message}${extra}\n`;
+        try { appendFileSync(this.logFile, line); } catch {}
+    }
+
     info(message: string, ...args: unknown[]) {
         console.log(message, ...args);
+        this.writeToFile('INFO', message, args);
     }
 
     log(message: string, ...args: unknown[]) {
+        this.writeToFile('LOG', message, args);
         if (this.verbose) {
             console.log(message, ...args);
         }
     }
 
     warn(message: string, ...args: unknown[]) {
+        this.writeToFile('WARN', message, args);
         if (this.verbose) {
             console.warn(message, ...args);
         }
     }
 
     error(message: string, ...args: unknown[]) {
+        this.writeToFile('ERROR', message, args);
         if (this.verbose) {
             console.error(message, ...args);
         }

package/src/services/whatsapp.service.ts

@@ -3,12 +3,20 @@ import {
     DisconnectReason,
     fetchLatestBaileysVersion,
     makeCacheableSignalKeyStore
-} from '@whiskeysockets/baileys';
+} from 'baileys';
 import P from 'pino';
 import { SessionManager } from './session.manager.js';
 import { IncomingMessage, SessionStatus } from '../models/whatsapp.types.js';
 import { MessageSender } from './message.sender.js';
 import { installBaileysConsoleFilter } from './baileys-console-filter.js';
+import { appendFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const LOG_FILE = join(homedir(), '.pi', 'whatsapp-pi', 'whatsapp-pi.log');
+function fileLog(msg: string) {
+    try { appendFileSync(LOG_FILE, `[${new Date().toISOString()}] [WhatsApp-Pi] ${msg}\n`); } catch {}
+}
 
 export interface WhatsAppStartOptions {
     allowPairingOnAuthFailure?: boolean;
@@ -28,6 +36,7 @@ interface IncomingMessageKey {
     id?: string;
     remoteJid?: string;
     fromMe?: boolean;
+    participant?: string;
 }
 
 interface IncomingMessageContent {
@@ -58,6 +67,8 @@ interface WhatsAppSocketLike {
     sendMessage(jid: string, content: { text: string }): Promise<{ key?: { id?: string } } | undefined>;
     sendPresenceUpdate(presence: 'composing' | 'recording' | 'paused', jid: string): Promise<void>;
     readMessages(messages: Array<{ remoteJid: string; id: string; fromMe: boolean }>): Promise<void>;
+    groupMetadata(jid: string): Promise<{ id: string; subject: string; participants: Array<{ id: string }> }>;
+    groupFetchAllParticipating(): Promise<Record<string, { id: string; subject: string; participants: Array<{ id: string }> }>>;
 }
 
 interface LastDisconnectLike {
@@ -89,12 +100,22 @@ export class WhatsAppService {
     private onMessage?: (m: MessagesUpsertEvent) => void;
     private onStatusUpdate?: (status: string) => void;
     private lastRemoteJid: string | null = null;
+    private boundGroupJid: string | null = null;
+    private groupMetadataCache: Map<string, { id: string; subject: string; participants: Array<{ id: string }> }> = new Map();
 
     constructor(sessionManager: SessionManager) {
         this.sessionManager = sessionManager;
         this.messageSender = new MessageSender(this);
     }
 
+    public setGroupBinding(groupJid: string) {
+        this.boundGroupJid = groupJid;
+    }
+
+    public getBoundGroupJid(): string | null {
+        return this.boundGroupJid;
+    }
+
     public getStatus(): SessionStatus {
         return this.sessionManager.getStatus();
     }
@@ -228,6 +249,8 @@ export class WhatsAppService {
 
         const logger = P({ level: this.verboseMode ? 'trace' : 'silent' });
 
+        const groupMetadataCache = this.groupMetadataCache;
+
         const socket = makeWASocket({
             version,
             printQRInTerminal: false,
@@ -236,7 +259,10 @@ export class WhatsAppService {
                 keys: makeCacheableSignalKeyStore(state.keys, logger)
             },
             syncFullHistory: false,
-            logger
+            logger,
+            cachedGroupMetadata: async (jid: string) => {
+                return groupMetadataCache.get(jid) as any;
+            }
         }) as WhatsAppSocketLike;
 
         return socket;
@@ -448,25 +474,41 @@ export class WhatsAppService {
         if (this.isPiGeneratedMessage(text)) return;
 
         const remoteJid = message.key.remoteJid;
-        if (remoteJid.endsWith('@g.us')) return;
+        const isGroup = remoteJid.endsWith('@g.us');
 
-        const senderJid = this.normalizeContactNumber(remoteJid.split('@')[0]);
+        if (this.boundGroupJid) {
+            // Group-only mode: reject everything except the bound group
+            if (remoteJid !== this.boundGroupJid) return;
+        }
+
+        // Eagerly cache group metadata on incoming messages so it's
+        // available for sender-key encryption when we reply
+        if (isGroup) {
+            void this.prepareGroupSession(remoteJid);
+        }
+
+        const senderJid = isGroup
+            ? remoteJid
+            : this.normalizeContactNumber(remoteJid.split('@')[0]);
         void this.recordIncomingMessage(message, remoteJid, text);
 
-        if (this.sessionManager.isBlocked(senderJid)) {
-            if (this.isVerbose()) {
-                console.log(`Ignoring message from ${senderJid} (explicitly blocked)`);
+        // In group-only mode, skip allow/block checks — the binding is the authorization
+        if (!this.boundGroupJid) {
+            if (this.sessionManager.isBlocked(senderJid)) {
+                if (this.isVerbose()) {
+                    console.log(`Ignoring message from ${senderJid} (explicitly blocked)`);
+                }
+                return;
             }
-            return;
-        }
 
-        if (!this.sessionManager.isAllowed(senderJid)) {
-            if (this.isVerbose()) {
-                console.log(`Ignoring message from ${senderJid} (not in allow list)`);
+            if (!this.sessionManager.isAllowed(senderJid)) {
+                if (this.isVerbose()) {
+                    console.log(`Ignoring message from ${senderJid} (not in allow list)`);
+                }
+                const pushName = message.pushName || undefined;
+                await this.sessionManager.trackIgnoredNumber(senderJid, pushName);
+                return;
             }
-            const pushName = message.pushName || undefined;
-            await this.sessionManager.trackIgnoredNumber(senderJid, pushName);
-            return;
         }
 
         this.lastRemoteJid = remoteJid;
@@ -497,14 +539,36 @@ export class WhatsAppService {
         return this.socket;
     }
 
-    async sendMessage(jid: string, text: string, origin: 'agent' | 'menu' = 'agent') {
+    /**
+     * Pre-loads group metadata into the cache for Baileys' cachedGroupMetadata.
+     * This ensures Baileys can resolve group participants for Signal
+     * sender-key encryption, preventing "No sessions" errors.
+     */
+    public async prepareGroupSession(jid: string): Promise<void> {
+        if (!jid.endsWith('@g.us')) return;
+        if (this.groupMetadataCache.has(jid)) {
+            fileLog(`Group metadata cache HIT for ${jid}`);
+            return;
+        }
+        const socket = this.getActiveSocket();
+        if (!socket) return;
+        try {
+            fileLog(`Fetching group metadata for ${jid}...`);
+            const metadata = await socket.groupMetadata(jid);
+            this.groupMetadataCache.set(jid, metadata);
+            fileLog(`Cached group metadata for ${jid} (${metadata.participants?.length ?? 0} participants)`);
+        } catch (error) {
+            fileLog(`FAILED to fetch group metadata for ${jid}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+
+    async sendMessage(jid: string, text: string) {
         // Ensure we show the typing indicator before sending
         await this.sendPresence(jid, 'composing');
 
         const result = await this.messageSender.send({
             recipientJid: jid,
-            text,
-            origin
+            text: text
         });
 
         // After sending, we can stop the typing indicator
@@ -519,7 +583,35 @@ export class WhatsAppService {
 
     async sendMenuMessage(jid: string, text: string) {
         const normalizedJid = this.normalizeRecipientJid(jid);
-        return this.sendMessage(normalizedJid, text, 'menu');
+        const socket = this.getActiveSocket();
+
+        if (!socket) {
+            return {
+                success: false,
+                error: 'WhatsApp is not connected',
+                attempts: 0
+            };
+        }
+
+        try {
+            await this.sendPresence(normalizedJid, 'composing');
+            const response = await socket.sendMessage(normalizedJid, { text });
+            await this.sendPresence(normalizedJid, 'paused');
+
+            return {
+                success: true,
+                messageId: response?.key?.id,
+                attempts: 1
+            };
+        } catch (error: unknown) {
+            await this.sendPresence(normalizedJid, 'paused');
+            console.error(`Failed to send menu message to ${normalizedJid}:`, error);
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Unknown error',
+                attempts: 1
+            };
+        }
     }
 
     async sendPresence(jid: string, presence: 'composing' | 'recording' | 'paused') {

package/src/ui/menu.handler.ts

@@ -325,7 +325,8 @@ export class MenuHandler {
         await this.sendPromptedMenuMessage(ctx, {
             displayName: this.getConversationDisplayName(conversation),
             senderNumber: conversation.senderNumber,
-            senderName: conversation.senderName
+            senderName: conversation.senderName,
+            appendPiSuffix: false
         });
     }
 
@@ -333,7 +334,8 @@ export class MenuHandler {
         await this.sendPromptedMenuMessage(ctx, {
             displayName: this.formatAllowedContactOption(contact),
             senderNumber: contact.number,
-            senderName: contact.name
+            senderName: contact.name,
+            appendPiSuffix: true
         });
     }
 
@@ -343,9 +345,10 @@ export class MenuHandler {
             displayName: string;
             senderNumber: string;
             senderName?: string;
+            appendPiSuffix: boolean;
         }
     ) {
-        const { displayName, senderNumber, senderName } = options;
+        const { displayName, senderNumber, senderName, appendPiSuffix } = options;
         for (let attempt = 0; attempt < 2; attempt++) {
             const inputText = (await ctx.ui.input(`Send a message to ${displayName}:`))?.trim() || '';
 
@@ -354,13 +357,14 @@ export class MenuHandler {
                 continue;
             }
 
-            const result = await this.whatsappService.sendMenuMessage(this.toJid(senderNumber), inputText);
+            const messageText = appendPiSuffix ? `${inputText} π` : inputText;
+            const result = await this.whatsappService.sendMenuMessage(this.toJid(senderNumber), messageText);
             if (result.success) {
                 await this.recentsService.recordMessage({
                     messageId: result.messageId ?? `${Date.now()}`,
                     senderNumber,
                     senderName,
-                    text: inputText,
+                    text: messageText,
                     direction: 'outgoing',
                     timestamp: Date.now()
                 });
@@ -453,7 +457,9 @@ export class MenuHandler {
     }
 
     private formatAllowedContactOption(contact: Contact): string {
-        return contact.name ? `${contact.name} (${contact.number})` : contact.number;
+        const isGroup = SessionManager.isGroupJid(contact.number);
+        const prefix = isGroup ? '[Group] ' : '';
+        return contact.name ? `${prefix}${contact.name} (${contact.number})` : `${prefix}${contact.number}`;
     }
 
     private sortContactsAlphabetically(contacts: Contact[]): Contact[] {
@@ -510,7 +516,9 @@ export class MenuHandler {
     private getConversationDisplayName(conversation: RecentConversationSummary): string {
         const allowedContact = this.sessionManager.getAllowedContact(conversation.senderNumber);
         const displayName = allowedContact?.name || conversation.senderName;
-        return displayName ? `${displayName} (${conversation.senderNumber})` : conversation.senderNumber;
+        const isGroup = SessionManager.isGroupJid(conversation.senderNumber);
+        const prefix = isGroup ? '[Group] ' : '';
+        return displayName ? `${prefix}${displayName} (${conversation.senderNumber})` : `${prefix}${conversation.senderNumber}`;
     }
 
     private formatDateTime(timestamp: number): string {

package/src/ui/message-detail.view.ts

@@ -29,10 +29,10 @@ export class MessageDetailView {
         ) {
             this.props.onClose();
         }
-    }
-
-    render(width: number): string[] {
-        const bodyText = this.props.text.length > 0 ? this.props.text : '[No readable text available]';
+    }
+
+    render(width: number): string[] {
+        const bodyText = this.props.text.length > 0 ? this.props.text : '[No readable text available]';
 
         const availableWidth = Math.max(20, width - 4);
         const rawHeaderLines = [

package/whatsapp-pi.ts

@@ -30,6 +30,12 @@ export default function (pi: ExtensionAPI) {
         default: false
     });
 
+    pi.registerFlag("whatsapp-group", {
+        description: "Bind this agent to a specific WhatsApp group JID (e.g. 120363012345@g.us). When set, only messages from this group are processed.",
+        type: "string",
+        default: ""
+    });
+
     const sessionManager = new SessionManager();
     const whatsappService = new WhatsAppService(sessionManager);
     const recentsService = new RecentsService(sessionManager);
@@ -77,6 +83,15 @@ export default function (pi: ExtensionAPI) {
         whatsappService.setStatusCallback((status) => {
             ctx.ui.setStatus('whatsapp', status);
         });
+
+        // Set up group binding if configured
+        const boundGroupJid = (pi.getFlag("whatsapp-group") as string) || "";
+        if (boundGroupJid) {
+            whatsappService.setGroupBinding(boundGroupJid);
+            sessionManager.setGroupJidForAuth(boundGroupJid);
+            logger.log(`[WhatsApp-Pi] Group-only mode: bound to ${boundGroupJid}`);
+        }
+
         await sessionManager.ensureInitialized();
         await recentsService.ensureInitialized();
         installGracefulShutdownHandlers();
@@ -87,9 +102,13 @@ export default function (pi: ExtensionAPI) {
             }
         };
         whatsappService.setIncomingMessageRecorder(async (message) => {
+            const isGroup = message.remoteJid.endsWith('@g.us');
+            const senderNumber = isGroup
+                ? message.remoteJid
+                : `+${message.remoteJid.split('@')[0]}`;
             await recentsService.recordMessage({
                 messageId: message.id,
-                senderNumber: `+${message.remoteJid.split('@')[0]}`,
+                senderNumber,
                 senderName: message.pushName,
                 text: message.text || '',
                 direction: 'incoming',
@@ -163,21 +182,29 @@ export default function (pi: ExtensionAPI) {
         }
     });
 
+    // Track whether send_wa_message tool already sent a reply this turn
+    let toolSentToJid: string | null = null;
+
     // Handle incoming messages by injecting them as user prompts
     whatsappService.setMessageCallback(async (m) => {
         const msg = m.messages?.[0];
         if (!msg?.message) return;
 
-        const sender = msg.key.remoteJid?.split('@')[0] || "unknown";
+        const remoteJid = msg.key.remoteJid;
+        const isGroup = remoteJid?.endsWith('@g.us') || false;
+        const participant = isGroup ? (msg.key.participant?.split('@')[0] || 'unknown') : (remoteJid?.split('@')[0] || 'unknown');
+        const sender = remoteJid?.split('@')[0] || "unknown";
         const pushName = msg.pushName || "WhatsApp User";
 
         // Mark as read and start typing indicator immediately
-        const remoteJid = msg.key.remoteJid;
         if (remoteJid && msg.key.id) {
             whatsappService.markRead(remoteJid, msg.key.id, msg.key.fromMe);
             whatsappService.sendPresence(remoteJid, 'composing');
         }
 
+        // Reset tool-sent flag for this new incoming message
+        toolSentToJid = null;
+
         const resolved = extractIncomingText(msg.message);
         if (resolved.kind === 'system') {
             logger.log(`[WhatsApp-Pi] ${pushName} (${sender}): ${resolved.text}`);
@@ -186,16 +213,21 @@ export default function (pi: ExtensionAPI) {
 
         const { text, imageBuffer, imageMimeType } = await incomingMediaService.process(resolved, pushName);
 
-        logger.log(`[WhatsApp-Pi] ${pushName} (${sender}): ${text}`);
+        // Format message header with group context when applicable
+        const messageHeader = isGroup
+            ? `Message from ${pushName} (${participant}) in group ${remoteJid}:`
+            : `Message from ${pushName} (${sender}):`;
+
+        logger.log(`[WhatsApp-Pi] ${messageHeader} ${text}`);
 
         // Use a standard delivery for ALL messages to ensure TUI consistency
         if (imageBuffer && imageMimeType) {
             pi.sendUserMessage([
-                { type: "text", text: `Message from ${pushName} (${sender}): ${text}` },
+                { type: "text", text: `${messageHeader} ${text}` },
                 { type: "image", data: imageBuffer.toString('base64'), mimeType: imageMimeType }
             ], { deliverAs: "followUp" });
         } else {
-            pi.sendUserMessage(`Message from ${pushName} (${sender}): ${text}`, { deliverAs: "followUp" });
+            pi.sendUserMessage(`${messageHeader} ${text}`, { deliverAs: "followUp" });
         }
 
         // Handle commands
@@ -225,13 +257,24 @@ export default function (pi: ExtensionAPI) {
     pi.registerTool({
         name: "send_wa_message",
         label: "Send WhatsApp Message",
-        description: "Send a WhatsApp message to a contact identified by their JID (e.g. 5511999998888@s.whatsapp.net). Returns a JSON result with success status and messageId or error.",
-        promptSnippet: "send_wa_message(jid, message) - Send a WhatsApp message to a contact by JID",
+        description: "Send a WhatsApp message to a contact or group. The 'jid' parameter is the WhatsApp JID (e.g. 5511999998888@s.whatsapp.net for contacts, or 120363012345@g.us for groups). If omitted, replies to the last conversation.",
+        promptSnippet: "send_wa_message(jid, message) - Send a WhatsApp message. jid is required (e.g. 5511999998888@s.whatsapp.net or 120363012345@g.us). IMPORTANT: After calling this tool, do NOT generate any follow-up text or confirmation — the message is already delivered to WhatsApp. Your entire response to the user should be sent ONLY through this tool, not repeated in chat.",
         parameters: Type.Object({
-            jid: Type.String({ minLength: 1, description: "WhatsApp JID of the recipient, e.g. 5511999998888@s.whatsapp.net" }),
+            jid: Type.Optional(Type.String({ description: "WhatsApp JID of the recipient" })),
+            recipient_jid: Type.Optional(Type.String({ description: "Alternative name for jid" })),
             message: Type.String({ minLength: 1, description: "Plain-text message content to send" })
         }),
         async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            // Resolve JID: jid > recipient_jid > lastRemoteJid
+            const resolvedJid = params.jid || params.recipient_jid || whatsappService.getLastRemoteJid();
+            if (!resolvedJid) {
+                return {
+                    isError: true,
+                    details: undefined,
+                    content: [{ type: "text" as const, text: JSON.stringify({ success: false, error: "No JID provided and no active conversation to reply to", attempts: 0 }) }]
+                };
+            }
+
             if (whatsappService.getStatus() !== 'connected') {
                 return {
                     isError: true,
@@ -247,31 +290,35 @@ export default function (pi: ExtensionAPI) {
 
             console.log([
                 '[WhatsApp-Pi] Outgoing WhatsApp message',
-                `  To: ${params.jid}`,
+                `  To: ${resolvedJid}`,
                 '  Message:',
                 formattedMessage
             ].join('\n'));
 
-            const result = await whatsappService.sendMessage(params.jid, params.message);
+            const result = await whatsappService.sendMessage(resolvedJid, params.message);
 
             if (result.success) {
+                // Mark that tool already sent to this JID — prevents message_end from re-sending
+                toolSentToJid = resolvedJid;
+                const isGroupJid = resolvedJid.endsWith('@g.us');
+                const senderNumber = isGroupJid ? resolvedJid : `+${resolvedJid.split('@')[0]}`;
                 await recentsService.recordMessage({
                     messageId: result.messageId!,
-                    senderNumber: `+${params.jid.split('@')[0]}`,
+                    senderNumber,
                     text: params.message,
                     direction: 'outgoing',
                     timestamp: Date.now()
                 });
                 console.log([
                     '[WhatsApp-Pi] Outgoing WhatsApp message result',
-                    `  To: ${params.jid}`,
+                    `  To: ${resolvedJid}`,
                     '  Status: sent',
                     `  MessageId: ${result.messageId ?? 'unknown'}`
                 ].join('\n'));
             } else {
                 console.log([
                     '[WhatsApp-Pi] Outgoing WhatsApp message result',
-                    `  To: ${params.jid}`,
+                    `  To: ${resolvedJid}`,
                     '  Status: failed',
                     `  Error: ${result.error ?? 'unknown error'}`
                 ].join('\n'));
@@ -285,6 +332,9 @@ export default function (pi: ExtensionAPI) {
         }
     });
 
+    // Suppress automatic message_end reply when tool already sent
+    // This is checked by the message_end handler below
+
     // Register commands
     pi.registerCommand("whatsapp", {
         description: "Manage WhatsApp integration",
@@ -318,6 +368,12 @@ export default function (pi: ExtensionAPI) {
             const lastJid = whatsappService.getLastRemoteJid();
             const text = message.content.filter(c => c.type === "text").map(c => c.text).join("\n");
 
+            // Skip if send_wa_message tool already sent a reply to this JID
+            if (toolSentToJid === lastJid) {
+                toolSentToJid = null;
+                return;
+            }
+
             if (lastJid && text) {
                 try {
                     const result = await whatsappService.sendMessage(lastJid, text);