@atomicmail/langchain 0.3.14

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

@@ -0,0 +1,49 @@
+// Help topic: overview (MCP help / AgentSkill help).
+import { postRegisterCronReminder } from "./cron.js";
+export const helpTopicOverview = `\
+# 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). Usernames are 5–21 characters
+   (local-part of \`@atomicmail.ai\`). When a different username is
+   requested and credentials already exist, register fails unless you use a
+   separate \`credentials_dir\` / \`--credentials-dir\` or pass \`forced: true\`
+   / \`--forced\` to replace the current directory. 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 (same
+   substitution for both). Session-backed tokens (\`$ACCOUNT_ID\`, \`$INBOX\`,
+   \`$INBOX_MAILBOX_ID\`, \`$UPLOAD_URL\`, \`$DOWNLOAD_URL\`) resolve from
+   credentials and JMAP session (\`$INBOX\` is always a full mailbox address;
+   \`$INBOX_MAILBOX_ID\` is the inbox **mailbox id** for filters and
+   \`mailboxIds\` — see **presets** topic). Pass any other \`$NAME\` via MCP
+   \`vars\` or \`--vars\`. Optional **attachments** (MCP \`attachments\`, skill
+   \`--attachment\`): each file is uploaded to \`uploadUrl\` (RFC 8620), then
+   \`$ATTACHMENT_0_BLOB_ID\`, … are substituted into your JMAP JSON.
+3. **help** — This documentation (optional \`topic\` / \`--topic\`), or the
+   published package README (\`topic\` / \`--topic\` \`readme\`).
+
+## Typical workflow
+
+1. \`register\` with a username (5–21 characters).
+2. After register, arrange hourly inbox polling per your runtime (see **cron**
+   topic — native scheduler if available; otherwise ask your operator or remind
+   manual fetch). Do not cron \`atomicmail jmap_request\` alone.
+3. \`jmap_request\` with JMAP method calls (presets may use \`$VAR_NAME\`; pass
+   custom values in \`vars\` / \`--vars\`).
+4. Call \`help\` early and often — before guessing JMAP or preset details, not
+   only when stuck. Prefer \`help\` over general JMAP knowledge; topics match
+   this package version.
+
+${postRegisterCronReminder}
+
+Available topics: overview, installation, auth, jmap_cheatsheet, tools,
+presets, cron, multi_account, troubleshooting. Use \`readme\` for the npm package \`README.md\`.`;

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

@@ -0,0 +1,2 @@
+export declare const helpTopicPresets = "# JMAP presets\n\nSave a method-call array or a full `{ \"using\", \"methodCalls\" }` envelope\nas JSON, then pass `ops_file` (MCP) or `--ops-file` (skill).\n\nRelative paths first resolve against the credential directory (MCP) or current\n`--credentials-dir` (skill). If not found, the runtime falls back to bundled\npresets that ship in both npm packages.\n\n## Bundled presets\n\n- `send_mail.json` \u2014 sends one email using `$TO`, `$SUBJECT`, `$BODY`.\n- `list_inbox.json` \u2014 latest 50 inbox messages (uses `$INBOX_MAILBOX_ID`).\n  **Use this preset for hourly inbox polling** (see **cron** topic).\n- `reply.json` \u2014 replies in-thread using `$MAIL_ID` and `$BODY`.\n- `send_mail_attachment.json` \u2014 `Blob/upload` + send; `vars`: `TO`,\n  `SUBJECT`, `BODY`, `ATTACHMENT_BASE64`, `ATTACHMENT_TYPE`,\n  `ATTACHMENT_NAME`. Fine for modest sizes; large files should use RFC 8620\n  upload instead (see `send_mail_blob_attachment.json`).\n- `send_mail_blob_attachment.json` \u2014 one attachment whose `blobId` comes from\n  `$ATTACHMENT_0_BLOB_ID` (etc.). Use with MCP `attachments` or skill\n  `--attachment PATH` so the client uploads files to `uploadUrl` before the\n  batch; `vars`: `TO`, `SUBJECT`, `BODY`. For `text/*` parts referenced\n  by `blobId`, the client adds `charset` (default `utf-8`) when omitted (RFC\n  8621). For several files in one `Email/set`, write normal JMAP JSON\n  referencing `$ATTACHMENT_1_BLOB_ID`, \u2026\n\n## Placeholders\n\nSyntax: `$VAR_NAME` where `VAR_NAME` matches `/^[A-Z][A-Z0-9_]*$/` (so JMAP\nkeywords like `$draft` stay untouched).\n\n- `$ACCOUNT_ID` \u2014 primary mail account id (from `GET /.well-known/jmap` when\n  referenced).\n- `$INBOX` \u2014 inbox email address from credentials.\n- `$INBOX_MAILBOX_ID` \u2014 JMAP mailbox id for the inbox (extra `Mailbox/query`;\n  use for `Email/query` / `Email/set` where the API wants a mailbox id).\n- `$UPLOAD_URL` \u2014 RFC 8620 upload URL template from JMAP session.\n- `$DOWNLOAD_URL` \u2014 RFC 8620 download URL template from JMAP session.\n- Any other `$FOO` \u2014 must appear in MCP `vars` or skill `--vars` as\n  `\"FOO\": \"...\"` (string values only; JSON escaping in the preset body is your\n  responsibility).\n- `$ATTACHMENT_N_BLOB_ID`, `$ATTACHMENT_N_NAME`, `$ATTACHMENT_N_TYPE`,\n  `$ATTACHMENT_N_SIZE` (N = 0, 1, \u2026) and `$ATTACHMENT_COUNT` \u2014 injected when\n  you pass MCP `attachments` or skill `--attachment`; you can still override\n  them in `vars` / `--vars` if needed.\n\nYou may override `ACCOUNT_ID` / `INBOX` / `INBOX_MAILBOX_ID` /\n`UPLOAD_URL` / `DOWNLOAD_URL` via `vars` / `--vars` if needed.";
+//# sourceMappingURL=presets.d.ts.map

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

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

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

