@atomicmail/agent-skill 0.1.0 → 0.2.1

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/{skill/scripts/lib/credentials.d.ts → lib/agent/session/agent-credentials-store.d.ts}

@@ -13,6 +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>;
+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

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

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

@@ -1,10 +1,6 @@
-// Credential file I/O. Three files form a complete skill credential set:
-//   credentials.json  — long-lived: apiKey, inboxId, server URLs, PoW salt.
-//   session.jwt       — short-lived (~4h): rotates via /session + PoW.
-//   capability.jwt    — short-lived (~2min): rotates via /capability.
-//
-// Files are written with mode 0600 so other local users cannot read them.
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+// Credential file I/O shared by MCP and AgentSkill.
+// Three files: credentials.json, session.jwt, capability.jwt (mode 0600).
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 export function defaultFilesFromOutDir(outDir) {
     const base = resolve(outDir);
@@ -28,7 +24,7 @@ export async function readCredentials(path) {
     }
     catch (err) {
         throw new Error(`Could not read credentials file '${path}': ${err.message}. ` +
-            "Did you run signup first?");
+            "Did you run register first?");
     }
     let obj;
     try {
@@ -51,6 +47,15 @@ export async function readCredentials(path) {
     }
     return obj;
 }
+export async function tryReadCredentials(path) {
+    try {
+        await readFile(path, "utf-8");
+    }
+    catch {
+        return undefined;
+    }
+    return readCredentials(path);
+}
 export async function writeJwtFile(path, jwt) {
     await ensureParent(path);
     await writeFile(path, jwt, { mode: 0o600 });
@@ -64,3 +69,18 @@ export async function tryReadJwtFile(path) {
         return undefined;
     }
 }
+/** Best-effort removal of credential artifacts (ignore missing files). */
+export async function unlinkCredentialArtifacts(files) {
+    for (const p of [
+        files.credentialsFile,
+        files.sessionFile,
+        files.capabilityFile,
+    ]) {
+        try {
+            await unlink(p);
+        }
+        catch {
+            // ignore
+        }
+    }
+}

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

@@ -0,0 +1,24 @@
+import { type SkillFiles } from "./agent-credentials-store.js";
+export type ConfigSource = "credentials-file" | "env" | "mixed" | "incomplete";
+export interface ResolvedAgentConfig {
+    authUrl: string;
+    apiUrl: string;
+    scryptSalt: string;
+    apiKey?: string;
+    inboxId?: string;
+    credentialDir: string;
+    files: SkillFiles;
+    source: ConfigSource;
+}
+/**
+ * Default credential directory:
+ *   1. ATOMIC_MAIL_CREDENTIALS_DIR
+ *   2. ~/.atomicmail/ or %USERPROFILE%/.atomicmail
+ */
+export declare function resolveCredentialDir(): string;
+/**
+ * Merge credentials.json with ATOMIC_MAIL_* env (env wins per field).
+ * authUrl and apiUrl must resolve from at least one source.
+ */
+export declare function resolveAgentConfigFromEnv(): Promise<ResolvedAgentConfig>;
+//# sourceMappingURL=agent-resolve-config.d.ts.map

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/agent/session/agent-resolve-config.js

