whatsapp-pi 1.0.65 → 1.0.67

package/README.md

@@ -138,7 +138,7 @@ The extension registers the following tools that the Pi agent can call:
 | `get_wa_conversation_history` | read-only | Get the most recent messages with a given `senderNumber` (accepts `+E164`, raw digits, or a JID). Supports `limit`. |
 | `check_wa_new_messages` | read-only | List conversations whose most recent message is incoming (i.e. waiting for a reply). Supports `sinceTimestamp` (ms epoch). |
 
-The three read-only tools query the local recents store at `~/.pi/whatsapp-pi/recents/recents.json`. They never touch the network and do not mark messages as read.
+The three read-only tools query the local recents store at `~/.pi/agent/extension/whatsapp-pi/recents/recents.json`. They never touch the network and do not mark messages as read.
 
 ## WhatsApp Numbers and JIDs
 
@@ -209,7 +209,7 @@ npm test
 - **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. The group must also be present in Allowed Groups.
 - **Allowed Group Reaction Mode**: Each allowed group can be set to Active or Passive. Passive mode only replies when the bot is directly mentioned with @.
-- **Recents Store**: Recent conversations and message history are persisted in `~/.pi/whatsapp-pi/recents/recents.json`.
+- **Recents Store**: Recent conversations and message history are persisted in `~/.pi/agent/extension/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 PDFs are saved under `./.pi-data/whatsapp/documents/` with local text preview when available.
 - **Session Handling**: Saved state, allow list, and startup reconnects are restored automatically when available.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whatsapp-pi",
-  "version": "1.0.65",
+  "version": "1.0.67",
   "type": "module",
   "description": "WhatsApp integration extension for Pi",
   "main": "whatsapp-pi.ts",

package/src/services/audio.service.ts

@@ -5,13 +5,16 @@ import { writeFile, mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
+import { createStoragePaths } from './storage-path.js';
 import { t } from '../i18n.js';
 
 const execAsync = promisify(exec);
 
 export class AudioService {
-    private readonly mediaDir = join(homedir(), '.pi', 'whatsapp-medias');
-    private readonly whisperPath = process.platform === 'win32' ? 'python -m whisper' : join(homedir(), '.local', 'bin', 'whisper');
+    private readonly mediaDir = createStoragePaths().mediaDir;
+    private readonly whisperCommands = process.platform === 'win32'
+        ? ['whisper', 'py -m whisper', 'python -m whisper']
+        : [join(homedir(), '.local', 'bin', 'whisper'), 'whisper', 'python3 -m whisper', 'python -m whisper'];
 
     constructor() {
         if (!existsSync(this.mediaDir)) {
@@ -35,9 +38,7 @@ export class AudioService {
 
             // Transcribe using Whisper
             // Using small model for better accuracy
-            const command = `${this.whisperPath} "${inputPath}" --model small --language pt --output_format txt --output_dir "${this.mediaDir}" --fp16 False`;
-            
-            await execAsync(command);
+            await this.runWhisper(inputPath);
 
             const txtPath = join(this.mediaDir, `${filename}.txt`);
             if (existsSync(txtPath)) {
@@ -52,4 +53,38 @@ export class AudioService {
             return t('audio.transcriptionErrorResult', { error: error instanceof Error ? error.message : String(error) });
         }
     }
+
+    private async runWhisper(inputPath: string): Promise<void> {
+        const commandArgs = `"${inputPath}" --model small --language pt --output_format txt --output_dir "${this.mediaDir}" --fp16 False`;
+        let lastError: unknown;
+
+        for (const whisperCommand of this.whisperCommands) {
+            const command = `${whisperCommand} ${commandArgs}`;
+
+            try {
+                await execAsync(command);
+                return;
+            } catch (error) {
+                lastError = error;
+                if (!this.isMissingWhisperCommand(error)) {
+                    throw error;
+                }
+            }
+        }
+
+        throw lastError instanceof Error ? lastError : new Error(String(lastError));
+    }
+
+    private isMissingWhisperCommand(error: unknown): boolean {
+        if (!(error instanceof Error)) {
+            return false;
+        }
+
+        const anyError = error as Error & { code?: number | string; stderr?: string };
+        const message = `${anyError.message}\n${anyError.stderr ?? ''}`;
+
+        return anyError.code === 127
+            || anyError.code === 9009
+            || /not found|not recognized/i.test(message);
+    }
 }

package/src/services/message.sender.ts

@@ -2,10 +2,9 @@ import { WhatsAppService } from './whatsapp.service.js';
 import { MessageRequest, MessageResult, WhatsAppError } from '../models/whatsapp.types.js';
 import { t } from '../i18n.js';
 import { appendFileSync } from 'fs';
-import { join } from 'path';
-import { homedir } from 'os';
+import { createStoragePaths } from './storage-path.js';
 
-const LOG_FILE = join(homedir(), '.pi', 'whatsapp-pi', 'whatsapp-pi.log');
+const LOG_FILE = createStoragePaths().logPath;
 function fileLog(msg: string) {
     try { appendFileSync(LOG_FILE, `[${new Date().toISOString()}] [MessageSender] ${msg}\n`); } catch {
         // File logging is best-effort.

package/src/services/recents.service.ts

@@ -1,6 +1,5 @@
-import { homedir } from 'os';
-import { join } from 'path';
-import { mkdir, readFile, writeFile } from 'fs/promises';
+import { readFile, writeFile } from 'fs/promises';
+import { createStoragePaths, ensureStorageDirectories as ensureStorageRoots, migrateLegacyStorage } from './storage-path.js';
 import type {
     MessageDirection,
     RecentConversationMessage,
@@ -19,9 +18,9 @@ export interface RecentsMessageInput {
 }
 
 export class RecentsService {
-    private readonly baseDir = join(homedir(), '.pi', 'whatsapp-pi');
-    private readonly dataDir = join(this.baseDir, 'recents');
-    private readonly storePath = join(this.dataDir, 'recents.json');
+    private readonly storagePaths = createStoragePaths();
+    private readonly dataDir = this.storagePaths.recentsDir;
+    private readonly storePath = this.storagePaths.recentsPath;
     private store: RecentsStore = {
         conversations: [],
         messagesBySender: {},
@@ -31,7 +30,16 @@ export class RecentsService {
     constructor(private readonly sessionManager: SessionManager) {}
 
     async ensureInitialized() {
-        await mkdir(this.dataDir, { recursive: true });
+        await ensureStorageRoots({
+            root: this.storagePaths.root,
+            authStateDir: this.storagePaths.authStateDir,
+            recentsDir: this.dataDir,
+            logDir: this.storagePaths.logDir
+        });
+        await migrateLegacyStorage({
+            root: this.storagePaths.root,
+            legacyRoot: this.storagePaths.legacyRoot
+        });
         await this.loadStore();
     }
 
@@ -125,12 +133,12 @@ export class RecentsService {
         });
     }
 
-    private stripSpecialCharacters(text: string): string {
-        return text
-            .replace(/\p{Extended_Pictographic}|\p{Emoji_Modifier}|\p{Regional_Indicator}|\u200D|\uFE0F/gu, '')
-            .replace(/\s+/g, ' ')
-            .trim();
-    }
+    private stripSpecialCharacters(text: string): string {
+        return text
+            .replace(/\p{Extended_Pictographic}|\p{Emoji_Modifier}|\p{Regional_Indicator}|\u200D|\uFE0F/gu, '')
+            .replace(/\s+/g, ' ')
+            .trim();
+    }
 
     private buildPreview(text: string): string {
         const normalized = this.stripSpecialCharacters(text);

package/src/services/session.manager.ts

@@ -1,59 +1,77 @@
 import { useMultiFileAuthState } from 'baileys';
 import { basename, join } from 'path';
 import { readFile, writeFile, mkdir, rm, rename, readdir } from 'fs/promises';
-import { homedir } from 'os';
-import { SessionStatus } from '../models/whatsapp.types.js';
-import { t } from '../i18n.js';
-
-export interface Contact {
-    number: string;
-    name?: string;
-    sendNumber?: 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 allowedGroups: Contact[] = [];
-    private ignoredNumbers: Contact[] = [];
+import { SessionStatus } from '../models/whatsapp.types.js';
+import { t } from '../i18n.js';
+import {
+    getDefaultLegacyStorageRoot,
+    getDefaultStorageRoot,
+    createStoragePaths,
+    ensureStorageDirectories as ensureStorageRoots,
+    migrateLegacyStorage,
+    type StoragePaths
+} from './storage-path.js';
+
+export interface Contact {
+    number: string;
+    name?: string;
+    sendNumber?: string;
+}
+
+export class SessionManager {
+    private readonly storagePaths: StoragePaths;
+    private authStateDir: string;
+    private readonly configPath: string;
+
+    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.storagePaths.root, `auth-${sanitized}`);
+    }
+
+    private status: SessionStatus = 'logged-out';
+    private allowList: Contact[] = [];
+    private allowedGroups: Contact[] = [];
+    private ignoredNumbers: Contact[] = [];
     private hasAuthState = false;
     private openaiKey: string = '';
     private visionModel: string = 'gpt-4o';
     private operatorJid: string = '';
     private configLoaded = false;
-
-    constructor(baseDir = join(homedir(), '.pi', 'whatsapp-pi')) {
-        this.baseDir = baseDir;
-        this.authStateDir = join(this.baseDir, 'auth');
-        this.configPath = join(this.baseDir, 'config.json');
-    }
-
+
+    constructor(baseDir = getDefaultStorageRoot(), legacyBaseDir = baseDir === getDefaultStorageRoot() ? getDefaultLegacyStorageRoot() : baseDir) {
+        this.storagePaths = createStoragePaths(baseDir, legacyBaseDir);
+        this.authStateDir = this.storagePaths.authStateDir;
+        this.configPath = this.storagePaths.configPath;
+    }
+
     private async ensureStorageDirectories() {
-        await mkdir(this.baseDir, { recursive: true });
-        await mkdir(this.authStateDir, { recursive: true });
+        await ensureStorageRoots({
+            root: this.storagePaths.root,
+            authStateDir: this.authStateDir,
+            recentsDir: this.storagePaths.recentsDir,
+            logDir: this.storagePaths.logDir
+        });
+    }
+
+    private async migrateLegacyStorageIfNeeded() {
+        await migrateLegacyStorage({
+            root: this.storagePaths.root,
+            legacyRoot: this.storagePaths.legacyRoot
+        });
     }
 
     public async ensureInitialized() {
         try {
             await this.ensureStorageDirectories();
+            await this.migrateLegacyStorageIfNeeded();
             await this.cleanupStaleConfigTempFiles();
             if (!this.configLoaded) {
                 await this.loadConfig();
@@ -64,119 +82,119 @@ export class SessionManager {
             // 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 => {
-                if (typeof item === 'string') return { number: item };
-                if (item && typeof item === 'object') {
-                    let num = item.number;
-                    // Unroll nested objects if any
-                    while (num && typeof num === 'object' && num.number) {
-                        num = num.number;
-                    }
-                    if (typeof num === 'string') {
-                        const sendNumber = typeof item.sendNumber === 'string' ? item.sendNumber : undefined;
-                        return { number: num, name: item.name, sendNumber };
-                    }
-                }
-                return null;
-            };
-
-            const loadedAllowList = (config.allowList || []).map(cleanContact).filter(Boolean) as Contact[];
-            const loadedAllowedGroups = (config.allowedGroups || []).map(cleanContact).filter(Boolean) as Contact[];
-            const migratedGroups = loadedAllowList.filter(c => SessionManager.isGroupJid(c.number));
-            this.allowList = loadedAllowList.filter(c => !SessionManager.isGroupJid(c.number));
-            this.allowedGroups = this.mergeContacts(loadedAllowedGroups, migratedGroups);
-            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';
-            this.operatorJid = config.operatorJid || '';
-
-            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,
-                allowedGroups: this.allowedGroups,
-                ignoredNumbers: this.ignoredNumbers,
-                status: this.status,
-                hasAuthState: this.hasAuthState,
-                openaiKey: this.openaiKey,
-                visionModel: this.visionModel,
-                operatorJid: this.operatorJid
-            };
-            await mkdir(this.baseDir, { recursive: true });
-            const serialized = JSON.stringify(config, null, 2);
-            await writeFile(tempPath, serialized);
-            try {
+
+    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;
+                    // Unroll nested objects if any
+                    while (num && typeof num === 'object' && num.number) {
+                        num = num.number;
+                    }
+                    if (typeof num === 'string') {
+                        const sendNumber = typeof item.sendNumber === 'string' ? item.sendNumber : undefined;
+                        return { number: num, name: item.name, sendNumber };
+                    }
+                }
+                return null;
+            };
+
+            const loadedAllowList = (config.allowList || []).map(cleanContact).filter(Boolean) as Contact[];
+            const loadedAllowedGroups = (config.allowedGroups || []).map(cleanContact).filter(Boolean) as Contact[];
+            const migratedGroups = loadedAllowList.filter(c => SessionManager.isGroupJid(c.number));
+            this.allowList = loadedAllowList.filter(c => !SessionManager.isGroupJid(c.number));
+            this.allowedGroups = this.mergeContacts(loadedAllowedGroups, migratedGroups);
+            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';
+            this.operatorJid = config.operatorJid || '';
+
+            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,
+                allowedGroups: this.allowedGroups,
+                ignoredNumbers: this.ignoredNumbers,
+                status: this.status,
+                hasAuthState: this.hasAuthState,
+                openaiKey: this.openaiKey,
+                visionModel: this.visionModel,
+                operatorJid: this.operatorJid
+            };
+            await mkdir(this.storagePaths.root, { recursive: true });
+            const serialized = JSON.stringify(config, null, 2);
+            await writeFile(tempPath, serialized);
+            try {
                 await rename(tempPath, this.configPath);
             } catch {
                 // Windows EPERM: atomic rename failed (file locked). Fall back to direct write.
@@ -194,14 +212,14 @@ export class SessionManager {
         let files: string[];
 
         try {
-            files = await readdir(this.baseDir);
+            files = await readdir(this.storagePaths.root);
         } catch {
             return;
         }
 
         await Promise.all(files
             .filter(fileName => fileName.startsWith(`${configFileName}.`) && fileName.endsWith('.tmp'))
-            .map(fileName => this.removeConfigTempFile(join(this.baseDir, fileName))));
+            .map(fileName => this.removeConfigTempFile(join(this.storagePaths.root, fileName))));
     }
 
     private async removeConfigTempFile(tempPath: string) {
@@ -218,278 +236,278 @@ export class SessionManager {
     getAllowList(): Contact[] {
         return this.allowList;
     }
-
-    getAllowedContact(number: string): Contact | undefined {
-        return this.allowList.find(c => c.number === number);
-    }
-
-    getAllowedGroups(): Contact[] {
-        return this.allowedGroups;
-    }
-
-    getAllowedGroup(groupJid: string): Contact | undefined {
-        return this.allowedGroups.find(c => c.number === groupJid);
-    }
-
-    getIgnoredNumbers(): Contact[] {
-        return this.ignoredNumbers;
-    }
-
-    async removeIgnoredNumber(number: string) {
-        this.ignoredNumbers = this.ignoredNumbers.filter(c => c.number !== number);
-        await this.saveConfig();
-    }
-
-    async addNumber(number: any, name?: string) {
-        // Handle potential nested objects from legacy bugs
-        let cleanNumber = number;
-        while (cleanNumber && typeof cleanNumber === 'object' && cleanNumber.number) {
-            cleanNumber = cleanNumber.number;
-        }
-
-        if (typeof cleanNumber !== 'string') {
-            console.warn(t('session.manager.invalidNumber'), cleanNumber);
-            return;
-        }
-
-        const existing = this.allowList.find(c => c.number === cleanNumber);
-        if (!existing) {
-            if (SessionManager.isGroupJid(cleanNumber)) {
-                await this.addAllowedGroup(cleanNumber, name);
-                return;
-            }
-            this.allowList.push({ number: cleanNumber, name });
-            this.ignoredNumbers = this.ignoredNumbers.filter(c => c.number !== cleanNumber);
-            await this.saveConfig();
-            return;
-        }
-
-        if (name && !existing.name) {
-            existing.name = name;
-            await this.saveConfig();
-        }
-    }
-
-    async removeNumber(number: string) {
-        this.allowList = this.allowList.filter(c => c.number !== number);
-        await this.saveConfig();
-    }
-
-    async addAllowedGroup(groupJid: string, name?: string) {
-        if (!SessionManager.isGroupJid(groupJid)) {
-            console.warn(t('session.manager.invalidNumber'), groupJid);
-            return;
-        }
-
-        const existing = this.allowedGroups.find(c => c.number === groupJid);
-        if (!existing) {
-            this.allowedGroups.push({ number: groupJid, name });
-            this.ignoredNumbers = this.ignoredNumbers.filter(c => c.number !== groupJid);
-            await this.saveConfig();
-            return;
-        }
-
-        if (name && !existing.name) {
-            existing.name = name;
-            await this.saveConfig();
-        }
-    }
-
-    async removeAllowedGroup(groupJid: string) {
-        this.allowedGroups = this.allowedGroups.filter(c => c.number !== groupJid);
-        await this.saveConfig();
-    }
-
-    async setAllowedContactAlias(number: string, alias: string) {
-        const trimmedAlias = alias.trim();
-        if (!trimmedAlias) {
-            return;
-        }
-
-        const contact = this.getAllowedContact(number);
-        if (!contact) {
-            return;
-        }
-
-        contact.name = trimmedAlias;
-        await this.saveConfig();
-    }
-
-    async removeAllowedContactAlias(number: string) {
-        const contact = this.getAllowedContact(number);
-        if (!contact || !contact.name) {
-            return;
-        }
-
-        delete contact.name;
-        await this.saveConfig();
-    }
-
-    async setContactSendNumber(number: string, sendNumber: string) {
-        const contact = this.getAllowedContact(number);
-        if (!contact) return;
-        contact.sendNumber = sendNumber.trim();
-        await this.saveConfig();
-    }
-
-    async removeContactSendNumber(number: string) {
-        const contact = this.getAllowedContact(number);
-        if (!contact) return;
-        delete contact.sendNumber;
-        await this.saveConfig();
-    }
-
-    async setAllowedGroupAlias(groupJid: string, alias: string) {
-        const trimmedAlias = alias.trim();
-        if (!trimmedAlias) {
-            return;
-        }
-
-        const group = this.getAllowedGroup(groupJid);
-        if (!group) {
-            return;
-        }
-
-        group.name = trimmedAlias;
-        await this.saveConfig();
-    }
-
-    async removeAllowedGroupAlias(groupJid: string) {
-        const group = this.getAllowedGroup(groupJid);
-        if (!group || !group.name) {
-            return;
-        }
-
-        delete group.name;
-        await this.saveConfig();
-    }
-
-    isAllowed(number: string): boolean {
-        return this.allowList.some(c => c.number === number);
-    }
-
-    isAllowedGroup(groupJid: string): boolean {
-        return this.allowedGroups.some(c => c.number === groupJid);
-    }
-
-    isConversationAllowed(sender: string): boolean {
-        return SessionManager.isGroupJid(sender)
-            ? this.isAllowedGroup(sender)
-            : this.isAllowed(sender);
-    }
-
-    async trackIgnoredNumber(number: string, name?: string) {
-        // Only track if not already allowed or ignored.
-        if (!this.isConversationAllowed(number) &&
-            !this.ignoredNumbers.find(c => c.number === number)) {
-            this.ignoredNumbers.push({ number, name });
-            await this.saveConfig();
-        }
-    }
-
-    private mergeContacts(primary: Contact[], secondary: Contact[]): Contact[] {
-        const merged = [...primary];
-        for (const contact of secondary) {
-            const existing = merged.find(c => c.number === contact.number);
-            if (!existing) {
-                merged.push(contact);
-            } else {
-                if (!existing.name && contact.name) {
-                    existing.name = contact.name;
-                }
-            }
-        }
-        return merged;
-    }
-
-    public async isRegistered(): Promise<boolean> {
-        await this.syncAuthStateFromDisk();
-        return this.hasAuthState;
-    }
-
-    async markAuthStateAvailable() {
-        if (!this.hasAuthState) {
-            this.hasAuthState = true;
-            await this.saveConfig();
-        }
-    }
-
-    async getAuthState() {
-        await this.ensureStorageDirectories();
-        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;
-        }
-    }
-
-    async deleteAuthState() {
-        try {
-            await rm(this.authStateDir, { recursive: true, force: true });
-            await mkdir(this.authStateDir, { recursive: true });
-            this.status = 'logged-out';
-            this.hasAuthState = false;
-            await this.saveConfig();
-        } catch (error) {
-            console.error(t('session.manager.failedDeleteAuthState'), error);
-        }
-    }
-
-    getStatus(): SessionStatus {
-        return this.status;
-    }
-
-    async setStatus(status: SessionStatus) {
-        this.status = status;
-        await this.saveConfig();
-    }
-
-    getOpenaiKey(): string {
-        return this.openaiKey;
-    }
-
-    async setOpenaiKey(key: string) {
-        this.openaiKey = key;
-        await this.saveConfig();
-    }
-
-    getVisionModel(): string {
-        return this.visionModel;
-    }
-
-    async setVisionModel(model: string) {
-        this.visionModel = model;
-        await this.saveConfig();
-    }
-
-    getOperatorJid(): string {
-        return this.operatorJid;
-    }
-
-    async setOperatorJid(jid: string) {
-        this.operatorJid = jid;
-        await this.saveConfig();
-    }
-
-    getAuthStateDir(): string {
-        return this.authStateDir;
-    }
-}
+
+    getAllowedContact(number: string): Contact | undefined {
+        return this.allowList.find(c => c.number === number);
+    }
+
+    getAllowedGroups(): Contact[] {
+        return this.allowedGroups;
+    }
+
+    getAllowedGroup(groupJid: string): Contact | undefined {
+        return this.allowedGroups.find(c => c.number === groupJid);
+    }
+
+    getIgnoredNumbers(): Contact[] {
+        return this.ignoredNumbers;
+    }
+
+    async removeIgnoredNumber(number: string) {
+        this.ignoredNumbers = this.ignoredNumbers.filter(c => c.number !== number);
+        await this.saveConfig();
+    }
+
+    async addNumber(number: any, name?: string) {
+        // Handle potential nested objects from legacy bugs
+        let cleanNumber = number;
+        while (cleanNumber && typeof cleanNumber === 'object' && cleanNumber.number) {
+            cleanNumber = cleanNumber.number;
+        }
+
+        if (typeof cleanNumber !== 'string') {
+            console.warn(t('session.manager.invalidNumber'), cleanNumber);
+            return;
+        }
+
+        const existing = this.allowList.find(c => c.number === cleanNumber);
+        if (!existing) {
+            if (SessionManager.isGroupJid(cleanNumber)) {
+                await this.addAllowedGroup(cleanNumber, name);
+                return;
+            }
+            this.allowList.push({ number: cleanNumber, name });
+            this.ignoredNumbers = this.ignoredNumbers.filter(c => c.number !== cleanNumber);
+            await this.saveConfig();
+            return;
+        }
+
+        if (name && !existing.name) {
+            existing.name = name;
+            await this.saveConfig();
+        }
+    }
+
+    async removeNumber(number: string) {
+        this.allowList = this.allowList.filter(c => c.number !== number);
+        await this.saveConfig();
+    }
+
+    async addAllowedGroup(groupJid: string, name?: string) {
+        if (!SessionManager.isGroupJid(groupJid)) {
+            console.warn(t('session.manager.invalidNumber'), groupJid);
+            return;
+        }
+
+        const existing = this.allowedGroups.find(c => c.number === groupJid);
+        if (!existing) {
+            this.allowedGroups.push({ number: groupJid, name });
+            this.ignoredNumbers = this.ignoredNumbers.filter(c => c.number !== groupJid);
+            await this.saveConfig();
+            return;
+        }
+
+        if (name && !existing.name) {
+            existing.name = name;
+            await this.saveConfig();
+        }
+    }
+
+    async removeAllowedGroup(groupJid: string) {
+        this.allowedGroups = this.allowedGroups.filter(c => c.number !== groupJid);
+        await this.saveConfig();
+    }
+
+    async setAllowedContactAlias(number: string, alias: string) {
+        const trimmedAlias = alias.trim();
+        if (!trimmedAlias) {
+            return;
+        }
+
+        const contact = this.getAllowedContact(number);
+        if (!contact) {
+            return;
+        }
+
+        contact.name = trimmedAlias;
+        await this.saveConfig();
+    }
+
+    async removeAllowedContactAlias(number: string) {
+        const contact = this.getAllowedContact(number);
+        if (!contact || !contact.name) {
+            return;
+        }
+
+        delete contact.name;
+        await this.saveConfig();
+    }
+
+    async setContactSendNumber(number: string, sendNumber: string) {
+        const contact = this.getAllowedContact(number);
+        if (!contact) return;
+        contact.sendNumber = sendNumber.trim();
+        await this.saveConfig();
+    }
+
+    async removeContactSendNumber(number: string) {
+        const contact = this.getAllowedContact(number);
+        if (!contact) return;
+        delete contact.sendNumber;
+        await this.saveConfig();
+    }
+
+    async setAllowedGroupAlias(groupJid: string, alias: string) {
+        const trimmedAlias = alias.trim();
+        if (!trimmedAlias) {
+            return;
+        }
+
+        const group = this.getAllowedGroup(groupJid);
+        if (!group) {
+            return;
+        }
+
+        group.name = trimmedAlias;
+        await this.saveConfig();
+    }
+
+    async removeAllowedGroupAlias(groupJid: string) {
+        const group = this.getAllowedGroup(groupJid);
+        if (!group || !group.name) {
+            return;
+        }
+
+        delete group.name;
+        await this.saveConfig();
+    }
+
+    isAllowed(number: string): boolean {
+        return this.allowList.some(c => c.number === number);
+    }
+
+    isAllowedGroup(groupJid: string): boolean {
+        return this.allowedGroups.some(c => c.number === groupJid);
+    }
+
+    isConversationAllowed(sender: string): boolean {
+        return SessionManager.isGroupJid(sender)
+            ? this.isAllowedGroup(sender)
+            : this.isAllowed(sender);
+    }
+
+    async trackIgnoredNumber(number: string, name?: string) {
+        // Only track if not already allowed or ignored.
+        if (!this.isConversationAllowed(number) &&
+            !this.ignoredNumbers.find(c => c.number === number)) {
+            this.ignoredNumbers.push({ number, name });
+            await this.saveConfig();
+        }
+    }
+
+    private mergeContacts(primary: Contact[], secondary: Contact[]): Contact[] {
+        const merged = [...primary];
+        for (const contact of secondary) {
+            const existing = merged.find(c => c.number === contact.number);
+            if (!existing) {
+                merged.push(contact);
+            } else {
+                if (!existing.name && contact.name) {
+                    existing.name = contact.name;
+                }
+            }
+        }
+        return merged;
+    }
+
+    public async isRegistered(): Promise<boolean> {
+        await this.syncAuthStateFromDisk();
+        return this.hasAuthState;
+    }
+
+    async markAuthStateAvailable() {
+        if (!this.hasAuthState) {
+            this.hasAuthState = true;
+            await this.saveConfig();
+        }
+    }
+
+    async getAuthState() {
+        await this.ensureStorageDirectories();
+        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;
+        }
+    }
+
+    async deleteAuthState() {
+        try {
+            await rm(this.authStateDir, { recursive: true, force: true });
+            await mkdir(this.authStateDir, { recursive: true });
+            this.status = 'logged-out';
+            this.hasAuthState = false;
+            await this.saveConfig();
+        } catch (error) {
+            console.error(t('session.manager.failedDeleteAuthState'), error);
+        }
+    }
+
+    getStatus(): SessionStatus {
+        return this.status;
+    }
+
+    async setStatus(status: SessionStatus) {
+        this.status = status;
+        await this.saveConfig();
+    }
+
+    getOpenaiKey(): string {
+        return this.openaiKey;
+    }
+
+    async setOpenaiKey(key: string) {
+        this.openaiKey = key;
+        await this.saveConfig();
+    }
+
+    getVisionModel(): string {
+        return this.visionModel;
+    }
+
+    async setVisionModel(model: string) {
+        this.visionModel = model;
+        await this.saveConfig();
+    }
+
+    getOperatorJid(): string {
+        return this.operatorJid;
+    }
+
+    async setOperatorJid(jid: string) {
+        this.operatorJid = jid;
+        await this.saveConfig();
+    }
+
+    getAuthStateDir(): string {
+        return this.authStateDir;
+    }
+}

package/src/services/storage-path.ts

@@ -0,0 +1,90 @@
+import { access, mkdir, readdir, cp, stat } from 'fs/promises';
+import { homedir } from 'os';
+import { join } from 'path';
+
+export function getDefaultStorageRoot(): string {
+    return join(homedir(), '.pi', 'agent', 'extension', 'whatsapp-pi');
+}
+
+export function getDefaultLegacyStorageRoot(): string {
+    return join(homedir(), '.pi', 'whatsapp-pi');
+}
+
+export interface StoragePaths {
+    root: string;
+    legacyRoot: string;
+    authStateDir: string;
+    configPath: string;
+    recentsDir: string;
+    recentsPath: string;
+    logDir: string;
+    logPath: string;
+    mediaDir: string;
+}
+
+export function createStoragePaths(root = getDefaultStorageRoot(), legacyRoot = getDefaultLegacyStorageRoot()): StoragePaths {
+    return {
+        root,
+        legacyRoot,
+        authStateDir: join(root, 'auth'),
+        configPath: join(root, 'config.json'),
+        recentsDir: join(root, 'recents'),
+        recentsPath: join(root, 'recents', 'recents.json'),
+        logDir: root,
+        logPath: join(root, 'whatsapp-pi.log'),
+        mediaDir: join(root, 'whatsapp-medias')
+    };
+}
+
+export async function ensureStorageDirectories(paths: Pick<StoragePaths, 'root' | 'authStateDir' | 'recentsDir' | 'logDir'>) {
+    await mkdir(paths.root, { recursive: true });
+    await mkdir(paths.authStateDir, { recursive: true });
+    await mkdir(paths.recentsDir, { recursive: true });
+    await mkdir(paths.logDir, { recursive: true });
+}
+
+export async function pathExists(targetPath: string): Promise<boolean> {
+    try {
+        await access(targetPath);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+async function copyEntry(source: string, target: string) {
+    const sourceStats = await stat(source);
+    if (sourceStats.isDirectory()) {
+        await mkdir(target, { recursive: true });
+        const entries = await readdir(source, { withFileTypes: true });
+        for (const entry of entries) {
+            await copyEntry(join(source, entry.name), join(target, entry.name));
+        }
+        return;
+    }
+
+    if (await pathExists(target)) {
+        return;
+    }
+
+    await cp(source, target, { force: false, preserveTimestamps: true });
+}
+
+export async function migrateLegacyStorage(paths: Pick<StoragePaths, 'root' | 'legacyRoot'>): Promise<boolean> {
+    if (paths.root === paths.legacyRoot) {
+        return false;
+    }
+
+    if (!(await pathExists(paths.legacyRoot))) {
+        return false;
+    }
+
+    await mkdir(paths.root, { recursive: true });
+    const entries = await readdir(paths.legacyRoot, { withFileTypes: true });
+
+    for (const entry of entries) {
+        await copyEntry(join(paths.legacyRoot, entry.name), join(paths.root, entry.name));
+    }
+
+    return true;
+}

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

@@ -1,16 +1,15 @@
 import { appendFileSync, mkdirSync } from 'fs';
-import { join } from 'path';
-import { homedir } from 'os';
+import { createStoragePaths } from './storage-path.js';
 
 export class WhatsAppPiLogger {
     private logFile: string;
 
     constructor(private verbose = false) {
-        const logDir = join(homedir(), '.pi', 'whatsapp-pi');
+        const { logDir, logPath } = createStoragePaths();
         try { mkdirSync(logDir, { recursive: true }); } catch {
             // File logging is best-effort.
         }
-        this.logFile = join(logDir, 'whatsapp-pi.log');
+        this.logFile = logPath;
     }
 
     setVerbose(verbose: boolean) {

package/src/services/whatsapp.service.ts

@@ -11,10 +11,9 @@ import { MessageSender } from './message.sender.js';
 import { installBaileysConsoleFilter } from './baileys-console-filter.js';
 import { t } from '../i18n.js';
 import { appendFileSync } from 'fs';
-import { join } from 'path';
-import { homedir } from 'os';
+import { createStoragePaths } from './storage-path.js';
 
-const LOG_FILE = join(homedir(), '.pi', 'whatsapp-pi', 'whatsapp-pi.log');
+const LOG_FILE = createStoragePaths().logPath;
 function fileLog(msg: string) {
     try { appendFileSync(LOG_FILE, `[${new Date().toISOString()}] [WhatsApp-Pi] ${msg}\n`); } catch {
         // File logging is best-effort.
@@ -185,27 +184,27 @@ export class WhatsAppService {
         return value;
     }
 
-    private normalizeRecipientJid(jid: string): string {
-        if (jid.includes('@')) return jid;
-        const digits = jid.startsWith('+') ? jid.slice(1) : jid;
-        return `${digits}@s.whatsapp.net`;
-    }
-
-    public resolveOutboundRecipientJid(recipient: string): string {
-        if (SessionManager.isGroupJid(recipient)) {
-            return recipient;
-        }
-
-        const senderNumber = this.normalizeContactNumber(recipient.split('@')[0]);
-        const allowedContact = this.sessionManager.getAllowedContact(recipient)
-            ?? this.sessionManager.getAllowedContact(senderNumber);
-
-        if (allowedContact?.sendNumber) {
-            return this.normalizeRecipientJid(allowedContact.sendNumber);
-        }
-
-        return this.normalizeRecipientJid(recipient);
-    }
+    private normalizeRecipientJid(jid: string): string {
+        if (jid.includes('@')) return jid;
+        const digits = jid.startsWith('+') ? jid.slice(1) : jid;
+        return `${digits}@s.whatsapp.net`;
+    }
+
+    public resolveOutboundRecipientJid(recipient: string): string {
+        if (SessionManager.isGroupJid(recipient)) {
+            return recipient;
+        }
+
+        const senderNumber = this.normalizeContactNumber(recipient.split('@')[0]);
+        const allowedContact = this.sessionManager.getAllowedContact(recipient)
+            ?? this.sessionManager.getAllowedContact(senderNumber);
+
+        if (allowedContact?.sendNumber) {
+            return this.normalizeRecipientJid(allowedContact.sendNumber);
+        }
+
+        return this.normalizeRecipientJid(recipient);
+    }
 
     private normalizeJidForComparison(jid: string): string {
         const [localPart, domain = ''] = jid.split('@');
@@ -669,29 +668,29 @@ export class WhatsAppService {
         }
     }
 
-    async sendMessage(jid: string, text: string) {
-        const recipientJid = this.resolveOutboundRecipientJid(jid);
-
-        // Ensure we show the typing indicator before sending
-        await this.sendPresence(recipientJid, 'composing');
-
-        const result = await this.messageSender.send({
-            recipientJid,
-            text: text
-        });
-
-        // After sending, we can stop the typing indicator
-        await this.sendPresence(recipientJid, 'paused');
-
-        if (!result.success) {
-            console.error(t('service.whatsapp.failedSendMessage', { jid: recipientJid, error: result.error ?? t('message.sender.unknownError') }));
-        }
-
-        return result;
-    }
-
-    async sendMenuMessage(jid: string, text: string) {
-        const normalizedJid = this.resolveOutboundRecipientJid(jid);
+    async sendMessage(jid: string, text: string) {
+        const recipientJid = this.resolveOutboundRecipientJid(jid);
+
+        // Ensure we show the typing indicator before sending
+        await this.sendPresence(recipientJid, 'composing');
+
+        const result = await this.messageSender.send({
+            recipientJid,
+            text: text
+        });
+
+        // After sending, we can stop the typing indicator
+        await this.sendPresence(recipientJid, 'paused');
+
+        if (!result.success) {
+            console.error(t('service.whatsapp.failedSendMessage', { jid: recipientJid, error: result.error ?? t('message.sender.unknownError') }));
+        }
+
+        return result;
+    }
+
+    async sendMenuMessage(jid: string, text: string) {
+        const normalizedJid = this.resolveOutboundRecipientJid(jid);
         const socket = this.getActiveSocket();
 
         if (!socket) {