@atomicmail/langchain 0.3.14

package/esm/lib/agent/auth/agent-jwt.js

@@ -0,0 +1,27 @@
+// JWT helpers for capability/session expiry checks.
+export const SESSION_SAFETY_MARGIN_MS = 60_000;
+export const CAPABILITY_SAFETY_MARGIN_MS = 20_000;
+export function decodeJwtPayload(jwt) {
+    const parts = jwt.split(".");
+    if (parts.length < 2) {
+        throw new Error("Malformed JWT: expected at least 2 dot-separated segments.");
+    }
+    const payloadB64Url = parts[1];
+    const padLen = (4 - (payloadB64Url.length % 4)) % 4;
+    const base64 = payloadB64Url
+        .replace(/-/g, "+")
+        .replace(/_/g, "/")
+        .padEnd(payloadB64Url.length + padLen, "=");
+    return JSON.parse(atob(base64));
+}
+export function isJwtExpired(jwt, marginMs) {
+    try {
+        const { exp } = decodeJwtPayload(jwt);
+        if (typeof exp !== "number")
+            return true;
+        return Date.now() >= exp * 1000 - marginMs;
+    }
+    catch {
+        return true;
+    }
+}

package/esm/lib/agent/auth/agent-pow.d.ts

@@ -0,0 +1,5 @@
+export declare function solvePow(challenge: string, difficulty: number, salt: string, onProgress?: (nonce: bigint) => void): Promise<{
+    powHex: string;
+    nonce: string;
+}>;
+//# sourceMappingURL=agent-pow.d.ts.map

package/esm/lib/agent/auth/agent-pow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-pow.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/auth/agent-pow.ts"],"names":[],"mappings":"AAuCA,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GACnC,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAU5C"}

package/esm/lib/agent/auth/agent-pow.js

@@ -0,0 +1,49 @@
+// PoW scrypt — mirrors services/auth-service/src/crypto.ts.
+import { scrypt } from "node:crypto";
+const SCRYPT_PARAMS = { N: 16384, r: 8, p: 1 };
+const POW_HASH_BYTES = 64;
+function bytesToHex(bytes) {
+    let hex = "";
+    for (let i = 0; i < bytes.length; i++) {
+        hex += bytes[i].toString(16).padStart(2, "0");
+    }
+    return hex;
+}
+function hasLeadingZeroBits(hash, bits) {
+    if (bits > hash.length * 8)
+        return false;
+    const fullBytes = Math.floor(bits / 8);
+    const remainingBits = bits % 8;
+    for (let i = 0; i < fullBytes; i++) {
+        if (hash[i] !== 0)
+            return false;
+    }
+    if (remainingBits > 0) {
+        const mask = (0xff << (8 - remainingBits)) & 0xff;
+        if ((hash[fullBytes] & mask) !== 0)
+            return false;
+    }
+    return true;
+}
+function scryptHash(data, salt) {
+    const bytes = new TextEncoder().encode(data);
+    return new Promise((resolve, reject) => {
+        scrypt(bytes, salt, POW_HASH_BYTES, SCRYPT_PARAMS, (err, derived) => {
+            if (err)
+                return reject(err);
+            resolve(new Uint8Array(derived));
+        });
+    });
+}
+export async function solvePow(challenge, difficulty, salt, onProgress) {
+    let nonce = 0n;
+    while (true) {
+        const digest = await scryptHash(`${challenge}:${nonce}`, salt);
+        if (hasLeadingZeroBits(digest, difficulty)) {
+            return { powHex: bytesToHex(digest), nonce: nonce.toString() };
+        }
+        nonce++;
+        if (onProgress && nonce % 64n === 0n)
+            onProgress(nonce);
+    }
+}

package/esm/lib/agent/jmap/agent-help-content.d.ts

@@ -0,0 +1,2 @@
+export * from "./help-content/index.js";
+//# sourceMappingURL=agent-help-content.d.ts.map

package/esm/lib/agent/jmap/agent-help-content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-help-content.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/jmap/agent-help-content.ts"],"names":[],"mappings":"AAEA,cAAc,yBAAyB,CAAC"}

