@holon-run/agentinbox 1.6.0 → 1.7.0

package/dist/src/adapters.js

@@ -5,6 +5,7 @@ const paths_1 = require("./paths");
 const feishu_1 = require("./sources/feishu");
 const github_1 = require("./sources/github");
 const telegram_1 = require("./sources/telegram");
+const email_1 = require("./sources/email");
 const remote_1 = require("./sources/remote");
 const remote_modules_1 = require("./sources/remote_modules");
 const source_resolution_1 = require("./source_resolution");
@@ -42,6 +43,7 @@ class AdapterRegistry {
     feishuDelivery;
     githubDelivery = new github_1.GithubDeliveryAdapter();
     telegramDelivery;
+    emailDelivery;
     homeDir;
     remoteModuleRegistry;
     constructor(store, appendSourceEvent, options) {
@@ -51,6 +53,7 @@ class AdapterRegistry {
         });
         this.feishuDelivery = new feishu_1.FeishuDeliveryAdapter(options?.feishuClient);
         this.telegramDelivery = new telegram_1.TelegramDeliveryAdapter(options?.telegramClient);
+        this.emailDelivery = new email_1.EmailDeliveryAdapter(options?.emailClient);
         this.remoteSource = new remote_1.RemoteSourceRuntime(store, appendSourceEvent, {
             homeDir: this.homeDir,
             client: options?.remoteSourceClient,
@@ -76,6 +79,9 @@ class AdapterRegistry {
         if (type === "telegram_bot") {
             return this.remoteSource;
         }
+        if (type === "email_mailbox") {
+            return this.remoteSource;
+        }
         return this.localEventSource;
     }
     deliveryAdapterFor(provider) {
@@ -88,6 +94,9 @@ class AdapterRegistry {
         if (provider === "telegram") {
             return this.telegramDelivery;
         }
+        if (provider === "email") {
+            return this.emailDelivery;
+        }
         return this.defaultDelivery;
     }
     async start() {
@@ -251,6 +260,9 @@ class AdapterRegistry {
         if (handle.provider === "telegram") {
             return this.remoteModuleRegistry.resolve(syntheticBuiltinSource("telegram_bot"), this.homeDir);
         }
+        if (handle.provider === "email") {
+            return this.remoteModuleRegistry.resolve(syntheticBuiltinSource("email_mailbox"), this.homeDir);
+        }
         return null;
     }
 }
@@ -262,6 +274,7 @@ function isExplicitFollowPreviewRef(value) {
         value === "github_repo_ci" ||
         value === "feishu_bot" ||
         value === "telegram_bot" ||
+        value === "email_mailbox" ||
         value.startsWith("remote:"));
 }
 function hasRemoteSourceModulePath(config) {

package/dist/src/service.js

@@ -3313,7 +3313,8 @@ function sourceTypeForPreviewRef(sourceRef) {
         sourceRef === "github_repo" ||
         sourceRef === "github_repo_ci" ||
         sourceRef === "feishu_bot" ||
-        sourceRef === "telegram_bot") {
+        sourceRef === "telegram_bot" ||
+        sourceRef === "email_mailbox") {
         return sourceRef;
     }
     if (sourceRef.startsWith("remote:")) {
@@ -3615,6 +3616,9 @@ function providerForSourceType(sourceType) {
     if (sourceType === "telegram_bot") {
         return "telegram";
     }
+    if (sourceType === "email_mailbox") {
+        return "email";
+    }
     return null;
 }
 function authHeaders(auth) {
@@ -4209,6 +4213,8 @@ function listHostStreamKinds(hostType) {
             return ["message_events"];
         case "telegram":
             return ["message_updates"];
+        case "email":
+            return ["message_events"];
         case "local_event":
             return ["events"];
         case "remote_source":
@@ -4218,6 +4224,7 @@ function listHostStreamKinds(hostType) {
 const KNOWN_DELIVERY_SURFACES = {
     feishu: ["message_reply", "chat_message"],
     github: ["issue_comment", "pull_request_comment", "review_comment"],
+    email: ["message_reply", "message_send"],
 };
 function unsupportedDeliverySurfaceMessage(handle) {
     const supported = KNOWN_DELIVERY_SURFACES[handle.provider];
@@ -4298,6 +4305,12 @@ function getHostConfigFields(hostType) {
                 { name: "tokenEnv", type: "string", description: "Environment variable containing the Telegram Bot API token.", required: false },
                 { name: "botUsername", type: "string", description: "Optional bot username used for shared host identity.", required: false },
             ];
+        case "email":
+            return [
+                { name: "uxcAuth", type: "string", description: "UXC auth profile holding mailbox credentials.", required: false },
+                { name: "smtpEndpoint", type: "string", description: "Default smtp:// endpoint for outbound delivery.", required: false },
+                { name: "fromAddress", type: "string", description: "Default outbound From address.", required: false },
+            ];
         case "local_event":
             return [];
         case "remote_source":
@@ -4317,6 +4330,9 @@ function sourceTypeForStreamRegistration(hostType, streamKind) {
     if (hostType === "telegram") {
         return "telegram_bot";
     }
+    if (hostType === "email") {
+        return "email_mailbox";
+    }
     if (hostType === "local_event") {
         return "local_event";
     }

package/dist/src/source_hosts.js

@@ -60,6 +60,22 @@ function resolveSourceRegistration(input) {
             sourceType: input.sourceType,
         };
     }
+    if (input.sourceType === "email_mailbox") {
+        const provider = stringOrDefault(config.provider, "imap");
+        return {
+            hostType: "email",
+            hostKey: `email:${provider}:${stringOrDefault(config.account, stringOrDefault(config.uxcAuth, input.sourceKey))}`,
+            hostConfig: {
+                ...(valueOrUndefined(config.uxcAuth) ? { uxcAuth: config.uxcAuth } : {}),
+                ...(valueOrUndefined(config.smtpEndpoint) ? { smtpEndpoint: config.smtpEndpoint } : {}),
+                ...(valueOrUndefined(config.fromAddress) ? { fromAddress: config.fromAddress } : {}),
+            },
+            streamKind: "message_events",
+            streamKey: input.sourceKey,
+            streamConfig: config,
+            sourceType: input.sourceType,
+        };
+    }
     if (input.sourceType === "local_event") {
         return {
             hostType: "local_event",

package/dist/src/source_schema.js

@@ -189,6 +189,57 @@ const SOURCE_SCHEMAS = {
             { name: "endpoint", type: "string", required: false, description: "Optional Telegram Bot API endpoint override." },
         ],
     },
+    email_mailbox: {
+        sourceType: "email_mailbox",
+        metadataFields: [
+            { name: "provider", type: "string", description: "Email provider: imap, gmail, graph, or jmap." },
+            { name: "account", type: "string", description: "Mailbox account alias." },
+            { name: "mailbox", type: "string", description: "Mailbox name such as INBOX." },
+            { name: "messageId", type: "string|null", description: "RFC Message-ID header when present." },
+            { name: "providerMessageId", type: "string|null", description: "Provider-native message id (IMAP UID or provider message id)." },
+            { name: "threadId", type: "string|null", description: "Thread reference derived from References/In-Reply-To headers." },
+            { name: "from", type: "string|null", description: "Normalized sender address." },
+            { name: "fromName", type: "string|null", description: "Sender display name when present." },
+            { name: "to", type: "object[]", description: "Normalized recipients with address and optional name." },
+            { name: "cc", type: "object[]", description: "Normalized cc recipients with address and optional name." },
+            { name: "subject", type: "string|null", description: "Message subject." },
+            { name: "textPreview", type: "string|null", description: "Short body snippet." },
+            { name: "date", type: "string|null", description: "Message date header value." },
+            { name: "hasAttachments", type: "boolean", description: "Whether the message carries attachments." },
+            { name: "attachmentCount", type: "number|null", description: "Attachment count; null when the provider did not expand attachment metadata." },
+            { name: "attachments", type: "object[]", description: "Attachment metadata entries with opaque retrieval handles; binary content is never embedded." },
+        ],
+        payloadExamples: [
+            {
+                type: "email_event",
+                version: "v1",
+                provider: "imap",
+                account: "user@example.com",
+                mailbox: "INBOX",
+                event_kind: "message_received",
+                message: {
+                    uid: "42",
+                    message_id: "<msg@example.com>",
+                    from: "sender@example.com",
+                    to: [{ raw: "user@example.com" }],
+                    subject: "Quarterly report",
+                    snippet: "Please review...",
+                },
+            },
+        ],
+        eventVariantExamples: ["email.message.received"],
+        configFields: [
+            { name: "provider", type: "string", required: true, description: "Email provider: imap, gmail, graph, or jmap." },
+            { name: "uxcAuth", type: "string", required: true, description: "UXC auth profile name holding mailbox credentials; credentials never inline." },
+            { name: "endpoint", type: "string", required: false, description: "imap:// or imaps:// endpoint for imap; provider API endpoint for gmail/graph/jmap (jmap requires it)." },
+            { name: "account", type: "string", required: false, description: "Account alias; defaults to the auth profile username." },
+            { name: "mailbox", type: "string", required: false, description: "Mailbox to watch; defaults to INBOX." },
+            { name: "pollIntervalSecs", type: "number", required: false, description: "Provider poll interval in seconds (min 15, default 60)." },
+            { name: "smtpEndpoint", type: "string", required: false, description: "Default smtp:// endpoint for outbound reply/send delivery." },
+            { name: "fromAddress", type: "string", required: false, description: "Default outbound From address for delivery." },
+            { name: "addressAllowlist", type: "string[]", required: false, description: "Optional from/to address allowlist applied before inbox routing." },
+        ],
+    },
 };
 function getSourceSchema(sourceType) {
     const schema = SOURCE_SCHEMAS[sourceType];

package/dist/src/sources/email.js

@@ -0,0 +1,532 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailDeliveryAdapter = exports.RpcEmailUxcClient = exports.GRAPH_MESSAGES_ENDPOINT = exports.GMAIL_MESSAGES_ENDPOINT = exports.EMAIL_EVENT_VERSION = exports.EMAIL_EVENT_TYPE = exports.EMAIL_MAILBOX_DEFAULT_POLL_INTERVAL_SECS = exports.EMAIL_DEFAULT_MAILBOX = void 0;
+exports.parseEmailMailboxSourceConfig = parseEmailMailboxSourceConfig;
+exports.buildEmailMailboxSourceSpec = buildEmailMailboxSourceSpec;
+exports.normalizeEmailMailboxEvent = normalizeEmailMailboxEvent;
+exports.emailDeliveryOperationsForHandle = emailDeliveryOperationsForHandle;
+exports.invokeEmailDeliveryOperation = invokeEmailDeliveryOperation;
+const uxc_daemon_client_1 = require("@holon-run/uxc-daemon-client");
+exports.EMAIL_DEFAULT_MAILBOX = "INBOX";
+exports.EMAIL_MAILBOX_DEFAULT_POLL_INTERVAL_SECS = 60;
+exports.EMAIL_EVENT_TYPE = "email_event";
+exports.EMAIL_EVENT_VERSION = "v1";
+exports.GMAIL_MESSAGES_ENDPOINT = "https://gmail.googleapis.com/gmail/v1/users/me/messages";
+exports.GRAPH_MESSAGES_ENDPOINT = "https://graph.microsoft.com/v1.0/me/messages?$expand=attachments";
+const EMAIL_MAILBOX_PROVIDERS = new Set(["imap", "gmail", "graph", "jmap"]);
+const EMAIL_DEFAULT_ENDPOINTS = {
+    gmail: exports.GMAIL_MESSAGES_ENDPOINT,
+    graph: exports.GRAPH_MESSAGES_ENDPOINT,
+};
+function parseEmailMailboxSourceConfig(source) {
+    const config = source.config ?? {};
+    const providerRaw = asString(config.provider) ?? asString(config.emailProvider);
+    if (!providerRaw) {
+        throw new Error("email_mailbox requires config.provider (imap, gmail, graph, or jmap)");
+    }
+    const provider = providerRaw.trim().toLowerCase();
+    if (!EMAIL_MAILBOX_PROVIDERS.has(provider)) {
+        throw new Error(`email_mailbox config.provider must be one of imap, gmail, graph, jmap; got ${providerRaw}`);
+    }
+    const endpointRaw = asString(config.endpoint);
+    let endpoint;
+    if (provider === "imap") {
+        if (!endpointRaw) {
+            throw new Error("email_mailbox with provider=imap requires config.endpoint (imap:// or imaps://)");
+        }
+        if (!/^imaps?:\/\//i.test(endpointRaw)) {
+            throw new Error(`email_mailbox imap endpoint must start with imap:// or imaps://; got ${endpointRaw}`);
+        }
+        endpoint = endpointRaw;
+    }
+    else {
+        const fallback = EMAIL_DEFAULT_ENDPOINTS[provider];
+        if (endpointRaw) {
+            if (!/^https?:\/\//i.test(endpointRaw)) {
+                throw new Error(`email_mailbox ${provider} endpoint must start with http:// or https://; got ${endpointRaw}`);
+            }
+            endpoint = endpointRaw;
+        }
+        else if (fallback) {
+            endpoint = fallback;
+        }
+        else {
+            throw new Error(`email_mailbox with provider=${provider} requires config.endpoint (${provider} API URL)`);
+        }
+    }
+    const uxcAuth = asString(config.uxcAuth) ?? asString(config.auth);
+    if (!uxcAuth || uxcAuth.trim().length === 0) {
+        throw new Error("email_mailbox requires config.uxcAuth (UXC auth profile name; credentials stay in UXC)");
+    }
+    const pollIntervalRaw = config.pollIntervalSecs;
+    let pollIntervalSecs = exports.EMAIL_MAILBOX_DEFAULT_POLL_INTERVAL_SECS;
+    if (pollIntervalRaw !== undefined && pollIntervalRaw !== null) {
+        const parsed = numberFromUnknown(pollIntervalRaw);
+        if (parsed === undefined || !Number.isInteger(parsed) || parsed < 15) {
+            throw new Error(`email_mailbox config.pollIntervalSecs must be an integer >= 15; got ${String(pollIntervalRaw)}`);
+        }
+        pollIntervalSecs = parsed;
+    }
+    const smtpEndpoint = asString(config.smtpEndpoint);
+    if (smtpEndpoint && !/^smtp:\/\/./i.test(smtpEndpoint)) {
+        throw new Error(`email_mailbox config.smtpEndpoint must use smtp:// (uxc SMTP surface); got ${smtpEndpoint}`);
+    }
+    const fromAddress = asString(config.fromAddress);
+    if (fromAddress && !fromAddress.includes("@")) {
+        throw new Error(`email_mailbox config.fromAddress must be an email address; got ${fromAddress}`);
+    }
+    const account = asString(config.account) ?? undefined;
+    if (account !== undefined && account.trim().length === 0) {
+        throw new Error("email_mailbox config.account must be a non-empty string when provided");
+    }
+    const mailbox = asString(config.mailbox) ?? exports.EMAIL_DEFAULT_MAILBOX;
+    if (mailbox.trim().length === 0) {
+        throw new Error("email_mailbox config.mailbox must be a non-empty string when provided");
+    }
+    const addressAllowlist = asStringArray(config.addressAllowlist ?? config.addressAllowList);
+    return {
+        provider: provider,
+        endpoint,
+        uxcAuth: uxcAuth.trim(),
+        account: account?.trim() || undefined,
+        mailbox,
+        pollIntervalSecs,
+        ...(smtpEndpoint ? { smtpEndpoint } : {}),
+        ...(fromAddress ? { fromAddress } : {}),
+        ...(addressAllowlist && addressAllowlist.length > 0 ? { addressAllowlist } : {}),
+    };
+}
+function buildEmailMailboxSourceSpec(config) {
+    const args = compactRecord({
+        mailbox: config.mailbox,
+        account: config.account,
+    });
+    if (config.provider === "imap") {
+        return {
+            endpoint: config.endpoint,
+            mode: "stream",
+            transport_hint: "email_imap_idle",
+            args,
+            options: {
+                auth: config.uxcAuth,
+                artifact_compaction: false,
+            },
+        };
+    }
+    return {
+        endpoint: config.endpoint,
+        mode: "poll",
+        transport_hint: "email_provider_poll",
+        args: {
+            provider: config.provider,
+            ...args,
+        },
+        poll_config: {
+            interval_secs: config.pollIntervalSecs,
+            extract_items_pointer: "/items",
+            checkpoint_strategy: {
+                type: "item_key",
+                item_key_pointer: "/message/uid",
+            },
+        },
+        options: {
+            auth: config.uxcAuth,
+            artifact_compaction: false,
+        },
+    };
+}
+function emailActorParts(value) {
+    if (typeof value === "string") {
+        const raw = value.trim();
+        if (raw.length === 0) {
+            return null;
+        }
+        const angled = raw.match(/<([^>]+)>\s*$/);
+        if (angled) {
+            const name = raw.slice(0, raw.lastIndexOf("<")).trim().replace(/^"|"$/g, "").trim();
+            return { address: angled[1].trim(), name: name.length > 0 ? name : null, raw };
+        }
+        return { address: raw, name: null, raw };
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    const record = value;
+    if (typeof record.raw === "string") {
+        return emailActorParts(record.raw);
+    }
+    const address = asString(record.address) ?? asString(record.email);
+    if (address) {
+        return { address, name: asString(record.name), raw: address };
+    }
+    return null;
+}
+function emailActorAddresses(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    const addresses = [];
+    for (const item of value) {
+        const parts = emailActorParts(item);
+        if (parts?.address) {
+            addresses.push(parts.address);
+        }
+    }
+    return addresses;
+}
+function emailActorList(value) {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+    return value
+        .map((item) => emailActorParts(item))
+        .filter((parts) => Boolean(parts?.address))
+        .map((parts) => ({
+        address: parts.address,
+        ...(parts.name ? { name: parts.name } : {}),
+    }));
+}
+function normalizeEmailMailboxEvent(source, config, raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return null;
+    }
+    const payload = raw;
+    if (payload.type !== exports.EMAIL_EVENT_TYPE) {
+        return null;
+    }
+    const version = asString(payload.version);
+    if (version !== null && version !== exports.EMAIL_EVENT_VERSION) {
+        return null;
+    }
+    if (payload.event_kind !== "message_received") {
+        return null;
+    }
+    const message = asRecord(payload.message);
+    if (Object.keys(message).length === 0) {
+        return null;
+    }
+    const provider = asString(payload.provider) ?? config.provider;
+    const account = asString(payload.account) ?? config.account ?? config.uxcAuth;
+    const mailbox = asString(payload.mailbox) ?? config.mailbox;
+    const uid = stringFromUnknown(message.uid);
+    const messageId = asString(message.message_id) ?? uid;
+    if (!uid && !messageId) {
+        return null;
+    }
+    const fromParts = emailActorParts(message.from);
+    const toAddresses = emailActorAddresses(message.to);
+    if (config.addressAllowlist &&
+        config.addressAllowlist.length > 0 &&
+        !addressMatchesAllowlist(config.addressAllowlist, fromParts?.address ?? null, toAddresses)) {
+        return null;
+    }
+    const attachments = Array.isArray(message.attachments)
+        ? message.attachments.filter((item) => Boolean(item) && typeof item === "object" && !Array.isArray(item))
+        : [];
+    const attachmentCountRaw = message.attachment_count;
+    const attachmentCount = numberFromUnknown(attachmentCountRaw) ?? null;
+    const date = asString(message.date);
+    return {
+        sourceId: source.sourceId,
+        sourceNativeId: `email:${provider}:${account}:${mailbox}:${uid ?? messageId}`,
+        eventVariant: "email.message.received",
+        occurredAt: occurredAtFromEmailDate(date),
+        metadata: {
+            provider,
+            account,
+            mailbox,
+            messageId: messageId ?? null,
+            providerMessageId: uid ?? null,
+            threadId: asString(message.thread_id),
+            from: fromParts ? (fromParts.address ?? fromParts.raw) : null,
+            fromName: fromParts?.name ?? null,
+            to: emailActorList(message.to),
+            cc: emailActorList(message.cc),
+            subject: asString(message.subject),
+            textPreview: asString(message.snippet),
+            date,
+            hasAttachments: attachments.length > 0 || message.has_attachments === true,
+            attachmentCount,
+            attachments,
+        },
+        rawPayload: payload,
+        deliveryHandle: {
+            provider: "email",
+            surface: "message_reply",
+            targetRef: fromParts ? (fromParts.address ?? fromParts.raw) : "",
+            threadRef: messageId ?? null,
+            replyMode: "reply",
+        },
+    };
+}
+function addressMatchesAllowlist(allowlist, fromAddress, toAddresses) {
+    const normalized = allowlist
+        .map((entry) => entry.trim().toLowerCase())
+        .filter((entry) => entry.length > 0);
+    if (normalized.length === 0) {
+        return true;
+    }
+    const lowerFrom = fromAddress?.toLowerCase() ?? null;
+    if (lowerFrom && normalized.includes(lowerFrom)) {
+        return true;
+    }
+    return toAddresses.some((address) => normalized.includes(address.toLowerCase()));
+}
+function occurredAtFromEmailDate(date) {
+    if (date) {
+        const parsed = Date.parse(date);
+        if (Number.isFinite(parsed)) {
+            return new Date(parsed).toISOString();
+        }
+    }
+    return new Date().toISOString();
+}
+class RpcEmailUxcClient {
+    client;
+    constructor(client = new uxc_daemon_client_1.UxcDaemonClient({ env: process.env })) {
+        this.client = client;
+    }
+    request(method, params) {
+        return this.client.request(method, params);
+    }
+}
+exports.RpcEmailUxcClient = RpcEmailUxcClient;
+function emailDeliveryOperationsForHandle(handle) {
+    if (handle.provider !== "email") {
+        return [];
+    }
+    if (handle.surface !== "message_reply" && handle.surface !== "message_send") {
+        return [];
+    }
+    const isReply = handle.surface === "message_reply";
+    const commonProperties = {
+        text: { type: "string", minLength: 1 },
+        subject: { type: "string", minLength: 1 },
+        to: { type: "array", items: { type: "string", minLength: 1 } },
+        cc: { type: "array", items: { type: "string", minLength: 1 } },
+        from: { type: "string", minLength: 1 },
+        smtpEndpoint: { type: "string", minLength: 1 },
+        uxcAuth: { type: "string", minLength: 1 },
+        correlationKey: { type: "string", minLength: 1 },
+    };
+    const operations = [
+        {
+            name: "send_text",
+            title: isReply ? "Reply With Text" : "Send Text Email",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                required: ["text", "subject"],
+                properties: commonProperties,
+            },
+            canonicalTextAlias: true,
+        },
+    ];
+    if (isReply) {
+        operations.push({
+            name: "reply_text",
+            title: "Reply With Text (Threaded)",
+            inputSchema: {
+                type: "object",
+                additionalProperties: false,
+                required: ["text"],
+                properties: {
+                    ...commonProperties,
+                    replyAll: { type: "boolean" },
+                    inReplyTo: { type: "string", minLength: 1 },
+                },
+            },
+        });
+    }
+    return operations;
+}
+async function invokeEmailDeliveryOperation(handle, operation, input, options) {
+    if (handle.provider !== "email") {
+        throw new Error(`email delivery operation requires an email handle, got ${handle.provider}`);
+    }
+    if (operation !== "send_text" && operation !== "reply_text") {
+        throw new Error(`unknown email delivery operation: ${operation}`);
+    }
+    const isReply = operation === "reply_text" || handle.surface === "message_reply";
+    const text = asString(input.text);
+    if (!text || text.trim().length === 0) {
+        throw new Error(`${operation} requires input.text`);
+    }
+    const config = sourceConfigOrNull(options?.source);
+    const to = asStringArray(input.to) ?? (handle.targetRef ? [handle.targetRef] : []);
+    const cc = asStringArray(input.cc) ?? [];
+    if (to.length === 0 && cc.length === 0) {
+        throw new Error(`${operation} requires at least one recipient in input.to (or input.cc)`);
+    }
+    const subject = resolveEmailSubject(operation, input, isReply);
+    const smtpEndpoint = asString(input.smtpEndpoint) ?? config?.smtpEndpoint ?? null;
+    if (!smtpEndpoint) {
+        throw new Error(`${operation} requires input.smtpEndpoint or source config smtpEndpoint (uxc supports smtp://)`);
+    }
+    const from = asString(input.from) ?? config?.fromAddress ?? addressLikeAccount(config?.account) ?? null;
+    if (!from) {
+        throw new Error(`${operation} requires input.from, source config fromAddress, or an account-like config.account value`);
+    }
+    const uxcAuth = asString(input.uxcAuth) ?? config?.uxcAuth ?? null;
+    const correlationKey = asString(input.correlationKey);
+    const inReplyTo = asString(input.inReplyTo) ?? (isReply ? handle.threadRef ?? null : null);
+    const params = compactRecord({
+        smtp_url: smtpEndpoint,
+        from,
+        to,
+        cc: cc.length > 0 ? cc : undefined,
+        subject,
+        text,
+        in_reply_to: inReplyTo ?? undefined,
+        auth: uxcAuth ?? undefined,
+        message_id: correlationKey ? correlationMessageId(correlationKey) : undefined,
+    });
+    const method = isReply ? "email.reply" : "email.send";
+    if (isReply) {
+        params.reply_handle = compactRecord({
+            message_id: handle.threadRef ?? undefined,
+            account: config?.account ?? undefined,
+            mailbox: config?.mailbox ?? undefined,
+        });
+    }
+    const client = options?.client ?? new RpcEmailUxcClient();
+    let result;
+    try {
+        result = await client.request(method, params);
+    }
+    catch (error) {
+        throw wrapEmailRpcError(error, method);
+    }
+    const note = isReply
+        ? `sent email reply${result.message_id ? ` (message-id ${result.message_id})` : ""}`
+        : `sent email${result.message_id ? ` (message-id ${result.message_id})` : ""}`;
+    return { status: "sent", note };
+}
+function resolveEmailSubject(operation, input, isReply) {
+    const subject = asString(input.subject);
+    if (!isReply) {
+        if (!subject || subject.trim().length === 0) {
+            throw new Error(`${operation} requires input.subject`);
+        }
+        return subject;
+    }
+    const base = subject && subject.trim().length > 0 ? subject.trim() : "your message";
+    if (/^re:/i.test(base)) {
+        return base;
+    }
+    return `Re: ${base}`;
+}
+function correlationMessageId(correlationKey) {
+    const trimmed = correlationKey.trim();
+    if (trimmed.startsWith("<") && trimmed.endsWith(">")) {
+        return trimmed;
+    }
+    const safe = trimmed.replace(/[<>\s]/g, "");
+    return `<agentinbox-${safe}@localhost>`;
+}
+function sourceConfigOrNull(source) {
+    if (!source || source.sourceType !== "email_mailbox") {
+        return null;
+    }
+    try {
+        return parseEmailMailboxSourceConfig(source);
+    }
+    catch {
+        return null;
+    }
+}
+function addressLikeAccount(account) {
+    if (!account) {
+        return null;
+    }
+    return account.includes("@") ? account : null;
+}
+function wrapEmailRpcError(error, method) {
+    if (error && typeof error === "object" && "code" in error) {
+        const code = error.code;
+        if (code === -32601 || code === -32602) {
+            return new Error(`connected uxc daemon does not support ${method} (code ${code}); upgrade uxc to a version with email send/reply RPC support`);
+        }
+    }
+    return error instanceof Error ? error : new Error(String(error));
+}
+class EmailDeliveryAdapter {
+    client;
+    constructor(client) {
+        this.client = client ?? new RpcEmailUxcClient();
+    }
+    async send(request, attempt) {
+        const handle = {
+            provider: attempt.provider,
+            surface: attempt.surface,
+            targetRef: attempt.targetRef,
+            threadRef: attempt.threadRef ?? null,
+            replyMode: attempt.replyMode ?? null,
+        };
+        const result = await invokeEmailDeliveryOperation(handle, "send_text", request.payload, {
+            client: this.client,
+        });
+        return { status: "sent", note: result.note };
+    }
+}
+exports.EmailDeliveryAdapter = EmailDeliveryAdapter;
+function compactRecord(input) {
+    const output = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (value === undefined || value === null) {
+            continue;
+        }
+        if (Array.isArray(value) && value.length === 0) {
+            continue;
+        }
+        output[key] = value;
+    }
+    return output;
+}
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+}
+function asString(value) {
+    return typeof value === "string" ? value : null;
+}
+function asStringArray(value) {
+    if (Array.isArray(value)) {
+        return value
+            .map((item) => stringFromUnknown(item))
+            .filter((item) => Boolean(item && item.trim().length > 0));
+    }
+    if (typeof value === "string") {
+        return value
+            .split(",")
+            .map((item) => item.trim())
+            .filter((item) => item.length > 0);
+    }
+    return null;
+}
+function stringFromUnknown(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return String(value);
+    }
+    if (typeof value === "bigint") {
+        return value.toString();
+    }
+    return null;
+}
+function numberFromUnknown(value) {
+    if (typeof value === "number" && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === "string" && value.trim().length > 0) {
+        const parsed = Number(value);
+        if (Number.isFinite(parsed)) {
+            return parsed;
+        }
+    }
+    return undefined;
+}

package/dist/src/sources/remote.js

@@ -11,6 +11,7 @@ const REMOTE_SOURCE_TYPES = new Set([
     "github_repo_ci",
     "feishu_bot",
     "telegram_bot",
+    "email_mailbox",
 ]);
 const DEFAULT_SYNC_INTERVAL_MS = 2_000;
 const DEFAULT_BACKOFF_BASE_SECS = 2;

package/dist/src/sources/remote_modules.js

@@ -15,9 +15,10 @@ const github_1 = require("./github");
 const github_ci_1 = require("./github_ci");
 const feishu_1 = require("./feishu");
 const telegram_1 = require("./telegram");
+const email_1 = require("./email");
 const REMOTE_USER_MODULE_ROOT_DIR = "source-modules";
-const BUILTIN_MODULE_IDS = new Set(["builtin.github_repo", "builtin.github_repo_ci", "builtin.feishu_bot", "builtin.telegram_bot"]);
-const BUILTIN_REMOTE_SOURCE_TYPES = ["github_repo", "github_repo_ci", "feishu_bot", "telegram_bot"];
+const BUILTIN_MODULE_IDS = new Set(["builtin.github_repo", "builtin.github_repo_ci", "builtin.feishu_bot", "builtin.telegram_bot", "builtin.email_mailbox"]);
+const BUILTIN_REMOTE_SOURCE_TYPES = ["github_repo", "github_repo_ci", "feishu_bot", "telegram_bot", "email_mailbox"];
 class RemoteSourceModuleRegistry {
     moduleCache = new Map();
     githubRepoModule;
@@ -37,6 +38,9 @@ class RemoteSourceModuleRegistry {
         if (source.sourceType === "telegram_bot") {
             return Promise.resolve(TELEGRAM_BOT_MODULE);
         }
+        if (source.sourceType === "email_mailbox") {
+            return Promise.resolve(EMAIL_MAILBOX_MODULE);
+        }
         if (source.sourceType !== "remote_source") {
             throw new Error(`unsupported source type for remote module: ${source.sourceType}`);
         }
@@ -86,6 +90,9 @@ function builtInModuleIdForSourceType(sourceType) {
     if (sourceType === "telegram_bot") {
         return "builtin.telegram_bot";
     }
+    if (sourceType === "email_mailbox") {
+        return "builtin.email_mailbox";
+    }
     return null;
 }
 function builtinRemoteSourceTypes() {
@@ -631,6 +638,73 @@ const TELEGRAM_BOT_MODULE = {
         };
     },
 };
+const EMAIL_MAILBOX_MODULE = {
+    id: "builtin.email_mailbox",
+    listDeliveryOperations(input) {
+        return (0, email_1.emailDeliveryOperationsForHandle)(input.handle);
+    },
+    async invokeDeliveryOperation(input) {
+        return (0, email_1.invokeEmailDeliveryOperation)(input.handle, input.operation, input.input, {
+            source: input.source,
+        });
+    },
+    describeCapabilities() {
+        return {
+            sourceKind: "email_mailbox",
+            aliases: ["email_mailbox", "email"],
+            configSchema: [
+                { name: "provider", type: "string", required: true, description: "Email provider: imap, gmail, graph, or jmap." },
+                { name: "uxcAuth", type: "string", required: true, description: "UXC auth profile name holding mailbox credentials." },
+                { name: "endpoint", type: "string", required: false, description: "imap:// or imaps:// endpoint for imap; provider API endpoint otherwise (required for jmap)." },
+                { name: "account", type: "string", required: false, description: "Account alias; defaults to the auth profile username." },
+                { name: "mailbox", type: "string", required: false, description: "Mailbox to watch; defaults to INBOX." },
+                { name: "pollIntervalSecs", type: "number", required: false, description: "Provider poll interval in seconds (min 15, default 60)." },
+                { name: "smtpEndpoint", type: "string", required: false, description: "Default smtp:// endpoint for outbound delivery." },
+                { name: "fromAddress", type: "string", required: false, description: "Default outbound From address." },
+                { name: "addressAllowlist", type: "string[]", required: false, description: "Optional from/to address allowlist." },
+            ],
+            metadataFields: [
+                { name: "provider", type: "string", description: "Email provider." },
+                { name: "account", type: "string", description: "Mailbox account alias." },
+                { name: "mailbox", type: "string", description: "Mailbox name." },
+                { name: "messageId", type: "string|null", description: "RFC Message-ID when present." },
+                { name: "providerMessageId", type: "string|null", description: "Provider-native message id." },
+                { name: "threadId", type: "string|null", description: "Thread reference from References/In-Reply-To headers." },
+                { name: "from", type: "string|null", description: "Normalized sender address." },
+                { name: "fromName", type: "string|null", description: "Sender display name." },
+                { name: "to", type: "object[]", description: "Normalized recipients." },
+                { name: "cc", type: "object[]", description: "Normalized cc recipients." },
+                { name: "subject", type: "string|null", description: "Message subject." },
+                { name: "textPreview", type: "string|null", description: "Body snippet." },
+                { name: "hasAttachments", type: "boolean", description: "Whether the message carries attachments." },
+                { name: "attachmentCount", type: "number|null", description: "Attachment count; null when provider metadata was not expanded." },
+                { name: "attachments", type: "object[]", description: "Attachment metadata with opaque retrieval handles." },
+            ],
+            eventVariantExamples: ["email.message.received"],
+        };
+    },
+    validateConfig(source) {
+        (0, email_1.parseEmailMailboxSourceConfig)(source);
+    },
+    buildManagedSourceSpec(source) {
+        return (0, email_1.buildEmailMailboxSourceSpec)((0, email_1.parseEmailMailboxSourceConfig)(source));
+    },
+    mapRawEvent(rawPayload, source) {
+        const config = (0, email_1.parseEmailMailboxSourceConfig)(source);
+        const normalized = (0, email_1.normalizeEmailMailboxEvent)(source, config, rawPayload);
+        if (!normalized) {
+            return null;
+        }
+        return {
+            sourceNativeId: normalized.sourceNativeId,
+            eventVariant: normalized.eventVariant,
+            metadata: normalized.metadata ?? {},
+            rawPayload: normalized.rawPayload ?? rawPayload,
+            occurredAt: normalized.occurredAt,
+            deliveryHandle: normalized.deliveryHandle,
+        };
+    },
+};
 function moduleConfigForSource(source) {
     const config = asRecord(source.config);
     if (source.sourceType === "remote_source") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@holon-run/agentinbox",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Local event subscription and delivery service for agents.",
   "license": "Apache-2.0",
   "repository": {