@holon-run/agentinbox 1.7.1 → 1.8.0

package/dist/src/email_body.js

@@ -0,0 +1,392 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EmailBodyReader = exports.EMAIL_BODY_MAX_BYTES = exports.EMAIL_BODY_DEFAULT_MAX_BYTES = void 0;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const uxc_daemon_client_1 = require("@holon-run/uxc-daemon-client");
+const email_attachment_1 = require("./email_attachment");
+const util_1 = require("./util");
+exports.EMAIL_BODY_DEFAULT_MAX_BYTES = 32 * 1024;
+exports.EMAIL_BODY_MAX_BYTES = 1024 * 1024;
+const EMAIL_BODY_CACHE_MAX_BYTES = 128 * 1024 * 1024;
+const EMAIL_BODY_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const EMAIL_BODY_SCHEMA_VERSION = 1;
+class EmailBodyReader {
+    store;
+    uxc;
+    inFlight = new Map();
+    cursorSecret = node_crypto_1.default.randomBytes(32);
+    constructor(store, uxc = new uxc_daemon_client_1.UxcDaemonClient({ env: process.env })) {
+        this.store = store;
+        this.uxc = uxc;
+    }
+    async read(inboxId, entry, source, options = {}) {
+        const maxBytes = options.maxBytes ?? exports.EMAIL_BODY_DEFAULT_MAX_BYTES;
+        if (!Number.isSafeInteger(maxBytes) || maxBytes < 1 || maxBytes > exports.EMAIL_BODY_MAX_BYTES) {
+            throw new Error(`email body max_bytes must be an integer between 1 and ${exports.EMAIL_BODY_MAX_BYTES}`);
+        }
+        if (source.sourceType !== "email_mailbox" || entry.eventVariant !== "email.message.received") {
+            return unavailable(entry.entryId, "unsupported", false, "This inbox entry is not a supported email message.");
+        }
+        const contentVersion = emailBodyContentVersion(entry);
+        const cursor = options.cursor
+            ? decodeCursor(options.cursor, inboxId, entry.entryId, this.cursorSecret)
+            : null;
+        if (cursor) {
+            const cached = this.store.getEmailBodyCache(inboxId, entry.entryId);
+            if (!cached ||
+                cached.contentVersion !== contentVersion ||
+                cached.expiresAt <= (0, util_1.nowIso)()) {
+                throw new Error("email body cursor is invalid or expired");
+            }
+            const snapshot = snapshotFromCache(cached);
+            if (snapshotVersion(snapshot) !== cursor.snapshotVersion) {
+                throw new Error("email body cursor is invalid or expired");
+            }
+            this.store.touchEmailBodyCache(entry.entryId, (0, util_1.nowIso)());
+            const attachments = (0, email_attachment_1.publicEmailAttachmentCollection)(entry.itemId, entry.metadata, (itemId, selector) => this.store.getEmailAttachmentMaterialization(itemId, selector));
+            return {
+                status: "available",
+                entryId: entry.entryId,
+                subject: optionalString(entry.metadata?.subject),
+                from: optionalString(entry.metadata?.from),
+                ...attachments,
+                body: pageSnapshot(snapshot, maxBytes, cursor.offset, inboxId, entry.entryId, this.cursorSecret),
+            };
+        }
+        const snapshot = await this.resolveSnapshot(inboxId, entry, source, contentVersion, options.fetch !== false);
+        if ("status" in snapshot) {
+            return snapshot;
+        }
+        const attachments = (0, email_attachment_1.publicEmailAttachmentCollection)(entry.itemId, entry.metadata, (itemId, selector) => this.store.getEmailAttachmentMaterialization(itemId, selector));
+        return {
+            status: "available",
+            entryId: entry.entryId,
+            subject: optionalString(entry.metadata?.subject),
+            from: optionalString(entry.metadata?.from),
+            ...attachments,
+            body: pageSnapshot(snapshot, maxBytes, 0, inboxId, entry.entryId, this.cursorSecret),
+        };
+    }
+    async resolveSnapshot(inboxId, entry, source, contentVersion, allowFetch) {
+        const now = (0, util_1.nowIso)();
+        const cached = this.store.getEmailBodyCache(inboxId, entry.entryId);
+        if (cached &&
+            cached.contentVersion === contentVersion &&
+            cached.expiresAt > now &&
+            (cached.completeness === "complete" || !allowFetch)) {
+            this.store.touchEmailBodyCache(entry.entryId, now);
+            return snapshotFromCache(cached);
+        }
+        const key = `${inboxId}:${entry.entryId}:${contentVersion}:${allowFetch ? "fetch" : "local"}`;
+        const existing = this.inFlight.get(key);
+        if (existing) {
+            return existing;
+        }
+        const pending = this.loadSnapshot(inboxId, entry, source, contentVersion, allowFetch, cached)
+            .finally(() => {
+            this.inFlight.delete(key);
+        });
+        this.inFlight.set(key, pending);
+        return pending;
+    }
+    async loadSnapshot(inboxId, entry, source, contentVersion, allowFetch, cached) {
+        const payload = entry.rawPayload ?? {};
+        const local = await this.readLocal(payload);
+        if (local?.completeness === "complete") {
+            return this.cacheSnapshot(inboxId, entry, contentVersion, local, "local");
+        }
+        const messageRef = optionalString(payload.message_ref);
+        if (allowFetch && messageRef) {
+            const fetched = await this.callUxc({ kind: "message_ref", messageRef });
+            if (!isUnavailable(fetched)) {
+                return this.cacheSnapshot(inboxId, entry, contentVersion, fetched, "fetched");
+            }
+            if (local) {
+                return this.cacheSnapshot(inboxId, entry, contentVersion, {
+                    ...local,
+                    reasons: uniqueStrings([...local.reasons, `fetch_${fetched.code}`]),
+                }, "local");
+            }
+            if (cached &&
+                cached.contentVersion === contentVersion &&
+                cached.expiresAt > (0, util_1.nowIso)()) {
+                return snapshotFromCache(cached);
+            }
+            return { ...fetched, entryId: entry.entryId };
+        }
+        if (local) {
+            return this.cacheSnapshot(inboxId, entry, contentVersion, local, "local");
+        }
+        if (cached && cached.contentVersion === contentVersion && cached.expiresAt > (0, util_1.nowIso)()) {
+            return snapshotFromCache(cached);
+        }
+        return {
+            status: "unavailable",
+            entryId: entry.entryId,
+            code: allowFetch ? (messageRef ? "provider_unavailable" : "identity_missing") : "local_body_unavailable",
+            retryable: allowFetch && Boolean(messageRef),
+            message: allowFetch
+                ? "No readable email body is available for this entry."
+                : "No local email body is available; retry without --no-fetch.",
+        };
+    }
+    async readLocal(payload) {
+        const embedded = bodyResultFromUnknown(payload.body);
+        if (embedded) {
+            return { ...embedded, contentVersion: "", origin: "local" };
+        }
+        const raw = objectValue(payload.raw);
+        const mimeBase64 = optionalString(raw.mime_inline_base64);
+        const originalBytes = optionalInteger(raw.original_bytes);
+        if (mimeBase64 && originalBytes != null) {
+            const result = await this.callUxc({
+                kind: "inline_mime",
+                mimeBase64,
+                originalBytes,
+                complete: raw.complete === true,
+            });
+            return isUnavailable(result) ? null : result;
+        }
+        const mimeText = optionalString(raw.mime_inline);
+        if (mimeText != null) {
+            const result = await this.callUxc({
+                kind: "legacy_mime",
+                mimeText,
+                sourceTruncated: raw.mime_truncated === true,
+            });
+            return isUnavailable(result) ? null : result;
+        }
+        return null;
+    }
+    async callUxc(input) {
+        try {
+            const status = objectValue(await this.uxc.request("daemon.status"));
+            const capability = objectValue(status.email_body);
+            const inputKinds = Array.isArray(capability.input_kinds) ? capability.input_kinds : [];
+            if (capability.schema_version !== EMAIL_BODY_SCHEMA_VERSION ||
+                !inputKinds.includes(input.kind)) {
+                return unavailable("", "capability_unavailable", false, "The installed UXC daemon does not support this email body input.");
+            }
+            const result = await this.uxc.request("email.body.read", {
+                input: emailBodyInputParams(input),
+            });
+            const parsed = bodyResultFromUnknown(result);
+            if (!parsed) {
+                return unavailable("", "parse_failed", false, "UXC returned an invalid email body result.");
+            }
+            return { ...parsed, contentVersion: "", origin: input.kind === "message_ref" ? "fetched" : "local" };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const timeout = /timed out|timeout/i.test(message);
+            return unavailable("", timeout ? "timeout" : "provider_unavailable", true, timeout ? "Email body retrieval timed out." : "Email body retrieval is temporarily unavailable.");
+        }
+    }
+    cacheSnapshot(inboxId, entry, contentVersion, snapshot, origin) {
+        if (!this.store.getInboxEntryForInbox(inboxId, entry.entryId)) {
+            return unavailable(entry.entryId, "not_found", false, "The inbox entry is no longer available.");
+        }
+        const now = (0, util_1.nowIso)();
+        const normalized = { ...snapshot, contentVersion, origin };
+        this.store.putEmailBodyCache({
+            entryId: entry.entryId,
+            inboxId,
+            itemId: entry.itemId,
+            sourceId: entry.sourceId,
+            contentVersion,
+            schemaVersion: snapshot.schemaVersion,
+            parserVersion: snapshot.parserVersion,
+            text: snapshot.text,
+            bytes: snapshot.bytes,
+            completeness: snapshot.completeness,
+            reasons: snapshot.reasons,
+            createdAt: now,
+            expiresAt: new Date(Date.parse(now) + EMAIL_BODY_CACHE_TTL_MS).toISOString(),
+            lastAccessedAt: now,
+        }, EMAIL_BODY_CACHE_MAX_BYTES);
+        return normalized;
+    }
+}
+exports.EmailBodyReader = EmailBodyReader;
+function bodyResultFromUnknown(value) {
+    const result = objectValue(value);
+    const completeness = result.completeness;
+    if (result.schema_version !== EMAIL_BODY_SCHEMA_VERSION ||
+        typeof result.parser_version !== "string" ||
+        result.format !== "text" ||
+        typeof result.text !== "string" ||
+        !Number.isSafeInteger(result.bytes) ||
+        (completeness !== "complete" && completeness !== "partial" && completeness !== "unverified") ||
+        !Array.isArray(result.reasons)) {
+        return null;
+    }
+    const actualBytes = Buffer.byteLength(result.text, "utf8");
+    if (actualBytes !== result.bytes || actualBytes > exports.EMAIL_BODY_MAX_BYTES) {
+        return null;
+    }
+    return {
+        schemaVersion: EMAIL_BODY_SCHEMA_VERSION,
+        parserVersion: result.parser_version,
+        text: result.text,
+        bytes: actualBytes,
+        completeness,
+        reasons: result.reasons.filter((reason) => typeof reason === "string"),
+    };
+}
+function snapshotFromCache(cache) {
+    return {
+        contentVersion: cache.contentVersion,
+        schemaVersion: cache.schemaVersion,
+        parserVersion: cache.parserVersion,
+        text: cache.text,
+        bytes: cache.bytes,
+        completeness: cache.completeness,
+        reasons: cache.reasons,
+        origin: "cache",
+    };
+}
+function pageSnapshot(snapshot, maxBytes, offset, inboxId, entryId, cursorSecret) {
+    const full = Buffer.from(snapshot.text, "utf8");
+    if (!Number.isSafeInteger(offset) || offset < 0 || offset > full.length || !isUtf8Boundary(full, offset)) {
+        throw new Error("email body cursor is invalid or expired");
+    }
+    let end = Math.min(full.length, offset + maxBytes);
+    while (end > offset && !isUtf8Boundary(full, end)) {
+        end -= 1;
+    }
+    if (end === offset && offset < full.length) {
+        let next = offset + 1;
+        while (next < full.length && !isUtf8Boundary(full, next)) {
+            next += 1;
+        }
+        throw new Error(`email body max_bytes is too small; at least ${next - offset} bytes are required for the next character`);
+    }
+    const hasMore = end < full.length;
+    const nextCursor = hasMore
+        ? encodeCursor({
+            v: 1,
+            inboxId,
+            entryId,
+            snapshotVersion: snapshotVersion(snapshot),
+            offset: end,
+        }, cursorSecret)
+        : undefined;
+    return {
+        format: "text",
+        text: full.subarray(offset, end).toString("utf8"),
+        returnedBytes: end - offset,
+        completeness: snapshot.completeness,
+        reasons: snapshot.reasons,
+        hasMore,
+        ...(nextCursor ? { nextCursor } : {}),
+        truncated: hasMore || snapshot.completeness !== "complete",
+        ...(snapshot.completeness === "complete" ? { totalBytes: snapshot.bytes } : {}),
+        origin: snapshot.origin,
+    };
+}
+function emailBodyContentVersion(entry) {
+    const payload = entry.rawPayload ?? {};
+    const raw = objectValue(payload.raw);
+    const message = objectValue(payload.message);
+    return node_crypto_1.default.createHash("sha256").update(JSON.stringify({
+        itemId: entry.itemId,
+        stableKey: message.stable_key ?? null,
+        messageRef: payload.message_ref ?? null,
+        body: payload.body ?? null,
+        rawRepresentation: raw.representation_version ?? null,
+        rawOriginalBytes: raw.original_bytes ?? raw.size_bytes ?? null,
+        rawComplete: raw.complete ?? null,
+        mimeBase64: raw.mime_inline_base64 ?? null,
+        legacyMime: raw.mime_inline ?? null,
+        legacyTruncated: raw.mime_truncated ?? null,
+    })).digest("base64url");
+}
+function encodeCursor(cursor, cursorSecret) {
+    const payload = Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+    return `${payload}.${signCursor(payload, cursorSecret)}`;
+}
+function decodeCursor(token, inboxId, entryId, cursorSecret) {
+    try {
+        const [payload, signature, extra] = token.split(".");
+        if (!payload || !signature || extra || !validCursorSignature(payload, signature, cursorSecret)) {
+            throw new Error("invalid");
+        }
+        const value = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+        if (value.v !== 1 ||
+            value.inboxId !== inboxId ||
+            value.entryId !== entryId ||
+            typeof value.snapshotVersion !== "string" ||
+            !Number.isSafeInteger(value.offset) ||
+            value.offset < 0) {
+            throw new Error("invalid");
+        }
+        return value;
+    }
+    catch {
+        throw new Error("email body cursor is invalid or expired");
+    }
+}
+function signCursor(payload, cursorSecret) {
+    return node_crypto_1.default.createHmac("sha256", cursorSecret).update(payload).digest("base64url");
+}
+function validCursorSignature(payload, signature, cursorSecret) {
+    const expected = Buffer.from(signCursor(payload, cursorSecret), "base64url");
+    const actual = Buffer.from(signature, "base64url");
+    return actual.length === expected.length && node_crypto_1.default.timingSafeEqual(actual, expected);
+}
+function snapshotVersion(snapshot) {
+    return node_crypto_1.default.createHash("sha256").update(JSON.stringify({
+        parserVersion: snapshot.parserVersion,
+        text: snapshot.text,
+        completeness: snapshot.completeness,
+        reasons: snapshot.reasons,
+    })).digest("base64url");
+}
+function emailBodyInputParams(input) {
+    switch (input.kind) {
+        case "inline_mime":
+            return {
+                kind: input.kind,
+                mime_base64: input.mimeBase64,
+                original_bytes: input.originalBytes,
+                complete: input.complete,
+            };
+        case "legacy_mime":
+            return {
+                kind: input.kind,
+                mime_text: input.mimeText,
+                ...(input.sourceTruncated === undefined ? {} : { source_truncated: input.sourceTruncated }),
+            };
+        case "message_ref":
+            return {
+                kind: input.kind,
+                message_ref: input.messageRef,
+            };
+    }
+}
+function isUnavailable(value) {
+    return "status" in value && value.status === "unavailable";
+}
+function isUtf8Boundary(buffer, offset) {
+    return offset === 0 || offset === buffer.length || (buffer[offset] & 0b1100_0000) !== 0b1000_0000;
+}
+function unavailable(entryId, code, retryable, message) {
+    return { status: "unavailable", entryId, code, retryable, message };
+}
+function objectValue(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function optionalString(value) {
+    return typeof value === "string" ? value : null;
+}
+function optionalInteger(value) {
+    return Number.isSafeInteger(value) && Number(value) >= 0 ? Number(value) : null;
+}
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}

