@atomicmail/langchain 0.3.14

package/presets/send_mail.json

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

package/presets/send_mail_attachment.json

@@ -0,0 +1,92 @@
+{
+  "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": "$ATTACHMENT_BASE64"
+              }
+            ],
+            "type": "$ATTACHMENT_TYPE"
+          }
+        }
+      },
+      "b0"
+    ],
+    [
+      "Email/set",
+      {
+        "accountId": "$ACCOUNT_ID",
+        "create": {
+          "m1": {
+            "mailboxIds": {
+              "$INBOX_MAILBOX_ID": true
+            },
+            "from": [
+              {
+                "email": "$INBOX"
+              }
+            ],
+            "to": [
+              {
+                "email": "$TO"
+              }
+            ],
+            "subject": "$SUBJECT",
+            "bodyValues": {
+              "body1": {
+                "value": "$BODY"
+              }
+            },
+            "textBody": [
+              {
+                "partId": "body1",
+                "type": "text/plain"
+              }
+            ],
+            "attachments": [
+              {
+                "blobId": "#b1",
+                "type": "$ATTACHMENT_TYPE",
+                "name": "$ATTACHMENT_NAME"
+              }
+            ]
+          }
+        }
+      },
+      "m0"
+    ],
+    [
+      "EmailSubmission/set",
+      {
+        "accountId": "$ACCOUNT_ID",
+        "create": {
+          "s1": {
+            "emailId": "#m1",
+            "envelope": {
+              "mailFrom": {
+                "email": "$INBOX"
+              },
+              "rcptTo": [
+                {
+                  "email": "$TO"
+                }
+              ]
+            }
+          }
+        }
+      },
+      "s0"
+    ]
+  ]
+}

package/presets/send_mail_blob_attachment.json

@@ -0,0 +1,74 @@
+{
+  "using": [
+    "urn:ietf:params:jmap:core",
+    "urn:ietf:params:jmap:mail",
+    "urn:ietf:params:jmap:submission"
+  ],
+  "methodCalls": [
+    [
+      "Email/set",
+      {
+        "accountId": "$ACCOUNT_ID",
+        "create": {
+          "m1": {
+            "mailboxIds": {
+              "$INBOX_MAILBOX_ID": true
+            },
+            "from": [
+              {
+                "email": "$INBOX"
+              }
+            ],
+            "to": [
+              {
+                "email": "$TO"
+              }
+            ],
+            "subject": "$SUBJECT",
+            "bodyValues": {
+              "body1": {
+                "value": "$BODY"
+              }
+            },
+            "textBody": [
+              {
+                "partId": "body1",
+                "type": "text/plain"
+              }
+            ],
+            "attachments": [
+              {
+                "blobId": "$ATTACHMENT_0_BLOB_ID",
+                "type": "$ATTACHMENT_0_TYPE",
+                "name": "$ATTACHMENT_0_NAME"
+              }
+            ]
+          }
+        }
+      },
+      "m0"
+    ],
+    [
+      "EmailSubmission/set",
+      {
+        "accountId": "$ACCOUNT_ID",
+        "create": {
+          "s1": {
+            "emailId": "#m1",
+            "envelope": {
+              "mailFrom": {
+                "email": "$INBOX"
+              },
+              "rcptTo": [
+                {
+                  "email": "$TO"
+                }
+              ]
+            }
+          }
+        }
+      },
+      "s0"
+    ]
+  ]
+}

package/shared/consts.json

@@ -0,0 +1,11 @@
+{
+  "DEFAULT_POW_SCRYPT_SALT_HEX": "0b980734412c292d6549110276b604ab1dea4883bd460d77d1b984adf8bca083",
+  "DEFAULT_AUTH_URL": "https://auth.atomicmail.ai",
+  "DEFAULT_API_URL": "https://api.atomicmail.ai",
+  "ONE_SEC_MS": 1000,
+  "ONE_MIN_MS": 60000,
+  "ONE_HOUR_MS": 3600000,
+  "ONE_DAY_MS": 86400000,
+  "ONE_MONTH_MS": 2592000000,
+  "ONE_YEAR_MS": 31536000000
+}

