@agenticmail/core 0.9.5 → 0.9.6

package/dist/index.d.cts

@@ -1764,6 +1764,129 @@ declare function redactSecret(value: unknown): string;
  */
 declare function redactObject<T>(input: T, _depth?: number): T;
 
+/**
+ * Persisted host-session registry.
+ *
+ * # What this is for
+ *
+ * When a sub-agent replies into the host bridge inbox
+ * (`claudecode@localhost` / `codex@localhost`), the dispatcher
+ * historically had no way to react: bridges are skipped by
+ * `shouldWatch` because they belong to the human operator's host CLI,
+ * not to an automated worker. The mail would sit unread until the
+ * operator opened their CLI again — sometimes hours later, sometimes
+ * never that day.
+ *
+ * This module is the missing link. Every time the host's mail-hook
+ * fires (on `SessionStart` / `UserPromptSubmit` / `Stop`), it captures
+ * the host CLI's current `session_id` and persists it here. The
+ * dispatcher can then check "what session was running last?" and
+ * attempt a headless resume against it when bridge mail arrives —
+ * the same way Telegram bridges (Fola, etc.) keep a session alive
+ * between bursts of activity.
+ *
+ * # The file
+ *
+ * `~/.agenticmail/host-sessions.json`:
+ *
+ * ```json
+ * {
+ *   "version": 1,
+ *   "sessions": {
+ *     "claudecode": {
+ *       "sessionId": "01a2b3c4-…",
+ *       "workspace": "/Users/ope/Desktop/facebook-project",
+ *       "lastSeenMs": 1778905200000,
+ *       "model": "claude-sonnet-4-5"
+ *     },
+ *     "codex": {
+ *       "sessionId": "019a2b3c-…",
+ *       "workspace": "/Users/ope/Desktop/facebook-project",
+ *       "lastSeenMs": 1778905100000
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Per host we keep ONE session — the most recent. If the operator
+ * runs `claude` twice (e.g. one window for "general", one for "build
+ * the LinkedIn clone"), we only track the last-active one. The
+ * bridge resume always targets whichever was active most recently;
+ * the operator's intuition matches that ("I just left my Claude
+ * Code session a minute ago and the bridge ought to be able to
+ * resume it").
+ *
+ * # Freshness semantics
+ *
+ * A session is considered "resumable" if `lastSeenMs` is within the
+ * last 24 hours. Older than that, both Anthropic and OpenAI tend to
+ * have evicted the session from their resume cache (cost-driven
+ * decision; observed empirically). The dispatcher uses
+ * `isSessionFresh(session, maxAgeMs)` to gate the resume attempt and
+ * fall through to SMS / persistent storage when stale.
+ *
+ * # Atomic writes
+ *
+ * The mail-hook can fire concurrently with another hook on a
+ * different host CLI window. The write path goes through a tmp file
+ * + rename so a torn write can never leave a half-valid JSON file
+ * that crashes the next reader. Same shape as `dispatcher-state.ts`.
+ */
+/** Canonical names for the host integrations that own bridge inboxes. */
+type HostName = 'claudecode' | 'codex';
+/**
+ * A snapshot of one host CLI's last-known session. Persisted to disk
+ * by the mail-hook on every fire; loaded by the dispatcher when
+ * bridge mail arrives so a resume can be attempted.
+ */
+interface HostSession {
+    /** Stable session_id from the host CLI (Claude Code or Codex). */
+    sessionId: string;
+    /** Wall-clock timestamp of the last hook fire on this session. */
+    lastSeenMs: number;
+    /** Optional: project cwd the host CLI was opened in. Used by
+     *  resume to spawn the headless turn in the right directory. */
+    workspace?: string;
+    /** Optional: model name the host session was using, surfaced
+     *  in logs for diagnostic context. */
+    model?: string;
+}
+/** Default freshness window — sessions older than this are skipped. */
+declare const DEFAULT_SESSION_MAX_AGE_MS: number;
+/**
+ * Record the current host session. Called from the mail-hook on
+ * every fire with the `session_id` the host passed in. Updates the
+ * existing record for that host or creates one — last write wins.
+ *
+ * Failures are swallowed so the mail-hook never crashes the host CLI
+ * over a disk write. The bridge-wake path tolerates a missing record
+ * (falls through to SMS).
+ */
+declare function saveHostSession(host: HostName, session: Omit<HostSession, 'lastSeenMs'>): void;
+/**
+ * Look up the most-recent session for a host. Returns null when no
+ * record exists OR the record is older than `maxAgeMs` (default 24h).
+ *
+ * The age gate exists because both providers expire resume tokens
+ * after roughly a day; attempting resume against a stale token is
+ * almost always slower than starting fresh.
+ */
+declare function loadHostSession(host: HostName, maxAgeMs?: number): HostSession | null;
+/**
+ * Pure freshness predicate — exported for tests + for callers that
+ * want to read the raw record (e.g. to print "last seen 2 hours ago"
+ * in a diagnostic command).
+ */
+declare function isSessionFresh(session: HostSession, maxAgeMs?: number): boolean;
+/**
+ * Clear a host's recorded session. Called when the operator runs
+ * `agenticmail-<host> uninstall` so the next install doesn't try to
+ * resume a session that no longer exists.
+ */
+declare function forgetHostSession(host: HostName): void;
+/** Exposed for tests + the `agenticmail status` diagnostic command. */
+declare function hostSessionStoragePath(): string;
+
 /**
  * SSRF-safe URL validation for the AgenticMail API base URL.
  *
@@ -2371,4 +2494,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, 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, 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, getDatabase, isInternalEmail, isValidPhoneNumber, normalizeAddress, normalizePhoneNumber, normalizeSubject, parseEmail, parseGoogleVoiceSms, recordToolCall, redactObject, redactSecret, resolveConfig, safeJoin, sanitizeEmail, saveConfig, 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, 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 };

package/dist/index.d.ts

@@ -1764,6 +1764,129 @@ declare function redactSecret(value: unknown): string;
  */
 declare function redactObject<T>(input: T, _depth?: number): T;
 
