@atomicmail/langchain 0.3.14

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

@@ -0,0 +1,159 @@
+// Help topic: post-register inbox polling (agent invocation, not raw CLI cron).
+/** Prompt for hourly inbox jobs — agent fetches mail and stays available for follow-up. */
+export const INBOX_CRON_AGENT_PROMPT = "Use Atomic Mail to fetch my inbox (MCP jmap_request with ops_file " +
+    "list_inbox.json, or atomicmail jmap_request --ops-file list_inbox.json). " +
+    "Summarize new messages, highlight what needs a reply, and stay available — " +
+    "I may ask you to reply, forward, search, or dig into something important.";
+/** Short block — embed in MCP instructions, register tool text, overview workflow. */
+export const postRegisterCronReminder = `\
+AFTER REGISTER — INBOX POLLING
+  Choose the path that matches your runtime (help topic "cron"):
+  • Native cron (OpenClaw, Hermes, atomic-agent, …): schedule an hourly AGENT turn with list_inbox.json in the prompt; wire MCP or AgentSkill into that agent. Do NOT cron atomicmail jmap_request alone.
+  • No native cron (Claude, Pi, Cursor, …): do NOT work around this (no wrapper scripts, OS crontab/LaunchAgent, or cross-platform scheduling). Ask your operator to set up polling on a capable host, or remind them to fetch mail manually when needed.
+  • Forbidden: register in one runtime and schedule the cron job on another.`;
+export const helpTopicCron = `\
+# Inbox polling (after register)
+
+Registration only creates credentials. For a useful inbox integration, inbound
+mail should be fetched and triaged about once per hour between interactive
+sessions.
+
+**Choose the path that matches your runtime — do not mix platforms.**
+
+## If your host supports scheduled jobs
+
+If you have a **native** way to enable cron or recurring agent turns (OpenClaw,
+Hermes, atomic-agent, and similar hosts), set up an hourly **agent** job after
+the first successful \`register\`. The job must **invoke an AI agent** (not just the
+Atomic Mail CLI) to fetch and triage mail. Wire Atomic Mail MCP or AgentSkill
+into that agent before scheduling.
+
+The scheduled turn should call preset **list_inbox.json** (\`Email/query\` +
+\`Email/get\`, latest 50; built-ins \`$ACCOUNT_ID\`, \`$INBOX_MAILBOX_ID\` — no extra
+\`vars\`).
+
+## If your host does **not** support scheduled jobs
+
+Examples: Claude, Pi, Cursor, and other chat or terminal agents without a cron
+API.
+
+**Do not spend tokens trying to work around this** — no wrapper scripts, OS
+crontab/LaunchAgent setup, or scheduling on a different platform on the agent's
+behalf.
+
+After a successful \`register\`, do one of the following:
+
+1. **Ask your operator** to set up hourly inbox polling on a host that supports
+   it (share the examples below), **or**
+2. **Remind your operator** to fetch mail manually when they need updates
+   (\`jmap_request\` with \`list_inbox.json\`, or \`atomicmail jmap_request
+   --ops-file list_inbox.json\`).
+
+## Forbidden: cross-platform scheduling
+
+Do **not** register in one runtime and schedule the cron job on another. Example
+of forbidden behavior: Pi runs \`register\`, then creates an OpenClaw cron job.
+Either the same runtime that registered schedules polling, or the operator
+schedules it themselves on a capable host.
+
+## What not to do (any runtime)
+
+- **Raw CLI in crontab** — \`atomicmail jmap_request --ops-file list_inbox.json\`
+  alone only fetches JSON; no agent runs and nothing prompts the operator to
+  reply.
+- **Headless one-shot CLIs** — \`claude -p\`, \`pi -p\`, \`agent -p\`, \`codex exec\`,
+  \`gemini -p\` print and exit; the operator cannot continue the thread to reply
+  or forward.
+
+## Agent prompt (use in scheduled jobs or manual fetches)
+
+\`\`\`text
+${INBOX_CRON_AGENT_PROMPT}
+\`\`\`
+
+## Scheduling examples (for capable hosts or operators)
+
+| Your setup | Recommended approach |
+| --- | --- |
+| OpenClaw gateway | Built-in \`openclaw cron\` |
+| Hermes Agent | Install skill → \`/suggestions\` blueprint after \`register\` (or manual \`hermes cron\`) |
+| Atomic Bot (atomicbot.ai) | Same as OpenClaw or Hermes host |
+| atomic-agent | Built-in \`atomic-agent task create\` |
+| No native cron (Claude, Pi, Cursor, …) | Ask operator to schedule on a capable host, or remind them to fetch manually |
+
+### OpenClaw
+
+Docs: https://docs.openclaw.ai/automation/cron-jobs
+
+\`\`\`bash
+openclaw cron add \\
+  --name "atomicmail-inbox" \\
+  --cron "0 * * * *" \\
+  --session isolated \\
+  --message "${INBOX_CRON_AGENT_PROMPT}" \\
+  --announce
+\`\`\`
+
+Manage: \`openclaw cron list\` · test: \`openclaw cron run <job-id>\`
+
+### Hermes Agent
+
+Skill blueprints: https://hermes-agent.nousresearch.com/docs/developer-guide/creating-skills
+
+Cron (manual fallback): https://hermes-agent.nousresearch.com/docs/user-guide/features/cron
+
+**Recommended:** Install the Atomic Mail Hermes skill → after \`register\`, accept
+the hourly inbox blueprint via \`/suggestions\` (\`no_agent: false\`,
+\`list_inbox.json\`, \`deliver: origin\`). Do not cron raw \`jmap_request\` or use
+\`--no-agent\`.
+
+**Credentials:** Default \`~/.hermes/atomicmail\` (not \`~/.atomicmail\`). The skill
+launcher sets \`ATOMIC_MAIL_CREDENTIALS_DIR\` when unset; override via env or
+\`atomicmail.credentials_dir\` config. Use \`--credentials-dir\` only for
+multi-account setups.
+
+**Manual fallback:**
+
+\`\`\`bash
+hermes cron create "0 * * * *" \\
+  "${INBOX_CRON_AGENT_PROMPT}" \\
+  --name "atomicmail-inbox" \\
+  --deliver origin
+\`\`\`
+
+Manage: \`hermes cron list\` · test: \`hermes cron run <job-id>\`
+
+### atomic-agent
+
+\`\`\`bash
+atomic-agent task create \\
+  --cron "0 * * * *" \\
+  --message "${INBOX_CRON_AGENT_PROMPT}"
+\`\`\`
+
+Manage: \`atomic-agent task list\`
+
+## Verify setup
+
+1. \`register\` succeeded; Atomic Mail MCP or AgentSkill is available to the agent.
+2. Run the agent prompt **once manually**; confirm inbox fetch and follow-up work.
+3. Confirm the job is registered (\`openclaw cron list\`, \`hermes cron list\`,
+   \`atomic-agent task list\`).
+
+## For operators: OS scheduling on terminal hosts
+
+This section is **operator documentation**, not an agent obligation. Chat agents
+without native cron should **not** attempt OS scheduling themselves.
+
+If you (the operator) run a **terminal CLI agent** without OpenClaw, Hermes, or
+similar, the scheduler must **start an interactive session** with the agent
+prompt — not call \`atomicmail\` directly.
+
+| Agent | Start interactively | Avoid for inbox polling |
+| --- | --- | --- |
+| Claude Code | \`claude "prompt"\` | \`claude -p\` |
+| Pi | \`pi "prompt"\` | \`pi -p\` |
+| Cursor CLI | \`agent "prompt"\` | \`agent -p\` |
+
+OS options: wrapper script + user crontab, macOS LaunchAgent, or Linux systemd
+user timer — launching a terminal emulator with an interactive agent session.`;

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