package/shared/fixtures/pow_vectors.json

@@ -0,0 +1,32 @@
+{
+  "generated_by": "ts/generate_pow_vectors.ts",
+  "scrypt": {
+    "N": 16384,
+    "r": 8,
+    "p": 1,
+    "dklen": 64
+  },
+  "vectors": [
+    {
+      "challenge": "fixture-alpha",
+      "difficulty": 4,
+      "nonce": "4",
+      "powHex": "0e365cf9d7a9a9d515b5362da1ed60b3c287d6b5de7f5f0e55b15bd8a34dd3605695e20f01fb60fbfd64f21dfafe151dcf22ba6b85bbd932fb569f89150c7c50",
+      "salt": "0b980734412c292d6549110276b604ab1dea4883bd460d77d1b984adf8bca083"
+    },
+    {
+      "challenge": "fixture-beta",
+      "difficulty": 6,
+      "nonce": "51",
+      "powHex": "0326f14661b1f70377aafd19280fcf8f6f21a0aec4ef3af4bd3c37493cc9b306ddaadce199044c03dbc013de84be945ef22e87675af65398de37b64a8cfedf38",
+      "salt": "0b980734412c292d6549110276b604ab1dea4883bd460d77d1b984adf8bca083"
+    },
+    {
+      "challenge": "fixture-gamma",
+      "difficulty": 8,
+      "nonce": "80",
+      "powHex": "004f0f2b137a745d72ff9ba1cacda12d8a8c8c309060abd918d78116e4f3e7b60dbe9f2653d1c357e6835e552523f132baaf39877deb2b14f36b3f0c3cd41748",
+      "salt": "0b980734412c292d6549110276b604ab1dea4883bd460d77d1b984adf8bca083"
+    }
+  ]
+}

package/shared/help/fragments/inbox_cron_agent_prompt.md

@@ -0,0 +1 @@
+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.

package/shared/help/fragments/post_register_cron_reminder.md

@@ -0,0 +1,5 @@
+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.

package/shared/help/readme_stub.md

@@ -0,0 +1,3 @@
+Topic `readme` returns this built-in stub in AgentSkill runtimes.
+In MCP runtimes, `help` with `{"topic":"readme"}` returns package `README.md`.
+Use CLI: `atomicmail help --topic readme`

package/shared/help/topics/auth.md

@@ -0,0 +1,8 @@
+# Atomic Mail — Auth flow
+
+1. `POST /api/v1/challenge` to get challenge JWT from `Authorization` header.
+2. Solve PoW with scrypt (`N=16384,r=8,p=1,dklen=64`).
+3. `POST /api/v1/session` with challenge JWT + PoW fields in JSON body.
+4. `POST /api/v1/capability` with session JWT to get capability JWT.
+
+JWTs are refreshed automatically and persisted to disk.

package/shared/help/topics/cron.md

