@agenticmail/core 0.9.9 → 0.9.11

package/dist/index.cjs

@@ -713,6 +713,7 @@ __export(index_exports, {
   AgentDeletionService: () => AgentDeletionService,
   AgentMemoryStore: () => AgentMemoryStore,
   AgenticMailClient: () => AgenticMailClient,
+  BRIDGE_OPERATOR_LIVE_WINDOW_MS: () => BRIDGE_OPERATOR_LIVE_WINDOW_MS,
   CloudflareClient: () => CloudflareClient,
   DEFAULT_AGENT_NAME: () => DEFAULT_AGENT_NAME,
   DEFAULT_AGENT_ROLE: () => DEFAULT_AGENT_ROLE,
@@ -743,10 +744,14 @@ __export(index_exports, {
   UnsafeApiUrlError: () => UnsafeApiUrlError,
   WARNING_THRESHOLD: () => WARNING_THRESHOLD,
   assertWithinBase: () => assertWithinBase,
+  bridgeWakeErrorMessage: () => bridgeWakeErrorMessage,
+  bridgeWakeLastSeenAgeMs: () => bridgeWakeLastSeenAgeMs,
   buildApiUrl: () => buildApiUrl,
   buildInboundSecurityAdvisory: () => buildInboundSecurityAdvisory,
   classifyEmailRoute: () => classifyEmailRoute,
+  classifyResumeError: () => classifyResumeError,
   closeDatabase: () => closeDatabase,
+  composeBridgeWakePrompt: () => composeBridgeWakePrompt,
   createTestDatabase: () => createTestDatabase,
   debug: () => debug,
   debugWarn: () => debugWarn,
@@ -769,6 +774,7 @@ __export(index_exports, {
   operatorPrefsStoragePath: () => operatorPrefsStoragePath,
   parseEmail: () => parseEmail,
   parseGoogleVoiceSms: () => parseGoogleVoiceSms,
+  planBridgeWake: () => planBridgeWake,
   recordToolCall: () => recordToolCall,
   redactObject: () => redactObject,
   redactSecret: () => redactSecret,
@@ -782,6 +788,7 @@ __export(index_exports, {
   scoreEmail: () => scoreEmail,
   setOperatorEmail: () => setOperatorEmail,
   setTelemetryVersion: () => setTelemetryVersion,
+  shouldSkipBridgeWakeForLiveOperator: () => shouldSkipBridgeWakeForLiveOperator,
   startRelayBridge: () => startRelayBridge,
   threadIdFor: () => threadIdFor,
   tryJoin: () => tryJoin,
@@ -805,8 +812,7 @@ var MailSender = class {
         pass: options.password
       },
       tls: {
-        rejectUnauthorized: false
-        // Local dev — no TLS
+        rejectUnauthorized: options.tlsRejectUnauthorized ?? true
       },
       connectionTimeout: 1e4,
       // 10s to establish TCP connection
@@ -2074,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 {
@@ -3692,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) {
@@ -3965,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 parts.join(" | ");
+  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}`;
+  }
+  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;
@@ -4022,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,
@@ -4033,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.
@@ -4044,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 = {
@@ -4070,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) {
@@ -4147,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})`);
@@ -4380,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
     });
@@ -4423,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 ?? "" })),
@@ -4439,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 {
@@ -4454,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
     });
@@ -4497,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 {
@@ -7233,6 +7339,95 @@ function hostSessionStoragePath() {
   return storagePath();
 }
 
+// src/host-bridge.ts
+var BRIDGE_OPERATOR_LIVE_WINDOW_MS = 3e4;
+var DEFAULT_EXPIRED_MARKERS = [
+  "session not found",
+  "invalid session",
+  "session expired",
+  "no such session",
+  "unknown session",
+  "thread not found",
+  "invalid thread",
+  "thread expired",
+  "no such thread",
+  "unknown thread"
+];
+var DEFAULT_SDK_MISSING_MARKERS = [
+  "cannot find module",
+  "could not be found",
+  "command not found"
+];
+function bridgeWakeErrorMessage(err) {
+  return err?.message ?? String(err);
+}
+function classifyResumeError(err, options = {}) {
+  const msg = bridgeWakeErrorMessage(err).toLowerCase();
+  const expiredMarkers = options.expiredMarkers ?? DEFAULT_EXPIRED_MARKERS;
+  const sdkMissingMarkers = options.sdkMissingMarkers ?? DEFAULT_SDK_MISSING_MARKERS;
+  if (expiredMarkers.some((marker) => msg.includes(marker))) return "session-expired";
+  if (sdkMissingMarkers.some((marker) => msg.includes(marker))) return "sdk-missing";
+  return "other";
+}
+function bridgeWakeLastSeenAgeMs(session, nowMs = Date.now()) {
+  if (!session) return null;
+  return nowMs - session.lastSeenMs;
+}
+function shouldSkipBridgeWakeForLiveOperator(session, nowMs = Date.now(), liveWindowMs = BRIDGE_OPERATOR_LIVE_WINDOW_MS) {
+  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";
+  const preview = (args.preview ?? "").slice(0, 600);
+  return [
+    `\u{1F380} Bridge mail arrived \u2014 headless wake.`,
+    "",
+    `You are being resumed against your last session because new mail landed in your bridge inbox (${args.bridgeName}@localhost) and you weren't actively at the keyboard.`,
+    "",
+    `Trigger:`,
+    `  UID:     ${args.uid}`,
+    `  From:    ${from}`,
+    `  Subject: ${subject}`,
+    `  Preview: ${preview}`,
+    "",
+    `Read it with mcp__agenticmail__read_email({ uid: ${args.uid} }) and decide:`,
+    `  \xB7 Does it need a reply from YOU (the operator's session)? Reply via mcp__agenticmail__reply_email.`,
+    `  \xB7 Does it need a teammate to act? Forward / re-route by replying with wake: ["<teammate>"].`,
+    `  \xB7 Is it [NEEDS OPERATOR] / [BLOCKED]? Then it's actually for the human \u2014 mark it unread, and the operator will see it on their next keystroke.`,
+    `  \xB7 Is it FYI noise? mark_read and exit.`,
+    "",
+    `Keep this turn SHORT. You're being resumed to handle ONE piece of mail, not to continue the prior conversation.`
+  ].join("\n");
+}
+
 // src/util/safe-url.ts
 var UnsafeApiUrlError = class extends Error {
   constructor(raw, reason) {
@@ -8910,6 +9105,7 @@ function parse(raw) {
   AgentDeletionService,
   AgentMemoryStore,
   AgenticMailClient,
+  BRIDGE_OPERATOR_LIVE_WINDOW_MS,
   CloudflareClient,
   DEFAULT_AGENT_NAME,
   DEFAULT_AGENT_ROLE,
@@ -8940,10 +9136,14 @@ function parse(raw) {
   UnsafeApiUrlError,
   WARNING_THRESHOLD,
   assertWithinBase,
+  bridgeWakeErrorMessage,
+  bridgeWakeLastSeenAgeMs,
   buildApiUrl,
   buildInboundSecurityAdvisory,
   classifyEmailRoute,
+  classifyResumeError,
   closeDatabase,
+  composeBridgeWakePrompt,
   createTestDatabase,
   debug,
   debugWarn,
@@ -8966,6 +9166,7 @@ function parse(raw) {
   operatorPrefsStoragePath,
   parseEmail,
   parseGoogleVoiceSms,
+  planBridgeWake,
   recordToolCall,
   redactObject,
   redactSecret,
@@ -8979,6 +9180,7 @@ function parse(raw) {
   scoreEmail,
   setOperatorEmail,
   setTelemetryVersion,
+  shouldSkipBridgeWakeForLiveOperator,
   startRelayBridge,
   threadIdFor,
   tryJoin,

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;
@@ -481,6 +499,7 @@ interface MailSenderOptions {
     password: string;
     authUser?: string;
     secure?: boolean;
+    tlsRejectUnauthorized?: boolean;
 }
 interface SendResultWithRaw extends SendResult {
     /** Raw RFC822 message bytes (for appending to Sent folder) */
@@ -1899,8 +1918,8 @@ declare function operatorPrefsStoragePath(): string;
  *
  * # What this is for
  *
- * When a sub-agent replies into the host bridge inbox
- * (`claudecode@localhost` / `codex@localhost`), the dispatcher
+ * When a sub-agent replies into a host bridge inbox
+ * (`claudecode@localhost` / `codex@localhost` / etc.), 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
@@ -1933,6 +1952,12 @@ declare function operatorPrefsStoragePath(): string;
  *       "sessionId": "019a2b3c-…",
  *       "workspace": "/Users/ope/Desktop/facebook-project",
  *       "lastSeenMs": 1778905100000
+ *     },
+ *     "openclaw": {
+ *       "sessionId": "openclaw-session-key",
+ *       "workspace": "/Users/ope/Desktop/facebook-project",
+ *       "lastSeenMs": 1778905000000,
+ *       "resumeMode": "wake"
  *     }
  *   }
  * }
@@ -1963,14 +1988,24 @@ declare function operatorPrefsStoragePath(): string;
  * 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';
+type HostName = 'claudecode' | 'codex' | 'openclaw' | 'gemini' | 'hermes';
+/**
+ * How a host can be woken from a persisted session record.
+ *
+ * - `resume`: the host can resume a durable prior conversation/thread.
+ * - `wake`: the host can target a live or recently known session key, but does
+ *   not guarantee full headless resume semantics.
+ * - `wake-only`: the host can receive a wake notification, but the dispatcher
+ *   must not treat it as a resumed worker turn.
+ */
+type HostSessionResumeMode = 'resume' | 'wake' | 'wake-only';
 /**
  * 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). */
+    /** Stable session_id/thread_id/session key from the host CLI/runtime. */
     sessionId: string;
     /** Wall-clock timestamp of the last hook fire on this session. */
     lastSeenMs: number;
@@ -1980,6 +2015,10 @@ interface HostSession {
     /** Optional: model name the host session was using, surfaced
      *  in logs for diagnostic context. */
     model?: string;
+    /** Optional: describes whether this host supports true resume or only wake. */
+    resumeMode?: HostSessionResumeMode;
+    /** Optional host-specific metadata. Must not contain secrets. */
+    hostMetadata?: Record<string, unknown>;
 }
 /** Default freshness window — sessions older than this are skipped. */
 declare const DEFAULT_SESSION_MAX_AGE_MS: number;
@@ -2017,6 +2056,62 @@ declare function forgetHostSession(host: HostName): void;
 /** Exposed for tests + the `agenticmail status` diagnostic command. */
 declare function hostSessionStoragePath(): string;
 
+type BridgeWakeError = 'session-expired' | 'sdk-missing' | 'timeout' | 'other';
+interface BridgeWakeResult {
+    ok: boolean;
+    text?: string;
+    error?: BridgeWakeError;
+    errorMessage?: string;
+    durationMs?: number;
+}
+interface BridgeWakePromptArgs {
+    bridgeName: string;
+    uid: number;
+    subject?: string;
+    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[];
+}
+declare const BRIDGE_OPERATOR_LIVE_WINDOW_MS = 30000;
+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
+ * instruction shape so Claude Code, Codex, OpenClaw and later hosts
+ * do not drift semantically.
+ */
+declare function composeBridgeWakePrompt(args: BridgeWakePromptArgs): string;
+
 /**
  * SSRF-safe URL validation for the AgenticMail API base URL.
  *
@@ -2624,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, 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 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, 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, buildApiUrl, buildInboundSecurityAdvisory, classifyEmailRoute, closeDatabase, 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, 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;
@@ -481,6 +499,7 @@ interface MailSenderOptions {
     password: string;
     authUser?: string;
     secure?: boolean;
+    tlsRejectUnauthorized?: boolean;
 }
 interface SendResultWithRaw extends SendResult {
     /** Raw RFC822 message bytes (for appending to Sent folder) */
@@ -1899,8 +1918,8 @@ declare function operatorPrefsStoragePath(): string;
  *
  * # What this is for
  *
- * When a sub-agent replies into the host bridge inbox
- * (`claudecode@localhost` / `codex@localhost`), the dispatcher
+ * When a sub-agent replies into a host bridge inbox
+ * (`claudecode@localhost` / `codex@localhost` / etc.), 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
@@ -1933,6 +1952,12 @@ declare function operatorPrefsStoragePath(): string;
  *       "sessionId": "019a2b3c-…",
  *       "workspace": "/Users/ope/Desktop/facebook-project",
  *       "lastSeenMs": 1778905100000
+ *     },
+ *     "openclaw": {
+ *       "sessionId": "openclaw-session-key",
+ *       "workspace": "/Users/ope/Desktop/facebook-project",
+ *       "lastSeenMs": 1778905000000,
+ *       "resumeMode": "wake"
  *     }
  *   }
  * }
@@ -1963,14 +1988,24 @@ declare function operatorPrefsStoragePath(): string;
  * 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';
+type HostName = 'claudecode' | 'codex' | 'openclaw' | 'gemini' | 'hermes';
+/**
+ * How a host can be woken from a persisted session record.
+ *
+ * - `resume`: the host can resume a durable prior conversation/thread.
+ * - `wake`: the host can target a live or recently known session key, but does
+ *   not guarantee full headless resume semantics.
+ * - `wake-only`: the host can receive a wake notification, but the dispatcher
+ *   must not treat it as a resumed worker turn.
+ */
+type HostSessionResumeMode = 'resume' | 'wake' | 'wake-only';
 /**
  * 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). */
+    /** Stable session_id/thread_id/session key from the host CLI/runtime. */
     sessionId: string;
     /** Wall-clock timestamp of the last hook fire on this session. */
     lastSeenMs: number;
@@ -1980,6 +2015,10 @@ interface HostSession {
     /** Optional: model name the host session was using, surfaced
      *  in logs for diagnostic context. */
     model?: string;
+    /** Optional: describes whether this host supports true resume or only wake. */
+    resumeMode?: HostSessionResumeMode;
+    /** Optional host-specific metadata. Must not contain secrets. */
+    hostMetadata?: Record<string, unknown>;
 }
 /** Default freshness window — sessions older than this are skipped. */
 declare const DEFAULT_SESSION_MAX_AGE_MS: number;
@@ -2017,6 +2056,62 @@ declare function forgetHostSession(host: HostName): void;
 /** Exposed for tests + the `agenticmail status` diagnostic command. */
 declare function hostSessionStoragePath(): string;
 
+type BridgeWakeError = 'session-expired' | 'sdk-missing' | 'timeout' | 'other';
+interface BridgeWakeResult {
+    ok: boolean;
+    text?: string;
+    error?: BridgeWakeError;
+    errorMessage?: string;
+    durationMs?: number;
+}
+interface BridgeWakePromptArgs {
+    bridgeName: string;
+    uid: number;
+    subject?: string;
+    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[];
+}
+declare const BRIDGE_OPERATOR_LIVE_WINDOW_MS = 30000;
+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
+ * instruction shape so Claude Code, Codex, OpenClaw and later hosts
+ * do not drift semantically.
+ */
+declare function composeBridgeWakePrompt(args: BridgeWakePromptArgs): string;
+
 /**
  * SSRF-safe URL validation for the AgenticMail API base URL.
  *
@@ -2624,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, 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 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, 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, buildApiUrl, buildInboundSecurityAdvisory, classifyEmailRoute, closeDatabase, 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, 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

@@ -24,8 +24,7 @@ var MailSender = class {
         pass: options.password
       },
       tls: {
-        rejectUnauthorized: false
-        // Local dev — no TLS
+        rejectUnauthorized: options.tlsRejectUnauthorized ?? true
       },
       connectionTimeout: 1e4,
       // 10s to establish TCP connection
@@ -1293,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 {
@@ -2907,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) {
@@ -3180,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 parts.join(" | ");
+  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}`;
+  }
+  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;
@@ -3237,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,
@@ -3248,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.
@@ -3259,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 = {
@@ -3285,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) {
@@ -3362,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})`);
@@ -3595,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
     });
@@ -3638,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 ?? "" })),
@@ -3654,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 {
@@ -3669,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
     });
@@ -3712,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 {
@@ -6447,6 +6546,95 @@ function hostSessionStoragePath() {
   return storagePath();
 }
 
+// src/host-bridge.ts
+var BRIDGE_OPERATOR_LIVE_WINDOW_MS = 3e4;
+var DEFAULT_EXPIRED_MARKERS = [
+  "session not found",
+  "invalid session",
+  "session expired",
+  "no such session",
+  "unknown session",
+  "thread not found",
+  "invalid thread",
+  "thread expired",
+  "no such thread",
+  "unknown thread"
+];
+var DEFAULT_SDK_MISSING_MARKERS = [
+  "cannot find module",
+  "could not be found",
+  "command not found"
+];
+function bridgeWakeErrorMessage(err) {
+  return err?.message ?? String(err);
+}
+function classifyResumeError(err, options = {}) {
+  const msg = bridgeWakeErrorMessage(err).toLowerCase();
+  const expiredMarkers = options.expiredMarkers ?? DEFAULT_EXPIRED_MARKERS;
+  const sdkMissingMarkers = options.sdkMissingMarkers ?? DEFAULT_SDK_MISSING_MARKERS;
+  if (expiredMarkers.some((marker) => msg.includes(marker))) return "session-expired";
+  if (sdkMissingMarkers.some((marker) => msg.includes(marker))) return "sdk-missing";
+  return "other";
+}
+function bridgeWakeLastSeenAgeMs(session, nowMs = Date.now()) {
+  if (!session) return null;
+  return nowMs - session.lastSeenMs;
+}
+function shouldSkipBridgeWakeForLiveOperator(session, nowMs = Date.now(), liveWindowMs = BRIDGE_OPERATOR_LIVE_WINDOW_MS) {
+  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";
+  const preview = (args.preview ?? "").slice(0, 600);
+  return [
+    `\u{1F380} Bridge mail arrived \u2014 headless wake.`,
+    "",
+    `You are being resumed against your last session because new mail landed in your bridge inbox (${args.bridgeName}@localhost) and you weren't actively at the keyboard.`,
+    "",
+    `Trigger:`,
+    `  UID:     ${args.uid}`,
+    `  From:    ${from}`,
+    `  Subject: ${subject}`,
+    `  Preview: ${preview}`,
+    "",
+    `Read it with mcp__agenticmail__read_email({ uid: ${args.uid} }) and decide:`,
+    `  \xB7 Does it need a reply from YOU (the operator's session)? Reply via mcp__agenticmail__reply_email.`,
+    `  \xB7 Does it need a teammate to act? Forward / re-route by replying with wake: ["<teammate>"].`,
+    `  \xB7 Is it [NEEDS OPERATOR] / [BLOCKED]? Then it's actually for the human \u2014 mark it unread, and the operator will see it on their next keystroke.`,
+    `  \xB7 Is it FYI noise? mark_read and exit.`,
+    "",
+    `Keep this turn SHORT. You're being resumed to handle ONE piece of mail, not to continue the prior conversation.`
+  ].join("\n");
+}
+
 // src/util/safe-url.ts
 var UnsafeApiUrlError = class extends Error {
   constructor(raw, reason) {
@@ -8138,6 +8326,7 @@ export {
   AgentDeletionService,
   AgentMemoryStore,
   AgenticMailClient,
+  BRIDGE_OPERATOR_LIVE_WINDOW_MS,
   CloudflareClient,
   DEFAULT_AGENT_NAME,
   DEFAULT_AGENT_ROLE,
@@ -8168,10 +8357,14 @@ export {
   UnsafeApiUrlError,
   WARNING_THRESHOLD,
   assertWithinBase,
+  bridgeWakeErrorMessage,
+  bridgeWakeLastSeenAgeMs,
   buildApiUrl,
   buildInboundSecurityAdvisory,
   classifyEmailRoute,
+  classifyResumeError,
   closeDatabase,
+  composeBridgeWakePrompt,
   createTestDatabase,
   debug,
   debugWarn,
@@ -8194,6 +8387,7 @@ export {
   operatorPrefsStoragePath,
   parseEmail,
   parseGoogleVoiceSms,
+  planBridgeWake,
   recordToolCall,
   redactObject,
   redactSecret,
@@ -8207,6 +8401,7 @@ export {
   scoreEmail,
   setOperatorEmail,
   setTelemetryVersion,
+  shouldSkipBridgeWakeForLiveOperator,
   startRelayBridge,
   threadIdFor,
   tryJoin,

package/package.json

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