@atomicmail/mcp 0.2.0 → 0.2.2

package/esm/lib/{src → agent/jmap}/agent-help-content.js

@@ -16,10 +16,12 @@ Three operations only:
 2. **jmap_request** — Send a JMAP method-call batch. Auth and JWT rotation are
    automatic. Pass inline \`ops\` JSON or an \`ops_file\` preset path (same
    substitution applies to both). Uppercase tokens like \`$ACCOUNT_ID\`,
-   \`$INBOX\`, \`$TO\`, \`$SUBJECT\` are replaced before the request is sent.
-   \`$ACCOUNT_ID\` / \`$INBOX\` come from the JMAP session and credentials; pass
-   any other names via MCP \`vars\` or skill \`--vars\`.
-3. **help** — This documentation (optional \`topic\` / \`--topic\`).
+   \`$INBOX\`, \`$UPLOAD_URL\`, \`$DOWNLOAD_URL\`, \`$TO\`, \`$SUBJECT\` are
+   replaced before the request is sent. \`$ACCOUNT_ID\` / \`$INBOX\` /
+   \`$UPLOAD_URL\` / \`$DOWNLOAD_URL\` come from the JMAP session and
+   credentials; pass any other names via MCP \`vars\` or skill \`--vars\`.
+3. **help** — This documentation (optional \`topic\` / \`--topic\`), or the
+   published package README (\`topic\` / \`--topic\` \`readme\`).
 
 ## Typical workflow
 
@@ -29,7 +31,7 @@ Three operations only:
 3. If stuck, read error hints and call \`help\`.
 
 Available topics: overview, installation, auth, jmap_cheatsheet, tools,
-presets, troubleshooting.`,
+presets, troubleshooting. Use \`readme\` for the npm package \`README.md\`.`,
     installation: `\
 # Atomic Mail — Installation
 
@@ -51,7 +53,8 @@ presets, troubleshooting.`,
 \`\`\`bash
 npx --package=@atomicmail/agent-skill atomicmail register --username "myagent"
 npx --package=@atomicmail/agent-skill atomicmail jmap_request \\
-  --ops-file send_hello.json
+  --ops-file list_inbox.json \\
+  --vars '{"COUNT":"10"}'
 npx --package=@atomicmail/agent-skill atomicmail help
 \`\`\`
 
@@ -85,18 +88,22 @@ See each package README for details.`,
 Auth is automatic after \`register\` (or when \`credentials.json\` + API key
 exist).
 
-1. **Challenge** — \`POST /api/v1/challenge\`
+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\` (4h TTL); signup returns a
-   one-time \`apiKey\`
-4. **Capability JWT** — \`POST /api/v1/capability\` (2 min TTL) used as the
-   JMAP bearer
+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 }\`  
+\`credentials.json\` — \`{ apiKey, inboxId, authUrl, apiUrl, scryptSalt, uploadUrl, downloadUrl }\`  
 \`session.jwt\` — session token  
 \`capability.jwt\` — capability token
 
@@ -118,7 +125,8 @@ JWTs are rotated before expiry and written back to disk.
 
 ## Examples
 
-Use \`$ACCOUNT_ID\` and \`$INBOX\` for session fields; use \`$TO\`, \`$SUBJECT\`,
+Use \`$ACCOUNT_ID\`, \`$INBOX\`, \`$UPLOAD_URL\`, and \`$DOWNLOAD_URL\` for
+session fields; use \`$TO\`, \`$SUBJECT\`,
 etc., and supply values via MCP \`vars\` or \`--vars\` (JSON object of strings).
 
 ### Mailboxes
@@ -173,15 +181,23 @@ replaces credentials in the directory and registers a new inbox.
 **Skill:** \`help [--topic TOPIC]\`
 
 Topics: overview, installation, auth, jmap_cheatsheet, tools, presets,
-troubleshooting.`,
+troubleshooting. Topic \`readme\` prints the published package \`README.md\`
+(same layout as npm; requires install from npm).`,
     presets: `\
 # JMAP presets
 
 Save a method-call array or a full \`{ "using", "methodCalls" }\` envelope
 as JSON, then pass \`ops_file\` (MCP) or \`--ops-file\` (skill).
 
-Relative paths resolve against the credential directory (MCP) or current
-\`--credentials-dir\` (skill).
+Relative paths first resolve against the credential directory (MCP) or current
+\`--credentials-dir\` (skill). If not found, the runtime falls back to bundled
+presets that ship in both npm packages.
+
+## Bundled presets
+
+- \`send_mail.json\` — sends one email using \`$TO\`, \`$SUBJECT\`, \`$BODY\`.
+- \`list_inbox.json\` — returns the latest \`$COUNT\` inbox messages.
+- \`reply.json\` — replies in-thread using \`$MAIL_ID\` and \`$BODY\`.
 
 ## Placeholders
 
@@ -191,11 +207,14 @@ keywords like \`$draft\` stay untouched).
 - \`$ACCOUNT_ID\` — primary mail account id (from \`GET /.well-known/jmap\` when
   referenced).
 - \`$INBOX\` — inbox email address from credentials.
+- \`$UPLOAD_URL\` — RFC 8620 upload URL template from JMAP session.
+- \`$DOWNLOAD_URL\` — RFC 8620 download URL template from JMAP session.
 - Any other \`$FOO\` — must appear in MCP \`vars\` or skill \`--vars\` as
   \`"FOO": "..."\` (string values only; JSON escaping in the preset body is your
   responsibility).
 
-You may override \`ACCOUNT_ID\` / \`INBOX\` via \`vars\` / \`--vars\` if needed.`,
+You may override \`ACCOUNT_ID\` / \`INBOX\` / \`UPLOAD_URL\` / \`DOWNLOAD_URL\`
+via \`vars\` / \`--vars\` if needed.`,
     troubleshooting: `\
 # Troubleshooting
 
@@ -226,11 +245,19 @@ Pass every custom placeholder in MCP \`vars\` or \`--vars\` as a JSON object of
 strings. Ensure \`register\` completed so \`$ACCOUNT_ID\` / \`$INBOX\` can resolve.`,
 };
 export const HELP_TOPIC_LIST = Object.keys(HELP_TOPICS);
