@atomicmail/langchain 0.3.14

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-jmap.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/jmap/agent-jmap.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,373 @@
+// JMAP envelope parsing, preset paths, $VAR substitution, and HTTP helpers.
+import { readFile } from "node:fs/promises";
+import { dirname, isAbsolute, resolve as resolvePath } from "node:path";
+import { cwd } from "node:process";
+import { fileURLToPath } from "node:url";
+import { tryReadSharedJson } from "../../core/shared-assets.js";
+import { readCredentials } from "../session/agent-credentials-store.js";
+import { inboxIdToMailboxEmail } from "../session/inbox-id-to-mailbox-email.js";
+import { assertBlobUploadEnvelopeWithinLimits, } from "./agent-jmap-blob-limits.js";
+import { buildVarsFromAttachmentFiles, } from "./agent-jmap-blob-upload.js";
+import { ensureTextCharsetOnEmailSetBlobParts } from "./agent-jmap-email-charset.js";
+import { substituteVars } from "./agent-vars.js";
+export const DEFAULT_JMAP_USING = [
+    "urn:ietf:params:jmap:core",
+    "urn:ietf:params:jmap:mail",
+];
+/** Presets shipped with MCP / skill npm packages (for error hints). */
+const sharedManifest = tryReadSharedJson("manifest.json");
+const sharedHints = tryReadSharedJson("messages/hints.json");
+export const BUNDLED_OPS_PRESET_NAMES = [
+    "list_inbox.json",
+    "reply.json",
+    "send_mail.json",
+    "send_mail_attachment.json",
+    "send_mail_blob_attachment.json",
+];
+export const JMAP_MAIL_URN = "urn:ietf:params:jmap:mail";
+/** RFC 9404 blob extension URN (Blob/upload, Blob/get, Blob/lookup). */
+export const JMAP_BLOB_URN = "urn:ietf:params:jmap:blob";
+export function parseJmapEnvelope(raw, defaultUsing, source) {
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${source} is not valid JSON: ${err.message}`);
+    }
+    if (Array.isArray(value)) {
+        return { using: [...defaultUsing], methodCalls: value };
+    }
+    if (value !== null &&
+        typeof value === "object" &&
+        Array.isArray(value.methodCalls)) {
+        const obj = value;
+        const using = Array.isArray(obj.using)
+            ? obj.using.filter((u) => typeof u === "string")
+            : [...defaultUsing];
+        return { using, methodCalls: obj.methodCalls };
+    }
+    throw new Error(`${source} must be a methodCalls array, e.g. ` +
+        '[["Mailbox/get",{...},"m0"]], or an object with a methodCalls array.');
+}
+export function resolveOpsFilePath(credentialDir, opsFile) {
+    return isAbsolute(opsFile) ? opsFile : resolvePath(credentialDir, opsFile);
+}
+export async function readOpsFile(credentialDir, opsFile) {
+    const filePath = resolveOpsFilePath(credentialDir, opsFile);
+    try {
+        return await readFile(filePath, "utf-8");
+    }
+    catch (err) {
+        if (!(err instanceof Error) || !isFileNotFound(err) || isAbsolute(opsFile)) {
+            throw err;
+        }
+    }
+    const bundledPath = await resolveBundledPresetPath(opsFile);
+    if (!bundledPath) {
+        throw new Error(`ops_file '${opsFile}' not found under credential directory (${filePath}) ` +
+            "and not among bundled presets: " +
+            `${BUNDLED_OPS_PRESET_NAMES.join(", ")}.`);
+    }
+    return await readFile(bundledPath, "utf-8");
+}
+function isFileNotFound(err) {
+    const code = err.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+async function resolveBundledPresetPath(opsFile) {
+    const moduleDir = dirname(fileURLToPath(globalThis[Symbol.for("import-meta-ponyfill-esmodule")](import.meta).url));
+    let currentDir = moduleDir;
+    for (let depth = 0; depth < 8; depth++) {
+        const candidates = [
+            resolvePath(currentDir, "shared", sharedManifest?.presets_dir ?? "presets", opsFile),
+            resolvePath(currentDir, "presets", opsFile),
+            resolvePath(currentDir, "agent", "jmap", "presets", opsFile),
+            resolvePath(currentDir, "lib", "src", "agent", "jmap", "presets", opsFile),
+        ];
+        for (const candidate of candidates) {
+            try {
+                await readFile(candidate, "utf-8");
+                return candidate;
+            }
+            catch (err) {
+                if (!(err instanceof Error) || !isFileNotFound(err)) {
+                    throw err;
+                }
+            }
+        }
+        const parent = resolvePath(currentDir, "..");
+        if (parent === currentDir)
+            break;
+        currentDir = parent;
+    }
+    return undefined;
+}
+export function extractPrimaryMailAccountId(session) {
+    const primary = session["primaryAccounts"];
+    if (!primary || typeof primary !== "object") {
+        throw new Error("JMAP session missing primaryAccounts.");
+    }
+    const id = primary[JMAP_MAIL_URN];
+    if (typeof id !== "string" || id.length === 0) {
+        throw new Error(`JMAP session missing primaryAccounts['${JMAP_MAIL_URN}'].`);
+    }
+    return id;
+}
+export function extractBlobEndpoints(session) {
+    const uploadUrl = session["uploadUrl"];
+    const downloadUrl = session["downloadUrl"];
+    if (typeof uploadUrl !== "string" || uploadUrl.length === 0) {
+        throw new Error("JMAP session missing uploadUrl.");
+    }
+    if (typeof downloadUrl !== "string" || downloadUrl.length === 0) {
+        throw new Error("JMAP session missing downloadUrl.");
+    }
+    return { uploadUrl, downloadUrl };
+}
+/** RFC 8620 §2 / §3.1: POST target for JMAP API calls from the Session object. */
+export function extractJmapApiUrl(session) {
+    const u = session["apiUrl"];
+    if (typeof u !== "string" || u.length === 0) {
+        throw new Error("JMAP session missing apiUrl.");
+    }
+    return u;
+}
+function asNonNegativeInt(v) {
+    if (typeof v !== "number" || !Number.isFinite(v))
+        return undefined;
+    if (!Number.isInteger(v) || v < 0 || v > Number.MAX_SAFE_INTEGER) {
+        return undefined;
+    }
+    return v;
+}
+/**
+ * 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 function extractBlobUploadLimits(session, accountId) {
+    const accounts = session["accounts"];
+    if (!accounts || typeof accounts !== "object")
+        return null;
+    const acc = accounts[accountId];
+    if (!acc || typeof acc !== "object")
+        return null;
+    const caps = acc["accountCapabilities"];
+    if (!caps || typeof caps !== "object")
+        return null;
+    const blob = caps[JMAP_BLOB_URN];
+    if (!blob || typeof blob !== "object")
+        return null;
+    const b = blob;
+    let maxSizeBlobSet = null;
+    const rawMax = b["maxSizeBlobSet"];
+    if (rawMax === null) {
+        maxSizeBlobSet = null;
+    }
+    else {
+        const n = asNonNegativeInt(rawMax);
+        maxSizeBlobSet = n === undefined ? null : n;
+    }
+    const maxDs = asNonNegativeInt(b["maxDataSources"]);
+    const out = { maxSizeBlobSet };
+    if (maxDs !== undefined) {
+        out.maxDataSources = maxDs;
+    }
+    return out;
+}
+export async function fetchJmapWellKnown(apiUrl, capabilityJwt) {
+    const base = apiUrl.replace(/\/+$/, "");
+    const res = await fetch(`${base}/.well-known/jmap`, {
+        headers: { Authorization: `Bearer ${capabilityJwt}` },
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`JMAP session fetch failed (HTTP ${res.status}): ${text}`);
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error("JMAP session response is not valid JSON.");
+    }
+}
+/**
+ * Parse ops JSON, substitute `$VAR_NAME` tokens (session + caller vars), POST to JMAP.
+ */
+export async function runJmapRequest(input) {
+    if (input.dryRun && input.attachments && input.attachments.length > 0) {
+        throw new Error("dryRun cannot be used with attachments: RFC 8620 upload runs first and would create blobs.");
+    }
+    let mergedVars = input.vars ?? {};
+    if (input.attachments && input.attachments.length > 0) {
+        const pathBase = input.attachmentPathBase ?? cwd();
+        const injected = await buildVarsFromAttachmentFiles(input.session, input.attachments, pathBase);
+        mergedVars = { ...injected, ...mergedVars };
+    }
+    const { text: raw } = await substituteVars({
+        raw: input.opsJson,
+        vars: mergedVars,
+        autoResolvers: {
+            ACCOUNT_ID: () => input.session.getPrimaryMailAccountId(),
+            INBOX: async () => {
+                const raw = input.session.currentInboxId ??
+                    (input.session.files
+                        ? (await readCredentials(input.session.files.credentialsFile))
+                            .inboxId
+                        : undefined);
+                if (!raw) {
+                    throw new Error("No inbox in session; run register first.");
+                }
+                return inboxIdToMailboxEmail(raw);
+            },
+            INBOX_MAILBOX_ID: () => fetchInboxMailboxId(input.session),
+            UPLOAD_URL: async () => {
+                if (input.session.currentUploadUrl) {
+                    return input.session.currentUploadUrl;
+                }
+                if (input.session.files) {
+                    return (await readCredentials(input.session.files.credentialsFile))
+                        .uploadUrl;
+                }
+                throw new Error("JMAP session missing uploadUrl.");
+            },
+            DOWNLOAD_URL: async () => {
+                if (input.session.currentDownloadUrl) {
+                    return input.session.currentDownloadUrl;
+                }
+                if (input.session.files) {
+                    return (await readCredentials(input.session.files.credentialsFile))
+                        .downloadUrl;
+                }
+                throw new Error("JMAP session missing downloadUrl.");
+            },
+        },
+    });
+    const envelope = parseJmapEnvelope(raw, input.defaultUsing, input.sourceLabel);
+    ensureTextCharsetOnEmailSetBlobParts(envelope);
+    await enforceJmapBlobUploadLimitsIfApplicable(input.session, envelope);
+    const jmapPostUrl = await input.session.getJmapPostUrl();
+    if (input.dryRun) {
+        return {
+            ok: true,
+            status: 200,
+            bodyText: JSON.stringify({
+                dryRun: true,
+                url: jmapPostUrl,
+                envelope,
+            }, null, 2),
+        };
+    }
+    const capabilityJwt = await input.session.getCapabilityToken();
+    const { ok, status, bodyText } = await postJmap(jmapPostUrl, capabilityJwt, envelope);
+    if (!ok) {
+        return { ok, status, bodyText };
+    }
+    return { ok, status, bodyText: attachJmapNextHints(bodyText) };
+}
+/**
+ * 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 async function fetchInboxMailboxId(port) {
+    const accountId = await port.getPrimaryMailAccountId();
+    const capabilityJwt = await port.getCapabilityToken();
+    const envelope = {
+        using: [
+            "urn:ietf:params:jmap:core",
+            "urn:ietf:params:jmap:mail",
+        ],
+        methodCalls: [
+            [
+                "Mailbox/query",
+                { accountId, filter: { role: "inbox" } },
+                "mq0",
+            ],
+        ],
+    };
+    const jmapPostUrl = await port.getJmapPostUrl();
+    const { ok, status, bodyText } = await postJmap(jmapPostUrl, capabilityJwt, envelope);
+    if (!ok) {
+        throw new Error(`Mailbox/query failed (HTTP ${status}): ${bodyText}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(bodyText);
+    }
+    catch {
+        throw new Error("Mailbox/query response is not valid JSON.");
+    }
+    const responses = parsed
+        .methodResponses;
+    const first = responses?.[0];
+    if (!Array.isArray(first) || first[0] === "error") {
+        throw new Error(`Mailbox/query failed: ${bodyText}`);
+    }
+    if (first[0] !== "Mailbox/query") {
+        throw new Error(`Mailbox/query failed: ${bodyText}`);
+    }
+    const payload = first[1];
+    const id = payload.ids?.[0];
+    if (typeof id !== "string" || id.length === 0) {
+        throw new Error("Mailbox/query returned no inbox mailbox id.");
+    }
+    return id;
+}
+function collectBlobUploadAccountIds(envelope) {
+    const ids = new Set();
+    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 aid = arg["accountId"];
+        if (typeof aid === "string" && aid.length > 0)
+            ids.add(aid);
+    }
+    return [...ids];
+}
+async function enforceJmapBlobUploadLimitsIfApplicable(session, envelope) {
+    if (!envelope.using.includes(JMAP_BLOB_URN))
+        return;
+    const hasUpload = envelope.methodCalls.some((c) => Array.isArray(c) && c[0] === "Blob/upload");
+    if (!hasUpload)
+        return;
+    const accountIds = collectBlobUploadAccountIds(envelope);
+    const limitsByAccount = new Map();
+    for (const id of accountIds) {
+        limitsByAccount.set(id, await session.getBlobUploadLimitsForAccount(id));
+    }
+    assertBlobUploadEnvelopeWithinLimits(envelope, limitsByAccount);
+}
+export async function postJmap(jmapPostUrl, capabilityJwt, envelope) {
+    const res = await fetch(jmapPostUrl, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${capabilityJwt}`,
+        },
+        body: JSON.stringify(envelope),
+    });
+    const bodyText = await res.text();
+    return { ok: res.ok, status: res.status, bodyText };
+}
+const JMAP_NEXT_HINTS = sharedHints?.jmap_next_hints ?? [
+    "Use jmap_request with Mailbox/get or Email/query to work with mail data.",
+    "Use presets with $VAR placeholders — $ACCOUNT_ID, $INBOX, and $INBOX_MAILBOX_ID come from the session; pass others via vars / --vars.",
+    "Call help for the JMAP cheatsheet and troubleshooting.",
+];
+/** Attach _next hints to a successful JMAP JSON object when parseable. */
+export function attachJmapNextHints(bodyText) {
+    try {
+        const obj = JSON.parse(bodyText);
+        if (obj && typeof obj === "object" && !Array.isArray(obj)) {
+            return JSON.stringify({ ...obj, _next: [...JMAP_NEXT_HINTS] }, null, 2);
+        }
+    }
+    catch {
+        // not JSON — return raw
+    }
+    return bodyText;
+}

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

@@ -0,0 +1,30 @@
+/** Keys allowed in MCP `vars` / skill `--vars` (without leading `$`). */
+export declare const USER_VAR_KEY_RE: RegExp;
+/**
+ * Parses a JSON object of string values (skill `--vars` / MCP `vars`).
+ * Throws `Error` with the same messages the CLI used to emit via `fail(...)`.
+ */
+export declare function parseUserVarsJson(jsonString: string): Record<string, string>;
+/** Matches `$FOO_BAR`; excludes JMAP keywords like `$draft` (lowercase). */
+export declare const VAR_PATTERN: RegExp;
+/** Names substituted from JMAP session / credentials when not overridden in `vars`. */
+export declare const SESSION_VAR_NAMES: Set<string>;
+export interface SubstituteVarsInput {
+    raw: string;
+    /** Caller-supplied values; keys are names without `$` (e.g. `TO`, `SUBJECT`). */
+    vars?: Record<string, string>;
+    /** Invoked only when the name appears in `raw`, is absent from `vars`, and a resolver exists. */
+    autoResolvers?: Record<string, () => Promise<string> | string>;
+}
+export interface SubstituteVarsResult {
+    text: string;
+}
+/** Unique variable names in order of first occurrence (without leading `$`). */
+export declare function findVarReferences(raw: string): string[];
+/**
+ * Replaces every `$VAR_NAME` in `raw` with the corresponding string.
+ * Single pass — values are not scanned for further `$` tokens.
+ * Throws if any referenced variable has no value (after vars + autoResolvers).
+ */
+export declare function substituteVars(input: SubstituteVarsInput): Promise<SubstituteVarsResult>;
+//# sourceMappingURL=agent-vars.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-vars.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/jmap/agent-vars.ts"],"names":[],"mappings":"AAEA,yEAAyE;AACzE,eAAO,MAAM,eAAe,QAAsB,CAAC;AAEnD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAyB5E;AAED,4EAA4E;AAC5E,eAAO,MAAM,WAAW,QAAyB,CAAC;AAMlD,uFAAuF;AACvF,eAAO,MAAM,iBAAiB,aAI5B,CAAC;AAEH,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9B,iGAAiG;IACjG,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,gFAAgF;AAChF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAWvD;AAeD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,oBAAoB,CAAC,CA+B/B"}

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

@@ -0,0 +1,96 @@
+// Variable substitution for JMAP presets / inline ops ($VAR_NAME tokens).
+/** Keys allowed in MCP `vars` / skill `--vars` (without leading `$`). */
+export const USER_VAR_KEY_RE = /^[A-Z][A-Z0-9_]*$/;
+/**
+ * Parses a JSON object of string values (skill `--vars` / MCP `vars`).
+ * Throws `Error` with the same messages the CLI used to emit via `fail(...)`.
+ */
+export function parseUserVarsJson(jsonString) {
+    let obj;
+    try {
+        obj = JSON.parse(jsonString);
+    }
+    catch (err) {
+        throw new Error(`--vars is not valid JSON: ${err.message}`);
+    }
+    if (!obj || typeof obj !== "object" || Array.isArray(obj)) {
+        throw new Error("--vars must be a JSON object of { VAR_NAME: string }.");
+    }
+    for (const [k, v] of Object.entries(obj)) {
+        if (!USER_VAR_KEY_RE.test(k)) {
+            throw new Error(`--vars key '${k}' must match /^[A-Z][A-Z0-9_]*$/.`);
+        }
+        if (typeof v !== "string") {
+            throw new Error(`--vars value for '${k}' must be a string.`);
+        }
+    }
+    return obj;
+}
+/** Matches `$FOO_BAR`; excludes JMAP keywords like `$draft` (lowercase). */
+export const VAR_PATTERN = /\$([A-Z][A-Z0-9_]*)/g;
+function varPattern() {
+    return new RegExp(VAR_PATTERN.source, VAR_PATTERN.flags);
+}
+/** Names substituted from JMAP session / credentials when not overridden in `vars`. */
+export const SESSION_VAR_NAMES = new Set([
+    "ACCOUNT_ID",
+    "INBOX",
+    "INBOX_MAILBOX_ID",
+]);
+/** Unique variable names in order of first occurrence (without leading `$`). */
+export function findVarReferences(raw) {
+    const seen = new Set();
+    const order = [];
+    for (const m of raw.matchAll(varPattern())) {
+        const name = m[1];
+        if (!seen.has(name)) {
+            seen.add(name);
+            order.push(name);
+        }
+    }
+    return order;
+}
+function formatMissingError(missing) {
+    const tokens = missing.map((n) => `$${n}`);
+    const hasSession = missing.some((n) => SESSION_VAR_NAMES.has(n));
+    let msg = `Missing values for variables: ${tokens.join(", ")}. ` +
+        "Pass custom placeholders in vars (MCP) or --vars (skill).";
+    if (hasSession) {
+        msg +=
+            " For $ACCOUNT_ID, $INBOX, and $INBOX_MAILBOX_ID, ensure register completed " +
+                "and credentials are valid, or pass overrides in vars.";
+    }
+    return new Error(msg);
+}
+/**
+ * Replaces every `$VAR_NAME` in `raw` with the corresponding string.
+ * Single pass — values are not scanned for further `$` tokens.
+ * Throws if any referenced variable has no value (after vars + autoResolvers).
+ */
+export async function substituteVars(input) {
+    const names = findVarReferences(input.raw);
+    if (names.length === 0) {
+        return { text: input.raw };
+    }
+    const userVars = input.vars ?? {};
+    const resolved = new Map();
+    for (const name of names) {
+        if (Object.prototype.hasOwnProperty.call(userVars, name)) {
+            resolved.set(name, userVars[name]);
+            continue;
+        }
+        const resolver = input.autoResolvers?.[name];
+        if (resolver) {
+            resolved.set(name, await resolver());
+            continue;
+        }
+    }
+    const missing = names.filter((n) => !resolved.has(n));
+    if (missing.length > 0) {
+        throw formatMissingError(missing);
+    }
+    const text = input.raw.replace(varPattern(), (_full, name) => {
+        return resolved.get(name);
+    });
+    return { text };
+}

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

@@ -0,0 +1,2 @@
+export declare const helpTopicAuth = "# Atomic Mail \u2014 Auth flow\n\nAuth is automatic after `register` (or when `credentials.json` + API key\nexist).\n\n1. **Challenge** \u2014 `POST /api/v1/challenge`, read challenge JWT from\n   `Authorization: Bearer <challengeJWT>`\n2. **Proof-of-work** \u2014 scrypt until difficulty satisfied\n3. **Session JWT** \u2014 `POST /api/v1/session` with challenge JWT in\n   `Authorization: Bearer ...` and PoW fields (`powHex`, `nonce`) in JSON\n   body; read session JWT from response `Authorization: Bearer ...` (1h TTL);\n   signup returns `apiKey` once\n4. **Capability JWT** \u2014 `POST /api/v1/capability` with session JWT in\n   `Authorization: Bearer ...`; read capability JWT from response\n   `Authorization: Bearer ...` (2 min TTL) used as the JMAP bearer\n\nJWTs are rotated before expiry and written back to disk.\n\n## Credential files (mode 0600)\n\n`credentials.json` \u2014 `{ apiKey, inboxId, authUrl, apiUrl, scryptSalt, uploadUrl, downloadUrl }`  \n`session.jwt` \u2014 session token  \n`capability.jwt` \u2014 capability token\n\n## Overriding defaults\n\n- `ATOMIC_MAIL_AUTH_URL` (default: `https://auth.atomicmail.ai`)\n- `ATOMIC_MAIL_API_URL` (default: `https://api.atomicmail.ai`)\n- `ATOMIC_MAIL_SCRYPT_SALT` (optional)\n- `ATOMIC_MAIL_API_KEY` (optional)\n- `ATOMIC_MAIL_CREDENTIALS_DIR` (default: `~/.atomicmail`)";
+//# sourceMappingURL=auth.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../../../../src/lib/agent/jmap/help-content/auth.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa,o0CA+BqC,CAAC"}

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

@@ -0,0 +1,33 @@
+// Help topic: auth (MCP help / AgentSkill help).
+export const helpTopicAuth = `\
+# Atomic Mail — Auth flow
+
+Auth is automatic after \`register\` (or when \`credentials.json\` + API key
+exist).
+
+1. **Challenge** — \`POST /api/v1/challenge\`, read challenge JWT from
+   \`Authorization: Bearer <challengeJWT>\`
+2. **Proof-of-work** — scrypt until difficulty satisfied
+3. **Session JWT** — \`POST /api/v1/session\` with challenge JWT in
+   \`Authorization: Bearer ...\` and PoW fields (\`powHex\`, \`nonce\`) in JSON
+   body; read session JWT from response \`Authorization: Bearer ...\` (1h TTL);
+   signup returns \`apiKey\` once
+4. **Capability JWT** — \`POST /api/v1/capability\` with session JWT in
+   \`Authorization: Bearer ...\`; read capability JWT from response
+   \`Authorization: Bearer ...\` (2 min TTL) used as the JMAP bearer
+
+JWTs are rotated before expiry and written back to disk.
+
+## Credential files (mode 0600)
+
+\`credentials.json\` — \`{ apiKey, inboxId, authUrl, apiUrl, scryptSalt, uploadUrl, downloadUrl }\`  
+\`session.jwt\` — session token  
+\`capability.jwt\` — capability token
+
+## Overriding defaults
+
+- \`ATOMIC_MAIL_AUTH_URL\` (default: \`https://auth.atomicmail.ai\`)
+- \`ATOMIC_MAIL_API_URL\` (default: \`https://api.atomicmail.ai\`)
+- \`ATOMIC_MAIL_SCRYPT_SALT\` (optional)
+- \`ATOMIC_MAIL_API_KEY\` (optional)
+- \`ATOMIC_MAIL_CREDENTIALS_DIR\` (default: \`~/.atomicmail\`)`;

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

@@ -0,0 +1,6 @@
+/** Prompt for hourly inbox jobs — agent fetches mail and stays available for follow-up. */
+export declare const INBOX_CRON_AGENT_PROMPT: string;
+/** Short block — embed in MCP instructions, register tool text, overview workflow. */
+export declare const postRegisterCronReminder = "AFTER REGISTER \u2014 INBOX POLLING\n  Choose the path that matches your runtime (help topic \"cron\"):\n  \u2022 Native cron (OpenClaw, Hermes, atomic-agent, \u2026): schedule an hourly AGENT turn with list_inbox.json in the prompt; wire MCP or AgentSkill into that agent. Do NOT cron atomicmail jmap_request alone.\n  \u2022 No native cron (Claude, Pi, Cursor, \u2026): do NOT work around this (no wrapper scripts, OS crontab/LaunchAgent, or cross-platform scheduling). Ask your operator to set up polling on a capable host, or remind them to fetch mail manually when needed.\n  \u2022 Forbidden: register in one runtime and schedule the cron job on another.";
+export declare const helpTopicCron = "# Inbox polling (after register)\n\nRegistration only creates credentials. For a useful inbox integration, inbound\nmail should be fetched and triaged about once per hour between interactive\nsessions.\n\n**Choose the path that matches your runtime \u2014 do not mix platforms.**\n\n## If your host supports scheduled jobs\n\nIf you have a **native** way to enable cron or recurring agent turns (OpenClaw,\nHermes, atomic-agent, and similar hosts), set up an hourly **agent** job after\nthe first successful `register`. The job must **invoke an AI agent** (not just the\nAtomic Mail CLI) to fetch and triage mail. Wire Atomic Mail MCP or AgentSkill\ninto that agent before scheduling.\n\nThe scheduled turn should call preset **list_inbox.json** (`Email/query` +\n`Email/get`, latest 50; built-ins `$ACCOUNT_ID`, `$INBOX_MAILBOX_ID` \u2014 no extra\n`vars`).\n\n## If your host does **not** support scheduled jobs\n\nExamples: Claude, Pi, Cursor, and other chat or terminal agents without a cron\nAPI.\n\n**Do not spend tokens trying to work around this** \u2014 no wrapper scripts, OS\ncrontab/LaunchAgent setup, or scheduling on a different platform on the agent's\nbehalf.\n\nAfter a successful `register`, do one of the following:\n\n1. **Ask your operator** to set up hourly inbox polling on a host that supports\n   it (share the examples below), **or**\n2. **Remind your operator** to fetch mail manually when they need updates\n   (`jmap_request` with `list_inbox.json`, or `atomicmail jmap_request\n   --ops-file list_inbox.json`).\n\n## Forbidden: cross-platform scheduling\n\nDo **not** register in one runtime and schedule the cron job on another. Example\nof forbidden behavior: Pi runs `register`, then creates an OpenClaw cron job.\nEither the same runtime that registered schedules polling, or the operator\nschedules it themselves on a capable host.\n\n## What not to do (any runtime)\n\n- **Raw CLI in crontab** \u2014 `atomicmail jmap_request --ops-file list_inbox.json`\n  alone only fetches JSON; no agent runs and nothing prompts the operator to\n  reply.\n- **Headless one-shot CLIs** \u2014 `claude -p`, `pi -p`, `agent -p`, `codex exec`,\n  `gemini -p` print and exit; the operator cannot continue the thread to reply\n  or forward.\n\n## Agent prompt (use in scheduled jobs or manual fetches)\n\n```text\nUse Atomic Mail to fetch my inbox (MCP jmap_request with ops_file list_inbox.json, or atomicmail jmap_request --ops-file list_inbox.json). Summarize new messages, highlight what needs a reply, and stay available \u2014 I may ask you to reply, forward, search, or dig into something important.\n```\n\n## Scheduling examples (for capable hosts or operators)\n\n| Your setup | Recommended approach |\n| --- | --- |\n| OpenClaw gateway | Built-in `openclaw cron` |\n| Hermes Agent | Install skill \u2192 `/suggestions` blueprint after `register` (or manual `hermes cron`) |\n| Atomic Bot (atomicbot.ai) | Same as OpenClaw or Hermes host |\n| atomic-agent | Built-in `atomic-agent task create` |\n| No native cron (Claude, Pi, Cursor, \u2026) | Ask operator to schedule on a capable host, or remind them to fetch manually |\n\n### OpenClaw\n\nDocs: https://docs.openclaw.ai/automation/cron-jobs\n\n```bash\nopenclaw cron add \\\n  --name \"atomicmail-inbox\" \\\n  --cron \"0 * * * *\" \\\n  --session isolated \\\n  --message \"Use Atomic Mail to fetch my inbox (MCP jmap_request with ops_file list_inbox.json, or atomicmail jmap_request --ops-file list_inbox.json). Summarize new messages, highlight what needs a reply, and stay available \u2014 I may ask you to reply, forward, search, or dig into something important.\" \\\n  --announce\n```\n\nManage: `openclaw cron list` \u00B7 test: `openclaw cron run <job-id>`\n\n### Hermes Agent\n\nSkill blueprints: https://hermes-agent.nousresearch.com/docs/developer-guide/creating-skills\n\nCron (manual fallback): https://hermes-agent.nousresearch.com/docs/user-guide/features/cron\n\n**Recommended:** Install the Atomic Mail Hermes skill \u2192 after `register`, accept\nthe hourly inbox blueprint via `/suggestions` (`no_agent: false`,\n`list_inbox.json`, `deliver: origin`). Do not cron raw `jmap_request` or use\n`--no-agent`.\n\n**Credentials:** Default `~/.hermes/atomicmail` (not `~/.atomicmail`). The skill\nlauncher sets `ATOMIC_MAIL_CREDENTIALS_DIR` when unset; override via env or\n`atomicmail.credentials_dir` config. Use `--credentials-dir` only for\nmulti-account setups.\n\n**Manual fallback:**\n\n```bash\nhermes cron create \"0 * * * *\" \\\n  \"Use Atomic Mail to fetch my inbox (MCP jmap_request with ops_file list_inbox.json, or atomicmail jmap_request --ops-file list_inbox.json). Summarize new messages, highlight what needs a reply, and stay available \u2014 I may ask you to reply, forward, search, or dig into something important.\" \\\n  --name \"atomicmail-inbox\" \\\n  --deliver origin\n```\n\nManage: `hermes cron list` \u00B7 test: `hermes cron run <job-id>`\n\n### atomic-agent\n\n```bash\natomic-agent task create \\\n  --cron \"0 * * * *\" \\\n  --message \"Use Atomic Mail to fetch my inbox (MCP jmap_request with ops_file list_inbox.json, or atomicmail jmap_request --ops-file list_inbox.json). Summarize new messages, highlight what needs a reply, and stay available \u2014 I may ask you to reply, forward, search, or dig into something important.\"\n```\n\nManage: `atomic-agent task list`\n\n## Verify setup\n\n1. `register` succeeded; Atomic Mail MCP or AgentSkill is available to the agent.\n2. Run the agent prompt **once manually**; confirm inbox fetch and follow-up work.\n3. Confirm the job is registered (`openclaw cron list`, `hermes cron list`,\n   `atomic-agent task list`).\n\n## For operators: OS scheduling on terminal hosts\n\nThis section is **operator documentation**, not an agent obligation. Chat agents\nwithout native cron should **not** attempt OS scheduling themselves.\n\nIf you (the operator) run a **terminal CLI agent** without OpenClaw, Hermes, or\nsimilar, the scheduler must **start an interactive session** with the agent\nprompt \u2014 not call `atomicmail` directly.\n\n| Agent | Start interactively | Avoid for inbox polling |\n| --- | --- | --- |\n| Claude Code | `claude \"prompt\"` | `claude -p` |\n| Pi | `pi \"prompt\"` | `pi -p` |\n| Cursor CLI | `agent \"prompt\"` | `agent -p` |\n\nOS options: wrapper script + user crontab, macOS LaunchAgent, or Linux systemd\nuser timer \u2014 launching a terminal emulator with an interactive agent session.";
+//# sourceMappingURL=cron.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cron.d.ts","sourceRoot":"","sources":["../../../../../src/lib/agent/jmap/help-content/cron.ts"],"names":[],"mappings":"AAEA,2FAA2F;AAC3F,eAAO,MAAM,uBAAuB,QAIyC,CAAC;AAE9E,sFAAsF;AACtF,eAAO,MAAM,wBAAwB,ypBAKwC,CAAC;AAE9E,eAAO,MAAM,aAAa,y2MAiJoD,CAAC"}