@holon-run/agentinbox 1.7.2 → 1.8.1

package/dist/src/service.js

@@ -11,6 +11,9 @@ const terminal_1 = require("./terminal");
 const runtime_gate_1 = require("./runtime_gate");
 const logging_1 = require("./logging");
 const source_hosts_1 = require("./source_hosts");
+const email_body_1 = require("./email_body");
+const email_attachment_1 = require("./email_attachment");
+const email_attachment_content_1 = require("./email_attachment_content");
 const DEFAULT_SUBSCRIPTION_POLL_LIMIT = 100;
 const DEFAULT_ACTIVATION_WINDOW_MS = 3_000;
 const DEFAULT_ACTIVATION_MAX_ITEMS = 20;
@@ -51,7 +54,9 @@ class AgentInboxService {
     lastAckedInboxGcAt = 0;
     lastLifecycleCleanupAt = 0;
     lastOfflineAgentGcAt = 0;
-    constructor(store, adapters, activationDispatcher = new ActivationDispatcher(), backend, activationPolicy, terminalDispatcher = new terminal_1.TerminalDispatcher(), activationGate, logger = new logging_1.NoopLogger(), gatingPolicy) {
+    emailBodyReader;
+    emailAttachmentContent;
+    constructor(store, adapters, activationDispatcher = new ActivationDispatcher(), backend, activationPolicy, terminalDispatcher = new terminal_1.TerminalDispatcher(), activationGate, logger = new logging_1.NoopLogger(), gatingPolicy, emailBodyUxcClient, emailAttachmentOptions) {
         this.store = store;
         this.adapters = adapters;
         this.activationDispatcher = activationDispatcher;
@@ -62,6 +67,8 @@ class AgentInboxService {
         this.terminalDispatcher = terminalDispatcher;
         this.logger = logger;
         this.activationGate = activationGate ?? new runtime_gate_1.DefaultActivationGate(undefined, undefined, this.logger.child("gate"), gatingPolicy);
+        this.emailBodyReader = new email_body_1.EmailBodyReader(store, emailBodyUxcClient);
+        this.emailAttachmentContent = new email_attachment_content_1.EmailAttachmentContentManager(store, `${store.getDataDirectory()}/attachments`, emailBodyUxcClient, emailAttachmentOptions);
     }
     activationDispatcher;
     terminalDispatcher;
@@ -634,6 +641,7 @@ class AgentInboxService {
         this.getAgent(agentId);
         const affectedSourceIds = Array.from(new Set(this.store.listSubscriptionsForAgent(agentId).map((subscription) => subscription.sourceId)));
         this.store.deleteAgent(agentId);
+        this.emailAttachmentContent.gc();
         for (const sourceId of affectedSourceIds) {
             this.refreshSourceIdleState(sourceId);
         }
@@ -1149,6 +1157,51 @@ class AgentInboxService {
     listInboxItems(agentId, options) {
         return this.store.listInboxEntries(this.ensureInboxForAgent(agentId).inboxId, options);
     }
+    async readInboxEmailBody(agentId, entryId, options) {
+        const inbox = this.store.getInboxByAgentId(agentId);
+        if (!inbox) {
+            throw new Error(`unknown inbox entry: ${entryId}`);
+        }
+        const entry = this.store.getInboxEntryForInbox(inbox.inboxId, entryId);
+        if (!entry) {
+            throw new Error(`unknown inbox entry: ${entryId}`);
+        }
+        if (entry.kind !== "item") {
+            return {
+                status: "unavailable",
+                entryId: entry.entryId,
+                code: "unsupported",
+                retryable: false,
+                message: "Digest entries do not represent one email body.",
+            };
+        }
+        const source = entry.sourceId ? this.store.getSource(entry.sourceId) : null;
+        if (!source) {
+            return {
+                status: "unavailable",
+                entryId: entry.entryId,
+                code: "source_unavailable",
+                retryable: false,
+                message: "The source for this inbox entry is no longer available.",
+            };
+        }
+        return this.emailBodyReader.read(inbox.inboxId, entry, source, options);
+    }
+    getInboxEmailAttachment(agentId, attachmentRef) {
+        return this.emailAttachmentContent.inspect(agentId, attachmentRef);
+    }
+    async materializeInboxEmailAttachment(agentId, attachmentRef) {
+        return this.emailAttachmentContent.materialize(agentId, attachmentRef);
+    }
+    openInboxEmailAttachmentContent(agentId, attachmentRef) {
+        return this.emailAttachmentContent.openContent(agentId, attachmentRef);
+    }
+    deleteInboxEmailAttachmentContent(agentId, attachmentRef) {
+        return this.emailAttachmentContent.delete(agentId, attachmentRef);
+    }
+    projectPublicInboxEntry(value) {
+        return (0, email_attachment_1.projectPublicInboxEntry)(value, (itemId, selector) => this.store.getEmailAttachmentMaterialization(itemId, selector));
+    }
     listRawInboxItems(agentId, options) {
         return this.store.listInboxItems(this.ensureInboxForAgent(agentId).inboxId, options);
     }
@@ -1462,12 +1515,14 @@ class AgentInboxService {
         return {
             deleted: this.store.deleteAckedInboxItems(inbox.inboxId, retentionCutoffIso(this.ackedRetentionMs)),
             retentionMs: this.ackedRetentionMs,
+            attachments: this.emailAttachmentContent.gc(),
         };
     }
     gcAckedInboxItems() {
         return {
             deleted: this.store.deleteAckedInboxItemsGlobal(retentionCutoffIso(this.ackedRetentionMs)),
             retentionMs: this.ackedRetentionMs,
+            attachments: this.emailAttachmentContent.gc(),
         };
     }
     gc() {
@@ -2676,9 +2731,11 @@ class AgentInboxService {
                     items: target.mode === "activation_with_items"
                         ? input.entries
                             .filter((entry) => entry.kind === "item")
-                            .map((entry) => entry.item)
+                            .map((entry) => this.projectPublicInboxEntry(entry.item))
+                        : undefined,
+                    entries: target.mode === "activation_with_items" && input.entries.length > 0
+                        ? input.entries.map((entry) => this.projectPublicInboxEntry(entry))
                         : undefined,
-                    entries: target.mode === "activation_with_items" && input.entries.length > 0 ? input.entries : undefined,
                     createdAt: (0, util_1.nowIso)(),
                     deliveredAt: null,
                 };
@@ -3075,6 +3132,7 @@ class AgentInboxService {
         }
         if (agents.length > 0) {
             this.store.save();
+            this.emailAttachmentContent.gc();
         }
         if (agents.length > 0) {
             this.rescheduleTimerSync();

package/dist/src/source_schema.js

@@ -207,7 +207,8 @@ const SOURCE_SCHEMAS = {
             { 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." },
+            { name: "attachmentsComplete", type: "boolean", description: "Whether the attachment metadata list is known to be complete." },
+            { name: "attachments", type: "object[]", description: "Safe attachment metadata with an opaque attachmentRef; provider retrieval handles and binary content are never exposed." },
         ],
         payloadExamples: [
             {
@@ -236,6 +237,8 @@ const SOURCE_SCHEMAS = {
             { 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: "initialFetchLimit", type: "number", required: false, description: "First-look backfill depth: 0 = new mail only, max 100, default 25." },
+            { name: "method", type: "string", required: false, description: "Provider poll HTTP method: get (default) or post; ignored for imap." },
+            { name: "requestBody", type: "object", required: false, description: "JSON request body for provider polling; requires method=post and is ignored for imap." },
             { 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." },

package/dist/src/sources/email.js

@@ -1,7 +1,8 @@
 "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_MAX_INITIAL_FETCH_LIMIT = exports.EMAIL_MAILBOX_DEFAULT_INITIAL_FETCH_LIMIT = exports.EMAIL_MAILBOX_DEFAULT_POLL_INTERVAL_SECS = exports.EMAIL_DEFAULT_MAILBOX = void 0;
+exports.EmailDeliveryAdapter = exports.RpcEmailUxcClient = exports.GRAPH_MESSAGES_ENDPOINT = exports.GMAIL_MESSAGES_ENDPOINT = exports.EMAIL_EVENT_VERSION = exports.EMAIL_EVENT_TYPE = exports.EMAIL_ATTACHMENT_DEFAULT_RETENTION_SECS = exports.EMAIL_ATTACHMENT_DEFAULT_MAX_MESSAGE_BYTES = exports.EMAIL_ATTACHMENT_DEFAULT_MAX_BYTES = exports.EMAIL_ATTACHMENT_DEFAULT_MAX_COUNT = exports.EMAIL_MAILBOX_MAX_INITIAL_FETCH_LIMIT = exports.EMAIL_MAILBOX_DEFAULT_INITIAL_FETCH_LIMIT = exports.EMAIL_MAILBOX_DEFAULT_POLL_INTERVAL_SECS = exports.EMAIL_DEFAULT_MAILBOX = void 0;
 exports.parseEmailMailboxSourceConfig = parseEmailMailboxSourceConfig;
+exports.parseEmailAttachmentPolicy = parseEmailAttachmentPolicy;
 exports.buildEmailMailboxSourceSpec = buildEmailMailboxSourceSpec;
 exports.normalizeEmailMailboxEvent = normalizeEmailMailboxEvent;
 exports.emailDeliveryOperationsForHandle = emailDeliveryOperationsForHandle;
@@ -11,6 +12,10 @@ exports.EMAIL_DEFAULT_MAILBOX = "INBOX";
 exports.EMAIL_MAILBOX_DEFAULT_POLL_INTERVAL_SECS = 60;
 exports.EMAIL_MAILBOX_DEFAULT_INITIAL_FETCH_LIMIT = 25;
 exports.EMAIL_MAILBOX_MAX_INITIAL_FETCH_LIMIT = 100;
+exports.EMAIL_ATTACHMENT_DEFAULT_MAX_COUNT = 20;
+exports.EMAIL_ATTACHMENT_DEFAULT_MAX_BYTES = 25 * 1024 * 1024;
+exports.EMAIL_ATTACHMENT_DEFAULT_MAX_MESSAGE_BYTES = 50 * 1024 * 1024;
+exports.EMAIL_ATTACHMENT_DEFAULT_RETENTION_SECS = 24 * 60 * 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";
@@ -98,6 +103,26 @@ function parseEmailMailboxSourceConfig(source) {
         throw new Error("email_mailbox config.mailbox must be a non-empty string when provided");
     }
     const addressAllowlist = asStringArray(config.addressAllowlist ?? config.addressAllowList);
+    const attachmentPolicy = parseEmailAttachmentPolicy(config.attachmentPolicy ?? config.attachment_policy);
+    const methodRaw = config.method;
+    let method = "get";
+    if (methodRaw !== undefined && methodRaw !== null) {
+        if (typeof methodRaw !== "string" || !["get", "post"].includes(methodRaw.trim().toLowerCase())) {
+            throw new Error(`email_mailbox config.method must be get or post; got ${String(methodRaw)}`);
+        }
+        method = methodRaw.trim().toLowerCase();
+    }
+    const requestBodyRaw = config.requestBody;
+    let requestBody;
+    if (requestBodyRaw !== undefined && requestBodyRaw !== null) {
+        if (typeof requestBodyRaw !== "object" || Array.isArray(requestBodyRaw)) {
+            throw new Error("email_mailbox config.requestBody must be a JSON object when provided");
+        }
+        if (method !== "post") {
+            throw new Error("email_mailbox config.requestBody requires config.method=post");
+        }
+        requestBody = requestBodyRaw;
+    }
     return {
         provider: provider,
         endpoint,
@@ -106,9 +131,28 @@ function parseEmailMailboxSourceConfig(source) {
         mailbox,
         pollIntervalSecs,
         initialFetchLimit,
+        method,
+        ...(requestBody ? { requestBody } : {}),
         ...(smtpEndpoint ? { smtpEndpoint } : {}),
         ...(fromAddress ? { fromAddress } : {}),
         ...(addressAllowlist && addressAllowlist.length > 0 ? { addressAllowlist } : {}),
+        attachmentPolicy,
+    };
+}
+function parseEmailAttachmentPolicy(value) {
+    const input = asRecord(value);
+    const mode = asString(input.mode) ?? "metadata";
+    if (mode !== "metadata" && mode !== "store_reference") {
+        throw new Error(`email_mailbox config.attachmentPolicy.mode must be metadata or store_reference; got ${mode}`);
+    }
+    return {
+        mode,
+        maxAttachmentsPerMessage: positiveIntegerOrDefault(input.maxAttachmentsPerMessage ?? input.max_attachments_per_message, exports.EMAIL_ATTACHMENT_DEFAULT_MAX_COUNT, "maxAttachmentsPerMessage"),
+        maxBytesPerAttachment: positiveIntegerOrDefault(input.maxBytesPerAttachment ?? input.max_bytes_per_attachment, exports.EMAIL_ATTACHMENT_DEFAULT_MAX_BYTES, "maxBytesPerAttachment"),
+        maxBytesPerMessage: positiveIntegerOrDefault(input.maxBytesPerMessage ?? input.max_bytes_per_message, exports.EMAIL_ATTACHMENT_DEFAULT_MAX_MESSAGE_BYTES, "maxBytesPerMessage"),
+        allowContentTypes: normalizedContentTypes(input.allowContentTypes ?? input.allow_content_types),
+        denyContentTypes: normalizedContentTypes(input.denyContentTypes ?? input.deny_content_types),
+        retentionSecs: positiveIntegerOrDefault(input.retentionSecs ?? input.retention_secs, exports.EMAIL_ATTACHMENT_DEFAULT_RETENTION_SECS, "retentionSecs"),
     };
 }
 function buildEmailMailboxSourceSpec(config) {
@@ -148,7 +192,9 @@ function buildEmailMailboxSourceSpec(config) {
         transport_hint: "email_provider_poll",
         args: {
             provider: config.provider,
+            method: config.method,
             ...args,
+            ...(config.requestBody ? { body: config.requestBody } : {}),
         },
         poll_config: pollConfig,
         options: {
@@ -232,6 +278,7 @@ function normalizeEmailMailboxEvent(source, config, raw) {
     const mailbox = asString(payload.mailbox) ?? config.mailbox;
     const uid = stringFromUnknown(message.uid);
     const messageId = asString(message.message_id) ?? uid;
+    const stableKey = asString(message.stable_key);
     if (!uid && !messageId) {
         return null;
     }
@@ -247,10 +294,18 @@ function normalizeEmailMailboxEvent(source, config, raw) {
         : [];
     const attachmentCountRaw = message.attachment_count;
     const attachmentCount = numberFromUnknown(attachmentCountRaw) ?? null;
+    const hasAttachments = attachments.length > 0
+        || (attachmentCount !== null && attachmentCount > 0)
+        || message.has_attachments === true;
+    const attachmentsComplete = attachmentCount !== null
+        ? attachmentCount === attachments.length
+        : message.has_attachments === false && attachments.length === 0;
     const date = asString(message.date);
     return {
         sourceId: source.sourceId,
-        sourceNativeId: `email:${provider}:${account}:${mailbox}:${uid ?? messageId}`,
+        sourceNativeId: stableKey
+            ? `email:${stableKey}`
+            : `email:${provider}:${account}:${mailbox}:${uid ?? messageId}`,
         eventVariant: "email.message.received",
         occurredAt: occurredAtFromEmailDate(date),
         metadata: {
@@ -267,8 +322,9 @@ function normalizeEmailMailboxEvent(source, config, raw) {
             subject: asString(message.subject),
             textPreview: asString(message.snippet),
             date,
-            hasAttachments: attachments.length > 0 || message.has_attachments === true,
+            hasAttachments,
             attachmentCount,
+            attachmentsComplete,
             attachments,
         },
         rawPayload: payload,
@@ -552,3 +608,16 @@ function numberFromUnknown(value) {
     }
     return undefined;
 }
+function positiveIntegerOrDefault(value, fallback, field) {
+    if (value === undefined || value === null) {
+        return fallback;
+    }
+    const parsed = numberFromUnknown(value);
+    if (parsed === undefined || !Number.isSafeInteger(parsed) || parsed < 1) {
+        throw new Error(`email_mailbox config.attachmentPolicy.${field} must be a positive integer; got ${String(value)}`);
+    }
+    return parsed;
+}
+function normalizedContentTypes(value) {
+    return [...new Set((asStringArray(value) ?? []).map((item) => item.trim().toLowerCase()))];
+}

package/dist/src/sources/remote_modules.js

@@ -680,7 +680,8 @@ const EMAIL_MAILBOX_MODULE = {
                 { 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." },
+                { name: "attachmentsComplete", type: "boolean", description: "Whether the attachment metadata list is known to be complete." },
+                { name: "attachments", type: "object[]", description: "Safe attachment metadata with an opaque attachmentRef; provider retrieval handles are not exposed." },
             ],
             eventVariantExamples: ["email.message.received"],
         };