@@ -0,0 +1,51 @@
+// Help topic: presets (MCP help / AgentSkill help).
+export const helpTopicPresets = `\
+# 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\` — latest 50 inbox messages (uses \`$INBOX_MAILBOX_ID\`).
+  **Use this preset for hourly inbox polling** (see **cron** topic).
+- \`reply.json\` — replies in-thread using \`$MAIL_ID\` and \`$BODY\`.
+- \`send_mail_attachment.json\` — \`Blob/upload\` + send; \`vars\`: \`TO\`,
+  \`SUBJECT\`, \`BODY\`, \`ATTACHMENT_BASE64\`, \`ATTACHMENT_TYPE\`,
+  \`ATTACHMENT_NAME\`. Fine for modest sizes; large files should use RFC 8620
+  upload instead (see \`send_mail_blob_attachment.json\`).
+- \`send_mail_blob_attachment.json\` — one attachment whose \`blobId\` comes from
+  \`$ATTACHMENT_0_BLOB_ID\` (etc.). Use with MCP \`attachments\` or skill
+  \`--attachment PATH\` so the client uploads files to \`uploadUrl\` before the
+  batch; \`vars\`: \`TO\`, \`SUBJECT\`, \`BODY\`. For \`text/*\` parts referenced
+  by \`blobId\`, the client adds \`charset\` (default \`utf-8\`) when omitted (RFC
+  8621). For several files in one \`Email/set\`, write normal JMAP JSON
+  referencing \`$ATTACHMENT_1_BLOB_ID\`, …
+
+## 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.
+- \`$INBOX_MAILBOX_ID\` — JMAP mailbox id for the inbox (extra \`Mailbox/query\`;
+  use for \`Email/query\` / \`Email/set\` where the API wants a mailbox id).
+- \`$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).
+- \`$ATTACHMENT_N_BLOB_ID\`, \`$ATTACHMENT_N_NAME\`, \`$ATTACHMENT_N_TYPE\`,
+  \`$ATTACHMENT_N_SIZE\` (N = 0, 1, …) and \`$ATTACHMENT_COUNT\` — injected when
+  you pass MCP \`attachments\` or skill \`--attachment\`; you can still override
+  them in \`vars\` / \`--vars\` if needed.
+
+You may override \`ACCOUNT_ID\` / \`INBOX\` / \`INBOX_MAILBOX_ID\` /
+\`UPLOAD_URL\` / \`DOWNLOAD_URL\` via \`vars\` / \`--vars\` if needed.`;

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