@@ -0,0 +1,6 @@
+export declare const HELP_TOPICS: Record<string, string>;
+export declare const HELP_TOPIC_LIST: string[];
+export declare function normalizeHelpTopic(topic: string): string;
+export type HelpRuntime = "mcp" | "skill";
+export declare function getHelp(topic?: string, runtime?: HelpRuntime): Promise<string>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../src/lib/agent/jmap/help-content/index.ts"],"names":[],"mappings":"AAiDA,eAAO,MAAM,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAQ7B,CAAC;AAEnB,eAAO,MAAM,eAAe,UAEG,CAAC;AAMhC,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,MAAM,MAAM,WAAW,GAAG,KAAK,GAAG,OAAO,CAAC;AAE1C,wBAAsB,OAAO,CAC3B,KAAK,CAAC,EAAE,MAAM,EACd,OAAO,GAAE,WAAqB,GAC7B,OAAO,CAAC,MAAM,CAAC,CAgBjB"}

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

@@ -0,0 +1,61 @@
+// Assembled help topics for MCP `help` and AgentSkill `help`.
+import { readNpmPackageReadme } from "../../../core/read-npm-package-readme.js";
+import { tryReadSharedJson, tryReadSharedText, } from "../../../core/shared-assets.js";
+import { helpTopicAuth } from "./auth.js";
+import { helpTopicCron } from "./cron.js";
+import { helpTopicInstallation } from "./installation.js";
+import { helpTopicJmapCheatsheet } from "./jmap-cheatsheet.js";
+import { helpTopicMultiAccount } from "./multi-account.js";
+import { helpTopicOverview } from "./overview.js";
+import { helpTopicPresets } from "./presets.js";
+import { helpTopicTools } from "./tools.js";
+import { helpTopicTroubleshooting } from "./troubleshooting.js";
+const manifest = tryReadSharedJson("manifest.json");
+const errors = tryReadSharedJson("messages/errors.json");
+const fallbackTopics = {
+    overview: helpTopicOverview,
+    installation: helpTopicInstallation,
+    auth: helpTopicAuth,
+    jmap_cheatsheet: helpTopicJmapCheatsheet,
+    tools: helpTopicTools,
+    presets: helpTopicPresets,
+    cron: helpTopicCron,
+    multi_account: helpTopicMultiAccount,
+    troubleshooting: helpTopicTroubleshooting,
+};
+const DEFAULT_README_STUB = 'Topic "readme" returns a built-in stub in AgentSkill runtimes. From MCP, topic "readme" returns the package README.md.';
+const DEFAULT_UNKNOWN_TOPIC = "Unknown topic \"{topic}\". Available topics: {topics}, readme";
+export const HELP_TOPICS = manifest
+    ? Object.fromEntries(manifest.help.topic_order.map((topic) => {
+        const text = tryReadSharedText(`${manifest.help.topics_dir}/${topic}.md`) ??
+            fallbackTopics[topic];
+        return [topic, text];
+    }))
+    : fallbackTopics;
+export const HELP_TOPIC_LIST = manifest
+    ? [...manifest.help.topic_order]
+    : Object.keys(fallbackTopics);
+const HELP_README_STUB = manifest
+    ? (tryReadSharedText(manifest.help.readme_stub_path) ?? DEFAULT_README_STUB)
+        .trim()
+    : DEFAULT_README_STUB;
+export function normalizeHelpTopic(topic) {
+    return topic.toLowerCase().replace(/[\s-]/g, "_");
+}
+export async function getHelp(topic, runtime = "skill") {
+    if (!topic) {
+        return HELP_TOPICS["overview"];
+    }
+    const key = normalizeHelpTopic(topic);
+    if (key === "readme") {
+        if (runtime === "mcp") {
+            return await readNpmPackageReadme();
+        }
+        return HELP_README_STUB;
+    }
+    const unknownTemplate = errors?.help_unknown_topic_template ??
+        DEFAULT_UNKNOWN_TOPIC;
+    return (HELP_TOPICS[key] ?? unknownTemplate)
+        .replace("{topic}", topic)
+        .replace("{topics}", HELP_TOPIC_LIST.join(", "));
+}

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