package/esm/lib/agent/jmap/agent-help-content.js

@@ -0,0 +1,2 @@
+// Long-form help for MCP `help` tool and AgentSkill `help` command.
+export * from "./help-content/index.js";

package/esm/lib/agent/jmap/agent-jmap-blob-limits.d.ts

@@ -0,0 +1,27 @@
+export interface JmapBlobUploadLimits {
+    maxSizeBlobSet: number | null;
+    /** When omitted, skip maxDataSources enforcement (not advertised). */
+    maxDataSources?: number;
+}
+export interface JmapEnvelopeLike {
+    using: string[];
+    methodCalls: unknown[];
+}
+export declare function utf8ByteLength(s: string): number;
+/** Decoded byte length; throws if the string is not valid standard base64. */
+export declare function decodedBase64ByteLength(b64: string): number;
+/**
+ * Returns total octets for one UploadObject `data` array, or `null` if a literal
+ * (non-`#`) blobId slice is present or a `#ref` is not yet in `knownSizes`.
+ */
+export declare function tryComputeUploadDataOctets(dataUnknown: unknown, knownSizes: ReadonlyMap<string, number>): number | null;
+/**
+ * Walks `methodCalls` in order and enforces limits for each `Blob/upload` whose
+ * `accountId` has an entry in `limitsByAccount`.
+ */
+export declare function assertBlobUploadEnvelopeWithinLimits(envelope: JmapEnvelopeLike, limitsByAccount: ReadonlyMap<string, JmapBlobUploadLimits | null>): void;
+export declare function assertAttachmentBytesWithinBlobLimit(items: readonly {
+    label: string;
+    byteLength: number;
+}[], limits: JmapBlobUploadLimits | null): void;
+//# sourceMappingURL=agent-jmap-blob-limits.d.ts.map

package/esm/lib/agent/jmap/agent-jmap-blob-limits.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-jmap-blob-limits.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/jmap/agent-jmap-blob-limits.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,oBAAoB;IACnC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,OAAO,EAAE,CAAC;CACxB;AAED,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,8EAA8E;AAC9E,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAgB3D;AAqBD;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,OAAO,EACpB,UAAU,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GACtC,MAAM,GAAG,IAAI,CAiDf;AA6DD;;;GAGG;AACH,wBAAgB,oCAAoC,CAClD,QAAQ,EAAE,gBAAgB,EAC1B,eAAe,EAAE,WAAW,CAAC,MAAM,EAAE,oBAAoB,GAAG,IAAI,CAAC,GAChE,IAAI,CAuBN;AAED,wBAAgB,oCAAoC,CAClD,KAAK,EAAE,SAAS;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,EAAE,EACvD,MAAM,EAAE,oBAAoB,GAAG,IAAI,GAClC,IAAI,CAYN"}

package/esm/lib/agent/jmap/agent-jmap-blob-limits.js

