@agenticmail/core 0.7.1 → 0.7.3

package/README.md

@@ -1,4 +1,8 @@
-# @agenticmail/core
+<p align="center">
+  <img src="https://raw.githubusercontent.com/agenticmail/agenticmail/main/docs/images/logo-200.png" alt="AgenticMail logo (pink bow)" width="180" />
+</p>
+
+<h1 align="center">@agenticmail/core</h1>
 
 Core SDK for [AgenticMail](https://github.com/agenticmail/agenticmail) — the first platform to give AI agents real email addresses and phone numbers.
 
@@ -6,6 +10,13 @@ This is the foundation layer that everything else builds on. If the API server,
 
 Every other AgenticMail package depends on this one.
 
+## ✨ What's new in 0.7.2
+
+- **`list_inbox` / `inbox_digest` consistency fix** — `MailReceiver.listEnvelopes` no longer trusts the stale cached `mailbox.exists` count and early-returns empty when an internal mail just landed. `getMailboxInfo` now issues an IMAP `NOOP` to refresh state before reading `client.mailbox`. `SEARCH` is the authoritative source; `list_inbox` and `inbox_digest` now agree.
+- **Custom outgoing headers** — the `headers` field on `SendMailOptions` is fully plumbed through to nodemailer, so callers (the API, the MCP server) can set `X-AgenticMail-Wake` and other custom headers for downstream consumers to read.
+
+The wake / thread-close / web UI features live in the API and dispatcher layers above this package; `core` provides the primitives they all share.
+
 ---
 
 ## Table of Contents
@@ -174,7 +185,7 @@ Full custom domain through Cloudflare. Agents send from `agent@yourdomain.com` w
 4. Stalwart hostname set to the domain (critical for SMTP EHLO greeting)
 5. DKIM signing key generated in Stalwart (selector: `agenticmail`)
 6. DNS records configured: MX (via Email Routing), SPF, DMARC, DKIM TXT, tunnel CNAME
-7. Tunnel started with ingress rules routing traffic to the API server (port 3100) and Stalwart (port 8080)
+7. Tunnel started with ingress rules routing traffic to the API server (port 3829) and Stalwart (port 8080)
 8. Cloudflare Email Routing enabled on the zone
 9. Email Worker deployed — catches all inbound email, base64-encodes the raw RFC822 content, and POSTs it to the AgenticMail inbound webhook with a shared secret
 10. Catch-all Email Routing rule set to route all `*@domain` to the Worker
@@ -410,7 +421,9 @@ Limits: minimum 1 result, maximum 1000 results per query (default 20).
 
 ## Data Storage
 
-AgenticMail uses a SQLite database with WAL mode (Write-Ahead Logging) for better concurrent access and foreign keys enabled for referential integrity. The database is initialized with automatic migrations that run on first access.
+AgenticMail uses Node's built-in **`node:sqlite`** module (stable since Node 22). The database runs with WAL mode (Write-Ahead Logging) for better concurrent access and foreign keys enabled for referential integrity. Automatic migrations run on first `getDatabase()` call.
+
+> **Why `node:sqlite` instead of `better-sqlite3`?** Before `0.7.0` this package depended on `better-sqlite3`, a native module that ships pre-built binaries per `NODE_MODULE_VERSION` and intermittently lags new Node releases. When prebuilds were missing, installers fell back to `node-gyp` compile-from-source — which requires Python, a C++ toolchain, and a working network at install time. `node:sqlite` is part of Node itself, so by definition it always matches the runtime. No prebuilds, no gyp, no native compilation, no Python prereq. The on-disk database format is unchanged (still SQLite 3); existing data files migrate transparently. **Cost:** Node 22+ is now the minimum supported runtime.
 
 **Database location:** `~/.agenticmail/agenticmail.db`
 
@@ -447,14 +460,14 @@ The SetupManager handles getting everything installed and configured for the fir
 - cloudflared — checks managed binary at `~/.agenticmail/bin/cloudflared` or system-wide via `which`
 
 **Automatic installation:**
-- Docker: via Homebrew (`brew install --cask docker`) on macOS, or the official install script on Linux. Opens Docker Desktop on macOS and waits up to 60 seconds for the daemon to start.
+- Docker: via Homebrew (`brew install colima docker docker-compose`) on macOS — **uses Colima, not Docker Desktop**, so there's no GUI gate and no terms-acceptance dialog. On Linux, the official install script. Starts Colima (`colima start --cpu 2 --memory 2 --disk 10`) and waits for the daemon to come up.
 - Stalwart: starts the container via `docker compose up -d` and waits up to 30 seconds for it to be running.
 - cloudflared: downloads the platform-specific binary from GitHub releases (supports macOS ARM/Intel and Linux ARM/Intel). Installs atomically (write to temp file, chmod, rename) at `~/.agenticmail/bin/cloudflared`.
 
 **Configuration generation:**
 - `docker-compose.yml` — Stalwart service with ports 8080 (HTTP admin), 587 (SMTP submission), 143 (IMAP), 25 (SMTP inbound)
 - `stalwart.toml` — Stalwart configuration with RocksDB storage, internal directory, stdout logging, and fallback admin credentials
-- `config.json` — Master key, Stalwart URL/credentials, SMTP/IMAP host/port, API host/port, data directory (written with mode 0600 for security)
+- `config.json` — Master key, Stalwart URL/credentials, SMTP/IMAP host/port, API host (default `127.0.0.1`) and API port (**default `3829`** — chosen to avoid common dev-tool ports like 3000/3100/3200/3300/4000/5000/8000/8080), data directory (written with mode 0600 for security)
 - `.env` — Environment variables (written with mode 0600)
 
 Configuration files are placed in the data directory (default: `~/.agenticmail/`). Calling `initConfig()` is idempotent — it loads existing config if present, but always regenerates Docker files to keep passwords in sync.

package/REFERENCE.md

@@ -825,7 +825,7 @@ class CloudflareClient {
 
 **`createTunnel()`** — Reuses existing tunnel if name matches. Generates random 32-byte secret.
 
-**`createTunnelRoute()`** — Creates ingress: `/api/agenticmail/*` → apiService (port 3100), `*` → primary service (port 8080), catch-all → 404.
+**`createTunnelRoute()`** — Creates ingress: `/api/agenticmail/*` → apiService (port 3829), `*` → primary service (port 8080), catch-all → 404.
 
 **`deployEmailWorker()`** — Multipart form upload with ES module metadata and plain_text env var bindings. Compatibility date: 2024-01-01.
 

package/dist/index.cjs

@@ -894,6 +894,10 @@ var MailReceiver = class {
   async getMailboxInfo(mailbox = "INBOX") {
     const lock = await this.client.getMailboxLock(mailbox);
     try {
+      try {
+        await this.client.noop();
+      } catch {
+      }
       const status = this.client.mailbox;
       if (!status) {
         return { name: mailbox, exists: 0, recent: 0, unseen: 0 };
@@ -912,12 +916,8 @@ var MailReceiver = class {
     const lock = await this.client.getMailboxLock(mailbox);
     try {
       const envelopes = [];
-      const mb = this.client.mailbox;
-      const total = mb ? mb.exists ?? 0 : 0;
-      if (total === 0) return envelopes;
       const limit = Math.min(Math.max(options?.limit ?? 20, 1), 1e3);
       const offset = Math.max(options?.offset ?? 0, 0);
-      if (offset >= total) return envelopes;
       const allUids = await this.client.search({ all: true }, { uid: true });
       if (!allUids || allUids.length === 0) return envelopes;
       const sortedUids = Array.from(allUids).sort((a, b) => b - a);
@@ -1011,6 +1011,24 @@ var MailReceiver = class {
       lock.release();
     }
   }
+  /**
+   * Flag / unflag a message. IMAP uses `\Flagged` for what Gmail
+   * calls "starred" — same on-disk bit, different vocabulary. We
+   * expose it as `setStarred(uid, true|false)` so the web UI can
+   * call a single endpoint with a boolean.
+   */
+  async setStarred(uid, starred, mailbox = "INBOX") {
+    const lock = await this.client.getMailboxLock(mailbox);
+    try {
+      if (starred) {
+        await this.client.messageFlagsAdd(String(uid), ["\\Flagged"], { uid: true });
+      } else {
+        await this.client.messageFlagsRemove(String(uid), ["\\Flagged"], { uid: true });
+      }
+    } finally {
+      lock.release();
+    }
+  }
   /** Move a message to another folder */
   async moveMessage(uid, fromMailbox, toMailbox) {
     const lock = await this.client.getMailboxLock(fromMailbox);

package/dist/index.d.cts

@@ -473,6 +473,13 @@ declare class MailReceiver {
     deleteMessage(uid: number, mailbox?: string): Promise<void>;
     /** Mark a message as unseen (unread) */
     markUnseen(uid: number, mailbox?: string): Promise<void>;
+    /**
+     * Flag / unflag a message. IMAP uses `\Flagged` for what Gmail
+     * calls "starred" — same on-disk bit, different vocabulary. We
+     * expose it as `setStarred(uid, true|false)` so the web UI can
+     * call a single endpoint with a boolean.
+     */
+    setStarred(uid: number, starred: boolean, mailbox?: string): Promise<void>;
     /** Move a message to another folder */
     moveMessage(uid: number, fromMailbox: string, toMailbox: string): Promise<void>;
     /** List all IMAP folders/mailboxes */

package/dist/index.d.ts

@@ -473,6 +473,13 @@ declare class MailReceiver {
     deleteMessage(uid: number, mailbox?: string): Promise<void>;
     /** Mark a message as unseen (unread) */
     markUnseen(uid: number, mailbox?: string): Promise<void>;
+    /**
+     * Flag / unflag a message. IMAP uses `\Flagged` for what Gmail
+     * calls "starred" — same on-disk bit, different vocabulary. We
+     * expose it as `setStarred(uid, true|false)` so the web UI can
+     * call a single endpoint with a boolean.
+     */
+    setStarred(uid: number, starred: boolean, mailbox?: string): Promise<void>;
     /** Move a message to another folder */
     moveMessage(uid: number, fromMailbox: string, toMailbox: string): Promise<void>;
     /** List all IMAP folders/mailboxes */

package/dist/index.js

@@ -140,6 +140,10 @@ var MailReceiver = class {
   async getMailboxInfo(mailbox = "INBOX") {
     const lock = await this.client.getMailboxLock(mailbox);
     try {
+      try {
+        await this.client.noop();
+      } catch {
+      }
       const status = this.client.mailbox;
       if (!status) {
         return { name: mailbox, exists: 0, recent: 0, unseen: 0 };
@@ -158,12 +162,8 @@ var MailReceiver = class {
     const lock = await this.client.getMailboxLock(mailbox);
     try {
       const envelopes = [];
-      const mb = this.client.mailbox;
-      const total = mb ? mb.exists ?? 0 : 0;
-      if (total === 0) return envelopes;
       const limit = Math.min(Math.max(options?.limit ?? 20, 1), 1e3);
       const offset = Math.max(options?.offset ?? 0, 0);
-      if (offset >= total) return envelopes;
       const allUids = await this.client.search({ all: true }, { uid: true });
       if (!allUids || allUids.length === 0) return envelopes;
       const sortedUids = Array.from(allUids).sort((a, b) => b - a);
@@ -257,6 +257,24 @@ var MailReceiver = class {
       lock.release();
     }
   }
+  /**
+   * Flag / unflag a message. IMAP uses `\Flagged` for what Gmail
+   * calls "starred" — same on-disk bit, different vocabulary. We
+   * expose it as `setStarred(uid, true|false)` so the web UI can
+   * call a single endpoint with a boolean.
+   */
+  async setStarred(uid, starred, mailbox = "INBOX") {
+    const lock = await this.client.getMailboxLock(mailbox);
+    try {
+      if (starred) {
+        await this.client.messageFlagsAdd(String(uid), ["\\Flagged"], { uid: true });
+      } else {
+        await this.client.messageFlagsRemove(String(uid), ["\\Flagged"], { uid: true });
+      }
+    } finally {
+      lock.release();
+    }
+  }
   /** Move a message to another folder */
   async moveMessage(uid, fromMailbox, toMailbox) {
     const lock = await this.client.getMailboxLock(fromMailbox);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/core",
-  "version": "0.7.1",
+  "version": "0.7.3",
   "description": "Core SDK for AgenticMail — email, SMS, and phone number access for AI agents",
   "type": "module",
   "main": "dist/index.js",