aamp-openclaw-plugin 0.1.27 → 0.1.29

package/package.json

@@ -7,7 +7,7 @@
     "skills"
   ],
   "license": "MIT",
-  "version": "0.1.27",
+  "version": "0.1.29",
   "description": "AAMP Agent Mail Protocol — OpenClaw plugin. Gives OpenClaw an AAMP mailbox identity and lets it receive, process and reply to AAMP tasks.",
   "type": "module",
   "main": "dist/index.js",
@@ -65,7 +65,8 @@
     "build": "node esbuild.config.js",
     "dev": "node esbuild.config.js --watch",
     "prepare": "npm run build",
-    "prepack": "npm run build"
+    "prepack": "npm run build",
+    "test": "vitest run"
   },
   "dependencies": {
     "nodemailer": "^6.9.10",
@@ -74,6 +75,7 @@
   "devDependencies": {
     "@types/node": "^20.11.30",
     "esbuild": "^0.20.2",
-    "typescript": "^5.4.3"
+    "typescript": "^5.4.3",
+    "vitest": "^1.6.1"
   }
 }

package/skills/SKILL.md

@@ -46,12 +46,13 @@ needed.
 
 | Endpoint | Auth | Purpose |
 |---|---|---|
-| `POST /api/nodes/self-register` | None | Create a new agent mailbox (returns one-time code) |
-| `GET /api/nodes/credentials?code=XXX` | None | Exchange one-time code for credentials |
-| `GET /api/inbox` | Basic `jmapToken` | List pending tasks for this agent |
-| `POST /api/send` | Basic `jmapToken` | Send an email (with optional AAMP headers) |
+| `GET /.well-known/aamp` | None | Discover the canonical AAMP API entrypoint |
+| `POST /api/aamp?action=aamp.mailbox.register` | None | Create a new agent mailbox (returns one-time code) |
+| `GET /api/aamp?action=aamp.mailbox.credentials&code=XXX` | None | Exchange one-time code for credentials |
+| `GET /api/aamp?action=aamp.mailbox.inbox` | Basic `mailboxToken` | List pending tasks for this agent |
+| `POST /api/aamp?action=aamp.mailbox.send` | Basic `mailboxToken` | Send an email (with optional AAMP headers) |
 
-**`jmapToken`** = `base64(email:smtpPassword)` — the same credential is used
+**`mailboxToken`** = `base64(email:smtpPassword)` — the same credential is used
 for both the REST endpoints above and for JMAP WebSocket Push (`/jmap/*`).
 
 ---
@@ -65,7 +66,13 @@ exchange the code for credentials.
 ### Step 1a — Self-register
 
 ```
-POST {AAMP_HOST}/api/nodes/self-register
+GET {AAMP_HOST}/.well-known/aamp
+```
+
+The discovery document returns the canonical AAMP API entrypoint (for example `/api/aamp`).
+
+```
+POST {AAMP_HOST}{AAMP_API_URL}?action=aamp.mailbox.register
 Content-Type: application/json
 
 { "slug": "{AAMP_SLUG}", "description": "OpenClaw AAMP agent" }
@@ -79,7 +86,7 @@ Content-Type: application/json
   "description": "OpenClaw AAMP agent",
   "registrationCode": "<64-char hex code>",
   "expiresInSeconds": 300,
-  "credentialsEndpoint": "/api/nodes/credentials"
+  "credentialsAction": "aamp.mailbox.credentials"
 }
 ```
 
@@ -89,14 +96,14 @@ The response does NOT include credentials. Instead it returns a one-time
 ### Step 1b — Exchange code for credentials
 
 ```
-GET {AAMP_HOST}/api/nodes/credentials?code={registrationCode}
+GET {AAMP_HOST}{AAMP_API_URL}?action=aamp.mailbox.credentials&code={registrationCode}
 ```
 
 **Response (200):**
 ```json
 {
   "email": "openclaw-agent-a1b2c3d4@aamp.local",
-  "jmap": { "token": "<base64 jmapToken>" },
+  "mailbox": { "token": "<base64 mailboxToken>" },
   "smtp": { "password": "<smtpPassword>" }
 }
 ```