@@ -0,0 +1,2 @@
+export declare const helpTopicTools = "# Tool / CLI reference\n\n## register\n\n**MCP input:** `{ \"username\": string, \"credentials_dir\"?: string, \"forced\"?: boolean }`  \n**Skill:** `register --username NAME [--credentials-dir DIR] [--forced]` (or `--api-key KEY`).\n\nUsernames must be 5\u201321 characters (local-part of your `@atomicmail.ai`\naddress).\n\nCreates an inbox or returns the same `{ inbox, accountId }` when the\nusername matches the stored inbox local-part. A **different** username\nfails by default to protect existing credentials. To add another account without\nreplacing the current one, pass a **separate** `credentials_dir` (MCP) or\n`--credentials-dir` (skill) \u2014 see **multi_account** topic. To replace\ncredentials in the **same** directory, pass **`forced: true`** (MCP) or\n**`--forced`** (skill) explicitly after backing up.\n\n**After a successful register,** arrange hourly inbox polling per your runtime\n(see **cron** topic \u2014 native cron hosts schedule an agent turn with\n`list_inbox.json`; no-native-cron hosts ask the operator or remind manual\nfetch).\n\n## jmap_request\n\n**MCP input:** `{ \"credentials_dir\"?: string, \"using\"?: string[], \"ops\"?: string, \"ops_file\"?: string,\n\"vars\"?: Record<string, string>, \"attachments\"?: { path, filename?, content_type? }[] }` \u2014\nkeys in `vars` are names without `$` (e.g. `TO` for `$TO`). Exactly one of\n`ops` or `ops_file`. When `attachments` is non-empty, each path is read on\nthe MCP host, `POST`ed to JMAP `uploadUrl` (RFC 8620), then\n`$ATTACHMENT_N_BLOB_ID` / `$ATTACHMENT_N_NAME` / `$ATTACHMENT_N_TYPE` /\n`$ATTACHMENT_N_SIZE` and `$ATTACHMENT_COUNT` are available in `ops` (same\nsemantics as if you had pasted those strings in `vars`).\n\n**Skill:** `jmap_request --ops '...'` or `--ops-file path` plus\n`--credentials-dir` (optional), plus optional `--vars '<json>'`,\n`--attachment PATH` (repeatable), `--attachment-path-base DIR`, `--using`,\n`--dry-run` (not with `--attachment`).\n\n## help\n\n**MCP:** `{ \"topic\"?: string }`  \n**Skill:** `help [--topic TOPIC]`\n\nTopics: overview, installation, auth, jmap_cheatsheet, tools, presets, cron,\nmulti_account, troubleshooting. Topic `readme` prints the published package `README.md`\n(same layout as npm; requires install from npm).";
+//# sourceMappingURL=tools.d.ts.map

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

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

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

@@ -0,0 +1,49 @@
+// Help topic: tools (MCP help / AgentSkill help).
+export const helpTopicTools = `\
+# Tool / CLI reference
+
+## register
+
+**MCP input:** \`{ "username": string, "credentials_dir"?: string, "forced"?: boolean }\`  
+**Skill:** \`register --username NAME [--credentials-dir DIR] [--forced]\` (or \`--api-key KEY\`).
+
+Usernames must be 5–21 characters (local-part of your \`@atomicmail.ai\`
+address).
+
+Creates an inbox or returns the same \`{ inbox, accountId }\` when the
+username matches the stored inbox local-part. A **different** username
+fails by default to protect existing credentials. To add another account without
+replacing the current one, pass a **separate** \`credentials_dir\` (MCP) or
+\`--credentials-dir\` (skill) — see **multi_account** topic. To replace
+credentials in the **same** directory, pass **\`forced: true\`** (MCP) or
+**\`--forced\`** (skill) explicitly after backing up.
+
+**After a successful register,** arrange hourly inbox polling per your runtime
+(see **cron** topic — native cron hosts schedule an agent turn with
+\`list_inbox.json\`; no-native-cron hosts ask the operator or remind manual
+fetch).
+
+## jmap_request
+
+**MCP input:** \`{ "credentials_dir"?: string, "using"?: string[], "ops"?: string, "ops_file"?: string,
+"vars"?: Record<string, string>, "attachments"?: { path, filename?, content_type? }[] }\` —
+keys in \`vars\` are names without \`$\` (e.g. \`TO\` for \`$TO\`). Exactly one of
+\`ops\` or \`ops_file\`. When \`attachments\` is non-empty, each path is read on
+the MCP host, \`POST\`ed to JMAP \`uploadUrl\` (RFC 8620), then
+\`$ATTACHMENT_N_BLOB_ID\` / \`$ATTACHMENT_N_NAME\` / \`$ATTACHMENT_N_TYPE\` /
+\`$ATTACHMENT_N_SIZE\` and \`$ATTACHMENT_COUNT\` are available in \`ops\` (same
+semantics as if you had pasted those strings in \`vars\`).
+
+**Skill:** \`jmap_request --ops '...'\` or \`--ops-file path\` plus
+\`--credentials-dir\` (optional), plus optional \`--vars '<json>'\`,
+\`--attachment PATH\` (repeatable), \`--attachment-path-base DIR\`, \`--using\`,
+\`--dry-run\` (not with \`--attachment\`).
+
+## help
+
+**MCP:** \`{ "topic"?: string }\`  
+**Skill:** \`help [--topic TOPIC]\`
+
+Topics: overview, installation, auth, jmap_cheatsheet, tools, presets, cron,
+multi_account, troubleshooting. Topic \`readme\` prints the published package \`README.md\`
+(same layout as npm; requires install from npm).`;

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