package/dist/src/http.js

@@ -1640,9 +1640,130 @@ function buildFastifyServer(service) {
                 afterEntryId: query.after_entry_id,
                 includeAcked: query.include_acked ? query.include_acked === "true" : undefined,
                 limit: parseOptionalPositiveInteger(query.limit),
-            }),
+            }).map((entry) => service.projectPublicInboxEntry(entry)),
         };
     });
+    app.get("/agents/:agentId/inbox/attachments/:attachmentRef", {
+        schema: {
+            tags: ["inbox"],
+            params: {
+                type: "object",
+                required: ["agentId", "attachmentRef"],
+                properties: {
+                    agentId: { type: "string", minLength: 1 },
+                    attachmentRef: { type: "string", minLength: 1 },
+                },
+            },
+            response: {
+                200: jsonObjectSchema,
+                404: errorResponseSchema,
+            },
+        },
+    }, async (request) => {
+        const params = request.params;
+        return service.getInboxEmailAttachment(decodeURIComponent(params.agentId), decodeURIComponent(params.attachmentRef));
+    });
+    app.post("/agents/:agentId/inbox/attachments/:attachmentRef/materialize", {
+        schema: {
+            tags: ["inbox"],
+            params: {
+                type: "object",
+                required: ["agentId", "attachmentRef"],
+                properties: {
+                    agentId: { type: "string", minLength: 1 },
+                    attachmentRef: { type: "string", minLength: 1 },
+                },
+            },
+            response: {
+                200: jsonObjectSchema,
+                400: errorResponseSchema,
+                404: errorResponseSchema,
+            },
+        },
+    }, async (request) => {
+        const params = request.params;
+        return service.materializeInboxEmailAttachment(decodeURIComponent(params.agentId), decodeURIComponent(params.attachmentRef));
+    });
+    app.get("/agents/:agentId/inbox/attachments/:attachmentRef/content", {
+        schema: {
+            tags: ["inbox"],
+            params: {
+                type: "object",
+                required: ["agentId", "attachmentRef"],
+                properties: {
+                    agentId: { type: "string", minLength: 1 },
+                    attachmentRef: { type: "string", minLength: 1 },
+                },
+            },
+            response: {
+                404: errorResponseSchema,
+            },
+        },
+    }, async (request, reply) => {
+        const params = request.params;
+        const content = service.openInboxEmailAttachmentContent(decodeURIComponent(params.agentId), decodeURIComponent(params.attachmentRef));
+        return reply
+            .type(content.contentType)
+            .header("content-length", String(content.size))
+            .header("content-disposition", attachmentContentDisposition(content.attachment.filename))
+            .header("cache-control", "private, no-store")
+            .send(content.stream);
+    });
+    app.delete("/agents/:agentId/inbox/attachments/:attachmentRef/content", {
+        schema: {
+            tags: ["inbox"],
+            params: {
+                type: "object",
+                required: ["agentId", "attachmentRef"],
+                properties: {
+                    agentId: { type: "string", minLength: 1 },
+                    attachmentRef: { type: "string", minLength: 1 },
+                },
+            },
+            response: {
+                200: jsonObjectSchema,
+                404: errorResponseSchema,
+            },
+        },
+    }, async (request) => {
+        const params = request.params;
+        return service.deleteInboxEmailAttachmentContent(decodeURIComponent(params.agentId), decodeURIComponent(params.attachmentRef));
+    });
+    app.get("/agents/:agentId/inbox/entries/:entryId/body", {
+        schema: {
+            tags: ["inbox"],
+            params: {
+                type: "object",
+                required: ["agentId", "entryId"],
+                properties: {
+                    agentId: { type: "string", minLength: 1 },
+                    entryId: { type: "string", minLength: 1 },
+                },
+            },
+            querystring: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    max_bytes: { type: "string", pattern: "^[1-9][0-9]*$" },
+                    fetch: { type: "string", enum: ["true", "false"] },
+                    cursor: { type: "string", minLength: 1 },
+                },
+            },
+            response: {
+                200: jsonObjectSchema,
+                400: errorResponseSchema,
+                404: errorResponseSchema,
+            },
+        },
+    }, async (request) => {
+        const params = request.params;
+        const query = request.query;
+        return service.readInboxEmailBody(decodeURIComponent(params.agentId), decodeURIComponent(params.entryId), {
+            maxBytes: parseOptionalPositiveInteger(query.max_bytes),
+            fetch: query.fetch ? query.fetch === "true" : undefined,
+            cursor: query.cursor,
+        });
+    });
     app.post("/agents/:agentId/inbox/items", {
         schema: {
             tags: ["inbox"],
@@ -1716,12 +1837,14 @@ function buildFastifyServer(service) {
             connection: "keep-alive",
         });
         const session = service.watchInbox(agentId, watchOptions, (event) => {
-            sendSse(raw, event.event, event);
+            sendSse(raw, event.event, event.event === "items"
+                ? { ...event, entries: event.entries.map((entry) => service.projectPublicInboxEntry(entry)) }
+                : event);
         });
         sendSse(raw, "items", {
             event: "items",
             agentId,
-            entries: session.initialItems,
+            entries: session.initialItems.map((entry) => service.projectPublicInboxEntry(entry)),
         });
         session.start();
         const heartbeatMs = watchOptions.heartbeatMs ?? 15_000;
@@ -2018,6 +2141,14 @@ function buildFastifyServer(service) {
             void reply.code(403).send({ error: message });
             return;
         }
+        const statusCode = error.statusCode;
+        if (typeof statusCode === "number"
+            && Number.isInteger(statusCode)
+            && statusCode >= 400
+            && statusCode < 600) {
+            void reply.code(statusCode).send({ error: message });
+            return;
+        }
         if (isBadRequestError(message)) {
             void reply.code(400).send({ error: message });
             return;
@@ -2065,6 +2196,18 @@ function optionalString(value) {
     const trimmed = value.trim();
     return trimmed.length > 0 ? trimmed : undefined;
 }
+function attachmentContentDisposition(filename) {
+    if (!filename) {
+        return "attachment";
+    }
+    const sanitized = filename.replace(/[\r\n]/g, "").trim();
+    if (!sanitized) {
+        return "attachment";
+    }
+    const encoded = encodeURIComponent(sanitized)
+        .replace(/['()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+    return `attachment; filename*=UTF-8''${encoded}`;
+}
 function assertDeliveryRouteAuthorized(service, routeId, authorization) {
     const binding = service.getOperatorBindingForReplyRoute(routeId);
     const deliveryAuth = binding?.deliveryAuth;
@@ -2155,6 +2298,7 @@ function isBadRequestError(message) {
         message.startsWith("expected boolean") ||
         message.startsWith("expected integer") ||
         message.startsWith("expected positive integer") ||
+        message.startsWith("email body ") ||
         message.startsWith("webhook agent registration requires") ||
         message.startsWith("agent registration requires either") ||
         message.startsWith("notifyLeaseMs must be a positive integer") ||