@@ -112,7 +119,7 @@ mailboxes without conflict (e.g. `openclaw-agent-a1b2c3d4`,
 
 **Important — credential lifecycle:**
 
-1. After exchanging the code, immediately save `email`, `jmap.token`, and
+1. After exchanging the code, immediately save `email`, `mailbox.token`, and
    `smtp.password` to `AAMP_CREDENTIALS_FILE`.
 2. At startup: load the credentials file first. **Only call self-register if
    the file is absent or incomplete** (missing any of the three fields) —
@@ -127,8 +134,8 @@ mailboxes without conflict (e.g. `openclaw-agent-a1b2c3d4`,
 Poll for tasks dispatched to this agent that are waiting for a response.
 
 ```
-GET {AAMP_HOST}/api/inbox
-Authorization: Basic {jmapToken}
+GET {AAMP_HOST}{AAMP_API_URL}?action=aamp.mailbox.inbox
+Authorization: Basic {mailboxToken}
 ```
 
 **Success response:**
@@ -139,8 +146,7 @@ Authorization: Basic {jmapToken}
     "fromAgent": "meego-abc123@aamp.local",
     "title": "Review PR #42",
     "contextLinks": ["https://github.com/org/repo/pull/42"],
-    "timeoutSecs": 3600,
-    "timeoutAt": "2026-03-17T09:00:00.000Z",
+    "expiresAt": "2026-03-17T09:00:00.000Z",
     "dispatchedAt": "2026-03-17T08:00:00.000Z",
     "createdAt": "2026-03-17T08:00:00.000Z"
   }
@@ -156,8 +162,8 @@ An empty array means no pending tasks.
 After completing a task, reply to the dispatcher with a `task.result` email.
 
 ```
-POST {AAMP_HOST}/api/send
-Authorization: Basic {jmapToken}
+POST {AAMP_HOST}{AAMP_API_URL}?action=aamp.mailbox.send
+Authorization: Basic {mailboxToken}
 Content-Type: application/json
 
 {
@@ -167,24 +173,23 @@ Content-Type: application/json
   "aampHeaders": {
     "X-AAMP-Intent":  "task.result",
     "X-AAMP-TaskId":  "<taskId>",
-    "X-AAMP-Status":  "completed",
-    "X-AAMP-Output":  "<structured result, JSON-encoded string or plain text>"
+    "X-AAMP-Status":  "completed"
   }
 }
 ```
 
-Use `"X-AAMP-Status": "rejected"` if the task cannot be completed, and add
-`"X-AAMP-ErrorMsg": "<reason>"`.
+Put the human-readable output or rejection reason in the email body. Keep
+`X-AAMP-StructuredResult` only when you need structured writeback fields.
 
 ---
 
 ## Step 3b — Send Help Request
 
-If the agent is blocked and needs human input, send a `task.help` email instead.
+If the agent is blocked and needs human input, send a `task.help_needed` email instead.
 
 ```
-POST {AAMP_HOST}/api/send
-Authorization: Basic {jmapToken}
+POST {AAMP_HOST}{AAMP_API_URL}?action=aamp.mailbox.send
+Authorization: Basic {mailboxToken}
 Content-Type: application/json
 
 {
@@ -192,17 +197,16 @@ Content-Type: application/json
   "subject": "[AAMP Help] {title}",
   "text": "<human-readable description of the blocker>",
   "aampHeaders": {
-    "X-AAMP-Intent":           "task.help",
+    "X-AAMP-Intent":           "task.help_needed",
     "X-AAMP-TaskId":           "<taskId>",
-    "X-AAMP-Question":         "<specific question for the human>",
-    "X-AAMP-BlockedReason":    "<why the agent is stuck>",
     "X-AAMP-SuggestedOptions": "<option A|option B|option C>"
   }
 }
 ```
 
-`X-AAMP-SuggestedOptions` is pipe-separated. Include 2–4 options when possible
-to make it easy for the human to respond quickly.
+Put the question and blocked reason in the email body. `X-AAMP-SuggestedOptions`
+remains pipe-separated; include 2–4 options when possible to make it easy for
+the human to respond quickly.
 
 ---
 
@@ -210,18 +214,18 @@ to make it easy for the human to respond quickly.
 
 - **401** on any endpoint → credentials invalid. Delete the credentials file
   and call self-register again to get a fresh mailbox.
-- **502** on `/api/send` → SMTP delivery failed. Retry after a short delay.
-- **500** on `/api/nodes/self-register` → management service unavailable.
+- **502** on `aamp.mailbox.send` → SMTP delivery failed. Retry after a short delay.
+- **500** on `aamp.mailbox.register` → management service unavailable.
   Retry with exponential back-off.
 
 ---
 
 ## JMAP WebSocket Push (optional, real-time)
 
-For real-time task delivery instead of polling `/api/inbox`, connect a WebSocket
+For real-time task delivery instead of polling `aamp.mailbox.inbox`, connect a WebSocket
 to `{AAMP_HOST}/jmap` and subscribe to the `EmailDelivery` push channel.
 The management service proxies this connection to the Stalwart mail server.
 
-Use `Authorization: Basic {jmapToken}` when upgrading the WebSocket connection.
+Use `Authorization: Basic {mailboxToken}` when upgrading the WebSocket connection.
 Parse incoming `Email/get` changes and filter for messages with `X-AAMP-Intent`
 header to detect task dispatches without polling.