@atomicmail/agent-skill 0.2.1 → 0.2.2

package/README.md

@@ -1,3 +1,7 @@
+---
+description: Install and run the @atomicmail/agent-skill CLI (register, jmap_request, help) for shell-capable agents and automation.
+---
+
 # @atomicmail/agent-skill
 
 Atomic Mail AgentSkill CLI for shell-capable AI agents. It exposes three

package/SKILL.md

@@ -13,7 +13,8 @@ rotation. This skill ships a single CLI entrypoint with three commands:
 
 - Register a new inbox or log in with an existing API key.
 - Send JMAP batches (inline JSON or preset files).
-- Read built-in documentation (JMAP cheatsheet, presets, troubleshooting).
+- Read built-in documentation (JMAP cheatsheet, presets, troubleshooting) or
+  the package README (`atomicmail help --topic readme`).
 
 ## Commands
 
@@ -57,9 +58,10 @@ npx --package=@atomicmail/agent-skill atomicmail jmap_request \
   --ops '[["Mailbox/get", {"accountId": "$ACCOUNT_ID"}, "m0"]]'
 ```
 
-`$ACCOUNT_ID` and `$INBOX` resolve from the session/credentials. Other
-placeholders such as `$TO` or `$SUBJECT` require `--vars` with a JSON object of
-strings (same substitution applies to `--ops` and `--ops-file`).
+`$ACCOUNT_ID`, `$INBOX`, `$UPLOAD_URL`, and `$DOWNLOAD_URL` resolve from the
+session/credentials. Other placeholders such as `$TO` or `$SUBJECT` require
+`--vars` with a JSON object of strings (same substitution applies to `--ops` and
+`--ops-file`).
 
 Preset file:
 
@@ -94,6 +96,42 @@ npx --package=@atomicmail/agent-skill atomicmail help --topic jmap_cheatsheet
 - `credentials.json` holds the API key (mode `0600`). Do not commit it.
 - JWT files are bearer secrets — do not log them.
 
+## Attachments and blobs
+
+### Inline blobs in JMAP (RFC 9404)
+
+Use `Blob/upload` and `Blob/get` through `jmap_request` by adding
+`urn:ietf:params:jmap:blob` to `using`.
+
+```bash
+npx --package=@atomicmail/agent-skill atomicmail jmap_request \
+  --ops '{
+    "using":[
+      "urn:ietf:params:jmap:core",
+      "urn:ietf:params:jmap:mail",
+      "urn:ietf:params:jmap:submission",
+      "urn:ietf:params:jmap:blob"
+    ],
+    "methodCalls":[
+      ["Blob/upload",{
+        "accountId":"$ACCOUNT_ID",
+        "create":{"b1":{"data:asText":"Hello attachment","type":"text/plain"}}
+      },"b0"]
+    ]
+  }'
+```
+
+### Separate upload/download templates (RFC 8620)
+
+`credentials.json` stores `uploadUrl` and `downloadUrl` from
+`GET /.well-known/jmap`.
+
+- `$UPLOAD_URL` is the RFC 8620 upload template.
+- `$DOWNLOAD_URL` is the RFC 8620 download template.
+
+Use these placeholders when building out-of-band blob transfer steps and attach
+the resulting `blobId` in follow-up JMAP calls.
+
 ## Overriding defaults
 
 - Endpoints: `--auth-url`, `--api-url` or `ATOMIC_MAIL_AUTH_URL`,

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

@@ -1 +1 @@
-{"version":3,"file":"agent-auth-http.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/auth/agent-auth-http.ts"],"names":[],"mappings":"AAoCA,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC,CAqBD;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;IACJ,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA,OAAO,CAAC,eAAe,CAAC,CAS1B;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAUjB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,eAAe,CAAC,CAgB1B"}
+{"version":3,"file":"agent-auth-http.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/auth/agent-auth-http.ts"],"names":[],"mappings":"AAKA,wBAAsB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;IAC7D,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC,CA8BD;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE;IACJ,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GACA,OAAO,CAAC,eAAe,CAAC,CA8B1B;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAejB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACzC;AAED,wBAAsB,oBAAoB,CACxC,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC,eAAe,CAAC,CAgB1B"}

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

@@ -1,66 +1,65 @@
 // auth-service HTTP: challenge → session → capability.
 import { decodeJwtPayload } from "./agent-jwt.js";
 import { solvePow } from "./agent-pow.js";
-async function postJson(url, body, headers = {}) {
-    const res = await fetch(url, {
+export async function fetchChallenge(authUrl) {
+    const res = await fetch(`${authUrl}/api/v1/challenge`, {
         method: "POST",
-        headers: {
-            ...(body ? { "Content-Type": "application/json" } : {}),
-            ...headers,
-        },
-        body: body ? JSON.stringify(body) : undefined,
     });
     const text = await res.text();
-    const path = (() => {
-        try {
-            return new URL(url).pathname;
-        }
-        catch {
-            return url;
-        }
-    })();
     if (!res.ok) {
-        throw new Error(`auth-service ${path} returned ${res.status}: ${text}`);
-    }
-    try {
-        return JSON.parse(text);
+        throw new Error(`auth-service /api/v1/challenge returned ${res.status}: ${text}`);
     }
-    catch {
-        throw new Error(`auth-service ${path} returned non-JSON body: ${text}`);
-    }
-}
-export async function fetchChallenge(authUrl) {
-    const data = await postJson(`${authUrl}/api/v1/challenge`, undefined);
-    if (typeof data.challengeJWT !== "string") {
-        throw new Error("Challenge response missing challengeJWT.");
-    }
-    const payload = decodeJwtPayload(data.challengeJWT);
+    const challengeJWT = readBearerToken(res.headers.get("Authorization"), "Challenge response missing Authorization bearer token.");
+    const payload = decodeJwtPayload(challengeJWT);
     if (typeof payload.jti !== "string" ||
         typeof payload.difficulty !== "number") {
         throw new Error("Challenge JWT payload malformed (missing jti or difficulty).");
     }
     return {
-        challengeJWT: data.challengeJWT,
+        challengeJWT,
         challenge: payload.jti,
         difficulty: payload.difficulty,
     };
 }
 export async function exchangeSession(authUrl, body) {
-    const data = await postJson(`${authUrl}/api/v1/session`, { ...body });
-    if (typeof data.sessionJWT !== "string") {
-        throw new Error("Session response missing sessionJWT.");
+    const { challengeJWT, ...payload } = body;
+    const res = await fetch(`${authUrl}/api/v1/session`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${challengeJWT}`,
+        },
+        body: JSON.stringify(payload),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`auth-service /api/v1/session returned ${res.status}: ${text}`);
+    }
+    const sessionJWT = readBearerToken(res.headers.get("Authorization"), "Session response missing Authorization bearer token.");
+    let data = {};
+    if (text.trim().length > 0) {
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            throw new Error("auth-service /api/v1/session returned non-JSON body.");
+        }
     }
     return {
-        sessionJWT: data.sessionJWT,
+        sessionJWT,
         apiKey: typeof data.apiKey === "string" ? data.apiKey : undefined,
     };
 }
 export async function fetchCapability(authUrl, sessionJWT) {
-    const data = await postJson(`${authUrl}/api/v1/capability`, undefined, { Authorization: `Bearer ${sessionJWT}` });
-    if (typeof data.capabilityJWT !== "string") {
-        throw new Error("Capability response missing capabilityJWT.");
+    const res = await fetch(`${authUrl}/api/v1/capability`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${sessionJWT}` },
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`auth-service /api/v1/capability returned ${res.status}: ${text}`);
     }
-    return data.capabilityJWT;
+    return readBearerToken(res.headers.get("Authorization"), "Capability response missing Authorization bearer token.");
 }
 export async function performPoWAndSession(input) {
     const { authUrl, scryptSalt } = input;
@@ -74,3 +73,13 @@ export async function performPoWAndSession(input) {
         username: input.username,
     });
 }
+function readBearerToken(headerValue, missingError) {
+    if (!headerValue) {
+        throw new Error(missingError);
+    }
+    const match = /^\s*Bearer\s+(.+?)\s*$/i.exec(headerValue);
+    if (!match || !match[1]) {
+        throw new Error("Authorization header must use Bearer scheme.");
+    }
+    return match[1];
+}

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

@@ -1,5 +1,3 @@
-export declare const SESSION_TTL_MS: number;
-export declare const CAPABILITY_TTL_MS: number;
 export declare const SESSION_SAFETY_MARGIN_MS = 60000;
 export declare const CAPABILITY_SAFETY_MARGIN_MS = 20000;
 export interface JwtPayload {

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

@@ -1 +1 @@
-{"version":3,"file":"agent-jwt.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/auth/agent-jwt.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,cAAc,QAAqB,CAAC;AACjD,eAAO,MAAM,iBAAiB,QAAgB,CAAC;AAE/C,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAC/C,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAElD,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAc/D;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQnE"}
+{"version":3,"file":"agent-jwt.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/auth/agent-jwt.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAC/C,eAAO,MAAM,2BAA2B,QAAS,CAAC;AAElD,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,UAAU,EAAE,GAAG,EAAE,MAAM,GAAG,CAAC,CAc/D;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAQnE"}

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

@@ -1,6 +1,4 @@
 // JWT helpers for capability/session expiry checks.
-export const SESSION_TTL_MS = 4 * 60 * 60 * 1000;
-export const CAPABILITY_TTL_MS = 2 * 60 * 1000;
 export const SESSION_SAFETY_MARGIN_MS = 60_000;
 export const CAPABILITY_SAFETY_MARGIN_MS = 20_000;
 export function decodeJwtPayload(jwt) {

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

@@ -1,4 +1,5 @@
 export declare const HELP_TOPICS: Record<string, string>;
 export declare const HELP_TOPIC_LIST: string[];
+export declare function normalizeHelpTopic(topic: string): string;
 export declare function getHelp(topic?: string): string;
 //# sourceMappingURL=agent-help-content.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"agent-help-content.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/jmap/agent-help-content.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA+O9C,CAAC;AAEF,eAAO,MAAM,eAAe,UAA2B,CAAC;AAExD,wBAAgB,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAW9C"}
+{"version":3,"file":"agent-help-content.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/jmap/agent-help-content.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CA0P9C,CAAC;AAEF,eAAO,MAAM,eAAe,UAA2B,CAAC;AAExD,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,wBAAgB,OAAO,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAkB9C"}

package/esm/lib/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
 
@@ -86,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
 
@@ -119,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
@@ -174,7 +181,8 @@ 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
 
@@ -199,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
 
@@ -234,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/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

@@ -1 +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,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;CAClC;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,CA4C5D;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"}
+{"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/agent/jmap/agent-jmap.js

@@ -93,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`, {
@@ -120,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/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

@@ -1 +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;CACpB;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,CAiCxE;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"}
+{"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/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-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

@@ -1 +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;AAatC,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;gBAEpC,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;YAEa,YAAY;IAU1B;;OAEG;IACG,uBAAuB,IAAI,OAAO,CAAC,MAAM,CAAC;IAShD,0BAA0B,IAAI,IAAI;IAIlC;;;OAGG;IACG,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAuEnD,kBAAkB,IAAI,OAAO,CAAC,MAAM,CAAC;YA4B7B,aAAa;IAyB3B,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,CAyB9B"}
+{"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/agent/session/agent-session.js

@@ -1,7 +1,7 @@
 // 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 "../auth/agent-jwt.js";
-import { extractPrimaryMailAccountId, fetchJmapWellKnown, } from "../jmap/agent-jmap.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/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/mod.d.ts

@@ -1,5 +1,6 @@
 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";

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

@@ -1 +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,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"}
+{"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

@@ -1,5 +1,6 @@
 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";

package/esm/lib/network/auth-client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth-client.d.ts","sourceRoot":"","sources":["../../../src/lib/network/auth-client.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,iBAAiB;IAChC,6FAA6F;IAC7F,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,iEAAiE;AACjE,qBAAa,eAAgB,SAAQ,KAAK;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;gBAEL,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAM9D;AAOD,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;gBAE3B,OAAO,EAAE,iBAAiB;IAKtC;;;;OAIG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAwBrD,4DAA4D;IACtD,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAqBjD;;;OAGG;IACG,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;YAgBvC,cAAc;YAkCd,WAAW;YAeX,gBAAgB;IAuB9B;;;;;;;OAOG;YACW,QAAQ;CAgBvB"}
+{"version":3,"file":"auth-client.d.ts","sourceRoot":"","sources":["../../../src/lib/network/auth-client.ts"],"names":[],"mappings":"AAoBA,MAAM,WAAW,iBAAiB;IAChC,6FAA6F;IAC7F,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,4EAA4E;IAC5E,MAAM,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,iEAAiE;AACjE,qBAAa,eAAgB,SAAQ,KAAK;IACxC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;gBAEL,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAM9D;AAOD,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;gBAE3B,OAAO,EAAE,iBAAiB;IAKtC;;;;OAIG;IACG,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAyBrD,4DAA4D;IACtD,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAgBjD;;;OAGG;IACG,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;YAoBvC,cAAc;YAsCd,WAAW;YAyCX,gBAAgB;IAuB9B;;;;;;;OAOG;YACW,QAAQ;CAgBvB"}

package/esm/lib/network/auth-client.js

@@ -40,32 +40,26 @@ export class AuthClient {
     async signup(username) {
         const { challengeJWT, challenge, difficulty } = await this.fetchChallenge();
         const { powHex, nonce } = await this.solvePoW(challenge, difficulty);
-        const data = await this.postSession({
-            challengeJWT,
+        const { sessionJWT, data } = await this.postSession(challengeJWT, {
             powHex,
             nonce: nonce.toString(),
             username,
         });
-        if (typeof data.apiKey !== "string" ||
-            typeof data.sessionJWT !== "string") {
-            throw new AuthClientError(200, JSON.stringify(data), "Signup response missing apiKey or sessionJWT.");
+        if (typeof data.apiKey !== "string") {
+            throw new AuthClientError(200, JSON.stringify(data), "Signup response missing apiKey.");
         }
-        return { apiKey: data.apiKey, sessionJWT: data.sessionJWT };
+        return { apiKey: data.apiKey, sessionJWT };
     }
     /** Exchange an existing API key for a fresh session JWT. */
     async login(apiKey) {
         const { challengeJWT, challenge, difficulty } = await this.fetchChallenge();
         const { powHex, nonce } = await this.solvePoW(challenge, difficulty);
-        const data = await this.postSession({
-            challengeJWT,
+        const { sessionJWT } = await this.postSession(challengeJWT, {
             powHex,
             nonce: nonce.toString(),
             apiKey,
         });
-        if (typeof data.sessionJWT !== "string") {
-            throw new AuthClientError(200, JSON.stringify(data), "Login response missing sessionJWT.");
-        }
-        return { sessionJWT: data.sessionJWT };
+        return { sessionJWT };
     }
     /**
      * Exchange a session JWT for a short-lived capability JWT (audience:
@@ -76,38 +70,57 @@ export class AuthClient {
             method: "POST",
             headers: { Authorization: `Bearer ${sessionJWT}` },
         });
-        const data = await this.parseJsonOrThrow(res, "capability");
-        if (typeof data.capabilityJWT !== "string") {
-            throw new AuthClientError(res.status, JSON.stringify(data), "Capability response missing capabilityJWT.");
+        const text = await res.text();
+        if (!res.ok) {
+            throw new AuthClientError(res.status, text, `auth-service capability returned ${res.status}: ${text}`);
         }
-        return { capabilityJWT: data.capabilityJWT };
+        const capabilityJWT = readBearerToken(res.headers.get("Authorization"), "Capability response missing Authorization bearer token.");
+        return { capabilityJWT };
     }
     async fetchChallenge() {
         const res = await fetch(`${this.baseUrl}/api/v1/challenge`, {
             method: "POST",
         });
-        const data = await this.parseJsonOrThrow(res, "challenge");
-        if (typeof data.challengeJWT !== "string") {
-            throw new AuthClientError(res.status, JSON.stringify(data), "Challenge response missing challengeJWT.");
+        const text = await res.text();
+        if (!res.ok) {
+            throw new AuthClientError(res.status, text, `auth-service challenge returned ${res.status}: ${text}`);
         }
-        const payload = decodeJwtPayload(data.challengeJWT);
+        const challengeJWT = readBearerToken(res.headers.get("Authorization"), "Challenge response missing Authorization bearer token.");
+        const payload = decodeJwtPayload(challengeJWT);
         if (typeof payload.jti !== "string" ||
             typeof payload.difficulty !== "number") {
-            throw new AuthClientError(res.status, data.challengeJWT, "Challenge JWT payload is malformed (missing jti or difficulty).");
+            throw new AuthClientError(res.status, challengeJWT, "Challenge JWT payload is malformed (missing jti or difficulty).");
         }
         return {
-            challengeJWT: data.challengeJWT,
+            challengeJWT,
             challenge: payload.jti,
             difficulty: payload.difficulty,
         };
     }
-    async postSession(body) {
+    async postSession(challengeJWT, body) {
         const res = await fetch(`${this.baseUrl}/api/v1/session`, {
             method: "POST",
-            headers: { "Content-Type": "application/json" },
+            headers: {
+                "Content-Type": "application/json",
+                Authorization: `Bearer ${challengeJWT}`,
+            },
             body: JSON.stringify(body),
         });
-        return await this.parseJsonOrThrow(res, "session");
+        const text = await res.text();
+        if (!res.ok) {
+            throw new AuthClientError(res.status, text, `auth-service session returned ${res.status}: ${text}`);
+        }
+        const sessionJWT = readBearerToken(res.headers.get("Authorization"), "Session response missing Authorization bearer token.");
+        let data = {};
+        if (text.trim().length > 0) {
+            try {
+                data = JSON.parse(text);
+            }
+            catch {
+                throw new AuthClientError(res.status, text, "auth-service session returned non-JSON body.");
+            }
+        }
+        return { sessionJWT, data };
     }
     async parseJsonOrThrow(res, endpoint) {
         const text = await res.text();
@@ -186,3 +199,13 @@ function decodeJwtPayload(jwt) {
         .padEnd(payloadB64Url.length + padLen, "=");
     return JSON.parse(atob(base64));
 }
+function readBearerToken(headerValue, missingError) {
+    if (!headerValue) {
+        throw new Error(missingError);
+    }
+    const match = /^\s*Bearer\s+(.+?)\s*$/i.exec(headerValue);
+    if (!match || !match[1]) {
+        throw new Error("Authorization header must use Bearer scheme.");
+    }
+    return match[1];
+}

package/esm/skill/cli.js

@@ -5,7 +5,7 @@ import process from "node:process";
 import { parseArgs } from "node:util";
 import { resolve } from "node:path";
 import { homedir } from "node:os";
-import { AgentSession, DEFAULT_JMAP_USING, DEFAULT_POW_SCRYPT_SALT_HEX, defaultFilesFromOutDir, getHelp, persistLoginWithApiKey, readCredentials, readOpsFile, runJmapRequest, } from "../lib/mod.js";
+import { AgentSession, DEFAULT_JMAP_USING, DEFAULT_POW_SCRYPT_SALT_HEX, defaultFilesFromOutDir, getHelp, normalizeHelpTopic, persistLoginWithApiKey, readCredentials, readNpmPackageReadme, readOpsFile, runJmapRequest, } from "../lib/mod.js";
 const USAGE = `Atomic Mail — AgentSkill
 
 Usage:
@@ -14,7 +14,7 @@ Usage:
 Commands:
   register       PoW signup or login with API key (writes credentials)
   jmap_request   Send a JMAP batch (inline --ops or --ops-file preset)
-  help           Full documentation [--topic TOPIC]
+  help           Full documentation [--topic TOPIC] (topic readme = package README)
 
 Examples:
   atomicmail register --username alice
@@ -22,6 +22,7 @@ Examples:
   atomicmail jmap_request --credentials-dir ./.atomic-mail --ops-file fetch.json
   atomicmail jmap_request --credentials-dir ./.atomic-mail --ops-file send.json --vars '{"TO":"a@b.com","SUBJECT":"Hi"}'
   atomicmail help --topic presets
+  atomicmail help --topic readme
 
 Run  atomicmail <command> --help  for command-specific flags.
 `;
@@ -252,7 +253,7 @@ Options:
     }
     process.stdout.write(bodyText.endsWith("\n") ? bodyText : bodyText + "\n");
 }
-function cmdHelp(argv) {
+async function cmdHelp(argv) {
     let parsed;
     try {
         parsed = parseArgs({
@@ -271,11 +272,22 @@ function cmdHelp(argv) {
     if (parsed.values.help) {
         process.stdout.write(`Usage: atomicmail help [--topic TOPIC]
 
-Topics include: overview, installation, auth, jmap_cheatsheet, tools, presets, troubleshooting.
+Topics include: overview, installation, auth, jmap_cheatsheet, tools, presets, troubleshooting, readme.
+Topic readme prints the npm package README.md (requires install from npm).
 `);
         process.exit(0);
     }
     const topic = parsed.values.topic;
+    if (topic !== undefined && normalizeHelpTopic(topic) === "readme") {
+        try {
+            const text = await readNpmPackageReadme();
+            process.stdout.write(text.endsWith("\n") ? text : text + "\n");
+        }
+        catch (err) {
+            fail(err instanceof Error ? err.message : String(err));
+        }
+        return;
+    }
     process.stdout.write(getHelp(topic) + "\n");
 }
 async function main() {
@@ -293,7 +305,7 @@ async function main() {
             await cmdJmapRequest(rest);
             break;
         case "help":
-            cmdHelp(rest);
+            await cmdHelp(rest);
             break;
         default:
             process.stderr.write(`Unknown command: ${cmd}\n\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atomicmail/agent-skill",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Atomic Mail AgentSkill — register, jmap_request, and help CLI for AI agents.",
   "keywords": [
     "atomic-mail",