humanish 0.104.3 → 0.106.0

package/dist/comms/agentmail.js

@@ -0,0 +1,568 @@
+import { inlineImageData, MAX_INLINE_IMAGE_BYTES, MAX_INLINE_IMAGES_BYTES, MAX_INLINE_IMAGES, } from "./images.js";
+import { RECEIVING_SCOPE_UNSUPPORTED, } from "./receiving-types.js";
+const API_ORIGIN = "https://api.agentmail.to";
+const DOWNLOAD_ORIGIN = "https://cdn.agentmail.to";
+/** Bounds apply to a whole operation, including every page, message and download. */
+export const AGENTMAIL_RECEIVING_LIMITS = Object.freeze({
+    timeoutMs: 30_000,
+    maxTimeoutMs: 60_000,
+    pages: 4,
+    pageSize: 25,
+    messages: 100,
+    requests: 160,
+    operationBytes: 12 * 1024 * 1024,
+    responseBytes: 2 * 1024 * 1024,
+    textBytes: 256 * 1024,
+    downloadRedirects: 2,
+});
+const ERROR_CODES = [
+    "agentmail_auth_rejected",
+    "agentmail_rate_limited",
+    "agentmail_unavailable",
+    "agentmail_timeout",
+    "agentmail_cancelled",
+    "agentmail_invalid_response",
+    "agentmail_ownership_mismatch",
+    "agentmail_not_found",
+    "agentmail_resource_deleting",
+    "agentmail_download_blocked",
+    "agentmail_size_limit",
+    "agentmail_invalid_input",
+    "agentmail_request_limit",
+    RECEIVING_SCOPE_UNSUPPORTED,
+];
+/** Every code the adapter reports: its error codes plus message and batch limitations. */
+export const AGENTMAIL_RECEIVING_CODES = new Set([
+    ...ERROR_CODES,
+    "agentmail_content_truncated",
+    "agentmail_content_missing",
+    "agentmail_timestamp_missing",
+    "agentmail_attachment_limit",
+    "agentmail_attachment_unsupported",
+    "agentmail_attachment_unavailable",
+    "agentmail_message_unavailable",
+    "agentmail_pagination_stalled",
+    "agentmail_page_limit",
+]);
+/** Safe for callers to report. Never retains the response body, URL, key or caught cause. */
+export class AgentMailReceivingError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+        this.name = "AgentMailReceivingError";
+    }
+}
+function fail(code) {
+    throw new AgentMailReceivingError(code);
+}
+function safeCode(error) {
+    return error instanceof AgentMailReceivingError ? error.code : "agentmail_unavailable";
+}
+function object(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        fail("agentmail_invalid_response");
+    return value;
+}
+function identifier(value) {
+    if (typeof value !== "string" ||
+        !value.length ||
+        value.length > 1024 ||
+        /[\u0000-\u0020\u007f]/.test(value))
+        fail("agentmail_invalid_response");
+    return value;
+}
+function inputId(value) {
+    try {
+        return identifier(value);
+    }
+    catch {
+        return fail("agentmail_invalid_input");
+    }
+}
+function checkLease(lease) {
+    inputId(lease.resourceId);
+    inputId(lease.address);
+    inputId(lease.clientId);
+}
+const inboxPath = (lease) => `/v0/inboxes/${encodeURIComponent(lease.resourceId)}`;
+const messagePath = (lease, id) => `${inboxPath(lease)}/messages/${encodeURIComponent(id)}`;
+function abortCode(budget) {
+    return budget.cancelled() ? "agentmail_cancelled" : "agentmail_timeout";
+}
+function checkAbort(budget) {
+    if (budget.signal.aborted)
+        fail(abortCode(budget));
+}
+function unlessAborted(promise, budget) {
+    if (budget.signal.aborted)
+        return Promise.reject(new AgentMailReceivingError(abortCode(budget)));
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(new AgentMailReceivingError(abortCode(budget)));
+        budget.signal.addEventListener("abort", onAbort, { once: true });
+        promise
+            .then(resolve, reject)
+            .finally(() => budget.signal.removeEventListener("abort", onAbort))
+            .catch(() => { });
+    });
+}
+async function operation(context, action) {
+    const timeout = context?.timeoutMs ?? AGENTMAIL_RECEIVING_LIMITS.timeoutMs;
+    if (!Number.isFinite(timeout) || timeout <= 0)
+        fail("agentmail_invalid_input");
+    const controller = new AbortController();
+    const onAbort = () => controller.abort();
+    const timer = setTimeout(onAbort, Math.min(timeout, AGENTMAIL_RECEIVING_LIMITS.maxTimeoutMs));
+    const budget = {
+        signal: controller.signal,
+        bytes: 0,
+        requests: 0,
+        cancelled: () => context?.signal?.aborted === true,
+    };
+    context?.signal?.addEventListener("abort", onAbort, { once: true });
+    if (context?.signal?.aborted)
+        controller.abort();
+    try {
+        checkAbort(budget);
+        return await action(budget);
+    }
+    catch (error) {
+        throw new AgentMailReceivingError(safeCode(error));
+    }
+    finally {
+        clearTimeout(timer);
+        context?.signal?.removeEventListener("abort", onAbort);
+        controller.abort();
+    }
+}
+async function bodyBytes(response, budget, maximum) {
+    checkAbort(budget);
+    const length = response.headers.get("content-length");
+    if (length && /^\d+$/.test(length) && Number(length) > maximum) {
+        void response.body?.cancel().catch(() => { });
+        fail("agentmail_size_limit");
+    }
+    if (!response.body)
+        return Buffer.alloc(0);
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        while (true) {
+            const result = await unlessAborted(reader.read(), budget);
+            if (result.done)
+                break;
+            size += result.value.byteLength;
+            budget.bytes += result.value.byteLength;
+            if (size > maximum || budget.bytes > AGENTMAIL_RECEIVING_LIMITS.operationBytes)
+                fail("agentmail_size_limit");
+            chunks.push(result.value);
+        }
+        return Buffer.concat(chunks, size);
+    }
+    finally {
+        void reader.cancel().catch(() => { });
+    }
+}
+function statusError(reply) {
+    if ([401, 403].includes(reply.status))
+        fail("agentmail_auth_rejected");
+    if (reply.status === 429)
+        fail("agentmail_rate_limited");
+    if (reply.status === 404 && object(reply.body).code === "not_found")
+        fail("agentmail_not_found");
+    if (reply.status === 409 && object(reply.body).code === "resource_deleting")
+        fail("agentmail_resource_deleting");
+    if (reply.status >= 500 || reply.status === 408)
+        fail("agentmail_unavailable");
+    fail("agentmail_invalid_response");
+}
+function success(reply) {
+    if (reply.status < 200 || reply.status >= 300)
+        statusError(reply);
+    return object(reply.body);
+}
+function absentOrDeleting(reply) {
+    if (reply.status === 404 && object(reply.body).code === "not_found")
+        return "absent";
+    if (reply.status === 409 && object(reply.body).code === "resource_deleting")
+        return "deleting";
+    return undefined;
+}
+function assertOwnership(raw, lease) {
+    if (raw.inbox_id !== lease.resourceId ||
+        raw.client_id !== lease.clientId ||
+        raw.email !== lease.address)
+        fail("agentmail_ownership_mismatch");
+}
+function limitedText(value, limitations) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string")
+        fail("agentmail_invalid_response");
+    if (Buffer.byteLength(value) <= AGENTMAIL_RECEIVING_LIMITS.textBytes)
+        return value;
+    limitations.push("agentmail_content_truncated");
+    // Leave no partial UTF-8 sequence at the boundary.
+    return Buffer.from(value)
+        .subarray(0, AGENTMAIL_RECEIVING_LIMITS.textBytes)
+        .toString("utf8")
+        .replace(/\ufffd$/, "");
+}
+const transient = (code) => code === "agentmail_unavailable" || code === "agentmail_timeout";
+/** The operation has no time, bytes or requests left for another item. */
+const exhausted = (budget) => budget.signal.aborted ||
+    budget.bytes >= AGENTMAIL_RECEIVING_LIMITS.operationBytes ||
+    budget.requests >= AGENTMAIL_RECEIVING_LIMITS.requests;
+async function request(receiver, url, init, budget) {
+    checkAbort(budget);
+    if (++budget.requests > AGENTMAIL_RECEIVING_LIMITS.requests)
+        fail("agentmail_request_limit");
+    try {
+        return await unlessAborted(receiver
+            .fetch(url, { ...init, signal: budget.signal, credentials: "omit" })
+            .then((response) => {
+            if (budget.signal.aborted) {
+                void response.body?.cancel().catch(() => { });
+                fail(abortCode(budget));
+            }
+            return response;
+        }), budget);
+    }
+    catch (error) {
+        if (budget.signal.aborted)
+            fail(abortCode(budget));
+        throw new AgentMailReceivingError(safeCode(error));
+    }
+}
+/** The only request that carries the management credential, always to the API origin. */
+async function api(receiver, path, method, budget, payload) {
+    const response = await request(receiver, `${API_ORIGIN}${path}`, {
+        method,
+        redirect: "error",
+        headers: {
+            Authorization: `Bearer ${receiver.key}`,
+            Accept: "application/json",
+            ...(payload === undefined ? {} : { "Content-Type": "application/json" }),
+        },
+        ...(payload === undefined ? {} : { body: JSON.stringify(payload) }),
+    }, budget);
+    const bytes = await bodyBytes(response, budget, AGENTMAIL_RECEIVING_LIMITS.responseBytes);
+    let body = null;
+    if (bytes.length) {
+        try {
+            body = JSON.parse(bytes.toString("utf8"));
+        }
+        catch {
+            if (response.ok)
+                fail("agentmail_invalid_response");
+        }
+    }
+    return { status: response.status, body };
+}
+async function download(receiver, rawUrl, budget) {
+    if (typeof rawUrl !== "string" || rawUrl.length > 16_384)
+        fail("agentmail_download_blocked");
+    let url;
+    try {
+        url = new URL(rawUrl);
+    }
+    catch {
+        return fail("agentmail_download_blocked");
+    }
+    for (let redirect = 0; redirect <= AGENTMAIL_RECEIVING_LIMITS.downloadRedirects; redirect++) {
+        // Exact origin established by live capture. No inferred S3 wildcard and no email-body fetches.
+        if (url.origin !== DOWNLOAD_ORIGIN || url.username || url.password || url.hash)
+            fail("agentmail_download_blocked");
+        const response = await request(receiver, url.href, { method: "GET", redirect: "manual" }, budget);
+        if ([301, 302, 303, 307, 308].includes(response.status)) {
+            void response.body?.cancel().catch(() => { });
+            const next = response.headers.get("location");
+            if (!next || redirect === AGENTMAIL_RECEIVING_LIMITS.downloadRedirects)
+                fail("agentmail_download_blocked");
+            try {
+                url = new URL(next, url);
+            }
+            catch {
+                return fail("agentmail_download_blocked");
+            }
+            continue;
+        }
+        if (!response.ok) {
+            void response.body?.cancel().catch(() => { });
+            fail("agentmail_unavailable");
+        }
+        return bodyBytes(response, budget, MAX_INLINE_IMAGE_BYTES);
+    }
+    return fail("agentmail_download_blocked");
+}
+/**
+ * A received message's text fields and timestamp, with no inline images yet. Its `limitations`
+ * array is the working list the caller keeps adding to.
+ */
+function parseMessage(raw, lease, id) {
+    if (raw.inbox_id !== lease.resourceId ||
+        raw.message_id !== id ||
+        !Array.isArray(raw.labels) ||
+        !raw.labels.includes("received"))
+        fail("agentmail_ownership_mismatch");
+    const limitations = [];
+    const from = limitedText(raw.from, limitations);
+    if (!from)
+        fail("agentmail_invalid_response");
+    const text = limitedText(raw.text, limitations) ?? "";
+    const html = limitedText(raw.html, limitations);
+    const subject = limitedText(raw.subject, limitations);
+    const message = {
+        channel: "email",
+        providerMessageId: id,
+        from,
+        text,
+        ...(html === undefined ? {} : { html }),
+        ...(subject === undefined ? {} : { subject }),
+        inlineImages: [],
+        limitations,
+    };
+    if (!text && !html)
+        limitations.push("agentmail_content_missing");
+    if (typeof raw.timestamp === "string" &&
+        raw.timestamp.length <= 64 &&
+        Number.isFinite(Date.parse(raw.timestamp)))
+        message.providerTimestamp = new Date(raw.timestamp).toISOString();
+    else
+        limitations.push("agentmail_timestamp_missing");
+    return message;
+}
+const INLINE_IMAGE_TYPES = ["image/png", "image/jpeg", "image/gif", "image/webp"];
+/**
+ * Downloads one inline image attachment within the message's remaining image bytes, with its
+ * size; undefined for an attachment that is not an inline image.
+ */
+async function inlineImage(receiver, lease, id, item, imageBytes, budget) {
+    const attachment = object(item);
+    if (attachment.content_disposition !== "inline" ||
+        !INLINE_IMAGE_TYPES.includes(String(attachment.content_type)))
+        return undefined;
+    const attachmentId = identifier(attachment.attachment_id);
+    const cid = identifier(attachment.content_id).replace(/^<|>$/g, "");
+    if (cid.length > 256)
+        fail("agentmail_invalid_response");
+    if (typeof attachment.size !== "number" ||
+        !Number.isSafeInteger(attachment.size) ||
+        attachment.size <= 0 ||
+        attachment.size > MAX_INLINE_IMAGE_BYTES ||
+        imageBytes + attachment.size > MAX_INLINE_IMAGES_BYTES)
+        fail("agentmail_size_limit");
+    const descriptor = success(await api(receiver, `${messagePath(lease, id)}/attachments/${encodeURIComponent(attachmentId)}`, "GET", budget));
+    if (descriptor.attachment_id !== attachmentId ||
+        descriptor.content_type !== attachment.content_type ||
+        descriptor.content_id !== attachment.content_id ||
+        descriptor.size !== attachment.size)
+        fail("agentmail_invalid_response");
+    const bytes = await download(receiver, descriptor.download_url, budget);
+    if (bytes.length !== attachment.size || imageBytes + bytes.length > MAX_INLINE_IMAGES_BYTES)
+        fail("agentmail_size_limit");
+    const image = {
+        contentId: cid,
+        contentType: String(attachment.content_type),
+        base64: bytes.toString("base64"),
+    };
+    if (!inlineImageData(image))
+        fail("agentmail_invalid_response");
+    return { image, size: bytes.length };
+}
+/** Fetches a message and its inline images; an image that fails becomes a limitation. */
+async function getMessage(receiver, lease, id, budget) {
+    const raw = success(await api(receiver, messagePath(lease, id), "GET", budget));
+    const message = parseMessage(raw, lease, id);
+    const limitations = message.limitations;
+    if (raw.attachments !== undefined && !Array.isArray(raw.attachments))
+        fail("agentmail_invalid_response");
+    const attachments = (raw.attachments ?? []);
+    if (attachments.length > MAX_INLINE_IMAGES)
+        limitations.push("agentmail_attachment_limit");
+    let imageBytes = 0;
+    for (const item of attachments.slice(0, MAX_INLINE_IMAGES)) {
+        try {
+            const inline = await inlineImage(receiver, lease, id, item, imageBytes, budget);
+            if (inline === undefined) {
+                limitations.push("agentmail_attachment_unsupported");
+                continue;
+            }
+            imageBytes += inline.size;
+            message.inlineImages.push(inline.image);
+        }
+        catch (error) {
+            const code = safeCode(error);
+            if (code === "agentmail_cancelled")
+                throw error;
+            limitations.push(code, "agentmail_attachment_unavailable");
+            if (exhausted(budget))
+                break;
+        }
+    }
+    message.limitations = [...new Set(limitations)];
+    return message;
+}
+async function authenticate(receiver, budget) {
+    const raw = success(await api(receiver, "/v0/auth/me", "GET", budget));
+    if (raw.scope_type !== "organization" && raw.scope_type !== "pod" && raw.scope_type !== "inbox")
+        fail("agentmail_invalid_response");
+    // Pod- and inbox-scoped keys cannot create the fresh inboxes a study needs.
+    if (raw.scope_type !== "organization")
+        fail(RECEIVING_SCOPE_UNSUPPORTED);
+    return {
+        provider: "agentmail",
+        accountId: identifier(raw.organization_id),
+        scopeType: raw.scope_type,
+        scopeId: identifier(raw.scope_id),
+    };
+}
+/** Provisions the inbox for `clientId`, retrying one transient failure. */
+async function acquireInbox(receiver, clientId, budget) {
+    inputId(clientId);
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            const raw = success(await api(receiver, "/v0/inboxes", "POST", budget, { client_id: clientId }));
+            const lease = {
+                resourceId: identifier(raw.inbox_id),
+                address: identifier(raw.email),
+                clientId,
+            };
+            if (raw.client_id !== clientId)
+                fail("agentmail_ownership_mismatch");
+            if (!/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(lease.address))
+                fail("agentmail_invalid_response");
+            return lease;
+        }
+        catch (error) {
+            if (attempt || !transient(safeCode(error)) || budget.signal.aborted)
+                throw error;
+        }
+    }
+    return fail("agentmail_unavailable");
+}
+/**
+ * Reads the inbox's received messages, page by page within the limits. A message or page that
+ * fails becomes a limitation and marks the batch incomplete; cancellation always throws.
+ */
+async function readInbox(receiver, lease, budget) {
+    checkLease(lease);
+    const batch = { messages: [], complete: true, limitations: [] };
+    const ids = new Set();
+    const tokens = new Set();
+    let token;
+    for (let page = 0; page < AGENTMAIL_RECEIVING_LIMITS.pages; page++) {
+        try {
+            const query = new URLSearchParams({
+                limit: String(AGENTMAIL_RECEIVING_LIMITS.pageSize),
+                labels: "received",
+                ...(token === undefined ? {} : { page_token: token }),
+            });
+            const raw = success(await api(receiver, `${inboxPath(lease)}/messages?${query.toString()}`, "GET", budget));
+            if (!Array.isArray(raw.messages) || raw.messages.length > AGENTMAIL_RECEIVING_LIMITS.pageSize)
+                fail("agentmail_invalid_response");
+            for (const item of raw.messages) {
+                const entry = object(item);
+                if (entry.inbox_id !== lease.resourceId)
+                    fail("agentmail_ownership_mismatch");
+                if (!Array.isArray(entry.labels))
+                    fail("agentmail_invalid_response");
+                if (!entry.labels.includes("received"))
+                    continue;
+                const id = identifier(entry.message_id);
+                if (ids.has(id))
+                    continue;
+                if (ids.size >= AGENTMAIL_RECEIVING_LIMITS.messages)
+                    fail("agentmail_size_limit");
+                ids.add(id);
+                try {
+                    const message = await getMessage(receiver, lease, id, budget);
+                    batch.messages.push(message);
+                    if (message.limitations.length) {
+                        batch.complete = false;
+                        batch.limitations.push(...message.limitations);
+                    }
+                }
+                catch (error) {
+                    if (safeCode(error) === "agentmail_cancelled")
+                        throw error;
+                    batch.complete = false;
+                    batch.limitations.push(safeCode(error), "agentmail_message_unavailable");
+                    if (exhausted(budget))
+                        throw error;
+                }
+            }
+            if (raw.next_page_token === undefined ||
+                raw.next_page_token === null ||
+                raw.next_page_token === "")
+                break;
+            token = identifier(raw.next_page_token);
+            if (tokens.has(token)) {
+                batch.complete = false;
+                batch.limitations.push("agentmail_pagination_stalled");
+                break;
+            }
+            tokens.add(token);
+            if (page + 1 === AGENTMAIL_RECEIVING_LIMITS.pages) {
+                batch.complete = false;
+                batch.limitations.push("agentmail_page_limit");
+            }
+        }
+        catch (error) {
+            if (safeCode(error) === "agentmail_cancelled")
+                throw error;
+            batch.complete = false;
+            batch.limitations.push(safeCode(error));
+            break;
+        }
+    }
+    batch.limitations = [...new Set(batch.limitations)];
+    return batch;
+}
+/** Deletes the inbox after checking it is this lease's; absent or deleting counts as released. */
+async function releaseInbox(receiver, lease, budget) {
+    checkLease(lease);
+    const before = await api(receiver, inboxPath(lease), "GET", budget);
+    const existing = absentOrDeleting(before);
+    if (existing)
+        return { status: existing };
+    assertOwnership(success(before), lease);
+    const deleted = await api(receiver, inboxPath(lease), "DELETE", budget);
+    const state = absentOrDeleting(deleted);
+    if (state)
+        return { status: state };
+    if (![200, 202, 204].includes(deleted.status))
+        statusError(deleted);
+    try {
+        const after = await api(receiver, inboxPath(lease), "GET", budget);
+        const result = absentOrDeleting(after);
+        if (result)
+            return { status: result };
+        assertOwnership(success(after), lease);
+        return { status: "deleting" };
+    }
+    catch (error) {
+        if (transient(safeCode(error)))
+            return { status: "deleting" };
+        throw error;
+    }
+}
+/** Host-only transport; the management credential is never sent to a desktop or download host. */
+export function createAgentMailReceiver(options) {
+    if (!options.apiKey || options.apiKey.length > 4096 || /[\u0000- \u007f]/.test(options.apiKey))
+        fail("agentmail_invalid_input");
+    const receiver = { key: options.apiKey, fetch: options.fetch ?? globalThis.fetch };
+    return {
+        provider: "agentmail",
+        addressing: "provisioned",
+        // POST /v0/inboxes with a known client_id returns the original inbox.
+        idempotentAcquire: true,
+        codes: AGENTMAIL_RECEIVING_CODES,
+        authRejectedCode: "agentmail_auth_rejected",
+        authenticate: (context) => operation(context, (budget) => authenticate(receiver, budget)),
+        acquire: (clientId, context) => operation(context, (budget) => acquireInbox(receiver, clientId, budget)),
+        read: (lease, context) => operation(context, (budget) => readInbox(receiver, lease, budget)),
+        release: (lease, context) => operation(context, (budget) => releaseInbox(receiver, lease, budget)),
+    };
+}

