@agenticmail/core 0.7.6 → 0.9.1

package/dist/index.d.cts

@@ -320,6 +320,13 @@ interface Agent {
     updatedAt: string;
     metadata: Record<string, unknown>;
     role: AgentRole;
+    /** Per-agent wake preference. When false, the dispatcher SKIPS
+     *  this agent on every CC-only delivery regardless of the
+     *  sender's `wake` list. Coder/silent-observer agents register
+     *  with `wake_on_cc: false` so a designer's `cc:` accidentally
+     *  including them never wastes a Claude turn. Defaults to true
+     *  (preserves the 0.9.0 wake-list-respecting behaviour). */
+    wakeOnCc?: boolean;
 }
 interface CreateAgentOptions {
     name: string;
@@ -1843,4 +1850,254 @@ 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 Database, 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, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, 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, classifyEmailRoute, closeDatabase, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, getDatabase, isInternalEmail, isValidPhoneNumber, normalizePhoneNumber, parseEmail, parseGoogleVoiceSms, recordToolCall, resolveConfig, sanitizeEmail, saveConfig, scanOutboundEmail, scoreEmail, setTelemetryVersion, startRelayBridge };
+/**
+ * Stable thread-id derivation.
+ *
+ * Two messages belong to the same thread if their normalized
+ * `(subject, root-from)` tuple matches. Computing this on demand
+ * from envelope data is cheap and avoids depending on the IMAP
+ * `THREAD` extension (which Stalwart doesn't advertise) or on
+ * reconstructing `In-Reply-To` / `References` chains (which agents
+ * sometimes forge or strip).
+ *
+ * # Normalization rules
+ *
+ *   - Strip every leading `Re:` / `Fwd:` / `Re[2]:` chain. Some
+ *     clients chain prefixes (`Re: Re: Fwd: Re: …`), which would
+ *     otherwise produce a different thread id for every hop.
+ *   - Collapse internal whitespace to single spaces.
+ *   - Trim leading + trailing whitespace.
+ *   - Lower-case for case-insensitive matching.
+ *   - Reply-on-thread coordination markers (`[FINAL]`, `[DONE]`,
+ *     `[CLOSED]`, `[WRAP]`) are stripped — a closing message
+ *     belongs to the SAME thread as the conversation it closes.
+ *
+ * # Identity hash
+ *
+ * SHA-256 of `<normalizedSubject>\n<rootFromLower>`, base64url
+ * truncated to 16 chars (~12 bytes of entropy = ~10^28 distinct
+ * threads; collision-free for any realistic deployment).
+ *
+ * The root sender is included so two unrelated conversations
+ * that share a generic subject ("hello", "follow up") aren't
+ * collapsed into one thread. We use the FIRST sender's address
+ * on the thread — agents reading a reply pass their own
+ * envelope's `from` value, but the thread id stays stable
+ * because we re-derive `rootFromAddr` from the cache when
+ * looking up an existing thread (see thread-cache.ts).
+ */
+declare function normalizeSubject(subject: string | undefined | null): string;
+declare function normalizeAddress(addr: string | undefined | null): string;
+interface ThreadIdInput {
+    subject?: string | null;
+    /** Optional. Kept as a field so call sites that previously
+     *  passed it keep working, but NOT used in the hash. The thread
+     *  id is intentionally subject-only so a reply from a different
+     *  sender (the replier, not the root) still maps to the same
+     *  thread without needing a cache lookup first. The dispatcher's
+     *  legacy `threadIdFromSubject` uses the same convention; this
+     *  function is its disk-safe + hashed equivalent. */
+    rootFromAddr?: string | null;
+}
+/**
+ * Subject-only stable thread id. Collisions between unrelated
+ * conversations that genuinely share the same normalized subject
+ * ("hello", "follow up") are accepted as the tradeoff for stable
+ * threading across replies. In practice agents on different
+ * threads use different participants, so the wake-budget +
+ * thread-close logic disambiguates downstream.
+ */
+declare function threadIdFor(input: ThreadIdInput): string;
+
+/**
+ * Per-thread message cache — Layer 1 of the wake-context system.
+ *
+ * # What it stores
+ *
+ * Each thread (keyed by the stable `threadIdFor` hash) gets a JSON
+ * file containing the last K message envelopes that were seen on
+ * the thread:
+ *
+ *   { threadId, subject, rootFromAddr, lastUpdated, messages: [
+ *     { uid, from, subject, preview, date }
+ *   ]}
+ *
+ * # What it does NOT store
+ *
+ * - Full message bodies. Storing the body would multiply the cache
+ *   size 20x and most agents don't need it on rehydration — they
+ *   need to see "who said what about what" at a glance, not the
+ *   exact prose. The dedicated `read_email(uid)` MCP tool serves
+ *   the body when the agent actually wants it.
+ *
+ * # Lifecycle
+ *
+ * - Built passively: the dispatcher calls `pushMessage(t, env)` on
+ *   every SSE new-mail event for the thread, even when no agent
+ *   actually wakes. Selective-wake skips, circuit-breaker mutes,
+ *   `[FINAL]` markers — none of them prevent the cache from being
+ *   populated. The cache is always up to date.
+ *
+ * - Read on every spawn: `readCache(t)` is called before the
+ *   dispatcher fires a worker, and the result is rendered into
+ *   the wake prompt.
+ *
+ * - Pruned on close: `cleanupThread(t)` is called when the
+ *   dispatcher detects a thread-close marker. Removes the file
+ *   immediately; 7-day grace via empty-tombstone is not needed
+ *   because the agent's own memory file handles "did this
+ *   thread actually close" semantics.
+ *
+ * - LRU-bounded: a directory-level LRU (default 5000 threads, ~25 MB)
+ *   runs at the head of every write to keep disk usage flat.
+ */
+interface CachedMessage {
+    uid: number;
+    /** Display name OR raw address — whichever was on the envelope. */
+    from: string;
+    /** Sender's bare email (post-normalization). Same value used to
+     *  derive the thread root, so agents can spot "did I write this?"
+     *  with one equality check. */
+    fromAddr: string;
+    subject: string;
+    /** Up to ~240 chars of plain-text body. */
+    preview: string;
+    /** ISO string. */
+    date: string;
+}
+interface ThreadCacheEntry {
+    threadId: string;
+    /** First-seen normalized subject — kept on the entry so the wake
+     *  prompt can show it without re-normalizing. */
+    subject: string;
+    /** First-seen root sender. Used to keep `threadIdFor` stable on
+     *  subsequent replies (which carry the replier's `from`, not
+     *  the original). */
+    rootFromAddr: string;
+    /** ms timestamp of most recent write. Drives LRU eviction. */
+    lastUpdated: number;
+    /** Newest-first. We cap at K — drop oldest on push. */
+    messages: CachedMessage[];
+}
+interface ThreadCacheOptions {
+    /** Override the on-disk root. Mainly for tests. */
+    cacheDir?: string;
+    /** Newest-N messages kept per thread. */
+    k?: number;
+    /** Max threads on disk before LRU eviction kicks in. */
+    lruCap?: number;
+}
+declare class ThreadCache {
+    private readonly dir;
+    private readonly k;
+    private readonly lruCap;
+    constructor(opts?: ThreadCacheOptions);
+    private pathFor;
+    read(threadId: string): ThreadCacheEntry | null;
+    /**
+     * Append a message to the thread's cache, pruning to the K
+     * newest entries. Creates the cache entry on first write.
+     *
+     * `rootFromAddr` is the sender of the ROOT message on the
+     * thread; on a brand-new thread this is just `env.fromAddr`,
+     * on a reply it's read off the existing cache entry (callers
+     * should pass the existing entry's rootFromAddr when known).
+     */
+    pushMessage(threadId: string, env: CachedMessage, meta: {
+        subject: string;
+        rootFromAddr: string;
+    }): ThreadCacheEntry;
+    /** Permanently remove a thread's cache (called on [FINAL] / [DONE] / [CLOSED] / [WRAP]). */
+    delete(threadId: string): void;
+    /**
+     * Render the cache as a compact text block for the wake prompt.
+     * One line per message, newest first. Empty string when the
+     * cache is empty — caller decides whether to suppress the
+     * header in that case.
+     */
+    renderForPrompt(entry: ThreadCacheEntry | null): string;
+    private writeAtomic;
+    /**
+     * Best-effort LRU eviction. Runs at most every 256 writes (we
+     * don't track a precise counter — `Math.random()` sampling keeps
+     * the write path cheap). When the directory has more files than
+     * `lruCap`, sort by mtime ascending and delete the oldest 10%.
+     */
+    private maybeEvict;
+}
+
+/**
+ * Per-agent thread memory — Layer 2 of the wake-context system.
+ *
+ * # What it stores
+ *
+ * Each `(agent, thread)` tuple gets a tiny markdown file
+ * the AGENT writes at the end of its wake. The dispatcher
+ * doesn't write this — it's the agent's own narrative about
+ * what THEY committed to, what's open, and the last action
+ * they took on the thread.
+ *
+ * # Why it's separate from the ThreadCache
+ *
+ * The cache is FACTS (whoever sent what when). The memory is
+ * JUDGMENT (what does each agent intend to do about it). Two
+ * agents on the same thread share the cache verbatim but each
+ * has their own memory file; what Vesper thinks she committed
+ * to is none of Orion's business.
+ *
+ * # Disk layout
+ *
+ *   ~/.agenticmail/agent-memory/<agentId>/<threadId>.md
+ *
+ * The path is hierarchical (per-agent dir) so cleanup on agent
+ * deletion is `rm -rf <agentDir>` and concurrent writers don't
+ * step on each other across agents.
+ *
+ * # Format
+ *
+ * Tiny YAML frontmatter for structured fields the dispatcher
+ * cares about (`updated_at`, `lastUid`); free-form markdown
+ * body for the agent's prose. The agent passes these as
+ * separate fields on the MCP tool and we render the file
+ * deterministically — no Markdown-in-YAML parsing nightmare.
+ */
+interface AgentMemoryFields {
+    /** One-paragraph narrative of where the thread stands. */
+    summary?: string;
+    /** Things THIS agent has committed to doing. */
+    commitments?: string[];
+    /** Things THIS agent is waiting on / open questions. */
+    openQuestions?: string[];
+    /** Last action this agent took on the thread (e.g. "replied UID 41 asking for the raw counts"). */
+    lastAction?: string;
+    /** Last message UID this agent has digested. Used as a cursor
+     *  to detect "memory is older than the cache" on the dispatcher
+     *  side. */
+    lastUid?: number;
+}
+interface AgentMemoryRead extends AgentMemoryFields {
+    /** ISO timestamp of the most recent write. */
+    updatedAt?: string;
+    /** Raw file contents — useful for the wake prompt; rendered
+     *  verbatim into the "Your own memory" block. */
+    raw: string;
+}
+interface AgentMemoryOptions {
+    memoryDir?: string;
+}
+declare class AgentMemoryStore {
+    private readonly dir;
+    constructor(opts?: AgentMemoryOptions);
+    private dirFor;
+    private pathFor;
+    read(agentId: string, threadId: string): AgentMemoryRead | null;
+    write(agentId: string, threadId: string, fields: AgentMemoryFields): void;
+    delete(agentId: string, threadId: string): void;
+    /** Render an agent's memory for injection into a wake prompt.
+     *  Returns the raw markdown if present; empty string when there's
+     *  no prior memory (the caller decides whether to suppress the
+     *  whole "Your own memory" block). */
+    renderForPrompt(memory: AgentMemoryRead | null): string;
+}
+
+export { AGENT_ROLES, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryFields, type AgentMemoryOptions, type AgentMemoryRead, AgentMemoryStore, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, type CachedMessage, CloudflareClient, type CreateAgentOptions, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DNSConfigurator, type Database, 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, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, 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, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type TunnelConfig, TunnelManager, WARNING_THRESHOLD, type WatcherOptions, buildInboundSecurityAdvisory, classifyEmailRoute, closeDatabase, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, getDatabase, isInternalEmail, isValidPhoneNumber, normalizeAddress, normalizePhoneNumber, normalizeSubject, parseEmail, parseGoogleVoiceSms, recordToolCall, resolveConfig, sanitizeEmail, saveConfig, scanOutboundEmail, scoreEmail, setTelemetryVersion, startRelayBridge, threadIdFor };