@@ -0,0 +1,2 @@
+export declare const helpTopicInstallation = "# Atomic Mail \u2014 Installation\n\n## MCP (stdio)\n\n```json\n{\n  \"mcpServers\": {\n    \"atomicmail\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@atomicmail/mcp\"]\n    }\n  }\n}\n```\n\n## AgentSkill (shell)\n\n```bash\nnpx --package=@atomicmail/agent-skill atomicmail register --username \"myagent\"\nnpx --package=@atomicmail/agent-skill atomicmail jmap_request \\\n  --ops-file list_inbox.json\nnpx --package=@atomicmail/agent-skill atomicmail help\n```\n\n## After register: hourly inbox polling\n\nRegistration only creates credentials. Arrange hourly inbox polling per your\nruntime (see **cron** topic): native cron hosts schedule an hourly **agent**\nturn with `list_inbox.json`; hosts without native cron should ask the operator\nto set up polling on a capable host or remind manual fetch. Do not cron\n`atomicmail jmap_request` alone.\n\n## Shared credentials\n\nMCP and the skill use the same directory layout (default `~/.atomicmail/`):\n\n- `credentials.json`, `session.jwt`, `capability.jwt`\n\n## Overriding defaults\n\n- Endpoints: `ATOMIC_MAIL_AUTH_URL`, `ATOMIC_MAIL_API_URL`\n- Default credentials path: `ATOMIC_MAIL_CREDENTIALS_DIR` (MCP host `env`),\n  `--credentials-dir` (skill), or per-call `credentials_dir` (MCP) /\n  `--credentials-dir` (skill) \u2014 see **multi_account** topic\n- Optional PoW salt: `ATOMIC_MAIL_SCRYPT_SALT`";
+//# sourceMappingURL=installation.d.ts.map

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

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

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

@@ -0,0 +1,47 @@
+// Help topic: installation (MCP help / AgentSkill help).
+export const helpTopicInstallation = `\
+# 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
+npx --package=@atomicmail/agent-skill atomicmail help
+\`\`\`
+
+## After register: hourly inbox polling
+
+Registration only creates credentials. Arrange hourly inbox polling per your
+runtime (see **cron** topic): native cron hosts schedule an hourly **agent**
+turn with \`list_inbox.json\`; hosts without native cron should ask the operator
+to set up polling on a capable host or remind manual fetch. Do not cron
+\`atomicmail jmap_request\` alone.
+
+## 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\`
+- Default credentials path: \`ATOMIC_MAIL_CREDENTIALS_DIR\` (MCP host \`env\`),
+  \`--credentials-dir\` (skill), or per-call \`credentials_dir\` (MCP) /
+  \`--credentials-dir\` (skill) — see **multi_account** topic
+- Optional PoW salt: \`ATOMIC_MAIL_SCRYPT_SALT\``;

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