+export function normalizeHelpTopic(topic) {
+    return topic.toLowerCase().replace(/[\s-]/g, "_");
+}
 export function getHelp(topic) {
     if (!topic) {
         return HELP_TOPICS["overview"];
     }
-    const key = topic.toLowerCase().replace(/[\s-]/g, "_");
+    const key = normalizeHelpTopic(topic);
+    if (key === "readme") {
+        return ("Topic \"readme\" prints the package README.md from the npm install. " +
+            "From MCP use {\"topic\":\"readme\"}; from the CLI: " +
+            "`atomicmail help --topic readme`.");
+    }
     return (HELP_TOPICS[key] ??
-        `Unknown topic "${topic}". Available topics: ${HELP_TOPIC_LIST.join(", ")}`);
+        `Unknown topic "${topic}". Available topics: ${HELP_TOPIC_LIST.join(", ")}, readme`);
 }

package/esm/lib/{src → agent/jmap}/agent-jmap.d.ts

@@ -8,6 +8,11 @@ export declare function parseJmapEnvelope(raw: string, defaultUsing: string[], s
 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;
 export declare function fetchJmapWellKnown(apiUrl: string, capabilityJwt: string): Promise<Record<string, unknown>>;
 /** Minimal surface for JMAP execution (implemented by AgentSession). */
 export interface JmapSessionPort {
@@ -18,6 +23,8 @@ export interface JmapSessionPort {
     getPrimaryMailAccountId(): Promise<string>;
     getCapabilityToken(): Promise<string>;
     readonly currentInboxId?: string;
+    readonly currentUploadUrl?: string;
+    readonly currentDownloadUrl?: string;
 }
 export interface RunJmapRequestInput {
     session: JmapSessionPort;

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":"AASA,eAAO,MAAM,kBAAkB,qEAGrB,CAAC;AAEX,eAAO,MAAM,aAAa,EAAG,2BAAoC,CAAC;AAElE,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,EAAE,OAAO,EAAE,CAAC;CACxB;AAED,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,EACX,YAAY,EAAE,MAAM,EAAE,EACtB,MAAM,EAAE,MAAM,GACb,YAAY,CAyBd;AAED,wBAAgB,kBAAkB,CAChC,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,GACd,MAAM,CAER;AAED,wBAAsB,WAAW,CAC/B,aAAa,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC,CAiBjB;AA8CD,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,MAAM,CAcR;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,iBAAiB,CAUnB;AAED,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAclC;AAED,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE;QAAE,eAAe,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,uBAAuB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IAC3C,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;IACtC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,kBAAkB,CAAC,EAAE,MAAM,CAAC;CACtC;AAED,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,eAAe,CAAC;IACzB,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,wFAAwF;IACxF,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/B;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAmD5D;AAED,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,YAAY,GACrB,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAY5D;AAQD,0EAA0E;AAC1E,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAU5D"}

package/esm/lib/{src → agent/jmap}/agent-jmap.js

@@ -1,7 +1,8 @@
 // JMAP envelope parsing, preset paths, $VAR substitution, and HTTP helpers.
 import { readFile } from "node:fs/promises";
-import { isAbsolute, resolve as resolvePath } from "node:path";
-import { readCredentials } from "./agent-credentials-store.js";
+import { dirname, isAbsolute, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+import { readCredentials } from "../session/agent-credentials-store.js";
 import { substituteVars } from "./agent-vars.js";
 export const DEFAULT_JMAP_USING = [
     "urn:ietf:params:jmap:core",
@@ -36,7 +37,50 @@ export function resolveOpsFilePath(credentialDir, opsFile) {
 }
 export async function readOpsFile(credentialDir, opsFile) {
     const filePath = resolveOpsFilePath(credentialDir, opsFile);
-    return await readFile(filePath, "utf-8");
+    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) {
+        return await readFile(filePath, "utf-8");
+    }
+    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, "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"];
@@ -49,6 +93,17 @@ export function extractPrimaryMailAccountId(session) {
     }
     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 };
+}
 export async function fetchJmapWellKnown(apiUrl, capabilityJwt) {
     const base = apiUrl.replace(/\/+$/, "");
     const res = await fetch(`${base}/.well-known/jmap`, {
@@ -76,6 +131,11 @@ export async function runJmapRequest(input) {
             ACCOUNT_ID: () => input.session.getPrimaryMailAccountId(),
             INBOX: async () => input.session.currentInboxId ??
                 (await readCredentials(input.session.files.credentialsFile)).inboxId,
+            UPLOAD_URL: async () => input.session.currentUploadUrl ??
+                (await readCredentials(input.session.files.credentialsFile)).uploadUrl,
+            DOWNLOAD_URL: async () => input.session.currentDownloadUrl ??
+                (await readCredentials(input.session.files.credentialsFile))
+                    .downloadUrl,
         },
     });
     const envelope = parseJmapEnvelope(raw, input.defaultUsing, input.sourceLabel);

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,4EAA4E;AAC5E,eAAO,MAAM,WAAW,QAAyB,CAAC;AAMlD,uFAAuF;AACvF,eAAO,MAAM,iBAAiB,aAA2C,CAAC;AAE1E,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/{src → agent/session}/agent-credentials-store.d.ts

@@ -4,6 +4,8 @@ export interface Credentials {
     authUrl: string;
     apiUrl: string;
     scryptSalt: string;
+    uploadUrl: string;
+    downloadUrl: string;
 }
 export interface SkillFiles {
     credentialsFile: string;

package/esm/lib/agent/session/agent-credentials-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-credentials-store.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/session/agent-credentials-store.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,UAAU;IACzB,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAOjE;AAMD,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAmCxE;AAED,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC,CAOlC;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAG3E;AAED,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAO7B;AAED,0EAA0E;AAC1E,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/esm/lib/{src → agent/session}/agent-credentials-store.js

@@ -39,6 +39,8 @@ export async function readCredentials(path) {
         "authUrl",
         "apiUrl",
         "scryptSalt",
+        "uploadUrl",
+        "downloadUrl",
     ];
     for (const k of required) {
         if (typeof obj[k] !== "string" || obj[k].length === 0) {

package/esm/lib/agent/session/agent-resolve-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-resolve-config.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/session/agent-resolve-config.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,KAAK,UAAU,EAEhB,MAAM,8BAA8B,CAAC;AAEtC,MAAM,MAAM,YAAY,GACpB,kBAAkB,GAClB,KAAK,GACL,OAAO,GACP,YAAY,CAAC;AAEjB,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAW7C;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,IAAI,OAAO,CACxD,mBAAmB,CACpB,CAoDA"}

package/esm/lib/{src → agent/session}/agent-resolve-config.js

@@ -1,6 +1,6 @@
 // Resolve MCP / process credential dir + URLs from env + credentials.json.
 import process from "node:process";
-import { DEFAULT_POW_SCRYPT_SALT_HEX } from "./consts.js";
+import { DEFAULT_POW_SCRYPT_SALT_HEX } from "../../core/consts.js";
 import { defaultFilesFromOutDir, tryReadCredentials, } from "./agent-credentials-store.js";
 /**
  * Default credential directory:

package/esm/lib/{src → agent/session}/agent-session.d.ts

@@ -28,16 +28,21 @@ export declare class AgentSession {
     private sessionJWT;
     private capabilityJWT;
     private cachedMailAccountId;
+    private cachedUploadUrl;
+    private cachedDownloadUrl;
     constructor(cfg: AgentSessionConfig);
     static create(cfg: AgentSessionConfig): Promise<AgentSession>;
     get hasApiKey(): boolean;
     get currentInboxId(): string | undefined;
+    get currentUploadUrl(): string | undefined;
+    get currentDownloadUrl(): string | undefined;
     private loadFromDisk;
     /**
      * Primary JMAP mail accountId from GET /.well-known/jmap (cached).
      */
     getPrimaryMailAccountId(): Promise<string>;
     invalidateJmapSessionCache(): void;
+    private refreshJmapSessionData;
     /**
      * Register or return existing inbox when username matches (idempotent).
      * Different username replaces on-disk credentials and creates a new inbox.

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/session/agent-session.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,UAAU,EAMhB,MAAM,8BAA8B,CAAC;AActC,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,UAAU,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAMD,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAKtD;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,MAAM,CAAqB;IACnC,OAAO,CAAC,OAAO,CAAqB;IACpC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAE3B,OAAO,CAAC,UAAU,CAAqB;IACvC,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,mBAAmB,CAAqB;IAChD,OAAO,CAAC,eAAe,CAAqB;IAC5C,OAAO,CAAC,iBAAiB,CAAqB;gBAElC,GAAG,EAAE,kBAAkB;WAUtB,MAAM,CAAC,GAAG,EAAE,kBAAkB,GAAG,OAAO,CAAC,YAAY,CAAC;IAMnE,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,cAAc,IAAI,MAAM,GAAG,SAAS,CAEvC;IAED,IAAI,gBAAgB,IAAI,MAAM,GAAG,SAAS,CAEzC;IAED,IAAI,kBAAkB,IAAI,MAAM,GAAG,SAAS,CAE3C;YAEa,YAAY;IAY1B;;OAEG;IACG,uBAAuB,IAAI,OAAO,CAAC,MAAM,CAAC;IAehD,0BAA0B,IAAI,IAAI;YAMpB,sBAAsB;IASpC;;;OAGG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IA8EnD,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC;YA4B7B,aAAa;IA2B3B,OAAO,IAAI,IAAI;CAGhB;AAED,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,UAAU,CAAC;IAClB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED,0EAA0E;AAC1E,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,2BAA2B,GACjC,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CA6B9B"}

package/esm/lib/{src → agent/session}/agent-session.js

@@ -1,8 +1,8 @@
 // Stateful PoW + capability JWT + optional cached JMAP session (accountId).
 import { tryReadCredentials, tryReadJwtFile, unlinkCredentialArtifacts, writeCredentials, writeJwtFile, } from "./agent-credentials-store.js";
-import { CAPABILITY_SAFETY_MARGIN_MS, decodeJwtPayload, isJwtExpired, SESSION_SAFETY_MARGIN_MS, } from "./agent-jwt.js";
-import { extractPrimaryMailAccountId, fetchJmapWellKnown, } from "./agent-jmap.js";
-import { fetchCapability, performPoWAndSession } from "./agent-auth-http.js";
+import { CAPABILITY_SAFETY_MARGIN_MS, decodeJwtPayload, isJwtExpired, SESSION_SAFETY_MARGIN_MS, } from "../auth/agent-jwt.js";
+import { extractBlobEndpoints, extractPrimaryMailAccountId, fetchJmapWellKnown, } from "../jmap/agent-jmap.js";
+import { fetchCapability, performPoWAndSession } from "../auth/agent-auth-http.js";
 function normalizeUsername(u) {
     return u.trim().toLowerCase();
 }
@@ -24,6 +24,8 @@ export class AgentSession {
     sessionJWT;
     capabilityJWT;
     cachedMailAccountId;
+    cachedUploadUrl;
+    cachedDownloadUrl;
     constructor(cfg) {
         this.authUrl = cfg.authUrl.replace(/\/+$/, "");
         this.apiUrl = cfg.apiUrl.replace(/\/+$/, "");
@@ -44,6 +46,12 @@ export class AgentSession {
     get currentInboxId() {
         return this.inboxId;
     }
+    get currentUploadUrl() {
+        return this.cachedUploadUrl;
+    }
+    get currentDownloadUrl() {
+        return this.cachedDownloadUrl;
+    }
     async loadFromDisk() {
         this.sessionJWT = await tryReadJwtFile(this.files.sessionFile);
         this.capabilityJWT = await tryReadJwtFile(this.files.capabilityFile);
@@ -51,22 +59,37 @@ export class AgentSession {
         if (disk) {
             this.apiKey = this.apiKey ?? disk.apiKey;
             this.inboxId = this.inboxId ?? disk.inboxId;
+            this.cachedUploadUrl = disk.uploadUrl;
+            this.cachedDownloadUrl = disk.downloadUrl;
         }
     }
     /**
      * Primary JMAP mail accountId from GET /.well-known/jmap (cached).
      */
     async getPrimaryMailAccountId() {
-        if (this.cachedMailAccountId)
+        if (this.cachedMailAccountId &&
+            this.cachedUploadUrl &&
+            this.cachedDownloadUrl) {
             return this.cachedMailAccountId;
-        const cap = await this.getCapabilityToken();
-        const session = await fetchJmapWellKnown(this.apiUrl, cap);
-        const id = extractPrimaryMailAccountId(session);
-        this.cachedMailAccountId = id;
-        return id;
+        }
+        await this.refreshJmapSessionData();
+        if (!this.cachedMailAccountId) {
+            throw new Error("JMAP session missing primary mail account id.");
+        }
+        return this.cachedMailAccountId;
     }
     invalidateJmapSessionCache() {
         this.cachedMailAccountId = undefined;
+        this.cachedUploadUrl = undefined;
+        this.cachedDownloadUrl = undefined;
+    }
+    async refreshJmapSessionData() {
+        const cap = await this.getCapabilityToken();
+        const session = await fetchJmapWellKnown(this.apiUrl, cap);
+        this.cachedMailAccountId = extractPrimaryMailAccountId(session);
+        const blobs = extractBlobEndpoints(session);
+        this.cachedUploadUrl = blobs.uploadUrl;
+        this.cachedDownloadUrl = blobs.downloadUrl;
     }
     /**
      * Register or return existing inbox when username matches (idempotent).
@@ -115,15 +138,22 @@ export class AgentSession {
         }
         this.inboxId = claims.inboxId;
         this.cachedMailAccountId = undefined;
+        this.cachedUploadUrl = undefined;
+        this.cachedDownloadUrl = undefined;
+        const accountId = await this.getPrimaryMailAccountId();
+        if (!this.cachedUploadUrl || !this.cachedDownloadUrl) {
+            throw new Error("JMAP session did not provide upload/download URLs.");
+        }
         const creds = {
             apiKey: this.apiKey,
             inboxId: this.inboxId,
             authUrl: this.authUrl,
             apiUrl: this.apiUrl,
             scryptSalt: this.scryptSalt,
+            uploadUrl: this.cachedUploadUrl,
+            downloadUrl: this.cachedDownloadUrl,
         };
         await writeCredentials(this.files.credentialsFile, creds);
-        const accountId = await this.getPrimaryMailAccountId();
         return {
             inbox: this.inboxId,
             accountId,
@@ -171,6 +201,8 @@ export class AgentSession {
         this.sessionJWT = result.sessionJWT;
         this.capabilityJWT = undefined;
         this.cachedMailAccountId = undefined;
+        this.cachedUploadUrl = undefined;
+        this.cachedDownloadUrl = undefined;
         await writeJwtFile(this.files.sessionFile, this.sessionJWT);
     }
     destroy() {
@@ -193,12 +225,16 @@ export async function persistLoginWithApiKey(input) {
     if (typeof inboxId !== "string" || inboxId.length === 0) {
         throw new Error("Capability JWT did not contain an inboxId claim.");
     }
+    const jmapSession = await fetchJmapWellKnown(apiUrl, capabilityJWT);
+    const blobs = extractBlobEndpoints(jmapSession);
     await writeCredentials(input.files.credentialsFile, {
         apiKey: input.apiKey,
         inboxId,
         authUrl,
         apiUrl,
         scryptSalt: input.scryptSalt,
+        uploadUrl: blobs.uploadUrl,
+        downloadUrl: blobs.downloadUrl,
     });
     await writeJwtFile(input.files.sessionFile, session.sessionJWT);
     await writeJwtFile(input.files.capabilityFile, capabilityJWT);

package/esm/lib/core/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../../../src/lib/core/consts.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,qEAC4B,CAAC;AAErE,eAAO,MAAM,UAAU,OAAO,CAAC;AAC/B,eAAO,MAAM,UAAU,QAAkB,CAAC;AAC1C,eAAO,MAAM,WAAW,QAAkB,CAAC;AAC3C,eAAO,MAAM,UAAU,QAAmB,CAAC;AAC3C,eAAO,MAAM,YAAY,QAAkB,CAAC;AAC5C,eAAO,MAAM,WAAW,QAAmB,CAAC"}

package/esm/lib/core/read-npm-package-readme.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Reads README.md from the npm package root (next to package.json).
+ * Intended for published @atomicmail/mcp and @atomicmail/agent-skill layouts.
+ */
+export declare function readNpmPackageReadme(): Promise<string>;
+//# sourceMappingURL=read-npm-package-readme.d.ts.map

package/esm/lib/core/read-npm-package-readme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-npm-package-readme.d.ts","sourceRoot":"","sources":["../../../src/lib/core/read-npm-package-readme.ts"],"names":[],"mappings":"AAiBA;;;GAGG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CA+C5D"}

package/esm/lib/core/read-npm-package-readme.js

@@ -0,0 +1,66 @@
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+const MAX_DEPTH = 16;
+const ATOMICMAIL_NPM_NAMES = new Set([
+    "@atomicmail/mcp",
+    "@atomicmail/agent-skill",
+]);
+function isEnoent(err) {
+    if (!(err instanceof Error))
+        return false;
+    const code = err.code;
+    return code === "ENOENT" || code === "ENOTDIR";
+}
+/**
+ * Reads README.md from the npm package root (next to package.json).
+ * Intended for published @atomicmail/mcp and @atomicmail/agent-skill layouts.
+ */
+export async function readNpmPackageReadme() {
+    const moduleDir = dirname(fileURLToPath(globalThis[Symbol.for("import-meta-ponyfill-esmodule")](import.meta).url));
+    let currentDir = moduleDir;
+    for (let i = 0; i < MAX_DEPTH; i++) {
+        const pkgPath = resolve(currentDir, "package.json");
+        const readmePath = resolve(currentDir, "README.md");
+        let pkgRaw;
+        try {
+            pkgRaw = await readFile(pkgPath, "utf-8");
+        }
+        catch (err) {
+            if (!isEnoent(err))
+                throw err;
+            const parent = resolve(currentDir, "..");
+            if (parent === currentDir)
+                break;
+            currentDir = parent;
+            continue;
+        }
+        let name;
+        try {
+            name = JSON.parse(pkgRaw).name;
+        }
+        catch {
+            name = undefined;
+        }
+        if (!name || !ATOMICMAIL_NPM_NAMES.has(name)) {
+            const parent = resolve(currentDir, "..");
+            if (parent === currentDir)
+                break;
+            currentDir = parent;
+            continue;
+        }
+        try {
+            return await readFile(readmePath, "utf-8");
+        }
+        catch (err) {
+            if (!isEnoent(err))
+                throw err;
+        }
+        const parent = resolve(currentDir, "..");
+        if (parent === currentDir)
+            break;
+        currentDir = parent;
+    }
+    throw new Error("Could not find Atomic Mail package README.md — use a published npm install " +
+        "(@atomicmail/mcp or @atomicmail/agent-skill) for --topic readme.");
+}

package/esm/lib/core/types.d.ts

@@ -0,0 +1,2 @@
+export type MaybePromise<R> = R | Promise<R>;
+//# sourceMappingURL=types.d.ts.map

package/esm/lib/core/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/core/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC"}

package/esm/lib/core/types.js

@@ -0,0 +1 @@
+export {};

package/esm/lib/core/utils.d.ts

@@ -0,0 +1,10 @@
+import type { MaybePromise } from "./types.js";
+export declare function delay(ms: number): Promise<void>;
+export type RetryCfg = {
+    maxTimeoutMs?: number;
+    startTimeoutMs?: number;
+    backoffMul?: number;
+    onBeforeRetry?: (e: unknown) => MaybePromise<void>;
+};
+export declare function retry<R>(fn: () => MaybePromise<R>, config: RetryCfg): Promise<R>;
+//# sourceMappingURL=utils.d.ts.map

package/esm/lib/core/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../../src/lib/core/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C;AAED,MAAM,MAAM,QAAQ,GAAG;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,aAAa,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,YAAY,CAAC,IAAI,CAAC,CAAC;CACpD,CAAC;AASF,wBAAsB,KAAK,CAAC,CAAC,EAC3B,EAAE,EAAE,MAAM,YAAY,CAAC,CAAC,CAAC,EACzB,MAAM,EAAE,QAAQ,GACf,OAAO,CAAC,CAAC,CAAC,CAgBZ"}

package/esm/lib/core/utils.js

@@ -0,0 +1,28 @@
+import { ONE_SEC_MS } from "./consts.js";
+export function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+const defaultCfg = {
+    maxTimeoutMs: ONE_SEC_MS * 32,
+    startTimeoutMs: ONE_SEC_MS,
+    backoffMul: 2,
+};
+// retry with exponential backoff, retries the fn on throw, re-throws on max backoff
+export async function retry(fn, config) {
+    const cfg = { ...defaultCfg, ...config };
+    let curTimeoutMs = cfg.startTimeoutMs;
+    while (true) {
+        try {
+            const res = await fn();
+            return res;
+        }
+        catch (e) {
+            if (cfg.onBeforeRetry)
+                await cfg.onBeforeRetry(e);
+            if (curTimeoutMs > cfg.maxTimeoutMs)
+                throw e;
+            await delay(curTimeoutMs);
+            curTimeoutMs = Math.floor(curTimeoutMs * cfg.backoffMul);
+        }
+    }
+}

package/esm/lib/mod.d.ts

@@ -0,0 +1,15 @@
+export * from "./network/auth-client.js";
+export * from "./core/utils.js";
+export * from "./core/read-npm-package-readme.js";
+export * from "./core/consts.js";
+export * from "./core/types.js";
+export * from "./agent/session/agent-credentials-store.js";
+export * from "./agent/auth/agent-jwt.js";
+export * from "./agent/auth/agent-pow.js";
+export * from "./agent/auth/agent-auth-http.js";
+export * from "./agent/jmap/agent-jmap.js";
+export * from "./agent/session/agent-session.js";
+export * from "./agent/session/agent-resolve-config.js";
+export * from "./agent/jmap/agent-help-content.js";
+export * from "./agent/jmap/agent-vars.js";
+//# sourceMappingURL=mod.d.ts.map

package/esm/lib/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/lib/mod.ts"],"names":[],"mappings":"AAAA,cAAc,0BAA0B,CAAC;AACzC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mCAAmC,CAAC;AAClD,cAAc,kBAAkB,CAAC;AACjC,cAAc,iBAAiB,CAAC;AAEhC,cAAc,4CAA4C,CAAC;AAC3D,cAAc,2BAA2B,CAAC;AAC1C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,iCAAiC,CAAC;AAChD,cAAc,4BAA4B,CAAC;AAC3C,cAAc,kCAAkC,CAAC;AACjD,cAAc,yCAAyC,CAAC;AACxD,cAAc,oCAAoC,CAAC;AACnD,cAAc,4BAA4B,CAAC"}

package/esm/lib/mod.js

@@ -0,0 +1,14 @@
+export * from "./network/auth-client.js";
+export * from "./core/utils.js";
+export * from "./core/read-npm-package-readme.js";
+export * from "./core/consts.js";
+export * from "./core/types.js";
+export * from "./agent/session/agent-credentials-store.js";
+export * from "./agent/auth/agent-jwt.js";
+export * from "./agent/auth/agent-pow.js";
+export * from "./agent/auth/agent-auth-http.js";
+export * from "./agent/jmap/agent-jmap.js";
+export * from "./agent/session/agent-session.js";
+export * from "./agent/session/agent-resolve-config.js";
+export * from "./agent/jmap/agent-help-content.js";
+export * from "./agent/jmap/agent-vars.js";