openclaw-agentmail-listener 0.2.1 → 0.3.0

package/README.md

@@ -78,6 +78,7 @@ 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
 
@@ -92,12 +93,27 @@ 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.
 
+## Instant wake
+
+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`).
+
+### Wake methods
+
+| 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 |
+
+The plugin reads port and token from your OpenClaw config automatically.
+
 ## Architecture notes
 
 - 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
 
 ## Dependencies
 

package/dist/index.js

@@ -13027,11 +13027,13 @@ function register(api) {
         api.logger.warn("agentmail-listener: no inboxId configured \u2014 service not starting");
         return;
       }
+      const wakeMode = cfg.wake === "hooks" || cfg.wake === "off" ? cfg.wake : "tools-invoke";
       const pluginCfg = {
         apiKey: cfg.apiKey,
         inboxId: cfg.inboxId,
         eventTypes: cfg.eventTypes ?? ["message.received"],
-        sessionKey: cfg.sessionKey ?? "agent:main:main"
+        sessionKey: cfg.sessionKey ?? "agent:main:main",
+        wake: wakeMode
       };
       startListener(api, pluginCfg);
     },
@@ -13152,6 +13154,10 @@ function handleEvent(api, cfg, event) {
         sessionKey: cfg.sessionKey ?? "agent:main:main",
         contextKey: `agentmail:${messageId}`
       });
+      const wakeText = "You have a new agentmail email. Check the pending system event for details.";
+      wakeAgent(api, cfg.wake ?? "tools-invoke", wakeText).catch((err) => {
+        api.logger.warn(`agentmail-listener: wake failed (event still queued): ${String(err)}`);
+      });
     } catch (err) {
       api.logger.error(`agentmail-listener: failed to enqueue system event: ${String(err)}`);
     }
@@ -13164,6 +13170,60 @@ function handleEvent(api, cfg, event) {
     );
   }
 }
+async function wakeAgent(api, mode, wakeText) {
+  if (mode === "off") return;
+  const cfg = api.runtime.config.loadConfig();
+  const port = cfg.gateway?.port ?? 18789;
+  if (mode === "hooks") {
+    const hooksToken = cfg.hooks?.token;
+    if (!hooksToken) {
+      api.logger.warn("agentmail-listener: wake=hooks but no hooks.token configured");
+      return;
+    }
+    const hooksPath = (cfg.hooks?.path ?? "/hooks").replace(/\/+$/, "");
+    const url2 = `http://127.0.0.1:${port}${hooksPath}/wake`;
+    const res2 = await fetch(url2, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${hooksToken}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ text: wakeText, mode: "now" })
+    });
+    if (!res2.ok) {
+      const body = await res2.text().catch(() => "");
+      throw new Error(`hooks/wake returned ${res2.status}: ${body}`);
+    }
+    api.logger.info("agentmail-listener: agent wake triggered via hooks");
+    return;
+  }
+  const gatewayToken = cfg.gateway?.auth?.token;
+  if (!gatewayToken) {
+    api.logger.warn("agentmail-listener: wake=tools-invoke but no gateway.auth.token configured");
+    return;
+  }
+  const url = `http://127.0.0.1:${port}/tools/invoke`;
+  const res = await fetch(url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${gatewayToken}`,
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({
+      tool: "cron",
+      args: {
+        action: "wake",
+        text: wakeText,
+        mode: "now"
+      }
+    })
+  });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`tools/invoke cron wake returned ${res.status}: ${body}`);
+  }
+  api.logger.info("agentmail-listener: agent wake triggered via tools/invoke");
+}
 var MIN_DELAY_MS = 1e3;
 var MAX_DELAY_MS = 6e4;
 var BACKOFF_FACTOR = 2;

package/openclaw.plugin.json

@@ -37,8 +37,14 @@
       },
       "sessionKey": {
         "type": "string",
-        "description": "Agent session key to deliver system events to. Defaults to \"main\" (the primary agent session).",
-        "default": "main"
+        "description": "Agent session key to deliver system events to. Defaults to \"agent:main:main\".",
+        "default": "agent:main:main"
+      },
+      "wake": {
+        "type": "string",
+        "enum": ["tools-invoke", "hooks", "off"],
+        "description": "How to wake the agent on new email. \"tools-invoke\" (default) uses gateway auth, \"hooks\" uses hooks.token, \"off\" disables wake.",
+        "default": "tools-invoke"
       }
     }
   },
@@ -58,7 +64,11 @@
     },
     "sessionKey": {
       "label": "Agent Session Key",
-      "placeholder": "main"
+      "placeholder": "agent:main:main"
+    },
+    "wake": {
+      "label": "Wake Method",
+      "placeholder": "tools-invoke"
     }
   }
 }

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "openclaw-agentmail-listener",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
-  "description": "OpenClaw plugin: AgentMail listener \u2014 injects system events when emails arrive",
+  "description": "OpenClaw plugin: AgentMail listener — injects system events when emails arrive",
   "files": [
     "dist",
     "openclaw.plugin.json",