@agenticmail/core 0.9.6 → 0.9.7

package/dist/index.d.cts

@@ -200,6 +200,20 @@ interface AgenticMailConfig {
         provider?: 'google_voice';
         configuredAt?: string;
     };
+    /**
+     * Operator's notification address. Used by the dispatcher's
+     * bridge-escalation path: when sub-agents mail a bridge inbox AND
+     * no fresh host session is available for a headless resume, the
+     * API forwards a digest to this address so the operator gets a
+     * phone push (via Gmail / Apple Mail / whichever app handles
+     * their address). Set during install — the host agent (claude /
+     * codex) collects it via the `setup_operator_email` MCP tool
+     * during bootstrap and persists it here.
+     *
+     * Optional. When unset, escalations are still recorded as a
+     * system event (visible in the web UI) but no email is sent.
+     */
+    operatorEmail?: string;
     masterKey: string;
     dataDir: string;
 }
@@ -1493,6 +1507,28 @@ declare class SmsManager {
     getSmsConfig(agentId: string): SmsConfig | null;
     /** Save SMS config to agent metadata */
     saveSmsConfig(agentId: string, config: SmsConfig): void;
+    /**
+     * Resolve the operator's "where do I get pinged" address from an
+     * agent's SMS config. Used by the dispatcher's bridge-escalation
+     * path: when sub-agents mail a bridge with no fresh host session
+     * available, we email the operator a digest at this address. Their
+     * phone's Gmail push notification surfaces it within seconds —
+     * effectively a free, programmatic alert channel.
+     *
+     * Returns the configured `forwardingEmail` (the same Gmail Google
+     * Voice forwards inbound SMS to, which the operator already has
+     * push notifications enabled for) when SMS is configured AND
+     * enabled. Returns null otherwise — caller falls through to a
+     * silent log + system event.
+     *
+     * Why we don't try real-SMS delivery yet: Google Voice's
+     * `<number>@txt.voice.google.com` email-to-SMS gateway was
+     * deprecated by Google years ago. A future `carrier` field on
+     * SmsConfig (Verizon vtext.com / AT&T txt.att.net / etc) will let
+     * the operator opt into actual SMS, but that's a follow-up — the
+     * email path already gets the operator a phone notification.
+     */
+    getAlertEmail(agentId: string): string | null;
     /** Remove SMS config from agent metadata */
     removeSmsConfig(agentId: string): void;
     /** Record an inbound SMS (parsed from email) */
@@ -1764,6 +1800,38 @@ declare function redactSecret(value: unknown): string;
  */
 declare function redactObject<T>(input: T, _depth?: number): T;
 
+/**
+ * Operator preferences — small per-installation knobs that don't fit
+ * cleanly in the bootstrap-managed `~/.agenticmail/config.json`.
+ *
+ * Currently just `operatorEmail` for bridge-escalation alerts. The
+ * intent is a tiny mutable surface the host agent (claudecode /
+ * codex) can update via MCP without touching the read-only-after-
+ * bootstrap config blob.
+ *
+ * # Storage
+ *
+ * `~/.agenticmail/operator-prefs.json`:
+ *
+ * ```json
+ * { "version": 1, "operatorEmail": "ope@gmail.com" }
+ * ```
+ *
+ * Atomic writes (tmp + rename), tolerant of missing / corrupt
+ * files (returns null and lets the caller decide). Lazy path
+ * resolution so tests can override `homedir()` per-test.
+ */
+/** Returns the operator's escalation email, or null if not set. */
+declare function getOperatorEmail(): string | null;
+/**
+ * Set (or clear) the operator's escalation email. Pass `null` /
+ * empty string to clear. Returns the canonical stored value (trimmed,
+ * lowercased local-part preserved as-is per RFC 5321).
+ */
+declare function setOperatorEmail(email: string | null): string | null;
+/** Exposed for tests + diagnostic CLI commands. */
+declare function operatorPrefsStoragePath(): string;
+
 /**
  * Persisted host-session registry.
  *
@@ -2494,4 +2562,4 @@ declare class AgentMemoryStore {
     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, DEFAULT_SESSION_MAX_AGE_MS, 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 HostName, type HostSession, 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, PathTraversalError, type PurchasedDomain, REDACTED, RELAY_PRESETS, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, SPAM_THRESHOLD, type SafeJoinOptions, 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, UnsafeApiUrlError, WARNING_THRESHOLD, type WatcherOptions, assertWithinBase, buildApiUrl, buildInboundSecurityAdvisory, classifyEmailRoute, closeDatabase, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, forgetHostSession, getDatabase, hostSessionStoragePath, isInternalEmail, isSessionFresh, isValidPhoneNumber, loadHostSession, normalizeAddress, normalizePhoneNumber, normalizeSubject, parseEmail, parseGoogleVoiceSms, recordToolCall, redactObject, redactSecret, resolveConfig, safeJoin, sanitizeEmail, saveConfig, saveHostSession, scanOutboundEmail, scoreEmail, setTelemetryVersion, startRelayBridge, threadIdFor, tryJoin, validateApiUrl };
+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, DEFAULT_SESSION_MAX_AGE_MS, 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 HostName, type HostSession, 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, PathTraversalError, type PurchasedDomain, REDACTED, RELAY_PRESETS, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, SPAM_THRESHOLD, type SafeJoinOptions, 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, UnsafeApiUrlError, WARNING_THRESHOLD, type WatcherOptions, assertWithinBase, buildApiUrl, buildInboundSecurityAdvisory, classifyEmailRoute, closeDatabase, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, forgetHostSession, getDatabase, getOperatorEmail, hostSessionStoragePath, isInternalEmail, isSessionFresh, isValidPhoneNumber, loadHostSession, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, parseEmail, parseGoogleVoiceSms, recordToolCall, redactObject, redactSecret, resolveConfig, safeJoin, sanitizeEmail, saveConfig, saveHostSession, scanOutboundEmail, scoreEmail, setOperatorEmail, setTelemetryVersion, startRelayBridge, threadIdFor, tryJoin, validateApiUrl };

package/dist/index.d.ts

@@ -200,6 +200,20 @@ interface AgenticMailConfig {
         provider?: 'google_voice';
         configuredAt?: string;
     };
+    /**
+     * Operator's notification address. Used by the dispatcher's
+     * bridge-escalation path: when sub-agents mail a bridge inbox AND
+     * no fresh host session is available for a headless resume, the
+     * API forwards a digest to this address so the operator gets a
+     * phone push (via Gmail / Apple Mail / whichever app handles
+     * their address). Set during install — the host agent (claude /
+     * codex) collects it via the `setup_operator_email` MCP tool
+     * during bootstrap and persists it here.
+     *
+     * Optional. When unset, escalations are still recorded as a
+     * system event (visible in the web UI) but no email is sent.
+     */
+    operatorEmail?: string;
     masterKey: string;
     dataDir: string;
 }
