openclaw-agentmail-listener 0.4.1 → 0.4.3

package/README.md

@@ -5,52 +5,27 @@ An [OpenClaw](https://openclaw.ai) plugin that listens for incoming emails via [
 ## What it does
 
 - Registers a background service at gateway startup
-- Connects to AgentMail via WebSocket
+- Connects to AgentMail via raw WebSocket (`wss://ws.agentmail.to/v0`)
 - Subscribes to a configured inbox (e.g. `nickbot@agentmail.to`)
-- When a `message.received` event fires, injects a system event via `core.system.enqueueSystemEvent()` with email metadata (from, subject, preview)
+- When a `message.received` event fires, injects a system event with email metadata (from, subject, preview)
+- Wakes the agent immediately via `requestHeartbeatNow()` so emails are processed right away
 - Auto-reconnects with exponential backoff on disconnect
+- Keepalive pings every 30 seconds
 - Stops cleanly when the gateway shuts down
 
 This is **not** a channel plugin — it doesn't handle replies. It just triggers system events so the agent notices new emails and can decide what to do (e.g. read the full message via the AgentMail skill and reply).
 
 ## Installation
 
-### Option 1: Install from npm (recommended)
-
 ```bash
 openclaw plugins install openclaw-agentmail-listener
 ```
 
 Restart the gateway afterwards.
 
-### Option 2: Install from GitHub
-
-```bash
-git clone https://github.com/thisnick/openclaw-agentmail ~/.openclaw/extensions/agentmail-listener
-cd ~/.openclaw/extensions/agentmail-listener
-npm install
-openclaw gateway restart
-```
-
-### Option 3: Load via config path
-
-In your OpenClaw config (`~/.openclaw/openclaw.json`):
-
-```json
-{
-  "plugins": {
-    "load": {
-      "paths": ["/path/to/openclaw-agentmail"]
-    }
-  }
-}
-```
-
-Then run `npm install` in the plugin directory and restart the gateway.
-
 ## Configuration
 
-Add to your OpenClaw config under `plugins.entries.agentmail-listener.config`:
+Add to your OpenClaw config under `plugins.entries`:
 
 ```json
 {
@@ -60,9 +35,7 @@ Add to your OpenClaw config under `plugins.entries.agentmail-listener.config`:
         "enabled": true,
         "config": {
           "apiKey": "am_us_your_key_here",
-          "inboxId": "yourbot@agentmail.to",
-          "eventTypes": ["message.received"],
-          "sessionKey": "agent:main:main"
+          "inboxId": "yourbot@agentmail.to"
         }
       }
     }
@@ -78,7 +51,6 @@ Add to your OpenClaw config under `plugins.entries.agentmail-listener.config`:
 | `inboxId` | string | ✅ | — | Inbox to subscribe (e.g. `nickbot@agentmail.to`) |
 | `eventTypes` | string[] | — | `["message.received"]` | Event types to subscribe to |
 | `sessionKey` | string | — | `"agent:main:main"` | Agent session key for routing system events |
-| `wake` | string | — | `"tools-invoke"` | Wake method: `"tools-invoke"` (default), `"hooks"`, or `"off"` |
 
 ## System event format
 
@@ -91,33 +63,49 @@ Subject: Hello there
 Preview: This is the first 200 chars of the email body...
 ```
 
-The event is keyed with `contextKey: agentmail:<messageId>` to deduplicate repeated events for the same message.
+The event is keyed with `contextKey: cron:agentmail:<messageId>` so it is both deduplicated and surfaced in the heartbeat prompt (see [How wake works](#how-wake-works) for details).
+
+## How wake works
+
+After enqueuing a system event, the plugin calls `requestHeartbeatNow()` with reason `"exec-event"`. This does two things:
 
-## Instant wake
+1. **Bypasses file gates** — the heartbeat fires immediately without requiring HEARTBEAT.md
+2. **Inspects pending events** — the enqueued system event is included in the heartbeat prompt
 
-By default, system events are only processed when the agent's heartbeat fires (which can be up to 1 hour). This plugin triggers an **immediate wake** after enqueuing each email event by calling the gateway's cron wake endpoint (`POST /tools/invoke`).
+The `cron:` prefix on the contextKey ensures the event passes through OpenClaw's `hasTaggedCronEvents` check, which enables event inspection and renders the email content via `buildCronEventPrompt`. Without this prefix, the event would be enqueued but silently discarded from the prompt.
 
-### Wake methods
+> **Why not `reason: "wake"`?** The `"wake"` reason bypasses file gates but does _not_ enable `shouldInspectPendingEvents` in the heartbeat runner, so system events are ignored. `"exec-event"` enables both.
 
-| Method | Auth | When to use |
-|--------|------|-------------|
-| `tools-invoke` (default) | `gateway.auth.token` | Works out of the box, no extra config |
-| `hooks` | `hooks.token` | If you already have hooks enabled |
-| `off` | — | Disable wake; rely on heartbeat polling |
+**Important config for proactive delivery:**
+
+The heartbeat `target` must be set to a channel (e.g. `"whatsapp"`, `"telegram"`) or `"last"` — otherwise the agent processes the email but the response is silently dropped (default target is `"none"`).
+
+```json
+{
+  "agents": {
+    "defaults": {
+      "heartbeat": {
+        "every": "1h",
+        "target": "whatsapp"
+      }
+    }
+  }
+}
+```
 
-The plugin reads port and token from your OpenClaw config automatically.
+**Note:** The `requests-in-flight` check is global — if any conversation is active on any channel, the wake is deferred (retries every 1s until the queue clears).
 
-## Architecture notes
+## Architecture
 
-- The plugin uses the `agentmail` npm package's WebSocket client
-- Reconnection uses exponential backoff (1s → 2s → 4s → ... → 60s max) with ±10% jitter
-- Re-subscription happens automatically on each reconnect (WebSocket `open` event)
-- Uses `api.runtime.system.enqueueSystemEvent()` to route events to the agent session
-- After enqueuing, triggers an immediate agent wake via the gateway's `/tools/invoke` endpoint (cron wake action) so the agent processes the email right away instead of waiting for the next heartbeat poll
+- **Raw WebSocket** — connects directly to `wss://ws.agentmail.to/v0` with API key as query param (no SDK dependency for the WebSocket layer)
+- **Reconnection** — exponential backoff (1s → 2s → 4s → ... → 60s max) with ±10% jitter
+- **Keepalive** — sends WebSocket pings every 30 seconds
+- **In-process wake** — uses `api.runtime.system.requestHeartbeatNow()` with `reason: "exec-event"` (no HTTP round-trips)
+- **System events** — uses `api.runtime.system.enqueueSystemEvent()` with `cron:`-prefixed contextKey to ensure prompt visibility
 
 ## Dependencies
 
-- `agentmail` ^0.2.17 — AgentMail TypeScript SDK
+- `ws` ^8.18.0 — WebSocket client for Node.js
 
 ## License
 

package/dist/index.js

@@ -192,10 +192,10 @@ function handleEventInner(api, cfg, event) {
       const sessionKey = cfg.sessionKey ?? "agent:main:main";
       api.runtime.system.enqueueSystemEvent(eventText, {
         sessionKey,
-        contextKey: `agentmail:${messageId}`
+        contextKey: `cron:agentmail:${messageId}`
       });
       api.runtime.system.requestHeartbeatNow({
-        reason: "agentmail: new email",
+        reason: "exec-event",
         sessionKey
       });
       api.logger.info("agentmail-listener: heartbeat wake requested");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-agentmail-listener",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "type": "module",
   "description": "OpenClaw plugin: AgentMail listener — injects system events when emails arrive",
   "files": [