@@ -0,0 +1,166 @@
+// RFC 9404 §3.1 client-side checks before Blob/upload POST (maxSizeBlobSet, maxDataSources).
+const utf8Encoder = new TextEncoder();
+export function utf8ByteLength(s) {
+    return utf8Encoder.encode(s).length;
+}
+/** Decoded byte length; throws if the string is not valid standard base64. */
+export function decodedBase64ByteLength(b64) {
+    const t = b64.replace(/\s+/g, "");
+    if (t.length === 0)
+        return 0;
+    if (t.length % 4 === 1) {
+        throw new Error("Invalid base64 in Blob/upload data:asBase64 (RFC 9404 §4.1): bad length.");
+    }
+    try {
+        const bin = atob(t.replace(/-/g, "+").replace(/_/g, "/"));
+        return bin.length;
+    }
+    catch {
+        throw new Error("Invalid base64 in Blob/upload data:asBase64 (RFC 9404 §4.1).");
+    }
+}
+function sliceOctetCount(sourceLen, offset, length) {
+    let off = 0;
+    if (typeof offset === "number" && Number.isInteger(offset) && offset >= 0) {
+        off = offset;
+    }
+    const rest = Math.max(0, sourceLen - off);
+    if (length === null || length === undefined) {
+        return rest;
+    }
+    if (typeof length === "number" && Number.isInteger(length) && length >= 0) {
+        return Math.min(rest, length);
+    }
+    return rest;
+}
+/**
+ * Returns total octets for one UploadObject `data` array, or `null` if a literal
+ * (non-`#`) blobId slice is present or a `#ref` is not yet in `knownSizes`.
+ */
+export function tryComputeUploadDataOctets(dataUnknown, knownSizes) {
+    if (!Array.isArray(dataUnknown))
+        return 0;
+    let total = 0;
+    for (const part of dataUnknown) {
+        if (!part || typeof part !== "object")
+            continue;
+        const o = part;
+        const tText = o["data:asText"];
+        const tB64 = o["data:asBase64"];
+        const tBlob = o["blobId"];
+        const hasText = tText !== undefined && tText !== null;
+        const hasB64 = tB64 !== undefined && tB64 !== null;
+        const hasBlob = tBlob !== undefined && tBlob !== null;
+        const n = [hasText, hasB64, hasBlob].filter(Boolean).length;
+        if (n === 0)
+            continue;
+        if (n !== 1) {
+            throw new Error("Each Blob/upload DataSourceObject must use exactly one of " +
+                "data:asText, data:asBase64, or blobId (RFC 9404 §4.1).");
+        }
+        if (hasText) {
+            if (typeof tText !== "string") {
+                throw new Error("Blob/upload data:asText must be a string.");
+            }
+            total += utf8ByteLength(tText);
+            continue;
+        }
+        if (hasB64) {
+            if (typeof tB64 !== "string") {
+                throw new Error("Blob/upload data:asBase64 must be a string.");
+            }
+            total += decodedBase64ByteLength(tB64);
+            continue;
+        }
+        if (typeof tBlob !== "string" || tBlob.length === 0) {
+            throw new Error("Blob/upload blobId must be a non-empty string.");
+        }
+        if (!tBlob.startsWith("#")) {
+            return null;
+        }
+        const refId = tBlob.slice(1);
+        const sourceLen = knownSizes.get(refId);
+        if (sourceLen === undefined) {
+            return null;
+        }
+        total += sliceOctetCount(sourceLen, o["offset"], o["length"]);
+    }
+    return total;
+}
+function resolveCreateSizesForOneBlobUpload(create, limits, priorSizes) {
+    const merged = new Map(priorSizes);
+    const pending = new Set(Object.keys(create));
+    while (pending.size > 0) {
+        let progressed = false;
+        for (const id of [...pending]) {
+            const upload = create[id];
+            if (!upload || typeof upload !== "object") {
+                pending.delete(id);
+                progressed = true;
+                continue;
+            }
+            const data = upload["data"];
+            const dsCount = Array.isArray(data) ? data.length : 0;
+            if (limits.maxDataSources !== undefined &&
+                dsCount > limits.maxDataSources) {
+                throw new Error(`Blob/upload create "${id}" uses ${dsCount} DataSourceObject entries; ` +
+                    `account maxDataSources is ${limits.maxDataSources} (RFC 9404 §3.1).`);
+            }
+            const computed = tryComputeUploadDataOctets(data, merged);
+            if (computed === null) {
+                continue;
+            }
+            if (limits.maxSizeBlobSet !== null &&
+                computed > limits.maxSizeBlobSet) {
+                throw new Error(`Blob/upload create "${id}" would be ${computed} octets; account ` +
+                    `maxSizeBlobSet is ${limits.maxSizeBlobSet} (RFC 9404 §3.1). ` +
+                    "Use a smaller payload, split data, or POST the file to the session " +
+                    "uploadUrl (RFC 8620) / MCP attachments for large binaries.");
+            }
+            merged.set(id, computed);
+            pending.delete(id);
+            progressed = true;
+        }
+        if (!progressed) {
+            break;
+        }
+    }
+    return merged;
+}
+/**
+ * Walks `methodCalls` in order and enforces limits for each `Blob/upload` whose
+ * `accountId` has an entry in `limitsByAccount`.
+ */
+export function assertBlobUploadEnvelopeWithinLimits(envelope, limitsByAccount) {
+    let globalSizes = new Map();
+    for (const call of envelope.methodCalls) {
+        if (!Array.isArray(call) || call[0] !== "Blob/upload")
+            continue;
+        const arg = call[1];
+        if (!arg || typeof arg !== "object")
+            continue;
+        const rec = arg;
+        const accountId = rec["accountId"];
+        if (typeof accountId !== "string" || accountId.length === 0)
+            continue;
+        const limits = limitsByAccount.get(accountId);
+        if (!limits)
+            continue;
+        const create = rec["create"];
+        if (!create || typeof create !== "object")
+            continue;
+        globalSizes = resolveCreateSizesForOneBlobUpload(create, limits, globalSizes);
+    }
+}
+export function assertAttachmentBytesWithinBlobLimit(items, limits) {
+    if (!limits || limits.maxSizeBlobSet === null)
+        return;
+    const max = limits.maxSizeBlobSet;
+    for (const it of items) {
+        if (it.byteLength > max) {
+            throw new Error(`${it.label} is ${it.byteLength} octets but account maxSizeBlobSet is ` +
+                `${max} (RFC 9404 §3.1). Use a smaller file or refresh the session if ` +
+                "limits changed.");
+        }
+    }
+}