@@ -0,0 +1,2 @@
+export declare const helpTopicTroubleshooting = "# Troubleshooting\n\n## Custom endpoint configuration issues\n\nDefaults are production endpoints. Set env vars only for custom deployments.\n\n## No API key / register first\n\nRun `register`, or set `ATOMIC_MAIL_API_KEY`, or copy an existing\n`credentials.json` into the credential directory.\n\n## auth-service /api/v1/session returned 401\n\nInvalid `apiKey` or wrong `ATOMIC_MAIL_SCRYPT_SALT` for this deployment.\n\n## Capability JWT missing inboxId\n\nServer/version mismatch \u2014 verify `ATOMIC_MAIL_AUTH_URL`.\n\n## Could not read ops file\n\nCheck the path; use an absolute path if unsure.\n\n## Missing values for variables (`$TO`, etc.)\n\nPass every custom placeholder in MCP `vars` or `--vars` as a JSON object of\nstrings. Ensure `register` completed so `$ACCOUNT_ID` / `$INBOX` can resolve.\n\n## `invalidArguments` on `Email/query` / `filter/inMailbox`\n\n`inMailbox` must be a **mailbox id**, not your inbox email. Use the built-in\n`$INBOX_MAILBOX_ID` placeholder (or run `Mailbox/get` / `Mailbox/query` and\npaste the id into `vars`).\n\n## `invalidProperties` / `notCreated` on `Blob/upload`\n\nRFC 9404 requires `data` as an **array** of objects, each with **exactly one**\nof `data:asText`, `data:asBase64`, or a `blobId` slice. Typical mistakes:\n`data` as a raw string; `data:asBase64` on the upload object instead of\ninside an array element; mixing two forms in one object. See topic\n`jmap_cheatsheet` (`Blob/upload` shape) and preset `send_mail_attachment.json`.\n\n## RFC 8620 binary `POST` to `uploadUrl` returns 404\n\nThe session lists an `uploadUrl` template, but your deployment must expose\nthat HTTP resource. If `POST` returns 404, out-of-band upload is not wired\non the server \u2014 use `Blob/upload` in JMAP instead, or fix the API gateway.\n\n## `Blob/upload` succeeds but `size` is 0 (or `Email/set` rejects the blob)\n\nThe server accepted the method but did not persist octets (broken or\nincomplete `Blob/upload`). Verify with a tiny `data: [{ \"data:asBase64\": \"QQ==\" }]`\npayload; if `size`\nstays 0, fix the JMAP/blob implementation on the host before sending\nattachments.\n\n## Installed package vs other documentation\n\nThe version you get from `npx -y @atomicmail/mcp` or\n`npx --package=@atomicmail/agent-skill \u2026` may lag behind other published docs.\nIf something disagrees, trust **your installed package**: run `help` and use\nthe bundled presets that ship with that version. In MCP runtimes, `help` with\ntopic `readme` returns package README.md.";
+//# sourceMappingURL=troubleshooting.d.ts.map

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

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

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

