@agenticmail/core 0.2.26

package/dist/index.d.ts

@@ -0,0 +1,1365 @@
+import { EventEmitter } from 'node:events';
+import Database 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;
+    };
+    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.
+     */
+    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>;
+}
+/**
+ * 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;
+    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;
+    }>;
+    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;
+
+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.
+ * Everything is auto-installed — no optional deps.
+ */
+declare class DependencyInstaller {
+    private onProgress;
+    constructor(onProgress?: InstallProgress);
+    /**
+     * Install Docker if not present.
+     * Uses Homebrew on macOS, apt on Linux.
+     */
+    installDocker(): Promise<void>;
+    /**
+     * Wait for Docker daemon to be ready (up to 60s).
+     */
+    private waitForDocker;
+    /**
+     * 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 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 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 };