package/esm/lib/agent/jmap/agent-jmap-blob-upload.d.ts

@@ -0,0 +1,24 @@
+import type { JmapSessionPort } from "./agent-jmap.js";
+/** One local file to upload before `$ATTACHMENT_*` substitution in ops JSON. */
+export interface JmapAttachmentInput {
+    path: string;
+    filename?: string;
+    contentType?: string;
+}
+export declare function guessMimeTypeFromFilename(name: string): string;
+export declare function expandUploadUrl(template: string, accountId: string): string;
+export declare function postBinaryBlobUpload(uploadUrlExpanded: string, capabilityJwt: string, bytes: Uint8Array, contentType: string): Promise<{
+    blobId: string;
+    size: number;
+}>;
+/**
+ * Reads each file, POSTs bytes to the JMAP session `uploadUrl`, and returns
+ * placeholder values for use in standard JMAP ops (same batch as
+ * `Email/set` / `EmailSubmission/set`).
+ *
+ * Injected keys (strings): `ATTACHMENT_0_BLOB_ID`, `ATTACHMENT_0_NAME`,
+ * `ATTACHMENT_0_TYPE`, `ATTACHMENT_0_SIZE`, … zero-based index per file, plus
+ * `ATTACHMENT_COUNT`.
+ */
+export declare function buildVarsFromAttachmentFiles(session: JmapSessionPort, attachments: JmapAttachmentInput[], pathBase?: string): Promise<Record<string, string>>;
+//# sourceMappingURL=agent-jmap-blob-upload.d.ts.map

package/esm/lib/agent/jmap/agent-jmap-blob-upload.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-jmap-blob-upload.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/jmap/agent-jmap-blob-upload.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAEvD,gFAAgF;AAChF,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAoBD,wBAAgB,yBAAyB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAK9D;AAED,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAI3E;AAED,wBAAsB,oBAAoB,CACxC,iBAAiB,EAAE,MAAM,EACzB,aAAa,EAAE,MAAM,EACrB,KAAK,EAAE,UAAU,EACjB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAwB3C;AAED;;;;;;;;GAQG;AACH,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,eAAe,EACxB,WAAW,EAAE,mBAAmB,EAAE,EAClC,QAAQ,GAAE,MAAc,GACvB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAuDjC"}

package/esm/lib/agent/jmap/agent-jmap-blob-upload.js

