agent-inbox 0.2.2 → 0.2.4

package/dist/mail/types.d.ts

@@ -0,0 +1,177 @@
+/**
+ * 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.
+ */
+/** 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;
+}
+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;
+}
+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;
+}
+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;
+}
+/**
+ * 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>;
+}
+/**
+ * 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>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/mail/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/mail/types.ts"],"names":[],"mappings":"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"}

package/dist/mail/types.js

@@ -0,0 +1,11 @@
+/**
+ * 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.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/mail/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/mail/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/push/notifier.d.ts

@@ -17,6 +17,14 @@ export interface NotifierConfig {
     inboxDir: string;
     /** Optional webhook URLs to POST new messages to */
     webhooks?: string[];
+    /** Soft cap on entries per per-agent inbox file. The file is allowed to
+     *  grow ~10% over this before being trimmed back, to amortize trim cost
+     *  across many appends. Defaults to 1000. Set to 0 to disable. */
+    maxEntriesPerInbox?: number;
+    /** Soft cap (in bytes) on per-agent inbox file size, with the same ~10%
+     *  amortization headroom as `maxEntriesPerInbox`. Defaults to 5 MiB. Set
+     *  to 0 to disable. */
+    maxBytesPerInbox?: number;
 }
 export interface InboxFileEntry {
     messageId: string;
@@ -39,10 +47,23 @@ export declare class PushNotifier {
     private storage;
     private events;
     private webhooks;
+    private maxEntries;
+    private maxBytes;
+    /** In-memory tracking so we can decide when to trim without stat/read. */
+    private entryCounts;
+    private fileSizes;
     constructor(config: NotifierConfig, storage: Storage, events: EventEmitter);
     private onMessage;
     /** Write a message to an agent's inbox file (NDJSON) */
     private writeAgentInbox;
+    /** Update in-memory entry/size counters after an append. Lazy-inits from
+     *  the file when first seen so caps still apply across process restarts. */
+    private bumpCounters;
+    /** Trim the file when soft caps (~1.1× the configured limits) are exceeded.
+     *  This amortizes the cost of read+rewrite across many appends. */
+    private maybeEnforceCap;
+    /** Trim the file to maxEntries / maxBytes. Returns counts of what's left. */
+    private trimFile;
     /** Read and format an agent's pending inbox as markdown (for hook injection) */
     readAndClearAgentInbox(agentId: string): string | null;
     /** Get the path to an agent's inbox file */

package/dist/push/notifier.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notifier.d.ts","sourceRoot":"","sources":["../../src/push/notifier.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAEvD;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,aAAa,CAAC;IAC7B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,qBAAa,YAAY;IAIrB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,MAAM;IALhB,OAAO,CAAC,QAAQ,CAAW;gBAGjB,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,YAAY;IAW9B,OAAO,CAAC,SAAS;IAoBjB,wDAAwD;IACxD,OAAO,CAAC,eAAe;IAmBvB,gFAAgF;IAChF,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAkCtD,4CAA4C;IAC5C,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAMvC,8CAA8C;YAChC,WAAW;CAuB1B;AAED,2DAA2D;AAC3D,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAyBlD;AAED,mEAAmE;AACnE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,MAAM,CA0BrE"}
+{"version":3,"file":"notifier.d.ts","sourceRoot":"","sources":["../../src/push/notifier.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAEvD;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,cAAc;IAC7B,0CAA0C;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;sEAEkE;IAClE,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;2BAEuB;IACvB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAKD,MAAM,WAAW,cAAc;IAC7B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,4EAA4E;AAC5E,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,aAAa,CAAC;IAC7B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,qBAAa,YAAY;IASrB,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,MAAM;IAVhB,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,UAAU,CAAS;IAC3B,OAAO,CAAC,QAAQ,CAAS;IACzB,0EAA0E;IAC1E,OAAO,CAAC,WAAW,CAA6B;IAChD,OAAO,CAAC,SAAS,CAA6B;gBAGpC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,YAAY;IAc9B,OAAO,CAAC,SAAS;IAoBjB,wDAAwD;IACxD,OAAO,CAAC,eAAe;IAwBvB;gFAC4E;IAC5E,OAAO,CAAC,YAAY;IAoBpB;uEACmE;IACnE,OAAO,CAAC,eAAe;IAgBvB,6EAA6E;IAC7E,OAAO,CAAC,QAAQ;IA6BhB,gFAAgF;IAChF,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAoCtD,4CAA4C;IAC5C,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAMvC,8CAA8C;YAChC,WAAW;CAuB1B;AAED,2DAA2D;AAC3D,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAyBlD;AAED,mEAAmE;AACnE,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,cAAc,EAAE,GAAG,MAAM,CA0BrE"}

package/dist/push/notifier.js

@@ -1,15 +1,25 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+const DEFAULT_MAX_ENTRIES = 1000;
+const DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
 export class PushNotifier {
     config;
     storage;
     events;
     webhooks;
+    maxEntries;
+    maxBytes;
+    /** In-memory tracking so we can decide when to trim without stat/read. */
+    entryCounts = new Map();
+    fileSizes = new Map();
     constructor(config, storage, events) {
         this.config = config;
         this.storage = storage;
         this.events = events;
         this.webhooks = config.webhooks ?? [];
+        this.maxEntries =
+            config.maxEntriesPerInbox ?? DEFAULT_MAX_ENTRIES;
+        this.maxBytes = config.maxBytesPerInbox ?? DEFAULT_MAX_BYTES;
         // Subscribe to message.created events
         events.on("message.created", (msg) => this.onMessage(msg));
         // Ensure inbox directory exists
@@ -45,12 +55,82 @@ export class PushNotifier {
             importance: message.importance,
             timestamp: message.created_at,
         };
+        const line = JSON.stringify(entry) + "\n";
         try {
-            fs.appendFileSync(filePath, JSON.stringify(entry) + "\n");
+            fs.appendFileSync(filePath, line);
         }
         catch {
-            // Best-effort write
+            return; // Best-effort write
         }
+        if (this.maxEntries <= 0 && this.maxBytes <= 0)
+            return;
+        this.bumpCounters(filePath, line.length);
+        this.maybeEnforceCap(filePath);
+    }
+    /** Update in-memory entry/size counters after an append. Lazy-inits from
+     *  the file when first seen so caps still apply across process restarts. */
+    bumpCounters(filePath, addedBytes) {
+        let count = this.entryCounts.get(filePath);
+        let size = this.fileSizes.get(filePath);
+        if (count === undefined || size === undefined) {
+            try {
+                const raw = fs.readFileSync(filePath, "utf-8");
+                count = raw.split("\n").filter((l) => l.length > 0).length;
+                size = raw.length;
+            }
+            catch {
+                count = 1;
+                size = addedBytes;
+            }
+        }
+        else {
+            count++;
+            size += addedBytes;
+        }
+        this.entryCounts.set(filePath, count);
+        this.fileSizes.set(filePath, size);
+    }
+    /** Trim the file when soft caps (~1.1× the configured limits) are exceeded.
+     *  This amortizes the cost of read+rewrite across many appends. */
+    maybeEnforceCap(filePath) {
+        const count = this.entryCounts.get(filePath) ?? 0;
+        const size = this.fileSizes.get(filePath) ?? 0;
+        const overEntries = this.maxEntries > 0 && count > this.maxEntries * 1.1;
+        const overBytes = this.maxBytes > 0 && size > this.maxBytes * 1.1;
+        if (!overEntries && !overBytes)
+            return;
+        const result = this.trimFile(filePath);
+        this.entryCounts.set(filePath, result.lines);
+        this.fileSizes.set(filePath, result.bytes);
+    }
+    /** Trim the file to maxEntries / maxBytes. Returns counts of what's left. */
+    trimFile(filePath) {
+        let raw;
+        try {
+            raw = fs.readFileSync(filePath, "utf-8");
+        }
+        catch {
+            return { lines: 0, bytes: 0 };
+        }
+        let kept = raw.split("\n").filter((l) => l.length > 0);
+        if (this.maxEntries > 0 && kept.length > this.maxEntries) {
+            kept = kept.slice(kept.length - this.maxEntries);
+        }
+        let bytes = kept.reduce((acc, l) => acc + l.length + 1, 0);
+        if (this.maxBytes > 0) {
+            while (kept.length > 1 && bytes > this.maxBytes) {
+                bytes -= kept[0].length + 1;
+                kept.shift();
+            }
+        }
+        const out = kept.length ? kept.join("\n") + "\n" : "";
+        try {
+            fs.writeFileSync(filePath, out);
+        }
+        catch {
+            // Best-effort
+        }
+        return { lines: kept.length, bytes: out.length };
     }
     /** Read and format an agent's pending inbox as markdown (for hook injection) */
     readAndClearAgentInbox(agentId) {
@@ -81,6 +161,8 @@ export class PushNotifier {
         // Clear the file
         try {
             fs.writeFileSync(filePath, "");
+            this.entryCounts.set(filePath, 0);
+            this.fileSizes.set(filePath, 0);
         }
         catch {
             // Best-effort clear

package/dist/push/notifier.js.map

@@ -1 +1 @@
-{"version":3,"file":"notifier.js","sourceRoot":"","sources":["../../src/push/notifier.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"notifier.js","sourceRoot":"","sources":["../../src/push/notifier.ts"],"names":[],"mappings":"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"}

package/dist/router/destination.d.ts

@@ -0,0 +1,69 @@
+/**
+ * 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 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 declare class UnknownDestinationError extends Error {
+    readonly agentId: string;
+    constructor(agentId: string);
+}
+/**
+ * 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 declare function classifyDestination(agentId: string, ctx: DestinationContext): Destination;
+/**
+ * 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 declare function domainMatches(domain: string, candidates: string[] | undefined): boolean;
+/**
+ * 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 declare function findDomainConflicts(ctx: DestinationContext): string[];
+//# sourceMappingURL=destination.d.ts.map

package/dist/router/destination.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"destination.d.ts","sourceRoot":"","sources":["../../src/router/destination.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,MAAM,WAAW,GACnB;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACnC;IAAE,KAAK,EAAE,YAAY,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,gBAAgB,CAAA;CAAE,GACnE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAErC,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,kBAAkB;IACjC,mDAAmD;IACnD,YAAY,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACtC,8EAA8E;IAC9E,eAAe,EAAE,eAAe,EAAE,CAAC;IACnC,2EAA2E;IAC3E,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,mFAAmF;AACnF,qBAAa,uBAAwB,SAAQ,KAAK;aACpB,OAAO,EAAE,MAAM;gBAAf,OAAO,EAAE,MAAM;CAO5C;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,MAAM,EACf,GAAG,EAAE,kBAAkB,GACtB,WAAW,CA+Bb;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAAE,GAAG,SAAS,GAC/B,OAAO,CAQT;AAaD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,kBAAkB,GAAG,MAAM,EAAE,CASrE"}

package/dist/router/destination.js

@@ -0,0 +1,106 @@
+/**
+ * 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";
+/** Thrown when a recipient matches neither a federation peer nor a mail domain. */
+export class UnknownDestinationError extends Error {
+    agentId;
+    constructor(agentId) {
+        super(`Cannot classify destination "${agentId}": its domain is not a configured ` +
+            `federation peer or mail domain. Declare it explicitly to route it.`);
+        this.agentId = agentId;
+        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, ctx) {
+    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, candidates) {
+    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) {
+    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) {
+    const mail = new Set(ctx.mailDomains.map((d) => d.toLowerCase()));
+    const conflicts = [];
+    for (const peer of ctx.federationPeers) {
+        for (const dom of peer.domains ?? []) {
+            if (mail.has(dom.toLowerCase()))
+                conflicts.push(dom);
+        }
+    }
+    return conflicts;
+}
+//# sourceMappingURL=destination.js.map

package/dist/router/destination.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"destination.js","sourceRoot":"","sources":["../../src/router/destination.ts"],"names":[],"mappings":"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"}

package/dist/router/message-router.d.ts

@@ -2,6 +2,16 @@ import { EventEmitter } from "node:events";
 import type { Message, MessageContent, Recipient, RecipientKind, Importance } from "../types.js";
 import type { Storage } from "../storage/interface.js";
 import type { ConnectionManager } from "../federation/connection-manager.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[] | {
@@ -22,11 +32,16 @@ export declare class MessageRouter {
     private events;
     private defaultScope;
     private federation;
+    private mail;
     constructor(storage: Storage, events: EventEmitter, defaultScope?: string);
     /**
      * Attach a federation connection manager for cross-system routing.
      */
     setFederation(federation: ConnectionManager): void;
+    /**
+     * Attach a mail gateway for routing to external email recipients.
+     */
+    setMail(mail: MailEgress): void;
     routeMessage(opts: SendOptions): Promise<Message>;
     markRead(messageId: string, agentId: string): boolean;
     markAcknowledged(messageId: string, agentId: string): boolean;

package/dist/router/message-router.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"message-router.d.ts","sourceRoot":"","sources":["../../src/router/message-router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EACV,OAAO,EACP,cAAc,EACd,SAAS,EACT,aAAa,EACb,UAAU,EACX,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAG7E,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,aAAa,CAAA;KAAE,EAAE,CAAC;IACrE,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,qBAAa,aAAa;IAItB,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,YAAY;IALtB,OAAO,CAAC,UAAU,CAAkC;gBAG1C,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,YAAY,EACpB,YAAY,GAAE,MAAkB;IAG1C;;OAEG;IACH,aAAa,CAAC,UAAU,EAAE,iBAAiB,GAAG,IAAI;IAI5C,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAmEvD,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAUrD,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAU7D,iBAAiB,CACf,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,aAAa,CAAA;KAAE,EAAE,GACnE,SAAS,EAAE;IAed,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAOjC;;OAEG;IACH,aAAa,IAAI,iBAAiB,GAAG,IAAI;CAG1C;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,cAAc,CAajE"}
+{"version":3,"file":"message-router.d.ts","sourceRoot":"","sources":["../../src/router/message-router.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,KAAK,EACV,OAAO,EACP,cAAc,EACd,SAAS,EACT,aAAa,EACb,UAAU,EACX,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAG7E;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,0EAA0E;IAC1E,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IACxC,iEAAiE;IACjE,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,aAAa,CAAA;KAAE,EAAE,CAAC;IACrE,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,qBAAa,aAAa;IAKtB,OAAO,CAAC,OAAO;IACf,OAAO,CAAC,MAAM;IACd,OAAO,CAAC,YAAY;IANtB,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,IAAI,CAA2B;gBAG7B,OAAO,EAAE,OAAO,EAChB,MAAM,EAAE,YAAY,EACpB,YAAY,GAAE,MAAkB;IAG1C;;OAEG;IACH,aAAa,CAAC,UAAU,EAAE,iBAAiB,GAAG,IAAI;IAIlD;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,UAAU,GAAG,IAAI;IAIzB,YAAY,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAqFvD,QAAQ,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAUrD,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAU7D,iBAAiB,CACf,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,aAAa,CAAA;KAAE,EAAE,GACnE,SAAS,EAAE;IAed,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAOjC;;OAEG;IACH,aAAa,IAAI,iBAAiB,GAAG,IAAI;CAG1C;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,cAAc,CAajE"}