agent-inbox 0.2.3 → 0.2.4

package/src/mail/types.ts

@@ -0,0 +1,221 @@
+/**
+ * Mail interop type contract.
+ *
+ * Defines the `MailTransport` interface and its envelope types — the backend-
+ * agnostic contract every mail backend (self-hosted SMTP, managed provider)
+ * must satisfy. See docs/MAIL-INTEROP-PLAN.md for the design rationale.
+ *
+ * Phase 1 lands the types only; no backend, gateway, or router wiring yet.
+ */
+
+// ---------------------------------------------------------------------------
+// Capabilities & lifecycle
+// ---------------------------------------------------------------------------
+
+/** What a backend can do. The gateway adapts to these instead of assuming. */
+export interface MailCapabilities {
+  /**
+   * How outbound mail leaves: direct to arbitrary public MX (self-hosted SMTP),
+   * via a configured smarthost relay, or via the backend's own API. Informational.
+   */
+  outbound: "mx" | "relay" | "api";
+  /** Backend signs DKIM itself (provider) or we must sign before handing off. */
+  signsDkim: boolean;
+  /** Backend verifies SPF/DKIM/DMARC on inbound and reports results. */
+  verifiesInboundAuth: boolean;
+  /** Inbound arrives via a long-lived listener (SMTP) or a push webhook. */
+  inbound: "listener" | "webhook" | "none";
+  /** Max message size the backend will accept, bytes. */
+  maxMessageBytes: number;
+}
+
+export type MailTransportState =
+  | "stopped"
+  | "starting"
+  | "ready"
+  | "degraded"
+  | "stopping";
+
+export interface MailHealth {
+  state: MailTransportState;
+  /** Human-readable detail for health endpoints / logs. */
+  detail?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Addresses & attachments
+// ---------------------------------------------------------------------------
+
+export interface MailAddress {
+  /** RFC 5322 addr-spec, e.g. "bob@example.com". */
+  address: string;
+  /** Optional display name. */
+  name?: string;
+}
+
+export interface MailAttachment {
+  filename?: string;
+  contentType: string;
+  /** Content-ID for inline html parts. */
+  contentId?: string;
+  /** Opaque handle into an AttachmentStore — the envelope carries a ref, not bytes. */
+  contentRef: string;
+  sizeBytes: number;
+}
+
+// ---------------------------------------------------------------------------
+// Outbound
+// ---------------------------------------------------------------------------
+
+export interface OutboundMail {
+  /** Stable key for idempotent send. Derived from the inbox Message.id. */
+  idempotencyKey: string;
+  from: MailAddress;
+  to: MailAddress[];
+  cc?: MailAddress[];
+  bcc?: MailAddress[];
+  subject?: string;
+  /** Rendered bodies. At least one of text/html should be present. */
+  text?: string;
+  html?: string;
+  /** RFC 5322 threading headers, already computed by the mapper. */
+  headers: {
+    messageId: string;
+    inReplyTo?: string;
+    references?: string[];
+  };
+  attachments?: MailAttachment[];
+  /** Opaque passthrough for backend-specific knobs (provider tags, etc.). */
+  backendHints?: Record<string, unknown>;
+}
+
+export type MailSendDisposition = "delivered" | "transient" | "permanent";
+
+/**
+ * Result of a send attempt. Backends collapse their native failure modes into
+ * these three dispositions so the retry/queue layer needs no backend knowledge.
+ */
+export interface MailSendResult {
+  disposition: MailSendDisposition;
+  /** Provider/SMTP id when delivered, for correlating DSNs/bounces. */
+  remoteMessageId?: string;
+  /** Numeric SMTP-style code when available (e.g. 250, 451, 550). */
+  code?: number;
+  /** Human-readable, for logs only — never parsed for control flow. */
+  detail?: string;
+  /** For transient failures: hint for next attempt (e.g. greylist retry-after). */
+  retryAfterMs?: number;
+}
+
+// ---------------------------------------------------------------------------
+// Inbound
+// ---------------------------------------------------------------------------
+
+export interface InboundAuthResults {
+  spf: "pass" | "fail" | "softfail" | "neutral" | "none";
+  dkim: "pass" | "fail" | "none";
+  dmarc: "pass" | "fail" | "none";
+}
+
+/**
+ * Bounce/DSN classification, parsed from RFC 3464 delivery-status reports.
+ * Present when an inbound message is a bounce, so the gateway can correlate it
+ * to the failed outbound send instead of treating it as a fresh message.
+ */
+export interface InboundBounce {
+  /** "failed" (permanent), "delayed" (transient), "delivered" (positive DSN). */
+  action: "failed" | "delayed" | "delivered";
+  /** The address that bounced. */
+  recipient: string;
+  /** RFC 3463 status code, e.g. "5.1.1". */
+  status?: string;
+  /** Message-ID of the original outbound mail, when the DSN echoes it. */
+  originalMessageId?: string;
+  diagnostic?: string;
+}
+
+export interface InboundMail {
+  /** Peer-asserted SMTP envelope (MAIL FROM / RCPT TO), distinct from headers. */
+  envelopeFrom: string;
+  envelopeTo: string[];
+  from: MailAddress;
+  to: MailAddress[];
+  cc?: MailAddress[];
+  subject?: string;
+  text?: string;
+  html?: string;
+  headers: {
+    messageId?: string;
+    inReplyTo?: string;
+    references?: string[];
+    /** Everything else, lower-cased keys, for the mapper to mine. */
+    raw: Record<string, string | string[]>;
+  };
+  attachments?: MailAttachment[];
+  /** Auth verdict — present iff capabilities.verifiesInboundAuth. */
+  authResults?: InboundAuthResults;
+  /** Peer IP / hostname, for allow-listing and abuse control. */
+  remote?: { ip?: string; reverseDns?: string };
+  /** Set when this inbound mail is a bounce/DSN (see InboundBounce). */
+  bounce?: InboundBounce;
+  sizeBytes: number;
+  receivedAt: string; // ISO
+}
+
+// ---------------------------------------------------------------------------
+// The transport contract
+// ---------------------------------------------------------------------------
+
+/**
+ * Ingress handler. The transport awaits this; resolution means "durably
+ * accepted" and only then is the peer MTA / webhook ACKed. A thrown handler
+ * means NACK so the sender retries — never a silent drop.
+ */
+export type InboundHandler = (mail: InboundMail) => Promise<void>;
+
+export interface MailTransport {
+  readonly capabilities: MailCapabilities;
+  readonly state: MailTransportState;
+
+  /**
+   * Idempotent. Resolves only when inbound is actually accepting (port bound /
+   * webhook registered) so callers don't ACK before we can receive.
+   */
+  start(): Promise<void>;
+
+  /** Graceful: stop accepting new inbound, finish in-flight, then release. */
+  stop(): Promise<void>;
+
+  /**
+   * Send one already-rendered outbound message.
+   * MUST be idempotent on `envelope.idempotencyKey`.
+   * MUST NOT throw for delivery failures — return a classified result instead.
+   * MAY throw only for programmer error (e.g. called while stopped).
+   */
+  send(envelope: OutboundMail): Promise<MailSendResult>;
+
+  /** Register the single ingress handler. See InboundHandler. */
+  onReceive(handler: InboundHandler): void;
+
+  /** Liveness for health endpoints and the degraded → ready transition. */
+  health(): Promise<MailHealth>;
+}
+
+// ---------------------------------------------------------------------------
+// Attachment storage (opaque contentRef backing store)
+// ---------------------------------------------------------------------------
+
+/**
+ * Swappable attachment byte store. `contentRef` values on MailAttachment are
+ * opaque handles produced by `put`. Mirrors the Storage two-impl pattern:
+ * SqliteAttachmentStore (default) and FsAttachmentStore (opt-in) land later.
+ */
+export interface AttachmentStore {
+  /** Returns a content-addressed ref (sha256-based). Dedups identical bytes. */
+  put(
+    bytes: Buffer,
+    meta: { contentType: string; filename?: string }
+  ): Promise<string>;
+  get(ref: string): Promise<Buffer>;
+  delete(ref: string): Promise<void>;
+}

package/src/router/destination.ts

@@ -0,0 +1,140 @@
+/**
+ * Destination classification.
+ *
+ * Email addresses are syntactically identical to federation addresses
+ * (`bob@example.com` vs `bob@system-2`), so before routing we must classify a
+ * recipient as one of: local agent, federation peer, or external mail.
+ *
+ * Classification is explicit-list driven — nothing is guessed from "looks like
+ * a domain". An unknown `@x` is a hard error rather than a silent misroute.
+ * Federation peers may declare their own domains, in which case they win over
+ * mail config for that domain. See docs/MAIL-INTEROP-PLAN.md §1.
+ *
+ * This layer sits *above* `parseAddress`, which is left untouched.
+ */
+
+import { parseAddress } from "../federation/address.js";
+import type { FederatedAddress } from "../types.js";
+
+export type Destination =
+  | { class: "local"; agentId: string }
+  | { class: "federation"; agentId: string; address: FederatedAddress }
+  | { class: "mail"; email: string };
+
+export interface DestinationPeer {
+  systemId: string;
+  /** Dotted addresses routed to this peer instead of being treated as mail. */
+  domains?: string[];
+}
+
+export interface DestinationContext {
+  /** Returns true if `id` is a known local agent. */
+  isLocalAgent: (id: string) => boolean;
+  /** Configured federation peers (system ids + optionally declared domains). */
+  federationPeers: DestinationPeer[];
+  /** Mail domains we recognize (identity.localDomains ∪ routableDomains). */
+  mailDomains: string[];
+}
+
+/** Thrown when a recipient matches neither a federation peer nor a mail domain. */
+export class UnknownDestinationError extends Error {
+  constructor(public readonly agentId: string) {
+    super(
+      `Cannot classify destination "${agentId}": its domain is not a configured ` +
+        `federation peer or mail domain. Declare it explicitly to route it.`
+    );
+    this.name = "UnknownDestinationError";
+  }
+}
+
+/**
+ * Classify a recipient address into local / federation / mail.
+ *
+ * Priority order (deterministic):
+ *   1. No `@`                                  → local
+ *   2. `@x` matches a peer systemId or domain  → federation
+ *   3. `@x` (or parent domain) in mailDomains  → mail
+ *   4. otherwise                               → throw UnknownDestinationError
+ *
+ * @throws UnknownDestinationError for rule-4 misses.
+ */
+export function classifyDestination(
+  agentId: string,
+  ctx: DestinationContext
+): Destination {
+  const atIdx = agentId.indexOf("@");
+
+  // Rule 1: no @ — local agent (no domain to disambiguate).
+  if (atIdx === -1) {
+    return { class: "local", agentId };
+  }
+
+  const addr = parseAddress(agentId);
+  const system = addr.system; // the part after @ (before any /scope)
+
+  // Defensive: parseAddress yielded no system (e.g. trailing-only @) — treat
+  // the whole string as a local agent id rather than guessing a domain.
+  if (!system) {
+    return { class: "local", agentId };
+  }
+
+  // Rule 2: federation peer by systemId or declared domain (wins over mail).
+  for (const peer of ctx.federationPeers) {
+    if (peer.systemId === system || domainMatches(system, peer.domains)) {
+      return { class: "federation", agentId, address: addr };
+    }
+  }
+
+  // Rule 3: configured mail domain (exact or parent-domain suffix match).
+  if (domainMatches(system, ctx.mailDomains)) {
+    return { class: "mail", email: stripScope(agentId) };
+  }
+
+  // Rule 4: explicit-list miss — never guess.
+  throw new UnknownDestinationError(agentId);
+}
+
+/**
+ * True if `domain` equals, or is a subdomain of, any entry in `candidates`.
+ * Matching is case-insensitive. `mail.example.com` matches a candidate of
+ * `example.com`; `notexample.com` does not match `example.com`.
+ */
+export function domainMatches(
+  domain: string,
+  candidates: string[] | undefined
+): boolean {
+  if (!candidates || candidates.length === 0) return false;
+  const d = domain.toLowerCase();
+  for (const c of candidates) {
+    const cand = c.toLowerCase();
+    if (d === cand || d.endsWith(`.${cand}`)) return true;
+  }
+  return false;
+}
+
+/**
+ * Drop a trailing `/scope` qualifier from an address, leaving a bare email.
+ * `bob@example.com/work` → `bob@example.com`.
+ */
+function stripScope(agentId: string): string {
+  const atIdx = agentId.indexOf("@");
+  if (atIdx === -1) return agentId;
+  const slashIdx = agentId.indexOf("/", atIdx);
+  return slashIdx === -1 ? agentId : agentId.slice(0, slashIdx);
+}
+
+/**
+ * Detect domains claimed by both a federation peer and mail config. Federation
+ * wins (see classifyDestination), but callers should surface this at startup
+ * via a `mail.config.conflict` warning. Returns the conflicting domains.
+ */
+export function findDomainConflicts(ctx: DestinationContext): string[] {
+  const mail = new Set(ctx.mailDomains.map((d) => d.toLowerCase()));
+  const conflicts: string[] = [];
+  for (const peer of ctx.federationPeers) {
+    for (const dom of peer.domains ?? []) {
+      if (mail.has(dom.toLowerCase())) conflicts.push(dom);
+    }
+  }
+  return conflicts;
+}

package/src/router/message-router.ts

@@ -11,6 +11,17 @@ import type { Storage } from "../storage/interface.js";
 import type { ConnectionManager } from "../federation/connection-manager.js";
 import { parseAddress, isRemoteAddress } from "../federation/address.js";
 
+/**
+ * Outbound mail sink. Implemented by MailGateway; kept as a local interface so
+ * the router does not depend on the mail module (avoids a cycle).
+ */
+export interface MailEgress {
+  /** True if this recipient's domain is one the mail gateway routes for. */
+  ownsRecipient(agentId: string): boolean;
+  /** Render and deliver the mail-class recipients of a message. */
+  send(message: Message): Promise<void>;
+}
+
 export interface SendOptions {
   from: string;
   to: string | string[] | { agent_id: string; kind?: RecipientKind }[];
@@ -26,6 +37,7 @@ export interface SendOptions {
 
 export class MessageRouter {
   private federation: ConnectionManager | null = null;
+  private mail: MailEgress | null = null;
 
   constructor(
     private storage: Storage,
@@ -40,6 +52,13 @@ export class MessageRouter {
     this.federation = federation;
   }
 
+  /**
+   * Attach a mail gateway for routing to external email recipients.
+   */
+  setMail(mail: MailEgress): void {
+    this.mail = mail;
+  }
+
   async routeMessage(opts: SendOptions): Promise<Message> {
     const recipients = this.resolveRecipients(opts.to);
     const content = normalizeContent(opts.payload);
@@ -72,8 +91,11 @@ export class MessageRouter {
       created_at: now,
     };
 
-    // Mark local recipients as delivered; route remote ones via federation
+    // Classify recipients: mail (external email) takes precedence over the
+    // federation interpretation of "agent@domain"; remaining remote recipients
+    // go to federation; everything else local.
     for (const r of message.recipients) {
+      if (this.mail?.ownsRecipient(r.agent_id)) continue; // mail — see below
       const addr = parseAddress(r.agent_id);
       if (!isRemoteAddress(addr) && this.isLocal(r.agent_id)) {
         r.delivered_at = now;
@@ -91,10 +113,25 @@ export class MessageRouter {
 
     this.events.emit("message.created", message);
 
-    // Route remote recipients via federation
+    // Route external mail recipients via the mail gateway.
+    if (this.mail) {
+      const hasMail = message.recipients.some((r) =>
+        this.mail!.ownsRecipient(r.agent_id)
+      );
+      if (hasMail) {
+        // Fire-and-forget; transient failures are queued inside the gateway.
+        this.mail.send(message).catch(() => {
+          // Mail delivery failures are handled by the gateway's retry queue
+        });
+      }
+    }
+
+    // Route remaining remote recipients via federation (excluding mail).
     if (this.federation) {
-      const hasRemote = message.recipients.some((r) =>
-        isRemoteAddress(parseAddress(r.agent_id))
+      const hasRemote = message.recipients.some(
+        (r) =>
+          isRemoteAddress(parseAddress(r.agent_id)) &&
+          !this.mail?.ownsRecipient(r.agent_id)
       );
       if (hasRemote) {
         // Fire-and-forget federation routing (results tracked via events)

package/src/storage/interface.ts

@@ -36,6 +36,17 @@ export interface Storage {
   /** Delete messages older than `cutoff` (ISO timestamp). Returns the count removed. */
   pruneMessagesOlderThan(cutoff: string): number;
 
+  // External-id mapping (mail dedup + bounce correlation)
+  /**
+   * Record that an external message id (e.g. an RFC 5322 Message-ID) maps to a
+   * stored inbox message. Idempotent: re-recording the same external id is a no-op.
+   */
+  recordExternalId(externalId: string, messageId: string): void;
+  /** Look up the inbox message id previously recorded for an external id. */
+  getMessageIdByExternalId(externalId: string): string | undefined;
+  /** Convenience: whether an external id has already been recorded. */
+  hasSeenExternalId(externalId: string): boolean;
+
   // Conversations
   getConversation(id: string): Conversation | undefined;
   putConversation(conversation: Conversation): Conversation;

package/src/storage/memory.ts

@@ -13,6 +13,7 @@ export class InMemoryStorage implements Storage {
   private conversations = new Map<string, Conversation>();
   private turns: Turn[] = [];
   private threads = new Map<string, Thread>();
+  private externalIds = new Map<string, string>();
 
   // --- Agents ---
 
@@ -50,6 +51,20 @@ export class InMemoryStorage implements Storage {
     if (msg) msg.conversation_id = conversationId;
   }
 
+  recordExternalId(externalId: string, messageId: string): void {
+    if (!this.externalIds.has(externalId)) {
+      this.externalIds.set(externalId, messageId);
+    }
+  }
+
+  getMessageIdByExternalId(externalId: string): string | undefined {
+    return this.externalIds.get(externalId);
+  }
+
+  hasSeenExternalId(externalId: string): boolean {
+    return this.externalIds.has(externalId);
+  }
+
   pruneMessagesOlderThan(cutoff: string): number {
     let removed = 0;
     const removedIds = new Set<string>();

package/src/storage/sqlite.ts

@@ -128,6 +128,13 @@ export class SqliteStorage implements Storage {
         FOREIGN KEY (conversation_id) REFERENCES ${t("conversations")}(id)
       );
 
+      -- External-id mapping (mail dedup + bounce correlation)
+      CREATE TABLE IF NOT EXISTS ${t("external_ids")} (
+        external_id TEXT PRIMARY KEY,
+        message_id TEXT NOT NULL,
+        recorded_at TEXT NOT NULL
+      );
+
       -- Indexes for common queries
       CREATE INDEX IF NOT EXISTS idx_${t("messages")}_scope ON ${t("messages")}(scope);
       CREATE INDEX IF NOT EXISTS idx_${t("messages")}_sender ON ${t("messages")}(sender_id);
@@ -183,6 +190,12 @@ export class SqliteStorage implements Storage {
     `);
   }
 
+  /** Expose the underlying handle so sibling features (mail queue/attachments)
+   *  can co-locate their tables. Caller must not close it. */
+  getDatabase(): Database.Database {
+    return this.db;
+  }
+
   // --- Agents ---
 
   getAgent(agentId: string): Agent | undefined {
@@ -291,6 +304,29 @@ export class SqliteStorage implements Storage {
       .run(conversationId, messageId);
   }
 
+  recordExternalId(externalId: string, messageId: string): void {
+    this.db
+      .prepare(
+        `INSERT INTO ${this.p("external_ids")} (external_id, message_id, recorded_at)
+         VALUES (?, ?, ?)
+         ON CONFLICT(external_id) DO NOTHING`
+      )
+      .run(externalId, messageId, new Date().toISOString());
+  }
+
+  getMessageIdByExternalId(externalId: string): string | undefined {
+    const row = this.db
+      .prepare(
+        `SELECT message_id FROM ${this.p("external_ids")} WHERE external_id = ?`
+      )
+      .get(externalId) as { message_id: string } | undefined;
+    return row?.message_id;
+  }
+
+  hasSeenExternalId(externalId: string): boolean {
+    return this.getMessageIdByExternalId(externalId) !== undefined;
+  }
+
   pruneMessagesOlderThan(cutoff: string): number {
     const m = this.p("messages");
     const r = this.p("recipients");

package/src/types.ts

@@ -211,6 +211,11 @@ export interface FederationPeerConfig {
   url?: string;
   /** Mesh peer ID for agentic-mesh transport connections. */
   meshPeerId?: string;
+  /**
+   * Dotted addresses (e.g. "team.corp.internal") routed to this peer rather
+   * than treated as external mail. See destination classification (§1).
+   */
+  domains?: string[];
   auth?: FederationAuth;
   exposure?: ExposurePolicy;
 }
@@ -311,6 +316,73 @@ export interface QueuedMessage {
   nextRetry?: string;
 }
 
+// --- Mail interop ---
+
+/** Maps between agent ids and email addresses; declares owned domains. */
+export interface MailIdentityConfig {
+  /** Domains we receive for; inbound RCPT TO outside these is rejected. */
+  localDomains: string[];
+  /** agent_id ↔ primary email. Plus-addressing (agent+scope@domain) aware. */
+  mappings: Array<{ agentId: string; address: string }>;
+  /** Default mailbox for accepted-but-unmatched inbound (e.g. a triage agent). */
+  catchAllAgentId?: string;
+}
+
+export interface MailConfig {
+  enabled: boolean;
+  backend: "smtp" | "provider";
+  identity: MailIdentityConfig;
+  /**
+   * Domains we will SEND to without erroring (destination classification §1).
+   * Receiving uses identity.localDomains. Anything outside both → error.
+   */
+  routableDomains?: string[];
+  smtp?: {
+    listenPort?: number;
+    relay?: {
+      host: string;
+      port: number;
+      auth?: { user: string; pass: string };
+    };
+    dkim?: { domain: string; selector: string; privateKeyRef: string };
+  };
+  provider?: {
+    name: "ses" | "postmark" | "mailgun";
+    apiKeyRef: string;
+    webhookPath?: string;
+  };
+  /** Delivery queue overrides; defaults to sqlite persistence when mail enabled. */
+  queue?: Partial<DeliveryQueueConfig>;
+  /**
+   * Attachment byte storage. Defaults to "sqlite" (content-addressed BLOBs in
+   * the DB). Use "fs" to keep bytes on disk for large/high-volume deployments.
+   */
+  attachments?: {
+    backend?: "sqlite" | "fs";
+    /** Directory for the "fs" backend. Defaults to <home>/.claude/agent-inbox/attachments. */
+    dir?: string;
+  };
+  /** Inbound sender allow-list (domains). Empty/undefined = allow all. */
+  allowedSenderDomains?: string[];
+  /** Drop inbound whose DMARC verdict is "fail". */
+  rejectDmarcFail?: boolean;
+  /** Max attachments on an inbound message before rejection. */
+  maxAttachments?: number;
+  /** Inbound rate limiting (abuse control). Disabled if unset. */
+  rateLimit?: {
+    windowMs?: number;
+    perSenderDomain?: number;
+    global?: number;
+  };
+  /** Bounce handling (both default on). See §8. */
+  bounce?: {
+    /** Emit the mail.bounced event. */
+    emitEvent?: boolean;
+    /** Inject a synthetic bounce Message into the original sender's inbox. */
+    synthesizeInboxMessage?: boolean;
+  };
+}
+
 // --- Config ---
 
 export interface InboxConfig {
@@ -327,4 +399,5 @@ export interface InboxConfig {
     };
   };
   federation?: FederationConfig;
+  mail?: MailConfig;
 }