@@ -0,0 +1,65 @@
+// Help topic: troubleshooting (MCP help / AgentSkill help).
+export const helpTopicTroubleshooting = `\
+# 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.
+
+## \`invalidArguments\` on \`Email/query\` / \`filter/inMailbox\`
+
+\`inMailbox\` must be a **mailbox id**, not your inbox email. Use the built-in
+\`$INBOX_MAILBOX_ID\` placeholder (or run \`Mailbox/get\` / \`Mailbox/query\` and
+paste the id into \`vars\`).
+
+## \`invalidProperties\` / \`notCreated\` on \`Blob/upload\`
+
+RFC 9404 requires \`data\` as an **array** of objects, each with **exactly one**
+of \`data:asText\`, \`data:asBase64\`, or a \`blobId\` slice. Typical mistakes:
+\`data\` as a raw string; \`data:asBase64\` on the upload object instead of
+inside an array element; mixing two forms in one object. See topic
+\`jmap_cheatsheet\` (\`Blob/upload\` shape) and preset \`send_mail_attachment.json\`.
+
+## RFC 8620 binary \`POST\` to \`uploadUrl\` returns 404
+
+The session lists an \`uploadUrl\` template, but your deployment must expose
+that HTTP resource. If \`POST\` returns 404, out-of-band upload is not wired
+on the server — use \`Blob/upload\` in JMAP instead, or fix the API gateway.
+
+## \`Blob/upload\` succeeds but \`size\` is 0 (or \`Email/set\` rejects the blob)
+
+The server accepted the method but did not persist octets (broken or
+incomplete \`Blob/upload\`). Verify with a tiny \`data: [{ "data:asBase64": "QQ==" }]\`
+payload; if \`size\`
+stays 0, fix the JMAP/blob implementation on the host before sending
+attachments.
+
+## Installed package vs other documentation
+
+The version you get from \`npx -y @atomicmail/mcp\` or
+\`npx --package=@atomicmail/agent-skill …\` may lag behind other published docs.
+If something disagrees, trust **your installed package**: run \`help\` and use
+the bundled presets that ship with that version. In MCP runtimes, \`help\` with
+topic \`readme\` returns package README.md.`;

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

