@atomicmail/agent-skill-openclaw 0.3.24

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`.

package/shared/manifest.json

@@ -0,0 +1,31 @@
+{
+  "version": 1,
+  "compat": {
+    "ts_min": "0.0.0"
+  },
+  "consts_path": "consts.json",
+  "messages": {
+    "errors_path": "messages/errors.json",
+    "hints_path": "messages/hints.json"
+  },
+  "presets_dir": "presets",
+  "help": {
+    "readme_stub_path": "help/readme_stub.md",
+    "topics_dir": "help/topics",
+    "fragments_dir": "help/fragments",
+    "topic_order": [
+      "overview",
+      "installation",
+      "auth",
+      "jmap_cheatsheet",
+      "tools",
+      "presets",
+      "cron",
+      "multi_account",
+      "troubleshooting"
+    ]
+  },
+  "fixtures": {
+    "pow_vectors_path": "fixtures/pow_vectors.json"
+  }
+}

package/shared/messages/errors.json

@@ -0,0 +1,68 @@
+{
+  "mcp_ops_mutually_exclusive": "ops and ops_file are mutually exclusive — provide one.",
+  "mcp_ops_required": "Provide either ops or ops_file.",
+  "cli_ops_mutually_exclusive": "--ops and --ops-file are mutually exclusive.",
+  "cli_ops_required": "Provide --ops or --ops-file.",
+  "cli_dry_run_with_attachment": "--dry-run cannot be combined with --attachment.",
+  "cli_unknown_command_template": "Unknown command: {cmd}",
+  "help_unknown_topic_template": "Unknown topic \"{topic}\". Available topics: {topics}, readme",
+  "help_readme_stub": "Topic \"readme\" returns a built-in stub in AgentSkill runtimes. From MCP, topic \"readme\" returns package README.md.",
+  "vars_invalid_json_template": "--vars is not valid JSON: {details}",
+  "vars_not_object": "--vars must be a JSON object of { VAR_NAME: string }.",
+  "vars_key_invalid_template": "--vars key '{key}' must match /^[A-Z][A-Z0-9_]*$/.",
+  "vars_value_not_string_template": "--vars value for '{key}' must be a string.",
+  "vars_missing_template": "Missing values for variables: {vars}. Pass custom placeholders in vars (MCP) or --vars (skill).",
+  "vars_missing_session_suffix": " For $ACCOUNT_ID, $INBOX, and $INBOX_MAILBOX_ID, ensure register completed and credentials are valid, or pass overrides in vars.",
+  "jmap_json_invalid_template": "{source} is not valid JSON: {details}",
+  "jmap_envelope_invalid_template": "{source} must be a methodCalls array, e.g. [[\"Mailbox/get\",{...},\"m0\"]], or an object with a methodCalls array.",
+  "jmap_ops_file_not_found_template": "ops_file '{ops_file}' not found under credential directory ({path}) and not among bundled presets: {presets}.",
+  "jmap_session_missing_primary_accounts": "JMAP session missing primaryAccounts.",
+  "jmap_session_missing_primary_mail_template": "JMAP session missing primaryAccounts['{urn}'].",
+  "jmap_session_missing_upload_url": "JMAP session missing uploadUrl.",
+  "jmap_session_missing_download_url": "JMAP session missing downloadUrl.",
+  "jmap_session_missing_api_url": "JMAP session missing apiUrl.",
+  "jmap_session_fetch_failed_template": "JMAP session fetch failed (HTTP {status}): {body}",
+  "jmap_session_response_not_json": "JMAP session response is not valid JSON.",
+  "jmap_dry_run_with_attachments": "dryRun cannot be used with attachments: RFC 8620 upload runs first and would create blobs.",
+  "mailbox_query_failed_http_template": "Mailbox/query failed (HTTP {status}): {body}",
+  "mailbox_query_response_not_json": "Mailbox/query response is not valid JSON.",
+  "mailbox_query_failed_template": "Mailbox/query failed: {body}",
+  "mailbox_query_missing_inbox_id": "Mailbox/query returned no inbox mailbox id.",
+  "agent_username_length": "Username must be 5–21 characters.",
+  "agent_register_api_key_without_inbox": "Cannot register: an API key is configured but inboxId is unknown. Fix credentials.json or unset ATOMIC_MAIL_API_KEY before registering.",
+  "agent_register_refused_existing_credentials_template": "Register refused because credentials already belong to \"{inbox}\" and requested username is \"{username}\". Alternatively, use a separate credential directory (credentials_dir in MCP / --credentials-dir in AgentSkill) to register another account without replacing the current one. If you want to replace credentials in this directory, first back it up and remember where you copied it, otherwise you may lose access to your old account. Then retry with forced=true (MCP) or --forced (AgentSkill).",
+  "agent_signup_missing_api_key": "Signup did not return an apiKey — this indicates a server bug.",
+  "agent_capability_missing_inbox_signup": "Capability JWT missing inboxId claim after signup.",
+  "agent_jmap_session_missing_urls": "JMAP session did not provide uploadUrl, downloadUrl, or apiUrl.",
+  "agent_internal_missing_session_jwt": "Internal: ensureSession() left sessionJWT unset.",
+  "agent_missing_api_key_or_session": "No API key configured and no valid session on disk. Run register first, set ATOMIC_MAIL_API_KEY, or place credentials.json in the credential directory.",
+  "agent_capability_missing_inbox": "Capability JWT did not contain an inboxId claim.",
+  "agent_jmap_cache_missing": "JMAP session cache missing after refresh.",
+  "credentials_invalid_json_template": "Could not parse credentials JSON at {path}: {details}",
+  "credentials_invalid_shape_template": "Invalid credentials JSON at {path}: expected string fields apiKey, inboxId, authUrl, apiUrl, scryptSalt, uploadUrl, downloadUrl.",
+  "credentials_write_failed_template": "Failed to write credentials at {path}: {details}",
+  "credentials_file_missing_template": "No credentials found in {dir}. Run register first or pass credentials_dir.",
+  "resolve_config_missing_credentials_dir_template": "No credentials found for command \"{command}\" in credentials_dir \"{dir}\". Run register for that directory first.",
+  "readme_missing_template": "README.md was not found in this package install. Tried: {paths}",
+  "jwt_malformed": "Malformed JWT: expected at least 2 dot-separated segments.",
+  "auth_missing_challenge_bearer": "Challenge response missing Authorization bearer token.",
+  "auth_missing_session_bearer": "Session response missing Authorization bearer token.",
+  "auth_missing_capability_bearer": "Capability response missing Authorization bearer token.",
+  "auth_header_not_bearer": "Authorization header must use Bearer scheme.",
+  "auth_challenge_payload_malformed": "Challenge JWT payload is malformed (missing jti or difficulty).",
+  "auth_session_non_json": "auth-service /api/v1/session returned non-JSON body.",
+  "auth_client_signup_missing_api_key": "Signup response missing apiKey.",
+  "jmap_verify_not_json": "JMAP response was not JSON; cannot verify submission.",
+  "jmap_verify_missing_method_responses": "JMAP response JSON missing methodResponses array.",
+  "blob_upload_path_not_readable_template": "Attachment path is not readable: {path}",
+  "blob_upload_missing_blob_id_template": "Upload response missing blobId: {response}",
+  "blob_limits_no_data_sources": "Blob/upload create entry must contain a data array with at least one source.",
+  "blob_limits_invalid_data_source": "Blob/upload data source must contain exactly one of data:asText, data:asBase64, or blobId.",
+  "blob_limits_as_text_not_string": "Blob/upload data:asText must be a string.",
+  "blob_limits_as_base64_not_string": "Blob/upload data:asBase64 must be a string.",
+  "blob_limits_blob_id_invalid": "Blob/upload blobId must be a non-empty string.",
+  "blob_limits_too_large_template": "Blob/upload create key '{key}' exceeds maxSizeBlobSet={max}: estimated {size} bytes.",
+  "blob_limits_too_many_sources_template": "Blob/upload create key '{key}' exceeds maxDataSources={max}: found {count}.",
+  "blob_limits_batch_too_large_template": "Blob/upload envelope exceeds maxSizeBlobSet for account '{accountId}': estimated {size} bytes > {max}.",
+  "send_big_attachment_missing_inbox": "No inbox in session; run register first."
+}

package/shared/messages/hints.json

@@ -0,0 +1,8 @@
+{
+  "jmap_next_hints": [
+    "Use jmap_request with Mailbox/get or Email/query to work with mail data.",
+    "Use presets with $VAR placeholders — $ACCOUNT_ID, $INBOX, and $INBOX_MAILBOX_ID come from the session; pass others via vars / --vars.",
+    "Call help for the JMAP cheatsheet and troubleshooting."
+  ],
+  "post_register_cron_reminder": "After register, arrange hourly inbox polling per help topic cron: native scheduler if available; otherwise ask operator or remind manual fetch. Do not cron jmap_request alone."
+}

package/shared/presets/list_inbox.json

@@ -0,0 +1,46 @@
+{
+  "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": 50
+      },
+      "q0"
+    ],
+    [
+      "Email/get",
+      {
+        "accountId": "$ACCOUNT_ID",
+        "#ids": {
+          "resultOf": "q0",
+          "name": "Email/query",
+          "path": "/ids"
+        },
+        "properties": [
+          "id",
+          "threadId",
+          "receivedAt",
+          "from",
+          "to",
+          "subject",
+          "preview"
+        ]
+      },
+      "g0"
+    ]
+  ]
+}

package/shared/presets/reply.json

@@ -0,0 +1,97 @@
+{
+  "using": [
+    "urn:ietf:params:jmap:core",
+    "urn:ietf:params:jmap:mail",
+    "urn:ietf:params:jmap:submission"
+  ],
+  "methodCalls": [
+    [
+      "Email/get",
+      {
+        "accountId": "$ACCOUNT_ID",
+        "ids": [
+          "$MAIL_ID"
+        ],
+        "properties": [
+          "id",
+          "threadId",
+          "from",
+          "replyTo",
+          "subject",
+          "messageId"
+        ]
+      },
+      "g0"
+    ],
+    [
+      "Email/set",
+      {
+        "accountId": "$ACCOUNT_ID",
+        "create": {
+          "d1": {
+            "mailboxIds": {
+              "$INBOX_MAILBOX_ID": true
+            },
+            "from": [
+              {
+                "email": "$INBOX"
+              }
+            ],
+            "#to": {
+              "resultOf": "g0",
+              "name": "Email/get",
+              "path": "/list/0/replyTo"
+            },
+            "#subject": {
+              "resultOf": "g0",
+              "name": "Email/get",
+              "path": "/list/0/subject"
+            },
+            "#inReplyTo": {
+              "resultOf": "g0",
+              "name": "Email/get",
+              "path": "/list/0/messageId"
+            },
+            "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": {
+                "resultOf": "g0",
+                "name": "Email/get",
+                "path": "/list/0/replyTo"
+              }
+            }
+          }
+        }
+      },
+      "c1"
+    ]
+  ]
+}

package/shared/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/shared/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/shared/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"
+    ]
+  ]
+}