@@ -0,0 +1,2 @@
+export declare const helpTopicJmapCheatsheet = "# JMAP cheatsheet\n\n## Capabilities (`using`)\n\nCommon URNs:\n\n- urn:ietf:params:jmap:core\n- urn:ietf:params:jmap:mail\n- urn:ietf:params:jmap:submission \u2014 required for `EmailSubmission/set`\n- urn:ietf:params:jmap:blob \u2014 required for `Blob/upload`, `Blob/get`, and\n  `Blob/lookup` (see RFC 9404 \u00A74.3 for reverse blob references).\n\n## Session blob limits\n\nPer-account limits live under\n`accounts[accountId].accountCapabilities[\"urn:ietf:params:jmap:blob\"]` (see\n[RFC 9404 \u00A73.1](https://www.rfc-editor.org/rfc/rfc9404#section-3.1)):\n`maxSizeBlobSet`, `maxDataSources`, etc. MCP and AgentSkill **reject before\nPOST** when a computable `Blob/upload` payload or an `attachments` file would\nexceed advertised `maxSizeBlobSet` or `maxDataSources` (`maxSizeBlobSet:\nnull` means no client octet cap). Literal (non-`#`) `blobId` slices are not\npre-sized on the client.\n\n## `Blob/upload` shape (RFC 9404)\n\nEach `Blob/upload` `create` value is an **UploadObject**: required `data` is\nan **array** of **DataSourceObject**; each array element uses **exactly one** of\n`data:asText`, `data:asBase64`, or `blobId` (+ optional `offset` /\n`length`). Optional `type` is a media-type hint. In one batch, reference a\ncreated blob as `\"#b1\"` when the create key was `b1`.\n\n**Invalid shapes** (do not expect servers to fix these): `data` as a plain\nstring; `data:asBase64` / `data:asText` on the upload object instead of\ninside an element of the `data` array; more than one of the allowed forms inside\na single array element.\n\n**Further reading:** [RFC 9404 \u00A74.1](https://www.rfc-editor.org/rfc/rfc9404#section-4.1).\n\n**Email parts:** in `Email/set`, `attachments[]` references the blob with\n`blobId` (e.g. `\"#b1\"` for create key `b1`), plus `type` / `name` per\nRFC 8621.\n\n**Out-of-band:** RFC 8620 `POST` to `uploadUrl` (MCP `attachments` / skill\n`--attachment`) then use `$ATTACHMENT_N_BLOB_ID` in the same JMAP JSON.\n\n## Placeholders\n\n- `$ACCOUNT_ID`, `$INBOX` (full mailbox **email** for `From` / envelope; from\n  `inboxId`, appending `@atomicmail.ai` or `ATOMIC_MAIL_INBOX_DOMAIN` when\n  needed), `$INBOX_MAILBOX_ID` (JMAP mailbox id \u2014 use for `Email/query` \u2192\n  `inMailbox` and `Email/set` \u2192 `mailboxIds`), `$UPLOAD_URL`,\n  `$DOWNLOAD_URL` resolve from the session.\n- Pass `$TO`, `$SUBJECT`, `$BODY`, etc. via MCP `vars` or skill `--vars`\n  (object of strings).\n\n## Bare methodCalls vs full envelope\n\nIf `ops` is **only** a methodCalls array, the default `using` is **core + mail**\nonly. For submission or blob methods, pass a full `{ \"using\", \"methodCalls\" }`\nobject (or use bundled presets, which include the right `using`).\n\n## Mailboxes\n\n```json\n[\"Mailbox/get\", {\"accountId\": \"$ACCOUNT_ID\"}, \"m0\"]\n```\n\n## Query + fetch latest inbox mail\n\n`inMailbox` must be a **mailbox id**, not the email address \u2014 use\n`$INBOX_MAILBOX_ID`.\n\n```json\n{\n  \"using\": [\"urn:ietf:params:jmap:core\", \"urn:ietf:params:jmap:mail\"],\n  \"methodCalls\": [\n    [\"Email/query\", {\n      \"accountId\": \"$ACCOUNT_ID\",\n      \"filter\": {\"inMailbox\": \"$INBOX_MAILBOX_ID\"},\n      \"sort\": [{\"property\": \"receivedAt\", \"isAscending\": false}],\n      \"limit\": 25\n    }, \"q0\"],\n    [\"Email/get\", {\n      \"accountId\": \"$ACCOUNT_ID\",\n      \"#ids\": {\"resultOf\": \"q0\", \"name\": \"Email/query\", \"path\": \"/ids\"},\n      \"properties\": [\"id\", \"threadId\", \"receivedAt\", \"from\", \"to\", \"subject\", \"preview\"]\n    }, \"g0\"]\n  ]\n}\n```\n\n## Send one email (draft + submit)\n\nSame pattern as bundled `send_mail.json`: `Email/set` includes\n`mailboxIds` with `$INBOX_MAILBOX_ID` as the mailbox id key, then\n`EmailSubmission/set` with `envelope`.\n\n```json\n{\n  \"using\": [\n    \"urn:ietf:params:jmap:core\",\n    \"urn:ietf:params:jmap:mail\",\n    \"urn:ietf:params:jmap:submission\"\n  ],\n  \"methodCalls\": [\n    [\"Email/set\", {\n      \"accountId\": \"$ACCOUNT_ID\",\n      \"create\": {\n        \"d1\": {\n          \"mailboxIds\": {\"$INBOX_MAILBOX_ID\": true},\n          \"from\": [{\"email\": \"$INBOX\"}],\n          \"to\": [{\"email\": \"$TO\"}],\n          \"subject\": \"$SUBJECT\",\n          \"textBody\": [{\"partId\": \"b\", \"type\": \"text/plain\"}],\n          \"bodyValues\": {\"b\": {\"value\": \"$BODY\"}},\n          \"keywords\": {\"$draft\": true}\n        }\n      }\n    }, \"c0\"],\n    [\"EmailSubmission/set\", {\n      \"accountId\": \"$ACCOUNT_ID\",\n      \"create\": {\n        \"s1\": {\n          \"emailId\": \"#d1\",\n          \"envelope\": {\n            \"mailFrom\": {\"email\": \"$INBOX\"},\n            \"rcptTo\": [{\"email\": \"$TO\"}]\n          }\n        }\n      }\n    }, \"c1\"]\n  ]\n}\n```\n\n## Attachment in one batch (`Blob/upload` + send)\n\n`Blob/upload` must follow RFC 9404 (see **`Blob/upload` shape** above). The\nbundled preset `send_mail_attachment.json` uses base64 parts:\n`\"data\": [{ \"data:asBase64\": \"$ATTACHMENT_BASE64\" }]` plus `type`. Vars:\n`TO`, `SUBJECT`, `BODY`, `ATTACHMENT_BASE64`, `ATTACHMENT_TYPE`,\n`ATTACHMENT_NAME`.\n\nMinimal inline example (base64 for UTF-8 `Hello`; replace addresses):\n\n```json\n{\n  \"using\": [\n    \"urn:ietf:params:jmap:core\",\n    \"urn:ietf:params:jmap:mail\",\n    \"urn:ietf:params:jmap:submission\",\n    \"urn:ietf:params:jmap:blob\"\n  ],\n  \"methodCalls\": [\n    [\"Blob/upload\", {\n      \"accountId\": \"$ACCOUNT_ID\",\n      \"create\": {\"b1\": {\"data\": [{ \"data:asBase64\": \"SGVsbG8=\" }], \"type\": \"text/plain\"}}\n    }, \"b0\"],\n    [\"Email/set\", {\n      \"accountId\": \"$ACCOUNT_ID\",\n      \"create\": {\n        \"m1\": {\n          \"mailboxIds\": {\"$INBOX_MAILBOX_ID\": true},\n          \"from\": [{\"email\": \"$INBOX\"}],\n          \"to\": [{\"email\": \"$TO\"}],\n          \"subject\": \"With attachment\",\n          \"bodyValues\": {\"body1\": {\"value\": \"See attachment.\"}},\n          \"textBody\": [{\"partId\": \"body1\", \"type\": \"text/plain\"}],\n          \"attachments\": [{\"blobId\": \"#b1\", \"type\": \"text/plain\", \"name\": \"note.txt\"}]\n        }\n      }\n    }, \"m0\"],\n    [\"EmailSubmission/set\", {\n      \"accountId\": \"$ACCOUNT_ID\",\n      \"create\": {\n        \"s1\": {\n          \"emailId\": \"#m1\",\n          \"envelope\": {\n            \"mailFrom\": {\"email\": \"$INBOX\"},\n            \"rcptTo\": [{\"email\": \"$TO\"}]\n          }\n        }\n      }\n    }, \"s0\"]\n  ]\n}\n```\n\n## Attachment via RFC 8620 (`uploadUrl`) \u2014 still standard JMAP\n\nKeep `Email/set` / `EmailSubmission/set` exactly as in RFC 8621; only the blob\nbytes go out-of-band: pass MCP `attachments` or skill `--attachment PATH`\n(repeatable). The client `POST`s each file to the session `uploadUrl`, then\nsubstitutes `$ATTACHMENT_0_BLOB_ID`, `$ATTACHMENT_0_NAME`, `$ATTACHMENT_0_TYPE`\ninto your `ops` / preset before the `/jmap/` batch. Bundled\n`send_mail_blob_attachment.json` is a minimal one-file example; for several\nparts, add more objects under `attachments` referencing `$ATTACHMENT_1_BLOB_ID`, etc.\nBefore POST, the client adds `charset` (default `utf-8`) to any `Email/set`\n`text/*` body part that uses `blobId` without `charset`, per RFC 8621.\n\n## Blob/get\n\nUse only property names allowed by [RFC 9404 \u00A74.2](https://www.rfc-editor.org/rfc/rfc9404#section-4.2)\n(for example `data:asBase64`, `size`). Do not list `id` or `type` in\n`properties` \u2014 `id` is still returned on each result object.\n\n```json\n{\n  \"using\": [\"urn:ietf:params:jmap:core\", \"urn:ietf:params:jmap:blob\"],\n  \"methodCalls\": [\n    [\"Blob/get\", {\n      \"accountId\": \"$ACCOUNT_ID\",\n      \"ids\": [\"$BLOB_ID\"],\n      \"properties\": [\"data:asBase64\", \"size\"]\n    }, \"g0\"]\n  ]\n}\n```\n\n## Blob/lookup\n\nReverse lookup: which mail objects reference a blob. Parameters `typeNames`,\n`ids`; errors include `unknownDataType`. See RFC 9404 \u00A74.3.\n\n## Tips\n\n- Back-references (`#b1`, `#m1`, `#draft`) chain calls in one batch.\n- Save reusable JSON as preset files and pass `ops_file`.";
+//# sourceMappingURL=jmap-cheatsheet.d.ts.map

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

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

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

