@xmanrui/dsh-im 4.22.0 → 4.23.0

package/src/channels/email/mail-format.mjs

@@ -0,0 +1,91 @@
+/**
+ * Shared mail formatting and thread helpers.
+ *
+ * These are transport-independent: quote stripping, thread resolution, address
+ * normalization, and the TLS-mode derivation used by the IMAP/SMTP transport.
+ */
+
+/** Reply text longer than this is truncated so it survives mail gateways. */
+const MAX_REPLY_CHARS = 100_000;
+
+/**
+ * Quoted-history markers. Mail clients append the whole prior conversation to
+ * every reply; leaving it in place would grow the prompt each turn and confuse
+ * the model, so the body is cut at the first marker.
+ */
+const QUOTE_MARKERS = [
+  /^On .{10,120} wrote:$/mi,
+  /^-{2,}\s*Original Message\s*-{2,}$/mi,
+  /^在 .{4,60}(写道|寫道)[:：]?\s*$/mi,
+  /^-{2,}\s*原始邮件\s*-{2,}$/mi,
+  /^\s*_{10,}\s*$/m,
+  /^From:\s.+$/mi,
+  /^发件人[:：]\s*.+$/mi,
+];
+
+/** Cut a mail body at the first quoted-history marker. */
+export function stripQuotedHistory(text) {
+  const body = String(text ?? '').replace(/\r\n/g, '\n');
+  let cut = body.length;
+  for (const marker of QUOTE_MARKERS) {
+    const match = marker.exec(body);
+    if (match && match.index > 0 && match.index < cut) cut = match.index;
+  }
+  return body
+    .slice(0, cut)
+    .split('\n')
+    .filter((line) => !/^\s*>/.test(line))
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+/**
+ * Derive the transport security mode from the port, which is how mail clients
+ * decide in practice: 465 is implicit TLS, 587 and 25 negotiate STARTTLS, and
+ * anything else is left to the explicit `secure` flag. Treating 587 as
+ * implicit TLS is the classic misconfiguration that makes SMTP hang.
+ */
+export function smtpSecurity(port, secure) {
+  if (secure === true) return { secure: true };
+  if (secure === false) return { secure: false, requireTLS: true };
+  if (port === 465) return { secure: true };
+  if (port === 587 || port === 25 || port === 2525) return { secure: false, requireTLS: true };
+  return { secure: false };
+}
+
+/** IMAP uses implicit TLS on 993 and STARTTLS otherwise. */
+export function imapSecurity(port, secure) {
+  if (secure !== undefined) return { secure: secure !== false };
+  return { secure: port === 993 };
+}
+
+/** Collect every message id from a header value (References / In-Reply-To). */
+export function parseMessageIds(value) {
+  if (!value) return [];
+  const raw = Array.isArray(value) ? value.join(' ') : String(value);
+  return (raw.match(/<[^<>@\s]+@[^<>\s]+>/g) ?? []).map((id) => id.trim());
+}
+
+/**
+ * Resolve the thread key for a message: an existing conversation is reused when
+ * the reply chain points at a message we have seen before, otherwise the
+ * message starts a new conversation.
+ */
+export function resolveThreadKey({ messageId, references = [], inReplyTo = [], conversationMap }) {
+  const chain = [...parseMessageIds(references), ...parseMessageIds(inReplyTo)];
+  for (let index = chain.length - 1; index >= 0; index -= 1) {
+    const key = conversationMap.get(chain[index]);
+    if (key) return key;
+  }
+  return parseMessageIds(messageId)[0] ?? `email:${Date.now()}`;
+}
+
+/** Lowercase a bare address, keeping only the addr-spec part. */
+export function normalizeAddress(value) {
+  const text = String(value ?? '').trim().toLowerCase();
+  const angled = /<([^<>]+)>/.exec(text);
+  return (angled ? angled[1] : text).trim();
+}
+
+export { MAX_REPLY_CHARS };

package/src/channels/email/state-store.mjs

@@ -0,0 +1,176 @@
+import { ConversationStateStore } from '../shared/conversation-state-store.mjs';
+
+/**
+ * Email adds one need on top of the shared conversation store: mail threads are
+ * identified by Message-ID headers, so the inbound chain (References /
+ * In-Reply-To) must resolve back to the conversation key we already created.
+ * The map is bounded — only the most recent ids are kept, since a thread that
+ * has been quiet for thousands of messages is not worth unbounded growth.
+ */
+const MAX_THREAD_IDS = 2_000;
+
+/** A conversation key that pins the chat to one existing Harness session. */
+export const BOUND_KEY_PREFIX = 'bound:';
+
+export class EmailStateStore extends ConversationStateStore {
+  // Loaded from persisted state on first use. Held in memory because threading
+  // reads it synchronously, and written back on every change so a restart does
+  // not turn a continuing thread into a brand-new conversation.
+  #threadIds = null;
+
+  /** The Message-ID → conversation map, loaded once from persisted state. */
+  #threads() {
+    if (this.#threadIds) return this.#threadIds;
+    const stored = this.extensionState().threadIds;
+    const map = new Map();
+    if (stored && typeof stored === 'object' && !Array.isArray(stored)) {
+      for (const [id, key] of Object.entries(stored)) {
+        if (typeof id === 'string' && id && typeof key === 'string' && key) map.set(id, key);
+      }
+    }
+    this.#threadIds = map;
+    return map;
+  }
+
+  /** Record that `messageId` belongs to `conversationKey`. */
+  rememberThreadId(messageId, conversationKey) {
+    if (typeof messageId !== 'string' || !messageId || typeof conversationKey !== 'string') return;
+    const threads = this.#threads();
+    // Re-insert so the freshest ids survive eviction.
+    threads.delete(messageId);
+    threads.set(messageId, conversationKey);
+    while (threads.size > MAX_THREAD_IDS) {
+      threads.delete(threads.keys().next().value);
+    }
+    // Persisted, so a reply arriving after a restart still joins its thread.
+    this.extensionState().threadIds = Object.fromEntries(threads);
+    void this.persist();
+  }
+
+  /** Conversation key previously associated with this Message-ID, if any. */
+  conversationForThreadId(messageId) {
+    return this.#threads().get(messageId) ?? null;
+  }
+
+  /** Read-only view used by the threading resolver. */
+  get threadMap() {
+    return this.#threads();
+  }
+
+  /**
+   * A QR authorization in flight. Persisted because the code stays valid for
+   * ten minutes, which easily outlives a plugin reload — losing it meant an
+   * already-completed scan could never be redeemed.
+   */
+  pendingAuth() {
+    const value = this.extensionState().pendingAuth;
+    if (!value || typeof value !== 'object') return null;
+    if (typeof value.pollUrl !== 'string' || !value.pollUrl) return null;
+    if (!Number.isFinite(value.expiresAt)) return null;
+    return { pollUrl: value.pollUrl, expiresAt: value.expiresAt, transport: value.transport };
+  }
+
+  async setPendingAuth(value) {
+    if (!value) {
+      delete this.extensionState().pendingAuth;
+    } else {
+      this.extensionState().pendingAuth = {
+        pollUrl: String(value.pollUrl ?? ''),
+        expiresAt: Number(value.expiresAt ?? 0),
+        ...(value.transport ? { transport: String(value.transport) } : {}),
+      };
+    }
+    await this.persist();
+  }
+
+  /**
+   * Fixed-session bindings, both scopes in one document:
+   *   { account: <sessionId|null>, senders: { <address>: <sessionId> } }
+   * A sender entry wins over the account default; with neither set the
+   * conversation starts a fresh session per thread (the original behaviour).
+   */
+  emailBindings() {
+    const bindings = this.extensionState().emailBindings;
+    if (!bindings || typeof bindings !== 'object') return { account: null, senders: {} };
+    const senders = {};
+    if (bindings.senders && typeof bindings.senders === 'object' && !Array.isArray(bindings.senders)) {
+      for (const [address, sessionId] of Object.entries(bindings.senders)) {
+        if (typeof address === 'string' && address
+          && typeof sessionId === 'string' && sessionId) senders[address] = sessionId;
+      }
+    }
+    return {
+      account: typeof bindings.account === 'string' && bindings.account ? bindings.account : null,
+      senders,
+    };
+  }
+
+  async setEmailBindings(value) {
+    const next = value && typeof value === 'object' ? value : {};
+    const senders = {};
+    if (next.senders && typeof next.senders === 'object' && !Array.isArray(next.senders)) {
+      for (const [address, sessionId] of Object.entries(next.senders)) {
+        if (typeof address === 'string' && address
+          && typeof sessionId === 'string' && sessionId) senders[address] = sessionId;
+      }
+    }
+    this.extensionState().emailBindings = {
+      account: typeof next.account === 'string' && next.account ? next.account : null,
+      senders,
+    };
+    await this.persist();
+    return this.emailBindings();
+  }
+
+  /**
+   * Resolve the session a message should use, honouring the binding order:
+   * a sender-specific binding, then the account-wide binding, then null which
+   * means "start a new session for this thread".
+   */
+  boundSessionFor(senderAddress) {
+    const { account, senders } = this.emailBindings();
+    const address = typeof senderAddress === 'string' ? senderAddress.trim().toLowerCase() : '';
+    if (address && senders[address]) return senders[address];
+    return account;
+  }
+
+  /**
+   * Mail cursors are not always numbers: IMAP addresses messages by an integer
+   * UID, while the Agent mailbox pages by an opaque string id. The shared store
+   * only accepts integers, so the mailbox keeps its own cursor and returns it
+   * through the inherited accessor.
+   */
+  cursor() {
+    const value = this.extensionState().mailCursor;
+    return value === undefined ? null : value;
+  }
+
+  async setCursor(cursor) {
+    if (typeof cursor !== 'string' && !Number.isSafeInteger(cursor)) {
+      throw new TypeError('Invalid update cursor');
+    }
+    if (typeof cursor === 'string' && cursor === '') {
+      throw new TypeError('Invalid update cursor');
+    }
+    this.extensionState().mailCursor = cursor;
+    await this.persist();
+  }
+
+  /**
+   * A bound conversation key maps straight to the pinned session. Without this,
+   * the resolver would miss the mapping and create a brand-new session even
+   * though the user asked for a fixed one. The bridge prefixes the key with the
+   * chat kind (`direct:`), so the marker is searched rather than assumed to be
+   * at the start.
+   */
+  sessionFor(key) {
+    if (typeof key === 'string') {
+      const marker = key.indexOf(BOUND_KEY_PREFIX);
+      if (marker !== -1) {
+        const sessionId = key.slice(marker + BOUND_KEY_PREFIX.length);
+        if (sessionId) return sessionId;
+      }
+    }
+    return super.sessionFor(key);
+  }
+}

package/src/channels/email/transport.mjs

@@ -0,0 +1,64 @@
+/**
+ * Mailbox transport contract.
+ *
+ * A transport moves mail; it owns nothing else. Conversation mapping, the
+ * sender allowlist, quote stripping, session binding, and loop prevention all
+ * live in the runtime and are shared by every transport — so adding a mail
+ * protocol means writing one adapter here, not another channel.
+ *
+ * Implementations:
+ *   imap-smtp   any standard mailbox, polled over IMAP and sent over SMTP
+ *   agent-mail  Tencent Agent Mail (agent.qq.com), HTTP + OAuth, long-polled
+ *
+ * Required methods:
+ *   connect()                        open the underlying connection
+ *   disconnect()                     close it; must be safe to call twice
+ *   latestUid()                      highest cursor value currently present
+ *   listMessages({ afterUid, limit, allowSenders })
+ *                                    messages newer than the cursor, already
+ *                                    filtered to allowlisted senders when a
+ *                                    set is supplied
+ *   sendReply({ to, subject, text, inReplyTo, references, attachments })
+ *                                    send inside the originating conversation
+ *   sendText({ to, subject, text, attachments })
+ *                                    send a standalone message
+ *
+ * A message returned by listMessages() is a mailparser-shaped object with a
+ * `uid` added:
+ *   { uid, messageId, from, to, cc, subject, text, html, attachments, headers }
+ * `attachments[]` entries carry { filename, contentType, size, content }.
+ */
+
+/** Methods every transport must provide. */
+export const TRANSPORT_METHODS = Object.freeze([
+  'connect',
+  'disconnect',
+  'latestUid',
+  'listMessages',
+  'sendReply',
+  'sendText',
+]);
+
+/** Default reply subject: one "Re:" prefix so threads stay grouped. */
+export function replySubject(subject) {
+  const text = String(subject ?? '').trim();
+  if (!text) return 'Re: (no subject)';
+  return /^re:/i.test(text) ? text : `Re: ${text}`;
+}
+
+/**
+ * Assert that a value satisfies the transport contract. Called when a
+ * transport is constructed so a malformed adapter fails at the boundary
+ * rather than part-way through a poll.
+ */
+export function assertTransport(transport, label = 'transport') {
+  if (!transport || typeof transport !== 'object') {
+    throw new TypeError(`${label} must be an object`);
+  }
+  for (const method of TRANSPORT_METHODS) {
+    if (typeof transport[method] !== 'function') {
+      throw new TypeError(`${label} must implement ${method}()`);
+    }
+  }
+  return transport;
+}