+/**
+ * Persisted host-session registry.
+ *
+ * # What this is for
+ *
+ * When a sub-agent replies into the host bridge inbox
+ * (`claudecode@localhost` / `codex@localhost`), the dispatcher
+ * historically had no way to react: bridges are skipped by
+ * `shouldWatch` because they belong to the human operator's host CLI,
+ * not to an automated worker. The mail would sit unread until the
+ * operator opened their CLI again — sometimes hours later, sometimes
+ * never that day.
+ *
+ * This module is the missing link. Every time the host's mail-hook
+ * fires (on `SessionStart` / `UserPromptSubmit` / `Stop`), it captures
+ * the host CLI's current `session_id` and persists it here. The
+ * dispatcher can then check "what session was running last?" and
+ * attempt a headless resume against it when bridge mail arrives —
+ * the same way Telegram bridges (Fola, etc.) keep a session alive
+ * between bursts of activity.
+ *
+ * # The file
+ *
+ * `~/.agenticmail/host-sessions.json`:
+ *
+ * ```json
+ * {
+ *   "version": 1,
+ *   "sessions": {
+ *     "claudecode": {
+ *       "sessionId": "01a2b3c4-…",
+ *       "workspace": "/Users/ope/Desktop/facebook-project",
+ *       "lastSeenMs": 1778905200000,
+ *       "model": "claude-sonnet-4-5"
+ *     },
+ *     "codex": {
+ *       "sessionId": "019a2b3c-…",
+ *       "workspace": "/Users/ope/Desktop/facebook-project",
+ *       "lastSeenMs": 1778905100000
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Per host we keep ONE session — the most recent. If the operator
+ * runs `claude` twice (e.g. one window for "general", one for "build
+ * the LinkedIn clone"), we only track the last-active one. The
+ * bridge resume always targets whichever was active most recently;
+ * the operator's intuition matches that ("I just left my Claude
+ * Code session a minute ago and the bridge ought to be able to
+ * resume it").
+ *
+ * # Freshness semantics
+ *
+ * A session is considered "resumable" if `lastSeenMs` is within the
+ * last 24 hours. Older than that, both Anthropic and OpenAI tend to
+ * have evicted the session from their resume cache (cost-driven
+ * decision; observed empirically). The dispatcher uses
+ * `isSessionFresh(session, maxAgeMs)` to gate the resume attempt and
+ * fall through to SMS / persistent storage when stale.
+ *
+ * # Atomic writes
+ *
+ * The mail-hook can fire concurrently with another hook on a
+ * different host CLI window. The write path goes through a tmp file
+ * + rename so a torn write can never leave a half-valid JSON file
+ * that crashes the next reader. Same shape as `dispatcher-state.ts`.
+ */
+/** Canonical names for the host integrations that own bridge inboxes. */
+type HostName = 'claudecode' | 'codex';
+/**
+ * A snapshot of one host CLI's last-known session. Persisted to disk
+ * by the mail-hook on every fire; loaded by the dispatcher when
+ * bridge mail arrives so a resume can be attempted.
+ */
+interface HostSession {
+    /** Stable session_id from the host CLI (Claude Code or Codex). */
+    sessionId: string;
+    /** Wall-clock timestamp of the last hook fire on this session. */
+    lastSeenMs: number;
+    /** Optional: project cwd the host CLI was opened in. Used by
+     *  resume to spawn the headless turn in the right directory. */
+    workspace?: string;
+    /** Optional: model name the host session was using, surfaced
+     *  in logs for diagnostic context. */
+    model?: string;
+}
+/** Default freshness window — sessions older than this are skipped. */
+declare const DEFAULT_SESSION_MAX_AGE_MS: number;
+/**
+ * Record the current host session. Called from the mail-hook on
+ * every fire with the `session_id` the host passed in. Updates the
+ * existing record for that host or creates one — last write wins.
+ *
+ * Failures are swallowed so the mail-hook never crashes the host CLI
+ * over a disk write. The bridge-wake path tolerates a missing record
+ * (falls through to SMS).
+ */
+declare function saveHostSession(host: HostName, session: Omit<HostSession, 'lastSeenMs'>): void;
+/**
+ * Look up the most-recent session for a host. Returns null when no
+ * record exists OR the record is older than `maxAgeMs` (default 24h).
+ *
+ * The age gate exists because both providers expire resume tokens
+ * after roughly a day; attempting resume against a stale token is
+ * almost always slower than starting fresh.
+ */
+declare function loadHostSession(host: HostName, maxAgeMs?: number): HostSession | null;
+/**
+ * Pure freshness predicate — exported for tests + for callers that
+ * want to read the raw record (e.g. to print "last seen 2 hours ago"
+ * in a diagnostic command).
+ */
+declare function isSessionFresh(session: HostSession, maxAgeMs?: number): boolean;
+/**
+ * Clear a host's recorded session. Called when the operator runs
+ * `agenticmail-<host> uninstall` so the next install doesn't try to
+ * resume a session that no longer exists.
+ */
+declare function forgetHostSession(host: HostName): void;
+/** Exposed for tests + the `agenticmail status` diagnostic command. */
+declare function hostSessionStoragePath(): string;
+
 /**
  * SSRF-safe URL validation for the AgenticMail API base URL.
  *
@@ -2371,4 +2494,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, 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, 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, getDatabase, isInternalEmail, isValidPhoneNumber, normalizeAddress, normalizePhoneNumber, normalizeSubject, parseEmail, parseGoogleVoiceSms, recordToolCall, redactObject, redactSecret, resolveConfig, safeJoin, sanitizeEmail, saveConfig, 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, 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 };