agent-inbox 0.2.2 → 0.2.4

package/src/jsonrpc/mail-server.ts

@@ -36,11 +36,21 @@ export class MailJsonRpcServer {
   private httpServer: http.Server | null = null;
   private subscribers = new Set<http.ServerResponse>();
 
+  /**
+   * Optional presence registry for resolving agent online/offline status.
+   * When provided, `mail/presence` enriches participants with live status.
+   */
+  private registry?: {
+    getStatus(agentId: string): string;
+  };
+
   constructor(
     private storage: Storage,
     private router: MessageRouter,
-    private events: EventEmitter
+    private events: EventEmitter,
+    registry?: { getStatus(agentId: string): string }
   ) {
+    this.registry = registry;
     this.registerMethods();
     this.setupEventForwarding();
   }
@@ -95,6 +105,20 @@ export class MailJsonRpcServer {
       return { ok: true };
     });
 
+    // mail/reopen — reopen a completed conversation
+    this.methods.set("mail/reopen", (params) => {
+      const conv = this.storage.getConversation(params.id as string);
+      if (!conv) throw rpcError(-32001, "Conversation not found");
+      conv.status = "active";
+      conv.updated_at = new Date().toISOString();
+      this.storage.putConversation(conv);
+      this.events.emit("mail.reopened", {
+        conversation_id: conv.id,
+        status: conv.status,
+      });
+      return { conversationId: conv.id, status: "active" };
+    });
+
     // mail/join — add self as participant
     this.methods.set("mail/join", (params) => {
       const conv = this.storage.getConversation(
@@ -162,6 +186,7 @@ export class MailJsonRpcServer {
       );
       if (!conv) throw rpcError(-32001, "Conversation not found");
 
+      const importance = params.importance as Turn["importance"] | undefined;
       const turn: Turn = {
         id: `turn-${ulid()}`,
         conversation_id: conv.id,
@@ -172,6 +197,7 @@ export class MailJsonRpcServer {
         thread_id: params.threadId as string | undefined,
         in_reply_to: params.inReplyTo as string | undefined,
         created_at: new Date().toISOString(),
+        ...(importance ? { importance } : {}),
       };
 
       this.storage.addTurn(turn);
@@ -220,6 +246,24 @@ export class MailJsonRpcServer {
         threads: this.storage.getThreadsByConversation(conv.id),
       };
     });
+
+    // mail/presence — list participants with live presence status
+    this.methods.set("mail/presence", (params) => {
+      const conversationId = params.conversationId as string;
+      if (!conversationId) throw rpcError(-32602, "conversationId required");
+
+      const conv = this.storage.getConversation(conversationId);
+      if (!conv) throw rpcError(-32001, "Conversation not found");
+
+      const participants = (conv.participants ?? []).map((p) => ({
+        agent_id: p.agent_id,
+        role: p.role,
+        joined_at: p.joined_at,
+        presence: this.registry?.getStatus(p.agent_id) ?? "unknown",
+      }));
+
+      return { conversationId, participants };
+    });
   }
 
   /** Process a JSON-RPC request (used by both IPC and HTTP transports) */
@@ -355,6 +399,9 @@ export class MailJsonRpcServer {
     this.events.on("mail.closed", (data) => {
       this.broadcast("mail.closed", data);
     });
+    this.events.on("mail.reopened", (data) => {
+      this.broadcast("mail.reopened", data);
+    });
   }
 
   private broadcast(eventType: string, data: unknown): void {

package/src/mail/address-book.ts

@@ -0,0 +1,111 @@
+/**
+ * Mail identity / address book.
+ *
+ * Maps between agent ids and external email addresses, and declares which
+ * domains we own (for inbound RCPT acceptance). Plus-addressing aware:
+ * `agent+scope@domain` resolves to agent `agent` in inbox scope `scope`.
+ *
+ * See docs/MAIL-INTEROP-PLAN.md §6.
+ */
+
+import type { MailIdentityConfig } from "../types.js";
+import type { MailAddress } from "./types.js";
+
+export interface ResolvedInbound {
+  agentId: string;
+  /** Inbox scope from plus-addressing, if present. */
+  scope?: string;
+}
+
+export class AddressBook {
+  private localDomains: string[];
+  /** lower-cased address → agentId */
+  private byAddress = new Map<string, string>();
+  /** agentId → canonical address */
+  private byAgent = new Map<string, string>();
+  private catchAllAgentId?: string;
+  /** Address mappings that collided (same address → multiple agents). */
+  readonly conflicts: string[] = [];
+
+  constructor(config: MailIdentityConfig) {
+    this.localDomains = config.localDomains.map((d) => d.toLowerCase());
+    this.catchAllAgentId = config.catchAllAgentId;
+    for (const { agentId, address } of config.mappings) {
+      const lower = address.toLowerCase();
+      const existing = this.byAddress.get(lower);
+      if (existing !== undefined && existing !== agentId) {
+        // Two agents mapped to the same address — inbound routing would be
+        // ambiguous. Keep the first and record the collision for surfacing.
+        this.conflicts.push(`${address} → ${existing} & ${agentId}`);
+        continue;
+      }
+      this.byAddress.set(lower, agentId);
+      // First mapping for an agent is its canonical from-address.
+      if (!this.byAgent.has(agentId)) this.byAgent.set(agentId, address);
+    }
+  }
+
+  /** Primary local domain — used to mint Message-IDs and default from-addresses. */
+  primaryDomain(): string {
+    return this.localDomains[0] ?? "localhost";
+  }
+
+  /** True if `domain` (or a parent of it) is one we receive mail for. */
+  ownsDomain(domain: string): boolean {
+    const d = domain.toLowerCase();
+    return this.localDomains.some(
+      (own) => d === own || d.endsWith(`.${own}`)
+    );
+  }
+
+  /**
+   * Resolve an inbound recipient email to a local agent (+ scope).
+   * Returns undefined if the domain is not ours, or the mailbox is unknown and
+   * no catch-all is configured.
+   */
+  resolveInbound(address: string): ResolvedInbound | undefined {
+    const parsed = splitAddress(address);
+    if (!parsed) return undefined;
+    const { local, domain } = parsed;
+
+    if (!this.ownsDomain(domain)) return undefined;
+
+    // Plus-addressing: agent+scope → base agent, scope.
+    const plusIdx = local.indexOf("+");
+    const base = plusIdx === -1 ? local : local.slice(0, plusIdx);
+    const scope = plusIdx === -1 ? undefined : local.slice(plusIdx + 1) || undefined;
+
+    const canonical = `${base}@${domain}`.toLowerCase();
+    const agentId = this.byAddress.get(canonical);
+    if (agentId) return { agentId, scope };
+
+    if (this.catchAllAgentId) return { agentId: this.catchAllAgentId, scope };
+    return undefined;
+  }
+
+  /**
+   * Resolve the from-address for an outbound sender agent. Falls back to
+   * `<agentId>@<primaryDomain>` when the agent has no explicit mapping.
+   */
+  resolveFrom(agentId: string): MailAddress {
+    const mapped = this.byAgent.get(agentId);
+    if (mapped) return { address: mapped };
+    return { address: `${agentId}@${this.primaryDomain()}` };
+  }
+}
+
+/** Split an addr-spec into local-part and domain. Returns undefined if malformed. */
+function splitAddress(
+  address: string
+): { local: string; domain: string } | undefined {
+  const at = address.indexOf("@");
+  if (at <= 0 || at !== address.lastIndexOf("@") || at === address.length - 1) {
+    // Reject empty local/domain and unquoted multiple "@" (e.g. "a@b@c"), so
+    // this layer agrees with parseAddress (which splits on the first "@").
+    return undefined;
+  }
+  const domain = address.slice(at + 1);
+  // A domain must not contain "/" (a federation scope separator) — defensive.
+  if (domain.includes("/")) return undefined;
+  return { local: address.slice(0, at), domain };
+}

package/src/mail/attachment-store.ts

@@ -0,0 +1,90 @@
+/**
+ * Attachment byte stores.
+ *
+ * `MailAttachment.contentRef` is opaque; bytes live behind an AttachmentStore.
+ * Default impl is SQLite-backed (atomic with the message, single-file backup,
+ * works with the in-memory DB used in tests). A filesystem impl is opt-in for
+ * large/high-volume deployments (added later). Refs are content-addressed
+ * (sha256) so identical bytes dedup. See docs/MAIL-INTEROP-PLAN.md §4c.
+ */
+
+import type Database from "better-sqlite3";
+import { createHash } from "node:crypto";
+import type { AttachmentStore } from "./types.js";
+
+export class SqliteAttachmentStore implements AttachmentStore {
+  private table: string;
+  private putStmt: Database.Statement;
+  private getStmt: Database.Statement;
+  private delStmt: Database.Statement;
+
+  /**
+   * @param db     A better-sqlite3 handle (lifecycle owned by the caller).
+   * @param prefix Table name prefix to match the Storage convention. Default "".
+   */
+  constructor(
+    private db: Database.Database,
+    prefix: string = ""
+  ) {
+    this.table = `${prefix}mail_attachments`;
+    this.migrate();
+    this.putStmt = this.db.prepare(
+      `INSERT INTO ${this.table} (ref, content_type, filename, bytes, size_bytes, created_at)
+       VALUES (@ref, @content_type, @filename, @bytes, @size_bytes, @created_at)
+       ON CONFLICT(ref) DO NOTHING`
+    );
+    this.getStmt = this.db.prepare(
+      `SELECT bytes FROM ${this.table} WHERE ref = ?`
+    );
+    this.delStmt = this.db.prepare(`DELETE FROM ${this.table} WHERE ref = ?`);
+  }
+
+  private migrate(): void {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS ${this.table} (
+        ref TEXT PRIMARY KEY,
+        content_type TEXT NOT NULL,
+        filename TEXT,
+        bytes BLOB NOT NULL,
+        size_bytes INTEGER NOT NULL,
+        created_at TEXT NOT NULL
+      );
+    `);
+  }
+
+  async put(
+    bytes: Buffer,
+    meta: { contentType: string; filename?: string }
+  ): Promise<string> {
+    const ref = "sha256:" + createHash("sha256").update(bytes).digest("hex");
+    // ON CONFLICT DO NOTHING — content-addressed, so identical bytes are deduped.
+    this.putStmt.run({
+      ref,
+      content_type: meta.contentType,
+      filename: meta.filename ?? null,
+      bytes,
+      size_bytes: bytes.length,
+      created_at: new Date().toISOString(),
+    });
+    return ref;
+  }
+
+  async get(ref: string): Promise<Buffer> {
+    assertValidRef(ref);
+    const row = this.getStmt.get(ref) as { bytes: Buffer } | undefined;
+    if (!row) throw new Error(`Attachment not found: ${ref}`);
+    return row.bytes;
+  }
+
+  async delete(ref: string): Promise<void> {
+    assertValidRef(ref);
+    this.delStmt.run(ref);
+  }
+}
+
+/** Refs are always sha256-of-content; reject anything else (parity with FS store). */
+function assertValidRef(ref: string): void {
+  if (!/^sha256:[0-9a-f]{64}$/.test(ref)) {
+    throw new Error(`Invalid attachment ref: ${ref}`);
+  }
+}

package/src/mail/email-mapper.ts

@@ -0,0 +1,288 @@
+/**
+ * Bidirectional mapping between RFC 5322 email and agent-inbox Messages.
+ *
+ * Parallels src/mesh/type-mapper.ts. Two pure functions:
+ *   - inboundMailToMessage: external email → inbox Message
+ *   - messageToOutboundMail: inbox Message → rendered OutboundMail
+ *
+ * Threading: RFC Message-ID / In-Reply-To / References map onto the inbox's
+ * thread_tag + in_reply_to. The RFC Message-ID is preserved in metadata so a
+ * later reply can reconstruct the In-Reply-To / References chain. See §5.
+ */
+
+import { ulid } from "ulid";
+import { createHash } from "node:crypto";
+import { normalizeContent } from "../router/message-router.js";
+import type { Message, Recipient, RecipientKind, Importance } from "../types.js";
+import type { AddressBook } from "./address-book.js";
+import type {
+  InboundMail,
+  OutboundMail,
+  MailAddress,
+  MailAttachment,
+} from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Contexts
+// ---------------------------------------------------------------------------
+
+export interface InboundMapContext {
+  addressBook: AddressBook;
+  /** Scope assigned when plus-addressing does not specify one. */
+  defaultScope?: string;
+  /**
+   * Resolve an RFC Message-ID we have already stored to its inbox Message id,
+   * so an inbound reply can set `in_reply_to` to the real parent.
+   */
+  lookupInboxIdByRfcMessageId?: (rfcMessageId: string) => string | undefined;
+}
+
+export interface OutboundMapContext {
+  addressBook: AddressBook;
+  /** Domain used to mint Message-IDs. Defaults to the address book primary domain. */
+  messageIdDomain?: string;
+  /** The RFC Message-ID we recorded when the parent inbox message was sent/received. */
+  lookupRfcMessageId?: (inboxId: string) => string | undefined;
+  /** The References chain recorded for the parent inbox message. */
+  lookupReferences?: (inboxId: string) => string[] | undefined;
+}
+
+/** Thrown when no inbound recipient resolves to a local agent. */
+export class UnknownRecipientError extends Error {
+  constructor(public readonly recipients: string[]) {
+    super(
+      `No inbound recipient resolved to a local agent: ${recipients.join(", ")}`
+    );
+    this.name = "UnknownRecipientError";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Inbound: email → Message
+// ---------------------------------------------------------------------------
+
+export function inboundMailToMessage(
+  mail: InboundMail,
+  ctx: InboundMapContext
+): Message {
+  const recipients: Recipient[] = [];
+  const unresolved: string[] = [];
+  let scope: string | undefined;
+
+  const addKind = (addrs: MailAddress[] | undefined, kind: RecipientKind) => {
+    for (const a of addrs ?? []) {
+      const resolved = ctx.addressBook.resolveInbound(a.address);
+      if (!resolved) {
+        unresolved.push(a.address);
+        continue;
+      }
+      recipients.push({ agent_id: resolved.agentId, kind });
+      // First resolved recipient with a plus-address scope wins. "to" is
+      // processed before "cc", so a to-scope still takes precedence, but a
+      // cc-only scoped recipient is no longer silently dropped.
+      if (scope === undefined && resolved.scope) {
+        scope = resolved.scope;
+      }
+    }
+  };
+
+  addKind(mail.to, "to");
+  addKind(mail.cc, "cc");
+
+  if (recipients.length === 0) {
+    throw new UnknownRecipientError(unresolved);
+  }
+
+  const rfcMessageId = mail.headers.messageId;
+  const rfcInReplyTo = mail.headers.inReplyTo;
+  const rfcReferences = mail.headers.references;
+
+  const metadata: Record<string, unknown> = {};
+  if (rfcMessageId) metadata.rfcMessageId = rfcMessageId;
+  if (rfcInReplyTo) metadata.rfcInReplyTo = rfcInReplyTo;
+  if (rfcReferences) metadata.rfcReferences = rfcReferences;
+  if (mail.html) metadata.htmlBody = mail.html;
+  if (mail.authResults) metadata.authResults = mail.authResults;
+  if (mail.remote) metadata.remote = mail.remote;
+  if (mail.envelopeFrom) metadata.envelopeFrom = mail.envelopeFrom;
+  if (mail.bounce) metadata.bounce = mail.bounce;
+  if (mail.attachments?.length) metadata.mailAttachments = mail.attachments;
+
+  // Resolve in_reply_to to a real inbox id when we can; otherwise leave it unset
+  // (the RFC id is retained in metadata for later correlation).
+  let inReplyTo: string | undefined;
+  if (rfcInReplyTo && ctx.lookupInboxIdByRfcMessageId) {
+    inReplyTo = ctx.lookupInboxIdByRfcMessageId(rfcInReplyTo);
+  }
+
+  const text = mail.text ?? "";
+
+  return {
+    id: ulid(),
+    scope: scope ?? ctx.defaultScope ?? "default",
+    sender_id: mail.from.address,
+    recipients,
+    subject: mail.subject,
+    content: normalizeContent(text),
+    thread_tag: deriveThreadTag(rfcReferences, rfcInReplyTo, rfcMessageId),
+    in_reply_to: inReplyTo,
+    importance: importanceFromHeaders(mail.headers.raw),
+    metadata,
+    created_at: mail.receivedAt,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Outbound: Message → email
+// ---------------------------------------------------------------------------
+
+export function messageToOutboundMail(
+  msg: Message,
+  ctx: OutboundMapContext
+): OutboundMail {
+  const domain = ctx.messageIdDomain ?? ctx.addressBook.primaryDomain();
+
+  const to = recipientsOfKind(msg, "to");
+  const cc = recipientsOfKind(msg, "cc");
+  const bcc = recipientsOfKind(msg, "bcc");
+
+  const { inReplyTo, references } = buildThreadingHeaders(msg, ctx);
+
+  const text = textFromContent(msg);
+  const html = typeof msg.metadata.htmlBody === "string"
+    ? (msg.metadata.htmlBody as string)
+    : undefined;
+
+  const attachments = validateAttachments(msg.metadata.mailAttachments);
+
+  // Only forward an explicit, opt-in hints object to the backend. We do NOT
+  // dump arbitrary internal message metadata to the external mail provider.
+  const backendHints =
+    msg.metadata.mailBackendHints &&
+    typeof msg.metadata.mailBackendHints === "object"
+      ? (msg.metadata.mailBackendHints as Record<string, unknown>)
+      : undefined;
+
+  return {
+    idempotencyKey: msg.id,
+    from: ctx.addressBook.resolveFrom(msg.sender_id),
+    to,
+    ...(cc.length ? { cc } : {}),
+    ...(bcc.length ? { bcc } : {}),
+    subject: msg.subject,
+    text,
+    ...(html ? { html } : {}),
+    headers: {
+      messageId: mintMessageId(msg.id, domain),
+      ...(inReplyTo ? { inReplyTo } : {}),
+      ...(references && references.length ? { references } : {}),
+    },
+    ...(attachments ? { attachments } : {}),
+    ...(backendHints ? { backendHints } : {}),
+  };
+}
+
+/** Validate untrusted attachment metadata, dropping malformed entries. */
+function validateAttachments(value: unknown): MailAttachment[] | undefined {
+  if (!Array.isArray(value)) return undefined;
+  const out: MailAttachment[] = [];
+  for (const a of value) {
+    if (
+      a &&
+      typeof a === "object" &&
+      typeof (a as MailAttachment).contentRef === "string" &&
+      typeof (a as MailAttachment).contentType === "string"
+    ) {
+      const att = a as MailAttachment;
+      out.push({
+        contentRef: att.contentRef,
+        contentType: att.contentType,
+        sizeBytes: typeof att.sizeBytes === "number" ? att.sizeBytes : 0,
+        ...(typeof att.filename === "string" ? { filename: att.filename } : {}),
+        ...(typeof att.contentId === "string" ? { contentId: att.contentId } : {}),
+      });
+    }
+  }
+  return out.length ? out : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function recipientsOfKind(msg: Message, kind: RecipientKind): MailAddress[] {
+  return msg.recipients
+    .filter((r) => r.kind === kind)
+    .map((r) => ({ address: r.agent_id }));
+}
+
+/** Stable thread tag from the root of the References chain. */
+function deriveThreadTag(
+  references: string[] | undefined,
+  inReplyTo: string | undefined,
+  messageId: string | undefined
+): string | undefined {
+  const root =
+    (references && references.length > 0 ? references[0] : undefined) ??
+    inReplyTo ??
+    messageId;
+  if (!root) return undefined;
+  const hash = createHash("sha1").update(root).digest("hex").slice(0, 12);
+  return `mail-${hash}`;
+}
+
+function buildThreadingHeaders(
+  msg: Message,
+  ctx: OutboundMapContext
+): { inReplyTo?: string; references?: string[] } {
+  if (!msg.in_reply_to) {
+    // Fresh thread, but a recorded RFC References chain (e.g. from the inbound
+    // side) should still be carried if present in metadata.
+    const meta = msg.metadata.rfcReferences;
+    return { references: Array.isArray(meta) ? (meta as string[]) : undefined };
+  }
+
+  const domain = ctx.messageIdDomain ?? ctx.addressBook.primaryDomain();
+  const parentRfcId =
+    ctx.lookupRfcMessageId?.(msg.in_reply_to) ??
+    mintMessageId(msg.in_reply_to, domain);
+
+  const parentRefs =
+    ctx.lookupReferences?.(msg.in_reply_to) ??
+    (Array.isArray(msg.metadata.rfcReferences)
+      ? (msg.metadata.rfcReferences as string[])
+      : []);
+
+  return {
+    inReplyTo: parentRfcId,
+    references: [...parentRefs, parentRfcId],
+  };
+}
+
+function mintMessageId(inboxId: string, domain: string): string {
+  return `<${inboxId}@${domain}>`;
+}
+
+function textFromContent(msg: Message): string {
+  const c = msg.content;
+  if (c.type === "text" && typeof c.text === "string") return c.text;
+  return JSON.stringify(c);
+}
+
+function importanceFromHeaders(
+  raw: Record<string, string | string[]>
+): Importance {
+  const header = (k: string): string => {
+    const v = raw[k];
+    return (Array.isArray(v) ? v[0] : v ?? "").toString().toLowerCase();
+  };
+  const importance = header("importance");
+  const priority = header("x-priority");
+  if (importance === "high" || priority.startsWith("1") || priority.startsWith("2")) {
+    return "high";
+  }
+  if (importance === "low" || priority.startsWith("4") || priority.startsWith("5")) {
+    return "low";
+  }
+  return "normal";
+}