@agenticmail/core 0.9.10 → 0.9.12

package/dist/index.cjs

@@ -774,6 +774,7 @@ __export(index_exports, {
   operatorPrefsStoragePath: () => operatorPrefsStoragePath,
   parseEmail: () => parseEmail,
   parseGoogleVoiceSms: () => parseGoogleVoiceSms,
+  planBridgeWake: () => planBridgeWake,
   recordToolCall: () => recordToolCall,
   redactObject: () => redactObject,
   redactSecret: () => redactSecret,
@@ -2079,7 +2080,13 @@ function rowToAgent(row) {
     // Old rows (pre-migration-016) have undefined `wake_on_cc`;
     // treat that as the default-true (respect sender's wake list
     // as-is). Only explicit 0 disables CC wakes for this agent.
-    wakeOnCc: row.wake_on_cc !== void 0 ? row.wake_on_cc !== 0 : true
+    wakeOnCc: row.wake_on_cc !== void 0 ? row.wake_on_cc !== 0 : true,
+    // Pre-migration-017 rows have undefined `stopped`; treat as
+    // not-stopped. The dispatcher only blocks wakes when this is
+    // explicitly truthy, so the default mirrors back-compat.
+    stopped: row.stopped !== void 0 ? row.stopped !== 0 : false,
+    stoppedAt: row.stopped_at ?? null,
+    stoppedReason: row.stopped_reason ?? null
   };
 }
 var AccountManager = class {
@@ -3697,6 +3704,22 @@ ALTER TABLE drafts ADD COLUMN attachments TEXT;
 -- explicitly named" preference from the wake-thrash feedback.
 -- Defaults to 1 (respect the senders wake list as-is).
 ALTER TABLE agents ADD COLUMN wake_on_cc INTEGER NOT NULL DEFAULT 1;
+`,
+  "017_agent_stopped.sql": `
+-- Soft-stop for an agent mid-task. When 1, the dispatcher refuses
+-- to wake this agent for ANY reason \u2014 allowlists, To/Cc, task
+-- notifications, all of it. Mail still gets delivered to the
+-- mailbox so the audit trail of the thread stays intact. This
+-- is the non-destructive counterpart to delete_agent: stops an
+-- agent that's currently churning without losing its inbox or
+-- the thread history.
+--
+-- Companion columns capture WHEN it was stopped and the OPTIONAL
+-- reason the caller passed (e.g. "task superseded", "budget
+-- exhausted") so an operator can audit later.
+ALTER TABLE agents ADD COLUMN stopped INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE agents ADD COLUMN stopped_at TEXT;
+ALTER TABLE agents ADD COLUMN stopped_reason TEXT;
 `
 };
 function runMigrations(database) {
@@ -3970,9 +3993,67 @@ function formatPollError(err) {
   const stdout = (e.stdout ?? "").toString().trim();
   if (stdout && !stderr) parts.push(`stdout=${truncate(stdout, 240)}`);
   if (parts.length === 1 && /^command failed$/i.test(head)) {
-    return `${head} (no further detail available \u2014 wrapping error did not carry stderr/code/response)`;
+    return redactCredentialTokens(`${head} (no further detail available \u2014 wrapping error did not carry stderr/code/response)`);
+  }
+  return redactCredentialTokens(parts.join(" | "));
+}
+function redactCredentialTokens(text) {
+  return text.replace(/\b(AUTH(?:ENTICATE)?)\s+(PLAIN|LOGIN|XOAUTH2|CRAM-MD5|EXTERNAL)\s+\S+/gi, "$1 $2 [redacted]").replace(/\b(AUTH(?:ENTICATE)?)\s+([A-Za-z0-9+/]{16,}={0,2})\b/gi, "$1 [redacted]");
+}
+function isRelayCredentialError(err) {
+  if (!err) return false;
+  const haystack = typeof err === "object" ? (() => {
+    const e = err;
+    return [
+      e.message,
+      e.code,
+      e.responseCode,
+      e.response,
+      e.responseText,
+      e.command,
+      e.serverResponse
+    ].filter(Boolean).join(" ").toLowerCase();
+  })() : String(err).toLowerCase();
+  return [
+    "eauth",
+    "authenticationfailed",
+    "authentication failed",
+    "authenticate failed",
+    "invalid credentials",
+    "invalid login",
+    "login failed",
+    "username and password not accepted",
+    "application-specific password",
+    "app password",
+    "badcredentials",
+    "invalid_grant",
+    "invalid_token",
+    "expired token",
+    "token expired",
+    "access token has expired",
+    "token has expired",
+    "token is expired",
+    "token is invalid",
+    "token revoked",
+    "xoauth2",
+    "aadsts",
+    "535",
+    "534",
+    "5.7.8"
+  ].some((marker) => haystack.includes(marker));
+}
+function formatRelayError(err, config, phase) {
+  const detail = formatPollError(err);
+  if (!isRelayCredentialError(err)) {
+    return `Relay ${phase} failed: ${detail}`;
   }
-  return parts.join(" | ");
+  const provider = config.provider === "gmail" ? "Gmail" : config.provider === "outlook" ? "Outlook/Microsoft 365" : "custom";
+  const action = config.provider === "gmail" ? "Create a fresh Gmail app password or reconnect the relay, then run agenticmail setup-relay again." : config.provider === "outlook" ? "Refresh/recreate the Microsoft relay credential or OAuth token, then run agenticmail setup-relay again." : "Refresh the relay credential, then run agenticmail setup-relay again.";
+  return [
+    `Relay ${phase} failed: ${provider} relay authentication for ${config.email} is invalid, expired, or revoked.`,
+    action,
+    `Original error: ${detail}`
+  ].join(" ");
 }
 function truncate(s, max) {
   if (s.length <= max) return s;
@@ -4027,7 +4108,11 @@ var RelayGateway = class {
         pass: config.password
       }
     });
-    await this.smtpTransport.verify();
+    try {
+      await this.smtpTransport.verify();
+    } catch (err) {
+      throw new Error(formatRelayError(err, config, "SMTP verification"));
+    }
     const imap = new import_imapflow3.ImapFlow({
       host: config.imapHost,
       port: config.imapPort,
@@ -4038,8 +4123,16 @@ var RelayGateway = class {
       },
       logger: false
     });
-    await imap.connect();
-    await imap.logout();
+    try {
+      await imap.connect();
+    } catch (err) {
+      throw new Error(formatRelayError(err, config, "IMAP verification"));
+    } finally {
+      try {
+        await imap.logout();
+      } catch {
+      }
+    }
   }
   /**
    * Send an email through the relay SMTP server.
@@ -4049,9 +4142,10 @@ var RelayGateway = class {
     if (!this.config || !this.smtpTransport) {
       throw new Error("Relay not configured. Call setup() first.");
     }
-    const atIdx = this.config.email.lastIndexOf("@");
-    const localPart2 = this.config.email.slice(0, atIdx);
-    const domain = this.config.email.slice(atIdx + 1);
+    const relayConfig = this.config;
+    const atIdx = relayConfig.email.lastIndexOf("@");
+    const localPart2 = relayConfig.email.slice(0, atIdx);
+    const domain = relayConfig.email.slice(atIdx + 1);
     const relayFrom = `${localPart2}+${agentName}@${domain}`;
     const displayName = mail.fromName || agentName;
     const mailOpts = {
@@ -4075,7 +4169,12 @@ var RelayGateway = class {
     };
     const composer = new import_mail_composer2.default(mailOpts);
     const raw = await composer.compile().build();
-    const result = await this.smtpTransport.sendMail(mailOpts);
+    let result;
+    try {
+      result = await this.smtpTransport.sendMail(mailOpts);
+    } catch (err) {
+      throw new Error(formatRelayError(err, relayConfig, "SMTP send"));
+    }
     if (result.messageId) {
       this.sentMessageIds.set(result.messageId, agentName);
       if (this.sentMessageIds.size > 1e4) {
@@ -4152,7 +4251,7 @@ var RelayGateway = class {
       this.consecutiveFailures = 0;
     } catch (err) {
       this.consecutiveFailures++;
-      const msg = formatPollError(err);
+      const msg = this.config ? formatRelayError(err, this.config, "IMAP poll") : formatPollError(err);
       console.error(`[RelayGateway] Poll failed (attempt ${this.consecutiveFailures}): ${msg}`);
       if (this.consecutiveFailures >= 5 && this.consecutiveFailures % 5 === 0) {
         console.error(`[RelayGateway] ${this.consecutiveFailures} consecutive failures \u2014 check IMAP credentials and connectivity (${this.config?.imapHost}:${this.config?.imapPort})`);
@@ -4385,13 +4484,14 @@ var RelayGateway = class {
    */
   async searchRelay(criteria, maxResults = 50) {
     if (!this.config) throw new Error("Relay not configured");
+    const relayConfig = this.config;
     const imap = new import_imapflow3.ImapFlow({
-      host: this.config.imapHost,
-      port: this.config.imapPort,
-      secure: this.config.imapPort === 993,
+      host: relayConfig.imapHost,
+      port: relayConfig.imapPort,
+      secure: relayConfig.imapPort === 993,
       auth: {
-        user: this.config.email,
-        pass: this.config.password
+        user: relayConfig.email,
+        pass: relayConfig.password
       },
       logger: false
     });
@@ -4428,7 +4528,7 @@ var RelayGateway = class {
             results.push({
               uid,
               source: "relay",
-              account: this.config.email,
+              account: relayConfig.email,
               messageId: envelope.messageId ?? "",
               subject: envelope.subject ?? "",
               from: (envelope.from ?? []).map((a) => ({ name: a.name, address: a.address ?? "" })),
@@ -4444,7 +4544,7 @@ var RelayGateway = class {
         lock.release();
       }
     } catch (err) {
-      console.error("[RelayGateway] Relay search failed:", err instanceof Error ? err.message : err);
+      console.error("[RelayGateway] Relay search failed:", formatRelayError(err, relayConfig, "IMAP search"));
       return [];
     } finally {
       try {
@@ -4459,13 +4559,14 @@ var RelayGateway = class {
    */
   async fetchRelayMessage(uid) {
     if (!this.config) throw new Error("Relay not configured");
+    const relayConfig = this.config;
     const imap = new import_imapflow3.ImapFlow({
-      host: this.config.imapHost,
-      port: this.config.imapPort,
-      secure: this.config.imapPort === 993,
+      host: relayConfig.imapHost,
+      port: relayConfig.imapPort,
+      secure: relayConfig.imapPort === 993,
       auth: {
-        user: this.config.email,
-        pass: this.config.password
+        user: relayConfig.email,
+        pass: relayConfig.password
       },
       logger: false
     });
@@ -4502,7 +4603,7 @@ var RelayGateway = class {
         lock.release();
       }
     } catch (err) {
-      console.error("[RelayGateway] Fetch relay message failed:", err instanceof Error ? err.message : err);
+      console.error("[RelayGateway] Fetch relay message failed:", formatRelayError(err, relayConfig, "IMAP fetch"));
       return null;
     } finally {
       try {
@@ -7276,6 +7377,32 @@ function shouldSkipBridgeWakeForLiveOperator(session, nowMs = Date.now(), liveWi
   const ageMs = bridgeWakeLastSeenAgeMs(session, nowMs);
   return ageMs !== null && ageMs < liveWindowMs;
 }
+function planBridgeWake(args) {
+  const nowMs = args.nowMs ?? Date.now();
+  const liveWindowMs = args.liveWindowMs ?? BRIDGE_OPERATOR_LIVE_WINDOW_MS;
+  const ageMs = bridgeWakeLastSeenAgeMs(args.session, nowMs);
+  if (ageMs !== null && ageMs < liveWindowMs) {
+    return {
+      action: "skip-live",
+      reason: "operator-live",
+      ageMs,
+      mail: args.mail
+    };
+  }
+  if (!args.session) {
+    return {
+      action: "escalate",
+      reason: "no-fresh-session",
+      mail: args.mail
+    };
+  }
+  return {
+    action: "resume",
+    session: args.session,
+    prompt: composeBridgeWakePrompt(args.mail),
+    mail: args.mail
+  };
+}
 function composeBridgeWakePrompt(args) {
   const subject = args.subject ?? "(no subject)";
   const from = args.from ?? "unknown";
@@ -9039,6 +9166,7 @@ function parse(raw) {
   operatorPrefsStoragePath,
   parseEmail,
   parseGoogleVoiceSms,
+  planBridgeWake,
   recordToolCall,
   redactObject,
   redactSecret,

package/dist/index.d.cts

@@ -358,6 +358,24 @@ interface Agent {
      *  including them never wastes a Claude turn. Defaults to true
      *  (preserves the 0.9.0 wake-list-respecting behaviour). */
     wakeOnCc?: boolean;
+    /** Soft-stop flag. When true, the dispatcher refuses to wake
+     *  this agent for ANY reason (allowlist, To/Cc, task events).
+     *  Mail still lands in the mailbox so the audit trail of the
+     *  thread is preserved — only Claude/Codex turns are blocked.
+     *  This is the non-destructive counterpart to delete_agent for
+     *  stopping a churning agent mid-task without losing context. */
+    stopped?: boolean;
+    /** ISO timestamp of when `stopped` was set to true. NULL when
+     *  the agent has never been stopped (or has since been resumed
+     *  — `resume_agent` clears both `stopped` and the audit fields
+     *  is a policy decision; the current implementation clears
+     *  `stopped` only and leaves the timestamp / reason in place so
+     *  operators can see the most-recent stop history). */
+    stoppedAt?: string | null;
+    /** Optional free-form reason supplied by the caller when the
+     *  agent was stopped (e.g. "task superseded by new requirements"
+     *  or "stop all sub-agents — user request 2025-12-09"). */
+    stoppedReason?: string | null;
 }
 interface CreateAgentOptions {
     name: string;
@@ -2053,6 +2071,29 @@ interface BridgeWakePromptArgs {
     from?: string;
     preview?: string;
 }
+interface BridgeMailContext extends BridgeWakePromptArgs {
+}
+type BridgeWakeRoute = {
+    action: 'skip-live';
+    reason: 'operator-live';
+    ageMs: number;
+    mail: BridgeMailContext;
+} | {
+    action: 'escalate';
+    reason: 'no-fresh-session';
+    mail: BridgeMailContext;
+} | {
+    action: 'resume';
+    session: HostSession;
+    prompt: string;
+    mail: BridgeMailContext;
+};
+interface PlanBridgeWakeArgs {
+    session: HostSession | null;
+    mail: BridgeMailContext;
+    nowMs?: number;
+    liveWindowMs?: number;
+}
 interface ResumeErrorClassificationOptions {
     expiredMarkers?: readonly string[];
     sdkMissingMarkers?: readonly string[];
@@ -2062,6 +2103,7 @@ declare function bridgeWakeErrorMessage(err: unknown): string;
 declare function classifyResumeError(err: unknown, options?: ResumeErrorClassificationOptions): BridgeWakeError;
 declare function bridgeWakeLastSeenAgeMs(session: Pick<HostSession, 'lastSeenMs'> | null | undefined, nowMs?: number): number | null;
 declare function shouldSkipBridgeWakeForLiveOperator(session: Pick<HostSession, 'lastSeenMs'> | null | undefined, nowMs?: number, liveWindowMs?: number): boolean;
+declare function planBridgeWake(args: PlanBridgeWakeArgs): BridgeWakeRoute;
 /**
  * Build the prompt a host session sees on bridge wake. Host adapters
  * keep their own SDK resume call, but share this operator-facing
@@ -2677,4 +2719,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, BRIDGE_OPERATOR_LIVE_WINDOW_MS, type BridgeWakeError, type BridgeWakePromptArgs, type BridgeWakeResult, 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 HostSessionResumeMode, type InboundEmail, type InboundSmsEvent, 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, type ResumeErrorClassificationOptions, SPAM_THRESHOLD, type SafeJoinOptions, type SanitizeDetection, type SanitizeResult, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, type SendSmsInput, type SendSmsResult, ServiceManager, type ServiceStatus, type SetupConfig, SetupManager, type SetupResult, type Severity, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SmsProvider, 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, bridgeWakeErrorMessage, bridgeWakeLastSeenAgeMs, buildApiUrl, buildInboundSecurityAdvisory, classifyEmailRoute, classifyResumeError, closeDatabase, composeBridgeWakePrompt, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, forgetHostSession, getDatabase, getOperatorEmail, getSmsProvider, hostSessionStoragePath, isInternalEmail, isSessionFresh, isValidPhoneNumber, loadHostSession, mapProviderSmsStatus, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, parseEmail, parseGoogleVoiceSms, recordToolCall, redactObject, redactSecret, redactSmsConfig, resolveConfig, safeJoin, sanitizeEmail, saveConfig, saveHostSession, scanOutboundEmail, scoreEmail, setOperatorEmail, setTelemetryVersion, shouldSkipBridgeWakeForLiveOperator, 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, BRIDGE_OPERATOR_LIVE_WINDOW_MS, type BridgeMailContext, type BridgeWakeError, type BridgeWakePromptArgs, type BridgeWakeResult, type BridgeWakeRoute, 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 HostSessionResumeMode, type InboundEmail, type InboundSmsEvent, 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 PlanBridgeWakeArgs, type PurchasedDomain, REDACTED, RELAY_PRESETS, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, type ResumeErrorClassificationOptions, SPAM_THRESHOLD, type SafeJoinOptions, type SanitizeDetection, type SanitizeResult, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, type SendSmsInput, type SendSmsResult, ServiceManager, type ServiceStatus, type SetupConfig, SetupManager, type SetupResult, type Severity, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SmsProvider, 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, bridgeWakeErrorMessage, bridgeWakeLastSeenAgeMs, buildApiUrl, buildInboundSecurityAdvisory, classifyEmailRoute, classifyResumeError, closeDatabase, composeBridgeWakePrompt, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, forgetHostSession, getDatabase, getOperatorEmail, getSmsProvider, hostSessionStoragePath, isInternalEmail, isSessionFresh, isValidPhoneNumber, loadHostSession, mapProviderSmsStatus, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, parseEmail, parseGoogleVoiceSms, planBridgeWake, recordToolCall, redactObject, redactSecret, redactSmsConfig, resolveConfig, safeJoin, sanitizeEmail, saveConfig, saveHostSession, scanOutboundEmail, scoreEmail, setOperatorEmail, setTelemetryVersion, shouldSkipBridgeWakeForLiveOperator, startRelayBridge, threadIdFor, tryJoin, validateApiUrl };

package/dist/index.d.ts

@@ -358,6 +358,24 @@ interface Agent {
      *  including them never wastes a Claude turn. Defaults to true
      *  (preserves the 0.9.0 wake-list-respecting behaviour). */
     wakeOnCc?: boolean;
+    /** Soft-stop flag. When true, the dispatcher refuses to wake
+     *  this agent for ANY reason (allowlist, To/Cc, task events).
+     *  Mail still lands in the mailbox so the audit trail of the
+     *  thread is preserved — only Claude/Codex turns are blocked.
+     *  This is the non-destructive counterpart to delete_agent for
+     *  stopping a churning agent mid-task without losing context. */
+    stopped?: boolean;
+    /** ISO timestamp of when `stopped` was set to true. NULL when
+     *  the agent has never been stopped (or has since been resumed
+     *  — `resume_agent` clears both `stopped` and the audit fields
+     *  is a policy decision; the current implementation clears
+     *  `stopped` only and leaves the timestamp / reason in place so
+     *  operators can see the most-recent stop history). */
+    stoppedAt?: string | null;
+    /** Optional free-form reason supplied by the caller when the
+     *  agent was stopped (e.g. "task superseded by new requirements"
+     *  or "stop all sub-agents — user request 2025-12-09"). */
+    stoppedReason?: string | null;
 }
 interface CreateAgentOptions {
     name: string;
@@ -2053,6 +2071,29 @@ interface BridgeWakePromptArgs {
     from?: string;
     preview?: string;
 }
+interface BridgeMailContext extends BridgeWakePromptArgs {
+}
+type BridgeWakeRoute = {
+    action: 'skip-live';
+    reason: 'operator-live';
+    ageMs: number;
+    mail: BridgeMailContext;
+} | {
+    action: 'escalate';
+    reason: 'no-fresh-session';
+    mail: BridgeMailContext;
+} | {
+    action: 'resume';
+    session: HostSession;
+    prompt: string;
+    mail: BridgeMailContext;
+};
+interface PlanBridgeWakeArgs {
+    session: HostSession | null;
+    mail: BridgeMailContext;
+    nowMs?: number;
+    liveWindowMs?: number;
+}
 interface ResumeErrorClassificationOptions {
     expiredMarkers?: readonly string[];
     sdkMissingMarkers?: readonly string[];
@@ -2062,6 +2103,7 @@ declare function bridgeWakeErrorMessage(err: unknown): string;
 declare function classifyResumeError(err: unknown, options?: ResumeErrorClassificationOptions): BridgeWakeError;
 declare function bridgeWakeLastSeenAgeMs(session: Pick<HostSession, 'lastSeenMs'> | null | undefined, nowMs?: number): number | null;
 declare function shouldSkipBridgeWakeForLiveOperator(session: Pick<HostSession, 'lastSeenMs'> | null | undefined, nowMs?: number, liveWindowMs?: number): boolean;
+declare function planBridgeWake(args: PlanBridgeWakeArgs): BridgeWakeRoute;
 /**
  * Build the prompt a host session sees on bridge wake. Host adapters
  * keep their own SDK resume call, but share this operator-facing
@@ -2677,4 +2719,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, BRIDGE_OPERATOR_LIVE_WINDOW_MS, type BridgeWakeError, type BridgeWakePromptArgs, type BridgeWakeResult, 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 HostSessionResumeMode, type InboundEmail, type InboundSmsEvent, 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, type ResumeErrorClassificationOptions, SPAM_THRESHOLD, type SafeJoinOptions, type SanitizeDetection, type SanitizeResult, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, type SendSmsInput, type SendSmsResult, ServiceManager, type ServiceStatus, type SetupConfig, SetupManager, type SetupResult, type Severity, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SmsProvider, 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, bridgeWakeErrorMessage, bridgeWakeLastSeenAgeMs, buildApiUrl, buildInboundSecurityAdvisory, classifyEmailRoute, classifyResumeError, closeDatabase, composeBridgeWakePrompt, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, forgetHostSession, getDatabase, getOperatorEmail, getSmsProvider, hostSessionStoragePath, isInternalEmail, isSessionFresh, isValidPhoneNumber, loadHostSession, mapProviderSmsStatus, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, parseEmail, parseGoogleVoiceSms, recordToolCall, redactObject, redactSecret, redactSmsConfig, resolveConfig, safeJoin, sanitizeEmail, saveConfig, saveHostSession, scanOutboundEmail, scoreEmail, setOperatorEmail, setTelemetryVersion, shouldSkipBridgeWakeForLiveOperator, 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, BRIDGE_OPERATOR_LIVE_WINDOW_MS, type BridgeMailContext, type BridgeWakeError, type BridgeWakePromptArgs, type BridgeWakeResult, type BridgeWakeRoute, 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 HostSessionResumeMode, type InboundEmail, type InboundSmsEvent, 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 PlanBridgeWakeArgs, type PurchasedDomain, REDACTED, RELAY_PRESETS, RelayBridge, type RelayBridgeOptions, type RelayConfig, RelayGateway, type RelayProvider, type RelaySearchResult, type ResumeErrorClassificationOptions, SPAM_THRESHOLD, type SafeJoinOptions, type SanitizeDetection, type SanitizeResult, type SearchCriteria, type SearchableEmail, type SecurityAdvisory, type SendMailOptions, type SendResult, type SendResultWithRaw, type SendSmsInput, type SendSmsResult, ServiceManager, type ServiceStatus, type SetupConfig, SetupManager, type SetupResult, type Severity, type SmsConfig, SmsManager, type SmsMessage, SmsPoller, type SmsProvider, 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, bridgeWakeErrorMessage, bridgeWakeLastSeenAgeMs, buildApiUrl, buildInboundSecurityAdvisory, classifyEmailRoute, classifyResumeError, closeDatabase, composeBridgeWakePrompt, createTestDatabase, debug, debugWarn, ensureDataDir, extractVerificationCode, flushTelemetry, forgetHostSession, getDatabase, getOperatorEmail, getSmsProvider, hostSessionStoragePath, isInternalEmail, isSessionFresh, isValidPhoneNumber, loadHostSession, mapProviderSmsStatus, normalizeAddress, normalizePhoneNumber, normalizeSubject, operatorPrefsStoragePath, parseEmail, parseGoogleVoiceSms, planBridgeWake, recordToolCall, redactObject, redactSecret, redactSmsConfig, resolveConfig, safeJoin, sanitizeEmail, saveConfig, saveHostSession, scanOutboundEmail, scoreEmail, setOperatorEmail, setTelemetryVersion, shouldSkipBridgeWakeForLiveOperator, startRelayBridge, threadIdFor, tryJoin, validateApiUrl };

package/dist/index.js

@@ -1292,7 +1292,13 @@ function rowToAgent(row) {
     // Old rows (pre-migration-016) have undefined `wake_on_cc`;
     // treat that as the default-true (respect sender's wake list
     // as-is). Only explicit 0 disables CC wakes for this agent.
-    wakeOnCc: row.wake_on_cc !== void 0 ? row.wake_on_cc !== 0 : true
+    wakeOnCc: row.wake_on_cc !== void 0 ? row.wake_on_cc !== 0 : true,
+    // Pre-migration-017 rows have undefined `stopped`; treat as
+    // not-stopped. The dispatcher only blocks wakes when this is
+    // explicitly truthy, so the default mirrors back-compat.
+    stopped: row.stopped !== void 0 ? row.stopped !== 0 : false,
+    stoppedAt: row.stopped_at ?? null,
+    stoppedReason: row.stopped_reason ?? null
   };
 }
 var AccountManager = class {
@@ -2906,6 +2912,22 @@ ALTER TABLE drafts ADD COLUMN attachments TEXT;
 -- explicitly named" preference from the wake-thrash feedback.
 -- Defaults to 1 (respect the senders wake list as-is).
 ALTER TABLE agents ADD COLUMN wake_on_cc INTEGER NOT NULL DEFAULT 1;
+`,
+  "017_agent_stopped.sql": `
+-- Soft-stop for an agent mid-task. When 1, the dispatcher refuses
+-- to wake this agent for ANY reason \u2014 allowlists, To/Cc, task
+-- notifications, all of it. Mail still gets delivered to the
+-- mailbox so the audit trail of the thread stays intact. This
+-- is the non-destructive counterpart to delete_agent: stops an
+-- agent that's currently churning without losing its inbox or
+-- the thread history.
+--
+-- Companion columns capture WHEN it was stopped and the OPTIONAL
+-- reason the caller passed (e.g. "task superseded", "budget
+-- exhausted") so an operator can audit later.
+ALTER TABLE agents ADD COLUMN stopped INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE agents ADD COLUMN stopped_at TEXT;
+ALTER TABLE agents ADD COLUMN stopped_reason TEXT;
 `
 };
 function runMigrations(database) {
@@ -3179,9 +3201,67 @@ function formatPollError(err) {
   const stdout = (e.stdout ?? "").toString().trim();
   if (stdout && !stderr) parts.push(`stdout=${truncate(stdout, 240)}`);
   if (parts.length === 1 && /^command failed$/i.test(head)) {
-    return `${head} (no further detail available \u2014 wrapping error did not carry stderr/code/response)`;
+    return redactCredentialTokens(`${head} (no further detail available \u2014 wrapping error did not carry stderr/code/response)`);
+  }
+  return redactCredentialTokens(parts.join(" | "));
+}
+function redactCredentialTokens(text) {
+  return text.replace(/\b(AUTH(?:ENTICATE)?)\s+(PLAIN|LOGIN|XOAUTH2|CRAM-MD5|EXTERNAL)\s+\S+/gi, "$1 $2 [redacted]").replace(/\b(AUTH(?:ENTICATE)?)\s+([A-Za-z0-9+/]{16,}={0,2})\b/gi, "$1 [redacted]");
+}
+function isRelayCredentialError(err) {
+  if (!err) return false;
+  const haystack = typeof err === "object" ? (() => {
+    const e = err;
+    return [
+      e.message,
+      e.code,
+      e.responseCode,
+      e.response,
+      e.responseText,
+      e.command,
+      e.serverResponse
+    ].filter(Boolean).join(" ").toLowerCase();
+  })() : String(err).toLowerCase();
+  return [
+    "eauth",
+    "authenticationfailed",
+    "authentication failed",
+    "authenticate failed",
+    "invalid credentials",
+    "invalid login",
+    "login failed",
+    "username and password not accepted",
+    "application-specific password",
+    "app password",
+    "badcredentials",
+    "invalid_grant",
+    "invalid_token",
+    "expired token",
+    "token expired",
+    "access token has expired",
+    "token has expired",
+    "token is expired",
+    "token is invalid",
+    "token revoked",
+    "xoauth2",
+    "aadsts",
+    "535",
+    "534",
+    "5.7.8"
+  ].some((marker) => haystack.includes(marker));
+}
+function formatRelayError(err, config, phase) {
+  const detail = formatPollError(err);
+  if (!isRelayCredentialError(err)) {
+    return `Relay ${phase} failed: ${detail}`;
   }
-  return parts.join(" | ");
+  const provider = config.provider === "gmail" ? "Gmail" : config.provider === "outlook" ? "Outlook/Microsoft 365" : "custom";
+  const action = config.provider === "gmail" ? "Create a fresh Gmail app password or reconnect the relay, then run agenticmail setup-relay again." : config.provider === "outlook" ? "Refresh/recreate the Microsoft relay credential or OAuth token, then run agenticmail setup-relay again." : "Refresh the relay credential, then run agenticmail setup-relay again.";
+  return [
+    `Relay ${phase} failed: ${provider} relay authentication for ${config.email} is invalid, expired, or revoked.`,
+    action,
+    `Original error: ${detail}`
+  ].join(" ");
 }
 function truncate(s, max) {
   if (s.length <= max) return s;
@@ -3236,7 +3316,11 @@ var RelayGateway = class {
         pass: config.password
       }
     });
-    await this.smtpTransport.verify();
+    try {
+      await this.smtpTransport.verify();
+    } catch (err) {
+      throw new Error(formatRelayError(err, config, "SMTP verification"));
+    }
     const imap = new ImapFlow3({
       host: config.imapHost,
       port: config.imapPort,
@@ -3247,8 +3331,16 @@ var RelayGateway = class {
       },
       logger: false
     });
-    await imap.connect();
-    await imap.logout();
+    try {
+      await imap.connect();
+    } catch (err) {
+      throw new Error(formatRelayError(err, config, "IMAP verification"));
+    } finally {
+      try {
+        await imap.logout();
+      } catch {
+      }
+    }
   }
   /**
    * Send an email through the relay SMTP server.
@@ -3258,9 +3350,10 @@ var RelayGateway = class {
     if (!this.config || !this.smtpTransport) {
       throw new Error("Relay not configured. Call setup() first.");
     }
-    const atIdx = this.config.email.lastIndexOf("@");
-    const localPart2 = this.config.email.slice(0, atIdx);
-    const domain = this.config.email.slice(atIdx + 1);
+    const relayConfig = this.config;
+    const atIdx = relayConfig.email.lastIndexOf("@");
+    const localPart2 = relayConfig.email.slice(0, atIdx);
+    const domain = relayConfig.email.slice(atIdx + 1);
     const relayFrom = `${localPart2}+${agentName}@${domain}`;
     const displayName = mail.fromName || agentName;
     const mailOpts = {
@@ -3284,7 +3377,12 @@ var RelayGateway = class {
     };
     const composer = new MailComposer2(mailOpts);
     const raw = await composer.compile().build();
-    const result = await this.smtpTransport.sendMail(mailOpts);
+    let result;
+    try {
+      result = await this.smtpTransport.sendMail(mailOpts);
+    } catch (err) {
+      throw new Error(formatRelayError(err, relayConfig, "SMTP send"));
+    }
     if (result.messageId) {
       this.sentMessageIds.set(result.messageId, agentName);
       if (this.sentMessageIds.size > 1e4) {
@@ -3361,7 +3459,7 @@ var RelayGateway = class {
       this.consecutiveFailures = 0;
     } catch (err) {
       this.consecutiveFailures++;
-      const msg = formatPollError(err);
+      const msg = this.config ? formatRelayError(err, this.config, "IMAP poll") : formatPollError(err);
       console.error(`[RelayGateway] Poll failed (attempt ${this.consecutiveFailures}): ${msg}`);
       if (this.consecutiveFailures >= 5 && this.consecutiveFailures % 5 === 0) {
         console.error(`[RelayGateway] ${this.consecutiveFailures} consecutive failures \u2014 check IMAP credentials and connectivity (${this.config?.imapHost}:${this.config?.imapPort})`);
@@ -3594,13 +3692,14 @@ var RelayGateway = class {
    */
   async searchRelay(criteria, maxResults = 50) {
     if (!this.config) throw new Error("Relay not configured");
+    const relayConfig = this.config;
     const imap = new ImapFlow3({
-      host: this.config.imapHost,
-      port: this.config.imapPort,
-      secure: this.config.imapPort === 993,
+      host: relayConfig.imapHost,
+      port: relayConfig.imapPort,
+      secure: relayConfig.imapPort === 993,
       auth: {
-        user: this.config.email,
-        pass: this.config.password
+        user: relayConfig.email,
+        pass: relayConfig.password
       },
       logger: false
     });
@@ -3637,7 +3736,7 @@ var RelayGateway = class {
             results.push({
               uid,
               source: "relay",
-              account: this.config.email,
+              account: relayConfig.email,
               messageId: envelope.messageId ?? "",
               subject: envelope.subject ?? "",
               from: (envelope.from ?? []).map((a) => ({ name: a.name, address: a.address ?? "" })),
@@ -3653,7 +3752,7 @@ var RelayGateway = class {
         lock.release();
       }
     } catch (err) {
-      console.error("[RelayGateway] Relay search failed:", err instanceof Error ? err.message : err);
+      console.error("[RelayGateway] Relay search failed:", formatRelayError(err, relayConfig, "IMAP search"));
       return [];
     } finally {
       try {
@@ -3668,13 +3767,14 @@ var RelayGateway = class {
    */
   async fetchRelayMessage(uid) {
     if (!this.config) throw new Error("Relay not configured");
+    const relayConfig = this.config;
     const imap = new ImapFlow3({
-      host: this.config.imapHost,
-      port: this.config.imapPort,
-      secure: this.config.imapPort === 993,
+      host: relayConfig.imapHost,
+      port: relayConfig.imapPort,
+      secure: relayConfig.imapPort === 993,
       auth: {
-        user: this.config.email,
-        pass: this.config.password
+        user: relayConfig.email,
+        pass: relayConfig.password
       },
       logger: false
     });
@@ -3711,7 +3811,7 @@ var RelayGateway = class {
         lock.release();
       }
     } catch (err) {
-      console.error("[RelayGateway] Fetch relay message failed:", err instanceof Error ? err.message : err);
+      console.error("[RelayGateway] Fetch relay message failed:", formatRelayError(err, relayConfig, "IMAP fetch"));
       return null;
     } finally {
       try {
@@ -6484,6 +6584,32 @@ function shouldSkipBridgeWakeForLiveOperator(session, nowMs = Date.now(), liveWi
   const ageMs = bridgeWakeLastSeenAgeMs(session, nowMs);
   return ageMs !== null && ageMs < liveWindowMs;
 }
+function planBridgeWake(args) {
+  const nowMs = args.nowMs ?? Date.now();
+  const liveWindowMs = args.liveWindowMs ?? BRIDGE_OPERATOR_LIVE_WINDOW_MS;
+  const ageMs = bridgeWakeLastSeenAgeMs(args.session, nowMs);
+  if (ageMs !== null && ageMs < liveWindowMs) {
+    return {
+      action: "skip-live",
+      reason: "operator-live",
+      ageMs,
+      mail: args.mail
+    };
+  }
+  if (!args.session) {
+    return {
+      action: "escalate",
+      reason: "no-fresh-session",
+      mail: args.mail
+    };
+  }
+  return {
+    action: "resume",
+    session: args.session,
+    prompt: composeBridgeWakePrompt(args.mail),
+    mail: args.mail
+  };
+}
 function composeBridgeWakePrompt(args) {
   const subject = args.subject ?? "(no subject)";
   const from = args.from ?? "unknown";
@@ -8261,6 +8387,7 @@ export {
   operatorPrefsStoragePath,
   parseEmail,
   parseGoogleVoiceSms,
+  planBridgeWake,
   recordToolCall,
   redactObject,
   redactSecret,

package/package.json

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