@agenticmail/core 0.5.0 → 0.5.2

package/dist/index.d.ts

@@ -1450,6 +1450,92 @@ declare class DependencyInstaller {
     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: {
@@ -1524,4 +1610,4 @@ declare class SetupManager {
     isInitialized(): boolean;
 }
 
-export { AGENT_ROLES, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, CloudflareClient, type CreateAgentOptions, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DNSConfigurator, type DeletionReport, type DeletionSummary, DependencyChecker, DependencyInstaller, type DependencyStatus, type DnsRecord, type DnsSetupResult, type DomainInfo, DomainManager, type DomainModeConfig, type DomainPurchaseResult, DomainPurchaser, type DomainSearchResult, type DomainSetupResult, type EmailEnvelope, EmailSearchIndex, type FolderInfo, type GatewayConfig, GatewayManager, type GatewayManagerOptions, type GatewayMode, type GatewayStatus, type InboundEmail, type InboxEvent, type InboxExpungeEvent, type InboxFlagsEvent, type InboxNewEvent, InboxWatcher, type InboxWatcherOptions, type InstallProgress, type LinkAdvisory, type LocalSmtpConfig, MailReceiver, type MailReceiverOptions, MailSender, type MailSenderOptions, type MailboxInfo, type OutboundCategory, type OutboundScanInput, type OutboundScanResult, type OutboundWarning, type ParsedAttachment, type ParsedEmail, type ParsedSms, type PurchasedDomain, RELAY_PRESETS, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, SPAM_THRESHOLD, type SanitizeDetection, type SanitizeResult, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, type SetupConfig, SetupManager, type SetupResult, type Severity, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SpamCategory, type SpamResult, type SpamRuleMatch, StalwartAdmin, type StalwartAdminOptions, type StalwartPrincipal, type TunnelConfig, TunnelManager, WARNING_THRESHOLD, type WatcherOptions, buildInboundSecurityAdvisory, closeDatabase, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, getDatabase, isInternalEmail, isValidPhoneNumber, normalizePhoneNumber, parseEmail, parseGoogleVoiceSms, resolveConfig, sanitizeEmail, saveConfig, scanOutboundEmail, scoreEmail, startRelayBridge };
+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, getDatabase, isInternalEmail, isValidPhoneNumber, normalizePhoneNumber, parseEmail, parseGoogleVoiceSms, resolveConfig, sanitizeEmail, saveConfig, scanOutboundEmail, scoreEmail, startRelayBridge };

package/dist/index.js

@@ -818,10 +818,10 @@ var StalwartAdmin = class {
     return ["exec", "agenticmail-stalwart", "stalwart-cli", "-u", "http://localhost:8080", "-c", creds];
   }
   async updateSetting(key, value) {
-    const { execFileSync: execFileSync3 } = await import("child_process");
+    const { execFileSync: execFileSync4 } = await import("child_process");
     const cli = this.cliArgs();
     try {
-      execFileSync3(
+      execFileSync4(
         "docker",
         [...cli, "server", "delete-config", key],
         { timeout: 15e3, stdio: ["ignore", "pipe", "pipe"] }
@@ -829,13 +829,13 @@ var StalwartAdmin = class {
     } catch {
     }
     try {
-      execFileSync3(
+      execFileSync4(
         "docker",
         [...cli, "server", "add-config", key, value],
         { timeout: 15e3, stdio: ["ignore", "pipe", "pipe"] }
       );
     } catch {
-      const output = execFileSync3(
+      const output = execFileSync4(
         "docker",
         [...cli, "server", "list-config", key],
         { timeout: 15e3, stdio: ["ignore", "pipe", "pipe"] }
@@ -850,14 +850,14 @@ var StalwartAdmin = class {
    * Critical for email deliverability — must match the sending domain.
    */
   async setHostname(domain) {
-    const { readFileSync: readFileSync3, writeFileSync: writeFileSync4 } = await import("fs");
-    const { homedir: homedir7 } = await import("os");
-    const { join: join8 } = await import("path");
-    const configPath = join8(homedir7(), ".agenticmail", "stalwart.toml");
+    const { readFileSync: readFileSync4, writeFileSync: writeFileSync5 } = await import("fs");
+    const { homedir: homedir8 } = await import("os");
+    const { join: join9 } = await import("path");
+    const configPath = join9(homedir8(), ".agenticmail", "stalwart.toml");
     try {
-      let config = readFileSync3(configPath, "utf-8");
+      let config = readFileSync4(configPath, "utf-8");
       config = config.replace(/^hostname\s*=\s*"[^"]*"/m, `hostname = "${domain}"`);
-      writeFileSync4(configPath, config);
+      writeFileSync5(configPath, config);
       console.log(`[Stalwart] Updated hostname to "${domain}" in stalwart.toml`);
     } catch (err) {
       throw new Error(`Failed to set config server.hostname=${domain}`);
@@ -866,15 +866,15 @@ var StalwartAdmin = class {
   // --- DKIM ---
   /** Path to the host-side stalwart.toml (mounted read-only into container) */
   get configPath() {
-    const { homedir: homedir7 } = __require("os");
-    const { join: join8 } = __require("path");
-    return join8(homedir7(), ".agenticmail", "stalwart.toml");
+    const { homedir: homedir8 } = __require("os");
+    const { join: join9 } = __require("path");
+    return join9(homedir8(), ".agenticmail", "stalwart.toml");
   }
   /** Path to host-side DKIM key directory */
   get dkimDir() {
-    const { homedir: homedir7 } = __require("os");
-    const { join: join8 } = __require("path");
-    return join8(homedir7(), ".agenticmail");
+    const { homedir: homedir8 } = __require("os");
+    const { join: join9 } = __require("path");
+    return join9(homedir8(), ".agenticmail");
   }
   /**
    * Create/reuse a DKIM signing key for a domain.
@@ -882,7 +882,7 @@ var StalwartAdmin = class {
    * Returns the public key (base64, no headers) for DNS TXT record.
    */
   async createDkimSignature(domain, selector = "agenticmail") {
-    const { execFileSync: execFileSync3 } = await import("child_process");
+    const { execFileSync: execFileSync4 } = await import("child_process");
     const signatureId = `agenticmail-${domain.replace(/\./g, "-")}`;
     const cli = this.cliArgs();
     const existing = await this.getSettings(`signature.${signatureId}`);
@@ -890,7 +890,7 @@ var StalwartAdmin = class {
       console.log(`[DKIM] Reusing existing signature "${signatureId}" from Stalwart DB`);
     } else {
       try {
-        execFileSync3("docker", [...cli, "server", "delete-config", `signature.${signatureId}`], {
+        execFileSync4("docker", [...cli, "server", "delete-config", `signature.${signatureId}`], {
           timeout: 1e4,
           stdio: ["ignore", "pipe", "pipe"]
         });
@@ -898,7 +898,7 @@ var StalwartAdmin = class {
       }
       console.log(`[DKIM] Creating RSA signature for ${domain} via stalwart-cli`);
       try {
-        execFileSync3("docker", [...cli, "dkim", "create", "rsa", domain, signatureId, selector], {
+        execFileSync4("docker", [...cli, "dkim", "create", "rsa", domain, signatureId, selector], {
           timeout: 15e3,
           stdio: ["ignore", "pipe", "pipe"]
         });
@@ -915,7 +915,7 @@ var StalwartAdmin = class {
         ["auth.dkim.sign.0001.else", "false"]
       ];
       for (const [key, value] of rules) {
-        execFileSync3("docker", [...cli, "server", "add-config", key, value], {
+        execFileSync4("docker", [...cli, "server", "add-config", key, value], {
           timeout: 1e4,
           stdio: ["ignore", "pipe", "pipe"]
         });
@@ -923,7 +923,7 @@ var StalwartAdmin = class {
     }
     let publicKey;
     try {
-      const output = execFileSync3("docker", [...cli, "dkim", "get-public-key", signatureId], {
+      const output = execFileSync4("docker", [...cli, "dkim", "get-public-key", signatureId], {
         timeout: 1e4,
         stdio: ["ignore", "pipe", "pipe"]
       }).toString();
@@ -934,7 +934,7 @@ var StalwartAdmin = class {
       throw new Error(`Failed to get DKIM public key: ${err.message}`);
     }
     try {
-      execFileSync3("docker", [...cli, "server", "reload-config"], {
+      execFileSync4("docker", [...cli, "server", "reload-config"], {
         timeout: 1e4,
         stdio: ["ignore", "pipe", "pipe"]
       });
@@ -947,9 +947,9 @@ var StalwartAdmin = class {
    * Restart the Stalwart Docker container and wait for it to be ready.
    */
   async restartContainer() {
-    const { execFileSync: execFileSync3 } = await import("child_process");
+    const { execFileSync: execFileSync4 } = await import("child_process");
     try {
-      execFileSync3("docker", ["restart", "agenticmail-stalwart"], { timeout: 3e4, stdio: ["ignore", "pipe", "pipe"] });
+      execFileSync4("docker", ["restart", "agenticmail-stalwart"], { timeout: 3e4, stdio: ["ignore", "pipe", "pipe"] });
       for (let i = 0; i < 15; i++) {
         try {
           const res = await fetch(`${this.baseUrl}/health`, { signal: AbortSignal.timeout(2e3) });
@@ -975,12 +975,12 @@ var StalwartAdmin = class {
    * This bypasses the need for a PTR record on the sending IP.
    */
   async configureOutboundRelay(config) {
-    const { readFileSync: readFileSync3, writeFileSync: writeFileSync4 } = await import("fs");
-    const { homedir: homedir7 } = await import("os");
-    const { join: join8 } = await import("path");
+    const { readFileSync: readFileSync4, writeFileSync: writeFileSync5 } = await import("fs");
+    const { homedir: homedir8 } = await import("os");
+    const { join: join9 } = await import("path");
     const routeName = config.routeName ?? "gmail";
-    const tomlPath = join8(homedir7(), ".agenticmail", "stalwart.toml");
-    let toml = readFileSync3(tomlPath, "utf-8");
+    const tomlPath = join9(homedir8(), ".agenticmail", "stalwart.toml");
+    let toml = readFileSync4(tomlPath, "utf-8");
     toml = toml.replace(/\n\[queue\.route\.gmail\][\s\S]*?(?=\n\[|$)/, "");
     toml = toml.replace(/\n\[queue\.strategy\][\s\S]*?(?=\n\[|$)/, "");
     toml += `
@@ -999,7 +999,7 @@ auth.secret = "${config.password}"
 route = [ { if = "is_local_domain('', rcpt_domain)", then = "'local'" },
            { else = "'${routeName}'" } ]
 `;
-    writeFileSync4(tomlPath, toml, "utf-8");
+    writeFileSync5(tomlPath, toml, "utf-8");
     await this.restartContainer();
   }
 };
@@ -3819,8 +3819,8 @@ var CloudflareClient = class {
     let available = false;
     if (result.supported_tld && !hasRegistration) {
       try {
-        const { execFileSync: execFileSync3 } = await import("child_process");
-        const whoisOutput = execFileSync3("whois", [domain], { timeout: 1e4, stdio: ["ignore", "pipe", "pipe"] }).toString().toLowerCase();
+        const { execFileSync: execFileSync4 } = await import("child_process");
+        const whoisOutput = execFileSync4("whois", [domain], { timeout: 1e4, stdio: ["ignore", "pipe", "pipe"] }).toString().toLowerCase();
         available = whoisOutput.includes("domain not found") || whoisOutput.includes("no match") || whoisOutput.includes("not found") || whoisOutput.includes("no data found") || whoisOutput.includes("status: free") || whoisOutput.includes("no entries found");
       } catch {
         available = false;
@@ -4284,8 +4284,8 @@ var TunnelManager = class {
       return this.binPath;
     }
     try {
-      const { execFileSync: execFileSync3 } = await import("child_process");
-      const sysPath = execFileSync3("which", ["cloudflared"], { timeout: 5e3, stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+      const { execFileSync: execFileSync4 } = await import("child_process");
+      const sysPath = execFileSync4("which", ["cloudflared"], { timeout: 5e3, stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
       if (sysPath && existsSync2(sysPath)) {
         this.binPath = sysPath;
         return sysPath;
@@ -5177,12 +5177,12 @@ var GatewayManager = class {
       zone = await this.cfClient.createZone(domain);
     }
     const existingRecords = await this.cfClient.listDnsRecords(zone.id);
-    const { homedir: homedir7 } = await import("os");
-    const backupDir = join4(homedir7(), ".agenticmail");
+    const { homedir: homedir8 } = await import("os");
+    const backupDir = join4(homedir8(), ".agenticmail");
     const backupPath = join4(backupDir, `dns-backup-${domain}-${Date.now()}.json`);
-    const { writeFileSync: writeFileSync4, mkdirSync: mkdirSync4 } = await import("fs");
-    mkdirSync4(backupDir, { recursive: true });
-    writeFileSync4(backupPath, JSON.stringify({
+    const { writeFileSync: writeFileSync5, mkdirSync: mkdirSync5 } = await import("fs");
+    mkdirSync5(backupDir, { recursive: true });
+    writeFileSync5(backupPath, JSON.stringify({
       domain,
       zoneId: zone.id,
       backedUpAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -5813,9 +5813,9 @@ var RELAY_PRESETS = {
 
 // src/setup/index.ts
 import { randomBytes as randomBytes2 } from "crypto";
-import { existsSync as existsSync5, readFileSync as readFileSync2, writeFileSync as writeFileSync3, mkdirSync as mkdirSync3, chmodSync } from "fs";
-import { join as join7 } from "path";
-import { homedir as homedir6 } from "os";
+import { existsSync as existsSync6, readFileSync as readFileSync3, writeFileSync as writeFileSync4, mkdirSync as mkdirSync4, chmodSync } from "fs";
+import { join as join8 } from "path";
+import { homedir as homedir7 } from "os";
 
 // src/setup/deps.ts
 import { execFileSync } from "child_process";
@@ -6301,6 +6301,440 @@ var DependencyInstaller = class {
   }
 };
 
+// src/setup/service.ts
+import { execFileSync as execFileSync3, execSync as execSync2 } from "child_process";
+import { existsSync as existsSync5, readFileSync as readFileSync2, writeFileSync as writeFileSync3, unlinkSync, mkdirSync as mkdirSync3 } from "fs";
+import { join as join7 } from "path";
+import { homedir as homedir6, platform as platform3 } from "os";
+var PLIST_LABEL = "com.agenticmail.server";
+var SYSTEMD_UNIT = "agenticmail.service";
+var ServiceManager = class {
+  os = platform3();
+  /**
+   * Get the path to the service file.
+   */
+  getServicePath() {
+    if (this.os === "darwin") {
+      return join7(homedir6(), "Library", "LaunchAgents", `${PLIST_LABEL}.plist`);
+    } else {
+      return join7(homedir6(), ".config", "systemd", "user", SYSTEMD_UNIT);
+    }
+  }
+  /**
+   * Find the Node.js binary path.
+   */
+  getNodePath() {
+    try {
+      return execFileSync3("which", ["node"], { timeout: 5e3, stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+    } catch {
+      return process.execPath;
+    }
+  }
+  /**
+   * Find the API server entry point.
+   * Searches common locations where agenticmail is installed.
+   */
+  getApiEntryPath() {
+    const searchDirs = [
+      // Global npm install
+      join7(homedir6(), "node_modules", "agenticmail"),
+      // npx cache / global prefix
+      ...(() => {
+        try {
+          const prefix = execSync2("npm prefix -g", { timeout: 5e3, stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+          return [
+            join7(prefix, "lib", "node_modules", "agenticmail"),
+            join7(prefix, "node_modules", "agenticmail")
+          ];
+        } catch {
+          return [];
+        }
+      })(),
+      // Homebrew on macOS
+      "/opt/homebrew/lib/node_modules/agenticmail",
+      "/usr/local/lib/node_modules/agenticmail"
+    ];
+    for (const base of searchDirs) {
+      const apiPaths = [
+        join7(base, "node_modules", "@agenticmail", "api", "dist", "index.js"),
+        join7(base, "..", "@agenticmail", "api", "dist", "index.js")
+      ];
+      for (const p of apiPaths) {
+        if (existsSync5(p)) return p;
+      }
+    }
+    const dataDir = join7(homedir6(), ".agenticmail");
+    const entryCache = join7(dataDir, "api-entry.path");
+    if (existsSync5(entryCache)) {
+      const cached = readFileSync2(entryCache, "utf-8").trim();
+      if (existsSync5(cached)) return cached;
+    }
+    throw new Error("Could not find @agenticmail/api entry point. Run `agenticmail start` first to populate the cache.");
+  }
+  /**
+   * Cache the API entry path so the service can find it later.
+   */
+  cacheApiEntryPath(entryPath) {
+    const dataDir = join7(homedir6(), ".agenticmail");
+    if (!existsSync5(dataDir)) mkdirSync3(dataDir, { recursive: true });
+    writeFileSync3(join7(dataDir, "api-entry.path"), entryPath);
+  }
+  /**
+   * Get the current package version.
+   */
+  getVersion() {
+    try {
+      const pkgPaths = [
+        join7(homedir6(), "node_modules", "agenticmail", "package.json"),
+        join7(homedir6(), ".agenticmail", "package-version.json")
+      ];
+      try {
+        const prefix = execSync2("npm prefix -g", { timeout: 5e3, stdio: ["ignore", "pipe", "ignore"] }).toString().trim();
+        pkgPaths.push(join7(prefix, "lib", "node_modules", "agenticmail", "package.json"));
+      } catch {
+      }
+      for (const p of pkgPaths) {
+        if (existsSync5(p)) {
+          const pkg = JSON.parse(readFileSync2(p, "utf-8"));
+          if (pkg.version) return pkg.version;
+        }
+      }
+    } catch {
+    }
+    return "unknown";
+  }
+  /**
+   * 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.
+   */
+  generateStartScript(nodePath, apiEntry) {
+    const scriptPath = join7(homedir6(), ".agenticmail", "bin", "start-server.sh");
+    const scriptDir = join7(homedir6(), ".agenticmail", "bin");
+    if (!existsSync5(scriptDir)) mkdirSync3(scriptDir, { recursive: true });
+    const script = [
+      "#!/bin/bash",
+      "# AgenticMail auto-start script",
+      "# Waits for Docker to be ready, then starts the API server.",
+      "",
+      'LOG_DIR="$HOME/.agenticmail/logs"',
+      'mkdir -p "$LOG_DIR"',
+      "",
+      "log() {",
+      `  echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" >> "$LOG_DIR/startup.log"`,
+      "}",
+      "",
+      'log "AgenticMail starting..."',
+      "",
+      "# Wait for Docker daemon (up to 10 minutes \u2014 Docker Desktop can be very slow on first boot)",
+      "MAX_WAIT=600",
+      "WAITED=0",
+      "while ! docker info >/dev/null 2>&1; do",
+      "  if [ $WAITED -ge $MAX_WAIT ]; then",
+      '    log "ERROR: Docker did not start after ${MAX_WAIT}s. Exiting."',
+      "    exit 1",
+      "  fi",
+      "  sleep 5",
+      "  WAITED=$((WAITED + 5))",
+      '  log "Waiting for Docker... (${WAITED}s)"',
+      "done",
+      'log "Docker is ready (waited ${WAITED}s)"',
+      "",
+      "# Wait for Stalwart container (up to 60s)",
+      "MAX_STALWART=60",
+      "WAITED=0",
+      'while ! docker ps --filter "name=agenticmail-stalwart" --format "{{.Status}}" 2>/dev/null | grep -qi "up"; do',
+      "  if [ $WAITED -ge $MAX_STALWART ]; then",
+      '    log "WARNING: Stalwart not running. Attempting to start..."',
+      '    COMPOSE="$HOME/.agenticmail/docker-compose.yml"',
+      '    if [ -f "$COMPOSE" ]; then',
+      '      docker compose -f "$COMPOSE" up -d 2>>"$LOG_DIR/startup.log"',
+      "      sleep 5",
+      "    fi",
+      "    break",
+      "  fi",
+      "  sleep 3",
+      "  WAITED=$((WAITED + 3))",
+      "done",
+      'log "Stalwart check complete"',
+      "",
+      "# Start the API server",
+      `log "Starting API server: ${nodePath} ${apiEntry}"`,
+      `exec "${nodePath}" "${apiEntry}"`
+    ].join("\n") + "\n";
+    writeFileSync3(scriptPath, script, { mode: 493 });
+    return scriptPath;
+  }
+  /**
+   * 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
+   */
+  generatePlist(nodePath, apiEntry, configPath) {
+    const config = JSON.parse(readFileSync2(configPath, "utf-8"));
+    const logDir = join7(homedir6(), ".agenticmail", "logs");
+    if (!existsSync5(logDir)) mkdirSync3(logDir, { recursive: true });
+    const version = this.getVersion();
+    const startScript = this.generateStartScript(nodePath, apiEntry);
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${PLIST_LABEL}</string>
+
+  <key>Comment</key>
+  <string>AgenticMail API Server (v${version})</string>
+
+  <key>ProgramArguments</key>
+  <array>
+    <string>${startScript}</string>
+  </array>
+
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>HOME</key>
+    <string>${homedir6()}</string>
+    <key>AGENTICMAIL_DATA_DIR</key>
+    <string>${config.dataDir || join7(homedir6(), ".agenticmail")}</string>
+    <key>AGENTICMAIL_MASTER_KEY</key>
+    <string>${config.masterKey}</string>
+    <key>STALWART_ADMIN_USER</key>
+    <string>${config.stalwart.adminUser}</string>
+    <key>STALWART_ADMIN_PASSWORD</key>
+    <string>${config.stalwart.adminPassword}</string>
+    <key>STALWART_URL</key>
+    <string>${config.stalwart.url}</string>
+    <key>AGENTICMAIL_API_PORT</key>
+    <string>${String(config.api.port)}</string>
+    <key>AGENTICMAIL_API_HOST</key>
+    <string>${config.api.host}</string>
+    <key>SMTP_HOST</key>
+    <string>${config.smtp.host}</string>
+    <key>SMTP_PORT</key>
+    <string>${String(config.smtp.port)}</string>
+    <key>IMAP_HOST</key>
+    <string>${config.imap.host}</string>
+    <key>IMAP_PORT</key>
+    <string>${String(config.imap.port)}</string>
+    <key>PATH</key>
+    <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
+    <key>AGENTICMAIL_SERVICE_VERSION</key>
+    <string>${version}</string>
+    <key>AGENTICMAIL_SERVICE_LABEL</key>
+    <string>${PLIST_LABEL}</string>
+  </dict>
+
+  <!-- Start when user logs in -->
+  <key>RunAtLoad</key>
+  <true/>
+
+  <!-- Always keep running \u2014 restart unconditionally if it ever stops -->
+  <key>KeepAlive</key>
+  <true/>
+
+  <!-- Minimum 15s between restarts to avoid rapid crash loops -->
+  <key>ThrottleInterval</key>
+  <integer>15</integer>
+
+  <!-- File descriptor limits \u2014 email servers need many open connections -->
+  <key>SoftResourceLimits</key>
+  <dict>
+    <key>NumberOfFiles</key>
+    <integer>8192</integer>
+  </dict>
+  <key>HardResourceLimits</key>
+  <dict>
+    <key>NumberOfFiles</key>
+    <integer>16384</integer>
+  </dict>
+
+  <key>StandardOutPath</key>
+  <string>${logDir}/server.log</string>
+  <key>StandardErrorPath</key>
+  <string>${logDir}/server.err.log</string>
+
+  <key>ProcessType</key>
+  <string>Background</string>
+</dict>
+</plist>`;
+  }
+  /**
+   * 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
+   */
+  generateSystemdUnit(nodePath, apiEntry, configPath) {
+    const config = JSON.parse(readFileSync2(configPath, "utf-8"));
+    const dataDir = config.dataDir || join7(homedir6(), ".agenticmail");
+    const version = this.getVersion();
+    const startScript = this.generateStartScript(nodePath, apiEntry);
+    return `[Unit]
+Description=AgenticMail API Server (v${version})
+After=network-online.target docker.service
+Wants=network-online.target docker.service
+StartLimitIntervalSec=300
+StartLimitBurst=5
+
+[Service]
+Type=simple
+ExecStart=${startScript}
+Restart=always
+RestartSec=15
+TimeoutStartSec=660
+LimitNOFILE=8192
+Environment=HOME=${homedir6()}
+Environment=AGENTICMAIL_DATA_DIR=${dataDir}
+Environment=AGENTICMAIL_MASTER_KEY=${config.masterKey}
+Environment=STALWART_ADMIN_USER=${config.stalwart.adminUser}
+Environment=STALWART_ADMIN_PASSWORD=${config.stalwart.adminPassword}
+Environment=STALWART_URL=${config.stalwart.url}
+Environment=AGENTICMAIL_API_PORT=${config.api.port}
+Environment=AGENTICMAIL_API_HOST=${config.api.host}
+Environment=SMTP_HOST=${config.smtp.host}
+Environment=SMTP_PORT=${config.smtp.port}
+Environment=IMAP_HOST=${config.imap.host}
+Environment=IMAP_PORT=${config.imap.port}
+Environment=PATH=/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin
+Environment=AGENTICMAIL_SERVICE_VERSION=${version}
+
+[Install]
+WantedBy=default.target
+`;
+  }
+  /**
+   * Install the auto-start service.
+   */
+  install() {
+    const configPath = join7(homedir6(), ".agenticmail", "config.json");
+    if (!existsSync5(configPath)) {
+      return { installed: false, message: "Config not found. Run agenticmail setup first." };
+    }
+    const nodePath = this.getNodePath();
+    let apiEntry;
+    try {
+      apiEntry = this.getApiEntryPath();
+    } catch (err) {
+      return { installed: false, message: err.message };
+    }
+    const servicePath = this.getServicePath();
+    if (this.os === "darwin") {
+      const dir = join7(homedir6(), "Library", "LaunchAgents");
+      if (!existsSync5(dir)) mkdirSync3(dir, { recursive: true });
+      if (existsSync5(servicePath)) {
+        try {
+          execFileSync3("launchctl", ["unload", servicePath], { timeout: 1e4, stdio: "ignore" });
+        } catch {
+        }
+      }
+      const plist = this.generatePlist(nodePath, apiEntry, configPath);
+      writeFileSync3(servicePath, plist);
+      try {
+        execFileSync3("launchctl", ["load", servicePath], { timeout: 1e4, stdio: "ignore" });
+      } catch (err) {
+        return { installed: false, message: `Failed to load service: ${err.message}` };
+      }
+      return { installed: true, message: `Service installed at ${servicePath}` };
+    } else if (this.os === "linux") {
+      const dir = join7(homedir6(), ".config", "systemd", "user");
+      if (!existsSync5(dir)) mkdirSync3(dir, { recursive: true });
+      const unit = this.generateSystemdUnit(nodePath, apiEntry, configPath);
+      writeFileSync3(servicePath, unit);
+      try {
+        execFileSync3("systemctl", ["--user", "daemon-reload"], { timeout: 1e4, stdio: "ignore" });
+        execFileSync3("systemctl", ["--user", "enable", SYSTEMD_UNIT], { timeout: 1e4, stdio: "ignore" });
+        execFileSync3("systemctl", ["--user", "start", SYSTEMD_UNIT], { timeout: 1e4, stdio: "ignore" });
+        try {
+          execFileSync3("loginctl", ["enable-linger"], { timeout: 1e4, stdio: "ignore" });
+        } catch {
+        }
+      } catch (err) {
+        return { installed: false, message: `Failed to enable service: ${err.message}` };
+      }
+      return { installed: true, message: `Service installed at ${servicePath}` };
+    } else {
+      return { installed: false, message: `Auto-start not supported on ${this.os}` };
+    }
+  }
+  /**
+   * Uninstall the auto-start service.
+   */
+  uninstall() {
+    const servicePath = this.getServicePath();
+    if (!existsSync5(servicePath)) {
+      return { removed: false, message: "Service is not installed." };
+    }
+    if (this.os === "darwin") {
+      try {
+        execFileSync3("launchctl", ["unload", servicePath], { timeout: 1e4, stdio: "ignore" });
+      } catch {
+      }
+      try {
+        unlinkSync(servicePath);
+      } catch {
+      }
+      return { removed: true, message: "Service removed." };
+    } else if (this.os === "linux") {
+      try {
+        execFileSync3("systemctl", ["--user", "stop", SYSTEMD_UNIT], { timeout: 1e4, stdio: "ignore" });
+        execFileSync3("systemctl", ["--user", "disable", SYSTEMD_UNIT], { timeout: 1e4, stdio: "ignore" });
+      } catch {
+      }
+      try {
+        unlinkSync(servicePath);
+      } catch {
+      }
+      try {
+        execFileSync3("systemctl", ["--user", "daemon-reload"], { timeout: 1e4, stdio: "ignore" });
+      } catch {
+      }
+      return { removed: true, message: "Service removed." };
+    } else {
+      return { removed: false, message: `Not supported on ${this.os}` };
+    }
+  }
+  /**
+   * Get the current service status.
+   */
+  status() {
+    const servicePath = this.getServicePath();
+    const plat = this.os === "darwin" ? "launchd" : this.os === "linux" ? "systemd" : "unsupported";
+    const installed = existsSync5(servicePath);
+    let running = false;
+    if (installed) {
+      if (this.os === "darwin") {
+        try {
+          const output = execSync2(`launchctl list | grep ${PLIST_LABEL}`, { timeout: 5e3, stdio: ["ignore", "pipe", "ignore"] }).toString();
+          const pid = output.trim().split("	")[0];
+          running = pid !== "-" && pid !== "" && !isNaN(parseInt(pid));
+        } catch {
+        }
+      } else if (this.os === "linux") {
+        try {
+          execFileSync3("systemctl", ["--user", "is-active", SYSTEMD_UNIT], { timeout: 5e3, stdio: "ignore" });
+          running = true;
+        } catch {
+        }
+      }
+    }
+    return { installed, running, platform: plat, servicePath: installed ? servicePath : null };
+  }
+  /**
+   * Reinstall the service (useful after config changes or updates).
+   */
+  reinstall() {
+    this.uninstall();
+    return this.install();
+  }
+};
+
 // src/setup/index.ts
 var SetupManager = class {
   checker = new DependencyChecker();
@@ -6342,13 +6776,13 @@ var SetupManager = class {
    * falls back to monorepo location.
    */
   getComposePath() {
-    const standalonePath = join7(homedir6(), ".agenticmail", "docker-compose.yml");
-    if (existsSync5(standalonePath)) return standalonePath;
+    const standalonePath = join8(homedir7(), ".agenticmail", "docker-compose.yml");
+    if (existsSync6(standalonePath)) return standalonePath;
     const cwd = process.cwd();
-    const candidates = [cwd, join7(cwd, "..")];
+    const candidates = [cwd, join8(cwd, "..")];
     for (const dir of candidates) {
-      const p = join7(dir, "docker-compose.yml");
-      if (existsSync5(p)) return p;
+      const p = join8(dir, "docker-compose.yml");
+      if (existsSync6(p)) return p;
     }
     return standalonePath;
   }
@@ -6358,19 +6792,19 @@ var SetupManager = class {
    * Always regenerates Docker files to keep passwords in sync.
    */
   initConfig() {
-    const dataDir = join7(homedir6(), ".agenticmail");
-    const configPath = join7(dataDir, "config.json");
-    const envPath = join7(dataDir, ".env");
-    if (existsSync5(configPath)) {
+    const dataDir = join8(homedir7(), ".agenticmail");
+    const configPath = join8(dataDir, "config.json");
+    const envPath = join8(dataDir, ".env");
+    if (existsSync6(configPath)) {
       try {
-        const existing = JSON.parse(readFileSync2(configPath, "utf-8"));
+        const existing = JSON.parse(readFileSync3(configPath, "utf-8"));
         this.generateDockerFiles(existing);
         return { configPath, envPath, config: existing, isNew: false };
       } catch {
       }
     }
-    if (!existsSync5(dataDir)) {
-      mkdirSync3(dataDir, { recursive: true });
+    if (!existsSync6(dataDir)) {
+      mkdirSync4(dataDir, { recursive: true });
     }
     const masterKey = `mk_${randomBytes2(24).toString("hex")}`;
     const stalwartPassword = randomBytes2(16).toString("hex");
@@ -6386,7 +6820,7 @@ var SetupManager = class {
       api: { port: 3100, host: "127.0.0.1" },
       dataDir
     };
-    writeFileSync3(configPath, JSON.stringify(config, null, 2));
+    writeFileSync4(configPath, JSON.stringify(config, null, 2));
     chmodSync(configPath, 384);
     const envContent = `# Auto-generated by agenticmail setup
 STALWART_ADMIN_USER=admin
@@ -6402,7 +6836,7 @@ SMTP_PORT=587
 IMAP_HOST=localhost
 IMAP_PORT=143
 `;
-    writeFileSync3(envPath, envContent);
+    writeFileSync4(envPath, envContent);
     chmodSync(envPath, 384);
     this.generateDockerFiles(config);
     return { configPath, envPath, config, isNew: true };
@@ -6412,13 +6846,13 @@ IMAP_PORT=143
    * with the correct admin password from config.
    */
   generateDockerFiles(config) {
-    const dataDir = config.dataDir || join7(homedir6(), ".agenticmail");
-    if (!existsSync5(dataDir)) {
-      mkdirSync3(dataDir, { recursive: true });
+    const dataDir = config.dataDir || join8(homedir7(), ".agenticmail");
+    if (!existsSync6(dataDir)) {
+      mkdirSync4(dataDir, { recursive: true });
     }
     const password = config.stalwart?.adminPassword || "changeme";
-    const composePath = join7(dataDir, "docker-compose.yml");
-    writeFileSync3(composePath, `services:
+    const composePath = join8(dataDir, "docker-compose.yml");
+    writeFileSync4(composePath, `services:
   stalwart:
     image: stalwartlabs/stalwart:latest
     container_name: agenticmail-stalwart
@@ -6440,8 +6874,8 @@ IMAP_PORT=143
 volumes:
   stalwart-data:
 `);
-    const tomlPath = join7(dataDir, "stalwart.toml");
-    writeFileSync3(tomlPath, `# Stalwart Mail Server \u2014 AgenticMail Configuration
+    const tomlPath = join8(dataDir, "stalwart.toml");
+    writeFileSync4(tomlPath, `# Stalwart Mail Server \u2014 AgenticMail Configuration
 
 [server]
 hostname = "localhost"
@@ -6496,8 +6930,8 @@ secret = "${password}"
    * Check if config has already been initialized.
    */
   isInitialized() {
-    const configPath = join7(homedir6(), ".agenticmail", "config.json");
-    return existsSync5(configPath);
+    const configPath = join8(homedir7(), ".agenticmail", "config.json");
+    return existsSync6(configPath);
   }
 };
 export {
@@ -6522,6 +6956,7 @@ export {
   RelayBridge,
   RelayGateway,
   SPAM_THRESHOLD,
+  ServiceManager,
   SetupManager,
   SmsManager,
   SmsPoller,

package/package.json

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