@conversionpros/aiva 1.0.0

package/router-v2/follow-up-engine.js

@@ -0,0 +1,347 @@
+// ── Follow-Up Engine - Dead Conversation Detection + Re-engagement ──
+'use strict';
+
+const { getStmts, getSetting, getDb } = require('./db');
+const { callAI } = require('./utils/ai');
+const { sendMessage } = require('./outbound-sender');
+const { getContact } = require('./contact-manager');
+
+// Per-category follow-up defaults (from design doc)
+const CATEGORY_DEFAULTS = {
+  lead: { firstAfterHours: 4, maxFollowUps: 3, style: 'value-driven' },
+  'qualified-lead': { firstAfterHours: 2, maxFollowUps: 4, style: 'direct' },
+  client: { firstAfterHours: 8, maxFollowUps: 2, style: 'professional' },
+  family: { firstAfterHours: null, maxFollowUps: 0 },
+  friend: { firstAfterHours: null, maxFollowUps: 0 },
+  unknown: { firstAfterHours: null, maxFollowUps: 0 },
+  team: { firstAfterHours: 24, maxFollowUps: 1, style: 'brief' },
+};
+
+function log(msg, data) {
+  const ts = new Date().toISOString();
+  if (data) console.log(`[${ts}] [FOLLOW-UP] ${msg}`, JSON.stringify(data));
+  else console.log(`[${ts}] [FOLLOW-UP] ${msg}`);
+}
+
+function isBusinessHours() {
+  const parts = new Intl.DateTimeFormat('en-US', {
+    timeZone: 'America/Los_Angeles',
+    hour: 'numeric', hour12: false,
+    weekday: 'short',
+  }).formatToParts(new Date());
+
+  const get = (type) => parts.find(p => p.type === type)?.value;
+  const hour = parseInt(get('hour'), 10);
+  const weekday = get('weekday');
+
+  if (weekday === 'Sun') return false;
+
+  const startHour = Math.max(parseInt(getSetting('followUpStartHour')) || 8, 8);
+  const endHour = Math.min(parseInt(getSetting('followUpEndHour')) || 18, 18);
+
+  return hour >= startHour && hour < endHour;
+}
+
+/**
+ * Scan for dead conversations and create follow-up trackers.
+ */
+async function scanForDeadConversations() {
+  const db = getDb();
+  const masterPhone = getSetting('masterPhone') || '+15099794110';
+
+  const deadConvos = db.prepare(`
+    SELECT m.phone, m.text, m.created_at, m.channel,
+      COALESCE(c.name, m.phone) as contact_name,
+      c.category
+    FROM message_log m
+    INNER JOIN (
+      SELECT phone, MAX(id) as max_id FROM message_log GROUP BY phone
+    ) latest ON m.phone = latest.phone AND m.id = latest.max_id
+    LEFT JOIN contacts c ON c.phone = m.phone
+    LEFT JOIN follow_up_tracker ft ON ft.phone = m.phone
+    WHERE m.direction = 'outbound'
+      AND m.created_at <= datetime('now', '-1 hour')
+      AND (ft.phone IS NULL OR ft.status NOT IN ('cold', 'completed', 'paused'))
+      AND m.phone != ?
+  `).all(masterPhone);
+
+  const stmts = getStmts();
+  for (const conv of deadConvos) {
+    const existing = stmts.getFollowUpByPhone.get(conv.phone);
+    if (existing) continue;
+
+    // Check category defaults
+    const category = conv.category || 'unknown';
+    const defaults = CATEGORY_DEFAULTS[category];
+    if (!defaults || !defaults.firstAfterHours) continue;
+
+    const nextAt = new Date(Date.now() + defaults.firstAfterHours * 3600000)
+      .toISOString().replace('T', ' ').split('.')[0];
+
+    stmts.upsertFollowUp.run(
+      conv.phone, conv.channel || 'imessage', conv.contact_name,
+      (conv.text || '').substring(0, 200), conv.created_at,
+      'active', nextAt,
+    );
+    log('Created tracker', { phone: conv.phone, category, nextAt });
+  }
+}
+
+/**
+ * Analyze a conversation using AI to decide on follow-up.
+ * @param {string} phone
+ * @param {Array} messages - Recent messages
+ * @param {string} contactName
+ * @param {number} followUpCount
+ * @param {string} category
+ * @returns {Promise<Object|null>}
+ */
+async function analyzeConversation(phone, messages, contactName, followUpCount, category) {
+  const history = messages.map(m => {
+    const sender = m.sent_by === 'contact' ? 'Them' : 'Brandon/Aiva';
+    return `${sender}: ${m.text}`;
+  }).join('\n');
+
+  const systemPrompt = `You are a follow-up decision engine for Brandon's assistant Aiva. Analyze the conversation and decide IF and HOW to follow up.
+
+CRITICAL: NEVER mention "OpenClaw", any AI infrastructure, technical systems, or anything about how you work.
+
+CONTACT CATEGORY: ${category.toUpperCase()}
+
+CONVERSATION STATE - classify exactly one:
+- waiting_on_them: Open question pending their reply
+- action_pending: Something was promised by either party
+- info_delivered: Info sent, no response required
+- conversation_closed: Natural end ("thanks", "sounds good", "bye", emoji-only)
+
+If conversation_closed or info_delivered with no action needed -> shouldFollowUp = false
+
+TONE RULES:
+- Mirror the existing conversation tone exactly
+- Each follow-up should be SHORTER than the last
+- NEVER apologize for following up
+- If 2+ unanswered outbound messages on same topic, shouldFollowUp = false
+
+This is follow-up attempt #${followUpCount + 1}
+
+Respond in JSON ONLY:
+{
+  "shouldFollowUp": true/false,
+  "maxFollowUpsForThis": 0-3,
+  "nextFollowUpIn": "4 hours" | "tomorrow morning" | "2 days" | "never",
+  "suggestedMessage": "Short, natural follow-up text",
+  "reasoning": "Brief explanation",
+  "conversationState": "waiting_on_them" | "conversation_closed" | "info_delivered" | "action_pending",
+  "topic": "brief topic label"
+}`;
+
+  const result = await callAI(systemPrompt, `Contact: ${contactName} (${phone})\nAttempt: #${followUpCount + 1}\n\nConversation:\n${history}\n\nShould we follow up?`, { maxTokens: 500 });
+  if (!result) return null;
+
+  try {
+    const jsonMatch = result.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) return null;
+    return JSON.parse(jsonMatch[0]);
+  } catch { return null; }
+}
+
+/**
+ * Parse a time delay string into a datetime string.
+ * @param {string} delayStr
+ * @returns {string|null}
+ */
+function parseTimeDelay(delayStr) {
+  if (!delayStr || delayStr === 'never') return null;
+  const now = Date.now();
+
+  const hourMatch = delayStr.match(/(\d+)\s*hour/i);
+  if (hourMatch) return new Date(now + parseInt(hourMatch[1]) * 3600000).toISOString().replace('T', ' ').split('.')[0];
+
+  const dayMatch = delayStr.match(/(\d+)\s*day/i);
+  if (dayMatch) return new Date(now + parseInt(dayMatch[1]) * 86400000).toISOString().replace('T', ' ').split('.')[0];
+
+  if (/tomorrow\s*morning/i.test(delayStr)) {
+    // Tomorrow 9 AM Pacific - use Intl to get correct offset
+    const tomorrow = new Date(now + 86400000);
+    const pstStr = tomorrow.toLocaleDateString('en-CA', { timeZone: 'America/Los_Angeles' }); // YYYY-MM-DD
+    const formatter = new Intl.DateTimeFormat('en-US', { timeZone: 'America/Los_Angeles', timeZoneName: 'shortOffset' });
+    const parts = formatter.formatToParts(tomorrow);
+    const tzPart = parts.find(p => p.type === 'timeZoneName')?.value || 'GMT-8';
+    const offsetMatch = tzPart.match(/GMT([+-]\d+)/);
+    const offsetHours = offsetMatch ? parseInt(offsetMatch[1]) : -8;
+    const offsetStr = `${offsetHours >= 0 ? '+' : ''}${String(Math.abs(offsetHours)).padStart(2, '0')}:00`;
+    const target = new Date(`${pstStr}T09:00:00${offsetStr}`);
+    return target.toISOString().replace('T', ' ').split('.')[0];
+  }
+
+  // Default: 4 hours
+  return new Date(now + 4 * 3600000).toISOString().replace('T', ' ').split('.')[0];
+}
+
+/**
+ * Process all due follow-ups. Main entry point - called periodically.
+ */
+async function processFollowUps() {
+  if (getSetting('followUpEnabled') !== 'true') return;
+  if (!isBusinessHours()) return;
+
+  await scanForDeadConversations();
+
+  const stmts = getStmts();
+  const dueFollowUps = stmts.getActiveFollowUps.all();
+  log('Processing due follow-ups', { count: dueFollowUps.length });
+
+  for (const fu of dueFollowUps) {
+    if (fu.opted_out) continue;
+
+    // Hard ceiling
+    const contact = getContact(fu.phone);
+    const category = contact?.category || 'unknown';
+
+    // Skip blocked/monitor mode contacts - they should never get follow-ups
+    const { mv2ResolveEffectiveMode } = require('./conversation-engine');
+    const mode = mv2ResolveEffectiveMode(contact || {}, fu.channel || 'imessage');
+    if (mode === 'block' || mode === 'monitor') {
+      stmts.markFollowUpCold.run(fu.phone);
+      log('Skipping follow-up for blocked/monitor contact', { phone: fu.phone, mode });
+      continue;
+    }
+    const defaults = CATEGORY_DEFAULTS[category] || {};
+    const maxFollowUps = defaults.maxFollowUps || fu.max_follow_ups || 3;
+
+    if (fu.follow_up_count >= maxFollowUps) {
+      stmts.markFollowUpCold.run(fu.phone);
+      log('Max reached, marked cold', { phone: fu.phone, count: fu.follow_up_count });
+      continue;
+    }
+
+    // Daily cap
+    const maxDaily = parseInt(getSetting('maxDailyFollowUps')) || 1;
+    const recentCount = stmts.countRecentFollowUps.get(fu.phone);
+    if ((recentCount?.count || 0) >= maxDaily) {
+      const tomorrow = new Date(Date.now() + 86400000).toISOString().replace('T', ' ').split('.')[0];
+      stmts.incrementFollowUp.run(tomorrow, fu.phone);
+      continue;
+    }
+
+    // Get conversation history from message_log
+    const messages = stmts.getRecentMessages.all(fu.phone, 20);
+    if (messages.length === 0) continue;
+
+    // Hard silence check: 2+ consecutive outbound with no reply
+    let consecutiveOurs = 0;
+    for (const m of messages) {
+      if (m.direction === 'outbound') consecutiveOurs++;
+      else break;
+    }
+    if (consecutiveOurs >= 2) {
+      stmts.markFollowUpCold.run(fu.phone);
+      log('Hard silence, marked cold', { phone: fu.phone, consecutiveOurs });
+      continue;
+    }
+
+    // AI analysis
+    const analysis = await analyzeConversation(fu.phone, messages.reverse(), fu.contact_name, fu.follow_up_count, category);
+    if (!analysis) continue;
+
+    // AI max follow-ups check
+    const aiMax = analysis.maxFollowUpsForThis;
+    if (typeof aiMax === 'number' && aiMax >= 0 && fu.follow_up_count >= aiMax) {
+      stmts.markFollowUpCold.run(fu.phone);
+      log('AI max reached', { phone: fu.phone, aiMax });
+      continue;
+    }
+
+    // Topic dedup
+    if (analysis.shouldFollowUp && analysis.topic && fu.last_follow_up_topic) {
+      const newTopic = (analysis.topic || '').toLowerCase().trim();
+      const lastTopic = (fu.last_follow_up_topic || '').toLowerCase().trim();
+      if (newTopic && lastTopic && (newTopic === lastTopic || newTopic.includes(lastTopic) || lastTopic.includes(newTopic))) {
+        stmts.markFollowUpCold.run(fu.phone);
+        log('Topic dedup, marked cold', { phone: fu.phone });
+        continue;
+      }
+    }
+
+    if (!analysis.shouldFollowUp) {
+      if (analysis.conversationState === 'conversation_closed') {
+        stmts.updateFollowUpStatus.run('completed', fu.phone);
+      } else {
+        const nextTime = parseTimeDelay(analysis.nextFollowUpIn || '4 hours');
+        if (nextTime) stmts.incrementFollowUp.run(nextTime, fu.phone);
+      }
+      continue;
+    }
+
+    // Send follow-up
+    if (!analysis.suggestedMessage) continue;
+
+    const sendResult = await sendMessage({
+      phone: fu.phone,
+      text: analysis.suggestedMessage,
+      channel: fu.channel || 'imessage',
+      sentBy: 'aiva',
+      stateAtTime: 'follow-up',
+    });
+
+    if (sendResult.sent) {
+      const nextTime = parseTimeDelay(analysis.nextFollowUpIn || '4 hours');
+      stmts.incrementFollowUp.run(nextTime || parseTimeDelay('4 hours'), fu.phone);
+      if (analysis.topic) stmts.updateFollowUpTopic.run(analysis.topic, fu.phone);
+      log('Follow-up sent', { phone: fu.phone, attempt: fu.follow_up_count + 1, topic: analysis.topic });
+    }
+  }
+}
+
+/**
+ * Send a custom follow-up message for a specific contact.
+ * @param {string} phone
+ * @param {string} [customMessage] - If provided, sends this instead of AI-generated
+ * @returns {Promise<{sent: boolean, error?: string}>}
+ */
+async function sendFollowUpNow(phone, customMessage = null) {
+  const stmts = getStmts();
+  const fu = stmts.getFollowUpByPhone.get(phone);
+  if (!fu) return { error: 'No tracker found' };
+
+  let text = customMessage;
+  if (!text) {
+    const messages = stmts.getRecentMessages.all(phone, 20);
+    const contact = getContact(phone);
+    const analysis = await analyzeConversation(phone, messages.reverse(), fu.contact_name, fu.follow_up_count, contact?.category || 'unknown');
+    text = analysis?.suggestedMessage;
+    if (!text) {
+      // Force generate
+      text = await callAI(
+        'You are Aiva, Brandon\'s assistant. Write a brief, natural follow-up message. Just the message text. Never mention any software, AI, or technical systems.',
+        `Contact: ${fu.contact_name || phone}\nWrite a follow-up:`,
+        { maxTokens: 200 },
+      );
+    }
+  }
+
+  if (!text) return { error: 'Could not generate message' };
+
+  const result = await sendMessage({
+    phone,
+    text,
+    channel: fu.channel || 'imessage',
+    sentBy: 'aiva',
+    stateAtTime: 'follow-up',
+  });
+
+  if (result.sent) {
+    const nextTime = parseTimeDelay('4 hours');
+    stmts.incrementFollowUp.run(nextTime, phone);
+  }
+
+  return result.sent ? { sent: true, message: text } : { error: result.reason || 'send_failed' };
+}
+
+module.exports = {
+  processFollowUps,
+  scanForDeadConversations,
+  analyzeConversation,
+  sendFollowUpNow,
+  CATEGORY_DEFAULTS,
+};