package/dist/index.d.ts

@@ -320,6 +320,13 @@ interface Agent {
     updatedAt: string;
     metadata: Record<string, unknown>;
     role: AgentRole;
+    /** Per-agent wake preference. When false, the dispatcher SKIPS
+     *  this agent on every CC-only delivery regardless of the
+     *  sender's `wake` list. Coder/silent-observer agents register
+     *  with `wake_on_cc: false` so a designer's `cc:` accidentally
+     *  including them never wastes a Claude turn. Defaults to true
+     *  (preserves the 0.9.0 wake-list-respecting behaviour). */
+    wakeOnCc?: boolean;
 }
 interface CreateAgentOptions {
     name: string;
@@ -1843,4 +1850,254 @@ 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 Database, 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, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, 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, classifyEmailRoute, closeDatabase, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, getDatabase, isInternalEmail, isValidPhoneNumber, normalizePhoneNumber, parseEmail, parseGoogleVoiceSms, recordToolCall, resolveConfig, sanitizeEmail, saveConfig, scanOutboundEmail, scoreEmail, setTelemetryVersion, startRelayBridge };
+/**
+ * Stable thread-id derivation.
+ *
+ * Two messages belong to the same thread if their normalized
+ * `(subject, root-from)` tuple matches. Computing this on demand
+ * from envelope data is cheap and avoids depending on the IMAP
+ * `THREAD` extension (which Stalwart doesn't advertise) or on
+ * reconstructing `In-Reply-To` / `References` chains (which agents
+ * sometimes forge or strip).
+ *
+ * # Normalization rules
+ *
+ *   - Strip every leading `Re:` / `Fwd:` / `Re[2]:` chain. Some
+ *     clients chain prefixes (`Re: Re: Fwd: Re: …`), which would
+ *     otherwise produce a different thread id for every hop.
+ *   - Collapse internal whitespace to single spaces.
+ *   - Trim leading + trailing whitespace.
+ *   - Lower-case for case-insensitive matching.
+ *   - Reply-on-thread coordination markers (`[FINAL]`, `[DONE]`,
+ *     `[CLOSED]`, `[WRAP]`) are stripped — a closing message
+ *     belongs to the SAME thread as the conversation it closes.
+ *
+ * # Identity hash
+ *
+ * SHA-256 of `<normalizedSubject>\n<rootFromLower>`, base64url
+ * truncated to 16 chars (~12 bytes of entropy = ~10^28 distinct
+ * threads; collision-free for any realistic deployment).
+ *
+ * The root sender is included so two unrelated conversations
+ * that share a generic subject ("hello", "follow up") aren't
+ * collapsed into one thread. We use the FIRST sender's address
+ * on the thread — agents reading a reply pass their own
+ * envelope's `from` value, but the thread id stays stable
+ * because we re-derive `rootFromAddr` from the cache when
+ * looking up an existing thread (see thread-cache.ts).
+ */
+declare function normalizeSubject(subject: string | undefined | null): string;
+declare function normalizeAddress(addr: string | undefined | null): string;
+interface ThreadIdInput {
+    subject?: string | null;
+    /** Optional. Kept as a field so call sites that previously
+     *  passed it keep working, but NOT used in the hash. The thread
+     *  id is intentionally subject-only so a reply from a different
+     *  sender (the replier, not the root) still maps to the same
+     *  thread without needing a cache lookup first. The dispatcher's
+     *  legacy `threadIdFromSubject` uses the same convention; this
+     *  function is its disk-safe + hashed equivalent. */
+    rootFromAddr?: string | null;
+}
+/**
+ * Subject-only stable thread id. Collisions between unrelated
+ * conversations that genuinely share the same normalized subject
+ * ("hello", "follow up") are accepted as the tradeoff for stable
+ * threading across replies. In practice agents on different
+ * threads use different participants, so the wake-budget +
+ * thread-close logic disambiguates downstream.
+ */
+declare function threadIdFor(input: ThreadIdInput): string;
+
+/**
+ * Per-thread message cache — Layer 1 of the wake-context system.
+ *
+ * # What it stores
+ *
+ * Each thread (keyed by the stable `threadIdFor` hash) gets a JSON
+ * file containing the last K message envelopes that were seen on
+ * the thread:
+ *
+ *   { threadId, subject, rootFromAddr, lastUpdated, messages: [
+ *     { uid, from, subject, preview, date }
+ *   ]}
+ *
+ * # What it does NOT store
+ *
+ * - Full message bodies. Storing the body would multiply the cache
+ *   size 20x and most agents don't need it on rehydration — they
+ *   need to see "who said what about what" at a glance, not the
+ *   exact prose. The dedicated `read_email(uid)` MCP tool serves
+ *   the body when the agent actually wants it.
+ *
+ * # Lifecycle
+ *
+ * - Built passively: the dispatcher calls `pushMessage(t, env)` on
+ *   every SSE new-mail event for the thread, even when no agent
+ *   actually wakes. Selective-wake skips, circuit-breaker mutes,
+ *   `[FINAL]` markers — none of them prevent the cache from being
+ *   populated. The cache is always up to date.
+ *
+ * - Read on every spawn: `readCache(t)` is called before the
+ *   dispatcher fires a worker, and the result is rendered into
+ *   the wake prompt.
+ *
+ * - Pruned on close: `cleanupThread(t)` is called when the
+ *   dispatcher detects a thread-close marker. Removes the file
+ *   immediately; 7-day grace via empty-tombstone is not needed
+ *   because the agent's own memory file handles "did this
+ *   thread actually close" semantics.
+ *
+ * - LRU-bounded: a directory-level LRU (default 5000 threads, ~25 MB)
+ *   runs at the head of every write to keep disk usage flat.
+ */
+interface CachedMessage {
+    uid: number;
+    /** Display name OR raw address — whichever was on the envelope. */
+    from: string;
+    /** Sender's bare email (post-normalization). Same value used to
+     *  derive the thread root, so agents can spot "did I write this?"
+     *  with one equality check. */
+    fromAddr: string;
+    subject: string;
+    /** Up to ~240 chars of plain-text body. */
+    preview: string;
+    /** ISO string. */
+    date: string;
+}
+interface ThreadCacheEntry {
+    threadId: string;
+    /** First-seen normalized subject — kept on the entry so the wake
+     *  prompt can show it without re-normalizing. */
+    subject: string;
+    /** First-seen root sender. Used to keep `threadIdFor` stable on
+     *  subsequent replies (which carry the replier's `from`, not
+     *  the original). */
+    rootFromAddr: string;
+    /** ms timestamp of most recent write. Drives LRU eviction. */
+    lastUpdated: number;
+    /** Newest-first. We cap at K — drop oldest on push. */
+    messages: CachedMessage[];
+}
+interface ThreadCacheOptions {
+    /** Override the on-disk root. Mainly for tests. */
+    cacheDir?: string;
+    /** Newest-N messages kept per thread. */
+    k?: number;
+    /** Max threads on disk before LRU eviction kicks in. */
+    lruCap?: number;
+}
+declare class ThreadCache {
+    private readonly dir;
+    private readonly k;
+    private readonly lruCap;
+    constructor(opts?: ThreadCacheOptions);
+    private pathFor;
+    read(threadId: string): ThreadCacheEntry | null;
+    /**
+     * Append a message to the thread's cache, pruning to the K
+     * newest entries. Creates the cache entry on first write.
+     *
+     * `rootFromAddr` is the sender of the ROOT message on the
+     * thread; on a brand-new thread this is just `env.fromAddr`,
+     * on a reply it's read off the existing cache entry (callers
+     * should pass the existing entry's rootFromAddr when known).
+     */
+    pushMessage(threadId: string, env: CachedMessage, meta: {
+        subject: string;
+        rootFromAddr: string;
+    }): ThreadCacheEntry;
+    /** Permanently remove a thread's cache (called on [FINAL] / [DONE] / [CLOSED] / [WRAP]). */
+    delete(threadId: string): void;
+    /**
+     * Render the cache as a compact text block for the wake prompt.
+     * One line per message, newest first. Empty string when the
+     * cache is empty — caller decides whether to suppress the
+     * header in that case.
+     */
+    renderForPrompt(entry: ThreadCacheEntry | null): string;
+    private writeAtomic;
+    /**
+     * Best-effort LRU eviction. Runs at most every 256 writes (we
+     * don't track a precise counter — `Math.random()` sampling keeps
+     * the write path cheap). When the directory has more files than
+     * `lruCap`, sort by mtime ascending and delete the oldest 10%.
+     */
+    private maybeEvict;
+}
+
+/**
+ * Per-agent thread memory — Layer 2 of the wake-context system.
+ *
+ * # What it stores
+ *
+ * Each `(agent, thread)` tuple gets a tiny markdown file
+ * the AGENT writes at the end of its wake. The dispatcher
+ * doesn't write this — it's the agent's own narrative about
+ * what THEY committed to, what's open, and the last action
+ * they took on the thread.
+ *
+ * # Why it's separate from the ThreadCache
+ *
+ * The cache is FACTS (whoever sent what when). The memory is
+ * JUDGMENT (what does each agent intend to do about it). Two
+ * agents on the same thread share the cache verbatim but each
+ * has their own memory file; what Vesper thinks she committed
+ * to is none of Orion's business.
+ *
+ * # Disk layout
+ *
+ *   ~/.agenticmail/agent-memory/<agentId>/<threadId>.md
+ *
+ * The path is hierarchical (per-agent dir) so cleanup on agent
+ * deletion is `rm -rf <agentDir>` and concurrent writers don't
+ * step on each other across agents.
+ *
+ * # Format
+ *
+ * Tiny YAML frontmatter for structured fields the dispatcher
+ * cares about (`updated_at`, `lastUid`); free-form markdown
+ * body for the agent's prose. The agent passes these as
+ * separate fields on the MCP tool and we render the file
+ * deterministically — no Markdown-in-YAML parsing nightmare.
+ */
+interface AgentMemoryFields {
+    /** One-paragraph narrative of where the thread stands. */
+    summary?: string;
+    /** Things THIS agent has committed to doing. */
+    commitments?: string[];
+    /** Things THIS agent is waiting on / open questions. */
+    openQuestions?: string[];
+    /** Last action this agent took on the thread (e.g. "replied UID 41 asking for the raw counts"). */
+    lastAction?: string;
+    /** Last message UID this agent has digested. Used as a cursor
+     *  to detect "memory is older than the cache" on the dispatcher
+     *  side. */
+    lastUid?: number;
+}
+interface AgentMemoryRead extends AgentMemoryFields {
+    /** ISO timestamp of the most recent write. */
+    updatedAt?: string;
+    /** Raw file contents — useful for the wake prompt; rendered
+     *  verbatim into the "Your own memory" block. */
+    raw: string;
+}
+interface AgentMemoryOptions {
+    memoryDir?: string;
+}
+declare class AgentMemoryStore {
+    private readonly dir;
+    constructor(opts?: AgentMemoryOptions);
+    private dirFor;
+    private pathFor;
+    read(agentId: string, threadId: string): AgentMemoryRead | null;
+    write(agentId: string, threadId: string, fields: AgentMemoryFields): void;
+    delete(agentId: string, threadId: string): void;
+    /** Render an agent's memory for injection into a wake prompt.
+     *  Returns the raw markdown if present; empty string when there's
+     *  no prior memory (the caller decides whether to suppress the
+     *  whole "Your own memory" block). */
+    renderForPrompt(memory: AgentMemoryRead | null): string;
+}
+
+export { AGENT_ROLES, AccountManager, type AddressInfo, type Agent, AgentDeletionService, type AgentMemoryFields, type AgentMemoryOptions, type AgentMemoryRead, AgentMemoryStore, type AgentRole, AgenticMailClient, type AgenticMailClientOptions, type AgenticMailConfig, type ArchiveAndDeleteOptions, type ArchivedEmail, type Attachment, type AttachmentAdvisory, type CachedMessage, CloudflareClient, type CreateAgentOptions, DEFAULT_AGENT_NAME, DEFAULT_AGENT_ROLE, DNSConfigurator, type Database, 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, type EmailRouteAction, type EmailRouteClass, type EmailRouteClassification, type EmailRouteInput, 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, ThreadCache, type ThreadCacheEntry, type ThreadCacheOptions, type ThreadIdInput, type TunnelConfig, TunnelManager, WARNING_THRESHOLD, type WatcherOptions, buildInboundSecurityAdvisory, classifyEmailRoute, closeDatabase, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, getDatabase, isInternalEmail, isValidPhoneNumber, normalizeAddress, normalizePhoneNumber, normalizeSubject, parseEmail, parseGoogleVoiceSms, recordToolCall, resolveConfig, sanitizeEmail, saveConfig, scanOutboundEmail, scoreEmail, setTelemetryVersion, startRelayBridge, threadIdFor };