@@ -0,0 +1,45 @@
+export interface Credentials {
+    apiKey: string;
+    inboxId: string;
+    authUrl: string;
+    apiUrl: string;
+    scryptSalt: string;
+    uploadUrl: string;
+    downloadUrl: string;
+}
+export interface SkillFiles {
+    credentialsFile: string;
+    sessionFile: string;
+    capabilityFile: string;
+}
+export interface CredentialArtifacts {
+    credentials?: Credentials;
+    sessionJwt?: string;
+    capabilityJwt?: string;
+}
+export interface CredentialStore {
+    load(): Promise<CredentialArtifacts>;
+    /**
+     * Persist provided artifacts. Missing fields are left unchanged.
+     */
+    save(artifacts: CredentialArtifacts): Promise<void>;
+    clear(): Promise<void>;
+}
+export declare function defaultFilesFromOutDir(outDir: string): SkillFiles;
+export declare function parseCredentialsJson(raw: string, pathForErrors?: string): Credentials;
+export declare function serializeCredentials(creds: Credentials): string;
+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>;
+export declare class FilesystemCredentialStore implements CredentialStore {
+    readonly files: SkillFiles;
+    constructor(files: SkillFiles);
+    load(): Promise<CredentialArtifacts>;
+    save(artifacts: CredentialArtifacts): Promise<void>;
+    clear(): Promise<void>;
+}
+/** 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;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,MAAM,WAAW,mBAAmB;IAClC,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACrC;;OAEG;IACH,IAAI,CAAC,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,MAAM,GAAG,UAAU,CAOjE;AAMD,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,MAAM,EACX,aAAa,SAAqB,GACjC,WAAW,CA4Bb;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAE/D;AAED,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,CAWxE;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,qBAAa,yBAA0B,YAAW,eAAe;IAC/D,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;gBAEf,KAAK,EAAE,UAAU;IAIvB,IAAI,IAAI,OAAO,CAAC,mBAAmB,CAAC;IAQpC,IAAI,CAAC,SAAS,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAYnD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B;AAED,0EAA0E;AAC1E,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,UAAU,GAChB,OAAO,CAAC,IAAI,CAAC,CAcf"}

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

@@ -0,0 +1,121 @@
+// 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);
+    return {
+        credentialsFile: join(base, "credentials.json"),
+        sessionFile: join(base, "session.jwt"),
+        capabilityFile: join(base, "capability.jwt"),
+    };
+}
+async function ensureParent(path) {
+    await mkdir(dirname(path), { recursive: true });
+}
+export function parseCredentialsJson(raw, pathForErrors = "credentials.json") {
+    let obj;
+    try {
+        obj = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`Credentials file '${pathForErrors}' is not valid JSON: ${err.message}`);
+    }
+    const required = [
+        "apiKey",
+        "inboxId",
+        "authUrl",
+        "apiUrl",
+        "scryptSalt",
+        "uploadUrl",
+        "downloadUrl",
+    ];
+    for (const k of required) {
+        if (typeof obj[k] !== "string" || obj[k].length === 0) {
+            throw new Error(`Credentials file '${pathForErrors}' missing required field: ${k}`);
+        }
+    }
+    return obj;
+}
+export function serializeCredentials(creds) {
+    return JSON.stringify(creds, null, 2) + "\n";
+}
+export async function writeCredentials(path, creds) {
+    await ensureParent(path);
+    await writeFile(path, serializeCredentials(creds), { mode: 0o600 });
+}
+export async function readCredentials(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf-8");
+    }
+    catch (err) {
+        throw new Error(`Could not read credentials file '${path}': ${err.message}. ` +
+            "Did you run register first?");
+    }
+    return parseCredentialsJson(raw, path);
+}
+export async function tryReadCredentials(path) {
+    try {
+        const raw = await readFile(path, "utf-8");
+        return parseCredentialsJson(raw, path);
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function writeJwtFile(path, jwt) {
+    await ensureParent(path);
+    await writeFile(path, jwt, { mode: 0o600 });
+}
+export async function tryReadJwtFile(path) {
+    try {
+        const raw = await readFile(path, "utf-8");
+        return raw.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+export class FilesystemCredentialStore {
+    files;
+    constructor(files) {
+        this.files = files;
+    }
+    async load() {
+        return {
+            credentials: await tryReadCredentials(this.files.credentialsFile),
+            sessionJwt: await tryReadJwtFile(this.files.sessionFile),
+            capabilityJwt: await tryReadJwtFile(this.files.capabilityFile),
+        };
+    }
+    async save(artifacts) {
+        if (artifacts.credentials !== undefined) {
+            await writeCredentials(this.files.credentialsFile, artifacts.credentials);
+        }
+        if (artifacts.sessionJwt !== undefined) {
+            await writeJwtFile(this.files.sessionFile, artifacts.sessionJwt);
+        }
+        if (artifacts.capabilityJwt !== undefined) {
+            await writeJwtFile(this.files.capabilityFile, artifacts.capabilityJwt);
+        }
+    }
+    async clear() {
+        await unlinkCredentialArtifacts(this.files);
+    }
+}
+/** 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,29 @@
+import { type SkillFiles } from "./agent-credentials-store.js";
+export type ConfigSource = "credentials-file" | "env" | "mixed" | "defaults";
+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;
+/**
+ * AgentSkill / CLI: resolve credential directory from `--credentials-dir` or
+ * `ATOMIC_MAIL_CREDENTIALS_DIR`, with `~` expansion (MCP uses `resolveCredentialDir` instead).
+ */
+export declare function expandCredentialDirInput(dir?: string): string;
+/**
+ * Merge credentials.json with ATOMIC_MAIL_* env (env wins per field).
+ * authUrl and apiUrl fall back to production defaults when unset.
+ */
+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":"AAWA,OAAO,EAEL,KAAK,UAAU,EAEhB,MAAM,8BAA8B,CAAC;AAEtC,MAAM,MAAM,YAAY,GACpB,kBAAkB,GAClB,KAAK,GACL,OAAO,GACP,UAAU,CAAC;AAEf,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,wBAAgB,wBAAwB,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,MAAM,CAI7D;AAED;;;GAGG;AACH,wBAAsB,yBAAyB,IAAI,OAAO,CACxD,mBAAmB,CACpB,CAuCA"}

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