@@ -0,0 +1,70 @@
+// Resolve MCP / process credential dir + URLs from env + credentials.json.
+import process from "node:process";
+import { DEFAULT_POW_SCRYPT_SALT_HEX } from "../../core/consts.js";
+import { defaultFilesFromOutDir, tryReadCredentials, } from "./agent-credentials-store.js";
+/**
+ * Default credential directory:
+ *   1. ATOMIC_MAIL_CREDENTIALS_DIR
+ *   2. ~/.atomicmail/ or %USERPROFILE%/.atomicmail
+ */
+export function resolveCredentialDir() {
+    const fromEnv = process.env.ATOMIC_MAIL_CREDENTIALS_DIR;
+    if (fromEnv && fromEnv.length > 0)
+        return fromEnv;
+    const home = process.env.HOME || process.env.USERPROFILE;
+    if (!home) {
+        throw new Error("Cannot determine default credential directory: HOME and USERPROFILE " +
+            "are both unset. Set ATOMIC_MAIL_CREDENTIALS_DIR explicitly.");
+    }
+    return `${home.replace(/[\\/]+$/, "")}/.atomicmail`;
+}
+/**
+ * Merge credentials.json with ATOMIC_MAIL_* env (env wins per field).
+ * authUrl and apiUrl must resolve from at least one source.
+ */
+export async function resolveAgentConfigFromEnv() {
+    const credentialDir = resolveCredentialDir();
+    const files = defaultFilesFromOutDir(credentialDir);
+    const fileCreds = await tryReadCredentials(files.credentialsFile);
+    const env = process.env;
+    const envAuthUrl = env.ATOMIC_MAIL_AUTH_URL;
+    const envApiUrl = env.ATOMIC_MAIL_API_URL;
+    const envSalt = env.ATOMIC_MAIL_SCRYPT_SALT;
+    const envApiKey = env.ATOMIC_MAIL_API_KEY;
+    const authUrl = envAuthUrl ?? fileCreds?.authUrl;
+    const apiUrl = envApiUrl ?? fileCreds?.apiUrl;
+    const scryptSalt = envSalt ?? fileCreds?.scryptSalt ??
+        DEFAULT_POW_SCRYPT_SALT_HEX;
+    const apiKey = envApiKey ?? fileCreds?.apiKey;
+    const inboxId = fileCreds?.inboxId;
+    const missing = [];
+    if (!authUrl)
+        missing.push("ATOMIC_MAIL_AUTH_URL");
+    if (!apiUrl)
+        missing.push("ATOMIC_MAIL_API_URL");
+    if (missing.length > 0) {
+        throw new Error(`Missing required configuration: ${missing.join(", ")}. ` +
+            `Provide these via environment variables, or place a populated ` +
+            `credentials.json in '${credentialDir}' (run register first, or set ` +
+            `ATOMIC_MAIL_CREDENTIALS_DIR).`);
+    }
+    const usingFile = fileCreds !== undefined;
+    const usingEnv = !!(envAuthUrl || envApiUrl || envSalt || envApiKey);
+    const source = usingFile && usingEnv
+        ? "mixed"
+        : usingFile
+            ? "credentials-file"
+            : usingEnv
+                ? "env"
+                : "incomplete";
+    return {
+        authUrl: authUrl.replace(/\/+$/, ""),
+        apiUrl: apiUrl.replace(/\/+$/, ""),
+        scryptSalt: scryptSalt,
+        apiKey,
+        inboxId,
+        credentialDir,
+        files,
+        source,
+    };
+}

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

@@ -0,0 +1,62 @@
+import { type SkillFiles } from "./agent-credentials-store.js";
+export interface AgentSessionConfig {
+    authUrl: string;
+    apiUrl: string;
+    scryptSalt: string;
+    apiKey?: string;
+    inboxId?: string;
+    credentialDir: string;
+    files: SkillFiles;
+}
+export interface RegisterResult {
+    inbox: string;
+    accountId: string;
+    /** Present only on first-time signup (not idempotent replay). */
+    apiKey?: string;
+    idempotent?: boolean;
+}
+/** Local-part of an inbox email, or the whole string if no @. */
+export declare function inboxLocalPart(inboxId: string): string;
+export declare class AgentSession {
+    private readonly authUrl;
+    readonly apiUrl: string;
+    private readonly scryptSalt;
+    private apiKey;
+    private inboxId;
+    readonly credentialDir: string;
+    readonly files: SkillFiles;
+    private sessionJWT;
+    private capabilityJWT;
+    private cachedMailAccountId;
+    constructor(cfg: AgentSessionConfig);
+    static create(cfg: AgentSessionConfig): Promise<AgentSession>;
+    get hasApiKey(): boolean;
+    get currentInboxId(): string | undefined;
+    private loadFromDisk;
+    /**
+     * Primary JMAP mail accountId from GET /.well-known/jmap (cached).
+     */
+    getPrimaryMailAccountId(): Promise<string>;
+    invalidateJmapSessionCache(): void;
+    /**
+     * Register or return existing inbox when username matches (idempotent).
+     * Different username replaces on-disk credentials and creates a new inbox.
+     */
+    register(username: string): Promise<RegisterResult>;
+    getCapabilityToken(): Promise<string>;
+    private ensureSession;
+    destroy(): void;
+}
+export interface PersistLoginWithApiKeyInput {
+    authUrl: string;
+    apiUrl: string;
+    scryptSalt: string;
+    apiKey: string;
+    files: SkillFiles;
+    onPowProgress?: (nonce: bigint) => void;
+}
+/** PoW login with an existing API key; writes credentials + JWT files. */
+export declare function persistLoginWithApiKey(input: PersistLoginWithApiKeyInput): Promise<{
+    inboxId: string;
+}>;
+//# sourceMappingURL=agent-session.d.ts.map

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

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