package/dist/comms/capture-surface.d.ts

@@ -0,0 +1,54 @@
+import type { ReceivingSurfaceFile } from "./receiving-types.js";
+import type { CommsMessage } from "./types.js";
+/** [fromOrigin, toOrigin] pairs: rewrite a link/href whose origin is the app's in-sandbox origin into a
+ *  lane-reachable origin, so the persona's browser can actually follow the verify link when it clicks. */
+export type OriginMap = Array<[string, string]>;
+export interface InboxRenderOptions {
+    originMap?: OriginMap;
+    /** Runtime recipient for this view; omission deliberately renders the operator's shared inbox. */
+    recipient?: string;
+    /** Declared addresses also receive empty scopes before the first delivery. */
+    recipients?: string[];
+}
+export declare function inboxRecipientScope(address: string): string;
+export declare function recipientInboxUrl(inboxUrl: string, address: string): string;
+/** Rewrite a URL's origin per the map (origins are exact strings the harness minted). Leaves
+ *  non-matching URLs — including sibling origins sharing a prefix — untouched. */
+export declare function rewriteOrigin(url: string, originMap?: OriginMap): string;
+/**
+ * Build the [internalOrigin → reachableOrigin] rewrite rows for a run. The app-under-test bakes ITS OWN
+ * origin into the verify links it emails (usually its loopback serve origin); the persona reaches the
+ * app at a possibly-different origin — the same loopback on the CUA route (identity, a no-op), the
+ * harness-minted getHost URL on the shared-world route (where the rewrite is REQUIRED). Emits the serve
+ * origin plus its loopback aliases at the serve port (127.0.0.1 / localhost / 0.0.0.0) so an app that
+ * stamps `localhost` still rewrites, and — because the harness cannot infer an absolute PUBLIC base URL
+ * an app was configured with — an operator-declared `linkOrigin` escape hatch, matched first. Origins
+ * only (no trailing slash, no path), so replaceOriginBoundary matches on a URL boundary.
+ */
+export declare function buildOriginMap(args: {
+    internalServeUrl?: string | undefined;
+    reachableBaseUrl?: string | undefined;
+    linkOrigin?: string | undefined;
+}): OriginMap;
+/** Best-guess primary call-to-action: the first verify/confirm-looking link, else the first link. */
+export declare function pickVerifyUrl(links: string[]): string | undefined;
+/** The inbox LIST page (semantic table; each row links to its message). */
+export declare function renderInboxList(messages: CommsMessage[], options?: InboxRenderOptions): string;
+/** One message, DEFAULT view: the app's real captured email in a minimal high-contrast shell. */
+export declare function renderInboxMessage(message: CommsMessage, options?: InboxRenderOptions): string;
+/** One message, SYNTHESIZED view: a guaranteed-legible reading pane (big verify button + big OTP). The
+ *  reliability fallback when the app's real email is a vision minefield; opt-in, never the default. */
+export declare function renderInboxMessageSynth(message: CommsMessage, options?: InboxRenderOptions): string;
+/** JSON projection of one message (the programmatic/CLI actor surface + the reliability backstop). Raw
+ *  runtime values (served in-sandbox only); links/verifyUrl origin-rewritten so a consumer can follow. */
+export declare function inboxMessageJson(message: CommsMessage, options?: InboxRenderOptions): Record<string, unknown>;
+/**
+ * Build every served file for the inbox surface from the normalized messages. The host writes each to
+ * `<servedDir>/<path>`; the in-sandbox catch serves `<servedDir>/<pathname>`, falling back to
+ * `<pathname>/index` (so a URL like `/inbox` maps to the `inbox/index` file while `/inbox/{id}` stays a
+ * directory) — standard web-server index semantics that avoid a file-vs-directory path collision. The
+ * URLs the persona actually sees stay clean (`/inbox`, `/inbox/{id}`, `/inbox/{id}/synth`). Content type
+ * is inferred from the `/api/` prefix. Message ids are `comms-NNNN` (never `index`/`latest`), so leaf
+ * filenames never collide with an id.
+ */
+export declare function buildInboxSurface(messages: CommsMessage[], options?: InboxRenderOptions): ReceivingSurfaceFile[];