@@ -0,0 +1,230 @@
+// Help topic: jmap_cheatsheet (MCP help / AgentSkill help).
+export const helpTopicJmapCheatsheet = `\
+# JMAP cheatsheet
+
+## Capabilities (\`using\`)
+
+Common URNs:
+
+- urn:ietf:params:jmap:core
+- urn:ietf:params:jmap:mail
+- urn:ietf:params:jmap:submission — required for \`EmailSubmission/set\`
+- urn:ietf:params:jmap:blob — required for \`Blob/upload\`, \`Blob/get\`, and
+  \`Blob/lookup\` (see RFC 9404 §4.3 for reverse blob references).
+
+## Session blob limits
+
+Per-account limits live under
+\`accounts[accountId].accountCapabilities["urn:ietf:params:jmap:blob"]\` (see
+[RFC 9404 §3.1](https://www.rfc-editor.org/rfc/rfc9404#section-3.1)):
+\`maxSizeBlobSet\`, \`maxDataSources\`, etc. MCP and AgentSkill **reject before
+POST** when a computable \`Blob/upload\` payload or an \`attachments\` file would
+exceed advertised \`maxSizeBlobSet\` or \`maxDataSources\` (\`maxSizeBlobSet:
+null\` means no client octet cap). Literal (non-\`#\`) \`blobId\` slices are not
+pre-sized on the client.
+
+## \`Blob/upload\` shape (RFC 9404)
+
+Each \`Blob/upload\` \`create\` value is an **UploadObject**: required \`data\` is
+an **array** of **DataSourceObject**; each array element uses **exactly one** of
+\`data:asText\`, \`data:asBase64\`, or \`blobId\` (+ optional \`offset\` /
+\`length\`). Optional \`type\` is a media-type hint. In one batch, reference a
+created blob as \`"#b1"\` when the create key was \`b1\`.
+
+**Invalid shapes** (do not expect servers to fix these): \`data\` as a plain
+string; \`data:asBase64\` / \`data:asText\` on the upload object instead of
+inside an element of the \`data\` array; more than one of the allowed forms inside
+a single array element.
+
+**Further reading:** [RFC 9404 §4.1](https://www.rfc-editor.org/rfc/rfc9404#section-4.1).
+
+**Email parts:** in \`Email/set\`, \`attachments[]\` references the blob with
+\`blobId\` (e.g. \`"#b1"\` for create key \`b1\`), plus \`type\` / \`name\` per
+RFC 8621.
+
+**Out-of-band:** RFC 8620 \`POST\` to \`uploadUrl\` (MCP \`attachments\` / skill
+\`--attachment\`) then use \`$ATTACHMENT_N_BLOB_ID\` in the same JMAP JSON.
+
+## Placeholders
+
+- \`$ACCOUNT_ID\`, \`$INBOX\` (full mailbox **email** for \`From\` / envelope; from
+  \`inboxId\`, appending \`@atomicmail.ai\` or \`ATOMIC_MAIL_INBOX_DOMAIN\` when
+  needed), \`$INBOX_MAILBOX_ID\` (JMAP mailbox id — use for \`Email/query\` →
+  \`inMailbox\` and \`Email/set\` → \`mailboxIds\`), \`$UPLOAD_URL\`,
+  \`$DOWNLOAD_URL\` resolve from the session.
+- Pass \`$TO\`, \`$SUBJECT\`, \`$BODY\`, etc. via MCP \`vars\` or skill \`--vars\`
+  (object of strings).
+
+## Bare methodCalls vs full envelope
+
+If \`ops\` is **only** a methodCalls array, the default \`using\` is **core + mail**
+only. For submission or blob methods, pass a full \`{ "using", "methodCalls" }\`
+object (or use bundled presets, which include the right \`using\`).
+
+## Mailboxes
+
+\`\`\`json
+["Mailbox/get", {"accountId": "$ACCOUNT_ID"}, "m0"]
+\`\`\`
+
+## Query + fetch latest inbox mail
+
+\`inMailbox\` must be a **mailbox id**, not the email address — use
+\`$INBOX_MAILBOX_ID\`.
+
+\`\`\`json
+{
+  "using": ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:mail"],
+  "methodCalls": [
+    ["Email/query", {
+      "accountId": "$ACCOUNT_ID",
+      "filter": {"inMailbox": "$INBOX_MAILBOX_ID"},
+      "sort": [{"property": "receivedAt", "isAscending": false}],
+      "limit": 25
+    }, "q0"],
+    ["Email/get", {
+      "accountId": "$ACCOUNT_ID",
+      "#ids": {"resultOf": "q0", "name": "Email/query", "path": "/ids"},
+      "properties": ["id", "threadId", "receivedAt", "from", "to", "subject", "preview"]
+    }, "g0"]
+  ]
+}
+\`\`\`
+
+## Send one email (draft + submit)
+
+Same pattern as bundled \`send_mail.json\`: \`Email/set\` includes
+\`mailboxIds\` with \`$INBOX_MAILBOX_ID\` as the mailbox id key, then
+\`EmailSubmission/set\` with \`envelope\`.
+
+\`\`\`json
+{
+  "using": [
+    "urn:ietf:params:jmap:core",
+    "urn:ietf:params:jmap:mail",
+    "urn:ietf:params:jmap:submission"
+  ],
+  "methodCalls": [
+    ["Email/set", {
+      "accountId": "$ACCOUNT_ID",
+      "create": {
+        "d1": {
+          "mailboxIds": {"$INBOX_MAILBOX_ID": true},
+          "from": [{"email": "$INBOX"}],
+          "to": [{"email": "$TO"}],
+          "subject": "$SUBJECT",
+          "textBody": [{"partId": "b", "type": "text/plain"}],
+          "bodyValues": {"b": {"value": "$BODY"}},
+          "keywords": {"$draft": true}
+        }
+      }
+    }, "c0"],
+    ["EmailSubmission/set", {
+      "accountId": "$ACCOUNT_ID",
+      "create": {
+        "s1": {
+          "emailId": "#d1",
+          "envelope": {
+            "mailFrom": {"email": "$INBOX"},
+            "rcptTo": [{"email": "$TO"}]
+          }
+        }
+      }
+    }, "c1"]
+  ]
+}
+\`\`\`
+
+## Attachment in one batch (\`Blob/upload\` + send)
+
+\`Blob/upload\` must follow RFC 9404 (see **\`Blob/upload\` shape** above). The
+bundled preset \`send_mail_attachment.json\` uses base64 parts:
+\`"data": [{ "data:asBase64": "$ATTACHMENT_BASE64" }]\` plus \`type\`. Vars:
+\`TO\`, \`SUBJECT\`, \`BODY\`, \`ATTACHMENT_BASE64\`, \`ATTACHMENT_TYPE\`,
+\`ATTACHMENT_NAME\`.
+
+Minimal inline example (base64 for UTF-8 \`Hello\`; replace addresses):
+
+\`\`\`json
+{
+  "using": [
+    "urn:ietf:params:jmap:core",
+    "urn:ietf:params:jmap:mail",
+    "urn:ietf:params:jmap:submission",
+    "urn:ietf:params:jmap:blob"
+  ],
+  "methodCalls": [
+    ["Blob/upload", {
+      "accountId": "$ACCOUNT_ID",
+      "create": {"b1": {"data": [{ "data:asBase64": "SGVsbG8=" }], "type": "text/plain"}}
+    }, "b0"],
+    ["Email/set", {
+      "accountId": "$ACCOUNT_ID",
+      "create": {
+        "m1": {
+          "mailboxIds": {"$INBOX_MAILBOX_ID": true},
+          "from": [{"email": "$INBOX"}],
+          "to": [{"email": "$TO"}],
+          "subject": "With attachment",
+          "bodyValues": {"body1": {"value": "See attachment."}},
+          "textBody": [{"partId": "body1", "type": "text/plain"}],
+          "attachments": [{"blobId": "#b1", "type": "text/plain", "name": "note.txt"}]
+        }
+      }
+    }, "m0"],
+    ["EmailSubmission/set", {
+      "accountId": "$ACCOUNT_ID",
+      "create": {
+        "s1": {
+          "emailId": "#m1",
+          "envelope": {
+            "mailFrom": {"email": "$INBOX"},
+            "rcptTo": [{"email": "$TO"}]
+          }
+        }
+      }
+    }, "s0"]
+  ]
+}
+\`\`\`
+
+## Attachment via RFC 8620 (\`uploadUrl\`) — still standard JMAP
+
+Keep \`Email/set\` / \`EmailSubmission/set\` exactly as in RFC 8621; only the blob
+bytes go out-of-band: pass MCP \`attachments\` or skill \`--attachment PATH\`
+(repeatable). The client \`POST\`s each file to the session \`uploadUrl\`, then
+substitutes \`$ATTACHMENT_0_BLOB_ID\`, \`$ATTACHMENT_0_NAME\`, \`$ATTACHMENT_0_TYPE\`
+into your \`ops\` / preset before the \`/jmap/\` batch. Bundled
+\`send_mail_blob_attachment.json\` is a minimal one-file example; for several
+parts, add more objects under \`attachments\` referencing \`$ATTACHMENT_1_BLOB_ID\`, etc.
+Before POST, the client adds \`charset\` (default \`utf-8\`) to any \`Email/set\`
+\`text/*\` body part that uses \`blobId\` without \`charset\`, per RFC 8621.
+
+## Blob/get
+
+Use only property names allowed by [RFC 9404 §4.2](https://www.rfc-editor.org/rfc/rfc9404#section-4.2)
+(for example \`data:asBase64\`, \`size\`). Do not list \`id\` or \`type\` in
+\`properties\` — \`id\` is still returned on each result object.
+
+\`\`\`json
+{
+  "using": ["urn:ietf:params:jmap:core", "urn:ietf:params:jmap:blob"],
+  "methodCalls": [
+    ["Blob/get", {
+      "accountId": "$ACCOUNT_ID",
+      "ids": ["$BLOB_ID"],
+      "properties": ["data:asBase64", "size"]
+    }, "g0"]
+  ]
+}
+\`\`\`
+
+## Blob/lookup
+
+Reverse lookup: which mail objects reference a blob. Parameters \`typeNames\`,
+\`ids\`; errors include \`unknownDataType\`. See RFC 9404 §4.3.
+
+## Tips
+
+- Back-references (\`#b1\`, \`#m1\`, \`#draft\`) chain calls in one batch.
+- Save reusable JSON as preset files and pass \`ops_file\`.`;

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