@@ -1493,6 +1507,28 @@ declare class SmsManager {
     getSmsConfig(agentId: string): SmsConfig | null;
     /** Save SMS config to agent metadata */
     saveSmsConfig(agentId: string, config: SmsConfig): void;
+    /**
+     * Resolve the operator's "where do I get pinged" address from an
+     * agent's SMS config. Used by the dispatcher's bridge-escalation
+     * path: when sub-agents mail a bridge with no fresh host session
+     * available, we email the operator a digest at this address. Their
+     * phone's Gmail push notification surfaces it within seconds —
+     * effectively a free, programmatic alert channel.
+     *
+     * Returns the configured `forwardingEmail` (the same Gmail Google
+     * Voice forwards inbound SMS to, which the operator already has
+     * push notifications enabled for) when SMS is configured AND
+     * enabled. Returns null otherwise — caller falls through to a
+     * silent log + system event.
+     *
+     * Why we don't try real-SMS delivery yet: Google Voice's
+     * `<number>@txt.voice.google.com` email-to-SMS gateway was
+     * deprecated by Google years ago. A future `carrier` field on
+     * SmsConfig (Verizon vtext.com / AT&T txt.att.net / etc) will let
+     * the operator opt into actual SMS, but that's a follow-up — the
+     * email path already gets the operator a phone notification.
+     */
+    getAlertEmail(agentId: string): string | null;
     /** Remove SMS config from agent metadata */
     removeSmsConfig(agentId: string): void;
     /** Record an inbound SMS (parsed from email) */
@@ -1764,6 +1800,38 @@ declare function redactSecret(value: unknown): string;
  */
 declare function redactObject<T>(input: T, _depth?: number): T;
 
+/**
+ * Operator preferences — small per-installation knobs that don't fit
+ * cleanly in the bootstrap-managed `~/.agenticmail/config.json`.
+ *
+ * Currently just `operatorEmail` for bridge-escalation alerts. The
+ * intent is a tiny mutable surface the host agent (claudecode /
+ * codex) can update via MCP without touching the read-only-after-
+ * bootstrap config blob.
+ *
+ * # Storage
+ *
+ * `~/.agenticmail/operator-prefs.json`:
+ *
+ * ```json
+ * { "version": 1, "operatorEmail": "ope@gmail.com" }
+ * ```
+ *
+ * Atomic writes (tmp + rename), tolerant of missing / corrupt
+ * files (returns null and lets the caller decide). Lazy path
+ * resolution so tests can override `homedir()` per-test.
+ */
+/** Returns the operator's escalation email, or null if not set. */
+declare function getOperatorEmail(): string | null;
+/**
+ * Set (or clear) the operator's escalation email. Pass `null` /
+ * empty string to clear. Returns the canonical stored value (trimmed,
+ * lowercased local-part preserved as-is per RFC 5321).
+ */
+declare function setOperatorEmail(email: string | null): string | null;
+/** Exposed for tests + diagnostic CLI commands. */
+declare function operatorPrefsStoragePath(): string;
+
 /**
  * Persisted host-session registry.
  *
@@ -2494,4 +2562,4 @@ declare class AgentMemoryStore {
     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, DEFAULT_SESSION_MAX_AGE_MS, 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 HostName, type HostSession, 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, PathTraversalError, type PurchasedDomain, REDACTED, RELAY_PRESETS, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, SPAM_THRESHOLD, type SafeJoinOptions, 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, UnsafeApiUrlError, WARNING_THRESHOLD, type WatcherOptions, assertWithinBase, buildApiUrl, buildInboundSecurityAdvisory, classifyEmailRoute, closeDatabase, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, forgetHostSession, getDatabase, hostSessionStoragePath, isInternalEmail, isSessionFresh, isValidPhoneNumber, loadHostSession, normalizeAddress, normalizePhoneNumber, normalizeSubject, parseEmail, parseGoogleVoiceSms, recordToolCall, redactObject, redactSecret, resolveConfig, safeJoin, sanitizeEmail, saveConfig, saveHostSession, scanOutboundEmail, scoreEmail, setTelemetryVersion, startRelayBridge, threadIdFor, tryJoin, validateApiUrl };
+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, DEFAULT_SESSION_MAX_AGE_MS, 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 HostName, type HostSession, 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, PathTraversalError, type PurchasedDomain, REDACTED, RELAY_PRESETS, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, SPAM_THRESHOLD, type SafeJoinOptions, 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, UnsafeApiUrlError, WARNING_THRESHOLD, type WatcherOptions, assertWithinBase, buildApiUrl, buildInboundSecurityAdvisory, classifyEmailRoute, closeDatabase, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, forgetHostSession, getDatabase, getOperatorEmail, hostSessionStoragePath, isInternalEmail, isSessionFresh, isValidPhoneNumber, loadHostSession, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, parseEmail, parseGoogleVoiceSms, recordToolCall, redactObject, redactSecret, resolveConfig, safeJoin, sanitizeEmail, saveConfig, saveHostSession, scanOutboundEmail, scoreEmail, setOperatorEmail, setTelemetryVersion, startRelayBridge, threadIdFor, tryJoin, validateApiUrl };