@@ -0,0 +1,71 @@
+// Resolve MCP / process credential dir + URLs from env + credentials.json.
+import { homedir } from "node:os";
+import process from "node:process";
+import { resolve } from "node:path";
+import { DEFAULT_API_URL, DEFAULT_AUTH_URL, 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`;
+}
+/**
+ * AgentSkill / CLI: resolve credential directory from `--credentials-dir` or
+ * `ATOMIC_MAIL_CREDENTIALS_DIR`, with `~` expansion (MCP uses `resolveCredentialDir` instead).
+ */
+export function expandCredentialDirInput(dir) {
+    const raw = dir ?? process.env.ATOMIC_MAIL_CREDENTIALS_DIR ?? "~/.atomicmail";
+    if (raw === "~")
+        return homedir();
+    return resolve(raw.replace(/^~\//, `${homedir()}/`));
+}
+/**
+ * Merge credentials.json with ATOMIC_MAIL_* env (env wins per field).
+ * authUrl and apiUrl fall back to production defaults when unset.
+ */
+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 ?? DEFAULT_AUTH_URL;
+    const apiUrl = envApiUrl ?? fileCreds?.apiUrl ?? DEFAULT_API_URL;
+    const scryptSalt = envSalt ?? fileCreds?.scryptSalt ??
+        DEFAULT_POW_SCRYPT_SALT_HEX;
+    const apiKey = envApiKey ?? fileCreds?.apiKey;
+    const inboxId = fileCreds?.inboxId;
+    const usingFile = fileCreds !== undefined;
+    const usingEnv = !!(envAuthUrl || envApiUrl || envSalt || envApiKey);
+    const source = usingFile && usingEnv
+        ? "mixed"
+        : usingFile
+            ? "credentials-file"
+            : usingEnv
+                ? "env"
+                : "defaults";
+    return {
+        authUrl: authUrl.replace(/\/+$/, ""),
+        apiUrl: apiUrl.replace(/\/+$/, ""),
+        scryptSalt: scryptSalt,
+        apiKey,
+        inboxId,
+        credentialDir,
+        files,
+        source,
+    };
+}

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

@@ -0,0 +1,8 @@
+import { AgentSession } from "./agent-session.js";
+import { type ResolvedAgentConfig } from "./agent-resolve-config.js";
+export interface CreateAgentSessionForCredentialDirOptions {
+    /** When true, credentials.json must exist (jmap_request path). */
+    requireCredentials?: boolean;
+}
+export declare function createAgentSessionForCredentialDir(credentialDir: string, envDefaults: Pick<ResolvedAgentConfig, "authUrl" | "apiUrl" | "scryptSalt">, options?: CreateAgentSessionForCredentialDirOptions): Promise<AgentSession>;
+//# sourceMappingURL=agent-session-for-dir.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"agent-session-for-dir.d.ts","sourceRoot":"","sources":["../../../../src/lib/agent/session/agent-session-for-dir.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAMlD,OAAO,EAEL,KAAK,mBAAmB,EACzB,MAAM,2BAA2B,CAAC;AAEnC,MAAM,WAAW,yCAAyC;IACxD,kEAAkE;IAClE,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC9B;AAED,wBAAsB,kCAAkC,CACtD,aAAa,EAAE,MAAM,EACrB,WAAW,EAAE,IAAI,CAAC,mBAAmB,EAAE,SAAS,GAAG,QAAQ,GAAG,YAAY,CAAC,EAC3E,OAAO,GAAE,yCAA8C,GACtD,OAAO,CAAC,YAAY,CAAC,CAgCvB"}

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

@@ -0,0 +1,33 @@
+// Create AgentSession for a specific credential directory (MCP per-request / CLI parity).
+import { AgentSession } from "./agent-session.js";
+import { defaultFilesFromOutDir, FilesystemCredentialStore, tryReadCredentials, } from "./agent-credentials-store.js";
+import { expandCredentialDirInput, } from "./agent-resolve-config.js";
+export async function createAgentSessionForCredentialDir(credentialDir, envDefaults, options = {}) {
+    const expandedDir = expandCredentialDirInput(credentialDir);
+    const files = defaultFilesFromOutDir(expandedDir);
+    const store = new FilesystemCredentialStore(files);
+    const fileCreds = await tryReadCredentials(files.credentialsFile);
+    if (!fileCreds) {
+        if (options.requireCredentials) {
+            throw new Error(`No credentials in '${expandedDir}'. Run register with ` +
+                `credentials_dir pointing at that directory first.`);
+        }
+        return AgentSession.create({
+            authUrl: envDefaults.authUrl,
+            apiUrl: envDefaults.apiUrl,
+            scryptSalt: envDefaults.scryptSalt,
+            credentialDir: expandedDir,
+            store,
+        });
+    }
+    const creds = fileCreds;
+    return AgentSession.create({
+        authUrl: creds.authUrl,
+        apiUrl: creds.apiUrl,
+        scryptSalt: creds.scryptSalt,
+        apiKey: creds.apiKey,
+        inboxId: creds.inboxId,
+        credentialDir: expandedDir,
+        store,
+    });
+}