@@ -0,0 +1,2 @@
+export declare const helpTopicMultiAccount = "# Multiple accounts and agents\n\nOne MCP server or CLI install can manage **several isolated inboxes** by using a\n**separate credential directory per account**. Each directory holds its own\n`credentials.json`, `session.jwt`, and `capability.jwt` (mode `0600`).\n\n## MCP (per tool call)\n\nPass optional `credentials_dir` on `register` and `jmap_request`:\n\n```json\n{ \"username\": \"alice\", \"credentials_dir\": \"~/.atomicmail/alice\" }\n{ \"ops_file\": \"list_inbox.json\", \"credentials_dir\": \"~/.atomicmail/bob\" }\n```\n\nWhen omitted, the default directory applies (`ATOMIC_MAIL_CREDENTIALS_DIR` or\n`~/.atomicmail`).\n\n## AgentSkill (per command)\n\n```bash\natomicmail register --username alice --credentials-dir ~/.atomicmail/alice\natomicmail jmap_request --credentials-dir ~/.atomicmail/bob --ops-file list_inbox.json\n```\n\n## Default vs per-call\n\n- **Default directory:** set once via `ATOMIC_MAIL_CREDENTIALS_DIR` (MCP host\n  `env`) or by omitting `credentials_dir` / `--credentials-dir`.\n- **Per-call override:** use a different path on each `register` or\n  `jmap_request` when the agent should act as another inbox.\n\nYou no longer need multiple MCP server entries with different `env` blocks\nunless you prefer that layout.\n\n## Register: forced vs separate directory\n\nIf the default directory already has an account and you want a **second**\ninbox, pass a **new** `credentials_dir` / `--credentials-dir` instead of\n`forced: true` / `--forced`. Use `forced` only when you intend to\n**replace** credentials in the **same** directory (after backing up).\n\n## Concurrency\n\nDo not run parallel `register` or `jmap_request` calls against the **same**\ncredential directory. JWT files are rewritten without locking (same caveat as\nthe CLI). Different directories are independent.";
+//# sourceMappingURL=multi-account.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"multi-account.d.ts","sourceRoot":"","sources":["../../../../../src/lib/agent/jmap/help-content/multi-account.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,qBAAqB,8xDA+Ce,CAAC"}

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