@@ -0,0 +1,104 @@
+// RFC 8620 binary blob upload (session uploadUrl) for jmap_request attachment paths.
+import { readFile } from "node:fs/promises";
+import { basename, isAbsolute, resolve } from "node:path";
+import { cwd } from "node:process";
+import { readCredentials } from "../session/agent-credentials-store.js";
+import { assertAttachmentBytesWithinBlobLimit } from "./agent-jmap-blob-limits.js";
+const EXT_TO_MIME = {
+    ".txt": "text/plain",
+    ".html": "text/html",
+    ".htm": "text/html",
+    ".css": "text/css",
+    ".js": "text/javascript",
+    ".json": "application/json",
+    ".pdf": "application/pdf",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+    ".zip": "application/zip",
+    ".gz": "application/gzip",
+    ".xml": "application/xml",
+};
+export function guessMimeTypeFromFilename(name) {
+    const lower = name.toLowerCase();
+    const dot = lower.lastIndexOf(".");
+    if (dot === -1)
+        return "application/octet-stream";
+    return EXT_TO_MIME[lower.slice(dot)] ?? "application/octet-stream";
+}
+export function expandUploadUrl(template, accountId) {
+    return template
+        .replaceAll("%7BaccountId%7D", accountId)
+        .replaceAll("{accountId}", accountId);
+}
+export async function postBinaryBlobUpload(uploadUrlExpanded, capabilityJwt, bytes, contentType) {
+    const body = bytes.buffer.slice(bytes.byteOffset, bytes.byteOffset + bytes.byteLength);
+    const res = await fetch(uploadUrlExpanded, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${capabilityJwt}`,
+            "Content-Type": contentType,
+        },
+        body,
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`RFC 8620 binary upload failed (HTTP ${res.status}) for ${uploadUrlExpanded}: ${text}`);
+    }
+    const j = JSON.parse(text);
+    if (typeof j.blobId !== "string" || j.blobId.length === 0) {
+        throw new Error(`Upload response missing blobId: ${text}`);
+    }
+    return { blobId: j.blobId, size: typeof j.size === "number" ? j.size : 0 };
+}
+/**
+ * Reads each file, POSTs bytes to the JMAP session `uploadUrl`, and returns
+ * placeholder values for use in standard JMAP ops (same batch as
+ * `Email/set` / `EmailSubmission/set`).
+ *
+ * Injected keys (strings): `ATTACHMENT_0_BLOB_ID`, `ATTACHMENT_0_NAME`,
+ * `ATTACHMENT_0_TYPE`, `ATTACHMENT_0_SIZE`, … zero-based index per file, plus
+ * `ATTACHMENT_COUNT`.
+ */
+export async function buildVarsFromAttachmentFiles(session, attachments, pathBase = cwd()) {
+    if (attachments.length === 0)
+        return {};
+    const accountId = await session.getPrimaryMailAccountId();
+    const limits = await session.getBlobUploadLimitsForAccount(accountId);
+    const capabilityJwt = await session.getCapabilityToken();
+    const uploadTemplate = session.currentUploadUrl ??
+        (session.files
+            ? (await readCredentials(session.files.credentialsFile)).uploadUrl
+            : undefined);
+    if (!uploadTemplate) {
+        throw new Error("JMAP session missing uploadUrl.");
+    }
+    const uploadUrlExpanded = expandUploadUrl(uploadTemplate, accountId);
+    const prepared = [];
+    for (let i = 0; i < attachments.length; i++) {
+        const a = attachments[i];
+        const abs = isAbsolute(a.path) ? a.path : resolve(pathBase, a.path);
+        const buf = await readFile(abs);
+        const bytes = buf;
+        const filename = a.filename ?? basename(abs);
+        const contentType = a.contentType ?? guessMimeTypeFromFilename(filename);
+        prepared.push({ bytes, filename, contentType });
+    }
+    assertAttachmentBytesWithinBlobLimit(prepared.map((p) => ({
+        label: p.filename,
+        byteLength: p.bytes.byteLength,
+    })), limits);
+    const vars = {};
+    for (let i = 0; i < prepared.length; i++) {
+        const { bytes, filename, contentType } = prepared[i];
+        const { blobId, size } = await postBinaryBlobUpload(uploadUrlExpanded, capabilityJwt, bytes, contentType);
+        vars[`ATTACHMENT_${i}_BLOB_ID`] = blobId;
+        vars[`ATTACHMENT_${i}_NAME`] = filename;
+        vars[`ATTACHMENT_${i}_TYPE`] = contentType;
+        vars[`ATTACHMENT_${i}_SIZE`] = String(size);
+    }
+    vars["ATTACHMENT_COUNT"] = String(attachments.length);
+    return vars;
+}

package/esm/lib/agent/jmap/agent-jmap-email-charset.d.ts

@@ -0,0 +1,8 @@
+import type { JmapEnvelope } from "./agent-jmap.js";
+/**
+ * Ensures blob-backed `text/*` body parts in `Email/set` `create` include
+ * `charset` when omitted, for strict JMAP servers. Skips parts with `partId`
+ * (RFC 8621 forbids charset there).
+ */
+export declare function ensureTextCharsetOnEmailSetBlobParts(envelope: JmapEnvelope): void;
+//# sourceMappingURL=agent-jmap-email-charset.d.ts.map

package/esm/lib/agent/jmap/agent-jmap-email-charset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-jmap-email-charset.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/jmap/agent-jmap-email-charset.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AA2CpD;;;;GAIG;AACH,wBAAgB,oCAAoC,CAClD,QAAQ,EAAE,YAAY,GACrB,IAAI,CAMN"}

package/esm/lib/agent/jmap/agent-jmap-email-charset.js

@@ -0,0 +1,61 @@
+// RFC 8621 §4.4: charset MUST be omitted when partId is given; blob-backed text/*
+// parts should include charset (type strips Content-Type parameters).
+const DEFAULT_TEXT_CHARSET = "utf-8";
+function baseMediaType(type) {
+    const semi = type.indexOf(";");
+    return (semi === -1 ? type : type.slice(0, semi)).trim().toLowerCase();
+}
+function isTextStarType(type) {
+    return baseMediaType(type).startsWith("text/");
+}
+/** RFC 8621 EmailBodyPart: never add charset when partId is set. */
+function ensureCharsetOnBodyPart(part) {
+    if (!part || typeof part !== "object" || Array.isArray(part))
+        return;
+    const o = part;
+    if (typeof o.partId === "string" && o.partId.length > 0)
+        return;
+    if (typeof o.blobId !== "string" || o.blobId.length === 0)
+        return;
+    const t = o.type;
+    if (typeof t !== "string" || !isTextStarType(t))
+        return;
+    if (o.charset != null && o.charset !== "")
+        return;
+    o.charset = DEFAULT_TEXT_CHARSET;
+}
+function normalizeBodyPartArray(arr) {
+    if (!Array.isArray(arr))
+        return;
+    for (const item of arr)
+        ensureCharsetOnBodyPart(item);
+}
+function normalizeEmailSetArg(arg) {
+    if (!arg || typeof arg !== "object" || Array.isArray(arg))
+        return;
+    const create = arg["create"];
+    if (!create || typeof create !== "object" || Array.isArray(create))
+        return;
+    for (const email of Object.values(create)) {
+        if (!email || typeof email !== "object" || Array.isArray(email))
+            continue;
+        const e = email;
+        normalizeBodyPartArray(e.attachments);
+        normalizeBodyPartArray(e.textBody);
+        normalizeBodyPartArray(e.htmlBody);
+    }
+}
+/**
+ * Ensures blob-backed `text/*` body parts in `Email/set` `create` include
+ * `charset` when omitted, for strict JMAP servers. Skips parts with `partId`
+ * (RFC 8621 forbids charset there).
+ */
+export function ensureTextCharsetOnEmailSetBlobParts(envelope) {
+    for (const call of envelope.methodCalls) {
+        if (!Array.isArray(call) || call.length < 2)
+            continue;
+        if (call[0] !== "Email/set")
+            continue;
+        normalizeEmailSetArg(call[1]);
+    }
+}

package/esm/lib/agent/jmap/agent-jmap-verify.d.ts

@@ -0,0 +1,9 @@
+/** Parse JMAP responses for integration tests and dev CLIs. */
+/** Throws if `EmailSubmission/set` did not create a submission. */
+export declare function assertJmapSubmissionCreated(bodyText: string): void;
+/**
+ * Throws if the first `Blob/upload` response reports `size: 0` for a non-empty
+ * payload (common server misconfiguration).
+ */
+export declare function assertBlobUploadSizesNonZero(bodyText: string, expectBytes: number): void;
+//# sourceMappingURL=agent-jmap-verify.d.ts.map

package/esm/lib/agent/jmap/agent-jmap-verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-jmap-verify.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/jmap/agent-jmap-verify.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAE/D,mEAAmE;AACnE,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAoBlE;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAC1C,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,IAAI,CAwBN"}

package/esm/lib/agent/jmap/agent-jmap-verify.js

@@ -0,0 +1,50 @@
+/** Parse JMAP responses for integration tests and dev CLIs. */
+/** Throws if `EmailSubmission/set` did not create a submission. */
+export function assertJmapSubmissionCreated(bodyText) {
+    let parsed;
+    try {
+        parsed = JSON.parse(bodyText);
+    }
+    catch {
+        throw new Error("JMAP response was not JSON; cannot verify submission.");
+    }
+    const responses = parsed.methodResponses ?? [];
+    for (const r of responses) {
+        if (!Array.isArray(r) || r[0] !== "EmailSubmission/set")
+            continue;
+        const payload = r[1];
+        if (payload?.created && Object.keys(payload.created).length > 0) {
+            return;
+        }
+    }
+    throw new Error("EmailSubmission/set did not create a submission. Response:\n" + bodyText);
+}
+/**
+ * Throws if the first `Blob/upload` response reports `size: 0` for a non-empty
+ * payload (common server misconfiguration).
+ */
+export function assertBlobUploadSizesNonZero(bodyText, expectBytes) {
+    if (expectBytes <= 0)
+        return;
+    let parsed;
+    try {
+        parsed = JSON.parse(bodyText);
+    }
+    catch {
+        return;
+    }
+    const first = parsed.methodResponses?.[0];
+    if (!Array.isArray(first) || first[0] !== "Blob/upload")
+        return;
+    const payload = first[1];
+    const created = payload?.created;
+    if (!created || typeof created !== "object")
+        return;
+    for (const v of Object.values(created)) {
+        const s = v?.size;
+        if (typeof s === "number" && s === 0) {
+            throw new Error("Blob/upload returned size 0 — this host is not persisting blob bytes. " +
+                "Fix the server, or use RFC 8620 binary upload when POST to uploadUrl works.");
+        }
+    }
+}

package/esm/lib/agent/jmap/agent-jmap.d.ts

@@ -0,0 +1,89 @@
+import { type JmapBlobUploadLimits } from "./agent-jmap-blob-limits.js";
+import { type JmapAttachmentInput } from "./agent-jmap-blob-upload.js";
+export type { JmapAttachmentInput } from "./agent-jmap-blob-upload.js";
+export type { JmapBlobUploadLimits } from "./agent-jmap-blob-limits.js";
+export declare const DEFAULT_JMAP_USING: readonly ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"];
+export declare const BUNDLED_OPS_PRESET_NAMES: readonly ["list_inbox.json", "reply.json", "send_mail.json", "send_mail_attachment.json", "send_mail_blob_attachment.json"];
+export declare const JMAP_MAIL_URN: "urn:ietf:params:jmap:mail";
+/** RFC 9404 blob extension URN (Blob/upload, Blob/get, Blob/lookup). */
+export declare const JMAP_BLOB_URN: "urn:ietf:params:jmap:blob";
+export interface JmapEnvelope {
+    using: string[];
+    methodCalls: unknown[];
+}
+export declare function parseJmapEnvelope(raw: string, defaultUsing: string[], source: string): JmapEnvelope;
+export declare function resolveOpsFilePath(credentialDir: string, opsFile: string): string;
+export declare function readOpsFile(credentialDir: string, opsFile: string): Promise<string>;
+export declare function extractPrimaryMailAccountId(session: Record<string, unknown>): string;
+export interface JmapBlobEndpoints {
+    uploadUrl: string;
+    downloadUrl: string;
+}
+export declare function extractBlobEndpoints(session: Record<string, unknown>): JmapBlobEndpoints;
+/** RFC 8620 §2 / §3.1: POST target for JMAP API calls from the Session object. */
+export declare function extractJmapApiUrl(session: Record<string, unknown>): string;
+/**
+ * RFC 9404 §3.1 blob limits for one account from GET /.well-known/jmap JSON.
+ * Returns null when the account does not advertise `urn:ietf:params:jmap:blob`.
+ */
+export declare function extractBlobUploadLimits(session: Record<string, unknown>, accountId: string): JmapBlobUploadLimits | null;
+export declare function fetchJmapWellKnown(apiUrl: string, capabilityJwt: string): Promise<Record<string, unknown>>;
+/** Minimal surface for JMAP execution (implemented by AgentSession). */
+export interface JmapSessionPort {
+    /** Base used for `GET /.well-known/jmap` (configured `ATOMIC_MAIL_API_URL` / credentials). */
+    readonly apiUrl: string;
+    readonly files?: {
+        credentialsFile: string;
+    };
+    /** RFC 8620 Session `apiUrl` — full URL for `POST` JMAP batches. */
+    getJmapPostUrl(): Promise<string>;
+    getPrimaryMailAccountId(): Promise<string>;
+    getCapabilityToken(): Promise<string>;
+    readonly currentInboxId?: string;
+    readonly currentUploadUrl?: string;
+    readonly currentDownloadUrl?: string;
+    /** RFC 9404 §3.1 limits from cached session; null if blob capability not advertised for the account. */
+    getBlobUploadLimitsForAccount(accountId: string): Promise<JmapBlobUploadLimits | null>;
+}
+export interface RunJmapRequestInput {
+    session: JmapSessionPort;
+    /** Raw JSON: methodCalls array or full envelope */
+    opsJson: string;
+    /** Default `using` when the envelope omits it */
+    defaultUsing: string[];
+    /** Label for parse errors */
+    sourceLabel: string;
+    dryRun?: boolean;
+    /**
+     * Local files uploaded via RFC 8620 (`POST` to session `uploadUrl`) before
+     * `$VAR` substitution. Injects `ATTACHMENT_0_BLOB_ID`, `ATTACHMENT_0_NAME`,
+     * `ATTACHMENT_0_TYPE`, `ATTACHMENT_0_SIZE`, … and `ATTACHMENT_COUNT`.
+     */
+    attachments?: JmapAttachmentInput[];
+    /** Base path for relative `attachments[].path` (default: process cwd). */
+    attachmentPathBase?: string;
+    /** Values for `$VAR` tokens (keys without `$`). Overrides injected attachment vars. */
+    vars?: Record<string, string>;
+}
+/**
+ * Parse ops JSON, substitute `$VAR_NAME` tokens (session + caller vars), POST to JMAP.
+ */
+export declare function runJmapRequest(input: RunJmapRequestInput): Promise<{
+    ok: boolean;
+    status: number;
+    bodyText: string;
+}>;
+/**
+ * Resolves the JMAP `Mailbox` id for the account inbox (`role: "inbox"`).
+ * Used for `$INBOX_MAILBOX_ID` substitution (distinct from `$INBOX`, which is
+ * the mailbox *email address* — see `inboxIdToMailboxEmail` for normalization).
+ */
+export declare function fetchInboxMailboxId(port: JmapSessionPort): Promise<string>;
+export declare function postJmap(jmapPostUrl: string, capabilityJwt: string, envelope: JmapEnvelope): Promise<{
+    ok: boolean;
+    status: number;
+    bodyText: string;
+}>;
+/** Attach _next hints to a successful JMAP JSON object when parseable. */
+export declare function attachJmapNextHints(bodyText: string): string;
+//# sourceMappingURL=agent-jmap.d.ts.map