@atomicmail/mcp 0.1.0 → 0.2.1

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

@@ -0,0 +1,29 @@
+// 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) {
+    const parts = jwt.split(".");
+    if (parts.length < 2) {
+        throw new Error("Malformed JWT: expected at least 2 dot-separated segments.");
+    }
+    const payloadB64Url = parts[1];
+    const padLen = (4 - (payloadB64Url.length % 4)) % 4;
+    const base64 = payloadB64Url
+        .replace(/-/g, "+")
+        .replace(/_/g, "/")
+        .padEnd(payloadB64Url.length + padLen, "=");
+    return JSON.parse(atob(base64));
+}
+export function isJwtExpired(jwt, marginMs) {
+    try {
+        const { exp } = decodeJwtPayload(jwt);
+        if (typeof exp !== "number")
+            return true;
+        return Date.now() >= exp * 1000 - marginMs;
+    }
+    catch {
+        return true;
+    }
+}

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

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

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

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

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

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

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

@@ -0,0 +1,4 @@
+export declare const HELP_TOPICS: Record<string, string>;
+export declare const HELP_TOPIC_LIST: 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

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

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

@@ -0,0 +1,244 @@
+// Long-form help for MCP `help` tool and AgentSkill `help` command.
+export const HELP_TOPICS = {
+    overview: `\
+# Atomic Mail — Overview
+
+Atomic Mail is an email service provider (ESP) designed for AI agents. You
+manage mail over JMAP (RFC 8620 + RFC 8621).
+
+## Public surface (identical for MCP and AgentSkill)
+
+Three operations only:
+
+1. **register** — Proof-of-work signup (or idempotent replay when the same
+   username matches the inbox already on disk). Persists credentials and
+   returns \`{ inbox, accountId }\` (and \`apiKey\` on first signup).
+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\`).
+
+## Typical workflow
+
+1. \`register\` with a username.
+2. \`jmap_request\` with JMAP method calls (presets may use \`$VAR_NAME\`; pass
+   custom values in \`vars\` / \`--vars\`).
+3. If stuck, read error hints and call \`help\`.
+
+Available topics: overview, installation, auth, jmap_cheatsheet, tools,
+presets, troubleshooting.`,
+    installation: `\
+# Atomic Mail — Installation
+
+## MCP (stdio)
+
+\`\`\`json
+{
+  "mcpServers": {
+    "atomicmail": {
+      "command": "npx",
+      "args": ["-y", "@atomicmail/mcp"]
+    }
+  }
+}
+\`\`\`
+
+## AgentSkill (shell)
+
+\`\`\`bash
+npx --package=@atomicmail/agent-skill atomicmail register --username "myagent"
+npx --package=@atomicmail/agent-skill atomicmail jmap_request \\
+  --ops-file list_inbox.json \\
+  --vars '{"COUNT":"10"}'
+npx --package=@atomicmail/agent-skill atomicmail help
+\`\`\`
+
+From the repo: \`deno run -A scripts/cli.ts <command> ...\` inside \`skill/\`.
+
+## Shared credentials
+
+MCP and the skill use the same directory layout (default \`~/.atomicmail/\`):
+
+- \`credentials.json\`, \`session.jwt\`, \`capability.jwt\`
+
+## Overriding defaults
+
+- Endpoints: \`ATOMIC_MAIL_AUTH_URL\`, \`ATOMIC_MAIL_API_URL\`
+- Credentials path: \`ATOMIC_MAIL_CREDENTIALS_DIR\` (MCP), \`--credentials-dir\` (skill)
+- Optional PoW salt: \`ATOMIC_MAIL_SCRYPT_SALT\`
+
+## From source (development)
+
+From the repo \`mcp/\` or \`skill/\` directory:
+
+\`\`\`bash
+deno task start   # MCP
+deno task build:npm
+\`\`\`
+
+See each package README for details.`,
+    auth: `\
+# Atomic Mail — Auth flow
+
+Auth is automatic after \`register\` (or when \`credentials.json\` + API key
+exist).
+
+1. **Challenge** — \`POST /api/v1/challenge\`
+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
+
+JWTs are rotated before expiry and written back to disk.
+
+## Credential files (mode 0600)
+
+\`credentials.json\` — \`{ apiKey, inboxId, authUrl, apiUrl, scryptSalt }\`  
+\`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\`)`,
+    jmap_cheatsheet: `\
+# JMAP cheatsheet
+
+## Capabilities (\`using\`)
+
+- urn:ietf:params:jmap:core
+- urn:ietf:params:jmap:mail
+- urn:ietf:params:jmap:submission
+
+## Examples
+
+Use \`$ACCOUNT_ID\` and \`$INBOX\` for session fields; use \`$TO\`, \`$SUBJECT\`,
+etc., and supply values via MCP \`vars\` or \`--vars\` (JSON object of strings).
+
+### Mailboxes
+\`\`\`json
+["Mailbox/get", {"accountId": "$ACCOUNT_ID"}, "m0"]
+\`\`\`
+
+### Query + fetch emails
+\`\`\`json
+["Email/query", {
+  "accountId": "$ACCOUNT_ID",
+  "filter": {"inMailbox": "$INBOX"},
+  "sort": [{"property": "receivedAt", "isAscending": false}],
+  "limit": 100
+}, "q0"]
+\`\`\`
+
+### Send (add submission to \`using\`)
+
+Include \`urn:ietf:params:jmap:submission\` in the envelope \`using\` array
+when calling \`EmailSubmission/set\`.
+
+## Tips
+
+- Back-references (\`#ids\`, \`#draft\`) chain calls in one batch.
+- Save reusable JSON as preset files and pass \`ops_file\`.`,
+    tools: `\
+# Tool / CLI reference
+
+## register
+
+**MCP input:** \`{ "username": string }\`  
+**Skill:** \`register --username NAME\` (or \`--api-key KEY\`).
+
+Creates an inbox or returns the same \`{ inbox, accountId }\` when the
+username matches the stored inbox local-part. A **different** username
+replaces credentials in the directory and registers a new inbox.
+
+## jmap_request
+
+**MCP input:** \`{ "using"?: string[], "ops"?: string, "ops_file"?: string,
+"vars"?: Record<string, string> }\` — keys in \`vars\` are names without \`$\`
+(e.g. \`TO\` for \`$TO\`). Exactly one of \`ops\` or \`ops_file\`.
+
+**Skill:** \`jmap_request --ops '...'\` or \`--ops-file path\` plus
+\`--credentials-dir\` (optional), plus optional \`--vars '<json>'\`, \`--using\`,
+\`--dry-run\`.
+
+## help
+
+**MCP:** \`{ "topic"?: string }\`  
+**Skill:** \`help [--topic TOPIC]\`
+
+Topics: overview, installation, auth, jmap_cheatsheet, tools, presets,
+troubleshooting.`,
+    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 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
+
+Syntax: \`$VAR_NAME\` where \`VAR_NAME\` matches \`/^[A-Z][A-Z0-9_]*$/\` (so JMAP
+keywords like \`$draft\` stay untouched).
+
+- \`$ACCOUNT_ID\` — primary mail account id (from \`GET /.well-known/jmap\` when
+  referenced).
+- \`$INBOX\` — inbox email address from credentials.
+- 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.`,
+    troubleshooting: `\
+# Troubleshooting
+
+## Custom endpoint configuration issues
+
+Defaults are production endpoints. Set env vars only for custom deployments.
+
+## No API key / register first
+
+Run \`register\`, or set \`ATOMIC_MAIL_API_KEY\`, or copy an existing
+\`credentials.json\` into the credential directory.
+
+## auth-service /api/v1/session returned 401
+
+Invalid \`apiKey\` or wrong \`ATOMIC_MAIL_SCRYPT_SALT\` for this deployment.
+
+## Capability JWT missing inboxId
+
+Server/version mismatch — verify \`ATOMIC_MAIL_AUTH_URL\`.
+
+## Could not read ops file
+
+Check the path; use an absolute path if unsure.
+
+## Missing values for variables (\`$TO\`, etc.)
+
+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 getHelp(topic) {
+    if (!topic) {
+        return HELP_TOPICS["overview"];
+    }
+    const key = topic.toLowerCase().replace(/[\s-]/g, "_");
+    return (HELP_TOPICS[key] ??
+        `Unknown topic "${topic}". Available topics: ${HELP_TOPIC_LIST.join(", ")}`);
+}

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

@@ -0,0 +1,49 @@
+export declare const DEFAULT_JMAP_USING: readonly ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"];
+export declare const JMAP_MAIL_URN: "urn:ietf:params:jmap:mail";
+export interface JmapEnvelope {
+    using: string[];
+    methodCalls: unknown[];
+}
+export declare function parseJmapEnvelope(raw: string, defaultUsing: string[], source: string): JmapEnvelope;
+export declare function resolveOpsFilePath(credentialDir: string, opsFile: string): string;
+export declare function readOpsFile(credentialDir: string, opsFile: string): Promise<string>;
+export declare function extractPrimaryMailAccountId(session: Record<string, unknown>): string;
+export declare function fetchJmapWellKnown(apiUrl: string, capabilityJwt: string): Promise<Record<string, unknown>>;
+/** Minimal surface for JMAP execution (implemented by AgentSession). */
+export interface JmapSessionPort {
+    readonly apiUrl: string;
+    readonly files: {
+        credentialsFile: string;
+    };
+    getPrimaryMailAccountId(): Promise<string>;
+    getCapabilityToken(): Promise<string>;
+    readonly currentInboxId?: string;
+}
+export interface RunJmapRequestInput {
+    session: JmapSessionPort;
+    /** Raw JSON: methodCalls array or full envelope */
+    opsJson: string;
+    /** Default `using` when the envelope omits it */
+    defaultUsing: string[];
+    /** Label for parse errors */
+    sourceLabel: string;
+    dryRun?: boolean;
+    /** Values for `$VAR` tokens (keys without `$`). Overrides session vars when present. */
+    vars?: Record<string, string>;
+}
+/**
+ * Parse ops JSON, substitute `$VAR_NAME` tokens (session + caller vars), POST to JMAP.
+ */
+export declare function runJmapRequest(input: RunJmapRequestInput): Promise<{
+    ok: boolean;
+    status: number;
+    bodyText: string;
+}>;
+export declare function postJmap(apiUrl: string, capabilityJwt: string, envelope: JmapEnvelope): Promise<{
+    ok: boolean;
+    status: number;
+    bodyText: string;
+}>;
+/** Attach _next hints to a successful JMAP JSON object when parseable. */
+export declare function attachJmapNextHints(bodyText: string): string;
+//# sourceMappingURL=agent-jmap.d.ts.map

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,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"}

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

@@ -0,0 +1,174 @@
+// 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 { 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",
+    "urn:ietf:params:jmap:mail",
+];
+export const JMAP_MAIL_URN = "urn:ietf:params:jmap:mail";
+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) {
+        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"];
+    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 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) {
+    const { text: raw } = await substituteVars({
+        raw: input.opsJson,
+        vars: input.vars,
+        autoResolvers: {
+            ACCOUNT_ID: () => input.session.getPrimaryMailAccountId(),
+            INBOX: async () => input.session.currentInboxId ??
+                (await readCredentials(input.session.files.credentialsFile)).inboxId,
+        },
+    });
+    const envelope = parseJmapEnvelope(raw, input.defaultUsing, input.sourceLabel);
+    if (input.dryRun) {
+        return {
+            ok: true,
+            status: 200,
+            bodyText: JSON.stringify({
+                dryRun: true,
+                url: `${input.session.apiUrl.replace(/\/+$/, "")}/jmap/`,
+                envelope,
+            }, null, 2),
+        };
+    }
+    const capabilityJwt = await input.session.getCapabilityToken();
+    const { ok, status, bodyText } = await postJmap(input.session.apiUrl, capabilityJwt, envelope);
+    if (!ok) {
+        return { ok, status, bodyText };
+    }
+    return { ok, status, bodyText: attachJmapNextHints(bodyText) };
+}
+export async function postJmap(apiUrl, capabilityJwt, envelope) {
+    const base = apiUrl.replace(/\/+$/, "");
+    const res = await fetch(`${base}/jmap/`, {
+        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 = [
+    "Use jmap_request with Mailbox/get or Email/query to work with mail data.",
+    "Use presets with $VAR placeholders — $ACCOUNT_ID and $INBOX 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,23 @@
+/** 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,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/agent/jmap/agent-vars.js

@@ -0,0 +1,65 @@
+// Variable substitution for JMAP presets / inline ops ($VAR_NAME tokens).
+/** 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"]);
+/** 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 and $INBOX, 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/{mcp/src/credentials.d.ts → lib/agent/session/agent-credentials-store.d.ts}

@@ -13,8 +13,9 @@ export interface SkillFiles {
 export declare function defaultFilesFromOutDir(outDir: string): SkillFiles;
 export declare function writeCredentials(path: string, creds: Credentials): Promise<void>;
 export declare function readCredentials(path: string): Promise<Credentials>;
-/** Like readCredentials, but returns undefined when the file does not exist. */
 export declare function tryReadCredentials(path: string): Promise<Credentials | undefined>;
 export declare function writeJwtFile(path: string, jwt: string): Promise<void>;
 export declare function tryReadJwtFile(path: string): Promise<string | undefined>;
-//# sourceMappingURL=credentials.d.ts.map
+/** Best-effort removal of credential artifacts (ignore missing files). */
+export declare function unlinkCredentialArtifacts(files: SkillFiles): Promise<void>;
+//# sourceMappingURL=agent-credentials-store.d.ts.map