@@ -0,0 +1,49 @@
+// Help topic: multi_account (MCP help / AgentSkill help).
+export const helpTopicMultiAccount = `\
+# Multiple accounts and agents
+
+One MCP server or CLI install can manage **several isolated inboxes** by using a
+**separate credential directory per account**. Each directory holds its own
+\`credentials.json\`, \`session.jwt\`, and \`capability.jwt\` (mode \`0600\`).
+
+## MCP (per tool call)
+
+Pass optional \`credentials_dir\` on \`register\` and \`jmap_request\`:
+
+\`\`\`json
+{ "username": "alice", "credentials_dir": "~/.atomicmail/alice" }
+{ "ops_file": "list_inbox.json", "credentials_dir": "~/.atomicmail/bob" }
+\`\`\`
+
+When omitted, the default directory applies (\`ATOMIC_MAIL_CREDENTIALS_DIR\` or
+\`~/.atomicmail\`).
+
+## AgentSkill (per command)
+
+\`\`\`bash
+atomicmail register --username alice --credentials-dir ~/.atomicmail/alice
+atomicmail jmap_request --credentials-dir ~/.atomicmail/bob --ops-file list_inbox.json
+\`\`\`
+
+## Default vs per-call
+
+- **Default directory:** set once via \`ATOMIC_MAIL_CREDENTIALS_DIR\` (MCP host
+  \`env\`) or by omitting \`credentials_dir\` / \`--credentials-dir\`.
+- **Per-call override:** use a different path on each \`register\` or
+  \`jmap_request\` when the agent should act as another inbox.
+
+You no longer need multiple MCP server entries with different \`env\` blocks
+unless you prefer that layout.
+
+## Register: forced vs separate directory
+
+If the default directory already has an account and you want a **second**
+inbox, pass a **new** \`credentials_dir\` / \`--credentials-dir\` instead of
+\`forced: true\` / \`--forced\`. Use \`forced\` only when you intend to
+**replace** credentials in the **same** directory (after backing up).
+
+## Concurrency
+
+Do not run parallel \`register\` or \`jmap_request\` calls against the **same**
+credential directory. JWT files are rewritten without locking (same caveat as
+the CLI). Different directories are independent.`;

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

