@agenticmail/openclaw 0.3.1 → 0.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 [OpenClaw](https://github.com/openclaw/openclaw) plugin for [AgenticMail](https://github.com/agenticmail/agenticmail) — gives any OpenClaw agent full email capabilities, inter-agent messaging, task coordination, and outbound security.
 
-This plugin provides 54 tools, a complete email channel integration, automatic sub-agent provisioning, inter-agent message rate limiting, and a built-in follow-up system for blocked emails. It also includes a skill definition with system prompt guidelines that teach agents how to handle email professionally and securely.
+This plugin provides 63 tools, a complete email channel integration, automatic sub-agent provisioning, inter-agent message rate limiting, and a built-in follow-up system for blocked emails. It also includes a skill definition with system prompt guidelines that teach agents how to handle email professionally and securely.
 
 ## Install
 
@@ -108,7 +108,7 @@ Plugin configuration lives in `~/.openclaw/openclaw.json` (user config), not in
 
 ---
 
-## Tools (54 total)
+## Tools (61 total)
 
 ### Core Email (8 tools)
 
@@ -273,6 +273,19 @@ Self-messaging is also prevented — an agent cannot send a message to itself.
 
 ## Skill Definition
 
+### SMS / Phone Number (8 tools)
+
+| Tool | Description |
+|------|-------------|
+| `agenticmail_sms_setup` | Configure Google Voice phone number for SMS access |
+| `agenticmail_sms_send` | Record and send SMS via Google Voice |
+| `agenticmail_sms_messages` | List inbound/outbound SMS messages |
+| `agenticmail_sms_check_code` | Extract verification/OTP codes from recent SMS |
+| `agenticmail_sms_read_voice` | Read SMS directly from Google Voice web (fastest method) |
+| `agenticmail_sms_record` | Record an SMS read from Google Voice web or any source |
+| `agenticmail_sms_parse_email` | Parse SMS from forwarded Google Voice email (fallback) |
+| `agenticmail_sms_config` | Get current SMS configuration |
+
 The plugin includes a skill at `skill/SKILL.md` that gets injected into the agent's system prompt. It covers:
 
 ### Email Rules

package/dist/index.js

@@ -2020,6 +2020,170 @@ ${orig.text || ""}`;
       }
     }
   });
+  reg("agenticmail_sms_setup", {
+    description: "Configure SMS/phone number access via Google Voice. The user must have a Google Voice account with SMS-to-email forwarding enabled. This gives the agent a phone number for receiving verification codes and sending texts.",
+    parameters: {
+      phoneNumber: { type: "string", required: true, description: "Google Voice phone number (e.g. +12125551234)" },
+      forwardingEmail: { type: "string", description: "Email address Google Voice forwards SMS to (defaults to agent email)" }
+    },
+    handler: async (params) => {
+      try {
+        const c = await ctxForParams(ctx, params);
+        return await apiRequest(c, "POST", "/sms/setup", {
+          phoneNumber: params.phoneNumber,
+          forwardingEmail: params.forwardingEmail,
+          provider: "google_voice"
+        });
+      } catch (err) {
+        return { success: false, error: err.message };
+      }
+    }
+  });
+  reg("agenticmail_sms_send", {
+    description: "Send an SMS text message via Google Voice. Records the message and provides instructions for sending via Google Voice web interface. The agent can automate the actual send using the browser tool on voice.google.com.",
+    parameters: {
+      to: { type: "string", required: true, description: "Recipient phone number" },
+      body: { type: "string", required: true, description: "Text message body" }
+    },
+    handler: async (params) => {
+      try {
+        const c = await ctxForParams(ctx, params);
+        return await apiRequest(c, "POST", "/sms/send", {
+          to: params.to,
+          body: params.body
+        });
+      } catch (err) {
+        return { success: false, error: err.message };
+      }
+    }
+  });
+  reg("agenticmail_sms_messages", {
+    description: "List SMS messages (inbound and outbound). Use direction filter to see only received or sent messages.",
+    parameters: {
+      direction: { type: "string", description: 'Filter: "inbound" or "outbound" (default: both)' },
+      limit: { type: "number", description: "Max messages (default: 20)" },
+      offset: { type: "number", description: "Skip messages (default: 0)" }
+    },
+    handler: async (params) => {
+      try {
+        const c = await ctxForParams(ctx, params);
+        const query = new URLSearchParams();
+        if (params.direction) query.set("direction", params.direction);
+        if (params.limit) query.set("limit", String(params.limit));
+        if (params.offset) query.set("offset", String(params.offset));
+        return await apiRequest(c, "GET", `/sms/messages?${query.toString()}`);
+      } catch (err) {
+        return { success: false, error: err.message };
+      }
+    }
+  });
+  reg("agenticmail_sms_check_code", {
+    description: `Check for recent verification/OTP codes received via SMS. Scans inbound SMS for common code patterns (6-digit, 4-digit, alphanumeric). Use this after requesting a verification code during sign-up flows.
+
+RECOMMENDED FLOW for reading verification codes:
+1. FIRST (fastest): Open Google Voice directly in the browser:
+   - Navigate to https://voice.google.com/u/0/messages
+   - Take a screenshot or snapshot to read the latest messages
+   - The code will be visible in the message list (no click needed for recent ones)
+   - Use agenticmail_sms_record to save the SMS and extract the code
+
+2. FALLBACK: If browser is unavailable, this tool checks the SMS database
+   (populated by email forwarding from Google Voice, which can be delayed 1-5 minutes)`,
+    parameters: {
+      minutes: { type: "number", description: "How many minutes back to check (default: 10)" }
+    },
+    handler: async (params) => {
+      try {
+        const c = await ctxForParams(ctx, params);
+        const query = params.minutes ? `?minutes=${params.minutes}` : "";
+        return await apiRequest(c, "GET", `/sms/verification-code${query}`);
+      } catch (err) {
+        return { success: false, error: err.message };
+      }
+    }
+  });
+  reg("agenticmail_sms_read_voice", {
+    description: `Read SMS messages directly from Google Voice web interface (FASTEST method). Opens voice.google.com in the browser, reads recent messages, and returns any found SMS with verification codes extracted. This is the PRIMARY way to check for SMS - much faster than waiting for email forwarding.
+
+Use this when:
+- Waiting for a verification code after signing up for a service
+- Checking for recent SMS messages
+- Email forwarding hasn't delivered the SMS yet
+
+The agent must have browser access and a Google Voice session (logged into Google in the browser profile).`,
+    parameters: {},
+    handler: async (params) => {
+      try {
+        const c = await ctxForParams(ctx, params);
+        const configResp = await apiRequest(c, "GET", "/sms/config");
+        const phoneNumber = configResp?.sms?.phoneNumber || "unknown";
+        return {
+          method: "google_voice_web",
+          phoneNumber,
+          instructions: [
+            "Open the browser to: https://voice.google.com/u/0/messages",
+            "Take a screenshot to see the message list",
+            "Recent SMS messages appear in the left sidebar with sender number and preview text",
+            "For verification codes, the code is usually visible in the preview without clicking",
+            "If you need the full message, click on the conversation",
+            "After reading, use agenticmail_sms_record to save the SMS to the database"
+          ],
+          browserUrl: "https://voice.google.com/u/0/messages",
+          tip: "This is much faster than email forwarding. Google Voice web shows messages instantly."
+        };
+      } catch (err) {
+        return { success: false, error: err.message };
+      }
+    }
+  });
+  reg("agenticmail_sms_record", {
+    description: "Record an SMS message that you read from Google Voice web or any other source. Saves it to the SMS database and extracts any verification codes. Use after reading a message from voice.google.com in the browser.",
+    parameters: {
+      from: { type: "string", required: true, description: "Sender phone number (e.g. +12065551234 or (206) 338-7285)" },
+      body: { type: "string", required: true, description: "The SMS message text" }
+    },
+    handler: async (params) => {
+      try {
+        const c = await ctxForParams(ctx, params);
+        return await apiRequest(c, "POST", "/sms/record", {
+          from: params.from,
+          body: params.body
+        });
+      } catch (err) {
+        return { success: false, error: err.message };
+      }
+    }
+  });
+  reg("agenticmail_sms_parse_email", {
+    description: "Parse an SMS from a forwarded Google Voice email. Use this when you receive an email from Google Voice containing an SMS. Extracts the sender number, message body, and any verification codes.",
+    parameters: {
+      emailBody: { type: "string", required: true, description: "The email body text to parse" },
+      emailFrom: { type: "string", description: "The email sender address" }
+    },
+    handler: async (params) => {
+      try {
+        const c = await ctxForParams(ctx, params);
+        return await apiRequest(c, "POST", "/sms/parse-email", {
+          emailBody: params.emailBody,
+          emailFrom: params.emailFrom
+        });
+      } catch (err) {
+        return { success: false, error: err.message };
+      }
+    }
+  });
+  reg("agenticmail_sms_config", {
+    description: "Get the current SMS/phone number configuration for this agent. Shows whether SMS is enabled, the phone number, and forwarding email.",
+    parameters: {},
+    handler: async (params) => {
+      try {
+        const c = await ctxForParams(ctx, params);
+        return await apiRequest(c, "GET", "/sms/config");
+      } catch (err) {
+        return { success: false, error: err.message };
+      }
+    }
+  });
 }
 
 // src/channel.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/openclaw",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "OpenClaw plugin and skill for AgenticMail",
   "type": "module",
   "main": "dist/index.js",
@@ -14,6 +14,7 @@
   "files": [
     "dist",
     "openclaw.plugin.json",
+    "scripts",
     "skill",
     "README.md",
     "REFERENCE.md",
@@ -26,7 +27,8 @@
   },
   "scripts": {
     "build": "tsup index.ts --format esm --dts --clean",
-    "test": "vitest run",
+    "test": "vitest run --passWithNoTests",
+    "preuninstall": "node scripts/uninstall.mjs",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {},

package/scripts/uninstall.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+/**
+ * Cleanup script that runs on `npm uninstall @agenticmail/openclaw`.
+ * Removes the agenticmail plugin entry from ~/.openclaw/openclaw.json
+ * and cleans up the plugin load path so OpenClaw doesn't error on
+ * a missing plugin.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const configPath = join(homedir(), '.openclaw', 'openclaw.json');
+
+if (!existsSync(configPath)) process.exit(0);
+
+try {
+  const raw = readFileSync(configPath, 'utf-8');
+  const config = JSON.parse(raw);
+
+  let changed = false;
+
+  // Remove plugins.entries.agenticmail
+  if (config.plugins?.entries?.agenticmail) {
+    delete config.plugins.entries.agenticmail;
+    changed = true;
+
+    // Clean up empty entries object
+    if (Object.keys(config.plugins.entries).length === 0) {
+      delete config.plugins.entries;
+    }
+  }
+
+  // Remove our path from plugins.load.paths
+  if (Array.isArray(config.plugins?.load?.paths)) {
+    const before = config.plugins.load.paths.length;
+    config.plugins.load.paths = config.plugins.load.paths.filter(
+      (p) => !p.includes('@agenticmail/openclaw')
+    );
+    if (config.plugins.load.paths.length !== before) changed = true;
+
+    // Clean up empty paths array
+    if (config.plugins.load.paths.length === 0) {
+      delete config.plugins.load.paths;
+      if (Object.keys(config.plugins.load).length === 0) {
+        delete config.plugins.load;
+      }
+    }
+  }
+
+  if (changed) {
+    writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n');
+    console.log('[agenticmail] Cleaned up OpenClaw config:', configPath);
+  }
+} catch {
+  // Don't fail the uninstall if cleanup fails
+}