@agenticmail/core 0.5.40 → 0.5.41

package/dist/index.d.cts

@@ -0,0 +1,1664 @@
+import { EventEmitter } from 'node:events';
+import Database, { Database as Database$1 } from 'better-sqlite3';
+import { ImapFlow } from 'imapflow';
+
+interface SendMailOptions {
+    to: string | string[];
+    subject: string;
+    text?: string;
+    html?: string;
+    cc?: string | string[];
+    bcc?: string | string[];
+    replyTo?: string;
+    inReplyTo?: string;
+    references?: string[];
+    attachments?: Attachment[];
+    headers?: Record<string, string>;
+    /** Display name for the From header, e.g. "Fola from Astrum" */
+    fromName?: string;
+}
+interface Attachment {
+    filename: string;
+    content: Buffer | string;
+    contentType?: string;
+    encoding?: string;
+}
+interface SendResult {
+    messageId: string;
+    envelope: {
+        from: string;
+        to: string[];
+    };
+}
+interface EmailEnvelope {
+    uid: number;
+    seq: number;
+    messageId: string;
+    subject: string;
+    from: AddressInfo[];
+    to: AddressInfo[];
+    date: Date;
+    flags: Set<string>;
+    size: number;
+}
+interface AddressInfo {
+    name?: string;
+    address: string;
+}
+interface ParsedEmail {
+    messageId: string;
+    subject: string;
+    from: AddressInfo[];
+    to: AddressInfo[];
+    cc?: AddressInfo[];
+    replyTo?: AddressInfo[];
+    date: Date;
+    text?: string;
+    html?: string;
+    inReplyTo?: string;
+    references?: string[];
+    attachments: ParsedAttachment[];
+    headers: Map<string, string>;
+}
+interface ParsedAttachment {
+    filename: string;
+    contentType: string;
+    size: number;
+    content: Buffer;
+}
+interface MailboxInfo {
+    name: string;
+    exists: number;
+    recent: number;
+    unseen: number;
+}
+interface SearchCriteria {
+    from?: string;
+    to?: string;
+    subject?: string;
+    since?: Date;
+    before?: Date;
+    seen?: boolean;
+    text?: string;
+}
+
+interface InboxNewEvent {
+    type: 'new';
+    uid: number;
+    message?: ParsedEmail;
+}
+interface InboxExpungeEvent {
+    type: 'expunge';
+    seq: number;
+}
+interface InboxFlagsEvent {
+    type: 'flags';
+    uid: number;
+    flags: Set<string>;
+}
+type InboxEvent = InboxNewEvent | InboxExpungeEvent | InboxFlagsEvent;
+interface WatcherOptions {
+    mailbox?: string;
+    autoFetch?: boolean;
+}
+
+interface InboxWatcherOptions {
+    host: string;
+    port: number;
+    email: string;
+    password: string;
+    secure?: boolean;
+}
+declare class InboxWatcher extends EventEmitter {
+    private options;
+    private client;
+    private watching;
+    private mailbox;
+    private autoFetch;
+    private _lock;
+    constructor(options: InboxWatcherOptions, watcherOptions?: WatcherOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    isWatching(): boolean;
+}
+
+interface AgenticMailClientOptions {
+    agentId: string;
+    apiKey: string;
+    email?: string;
+    password?: string;
+    smtp?: {
+        host: string;
+        port: number;
+    };
+    imap?: {
+        host: string;
+        port: number;
+    };
+    apiUrl?: string;
+}
+declare class AgenticMailClient {
+    private sender;
+    private receiver;
+    private options;
+    private connected;
+    private connectPromise;
+    constructor(options: AgenticMailClientOptions);
+    connect(): Promise<void>;
+    private _connect;
+    disconnect(): Promise<void>;
+    send(mail: SendMailOptions): Promise<SendResult>;
+    inbox(options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<EmailEnvelope[]>;
+    read(uid: number): Promise<ParsedEmail>;
+    search(criteria: SearchCriteria): Promise<number[]>;
+    markSeen(uid: number): Promise<void>;
+    deleteMessage(uid: number): Promise<void>;
+    watch(options?: WatcherOptions): InboxWatcher;
+}
+
+interface AgenticMailConfig {
+    stalwart: {
+        url: string;
+        adminUser: string;
+        adminPassword: string;
+    };
+    smtp: {
+        host: string;
+        port: number;
+    };
+    imap: {
+        host: string;
+        port: number;
+    };
+    api: {
+        port: number;
+        host: string;
+    };
+    gateway?: {
+        mode?: 'relay' | 'domain' | 'none';
+        autoResume?: boolean;
+    };
+    sms?: {
+        enabled?: boolean;
+        phoneNumber?: string;
+        forwardingEmail?: string;
+        provider?: 'google_voice';
+        configuredAt?: string;
+    };
+    masterKey: string;
+    dataDir: string;
+}
+declare function resolveConfig(overrides?: Partial<AgenticMailConfig>): AgenticMailConfig;
+declare function ensureDataDir(config: AgenticMailConfig): void;
+declare function saveConfig(config: AgenticMailConfig): void;
+
+interface StalwartPrincipal {
+    type: 'individual' | 'group' | 'domain' | 'list' | 'apiKey';
+    name: string;
+    secrets?: string[];
+    emails?: string[];
+    description?: string;
+    quota?: number;
+    memberOf?: string[];
+    members?: string[];
+    roles?: string[];
+}
+
+interface StalwartAdminOptions {
+    url: string;
+    adminUser: string;
+    adminPassword: string;
+}
+declare class StalwartAdmin {
+    private options;
+    private baseUrl;
+    private authHeader;
+    constructor(options: StalwartAdminOptions);
+    private request;
+    createPrincipal(principal: StalwartPrincipal): Promise<void>;
+    getPrincipal(name: string): Promise<StalwartPrincipal>;
+    updatePrincipal(name: string, changes: Partial<StalwartPrincipal>): Promise<void>;
+    /** Add an email alias to a principal without removing existing ones */
+    addEmailAlias(name: string, email: string): Promise<void>;
+    deletePrincipal(name: string): Promise<void>;
+    listPrincipals(type?: string): Promise<string[]>;
+    /** Ensure a domain exists in Stalwart (create if missing). */
+    ensureDomain(domain: string): Promise<void>;
+    healthCheck(): Promise<boolean>;
+    /** Get a Stalwart setting value. */
+    getSetting(key: string): Promise<string | undefined>;
+    /** Get all settings under a prefix. */
+    getSettings(prefix: string): Promise<Record<string, string>>;
+    /**
+     * Set a Stalwart configuration value via stalwart-cli.
+     * Note: stalwart-cli may return a 500 error even when the operation succeeds.
+     * We verify by listing the config afterwards.
+     */
+    private cliArgs;
+    updateSetting(key: string, value: string): Promise<void>;
+    /**
+     * Set the server hostname used in SMTP EHLO greetings.
+     * Critical for email deliverability — must match the sending domain.
+     */
+    setHostname(domain: string): Promise<void>;
+    /** Path to the host-side stalwart.toml (mounted read-only into container) */
+    private get configPath();
+    /** Path to host-side DKIM key directory */
+    private get dkimDir();
+    /**
+     * Create/reuse a DKIM signing key for a domain.
+     * Uses stalwart-cli to generate the key and store config in Stalwart's DB.
+     * Returns the public key (base64, no headers) for DNS TXT record.
+     */
+    createDkimSignature(domain: string, selector?: string): Promise<{
+        signatureId: string;
+        publicKey: string;
+    }>;
+    /**
+     * Restart the Stalwart Docker container and wait for it to be ready.
+     */
+    private restartContainer;
+    /**
+     * Check if a DKIM signature exists for a domain (checks Stalwart DB).
+     */
+    hasDkimSignature(domain: string): Promise<boolean>;
+    /**
+     * Configure Gmail SMTP as outbound relay (smarthost).
+     * Routes all non-local mail through smtp.gmail.com using app password auth.
+     * This bypasses the need for a PTR record on the sending IP.
+     */
+    configureOutboundRelay(config: {
+        smtpHost: string;
+        smtpPort: number;
+        username: string;
+        password: string;
+        routeName?: string;
+    }): Promise<void>;
+}
+
+/** Predefined agent roles */
+type AgentRole = 'secretary' | 'assistant' | 'researcher' | 'writer' | 'custom';
+declare const AGENT_ROLES: readonly AgentRole[];
+declare const DEFAULT_AGENT_ROLE: AgentRole;
+declare const DEFAULT_AGENT_NAME = "secretary";
+interface Agent {
+    id: string;
+    name: string;
+    email: string;
+    apiKey: string;
+    stalwartPrincipal: string;
+    createdAt: string;
+    updatedAt: string;
+    metadata: Record<string, unknown>;
+    role: AgentRole;
+}
+interface CreateAgentOptions {
+    name: string;
+    domain?: string;
+    password?: string;
+    metadata?: Record<string, unknown>;
+    gateway?: 'relay' | 'domain';
+    role?: AgentRole;
+}
+
+declare class AccountManager {
+    private db;
+    private stalwart;
+    constructor(db: Database.Database, stalwart: StalwartAdmin);
+    create(options: CreateAgentOptions): Promise<Agent>;
+    getById(id: string): Promise<Agent | null>;
+    getByApiKey(apiKey: string): Promise<Agent | null>;
+    getByName(name: string): Promise<Agent | null>;
+    list(): Promise<Agent[]>;
+    getByRole(role: AgentRole): Promise<Agent[]>;
+    delete(id: string): Promise<boolean>;
+    updateMetadata(id: string, metadata: Record<string, unknown>): Promise<Agent | null>;
+    getCredentials(id: string): Promise<{
+        email: string;
+        password: string;
+        principal: string;
+        smtpHost: string;
+        smtpPort: number;
+        imapHost: string;
+        imapPort: number;
+    } | null>;
+}
+
+interface ArchivedEmail {
+    uid: number;
+    messageId: string;
+    from: string;
+    to: string[];
+    subject: string;
+    date: string;
+    text?: string;
+    html?: string;
+}
+interface DeletionReport {
+    id: string;
+    agent: {
+        id: string;
+        name: string;
+        email: string;
+        role: string;
+        createdAt: string;
+    };
+    deletedAt: string;
+    deletedBy: string;
+    reason?: string;
+    emails: {
+        inbox: ArchivedEmail[];
+        sent: ArchivedEmail[];
+        other: Record<string, ArchivedEmail[]>;
+    };
+    summary: {
+        totalEmails: number;
+        inboxCount: number;
+        sentCount: number;
+        otherCount: number;
+        folders: string[];
+        firstEmailDate?: string;
+        lastEmailDate?: string;
+        topCorrespondents: {
+            address: string;
+            count: number;
+        }[];
+    };
+}
+interface DeletionSummary {
+    id: string;
+    agentName: string;
+    agentEmail: string;
+    agentRole: string | null;
+    deletedAt: string;
+    deletedBy: string | null;
+    reason: string | null;
+    emailCount: number;
+    filePath: string | null;
+}
+interface ArchiveAndDeleteOptions {
+    deletedBy?: string;
+    reason?: string;
+}
+declare class AgentDeletionService {
+    private db;
+    private accountManager;
+    private config;
+    constructor(db: Database.Database, accountManager: AccountManager, config: AgenticMailConfig);
+    archiveAndDelete(agentId: string, options?: ArchiveAndDeleteOptions): Promise<DeletionReport>;
+    getReport(deletionId: string): DeletionReport | null;
+    listReports(): DeletionSummary[];
+    private archiveEmails;
+    private archiveFolder;
+    private buildSummary;
+    private saveToFile;
+    private saveToDatabase;
+}
+
+interface MailSenderOptions {
+    host: string;
+    port: number;
+    email: string;
+    password: string;
+    authUser?: string;
+    secure?: boolean;
+}
+interface SendResultWithRaw extends SendResult {
+    /** Raw RFC822 message bytes (for appending to Sent folder) */
+    raw: Buffer;
+}
+declare class MailSender {
+    private options;
+    private transporter;
+    private email;
+    constructor(options: MailSenderOptions);
+    send(mail: SendMailOptions): Promise<SendResultWithRaw>;
+    verify(): Promise<boolean>;
+    close(): void;
+}
+
+interface MailReceiverOptions {
+    host: string;
+    port: number;
+    email: string;
+    password: string;
+    secure?: boolean;
+}
+declare class MailReceiver {
+    private options;
+    private client;
+    private connected;
+    constructor(options: MailReceiverOptions);
+    connect(): Promise<void>;
+    /** Check if the IMAP client is actually usable */
+    get usable(): boolean;
+    disconnect(): Promise<void>;
+    getMailboxInfo(mailbox?: string): Promise<MailboxInfo>;
+    listEnvelopes(mailbox?: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<EmailEnvelope[]>;
+    fetchMessage(uid: number, mailbox?: string): Promise<Buffer>;
+    search(criteria: SearchCriteria, mailbox?: string): Promise<number[]>;
+    markSeen(uid: number, mailbox?: string): Promise<void>;
+    deleteMessage(uid: number, mailbox?: string): Promise<void>;
+    /** Mark a message as unseen (unread) */
+    markUnseen(uid: number, mailbox?: string): Promise<void>;
+    /** Move a message to another folder */
+    moveMessage(uid: number, fromMailbox: string, toMailbox: string): Promise<void>;
+    /** List all IMAP folders/mailboxes */
+    listFolders(): Promise<FolderInfo[]>;
+    /** Create a new IMAP folder */
+    createFolder(path: string): Promise<void>;
+    /** Batch mark multiple messages as seen */
+    batchMarkSeen(uids: number[], mailbox?: string): Promise<void>;
+    /** Batch mark multiple messages as unseen */
+    batchMarkUnseen(uids: number[], mailbox?: string): Promise<void>;
+    /** Batch delete multiple messages */
+    batchDelete(uids: number[], mailbox?: string): Promise<void>;
+    /** Batch fetch raw message content for multiple UIDs */
+    batchFetch(uids: number[], mailbox?: string): Promise<Map<number, Buffer>>;
+    /** Batch move multiple messages to another folder */
+    batchMove(uids: number[], fromMailbox: string, toMailbox: string): Promise<void>;
+    /** Append a raw RFC822 message to a mailbox (e.g. "Sent") with given flags */
+    appendMessage(raw: Buffer, mailbox: string, flags?: string[]): Promise<void>;
+    getImapClient(): ImapFlow;
+}
+interface FolderInfo {
+    path: string;
+    name: string;
+    specialUse?: string;
+    flags: string[];
+}
+
+declare function parseEmail(raw: Buffer | string): Promise<ParsedEmail>;
+
+type SpamCategory = 'prompt_injection' | 'social_engineering' | 'data_exfiltration' | 'phishing' | 'header_anomaly' | 'content_spam' | 'link_analysis' | 'authentication' | 'attachment_risk';
+interface SpamRuleMatch {
+    ruleId: string;
+    category: SpamCategory;
+    score: number;
+    description: string;
+}
+interface SpamResult {
+    score: number;
+    isSpam: boolean;
+    isWarning: boolean;
+    matches: SpamRuleMatch[];
+    topCategory: SpamCategory | null;
+}
+declare const SPAM_THRESHOLD = 40;
+declare const WARNING_THRESHOLD = 20;
+declare function isInternalEmail(email: ParsedEmail, localDomains?: string[]): boolean;
+declare function scoreEmail(email: ParsedEmail): SpamResult;
+
+interface SanitizeDetection {
+    type: string;
+    description: string;
+    count: number;
+}
+interface SanitizeResult {
+    text: string;
+    html: string;
+    detections: SanitizeDetection[];
+    wasModified: boolean;
+}
+declare function sanitizeEmail(email: ParsedEmail): SanitizeResult;
+
+/**
+ * Outbound Email Guard — scans outgoing emails for sensitive content.
+ * Pure functions, zero external dependencies.
+ */
+type OutboundCategory = 'pii' | 'credential' | 'system_internal' | 'owner_privacy' | 'attachment_risk';
+type Severity = 'high' | 'medium';
+interface OutboundWarning {
+    category: OutboundCategory;
+    severity: Severity;
+    ruleId: string;
+    description: string;
+    match: string;
+}
+interface OutboundScanResult {
+    warnings: OutboundWarning[];
+    hasHighSeverity: boolean;
+    hasMediumSeverity: boolean;
+    blocked: boolean;
+    summary: string;
+}
+interface OutboundScanInput {
+    to: string | string[];
+    subject?: string;
+    text?: string;
+    html?: string;
+    attachments?: Array<{
+        filename?: string;
+        contentType?: string;
+        content?: string | Buffer;
+        encoding?: string;
+    }>;
+}
+interface AttachmentAdvisory {
+    filename: string;
+    risk: string;
+    detail: string;
+}
+interface LinkAdvisory {
+    ruleId: string;
+    detail: string;
+}
+interface SecurityAdvisory {
+    spamScore?: number;
+    spamCategory?: string;
+    isSpam?: boolean;
+    isWarning?: boolean;
+    attachmentWarnings: AttachmentAdvisory[];
+    linkWarnings: LinkAdvisory[];
+    summary: string;
+}
+/**
+ * Scans outgoing email content for sensitive data (PII, credentials, system info, owner privacy).
+ * Skips scanning entirely if ALL recipients are @localhost (internal agent-to-agent communication).
+ */
+declare function scanOutboundEmail(input: OutboundScanInput): OutboundScanResult;
+/**
+ * Builds a structured security advisory from email metadata (spam score, attachments, link warnings).
+ * Used by tool handlers to present per-attachment and per-link warnings to the agent.
+ */
+declare function buildInboundSecurityAdvisory(security: {
+    score?: number;
+    category?: string;
+    isSpam?: boolean;
+    isWarning?: boolean;
+    matches?: Array<{
+        ruleId: string;
+    }>;
+} | undefined, attachments: Array<{
+    filename?: string;
+    contentType?: string;
+    size?: number;
+}> | undefined): SecurityAdvisory;
+
+declare function getDatabase(config: AgenticMailConfig): Database.Database;
+declare function closeDatabase(): void;
+declare function createTestDatabase(): Database.Database;
+
+interface SearchableEmail {
+    agentId: string;
+    messageId: string;
+    subject: string;
+    fromAddress: string;
+    toAddress: string;
+    bodyText: string;
+    receivedAt: string;
+}
+declare class EmailSearchIndex {
+    private db;
+    constructor(db: Database.Database);
+    index(email: SearchableEmail): void;
+    search(agentId: string, query: string, limit?: number): SearchableEmail[];
+    deleteByAgent(agentId: string): void;
+}
+
+interface DomainInfo {
+    domain: string;
+    stalwartPrincipal: string;
+    dkimSelector?: string;
+    dkimPublicKey?: string;
+    verified: boolean;
+    createdAt: string;
+}
+interface DnsRecord {
+    type: 'TXT' | 'CNAME' | 'MX';
+    name: string;
+    value: string;
+    purpose: string;
+}
+interface DomainSetupResult {
+    domain: string;
+    dnsRecords: DnsRecord[];
+}
+
+declare class DomainManager {
+    private db;
+    private stalwart;
+    constructor(db: Database.Database, stalwart: StalwartAdmin);
+    setup(domain: string): Promise<DomainSetupResult>;
+    private generateDnsRecords;
+    get(domain: string): Promise<DomainInfo | null>;
+    list(): Promise<DomainInfo[]>;
+    getDnsRecords(domain: string): Promise<DnsRecord[]>;
+    verify(domain: string): Promise<boolean>;
+    delete(domain: string): Promise<boolean>;
+}
+
+type GatewayMode = 'relay' | 'domain' | 'none';
+type RelayProvider = 'gmail' | 'outlook' | 'custom';
+interface RelayConfig {
+    provider: RelayProvider;
+    email: string;
+    password: string;
+    smtpHost: string;
+    smtpPort: number;
+    imapHost: string;
+    imapPort: number;
+}
+interface DomainModeConfig {
+    domain: string;
+    cloudflareApiToken: string;
+    cloudflareAccountId: string;
+    tunnelId?: string;
+    tunnelToken?: string;
+    /** URL of the Cloudflare Worker outbound relay (e.g. https://agenticmail-outbound.xxx.workers.dev) */
+    outboundWorkerUrl?: string;
+    /** Shared secret for authenticating with the outbound Worker */
+    outboundSecret?: string;
+    /** Shared secret for authenticating inbound webhook from Email Worker */
+    inboundSecret?: string;
+    /** Name of the deployed Email Worker */
+    emailWorkerName?: string;
+}
+interface GatewayConfig {
+    mode: GatewayMode;
+    relay?: RelayConfig;
+    domain?: DomainModeConfig;
+}
+interface GatewayStatus {
+    mode: GatewayMode;
+    healthy: boolean;
+    relay?: {
+        provider: RelayProvider;
+        email: string;
+        polling: boolean;
+    };
+    domain?: {
+        domain: string;
+        dnsConfigured: boolean;
+        tunnelActive: boolean;
+    };
+}
+interface PurchasedDomain {
+    domain: string;
+    registrar: string;
+    cloudflareZoneId?: string;
+    tunnelId?: string;
+    dnsConfigured: boolean;
+    tunnelActive: boolean;
+    purchasedAt: string;
+}
+/** Relay provider presets for SMTP/IMAP connection details */
+declare const RELAY_PRESETS: Record<'gmail' | 'outlook', Pick<RelayConfig, 'smtpHost' | 'smtpPort' | 'imapHost' | 'imapPort'>>;
+interface CloudflareZone {
+    id: string;
+    name: string;
+    status: string;
+    name_servers: string[];
+}
+interface CloudflareDnsRecord {
+    id: string;
+    type: string;
+    name: string;
+    content: string;
+    ttl: number;
+    proxied?: boolean;
+    priority?: number;
+}
+interface CloudflareTunnel {
+    id: string;
+    name: string;
+    status: string;
+    created_at: string;
+    deleted_at?: string | null;
+    connections: Array<{
+        id: string;
+    }>;
+}
+interface CloudflareDomainAvailability {
+    name: string;
+    available: boolean;
+    premium: boolean;
+    price?: number;
+}
+
+interface RelayGatewayOptions {
+    onInboundMail?: (agentName: string, parsed: InboundEmail) => void | Promise<void>;
+    /** Fallback agent name for emails without sub-addressing */
+    defaultAgentName?: string;
+}
+interface InboundEmail {
+    messageId: string;
+    from: string;
+    to: string;
+    subject: string;
+    text?: string;
+    html?: string;
+    date: Date;
+    inReplyTo?: string;
+    references?: string[];
+    attachments?: Array<{
+        filename: string;
+        contentType: string;
+        size: number;
+        content: Buffer;
+    }>;
+}
+/**
+ * RelayGateway handles sending/receiving email through an existing
+ * Gmail/Outlook account using sub-addressing (user+agent@gmail.com).
+ */
+declare class RelayGateway {
+    private smtpTransport;
+    private pollTimer;
+    private polling;
+    private config;
+    private onInboundMail;
+    private defaultAgentName;
+    private _pollInProgress;
+    /** Track highest UID seen so we only process new messages after first poll */
+    private lastSeenUid;
+    private firstPollDone;
+    /** Callback invoked when lastSeenUid advances (for persistence) */
+    onUidAdvance: ((uid: number) => void) | null;
+    /** Map sent messageId → agentName for In-Reply-To based routing */
+    private sentMessageIds;
+    /** Robustness: consecutive failure tracking + backoff */
+    private consecutiveFailures;
+    private pollIntervalMs;
+    private readonly MAX_BACKOFF_MS;
+    private readonly CONNECT_TIMEOUT_MS;
+    constructor(options?: RelayGatewayOptions);
+    setup(config: RelayConfig): Promise<void>;
+    /**
+     * Send an email through the relay SMTP server.
+     * Rewrites the From address to use sub-addressing: relay+agentName@gmail.com
+     */
+    sendViaRelay(agentName: string, mail: SendMailOptions): Promise<SendResultWithRaw>;
+    /**
+     * Start polling the relay IMAP account for new emails.
+     * Routes inbound mail to the correct agent based on sub-addressing or In-Reply-To.
+     *
+     * Robust design:
+     * - Uses setTimeout (not setInterval) so backoff works naturally
+     * - Exponential backoff on consecutive failures (30s → 1m → 2m → 5m cap)
+     * - Always reschedules — polling never permanently stops
+     * - Connection timeout prevents hung connections
+     * - Detailed failure logging with recovery info
+     */
+    startPolling(intervalMs?: number): Promise<void>;
+    stopPolling(): void;
+    /** Calculate next poll delay with exponential backoff on failures */
+    private getNextPollDelay;
+    /** Schedule the next poll with appropriate delay */
+    private scheduleNextPoll;
+    private pollOnce;
+    private _doPoll;
+    /**
+     * Check if an email address is one of our relay sender addresses (user+agent@domain).
+     */
+    private isOurRelaySender;
+    /**
+     * Extract agent name from email using multiple strategies:
+     * 1. Sub-address in To/CC/Delivered-To/X-Original-To headers
+     * 2. In-Reply-To matching against sent message IDs
+     * 3. References chain matching against sent message IDs
+     */
+    private extractAgentName;
+    /**
+     * Register a sent message ID for reply tracking.
+     * Called externally when messages are sent via relay from GatewayManager.
+     */
+    trackSentMessage(messageId: string, agentName: string): void;
+    /**
+     * Restore lastSeenUid from persistent storage (used on resume after restart).
+     * If the restored UID is > 0, also marks firstPollDone to skip the initial window scan.
+     */
+    setLastSeenUid(uid: number): void;
+    isConfigured(): boolean;
+    isPolling(): boolean;
+    getConfig(): RelayConfig | null;
+    /**
+     * Search the relay IMAP account (Gmail/Outlook) for emails matching criteria.
+     * Returns parsed envelope data so results can be merged with local search.
+     */
+    searchRelay(criteria: {
+        from?: string;
+        to?: string;
+        subject?: string;
+        text?: string;
+        since?: Date;
+        before?: Date;
+        seen?: boolean;
+    }, maxResults?: number): Promise<RelaySearchResult[]>;
+    /**
+     * Fetch a full email from the relay account by UID and return it as an InboundEmail.
+     * Used to import a specific email from Gmail/Outlook into the local inbox.
+     */
+    fetchRelayMessage(uid: number): Promise<InboundEmail | null>;
+    shutdown(): Promise<void>;
+}
+interface RelaySearchResult {
+    uid: number;
+    source: 'relay';
+    account: string;
+    messageId: string;
+    subject: string;
+    from: Array<{
+        name?: string;
+        address: string;
+    }>;
+    to: Array<{
+        name?: string;
+        address: string;
+    }>;
+    date: Date;
+    flags: string[];
+}
+
+declare class CloudflareClient {
+    private token;
+    private accountId;
+    constructor(token: string, accountId: string);
+    listZones(): Promise<CloudflareZone[]>;
+    getZone(domain: string): Promise<CloudflareZone | null>;
+    createZone(domain: string): Promise<CloudflareZone>;
+    listDnsRecords(zoneId: string): Promise<CloudflareDnsRecord[]>;
+    createDnsRecord(zoneId: string, record: {
+        type: string;
+        name: string;
+        content: string;
+        ttl?: number;
+        priority?: number;
+        proxied?: boolean;
+    }): Promise<CloudflareDnsRecord>;
+    deleteDnsRecord(zoneId: string, recordId: string): Promise<void>;
+    searchDomains(query: string): Promise<CloudflareDomainAvailability[]>;
+    checkAvailability(domain: string): Promise<CloudflareDomainAvailability>;
+    purchaseDomain(domain: string, autoRenew?: boolean): Promise<{
+        domain: string;
+        status: string;
+    }>;
+    listRegisteredDomains(): Promise<Array<{
+        domain: string;
+        status: string;
+    }>>;
+    createTunnel(name: string): Promise<CloudflareTunnel>;
+    getTunnel(tunnelId: string): Promise<CloudflareTunnel>;
+    getTunnelToken(tunnelId: string): Promise<string>;
+    createTunnelRoute(tunnelId: string, hostname: string, service: string, options?: {
+        apiService?: string;
+    }): Promise<void>;
+    deleteTunnel(tunnelId: string): Promise<void>;
+    /** Enable Email Routing on a zone */
+    enableEmailRouting(zoneId: string): Promise<void>;
+    /** Disable Email Routing on a zone (unlocks managed MX/SPF records for deletion) */
+    disableEmailRouting(zoneId: string): Promise<void>;
+    /** Get Email Routing status for a zone */
+    getEmailRoutingStatus(zoneId: string): Promise<{
+        enabled: boolean;
+        status: string;
+    }>;
+    /** Set catch-all rule to forward to a Worker */
+    setCatchAllWorkerRule(zoneId: string, workerName: string): Promise<void>;
+    /** Deploy an Email Worker script (ES module format) */
+    deployEmailWorker(scriptName: string, scriptContent: string, envVars?: Record<string, string>): Promise<void>;
+    /** Delete a Worker script */
+    deleteWorker(scriptName: string): Promise<void>;
+    listTunnels(): Promise<CloudflareTunnel[]>;
+    private request;
+}
+
+interface DomainSearchResult {
+    domain: string;
+    available: boolean;
+    premium: boolean;
+    price?: number;
+}
+interface DomainPurchaseResult {
+    domain: string;
+    status: string;
+}
+/**
+ * DomainPurchaser handles searching for and purchasing domains
+ * via Cloudflare Registrar.
+ */
+declare class DomainPurchaser {
+    private cf;
+    constructor(cf: CloudflareClient);
+    /**
+     * Search for available domains matching the given keywords.
+     * Appends common TLDs to keywords and checks availability.
+     */
+    searchAvailable(keywords: string[], tlds?: string[]): Promise<DomainSearchResult[]>;
+    /**
+     * Purchase a domain via Cloudflare Registrar.
+     * NOTE: Cloudflare API tokens only support READ access for registrar.
+     * Domain purchases must be done manually via the Cloudflare dashboard
+     * or another registrar (then point nameservers to Cloudflare).
+     */
+    purchase(_domain: string, _autoRenew?: boolean): Promise<DomainPurchaseResult>;
+    /**
+     * Check the registration status of a purchased domain.
+     */
+    getStatus(domain: string): Promise<{
+        domain: string;
+        status: string;
+    }>;
+    /**
+     * List all domains registered under the Cloudflare account.
+     */
+    listRegistered(): Promise<Array<{
+        domain: string;
+        status: string;
+    }>>;
+}
+
+interface DnsSetupResult {
+    records: Array<{
+        type: string;
+        name: string;
+        content: string;
+        purpose: string;
+    }>;
+    removed: Array<{
+        type: string;
+        name: string;
+        content: string;
+        reason: string;
+    }>;
+}
+/**
+ * DNSConfigurator automatically creates MX, SPF, DKIM, and DMARC
+ * DNS records for a domain using the Cloudflare API.
+ * Replaces conflicting records (old MX, SPF, A records) to ensure clean setup.
+ */
+declare class DNSConfigurator {
+    private cf;
+    constructor(cf: CloudflareClient);
+    /**
+     * Configure all DNS records required for email on a domain.
+     * Replaces existing MX and SPF records that conflict with AgenticMail.
+     */
+    /**
+     * Detect the server's public IPv4 address for SPF records.
+     */
+    detectPublicIp(): Promise<string | null>;
+    configureForEmail(domain: string, zoneId: string, options?: {
+        dkimSelector?: string;
+        dkimPublicKey?: string;
+        serverIp?: string;
+    }): Promise<DnsSetupResult>;
+    /**
+     * Configure DNS records to point the domain at a Cloudflare Tunnel.
+     * Removes conflicting A/AAAA records for the root domain first.
+     */
+    configureForTunnel(domain: string, zoneId: string, tunnelId: string): Promise<DnsSetupResult['removed']>;
+    /**
+     * Verify DNS propagation by resolving MX and TXT records.
+     */
+    verify(domain: string): Promise<{
+        mx: boolean;
+        spf: boolean;
+        dmarc: boolean;
+    }>;
+}
+
+interface TunnelConfig {
+    tunnelId: string;
+    tunnelToken: string;
+}
+/**
+ * TunnelManager handles the Cloudflare Tunnel lifecycle:
+ * downloading cloudflared, creating/starting tunnels, and routing ingress.
+ */
+declare class TunnelManager {
+    private cf;
+    private process;
+    private running;
+    private binPath;
+    constructor(cf: CloudflareClient);
+    /**
+     * Find or download the cloudflared binary.
+     * Checks: managed binary → system-wide → download.
+     */
+    install(): Promise<string>;
+    /**
+     * Create a new Cloudflare Tunnel via the API.
+     * If a tunnel with the same name already exists, reuse it.
+     */
+    create(name: string): Promise<TunnelConfig>;
+    /**
+     * Start the cloudflared tunnel process.
+     */
+    start(tunnelToken: string): Promise<void>;
+    /**
+     * Configure tunnel ingress rules: route mail.{domain} → SMTP, {domain} → HTTP
+     */
+    createIngress(tunnelId: string, domain: string, smtpPort?: number, httpPort?: number, apiPort?: number): Promise<void>;
+    /**
+     * Stop the running cloudflared process.
+     */
+    stop(): Promise<void>;
+    /**
+     * Check if the tunnel is currently running.
+     */
+    status(): {
+        running: boolean;
+        pid?: number;
+    };
+    /**
+     * Check tunnel health via the Cloudflare API.
+     */
+    healthCheck(tunnelId: string): Promise<{
+        healthy: boolean;
+        status: string;
+    }>;
+}
+
+interface LocalSmtpConfig {
+    host: string;
+    port: number;
+    user: string;
+    pass: string;
+}
+interface GatewayManagerOptions {
+    db: Database.Database;
+    stalwart: StalwartAdmin;
+    accountManager?: AccountManager;
+    localSmtp?: LocalSmtpConfig;
+    onInboundMail?: (agentName: string, mail: InboundEmail) => void | Promise<void>;
+    /** Master key used to encrypt credentials at rest in SQLite. */
+    encryptionKey?: string;
+}
+/**
+ * GatewayManager orchestrates relay and domain modes for sending/receiving
+ * real internet email. It coordinates between the relay gateway, Cloudflare
+ * services (DNS, tunnels, registrar), and the local Stalwart instance.
+ */
+declare class GatewayManager {
+    private options;
+    private db;
+    private stalwart;
+    private accountManager;
+    private relay;
+    private config;
+    private cfClient;
+    private tunnel;
+    private dnsConfigurator;
+    private domainPurchaser;
+    private smsManager;
+    private smsPollers;
+    private encryptionKey;
+    constructor(options: GatewayManagerOptions);
+    /**
+     * Check if a message has already been delivered to an agent (deduplication).
+     */
+    isAlreadyDelivered(messageId: string, agentName: string): boolean;
+    /**
+     * Record that a message was delivered to an agent.
+     */
+    recordDelivery(messageId: string, agentName: string): void;
+    /**
+     * Built-in inbound mail handler: delivers relay inbound mail to agent's local Stalwart mailbox.
+     * Authenticates as the agent to send to their own mailbox (Stalwart requires sender = auth user).
+     *
+     * Also intercepts owner replies to approval notification emails — if the reply says
+     * "approve" or "reject", the pending outbound email is automatically processed.
+     */
+    private deliverInboundLocally;
+    /**
+     * Check if an inbound email is a reply to a pending approval notification.
+     * If the reply body starts with "approve"/"yes" or "reject"/"no", automatically
+     * process the pending email (send it or discard it) and confirm to the owner.
+     */
+    private tryProcessApprovalReply;
+    /**
+     * Execute approval of a pending outbound email: look up the agent, reconstitute
+     * attachments, and send the email via gateway routing or local SMTP.
+     */
+    private executeApproval;
+    /**
+     * Send a confirmation email back to the owner after processing an approval reply.
+     */
+    private sendApprovalConfirmation;
+    setupRelay(config: RelayConfig, options?: {
+        defaultAgentName?: string;
+        defaultAgentRole?: AgentRole;
+        skipDefaultAgent?: boolean;
+    }): Promise<{
+        agent?: Agent;
+    }>;
+    setupDomain(options: {
+        cloudflareToken: string;
+        cloudflareAccountId: string;
+        domain?: string;
+        purchase?: {
+            keywords: string[];
+            tld?: string;
+        };
+        outboundWorkerUrl?: string;
+        outboundSecret?: string;
+        gmailRelay?: {
+            email: string;
+            appPassword: string;
+        };
+    }): Promise<{
+        domain: string;
+        dnsConfigured: boolean;
+        tunnelId: string;
+        outboundRelay?: {
+            configured: boolean;
+            provider: string;
+        };
+        nextSteps?: string[];
+    }>;
+    /**
+     * Send a test email through the gateway without requiring a real agent.
+     * In relay mode, uses "test" as the sub-address.
+     * In domain mode, uses the first available agent (Stalwart needs real credentials).
+     */
+    sendTestEmail(to: string): Promise<SendResultWithRaw | null>;
+    /**
+     * Route an outbound email. If the destination is external and a gateway
+     * is configured, send via the appropriate channel.
+     * Returns null if the mail should be sent via local Stalwart.
+     */
+    routeOutbound(agentName: string, mail: SendMailOptions): Promise<SendResultWithRaw | null>;
+    /**
+     * Send email by submitting to local Stalwart via SMTP (port 587).
+     * Stalwart handles DKIM signing and delivery (direct or via relay).
+     * Reply-To is set to the agent's domain email so replies come back
+     * to the domain (handled by Cloudflare Email Routing → inbound Worker).
+     */
+    private sendViaStalwart;
+    getStatus(): GatewayStatus;
+    getMode(): GatewayMode;
+    getConfig(): GatewayConfig;
+    getStalwart(): StalwartAdmin;
+    getDomainPurchaser(): DomainPurchaser | null;
+    getDNSConfigurator(): DNSConfigurator | null;
+    getTunnelManager(): TunnelManager | null;
+    getRelay(): RelayGateway;
+    /**
+     * Search the connected relay account (Gmail/Outlook) for emails matching criteria.
+     * Returns empty array if relay is not configured.
+     */
+    searchRelay(criteria: {
+        from?: string;
+        to?: string;
+        subject?: string;
+        text?: string;
+        since?: Date;
+        before?: Date;
+        seen?: boolean;
+    }, maxResults?: number): Promise<RelaySearchResult[]>;
+    /**
+     * Import an email from the connected relay account into an agent's local inbox.
+     * Fetches the full message from relay IMAP and delivers it locally, preserving
+     * all headers (Message-ID, In-Reply-To, References) for thread continuity.
+     */
+    importRelayMessage(relayUid: number, agentName: string): Promise<{
+        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).
+     */
+    resume(): Promise<void>;
+    private loadConfig;
+    private saveConfig;
+    private saveLastSeenUid;
+    private loadLastSeenUid;
+}
+
+interface RelayBridgeOptions {
+    /** Port for the HTTP bridge server */
+    port: number;
+    /** Shared secret for authenticating requests */
+    secret: string;
+    /** Local Stalwart SMTP host (default: 127.0.0.1) */
+    smtpHost?: string;
+    /** Local Stalwart SMTP submission port (default: 587) */
+    smtpPort?: number;
+    /** Stalwart auth credentials for the sending agent */
+    smtpUser: string;
+    smtpPass: string;
+}
+/**
+ * RelayBridge — A local HTTP-to-SMTP bridge that submits email to Stalwart.
+ *
+ * Stalwart then handles DKIM signing, MX resolution, and direct delivery
+ * to the recipient's mail server on port 25. FROM is preserved exactly.
+ *
+ * This bridge is exposed via Cloudflare Tunnel so Cloudflare Workers
+ * (which can't connect to port 25) can trigger outbound email through it.
+ *
+ * For production, deploy on a VPS with proper PTR/FCrDNS for reliable
+ * delivery to all providers (Gmail, Outlook, etc.).
+ */
+declare class RelayBridge {
+    private server;
+    private options;
+    constructor(options: RelayBridgeOptions);
+    start(): Promise<void>;
+    stop(): void;
+    private handleRequest;
+    private submitToStalwart;
+}
+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;
+}
+
+/**
+ * AgenticMail Anonymous Telemetry
+ *
+ * Collects anonymous usage counts to help improve the product.
+ * NO personal data, API keys, emails, or content is ever collected.
+ *
+ * Opt out: set AGENTICMAIL_TELEMETRY=0 or DO_NOT_TRACK=1
+ *
+ * What we collect:
+ * - Tool call counts (which tools are popular)
+ * - Package version
+ * - Anonymous install ID (random UUID, no PII)
+ * - OS platform (e.g. "darwin", "linux")
+ */
+/** Set the package version for telemetry events */
+declare function setTelemetryVersion(version: string): void;
+/** Record a tool call (fire-and-forget, never throws) */
+declare function recordToolCall(toolName: string): void;
+/** Flush remaining events on process exit */
+declare function flushTelemetry(): void;
+
+declare function debug(tag: string, message: string): void;
+declare function debugWarn(tag: string, message: string): void;
+
+interface DependencyStatus {
+    name: string;
+    installed: boolean;
+    version?: string;
+    description: string;
+}
+/**
+ * DependencyChecker detects which external tools are available.
+ * All dependencies are required — setup will auto-install any missing ones.
+ */
+declare class DependencyChecker {
+    checkAll(): Promise<DependencyStatus[]>;
+    checkDocker(): Promise<DependencyStatus>;
+    checkStalwart(): Promise<DependencyStatus>;
+    checkCloudflared(): Promise<DependencyStatus>;
+}
+
+type InstallProgress = (message: string) => void;
+/**
+ * DependencyInstaller handles installing all external dependencies.
+ * Uses Colima + Docker CLI on macOS (no Docker Desktop GUI).
+ * Uses Docker Engine directly on Linux.
+ */
+declare class DependencyInstaller {
+    private onProgress;
+    constructor(onProgress?: InstallProgress);
+    /**
+     * Ensure Docker is installed AND the daemon is running.
+     *
+     * Flow:
+     *   1. docker info works? → done
+     *   2. docker CLI + colima exist but not running? → colima start
+     *   3. Nothing installed? → install via brew (colima + docker) or Docker Engine (Linux)
+     */
+    installDocker(): Promise<void>;
+    /** Check if `docker info` succeeds (CLI + daemon both working). */
+    private isDockerReady;
+    /**
+     * macOS: Install Docker via Colima (CLI-only, no GUI, no license dialogs).
+     * Installs colima + docker + docker-compose via Homebrew, then starts Colima.
+     */
+    private installDockerMac;
+    /**
+     * Link docker-compose as a Docker CLI plugin so `docker compose` (v2 syntax) works.
+     * Brew installs docker-compose as a standalone binary, but many tools expect
+     * the `docker compose` subcommand.
+     */
+    private linkComposePlugin;
+    /**
+     * Start Colima and wait for Docker to be ready.
+     */
+    private startColima;
+    /**
+     * Install Docker Engine on Linux using Docker's official convenience script.
+     * Also adds the current user to the docker group for rootless usage.
+     */
+    private installDockerLinux;
+    /**
+     * Wait for Docker daemon on Linux.
+     */
+    private waitForDockerLinux;
+    /**
+     * Windows: Install Docker via WSL2 + Docker Engine, or guide user to Docker Desktop.
+     * Prefers WSL2 with Docker Engine (no GUI needed).
+     */
+    private installDockerWindows;
+    /**
+     * Wait for Docker daemon on Windows.
+     */
+    private waitForDockerWindows;
+    /**
+     * Start the Stalwart mail server Docker container.
+     */
+    startStalwart(composePath: string): Promise<void>;
+    /**
+     * Download and install cloudflared to ~/.agenticmail/bin/cloudflared.
+     * Returns the path to the installed binary.
+     */
+    installCloudflared(): Promise<string>;
+    /**
+     * Install all dependencies. Checks each one and installs if missing.
+     */
+    installAll(composePath: string): Promise<void>;
+}
+
+interface ServiceStatus {
+    installed: boolean;
+    running: boolean;
+    platform: 'launchd' | 'systemd' | 'unsupported';
+    servicePath: string | null;
+}
+/**
+ * ServiceManager handles auto-start on boot for the AgenticMail API server.
+ * - macOS: LaunchAgent plist (user-level, no sudo needed)
+ * - Linux: systemd user service (user-level, no sudo needed)
+ */
+declare class ServiceManager {
+    private os;
+    /**
+     * Get the path to the service file.
+     */
+    private getServicePath;
+    /**
+     * Find the Node.js binary path.
+     */
+    private getNodePath;
+    /**
+     * Find the API server entry point.
+     * Searches common locations where agenticmail is installed.
+     */
+    private getApiEntryPath;
+    /**
+     * Cache the API entry path so the service can find it later.
+     */
+    cacheApiEntryPath(entryPath: string): void;
+    /**
+     * Get the current package version.
+     */
+    private getVersion;
+    /**
+     * Generate a wrapper script that waits for Docker before starting the API.
+     * This ensures AgenticMail doesn't fail on boot when Docker is still loading.
+     */
+    private generateStartScript;
+    /**
+     * Generate the launchd plist content for macOS.
+     * More robust than OpenClaw's plist:
+     * - Wrapper script waits for Docker + Stalwart before starting
+     * - KeepAlive: true (unconditional — always restart, not just on crash)
+     * - SoftResourceLimits for file descriptors (email servers need many)
+     * - StartInterval as backup heartbeat (checks every 5 min)
+     * - Service version tracking in env vars
+     */
+    private generatePlist;
+    /**
+     * Generate the systemd user service content for Linux.
+     * More robust than basic services:
+     * - Wrapper script waits for Docker + Stalwart
+     * - Restart=always (unconditional)
+     * - WatchdogSec for health monitoring
+     * - File descriptor limits
+     * - Proper dependency ordering
+     */
+    private generateSystemdUnit;
+    /**
+     * Install the auto-start service.
+     */
+    install(): {
+        installed: boolean;
+        message: string;
+    };
+    /**
+     * Uninstall the auto-start service.
+     */
+    uninstall(): {
+        removed: boolean;
+        message: string;
+    };
+    /**
+     * Get the current service status.
+     */
+    status(): ServiceStatus;
+    /**
+     * Reinstall the service (useful after config changes or updates).
+     */
+    reinstall(): {
+        installed: boolean;
+        message: string;
+    };
+}
+
+interface SetupConfig {
+    masterKey: string;
+    stalwart: {
+        url: string;
+        adminUser: string;
+        adminPassword: string;
+    };
+    smtp: {
+        host: string;
+        port: number;
+    };
+    imap: {
+        host: string;
+        port: number;
+    };
+    api: {
+        port: number;
+        host: string;
+    };
+    dataDir: string;
+}
+interface SetupResult {
+    configPath: string;
+    envPath: string;
+    config: SetupConfig;
+    isNew: boolean;
+}
+/**
+ * SetupManager orchestrates AgenticMail initialization:
+ * config generation, dependency installation, and service startup.
+ * All dependencies are required and auto-installed.
+ */
+declare class SetupManager {
+    private checker;
+    private installer;
+    constructor(onProgress?: InstallProgress);
+    /**
+     * Check all dependencies and return their status.
+     */
+    checkDependencies(): Promise<DependencyStatus[]>;
+    /**
+     * Install all missing dependencies automatically.
+     * Docker → Stalwart → cloudflared. Nothing is optional.
+     */
+    installAll(composePath: string): Promise<void>;
+    /**
+     * Ensure a specific dependency is installed.
+     */
+    ensureDocker(): Promise<void>;
+    ensureStalwart(composePath?: string): Promise<void>;
+    ensureCloudflared(): Promise<string>;
+    /**
+     * Get the path to docker-compose.yml.
+     * Prefers ~/.agenticmail/docker-compose.yml (standalone),
+     * falls back to monorepo location.
+     */
+    getComposePath(): string;
+    /**
+     * Initialize AgenticMail config files.
+     * If config already exists, returns the existing config without overwriting.
+     * Always regenerates Docker files to keep passwords in sync.
+     */
+    initConfig(): SetupResult;
+    /**
+     * Generate docker-compose.yml and stalwart.toml in ~/.agenticmail/
+     * with the correct admin password from config.
+     */
+    private generateDockerFiles;
+    /**
+     * Check if config has already been initialized.
+     */
+    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 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, ServiceManager, type ServiceStatus, 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, flushTelemetry, getDatabase, isInternalEmail, isValidPhoneNumber, normalizePhoneNumber, parseEmail, parseGoogleVoiceSms, recordToolCall, resolveConfig, sanitizeEmail, saveConfig, scanOutboundEmail, scoreEmail, setTelemetryVersion, startRelayBridge };