@@ -0,0 +1,2 @@
+export declare const helpTopicOverview = "# Atomic Mail \u2014 Overview\n\nAtomic Mail is an email service provider (ESP) designed for AI agents. You\nmanage mail over JMAP (RFC 8620 + RFC 8621).\n\n## Public surface (identical for MCP and AgentSkill)\n\nThree operations only:\n\n1. **register** \u2014 Proof-of-work signup (or idempotent replay when the same\n   username matches the inbox already on disk). Usernames are 5\u201321 characters\n   (local-part of `@atomicmail.ai`). When a different username is\n   requested and credentials already exist, register fails unless you use a\n   separate `credentials_dir` / `--credentials-dir` or pass `forced: true`\n   / `--forced` to replace the current directory. Persists\n   credentials and returns `{ inbox, accountId }` (and `apiKey` on first\n   signup).\n2. **jmap_request** \u2014 Send a JMAP method-call batch; auth and JWT rotation are\n   automatic. Pass inline `ops` JSON or an `ops_file` preset (same\n   substitution for both). Session-backed tokens (`$ACCOUNT_ID`, `$INBOX`,\n   `$INBOX_MAILBOX_ID`, `$UPLOAD_URL`, `$DOWNLOAD_URL`) resolve from\n   credentials and JMAP session (`$INBOX` is always a full mailbox address;\n   `$INBOX_MAILBOX_ID` is the inbox **mailbox id** for filters and\n   `mailboxIds` \u2014 see **presets** topic). Pass any other `$NAME` via MCP\n   `vars` or `--vars`. Optional **attachments** (MCP `attachments`, skill\n   `--attachment`): each file is uploaded to `uploadUrl` (RFC 8620), then\n   `$ATTACHMENT_0_BLOB_ID`, \u2026 are substituted into your JMAP JSON.\n3. **help** \u2014 This documentation (optional `topic` / `--topic`), or the\n   published package README (`topic` / `--topic` `readme`).\n\n## Typical workflow\n\n1. `register` with a username (5\u201321 characters).\n2. After register, arrange hourly inbox polling per your runtime (see **cron**\n   topic \u2014 native scheduler if available; otherwise ask your operator or remind\n   manual fetch). Do not cron `atomicmail jmap_request` alone.\n3. `jmap_request` with JMAP method calls (presets may use `$VAR_NAME`; pass\n   custom values in `vars` / `--vars`).\n4. Call `help` early and often \u2014 before guessing JMAP or preset details, not\n   only when stuck. Prefer `help` over general JMAP knowledge; topics match\n   this package version.\n\nAFTER REGISTER \u2014 INBOX POLLING\n  Choose the path that matches your runtime (help topic \"cron\"):\n  \u2022 Native cron (OpenClaw, Hermes, atomic-agent, \u2026): schedule an hourly AGENT turn with list_inbox.json in the prompt; wire MCP or AgentSkill into that agent. Do NOT cron atomicmail jmap_request alone.\n  \u2022 No native cron (Claude, Pi, Cursor, \u2026): do NOT work around this (no wrapper scripts, OS crontab/LaunchAgent, or cross-platform scheduling). Ask your operator to set up polling on a capable host, or remind them to fetch mail manually when needed.\n  \u2022 Forbidden: register in one runtime and schedule the cron job on another.\n\nAvailable topics: overview, installation, auth, jmap_cheatsheet, tools,\npresets, cron, multi_account, troubleshooting. Use `readme` for the npm package `README.md`.";
+//# sourceMappingURL=overview.d.ts.map

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

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