@@ -0,0 +1,217 @@
+# 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
+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.
+```
+
+## Scheduling examples (for capable hosts or operators)
+
+| Your setup | Recommended approach |
+| --- | --- |
+| OpenClaw gateway | Built-in `openclaw cron` |
+| Hermes Agent | Install Atomic Mail 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 |
+
+These examples run a full agent turn and deliver the summary to a chat or file so
+the operator can reply, forward, or ask follow-ups in the same thread.
+
+### OpenClaw
+
+Docs: https://docs.openclaw.ai/automation/cron-jobs
+
+- Schedule: `--cron "0 * * * *"` or `--every 1h`
+- Session: `--session isolated` (fresh turn each run)
+- Delivery: `--announce` (posts to your configured channel)
+- Prompt: `--message` with the agent prompt above
+
+```bash
+openclaw cron add \
+  --name "atomicmail-inbox" \
+  --cron "0 * * * *" \
+  --session isolated \
+  --message "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." \
+  --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: skill + blueprint
+
+1. Install the **Atomic Mail** skill from the unified in-repo tap
+   (`hermes skills install Atomic-Mail/atomic-mail-agentic/integrations/skill/atomicmail`).
+2. After the first successful `register`, accept the hourly inbox **blueprint**
+   via `/suggestions`.
+
+The blueprint schedules a full **agent** turn (`no_agent: false`) with
+`list_inbox.json` and delivers to `origin`. Do **not** skip this step. Do **not**
+schedule raw `jmap_request` cron jobs or use `--no-agent` (script-only; no LLM).
+
+#### Credentials on Hermes
+
+- Default directory: `~/.hermes/atomicmail` (not `~/.atomicmail`).
+- The skill launcher sets `ATOMIC_MAIL_CREDENTIALS_DIR` to
+  `$HOME/.hermes/atomicmail` when that variable is **not** already set — operator
+  overrides are preserved.
+- Override explicitly with `ATOMIC_MAIL_CREDENTIALS_DIR` or
+  `atomicmail.credentials_dir` in Hermes config.
+
+#### Multi-account only
+
+Operating multiple inboxes at once: pass `--credentials-dir` (skill) or
+`credentials_dir` (MCP) on `register` / `jmap_request` with a separate directory
+per account. Not needed for the default single-inbox flow.
+
+#### Manual fallback: `hermes cron`
+
+If you are not using the skill blueprint, create the job manually:
+
+- Schedule: cron expression (`0 * * * *`) or natural language (`every 1h`)
+- Delivery: `--deliver origin` (or `telegram`, `discord`, `slack`, `email`,
+  `local`, etc.)
+- **Do not** use `--no-agent`
+
+```bash
+hermes cron create "0 * * * *" \
+  "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." \
+  --name "atomicmail-inbox" \
+  --deliver origin
+```
+
+In chat: `/cron add "0 * * * *" "<prompt>" --deliver origin`. Manage:
+`hermes cron list` · test: `hermes cron run <job-id>`
+
+### Atomic Bot (atomicbot.ai)
+
+Runs OpenClaw or Hermes — use the matching block above.
+
+### atomic-agent
+
+Docs: https://github.com/AtomicBot-ai/atomic-agent
+
+```bash
+atomic-agent task create \
+  --cron "0 * * * *" \
+  --message "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."
+```
+
+Manage: `atomic-agent task list`
+
+## Verify setup
+
+After scheduling (or after asking your operator to schedule):
+
+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 (Claude, Pi, Cursor, …) should **not** attempt OS scheduling
+themselves — ask the operator to set up polling on a capable host or fetch mail
+manually.
+
+If you (the operator) run a **terminal CLI agent** and want hourly inbox checks
+without OpenClaw, Hermes, or similar, the scheduler must **start an interactive
+session** with the agent prompt — not call `atomicmail` directly.
+
+### Terminal agents (interactive invocation)
+
+| Agent | Start interactively | Avoid for inbox polling |
+| --- | --- | --- |
+| Claude Code | `claude "prompt"` | `claude -p` |
+| Pi | `pi "prompt"` | `pi -p` |
+| Cursor CLI | `agent "prompt"` | `agent -p` |
+| Gemini CLI | `gemini -i "prompt"` | `gemini -p` |
+| Codex CLI | `codex` (TUI) | `codex exec` |
+
+Resolve the binary on **your** machine (`command -v claude`, `command -v pi`,
+etc.) and use that path in scripts.
+
+### OS scheduling approaches
+
+Pick what fits your OS and how you work:
+
+**A. Wrapper script + user crontab**
+
+Write a small script that (1) sets any API keys the agent needs, (2) launches
+your terminal emulator or GUI session, (3) runs the agent **interactively** with
+the prompt. Point crontab at the script. Cron does not load shell startup
+files — export env vars inside the script.
+
+**B. macOS LaunchAgent**
+
+A `LaunchAgents` plist on a calendar interval often works better than crontab
+for opening Terminal or iTerm and starting an interactive agent in the logged-in
+GUI session.
+
+**C. Linux graphical session**
+
+Schedule via user crontab or a **systemd user timer**, launching a terminal
+emulator only when a graphical session is active (`DISPLAY`,
+`DBUS_SESSION_BUS_ADDRESS` for your session).
+
+Test manually before automating: run the same command you intend to schedule and
+confirm the agent can call `list_inbox.json` and wait for your replies.

