@agenticmail/core 0.3.4 → 0.5.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'node:events';
-import Database from 'better-sqlite3';
+import Database, { Database as Database$1 } from 'better-sqlite3';
 import { ImapFlow } from 'imapflow';
 
 interface SendMailOptions {
@@ -181,6 +181,13 @@ interface AgenticMailConfig {
         mode?: 'relay' | 'domain' | 'none';
         autoResume?: boolean;
     };
+    sms?: {
+        enabled?: boolean;
+        phoneNumber?: string;
+        forwardingEmail?: string;
+        provider?: 'google_voice';
+        configuredAt?: string;
+    };
     masterKey: string;
     dataDir: string;
 }
@@ -1078,6 +1085,8 @@ declare class GatewayManager {
     private tunnel;
     private dnsConfigurator;
     private domainPurchaser;
+    private smsManager;
+    private smsPollers;
     constructor(options: GatewayManagerOptions);
     /**
      * Check if a message has already been delivered to an agent (deduplication).
@@ -1190,6 +1199,11 @@ declare class GatewayManager {
         success: boolean;
         error?: string;
     }>;
+    /**
+     * Start SMS pollers for all agents that have separate GV Gmail credentials.
+     * Agents with sameAsRelay=true are handled in deliverInboundLocally.
+     */
+    private startSmsPollers;
     shutdown(): Promise<void>;
     /**
      * Resume gateway from saved config (e.g., after server restart).
@@ -1237,6 +1251,144 @@ declare class RelayBridge {
 }
 declare function startRelayBridge(options: RelayBridgeOptions): RelayBridge;
 
+/**
+ * SMS Manager - Google Voice SMS integration
+ *
+ * How it works:
+ * 1. User sets up Google Voice with SMS-to-email forwarding
+ * 2. Incoming SMS arrives at Google Voice -> forwarded to email -> lands in agent inbox
+ * 3. Agent parses forwarded SMS from email body
+ * 4. Outgoing SMS sent via Google Voice web interface (browser automation)
+ *
+ * SMS config is stored in agent metadata under the "sms" key.
+ */
+
+interface SmsConfig {
+    /** Whether SMS is enabled for this agent */
+    enabled: boolean;
+    /** Google Voice phone number (e.g. +12125551234) */
+    phoneNumber: string;
+    /** The email address Google Voice forwards SMS to (the Gmail used for GV signup) */
+    forwardingEmail: string;
+    /** App password for forwarding email (only needed if different from relay email) */
+    forwardingPassword?: string;
+    /** Whether the GV Gmail is the same as the relay email */
+    sameAsRelay?: boolean;
+    /** Provider (currently only google_voice) */
+    provider: 'google_voice';
+    /** When SMS was configured */
+    configuredAt: string;
+}
+interface ParsedSms {
+    from: string;
+    body: string;
+    timestamp: string;
+    raw?: string;
+}
+interface SmsMessage {
+    id: string;
+    agentId: string;
+    direction: 'inbound' | 'outbound';
+    phoneNumber: string;
+    body: string;
+    status: 'pending' | 'sent' | 'delivered' | 'failed' | 'received';
+    createdAt: string;
+    metadata?: Record<string, unknown>;
+}
+/** Normalize a phone number to E.164-ish format (+1XXXXXXXXXX) */
+declare function normalizePhoneNumber(raw: string): string | null;
+/** Validate a phone number (basic) */
+declare function isValidPhoneNumber(phone: string): boolean;
+/**
+ * Parse an SMS forwarded from Google Voice via email.
+ * Google Voice forwards SMS with a specific format.
+ *
+ * Known sender addresses:
+ * - voice-noreply@google.com
+ * - *@txt.voice.google.com
+ * - Google Voice <voice-noreply@google.com>
+ */
+declare function parseGoogleVoiceSms(emailBody: string, emailFrom: string): ParsedSms | null;
+/**
+ * Extract verification codes from SMS body.
+ * Supports common formats: 6-digit, 4-digit, alphanumeric codes.
+ */
+declare function extractVerificationCode(smsBody: string): string | null;
+declare class SmsManager {
+    private db;
+    private initialized;
+    constructor(db: Database$1);
+    private ensureTable;
+    /** Get SMS config from agent metadata */
+    getSmsConfig(agentId: string): SmsConfig | null;
+    /** Save SMS config to agent metadata */
+    saveSmsConfig(agentId: string, config: SmsConfig): void;
+    /** Remove SMS config from agent metadata */
+    removeSmsConfig(agentId: string): void;
+    /** Record an inbound SMS (parsed from email) */
+    recordInbound(agentId: string, parsed: ParsedSms): SmsMessage;
+    /** Record an outbound SMS attempt */
+    recordOutbound(agentId: string, phoneNumber: string, body: string, status?: 'pending' | 'sent' | 'failed'): SmsMessage;
+    /** Update SMS status */
+    updateStatus(id: string, status: SmsMessage['status']): void;
+    /** List SMS messages for an agent */
+    listMessages(agentId: string, opts?: {
+        direction?: 'inbound' | 'outbound';
+        limit?: number;
+        offset?: number;
+    }): SmsMessage[];
+    /** Check for recent verification codes in inbound SMS */
+    checkForVerificationCode(agentId: string, minutesBack?: number): {
+        code: string;
+        from: string;
+        body: string;
+        receivedAt: string;
+    } | null;
+}
+/**
+ * SmsPoller — Polls for Google Voice SMS forwarded emails.
+ *
+ * Two modes:
+ * 1. **Same email** (sameAsRelay=true): Hooks into the relay's onInboundMail callback.
+ *    The relay poll already fetches emails; SmsPoller filters for GV forwarded SMS.
+ * 2. **Separate email** (sameAsRelay=false): Runs its own IMAP poll against the GV Gmail
+ *    using the separate credentials (forwardingEmail + forwardingPassword).
+ *
+ * Parsed SMS messages are stored in the sms_messages table.
+ */
+declare class SmsPoller {
+    private smsManager;
+    private agentId;
+    private config;
+    private pollTimer;
+    private polling;
+    private lastSeenUid;
+    private firstPollDone;
+    private consecutiveFailures;
+    private readonly POLL_INTERVAL_MS;
+    private readonly MAX_BACKOFF_MS;
+    private readonly CONNECT_TIMEOUT_MS;
+    /** Callback for new inbound SMS */
+    onSmsReceived: ((agentId: string, sms: ParsedSms) => void | Promise<void>) | null;
+    constructor(smsManager: SmsManager, agentId: string, config: SmsConfig);
+    /** Whether this poller needs its own IMAP connection (separate Gmail) */
+    get needsSeparatePoll(): boolean;
+    /**
+     * Process an email from the relay poll (same-email mode).
+     * Called by the relay gateway's onInboundMail when it detects a GV email.
+     * Returns true if the email was an SMS and was processed.
+     */
+    processRelayEmail(from: string, subject: string, body: string): boolean;
+    /**
+     * Start polling the separate GV Gmail for SMS (separate-email mode).
+     * Only call this if needsSeparatePoll is true.
+     */
+    startPolling(): Promise<void>;
+    stopPolling(): void;
+    private scheduleNext;
+    private pollOnce;
+}
+
 declare function debug(tag: string, message: string): void;
 declare function debugWarn(tag: string, message: string): void;
 
@@ -1272,14 +1424,15 @@ declare class DependencyInstaller {
      */
     installDocker(): Promise<void>;
     /**
-     * Attempt to start the Docker daemon.
-     * On macOS: opens Docker Desktop app.
-     * On Linux: tries systemctl.
+     * Attempt to start the Docker daemon using multiple strategies.
+     * On macOS: tries Docker Desktop app, then docker CLI commands.
+     * On Linux: tries systemctl, then dockerd direct, then snap.
      */
     private startDockerDaemon;
     /**
-     * Wait for Docker daemon to be ready (up to 3 minutes).
-     * Docker Desktop can take 1-2+ minutes on first launch.
+     * Wait for Docker daemon to be ready, with automatic retry strategies.
+     * Tries multiple approaches to start Docker if the first one fails.
+     * Reports progress as a percentage (0-100).
      */
     private waitForDocker;
     /**
@@ -1371,4 +1524,4 @@ declare class SetupManager {
     isInitialized(): boolean;
 }
 
-export { AGENT_ROLES, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, CloudflareClient, type CreateAgentOptions, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DNSConfigurator, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, type EmailEnvelope, EmailSearchIndex, type FolderInfo, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type InboundEmail, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, type LinkAdvisory, type LocalSmtpConfig, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, type ParsedAttachment, type ParsedEmail, type PurchasedDomain, RELAY_PRESETS, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, SPAM_THRESHOLD, type SanitizeDetection, type SanitizeResult, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, type SetupConfig, SetupManager, type SetupResult, type Severity, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, type TunnelConfig, TunnelManager, WARNING_THRESHOLD, type WatcherOptions, buildInboundSecurityAdvisory, closeDatabase, createTestDatabase, debug, debugWarn, ensureDataDir, getDatabase, isInternalEmail, parseEmail, resolveConfig, sanitizeEmail, saveConfig, scanOutboundEmail, scoreEmail, startRelayBridge };
+export { AGENT_ROLES, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, CloudflareClient, type CreateAgentOptions, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DNSConfigurator, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, type EmailEnvelope, EmailSearchIndex, type FolderInfo, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type InboundEmail, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, type LinkAdvisory, type LocalSmtpConfig, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, type ParsedAttachment, type ParsedEmail, type ParsedSms, type PurchasedDomain, RELAY_PRESETS, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, SPAM_THRESHOLD, type SanitizeDetection, type SanitizeResult, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, type SetupConfig, SetupManager, type SetupResult, type Severity, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, type TunnelConfig, TunnelManager, WARNING_THRESHOLD, type WatcherOptions, buildInboundSecurityAdvisory, closeDatabase, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, getDatabase, isInternalEmail, isValidPhoneNumber, normalizePhoneNumber, parseEmail, parseGoogleVoiceSms, resolveConfig, sanitizeEmail, saveConfig, scanOutboundEmail, scoreEmail, startRelayBridge };

package/dist/index.js

@@ -4433,6 +4433,406 @@ var TunnelManager = class {
 
 // src/gateway/manager.ts
 import MailComposer3 from "nodemailer/lib/mail-composer/index.js";
+
+// src/sms/manager.ts
+function normalizePhoneNumber(raw) {
+  const cleaned = raw.replace(/[^+\d]/g, "");
+  if (!cleaned) return null;
+  const digits = cleaned.replace(/\D/g, "");
+  if (digits.length === 10) return `+1${digits}`;
+  if (digits.length === 11 && digits.startsWith("1")) return `+${digits}`;
+  if (cleaned.startsWith("+") && digits.length >= 10 && digits.length <= 15) return `+${digits}`;
+  if (digits.length < 10) return null;
+  if (digits.length <= 11) return `+1${digits.slice(-10)}`;
+  return null;
+}
+function isValidPhoneNumber(phone) {
+  const normalized = normalizePhoneNumber(phone);
+  if (!normalized) return false;
+  const digits = normalized.replace(/\D/g, "");
+  return digits.length >= 10 && digits.length <= 15;
+}
+function parseGoogleVoiceSms(emailBody, emailFrom) {
+  if (!emailBody || typeof emailBody !== "string") return null;
+  if (!emailFrom || typeof emailFrom !== "string") return null;
+  const fromLower = emailFrom.toLowerCase();
+  const isGoogleVoice = fromLower.includes("voice-noreply@google.com") || fromLower.includes("@txt.voice.google.com") || fromLower.includes("voice.google.com") || fromLower.includes("google.com/voice") || fromLower.includes("google") && fromLower.includes("voice");
+  if (!isGoogleVoice) return null;
+  let text = emailBody.replace(/<br\s*\/?>/gi, "\n").replace(/<\/p>/gi, "\n").replace(/<\/div>/gi, "\n").replace(/<[^>]+>/g, "").replace(/&nbsp;/gi, " ").replace(/&amp;/gi, "&").replace(/&lt;/gi, "<").replace(/&gt;/gi, ">").replace(/&quot;/gi, '"').replace(/&#39;/gi, "'").trim();
+  let from = "";
+  const newMsgMatch = text.match(/new\s+(?:text\s+)?message\s+from\s+(\+?[\d\s().-]+)/i);
+  if (newMsgMatch) {
+    from = newMsgMatch[1];
+  }
+  if (!from) {
+    const colonMatch = text.match(/^(\+?[\d\s().-]{10,})\s*:\s*/m);
+    if (colonMatch) {
+      from = colonMatch[1];
+    }
+  }
+  if (!from) {
+    const firstLines = text.split("\n").slice(0, 5).join(" ");
+    const phoneMatch = firstLines.match(/(\+?1?[-.\s]?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4})/);
+    if (phoneMatch) from = phoneMatch[1];
+  }
+  if (from) {
+    const normalized = normalizePhoneNumber(from);
+    from = normalized || from.replace(/[^+\d]/g, "");
+  }
+  const lines = text.split("\n").map((l) => l.trim()).filter((l) => l);
+  const boilerplatePatterns = [
+    /^new\s+(text\s+)?message\s+from/i,
+    /^\+?1?[-.\s]?\(?\d{3}\)?[-.\s]?\d{3}[-.\s]?\d{4}\s*$/,
+    /^to\s+respond\s+to\s+this/i,
+    /^your\s+account$/i,
+    /^google\s+voice$/i,
+    /^sent\s+via\s+google\s+voice/i,
+    /^you\s+received\s+this/i,
+    /^to\s+stop\s+receiving/i,
+    /^reply\s+to\s+this\s+email/i,
+    /^https?:\/\/voice\.google\.com/i,
+    /^manage\s+your\s+settings/i,
+    /^google\s+llc/i,
+    /^1600\s+amphitheatre/i
+  ];
+  const messageLines = lines.filter((l) => {
+    for (const p of boilerplatePatterns) {
+      if (p.test(l)) return false;
+    }
+    return true;
+  });
+  let body = messageLines.join("\n").trim();
+  const prefixMatch = body.match(/^(\+?[\d\s().-]{10,})\s*:\s*([\s\S]+)/);
+  if (prefixMatch) {
+    body = prefixMatch[2].trim();
+  }
+  if (!body) return null;
+  return {
+    from: from || "unknown",
+    body,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    raw: emailBody
+  };
+}
+function extractVerificationCode(smsBody) {
+  if (!smsBody || typeof smsBody !== "string") return null;
+  const patterns = [
+    // "Your code is 123456" / "verification code: 123456" / "code is: 123456"
+    /(?:code|pin|otp|token|password)\s*(?:is|:)\s*(\d{4,8})/i,
+    // "123456 is your code"
+    /(\d{4,8})\s+is\s+your\s+(?:code|pin|otp|verification)/i,
+    // G-123456 (Google style)
+    /[Gg]-(\d{4,8})/,
+    // "Enter 123456 to verify" / "Use 123456 to"
+    /(?:enter|use)\s+(\d{4,8})\s+(?:to|for|as)/i,
+    // Standalone 6-digit on its own line (common pattern)
+    /^\s*(\d{6})\s*$/m,
+    // "Code: ABC-123" style alphanumeric
+    /(?:code|pin)\s*(?:is|:)\s*([A-Z0-9]{3,6}[-][A-Z0-9]{3,6})/i,
+    // Last resort: any 6-digit sequence not part of a longer number
+    /(?<!\d)(\d{6})(?!\d)/
+  ];
+  for (const pattern of patterns) {
+    const match = smsBody.match(pattern);
+    if (match?.[1]) return match[1];
+  }
+  return null;
+}
+var SmsManager = class {
+  constructor(db2) {
+    this.db = db2;
+    this.ensureTable();
+  }
+  initialized = false;
+  ensureTable() {
+    if (this.initialized) return;
+    try {
+      this.db.exec(`
+        CREATE TABLE IF NOT EXISTS sms_messages (
+          id TEXT PRIMARY KEY,
+          agent_id TEXT NOT NULL,
+          direction TEXT NOT NULL CHECK(direction IN ('inbound', 'outbound')),
+          phone_number TEXT NOT NULL,
+          body TEXT NOT NULL,
+          status TEXT NOT NULL DEFAULT 'pending',
+          created_at TEXT NOT NULL DEFAULT (datetime('now')),
+          metadata TEXT DEFAULT '{}'
+        )
+      `);
+      try {
+        this.db.exec("CREATE INDEX IF NOT EXISTS idx_sms_agent ON sms_messages(agent_id)");
+      } catch {
+      }
+      try {
+        this.db.exec("CREATE INDEX IF NOT EXISTS idx_sms_direction ON sms_messages(direction)");
+      } catch {
+      }
+      try {
+        this.db.exec("CREATE INDEX IF NOT EXISTS idx_sms_created ON sms_messages(created_at)");
+      } catch {
+      }
+      this.initialized = true;
+    } catch (err) {
+      this.initialized = true;
+    }
+  }
+  /** Get SMS config from agent metadata */
+  getSmsConfig(agentId) {
+    const row = this.db.prepare("SELECT metadata FROM agents WHERE id = ?").get(agentId);
+    if (!row) return null;
+    try {
+      const meta = JSON.parse(row.metadata || "{}");
+      return meta.sms && meta.sms.enabled !== void 0 ? meta.sms : null;
+    } catch {
+      return null;
+    }
+  }
+  /** Save SMS config to agent metadata */
+  saveSmsConfig(agentId, config) {
+    const row = this.db.prepare("SELECT metadata FROM agents WHERE id = ?").get(agentId);
+    if (!row) throw new Error(`Agent ${agentId} not found`);
+    let meta;
+    try {
+      meta = JSON.parse(row.metadata || "{}");
+    } catch {
+      meta = {};
+    }
+    meta.sms = config;
+    this.db.prepare("UPDATE agents SET metadata = ?, updated_at = datetime('now') WHERE id = ?").run(JSON.stringify(meta), agentId);
+  }
+  /** Remove SMS config from agent metadata */
+  removeSmsConfig(agentId) {
+    const row = this.db.prepare("SELECT metadata FROM agents WHERE id = ?").get(agentId);
+    if (!row) return;
+    let meta;
+    try {
+      meta = JSON.parse(row.metadata || "{}");
+    } catch {
+      meta = {};
+    }
+    delete meta.sms;
+    this.db.prepare("UPDATE agents SET metadata = ?, updated_at = datetime('now') WHERE id = ?").run(JSON.stringify(meta), agentId);
+  }
+  /** Record an inbound SMS (parsed from email) */
+  recordInbound(agentId, parsed) {
+    const id = `sms_in_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const createdAt = parsed.timestamp || (/* @__PURE__ */ new Date()).toISOString();
+    this.db.prepare(
+      "INSERT INTO sms_messages (id, agent_id, direction, phone_number, body, status, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)"
+    ).run(id, agentId, "inbound", parsed.from, parsed.body, "received", createdAt);
+    return { id, agentId, direction: "inbound", phoneNumber: parsed.from, body: parsed.body, status: "received", createdAt };
+  }
+  /** Record an outbound SMS attempt */
+  recordOutbound(agentId, phoneNumber, body, status = "pending") {
+    const id = `sms_out_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const normalized = normalizePhoneNumber(phoneNumber) || phoneNumber;
+    this.db.prepare(
+      "INSERT INTO sms_messages (id, agent_id, direction, phone_number, body, status, created_at) VALUES (?, ?, ?, ?, ?, ?, ?)"
+    ).run(id, agentId, "outbound", normalized, body, status, now);
+    return { id, agentId, direction: "outbound", phoneNumber: normalized, body, status, createdAt: now };
+  }
+  /** Update SMS status */
+  updateStatus(id, status) {
+    this.db.prepare("UPDATE sms_messages SET status = ? WHERE id = ?").run(status, id);
+  }
+  /** List SMS messages for an agent */
+  listMessages(agentId, opts) {
+    const limit = Math.min(Math.max(opts?.limit ?? 20, 1), 100);
+    const offset = Math.max(opts?.offset ?? 0, 0);
+    let query = "SELECT * FROM sms_messages WHERE agent_id = ?";
+    const params = [agentId];
+    if (opts?.direction && (opts.direction === "inbound" || opts.direction === "outbound")) {
+      query += " AND direction = ?";
+      params.push(opts.direction);
+    }
+    query += " ORDER BY created_at DESC LIMIT ? OFFSET ?";
+    params.push(limit, offset);
+    return this.db.prepare(query).all(...params).map((row) => ({
+      id: row.id,
+      agentId: row.agent_id,
+      direction: row.direction,
+      phoneNumber: row.phone_number,
+      body: row.body,
+      status: row.status,
+      createdAt: row.created_at,
+      metadata: row.metadata ? JSON.parse(row.metadata) : void 0
+    }));
+  }
+  /** Check for recent verification codes in inbound SMS */
+  checkForVerificationCode(agentId, minutesBack = 10) {
+    const safeMins = Math.min(Math.max(minutesBack, 1), 1440);
+    const cutoff = new Date(Date.now() - safeMins * 60 * 1e3).toISOString();
+    const messages = this.db.prepare(
+      "SELECT * FROM sms_messages WHERE agent_id = ? AND direction = ? AND created_at > ? ORDER BY created_at DESC LIMIT 50"
+    ).all(agentId, "inbound", cutoff);
+    for (const msg of messages) {
+      const code = extractVerificationCode(msg.body);
+      if (code) {
+        return { code, from: msg.phone_number, body: msg.body, receivedAt: msg.created_at };
+      }
+    }
+    return null;
+  }
+};
+var SmsPoller = class {
+  constructor(smsManager, agentId, config) {
+    this.smsManager = smsManager;
+    this.agentId = agentId;
+    this.config = config;
+  }
+  pollTimer = null;
+  polling = false;
+  lastSeenUid = 0;
+  firstPollDone = false;
+  consecutiveFailures = 0;
+  POLL_INTERVAL_MS = 3e4;
+  MAX_BACKOFF_MS = 5 * 6e4;
+  CONNECT_TIMEOUT_MS = 3e4;
+  /** Callback for new inbound SMS */
+  onSmsReceived = null;
+  /** Whether this poller needs its own IMAP connection (separate Gmail) */
+  get needsSeparatePoll() {
+    return !this.config.sameAsRelay && !!this.config.forwardingPassword;
+  }
+  /**
+   * Process an email from the relay poll (same-email mode).
+   * Called by the relay gateway's onInboundMail when it detects a GV email.
+   * Returns true if the email was an SMS and was processed.
+   */
+  processRelayEmail(from, subject, body) {
+    const parsed = parseGoogleVoiceSms(body, from);
+    if (!parsed) return false;
+    this.smsManager.recordInbound(this.agentId, parsed);
+    this.onSmsReceived?.(this.agentId, parsed);
+    return true;
+  }
+  /**
+   * Start polling the separate GV Gmail for SMS (separate-email mode).
+   * Only call this if needsSeparatePoll is true.
+   */
+  async startPolling() {
+    if (!this.needsSeparatePoll) return;
+    if (this.polling) return;
+    this.polling = true;
+    console.log(`[SmsPoller] Starting SMS poll for ${this.config.phoneNumber} via ${this.config.forwardingEmail}`);
+    await this.pollOnce();
+    this.scheduleNext();
+  }
+  stopPolling() {
+    this.polling = false;
+    if (this.pollTimer) {
+      clearTimeout(this.pollTimer);
+      this.pollTimer = null;
+    }
+  }
+  scheduleNext() {
+    if (!this.polling) return;
+    const backoff = this.consecutiveFailures > 0 ? Math.min(this.POLL_INTERVAL_MS * Math.pow(2, this.consecutiveFailures - 1), this.MAX_BACKOFF_MS) : this.POLL_INTERVAL_MS;
+    this.pollTimer = setTimeout(async () => {
+      await this.pollOnce();
+      this.scheduleNext();
+    }, backoff);
+  }
+  async pollOnce() {
+    if (!this.config.forwardingEmail || !this.config.forwardingPassword) return;
+    let ImapFlow4;
+    try {
+      ImapFlow4 = (await import("imapflow")).ImapFlow;
+    } catch {
+      console.error("[SmsPoller] imapflow not available");
+      return;
+    }
+    let simpleParser3;
+    try {
+      simpleParser3 = (await import("mailparser")).simpleParser;
+    } catch {
+      console.error("[SmsPoller] mailparser not available");
+      return;
+    }
+    const imap = new ImapFlow4({
+      host: "imap.gmail.com",
+      port: 993,
+      secure: true,
+      auth: {
+        user: this.config.forwardingEmail,
+        pass: this.config.forwardingPassword
+      },
+      logger: false,
+      tls: { rejectUnauthorized: true }
+    });
+    const timeout = setTimeout(() => {
+      try {
+        imap.close();
+      } catch {
+      }
+    }, this.CONNECT_TIMEOUT_MS);
+    try {
+      await imap.connect();
+      clearTimeout(timeout);
+      const lock = await imap.getMailboxLock("INBOX");
+      try {
+        if (!this.firstPollDone) {
+          const status = imap.mailbox;
+          const uidNext = status && typeof status === "object" && "uidNext" in status ? status.uidNext : 1;
+          this.lastSeenUid = Math.max(0, uidNext - 21);
+          this.firstPollDone = true;
+        }
+        let searchResult;
+        try {
+          searchResult = await imap.search(
+            { from: "voice-noreply@google.com", uid: `${this.lastSeenUid + 1}:*` },
+            { uid: true }
+          );
+        } catch {
+          try {
+            searchResult = await imap.search({ all: true }, { uid: true });
+            searchResult = searchResult.filter((uid) => uid > this.lastSeenUid);
+          } catch {
+            return;
+          }
+        }
+        if (!searchResult?.length) return;
+        const uids = searchResult.filter((uid) => uid > this.lastSeenUid);
+        for (const uid of uids) {
+          if (uid > this.lastSeenUid) this.lastSeenUid = uid;
+          try {
+            const msg = await imap.fetchOne(String(uid), { source: true }, { uid: true });
+            const source = msg?.source;
+            if (!source) continue;
+            const parsed = await simpleParser3(source);
+            const fromAddr = parsed.from?.value?.[0]?.address ?? "";
+            const body = parsed.text || parsed.html || "";
+            const sms = parseGoogleVoiceSms(body, fromAddr);
+            if (sms) {
+              this.smsManager.recordInbound(this.agentId, sms);
+              this.onSmsReceived?.(this.agentId, sms);
+            }
+          } catch {
+          }
+        }
+      } finally {
+        lock.release();
+      }
+      if (this.consecutiveFailures > 0) {
+        console.log(`[SmsPoller] Recovered after ${this.consecutiveFailures} failures`);
+      }
+      this.consecutiveFailures = 0;
+      await imap.logout();
+    } catch (err) {
+      clearTimeout(timeout);
+      this.consecutiveFailures++;
+      const msg = err instanceof Error ? err.message : String(err);
+      console.error(`[SmsPoller] Poll failed (${this.consecutiveFailures}): ${msg}`);
+      try {
+        await imap.logout();
+      } catch {
+      }
+    }
+  }
+};
+
+// src/gateway/manager.ts
 var GatewayManager = class {
   constructor(options) {
     this.options = options;
@@ -4449,6 +4849,10 @@ var GatewayManager = class {
     } catch {
       this.config = { mode: "none" };
     }
+    try {
+      this.smsManager = new SmsManager(options.db);
+    } catch {
+    }
   }
   db;
   stalwart;
@@ -4459,6 +4863,8 @@ var GatewayManager = class {
   tunnel = null;
   dnsConfigurator = null;
   domainPurchaser = null;
+  smsManager = null;
+  smsPollers = /* @__PURE__ */ new Map();
   /**
    * Check if a message has already been delivered to an agent (deduplication).
    */
@@ -4487,6 +4893,26 @@ var GatewayManager = class {
       return;
     }
     if (mail.messageId && this.isAlreadyDelivered(mail.messageId, agentName)) return;
+    if (this.smsManager) {
+      try {
+        const smsBody = mail.text || mail.html || "";
+        const parsedSms = parseGoogleVoiceSms(smsBody, mail.from);
+        if (parsedSms) {
+          const agent2 = this.accountManager ? await this.accountManager.getByName(agentName) : null;
+          const agentId = agent2?.id;
+          if (agentId) {
+            const smsConfig = this.smsManager.getSmsConfig(agentId);
+            if (smsConfig?.enabled && smsConfig.sameAsRelay) {
+              this.smsManager.recordInbound(agentId, parsedSms);
+              console.log(`[GatewayManager] SMS received from ${parsedSms.from}: "${parsedSms.body.slice(0, 50)}..." \u2192 agent ${agentName}`);
+              if (mail.messageId) this.recordDelivery(mail.messageId, agentName);
+            }
+          }
+        }
+      } catch (err) {
+        debug("GatewayManager", `SMS detection error: ${err.message}`);
+      }
+    }
     try {
       await this.tryProcessApprovalReply(mail);
     } catch (err) {
@@ -5139,10 +5565,38 @@ var GatewayManager = class {
       return { success: false, error: err instanceof Error ? err.message : String(err) };
     }
   }
+  // --- SMS Polling ---
+  /**
+   * Start SMS pollers for all agents that have separate GV Gmail credentials.
+   * Agents with sameAsRelay=true are handled in deliverInboundLocally.
+   */
+  async startSmsPollers() {
+    if (!this.smsManager || !this.accountManager) return;
+    const agents = this.db.prepare("SELECT id, name, metadata FROM agents").all();
+    for (const agent of agents) {
+      try {
+        const meta = JSON.parse(agent.metadata || "{}");
+        const smsConfig = meta.sms;
+        if (!smsConfig?.enabled || !smsConfig.forwardingPassword || smsConfig.sameAsRelay) continue;
+        const poller = new SmsPoller(this.smsManager, agent.id, smsConfig);
+        poller.onSmsReceived = (agentId, sms) => {
+          console.log(`[SmsPoller] SMS received for agent ${agent.name}: from ${sms.from}, body="${sms.body.slice(0, 50)}..."`);
+        };
+        this.smsPollers.set(agent.id, poller);
+        await poller.startPolling();
+        console.log(`[GatewayManager] SMS poller started for agent "${agent.name}" (${smsConfig.forwardingEmail})`);
+      } catch {
+      }
+    }
+  }
   // --- Lifecycle ---
   async shutdown() {
     await this.relay.shutdown();
     this.tunnel?.stop();
+    for (const poller of this.smsPollers.values()) {
+      poller.stopPolling();
+    }
+    this.smsPollers.clear();
   }
   /**
    * Resume gateway from saved config (e.g., after server restart).
@@ -5162,6 +5616,13 @@ var GatewayManager = class {
         console.error("[GatewayManager] Failed to resume relay:", err);
       }
     }
+    if (this.smsManager && this.accountManager) {
+      try {
+        await this.startSmsPollers();
+      } catch (err) {
+        console.error("[GatewayManager] Failed to start SMS pollers:", err);
+      }
+    }
     if (this.config.mode === "domain" && this.config.domain) {
       try {
         this.cfClient = new CloudflareClient(
@@ -5432,11 +5893,129 @@ var DependencyChecker = class {
 };
 
 // src/setup/installer.ts
-import { execFileSync as execFileSync2, execSync } from "child_process";
+import { execFileSync as execFileSync2, execSync, spawn as spawnChild } from "child_process";
 import { existsSync as existsSync4 } from "fs";
 import { writeFile, rename, chmod as chmod2, mkdir as mkdir2, unlink } from "fs/promises";
 import { join as join6 } from "path";
 import { homedir as homedir5, platform as platform2, arch as arch2 } from "os";
+function runWithRollingOutput(command, args, opts = {}) {
+  const maxLines = opts.maxLines ?? 20;
+  const timeout = opts.timeout ?? 3e5;
+  return new Promise((resolve, reject) => {
+    const child = spawnChild(command, args, {
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout
+    });
+    const lines = [];
+    let displayedCount = 0;
+    let fullOutput = "";
+    const processData = (data) => {
+      const text = data.toString();
+      fullOutput += text;
+      const newLines = text.split("\n");
+      for (const line of newLines) {
+        const trimmed = line.trimEnd();
+        if (!trimmed) continue;
+        lines.push(trimmed);
+        if (displayedCount > 0) {
+          const toClear = Math.min(displayedCount, maxLines);
+          process.stdout.write(`\x1B[${toClear}A`);
+          for (let i = 0; i < toClear; i++) {
+            process.stdout.write("\x1B[2K\n");
+          }
+          process.stdout.write(`\x1B[${toClear}A`);
+        }
+        const visible = lines.slice(-maxLines);
+        for (const vLine of visible) {
+          process.stdout.write(`  \x1B[90m${vLine.slice(0, 100)}\x1B[0m
+`);
+        }
+        displayedCount = visible.length;
+      }
+    };
+    child.stdout?.on("data", processData);
+    child.stderr?.on("data", processData);
+    child.on("close", (code) => {
+      if (displayedCount > 0) {
+        process.stdout.write(`\x1B[${displayedCount}A`);
+        for (let i = 0; i < displayedCount; i++) {
+          process.stdout.write("\x1B[2K\n");
+        }
+        process.stdout.write(`\x1B[${displayedCount}A`);
+      }
+      resolve({ exitCode: code ?? 1, fullOutput });
+    });
+    child.on("error", (err) => {
+      if (displayedCount > 0) {
+        process.stdout.write(`\x1B[${displayedCount}A`);
+        for (let i = 0; i < displayedCount; i++) {
+          process.stdout.write("\x1B[2K\n");
+        }
+        process.stdout.write(`\x1B[${displayedCount}A`);
+      }
+      reject(err);
+    });
+  });
+}
+function runShellWithRollingOutput(cmd, opts = {}) {
+  const maxLines = opts.maxLines ?? 20;
+  const timeout = opts.timeout ?? 3e5;
+  return new Promise((resolve, reject) => {
+    const child = spawnChild("sh", ["-c", cmd], {
+      stdio: ["ignore", "pipe", "pipe"],
+      timeout
+    });
+    const lines = [];
+    let displayedCount = 0;
+    let fullOutput = "";
+    const processData = (data) => {
+      const text = data.toString();
+      fullOutput += text;
+      const newLines = text.split("\n");
+      for (const line of newLines) {
+        const trimmed = line.trimEnd();
+        if (!trimmed) continue;
+        lines.push(trimmed);
+        if (displayedCount > 0) {
+          const toClear = Math.min(displayedCount, maxLines);
+          process.stdout.write(`\x1B[${toClear}A`);
+          for (let i = 0; i < toClear; i++) {
+            process.stdout.write("\x1B[2K\n");
+          }
+          process.stdout.write(`\x1B[${toClear}A`);
+        }
+        const visible = lines.slice(-maxLines);
+        for (const vLine of visible) {
+          process.stdout.write(`  \x1B[90m${vLine.slice(0, 100)}\x1B[0m
+`);
+        }
+        displayedCount = visible.length;
+      }
+    };
+    child.stdout?.on("data", processData);
+    child.stderr?.on("data", processData);
+    child.on("close", (code) => {
+      if (displayedCount > 0) {
+        process.stdout.write(`\x1B[${displayedCount}A`);
+        for (let i = 0; i < displayedCount; i++) {
+          process.stdout.write("\x1B[2K\n");
+        }
+        process.stdout.write(`\x1B[${displayedCount}A`);
+      }
+      resolve({ exitCode: code ?? 1, fullOutput });
+    });
+    child.on("error", (err) => {
+      if (displayedCount > 0) {
+        process.stdout.write(`\x1B[${displayedCount}A`);
+        for (let i = 0; i < displayedCount; i++) {
+          process.stdout.write("\x1B[2K\n");
+        }
+        process.stdout.write(`\x1B[${displayedCount}A`);
+      }
+      reject(err);
+    });
+  });
+}
 var DependencyInstaller = class {
   onProgress;
   constructor(onProgress) {
@@ -5474,14 +6053,20 @@ var DependencyInstaller = class {
       } catch {
         throw new Error("Homebrew is required to install Docker on macOS. Install it from https://brew.sh then try again.");
       }
-      execFileSync2("brew", ["install", "--cask", "docker"], { timeout: 3e5, stdio: "inherit" });
+      const brewResult = await runWithRollingOutput("brew", ["install", "--cask", "docker"], { timeout: 3e5 });
+      if (brewResult.exitCode !== 0) {
+        throw new Error("Failed to install Docker via Homebrew. Try: brew install --cask docker");
+      }
       this.onProgress("Docker installed. Starting Docker Desktop...");
       this.startDockerDaemon();
       await this.waitForDocker();
     } else if (os === "linux") {
       this.onProgress("Installing Docker...");
       try {
-        execSync("curl -fsSL https://get.docker.com | sh", { timeout: 3e5, stdio: "inherit" });
+        const result = await runShellWithRollingOutput("curl -fsSL https://get.docker.com | sh", { timeout: 3e5 });
+        if (result.exitCode !== 0) {
+          throw new Error("Install script failed");
+        }
       } catch {
         throw new Error("Failed to install Docker. Install it manually: https://docs.docker.com/get-docker/");
       }
@@ -5491,48 +6076,123 @@ var DependencyInstaller = class {
     }
   }
   /**
-   * Attempt to start the Docker daemon.
-   * On macOS: opens Docker Desktop app.
-   * On Linux: tries systemctl.
+   * Attempt to start the Docker daemon using multiple strategies.
+   * On macOS: tries Docker Desktop app, then docker CLI commands.
+   * On Linux: tries systemctl, then dockerd direct, then snap.
    */
-  startDockerDaemon() {
+  startDockerDaemon(strategy) {
     const os = platform2();
     if (os === "darwin") {
-      try {
-        execFileSync2("open", ["-a", "Docker"], { timeout: 1e4, stdio: "ignore" });
-      } catch {
+      switch (strategy) {
+        case "cli":
+          try {
+            execSync("docker context use default 2>/dev/null; docker info", { timeout: 5e3, stdio: "ignore" });
+          } catch {
+          }
+          break;
+        case "reopen":
+          try {
+            execSync(`osascript -e 'quit app "Docker"'`, { timeout: 5e3, stdio: "ignore" });
+          } catch {
+          }
+          try {
+            execFileSync2("sleep", ["2"], { timeout: 5e3, stdio: "ignore" });
+          } catch {
+          }
+          try {
+            execFileSync2("open", ["-a", "Docker"], { timeout: 1e4, stdio: "ignore" });
+          } catch {
+          }
+          break;
+        case "background":
+          try {
+            const appBin = "/Applications/Docker.app/Contents/MacOS/Docker";
+            if (existsSync4(appBin)) {
+              execSync(`"${appBin}" &`, { timeout: 5e3, stdio: "ignore", shell: "sh" });
+            }
+          } catch {
+          }
+          break;
+        default:
+          try {
+            execFileSync2("open", ["-a", "Docker"], { timeout: 1e4, stdio: "ignore" });
+          } catch {
+          }
       }
     } else if (os === "linux") {
-      try {
-        execFileSync2("sudo", ["systemctl", "start", "docker"], { timeout: 15e3, stdio: "ignore" });
-      } catch {
+      switch (strategy) {
+        case "snap":
+          try {
+            execFileSync2("sudo", ["snap", "start", "docker"], { timeout: 15e3, stdio: "ignore" });
+          } catch {
+          }
+          break;
+        case "service":
+          try {
+            execFileSync2("sudo", ["service", "docker", "start"], { timeout: 15e3, stdio: "ignore" });
+          } catch {
+          }
+          break;
+        default:
+          try {
+            execFileSync2("sudo", ["systemctl", "start", "docker"], { timeout: 15e3, stdio: "ignore" });
+          } catch {
+          }
       }
     }
   }
   /**
-   * Wait for Docker daemon to be ready (up to 3 minutes).
-   * Docker Desktop can take 1-2+ minutes on first launch.
+   * Wait for Docker daemon to be ready, with automatic retry strategies.
+   * Tries multiple approaches to start Docker if the first one fails.
+   * Reports progress as a percentage (0-100).
    */
   async waitForDocker() {
-    this.onProgress("Waiting for Docker to start (this can take a minute)...");
-    const maxWait = 18e4;
+    const os = platform2();
+    const strategies = os === "darwin" ? ["default", "cli", "reopen", "background"] : ["default", "service", "snap"];
+    const totalTime = 24e4;
+    const perStrategyTime = Math.floor(totalTime / strategies.length);
     const start = Date.now();
-    let attempts = 0;
-    while (Date.now() - start < maxWait) {
+    let strategyIdx = 0;
+    this.onProgress("__progress__:0:Starting Docker...");
+    while (Date.now() - start < totalTime) {
       try {
         execFileSync2("docker", ["info"], { timeout: 5e3, stdio: "ignore" });
+        this.onProgress("__progress__:100:Docker is ready!");
         return;
       } catch {
       }
-      attempts++;
-      if (attempts % 5 === 0) {
-        const elapsed = Math.round((Date.now() - start) / 1e3);
-        this.onProgress(`Still waiting for Docker to start (${elapsed}s)...`);
+      const elapsed = Date.now() - start;
+      const pct = Math.min(95, Math.round(elapsed / totalTime * 100));
+      const currentStrategyElapsed = elapsed - strategyIdx * perStrategyTime;
+      if (currentStrategyElapsed >= perStrategyTime && strategyIdx < strategies.length - 1) {
+        strategyIdx++;
+        const strategy = strategies[strategyIdx];
+        const msgs = {
+          cli: "Trying Docker CLI...",
+          reopen: "Restarting Docker Desktop...",
+          background: "Trying direct launch...",
+          service: "Trying service command...",
+          snap: "Trying snap..."
+        };
+        this.onProgress(`__progress__:${pct}:${msgs[strategy] || "Trying another approach..."}`);
+        this.startDockerDaemon(strategy);
+      } else {
+        const msgs = [
+          "Starting Docker...",
+          "Waiting for Docker engine...",
+          "Docker is loading...",
+          "Almost there...",
+          "Still starting up...",
+          "First launch takes a bit longer...",
+          "Hang tight..."
+        ];
+        const msgIdx = Math.floor(elapsed / 1e4) % msgs.length;
+        this.onProgress(`__progress__:${pct}:${msgs[msgIdx]}`);
       }
       await new Promise((r) => setTimeout(r, 3e3));
     }
     throw new Error(
-      "Docker daemon did not start in time. Open Docker Desktop manually, wait for it to finish loading, then run this again."
+      "DOCKER_MANUAL_START"
     );
   }
   /**
@@ -5549,14 +6209,17 @@ var DependencyInstaller = class {
       this.startDockerDaemon();
       await this.waitForDocker();
     }
-    this.onProgress("Starting Stalwart mail server...");
-    execFileSync2("docker", ["compose", "-f", composePath, "up", "-d"], {
-      timeout: 12e4,
-      stdio: ["ignore", "pipe", "pipe"]
-    });
+    this.onProgress("__progress__:10:Pulling mail server image...");
+    const composeResult = await runWithRollingOutput("docker", ["compose", "-f", composePath, "up", "-d"], { timeout: 12e4 });
+    if (composeResult.exitCode !== 0) {
+      throw new Error("Failed to start mail server container. Check Docker is running.");
+    }
+    this.onProgress("__progress__:60:Waiting for mail server to start...");
     const maxWait = 3e4;
     const start = Date.now();
     while (Date.now() - start < maxWait) {
+      const pct = 60 + Math.round((Date.now() - start) / maxWait * 35);
+      this.onProgress(`__progress__:${Math.min(95, pct)}:Starting mail server...`);
       try {
         const output = execFileSync2(
           "docker",
@@ -5564,6 +6227,7 @@ var DependencyInstaller = class {
           { timeout: 5e3, stdio: ["ignore", "pipe", "ignore"] }
         ).toString().trim();
         if (output.toLowerCase().includes("up")) {
+          this.onProgress("__progress__:100:Mail server ready!");
           return;
         }
       } catch {
@@ -5859,6 +6523,8 @@ export {
   RelayGateway,
   SPAM_THRESHOLD,
   SetupManager,
+  SmsManager,
+  SmsPoller,
   StalwartAdmin,
   TunnelManager,
   WARNING_THRESHOLD,
@@ -5868,9 +6534,13 @@ export {
   debug,
   debugWarn,
   ensureDataDir,
+  extractVerificationCode,
   getDatabase,
   isInternalEmail,
+  isValidPhoneNumber,
+  normalizePhoneNumber,
   parseEmail,
+  parseGoogleVoiceSms,
   resolveConfig,
   sanitizeEmail,
   saveConfig,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/core",
-  "version": "0.3.4",
+  "version": "0.5.0",
   "description": "Core SDK for AgenticMail — programmatic email for AI agents",
   "type": "module",
   "main": "dist/index.js",