@@ -0,0 +1,206 @@
+// 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 { fetchCapability, performPoWAndSession } from "../auth/agent-auth-http.js";
+function normalizeUsername(u) {
+    return u.trim().toLowerCase();
+}
+/** Local-part of an inbox email, or the whole string if no @. */
+export function inboxLocalPart(inboxId) {
+    const i = inboxId.indexOf("@");
+    return i === -1
+        ? normalizeUsername(inboxId)
+        : normalizeUsername(inboxId.slice(0, i));
+}
+export class AgentSession {
+    authUrl;
+    apiUrl;
+    scryptSalt;
+    apiKey;
+    inboxId;
+    credentialDir;
+    files;
+    sessionJWT;
+    capabilityJWT;
+    cachedMailAccountId;
+    constructor(cfg) {
+        this.authUrl = cfg.authUrl.replace(/\/+$/, "");
+        this.apiUrl = cfg.apiUrl.replace(/\/+$/, "");
+        this.scryptSalt = cfg.scryptSalt;
+        this.apiKey = cfg.apiKey;
+        this.inboxId = cfg.inboxId;
+        this.credentialDir = cfg.credentialDir;
+        this.files = cfg.files;
+    }
+    static async create(cfg) {
+        const session = new AgentSession(cfg);
+        await session.loadFromDisk();
+        return session;
+    }
+    get hasApiKey() {
+        return this.apiKey !== undefined && this.apiKey.length > 0;
+    }
+    get currentInboxId() {
+        return this.inboxId;
+    }
+    async loadFromDisk() {
+        this.sessionJWT = await tryReadJwtFile(this.files.sessionFile);
+        this.capabilityJWT = await tryReadJwtFile(this.files.capabilityFile);
+        const disk = await tryReadCredentials(this.files.credentialsFile);
+        if (disk) {
+            this.apiKey = this.apiKey ?? disk.apiKey;
+            this.inboxId = this.inboxId ?? disk.inboxId;
+        }
+    }
+    /**
+     * Primary JMAP mail accountId from GET /.well-known/jmap (cached).
+     */
+    async getPrimaryMailAccountId() {
+        if (this.cachedMailAccountId)
+            return this.cachedMailAccountId;
+        const cap = await this.getCapabilityToken();
+        const session = await fetchJmapWellKnown(this.apiUrl, cap);
+        const id = extractPrimaryMailAccountId(session);
+        this.cachedMailAccountId = id;
+        return id;
+    }
+    invalidateJmapSessionCache() {
+        this.cachedMailAccountId = undefined;
+    }
+    /**
+     * Register or return existing inbox when username matches (idempotent).
+     * Different username replaces on-disk credentials and creates a new inbox.
+     */
+    async register(username) {
+        const want = normalizeUsername(username);
+        if (this.hasApiKey && !this.inboxId) {
+            throw new Error("Cannot register: an API key is configured but inboxId is unknown. " +
+                "Fix credentials.json or unset ATOMIC_MAIL_API_KEY before registering.");
+        }
+        if (this.hasApiKey && this.inboxId) {
+            const have = inboxLocalPart(this.inboxId);
+            if (have === want) {
+                const accountId = await this.getPrimaryMailAccountId();
+                return {
+                    inbox: this.inboxId,
+                    accountId,
+                    idempotent: true,
+                };
+            }
+            await unlinkCredentialArtifacts(this.files);
+            this.apiKey = undefined;
+            this.inboxId = undefined;
+            this.sessionJWT = undefined;
+            this.capabilityJWT = undefined;
+            this.cachedMailAccountId = undefined;
+        }
+        const result = await performPoWAndSession({
+            authUrl: this.authUrl,
+            scryptSalt: this.scryptSalt,
+            username,
+        });
+        if (!result.apiKey) {
+            throw new Error("Signup did not return an apiKey — this indicates a server bug.");
+        }
+        this.apiKey = result.apiKey;
+        this.sessionJWT = result.sessionJWT;
+        await writeJwtFile(this.files.sessionFile, this.sessionJWT);
+        const capability = await fetchCapability(this.authUrl, this.sessionJWT);
+        this.capabilityJWT = capability;
+        await writeJwtFile(this.files.capabilityFile, capability);
+        const claims = decodeJwtPayload(capability);
+        if (typeof claims.inboxId !== "string" || claims.inboxId.length === 0) {
+            throw new Error("Capability JWT missing inboxId claim after signup.");
+        }
+        this.inboxId = claims.inboxId;
+        this.cachedMailAccountId = undefined;
+        const creds = {
+            apiKey: this.apiKey,
+            inboxId: this.inboxId,
+            authUrl: this.authUrl,
+            apiUrl: this.apiUrl,
+            scryptSalt: this.scryptSalt,
+        };
+        await writeCredentials(this.files.credentialsFile, creds);
+        const accountId = await this.getPrimaryMailAccountId();
+        return {
+            inbox: this.inboxId,
+            accountId,
+            apiKey: this.apiKey,
+        };
+    }
+    async getCapabilityToken() {
+        if (this.capabilityJWT &&
+            !isJwtExpired(this.capabilityJWT, CAPABILITY_SAFETY_MARGIN_MS)) {
+            return this.capabilityJWT;
+        }
+        await this.ensureSession();
+        if (!this.sessionJWT) {
+            throw new Error("Internal: ensureSession() left sessionJWT unset.");
+        }
+        const cap = await fetchCapability(this.authUrl, this.sessionJWT);
+        this.capabilityJWT = cap;
+        await writeJwtFile(this.files.capabilityFile, cap);
+        try {
+            const claims = decodeJwtPayload(cap);
+            if (typeof claims.inboxId === "string" && claims.inboxId.length > 0) {
+                this.inboxId = claims.inboxId;
+            }
+        }
+        catch {
+            // non-fatal
+        }
+        return cap;
+    }
+    async ensureSession() {
+        if (this.sessionJWT &&
+            !isJwtExpired(this.sessionJWT, SESSION_SAFETY_MARGIN_MS)) {
+            return;
+        }
+        if (!this.apiKey) {
+            throw new Error("No API key configured and no valid session on disk. Run register " +
+                "first, set ATOMIC_MAIL_API_KEY, or place credentials.json in the " +
+                "credential directory.");
+        }
+        const result = await performPoWAndSession({
+            authUrl: this.authUrl,
+            scryptSalt: this.scryptSalt,
+            apiKey: this.apiKey,
+        });
+        this.sessionJWT = result.sessionJWT;
+        this.capabilityJWT = undefined;
+        this.cachedMailAccountId = undefined;
+        await writeJwtFile(this.files.sessionFile, this.sessionJWT);
+    }
+    destroy() {
+        // reserved
+    }
+}
+/** PoW login with an existing API key; writes credentials + JWT files. */
+export async function persistLoginWithApiKey(input) {
+    const authUrl = input.authUrl.replace(/\/+$/, "");
+    const apiUrl = input.apiUrl.replace(/\/+$/, "");
+    const session = await performPoWAndSession({
+        authUrl,
+        scryptSalt: input.scryptSalt,
+        apiKey: input.apiKey,
+        onPowProgress: input.onPowProgress,
+    });
+    const capabilityJWT = await fetchCapability(authUrl, session.sessionJWT);
+    const claims = decodeJwtPayload(capabilityJWT);
+    const inboxId = claims.inboxId;
+    if (typeof inboxId !== "string" || inboxId.length === 0) {
+        throw new Error("Capability JWT did not contain an inboxId claim.");
+    }
+    await writeCredentials(input.files.credentialsFile, {
+        apiKey: input.apiKey,
+        inboxId,
+        authUrl,
+        apiUrl,
+        scryptSalt: input.scryptSalt,
+    });
+    await writeJwtFile(input.files.sessionFile, session.sessionJWT);
+    await writeJwtFile(input.files.capabilityFile, capabilityJWT);
+    return { inboxId };
+}

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/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,14 @@
+export * from "./network/auth-client.js";
+export * from "./core/utils.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,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,13 @@
+export * from "./network/auth-client.js";
+export * from "./core/utils.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";