package/shared/help/topics/installation.md

@@ -0,0 +1,35 @@
+# 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 host** (OpenClaw, Hermes, atomic-agent, …): schedule an hourly
+  **agent** turn with `list_inbox.json` inside the prompt.
+- **No native cron** (Claude, Pi, Cursor, …): ask your operator to set up
+  polling on a capable host, or remind them to fetch mail manually when needed.
+  Do not work around this with wrapper scripts or OS schedulers.
+
+Do not cron `atomicmail jmap_request` alone.

package/shared/help/topics/jmap_cheatsheet.md

@@ -0,0 +1,19 @@
+# JMAP cheatsheet
+
+## Capabilities (`using`)
+
+- `urn:ietf:params:jmap:core`
+- `urn:ietf:params:jmap:mail`
+- `urn:ietf:params:jmap:submission`
+- `urn:ietf:params:jmap:blob`
+
+## Placeholders
+
+- `$ACCOUNT_ID`, `$INBOX`, `$INBOX_MAILBOX_ID`, `$UPLOAD_URL`, `$DOWNLOAD_URL`
+- Any other `$NAME` must come from `vars` / `--vars`.
+
+## Notes
+
+- Bare methodCalls arrays default to core+mail only.
+- For submission/blob methods use a full envelope with `using`.
+- `inMailbox` expects mailbox id (`$INBOX_MAILBOX_ID`), not email address.

package/shared/help/topics/multi_account.md

@@ -0,0 +1,9 @@
+# Multiple accounts and agents
+
+Use separate credential directories per account. Each directory stores:
+
+- `credentials.json`
+- `session.jwt`
+- `capability.jwt`
+
+Override per call with `credentials_dir` (MCP) or `--credentials-dir` (skill).

package/shared/help/topics/overview.md

@@ -0,0 +1,27 @@
+# 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
+
+Three operations only:
+
+1. **register** — proof-of-work signup with optional idempotent replay.
+2. **jmap_request** — run JMAP method-call batches with auth + JWT rotation.
+3. **help** — read built-in docs and package README.
+
+## Typical workflow
+
+1. Register with a username (5–21 chars).
+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. Use `jmap_request` with `ops` or `ops_file`; supply `vars` as needed.
+4. Use `help` topics before guessing protocol details.
+
+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.

package/shared/help/topics/presets.md

@@ -0,0 +1,12 @@
+# JMAP presets
+
+Bundled presets:
+
+- `send_mail.json`
+- `list_inbox.json`
+- `reply.json`
+- `send_mail_attachment.json`
+- `send_mail_blob_attachment.json`
+
+Relative `ops_file` paths resolve from credentials directory first, then bundled
+presets shipped with the package.

package/shared/help/topics/tools.md

@@ -0,0 +1,16 @@
+# Tool / CLI reference
+
+## register
+
+- MCP: `{ "username": string, "credentials_dir"?: string, "forced"?: boolean }`
+- Skill: `register --username NAME [--credentials-dir DIR] [--forced]`
+
+## jmap_request
+
+- MCP: one of `ops` or `ops_file`, optional `vars`, optional `attachments`.
+- Skill: one of `--ops` or `--ops-file`, optional `--vars`, `--attachment`.
+
+## help
+
+- MCP: `{ "topic"?: string }`
+- Skill: `help [--topic TOPIC]`

package/shared/help/topics/troubleshooting.md

@@ -0,0 +1,6 @@
+# Troubleshooting
+
+- Missing API key: run `register` or provide valid credentials.
+- Wrong `inMailbox`: use `$INBOX_MAILBOX_ID` (mailbox id), not inbox email.
+- Blob/upload shape errors: `data` must be an array of datasource objects.
+- Missing variables (`$TO`, etc.): provide them via `vars` / `--vars`.