nduka 1.0.0

package/dist/gateway/server.js

@@ -0,0 +1,947 @@
+/**
+ * WhatsApp Gateway Server
+ *
+ * Entry point for the WhatsApp automation gateway.
+ *
+ * Architecture (following OpenClaw's Gateway pattern):
+ *
+ *   WhatsApp ←→ Baileys Socket ←→ Gateway ←→ Event Bus ←→ Router ←→ AI
+ *
+ * The gateway is the sole owner of the WhatsApp session.
+ * Nothing talks directly to WhatsApp — everything routes through here.
+ */
+// ── Global safety net for Baileys internal media key errors ──
+process.on('unhandledRejection', (reason) => {
+    const msg = reason?.message || String(reason);
+    if (msg.includes('media key') || msg.includes('empty media')) {
+        console.warn('[Recovered] Media key error in history sync:', msg);
+        return;
+    }
+    console.error('[Fatal] Unhandled rejection:', reason);
+    process.exit(1);
+});
+// ── Single-instance guard ──
+if (globalThis.__BAILEYS_RUNNING__) {
+    console.error('[FATAL] Another gateway instance is already running. Exiting.');
+    process.exit(1);
+}
+globalThis.__BAILEYS_RUNNING__ = true;
+import { SingleFileAuthStore, deepClone } from './auth/store.js';
+import { SocketManager, Browsers } from './socket/index.js';
+import { EventHandler } from './events/handler.js';
+import { ReconnectManager } from './reconnect/manager.js';
+import { HealthMonitor } from './health/monitor.js';
+import { controlledReconnect } from './connection-state.js';
+import { syncMutex } from './sync-mutex.js';
+import { transition, isReady, ConnState } from './conn-state-machine.js';
+import { bufferMessage } from './message-buffer.js';
+import { getEventBus, EventType } from '../event-bus/index.js';
+import { DatabaseManager } from '../database/index.js';
+import { MediaService } from '../media/service.js';
+import { SessionManager } from '../session/manager.js';
+import { SessionSnapshotService } from '../session/snapshot.js';
+import { SessionRecoveryService } from '../session/recovery.js';
+import { AIResponseEngine } from '../llm/engine.js';
+import { OcrClient } from '../llm/ocr-client.js';
+import { OcrModelRegistry } from '../llm/ocr-registry.js';
+import { ToolRegistry } from '../tools/registry.js';
+import { OwnerIdentityService } from '../owner/identity.js';
+import { GlobalConfigService } from '../owner/config.js';
+import { OwnerRouter } from '../owner/router.js';
+import { PersistentMemory } from '../memory/persistent.js';
+import { GroqWhisperService } from '../voice-pipeline/groq-whisper.js';
+import { ConversationOps } from '../conversation/ops.js';
+import { ConversationRuntime } from '../conversation/runtime.js';
+import { EventSourcingStore } from '../event-sourcing/store.js';
+import { ChatRegistry } from '../chat-registry/service.js';
+import { ChatStateStore } from '../chat-state/store.js';
+import { checkApiKeys } from '../llm/config.js';
+import { TaskModelRouter } from '../llm/task-router.js';
+import { createGatewayAsyncJobWorker } from '../async-jobs/gateway-worker.js';
+import { PromptRegistry } from '../prompts/registry.js';
+import { isAudioTranscriptionEnabled, isImageAnalysisEnabled, isPdfAnalysisEnabled } from '../config/runtime-feature-flags.js';
+import qrcode from 'qrcode-terminal';
+// ─── Configuration ───────────────────────────────────────────────────────────
+const AUTH_FILE_PATH = process.env.AUTH_FILE_PATH || './data/auth_state.json';
+const LOG_LEVEL = process.env.LOG_LEVEL || 'info';
+// ─── Logger ──────────────────────────────────────────────────────────────────
+/**
+ * Normalize a WhatsApp JID for consistent chat identification.
+ * WhatsApp uses both @s.whatsapp.net (phone JID) and @lid (Lite ID)
+ * for the same conversation. Normalize to a stable key.
+ */
+function normalizeChatJid(jid) {
+    // Strip device suffix (e.g., :4, :7)
+    let normalized = jid.replace(/:(\d+)@/, '@');
+    // LID addresses: use the LID as-is since it's already a stable identifier
+    if (normalized.endsWith('@lid')) {
+        return normalized;
+    }
+    // Group JIDs: keep as-is
+    if (normalized.endsWith('@g.us')) {
+        return normalized;
+    }
+    // Phone JIDs: strip device suffix, normalize domain
+    normalized = normalized.replace('@s.whatsapp.net', '@s.whatsapp.net');
+    return normalized;
+}
+function isGatewayMediaMessageType(messageType) {
+    return messageType === 'imageMessage' || messageType === 'videoMessage' || messageType === 'documentMessage' || messageType === 'stickerMessage' || messageType === 'audioMessage';
+}
+function isVisualMediaMessageType(messageType) {
+    return messageType === 'imageMessage' || messageType === 'documentMessage';
+}
+function mediaTypeFromMessageType(messageType) {
+    if (messageType === 'imageMessage')
+        return 'image';
+    if (messageType === 'videoMessage')
+        return 'video';
+    if (messageType === 'documentMessage')
+        return 'document';
+    if (messageType === 'stickerMessage')
+        return 'sticker';
+    if (messageType === 'audioMessage')
+        return 'audio';
+    return null;
+}
+function downloadResultFromParsedMedia(messageType, media) {
+    const mediaType = mediaTypeFromMessageType(messageType);
+    if (!mediaType || !media?.downloaded || !media.mediaId || !media.filePath)
+        return null;
+    return {
+        mediaId: media.mediaId,
+        filePath: media.filePath,
+        fileSize: media.fileSize || 0,
+        sha256: media.sha256 || '',
+        mimeType: media.mimeType || 'application/octet-stream',
+        fileName: media.fileName,
+        mediaType,
+    };
+}
+const logger = {
+    info: (msg, ...args) => console.log(`[Gateway] ${msg}`, ...args),
+    warn: (msg, ...args) => console.warn(`[Gateway] ${msg}`, ...args),
+    error: (msg, ...args) => console.error(`[Gateway] ${msg}`, ...args),
+    debug: (msg, ...args) => {
+        if (LOG_LEVEL === 'debug')
+            console.debug(`[Gateway] ${msg}`, ...args);
+    },
+};
+// ─── Gateway ─────────────────────────────────────────────────────────────────
+class Gateway {
+    authStore;
+    socketManager = null;
+    eventHandler;
+    reconnectManager;
+    healthMonitor;
+    shuttingDown = false;
+    saveIntervals = [];
+    db = DatabaseManager.getInstance();
+    mediaService = new MediaService();
+    sessionManager = new SessionManager();
+    snapshotService = new SessionSnapshotService(AUTH_FILE_PATH);
+    recoveryService;
+    aiEngine = new AIResponseEngine();
+    toolRegistry = new ToolRegistry();
+    ownerIdentity = new OwnerIdentityService();
+    globalConfig = new GlobalConfigService();
+    ownerRouter = new OwnerRouter(this.ownerIdentity, this.globalConfig, this.toolRegistry.getModelManager());
+    persistentMemory = new PersistentMemory();
+    whisperService = new GroqWhisperService();
+    ocrClient = new OcrClient({ timeoutMs: Number(process.env.OCR_TIMEOUT_MS || 60_000) });
+    ocrRegistry = new OcrModelRegistry();
+    eventStore = new EventSourcingStore();
+    chatRegistry = new ChatRegistry(new ChatStateStore());
+    ops;
+    runtime;
+    asyncJobWorker = null;
+    promptRegistry = new PromptRegistry();
+    constructor() {
+        this.authStore = new SingleFileAuthStore(AUTH_FILE_PATH);
+        this.eventHandler = new EventHandler();
+        this.reconnectManager = new ReconnectManager({
+            initialDelayMs: 1_000,
+            maxDelayMs: 60_000,
+            backoffMultiplier: 2,
+            maxAttempts: 0, // unlimited
+        });
+        this.healthMonitor = new HealthMonitor();
+        this.recoveryService = new SessionRecoveryService(this.authStore, this.snapshotService);
+        this.ops = new ConversationOps(this.persistentMemory, new ChatStateStore(), this.chatRegistry, this.eventStore);
+        this.runtime = new ConversationRuntime(this.ownerIdentity, this.globalConfig, this.aiEngine, this.persistentMemory, this.toolRegistry);
+        this.asyncJobWorker = createGatewayAsyncJobWorker({
+            registry: this.toolRegistry,
+            sendText: (chatJid, text) => this.sendReply(chatJid, text),
+            onDelivered: (job, reply) => {
+                this.persistentMemory.store(job.chatJid, 'user', job.originalText, 'customer');
+                this.persistentMemory.store(job.chatJid, 'assistant', reply, 'tool');
+                this.persistentMemory.trim(job.chatJid, this.globalConfig.get('maxMessagesPerChat'));
+            },
+            onResult: (result) => {
+                if (result.due || result.succeeded || result.retried || result.failed) {
+                    logger.info(`[AsyncJobs] tick complete: due=${result.due}, succeeded=${result.succeeded}, retried=${result.retried}, failed=${result.failed}`);
+                }
+            },
+            onError: (error) => logger.error('[AsyncJobs] worker error:', error.message),
+            answerSynthesizer: async (input) => {
+                const synthesisRouter = new TaskModelRouter();
+                const synthesisTask = synthesisRouter.isTask('tool_synthesis') ? 'tool_synthesis' : 'text_summary';
+                const prompt = this.promptRegistry.render('tool_result_synthesis', {
+                    toolName: input.toolName,
+                    toolQuery: input.toolQuery,
+                    toolResult: input.toolResult,
+                    userQuestion: input.userQuestion,
+                });
+                const response = await this.aiEngine.generateResponse(prompt, [], {
+                    task: synthesisTask,
+                    systemPromptName: null,
+                    maxTokens: 900,
+                    temperature: 0.2,
+                    weakRetry: true,
+                });
+                return response.text;
+            },
+        });
+    }
+    /** Start the gateway. */
+    async start() {
+        this.shuttingDown = false;
+        logger.info('Starting WhatsApp Gateway...');
+        // ── Session ownership check ──
+        const isOwner = this.sessionManager.acquireOwnership();
+        if (!isOwner) {
+            logger.error('❌ Another Gateway process already owns the session. Exiting.');
+            process.exit(1);
+        }
+        logger.info(`Session ownership acquired (v${this.sessionManager.getVersion()})`);
+        // ── API Key Status ──
+        const keys = checkApiKeys();
+        if (keys.openrouter || keys.kilocode) {
+            logger.info('🔑 API Keys loaded:');
+            if (keys.openrouter)
+                logger.info('   OpenRouter: ✅');
+            if (keys.kilocode)
+                logger.info('   Kilocode: ✅');
+        }
+        else {
+            logger.warn('⚠️  No API keys found — AI responses disabled (echo mode)');
+        }
+        // Load existing auth state
+        const hasExistingAuth = this.authStore.loadSync();
+        if (hasExistingAuth) {
+            logger.info('Loaded existing auth session from disk');
+        }
+        else {
+            logger.info('No existing auth session — QR scan required');
+        }
+        // Set up reconnection handler with strict state machine (prevents deadlocks)
+        this.reconnectManager.onReconnect(async () => {
+            if (this.shuttingDown)
+                return;
+            this.healthMonitor.recordReconnectAttempt();
+            await controlledReconnect(async () => {
+                if (this.socketManager) {
+                    await this.socketManager.disconnect();
+                    this.socketManager = null;
+                }
+            }, async () => { await this.connect(); });
+        });
+        // Register message handler
+        const eventBus = getEventBus();
+        // History sync guard — ignore messages during initial sync to avoid media key errors
+        let isSyncing = true;
+        const SYNC_WINDOW_MS = 20_000; // 20s sync grace period
+        setTimeout(() => { isSyncing = false; }, SYNC_WINDOW_MS);
+        this.eventHandler.onMessage(async (msg) => {
+            // ── HARD GATE: Only process messages when READY and crypto is stable ──
+            if (!isReady()) {
+                if (msg.isNotify)
+                    bufferMessage(msg);
+                return;
+            }
+            this.healthMonitor.recordMessageReceived();
+            // Persist message to database
+            this.db.insertMessage({
+                id: msg.key?.id || '',
+                remote_jid: msg.chatJid,
+                from_me: msg.fromMe ? 1 : 0,
+                sender_jid: msg.senderJid || null,
+                participant_jid: msg.key?.participant || null,
+                text_content: msg.textContent,
+                message_type: msg.messageType || 'unknown',
+                message_status: 'received',
+                raw_message: JSON.stringify(msg.raw),
+                timestamp: Number(msg.timestamp) || Date.now(),
+            });
+            // Persist chat if not exists
+            this.db.upsertChat({
+                jid: msg.chatJid,
+                name: null,
+                is_group: msg.chatJid?.includes('@g.us') ? 1 : 0,
+                last_message_at: new Date().toISOString(),
+                unread_count: 0,
+            });
+            const msgAge = Date.now() - (Number(msg.timestamp) * 1000 || Date.now());
+            const isRecent = msgAge < 120_000;
+            const isSelfChat = msg.fromMe && msg.chatJid === msg.senderJid;
+            const shouldRespond = !msg.fromMe || isSelfChat;
+            if (isVisualMediaMessageType(msg.messageType) && this.socketManager && shouldRespond && isRecent) {
+                logger.info(`[${msg.chatJid}] Received ${msg.messageType} with caption: ${msg.textContent || '(no caption)'}`);
+                await this.handleVisualMediaMessage(msg);
+                return;
+            }
+            // Emit to event bus
+            if (msg.textContent) {
+                logger.info(`[${msg.chatJid}] ${msg.textContent}`);
+                const payload = {
+                    messageId: msg.key?.id || '',
+                    chatJid: msg.chatJid,
+                    senderJid: msg.senderJid,
+                    textContent: msg.textContent,
+                    messageType: msg.messageType || 'conversation',
+                    timestamp: Number(msg.timestamp) || Date.now(),
+                    isGroup: msg.chatJid?.includes('@g.us') || false,
+                    participantJid: msg.key?.participant || undefined,
+                };
+                eventBus.emit(EventType.MESSAGE_RECEIVED, payload);
+                // Respond to incoming messages — only recent ones
+                // Allow self-chat (fromMe + ownerDetected) for command processing
+                if (this.socketManager && shouldRespond && isRecent) {
+                    await this.handleIncomingMessage(msg);
+                }
+            }
+            else if (msg.messageType) {
+                // Silently skip system/infrastructure message types
+                if (msg.messageType === 'protocolMessage' ||
+                    msg.messageType === 'senderKeyDistributionMessage' ||
+                    msg.messageType === 'reactionMessage') {
+                    return;
+                }
+                // Log non-system messages only
+                logger.info(`[${msg.chatJid}] Received ${msg.messageType} message`);
+                // Download media immediately (before CDN link expires)
+                const isMedia = isGatewayMediaMessageType(msg.messageType);
+                if (isMedia && msg.raw) {
+                    this.mediaService.downloadFromMessage(msg.raw).then((result) => {
+                        if (result) {
+                            logger.info(`[Media] Downloaded ${result.mediaType}: ${result.filePath} (${result.fileSize}B)`);
+                            if (msg.messageType === 'audioMessage') {
+                                if (!isAudioTranscriptionEnabled()) {
+                                    logger.info('[Voice] Transcription skipped because audio transcription is turned off in chatbot settings.');
+                                    if (shouldRespond && isRecent) {
+                                        this.sendReply(msg.chatJid, 'I received the audio, but voice transcription is turned off in the chatbot settings right now.').catch((err) => {
+                                            logger.error('[Voice] Disabled-transcription reply failed:', err.message);
+                                        });
+                                    }
+                                    return;
+                                }
+                                // Transcribe voice note with Groq Whisper
+                                this.whisperService.transcribe(result.filePath).then((transcript) => {
+                                    if (transcript.success) {
+                                        logger.info(`[Voice] Transcribed: "${transcript.text.slice(0, 80)}..."`);
+                                        // Feed transcribed text to AI for response
+                                        this.handleIncomingMessage({
+                                            ...msg,
+                                            textContent: `[Voice Note]: ${transcript.text}`,
+                                            messageType: 'conversation',
+                                        });
+                                    }
+                                    else {
+                                        logger.error(`[Voice] Transcription failed: ${transcript.error}`);
+                                    }
+                                }).catch((err) => {
+                                    logger.error('[Voice] Whisper error:', err.message);
+                                });
+                            }
+                            else {
+                                eventBus.emit(EventType.MEDIA_RECEIVED, {
+                                    messageId: msg.key?.id || '',
+                                    chatJid: msg.chatJid,
+                                    senderJid: msg.senderJid,
+                                    mediaType: result.mediaType,
+                                    mimeType: result.mimeType,
+                                    fileName: result.fileName,
+                                    fileSize: result.fileSize,
+                                    caption: msg.textContent || undefined,
+                                    timestamp: Number(msg.timestamp) || Date.now(),
+                                });
+                            }
+                        }
+                    }).catch((err) => {
+                        logger.error('[Media] Download error:', err.message);
+                    });
+                }
+                else if (isMedia) {
+                    // Fallback: emit event without download
+                    if (msg.messageType === 'audioMessage') {
+                        eventBus.emit(EventType.VOICE_RECEIVED, {
+                            messageId: msg.key?.id || '',
+                            chatJid: msg.chatJid,
+                            senderJid: msg.senderJid,
+                            ptt: true,
+                            timestamp: Number(msg.timestamp) || Date.now(),
+                        });
+                    }
+                    else {
+                        eventBus.emit(EventType.MEDIA_RECEIVED, {
+                            messageId: msg.key?.id || '',
+                            chatJid: msg.chatJid,
+                            senderJid: msg.senderJid,
+                            mediaType: msg.messageType.replace('Message', ''),
+                            caption: msg.textContent || undefined,
+                            timestamp: Number(msg.timestamp) || Date.now(),
+                        });
+                    }
+                }
+            }
+        });
+        // Register connection state handler
+        this.eventHandler.onConnectionState((state) => {
+            if (state.qr) {
+                // Display QR code in terminal
+                logger.info('Scan the QR code below with WhatsApp:');
+                try {
+                    qrcode.generate(state.qr, { small: true });
+                }
+                catch {
+                    // Fallback if qrcode-terminal fails
+                    console.log(state.qr);
+                }
+            }
+            if (state.connection === 'open') {
+                logger.info('✅ Connected to WhatsApp!');
+                this.healthMonitor.updateConnection('open');
+                this.healthMonitor.resetReconnectAttempts();
+                // Detect/refresh owner on every successful login
+                if (this.socketManager) {
+                    const sock = this.socketManager.getSocket();
+                    if (sock) {
+                        const owner = this.ownerIdentity.detectOwner(sock);
+                        if (owner) {
+                            logger.info(`👑 Owner: ${owner.ownerJid} (phone: ${owner.ownerPhone})`);
+                        }
+                    }
+                }
+                else {
+                    this.ownerIdentity.updateLastSeen();
+                }
+                const connPayload = { state: 'open' };
+                eventBus.emit(EventType.CONNECTION_STATE_CHANGED, connPayload);
+            }
+            else if (state.connection === 'close') {
+                logger.warn('Connection closed');
+                this.healthMonitor.updateConnection('close');
+                // 515 restartRequired is NORMAL after pairing — reconnect immediately
+                const isRestartRequired = state.lastDisconnect?.reason?.includes('515');
+                const connPayload = {
+                    state: 'close',
+                    lastDisconnectReason: state.lastDisconnect?.reason,
+                };
+                eventBus.emit(EventType.CONNECTION_STATE_CHANGED, connPayload);
+                // Only reconnect if not shutting down
+                if (!this.shuttingDown) {
+                    this.reconnectManager.handleConnectionUpdate(state);
+                }
+            }
+            else if (state.connection === 'connecting') {
+                this.healthMonitor.updateConnection('connecting');
+            }
+        });
+        // Connect — use pairing code if phone number provided
+        const pairingPhone = process.env.WA_PAIRING_PHONE;
+        if (pairingPhone) {
+            logger.info(`Using pairing code for: ${pairingPhone}`);
+        }
+        await this.connect(pairingPhone);
+        if (this.asyncJobWorker?.start()) {
+            logger.info('[AsyncJobs] worker started');
+        }
+        // Start periodic session snapshots
+        this.snapshotService.startPeriodicSnapshots();
+    }
+    /** Establish a WhatsApp connection. */
+    async connect(pairingPhone) {
+        if (this.shuttingDown)
+            return;
+        transition(ConnState.CONNECTING);
+        try {
+            // Fully destroy old socket before creating new one
+            if (this.socketManager) {
+                await this.socketManager.disconnect();
+                this.socketManager = null;
+            }
+            // Re-validate auth before reconnect (prevents handshake failures from stale creds)
+            const isValid = await this.recoveryService.validateBeforeConnect();
+            if (!isValid) {
+                logger.error('Auth validation failed — credentials may be corrupted');
+                this.snapshotService.rollbackToLatest();
+            }
+            // Deep-clone auth state to prevent shared mutable state between sockets.
+            // Baileys mutates creds in-place during connection lifecycle (me.lid, registered, etc.).
+            // Sharing the same object causes Signal session corruption on reconnect.
+            const authState = deepClone(this.authStore.getAuthState());
+            this.socketManager = new SocketManager({
+                auth: authState,
+                browser: Browsers.macOS('Desktop'),
+            });
+            const { sock } = await this.socketManager.createSocket();
+            const baileysEv = sock.ev;
+            // ── Prekey refresh + state transition on successful connection ──
+            let readyTransitioned = false;
+            sock.ev.on('connection.update', async (update) => {
+                const u = update;
+                if (u.connection === 'open') {
+                    transition(ConnState.SYNCING);
+                    try {
+                        this.authStore.updateCreds(sock.authState.creds);
+                        await this.authStore.save();
+                        logger.info('[AuthStore] Saved auth state after connection open');
+                    }
+                    catch (err) {
+                        logger.error('Failed to save auth state after connection open:', err.message);
+                    }
+                    if (!readyTransitioned) {
+                        readyTransitioned = true;
+                        try {
+                            const keys = sock.authState.keys;
+                            const count = keys?.getPreKeysCount?.() ?? 0;
+                            if (count < 10) {
+                                logger.info(`[Prekey] Only ${count} prekeys — regenerating to 50...`);
+                                await sock.uploadPreKeys(50);
+                                logger.info('[Prekey] Regeneration complete');
+                            }
+                            // Transition to READY after prekeys are confirmed
+                            transition(ConnState.READY);
+                            logger.info('[Gateway] ✅ READY — processing messages now');
+                        }
+                        catch (e) {
+                            logger.warn('[Prekey] Refresh failed — continuing anyway:', e.message);
+                            transition(ConnState.READY); // Still go READY even if prekeys fail
+                        }
+                    }
+                }
+                ;
+            });
+            // ── Pairing code + crypto recovery ──
+            if (pairingPhone) {
+                sock.ev.on('connection.update', async (update) => {
+                    const u = update;
+                    if (u.qr) {
+                        try {
+                            const code = await sock.requestPairingCode(pairingPhone);
+                            logger.info(`📱 Pairing code: ${code}`);
+                            logger.info('Enter this code on your phone when prompted');
+                        }
+                        catch (err) {
+                            logger.error('Failed to request pairing code:', err.message);
+                        }
+                    }
+                });
+            }
+            // ── Crypto session recovery: intercept Signal protocol errors ──
+            sock.ev.on('connection.update', (update) => {
+                const u = update;
+                if (u.connection === 'open') {
+                    const originalOnUnexpected = sock.onUnexpectedError;
+                    if (originalOnUnexpected) {
+                        sock.onUnexpectedError = (err, msg) => {
+                            const errMsg = err?.message || '';
+                            if (errMsg.includes('MessageCounter') ||
+                                errMsg.includes('Key used already') ||
+                                errMsg.includes('No matching sessions') ||
+                                errMsg.includes('Invalid PreKey') ||
+                                errMsg.includes('Bad MAC') ||
+                                errMsg.includes('SessionError') ||
+                                errMsg.includes('Failed to decrypt')) {
+                                logger.warn(`[Crypto] Recoverable session error in '${msg}': ${errMsg}`);
+                                Promise.resolve(sock.authState.keys.set({ session: {} })).catch(() => { });
+                                return;
+                            }
+                            originalOnUnexpected(err, msg);
+                        };
+                    }
+                }
+            });
+            baileysEv.on('creds.update', async (creds) => {
+                this.authStore.updateCreds(creds);
+                try {
+                    await this.authStore.save();
+                }
+                catch (err) {
+                    logger.error('Failed to save auth state after creds.update:', err.message);
+                }
+            });
+            baileysEv.on('connection.update', (update) => {
+                const connUpdate = update;
+                const conn = connUpdate.connection;
+                // ── DEBUG: Full connection.update logging for pairing diagnostics ──
+                if (conn === 'close' || connUpdate.lastDisconnect || connUpdate.qr) {
+                    const ld = connUpdate.lastDisconnect;
+                    logger.info('📡 RAW connection.update:', JSON.stringify({
+                        connection: connUpdate.connection,
+                        isNewLogin: connUpdate.isNewLogin,
+                        qr: connUpdate.qr ? '(QR - see above)' : undefined,
+                        lastDisconnect: ld
+                            ? {
+                                date: ld.date,
+                                error: ld.error instanceof Error ? ld.error.message : String(ld.error),
+                                statusCode: ld.error instanceof Error
+                                    ? ld.error.statusCode
+                                    : undefined,
+                            }
+                            : undefined,
+                        receivedPendingNotifications: connUpdate.receivedPendingNotifications,
+                        isOnline: connUpdate.isOnline,
+                    }));
+                }
+                // Don't process connection updates during shutdown
+                if (this.shuttingDown && conn === 'close')
+                    return;
+                // Reset chat state on sync corruption to break retry loops
+                if (conn === 'close') {
+                    transition(ConnState.RECONNECTING);
+                    const errMsg = connUpdate.lastDisconnect?.error?.message || '';
+                    if (errMsg.includes('Invalid patch mac') || errMsg.includes('decodeSyncdPatch')) {
+                        logger.warn('[Sync] Chat state corrupted — sync mutex will prevent parallel mutations on reconnect');
+                    }
+                }
+                this.eventHandler.handleConnectionUpdate(update);
+            });
+            baileysEv.on('messages.upsert', (msg) => {
+                if (this.shuttingDown)
+                    return;
+                syncMutex.run(() => this.eventHandler.handleMessagesUpsert(msg)).catch((err) => {
+                    logger.error('[MessagesUpsert] Handler error:', err);
+                });
+            });
+            // ── Error 463 recovery: refresh privacy tokens on delivery failure ──
+            // Baileys v6.7.23 doesn't auto-recover from error 463 (MissingTcToken).
+            // The fix (PR #2517) was added after this version. We implement it here.
+            const inFlight463Recoveries = new Set();
+            baileysEv.on('messages.update', (updates) => {
+                const items = updates;
+                for (const item of items) {
+                    if (item.update?.status === 'ERROR' && item.update?.messageStubParameters?.includes('463')) {
+                        const jid = item.key?.remoteJid;
+                        if (jid && !inFlight463Recoveries.has(jid)) {
+                            inFlight463Recoveries.add(jid);
+                            logger.warn(`[Error463] MissingTcToken for ${jid} — refreshing privacy token`);
+                            // Best-effort: issue a new privacy token
+                            sock.query({
+                                tag: 'iq',
+                                attrs: { to: '@s.whatsapp.net', type: 'set', xmlns: 'privacy' },
+                                content: [{ tag: 'tctoken', attrs: { jid }, content: undefined }]
+                            }).catch(() => { }).finally(() => {
+                                setTimeout(() => inFlight463Recoveries.delete(jid), 30_000);
+                            });
+                        }
+                    }
+                }
+            });
+            // Periodically save auth state (every 30 seconds)
+            const saveInterval = setInterval(async () => {
+                try {
+                    await this.authStore.save();
+                }
+                catch (err) {
+                    logger.error('Failed to save auth state:', err.message);
+                }
+            }, 30_000);
+            this.saveIntervals.push(saveInterval);
+            // Clean up interval on disconnect
+            baileysEv.on('connection.update', (update) => {
+                const connUpdate = update;
+                if (connUpdate.connection === 'close') {
+                    clearInterval(saveInterval);
+                    this.saveIntervals = this.saveIntervals.filter((i) => i !== saveInterval);
+                }
+            });
+        }
+        catch (err) {
+            logger.error('Connection failed:', err.message);
+            if (!this.shuttingDown) {
+                this.reconnectManager.handleConnectionUpdate({
+                    connection: 'close',
+                    lastDisconnect: { date: new Date(), reason: err.message },
+                });
+            }
+        }
+    }
+    /** Echo a message back (fallback when no API keys). */
+    async echoMessage(msg) {
+        if (!this.socketManager || msg.fromMe)
+            return;
+        try {
+            // Simulate typing for natural feel
+            await this.socketManager.sendPresenceUpdate('composing', msg.chatJid);
+            await new Promise((resolve) => setTimeout(resolve, 1500));
+            const echoText = `Echo: ${msg.textContent}`;
+            const result = await this.socketManager.sendText(msg.chatJid, echoText);
+            this.healthMonitor.recordMessageSent();
+            logger.info(`[${msg.chatJid}] Sent: ${echoText}`);
+            // Persist sent message
+            const sentId = result?.key?.id || '';
+            this.db.insertMessage({
+                id: sentId,
+                remote_jid: msg.chatJid,
+                from_me: 1,
+                sender_jid: null,
+                participant_jid: null,
+                text_content: echoText,
+                message_type: 'conversation',
+                message_status: 'delivered',
+                raw_message: JSON.stringify(result),
+                timestamp: Date.now(),
+            });
+            // Emit message sent event
+            getEventBus().emit(EventType.MESSAGE_SENT, {
+                messageId: sentId,
+                chatJid: msg.chatJid,
+                textContent: echoText,
+                timestamp: Date.now(),
+            });
+            await this.socketManager.sendPresenceUpdate('paused', msg.chatJid);
+        }
+        catch (err) {
+            logger.error('Failed to echo message:', err.message);
+        }
+    }
+    /** AI-powered response using OpenRouter/Kilocode. */
+    async aiRespond(msg, history, options) {
+        // Allow self-chat (where chatJid === senderJid) for owner commands
+        const isSelfChat = msg.fromMe && msg.chatJid === msg.senderJid;
+        if (!this.socketManager || !msg.textContent)
+            return;
+        if (msg.fromMe && !isSelfChat)
+            return; // Only block non-self fromMe messages
+        try {
+            await this.socketManager.sendPresenceUpdate('composing', msg.chatJid);
+            const startTime = Date.now();
+            const response = await this.aiEngine.generateResponse(msg.textContent, history, options);
+            const latency = Date.now() - startTime;
+            if (response.text && response.text.length > 0) {
+                await this.sendReply(msg.chatJid, response.text, response);
+                this.healthMonitor.recordMessageSent();
+                logger.info(`[AI] ${msg.chatJid} ← ${response.text.slice(0, 50)}... (${response.model}, ${latency}ms)`);
+                // Persist to memory
+                this.persistentMemory.store(msg.chatJid, 'assistant', response.text);
+                const sentId = `sent_${Date.now()}`;
+                this.db.insertMessage({
+                    id: sentId,
+                    remote_jid: msg.chatJid,
+                    from_me: 1,
+                    sender_jid: null,
+                    participant_jid: null,
+                    text_content: response.text,
+                    message_type: 'conversation',
+                    message_status: 'delivered',
+                    raw_message: JSON.stringify(response),
+                    timestamp: Date.now(),
+                });
+                getEventBus().emit(EventType.MESSAGE_SENT, {
+                    messageId: sentId,
+                    chatJid: msg.chatJid,
+                    textContent: response.text,
+                    timestamp: Date.now(),
+                });
+            }
+            await this.socketManager.sendPresenceUpdate('paused', msg.chatJid);
+        }
+        catch (err) {
+            logger.error('AI response failed:', err.message);
+            // Fallback to echo on AI failure
+            await this.echoMessage(msg);
+        }
+    }
+    async analyzeVisualMedia(downloaded, caption) {
+        const isPdf = downloaded.mediaType === 'document' && /pdf/i.test(downloaded.mimeType || downloaded.fileName || '');
+        const task = isPdf ? 'pdf_summary' : 'vision_ocr';
+        const selected = this.ocrRegistry.require(task);
+        if (!selected.ok) {
+            return `MEDIA_ANALYSIS_FAILED: ${selected.reason}. Configure ${task} in config/llm.settings.json or the matching TASK_* env overrides.`;
+        }
+        const captionLine = caption?.trim()
+            ? `The user attached this media and asked: "${caption.trim()}"`
+            : 'The user attached this media and wants to know what it is for.';
+        const prompt = this.promptRegistry.render(isPdf ? 'media_pdf_summary' : 'media_image_analysis', { captionLine });
+        const runOcr = (profile) => this.ocrClient.run({
+            task,
+            filePath: downloaded.filePath,
+            mimeType: downloaded.mimeType,
+            fileName: downloaded.fileName,
+            prompt,
+            profile,
+        });
+        const result = await runOcr(selected.profile);
+        if (result.ok)
+            return result.text;
+        const fallback = this.ocrRegistry.requireFallback(task);
+        if (fallback.ok) {
+            logger.warn(`[MediaAnalysisFallback] ${JSON.stringify({
+                task,
+                failedProvider: selected.profile.provider,
+                failedModel: selected.profile.model,
+                fallbackProvider: fallback.profile.provider,
+                fallbackModel: fallback.profile.model,
+                reason: result.errorMessage,
+            })}`);
+            const fallbackResult = await runOcr(fallback.profile);
+            if (fallbackResult.ok)
+                return fallbackResult.text;
+            return `MEDIA_ANALYSIS_FAILED: ${result.errorMessage}; fallback ${fallback.profile.provider}/${fallback.profile.model} also failed: ${fallbackResult.errorMessage}`;
+        }
+        return `MEDIA_ANALYSIS_FAILED: ${result.errorMessage}`;
+    }
+    async handleVisualMediaMessage(msg) {
+        if (!this.socketManager)
+            return;
+        const caption = msg.textContent && !msg.textContent.startsWith('[media:') ? msg.textContent : 'What is this for?';
+        let downloaded = downloadResultFromParsedMedia(msg.messageType, msg.media);
+        if (!downloaded && msg.raw) {
+            downloaded = await this.mediaService.downloadFromMessage(msg.raw);
+        }
+        if (!downloaded) {
+            await this.sendReply(msg.chatJid, `I received the ${msg.messageType?.replace('Message', '') || 'media'}, but I couldn't download it for analysis. Please resend it once more.`);
+            return;
+        }
+        logger.info(`[Media] Downloaded ${downloaded.mediaType}: ${downloaded.filePath} (${downloaded.fileSize}B)`);
+        const isPdf = downloaded.mediaType === 'document' && /pdf/i.test(downloaded.mimeType || downloaded.fileName || '');
+        const mediaAnalysisEnabled = isPdf ? isPdfAnalysisEnabled() : isImageAnalysisEnabled();
+        if (!mediaAnalysisEnabled) {
+            const mediaLabel = isPdf ? 'PDF analysis' : 'image analysis';
+            logger.info(`[MediaAnalysisDisabled] ${JSON.stringify({
+                chatJid: msg.chatJid,
+                messageId: msg.key?.id || '',
+                mediaType: downloaded.mediaType,
+                mimeType: downloaded.mimeType,
+            })}`);
+            await this.sendReply(msg.chatJid, `I received the ${isPdf ? 'PDF' : 'image'}, but ${mediaLabel} is turned off in the chatbot settings right now.`);
+            return;
+        }
+        getEventBus().emit(EventType.MEDIA_RECEIVED, {
+            messageId: msg.key?.id || '',
+            chatJid: msg.chatJid,
+            senderJid: msg.senderJid,
+            mediaType: downloaded.mediaType,
+            mimeType: downloaded.mimeType,
+            fileName: downloaded.fileName,
+            fileSize: downloaded.fileSize,
+            caption,
+            timestamp: Number(msg.timestamp) || Date.now(),
+        });
+        const analysis = await this.analyzeVisualMedia(downloaded, caption);
+        if (analysis.startsWith('MEDIA_ANALYSIS_FAILED:')) {
+            logger.warn(`[MediaAnalysisFailed] ${JSON.stringify({
+                chatJid: msg.chatJid,
+                messageId: msg.key?.id || '',
+                mediaType: downloaded.mediaType,
+                mimeType: downloaded.mimeType,
+                fileName: downloaded.fileName,
+                filePath: downloaded.filePath,
+                reason: analysis.replace('MEDIA_ANALYSIS_FAILED: ', ''),
+            })}`);
+            await this.sendReply(msg.chatJid, analysis.replace('MEDIA_ANALYSIS_FAILED: ', 'I received the image, but I could not analyze it yet: '));
+            return;
+        }
+        await this.handleIncomingMessage({
+            ...msg,
+            messageType: 'conversation',
+            textContent: this.promptRegistry.render('media_answer_context', { caption, analysis }),
+        });
+    }
+    /** Route incoming message: OwnerRouter → commands/tools → AI. */
+    /** Single entry point — delegates to ConversationRuntime. */
+    async handleIncomingMessage(msg) {
+        if (!msg.textContent || !this.socketManager)
+            return;
+        const result = await this.runtime.processMessage(msg);
+        if (result.reply) {
+            await this.sendReply(msg.chatJid, result.reply);
+        }
+    }
+    async sendReply(chatJid, text, logRaw) {
+        if (!this.socketManager)
+            return;
+        // Sanitize: strip JSON blocks, code fences, raw data structures
+        let clean = text
+            .replace(/```[\s\S]*?```/g, '')
+            .replace(/\{[\s\S]*?"query"[\s\S]*?\}/g, '')
+            .replace(/\[[\s\S]*?"results"[\s\S]*?\]/g, '')
+            .replace(/  +/g, ' ')
+            .trim();
+        // Enforce WhatsApp-friendly length
+        if (clean.length > 4000)
+            clean = clean.slice(0, 3997) + '...';
+        if (!clean)
+            clean = 'I could not create a safe reply from that result. Please try again or ask the owner to check logs.';
+        await this.socketManager.sendPresenceUpdate('composing', chatJid);
+        await this.socketManager.sendText(chatJid, clean);
+        this.healthMonitor.recordMessageSent();
+        logger.info(`[REPLY] ${chatJid} ← ${clean.slice(0, 50)}...`);
+        // Log raw data for debugging but never send it
+        if (logRaw)
+            logger.debug('[REPLY_RAW]', JSON.stringify(logRaw).slice(0, 500));
+        await this.socketManager.sendPresenceUpdate('paused', chatJid);
+    }
+    getHealth() {
+        return this.healthMonitor.getStatus();
+    }
+    /** Graceful shutdown. */
+    async shutdown() {
+        this.shuttingDown = true;
+        logger.info('Shutting down...');
+        // Clear all save intervals
+        for (const interval of this.saveIntervals) {
+            clearInterval(interval);
+        }
+        this.saveIntervals = [];
+        // Stop async job worker
+        this.asyncJobWorker?.stop();
+        // Stop reconnect attempts
+        this.reconnectManager.destroy();
+        // Stop periodic snapshots
+        this.snapshotService.stopPeriodicSnapshots();
+        // Save auth state one last time
+        try {
+            await this.authStore.save();
+        }
+        catch (err) {
+            logger.error('Failed to save auth state on shutdown:', err.message);
+        }
+        // Disconnect socket
+        if (this.socketManager) {
+            await this.socketManager.disconnect();
+        }
+        // Release session ownership
+        this.sessionManager.releaseOwnership();
+        logger.info('Gateway shut down');
+    }
+}
+// ─── Start ───────────────────────────────────────────────────────────────────
+let gateway = null;
+async function main() {
+    gateway = new Gateway();
+    // Handle graceful shutdown
+    const shutdown = async (signal) => {
+        logger.info(`Received ${signal} — shutting down`);
+        if (gateway)
+            await gateway.shutdown();
+        process.exit(0);
+    };
+    process.on('SIGINT', () => shutdown('SIGINT'));
+    process.on('SIGTERM', () => shutdown('SIGTERM'));
+    process.on('uncaughtException', (err) => {
+        logger.error('Uncaught exception:', err.message);
+        shutdown('uncaughtException').catch(() => process.exit(1));
+    });
+    process.on('unhandledRejection', (reason) => {
+        logger.error('Unhandled rejection:', reason);
+    });
+    await gateway.start();
+}
+main().catch((err) => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});
+export { Gateway };
+//# sourceMappingURL=server.js.map