@textopenclaw/textclaw 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TextClaw
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,77 @@
+# @textopenclaw/textclaw
+
+iMessage channel plugin for [OpenClaw](https://github.com/openclaw/openclaw) via [TextClaw](https://textclaw.now) relay. No Mac required.
+
+```
+Your OpenClaw --> TextClaw Relay API --> iMessage
+```
+
+## Quick Start
+
+1. **Get an API key** from [textclaw.now](https://textclaw.now) (sign up, then grab your BYOC key from the dashboard)
+2. **Install the plugin:**
+   ```bash
+   openclaw plugins install @textopenclaw/textclaw
+   ```
+3. **Add to your channel config:**
+   ```json
+   {
+     "textclaw": {
+       "enabled": true,
+       "textclawUrl": "https://textclaw.now",
+       "apiKey": "YOUR_API_KEY"
+     }
+   }
+   ```
+4. **Done.** Messages arrive via WebSocket automatically. No public URL needed.
+
+## Configuration
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| `enabled` | No | Enable/disable the channel (default: `false`) |
+| `textclawUrl` | Yes | TextClaw API base URL |
+| `apiKey` | Yes | Your BYOC API key from TextClaw |
+| `dmPolicy` | No | `"open"`, `"allowlist"`, `"pairing"`, or `"disabled"` (default: `"open"`) |
+| `allowFrom` | No | Phone numbers allowed to DM when using `"allowlist"` policy |
+
+## Features
+
+- Send and receive iMessages (text + media)
+- Typing indicators
+- Tapback reactions: heart, thumbsup, thumbsdown, laugh, emphasize, question
+- Message chunking for long texts (4000 char limit per message)
+- WebSocket connection for real-time inbound message delivery
+
+## How It Works
+
+1. **Outbound**: OpenClaw calls the TextClaw relay API, which forwards the message to iMessage.
+2. **Inbound**: TextClaw receives inbound message webhooks, matches them to your account, and pushes messages to your OpenClaw instance via WebSocket (with HTTP fallback if you provide an `openclaw_url` during registration).
+
+## Setup for AI Agents
+
+If you're an OpenClaw instance configuring iMessage support, here's everything you need:
+
+**You were given a TextClaw API key** (64-character hex string from textclaw.now).
+
+Install the plugin:
+```bash
+openclaw plugins install @textopenclaw/textclaw
+```
+
+Add this to your channel config:
+```json
+{
+  "textclaw": {
+    "enabled": true,
+    "textclawUrl": "https://textclaw.now",
+    "apiKey": "YOUR_API_KEY"
+  }
+}
+```
+
+That's it. The plugin connects to TextClaw via WebSocket automatically. No public URL, no port forwarding, no extra setup. Messages flow through TextClaw's relay to iMessage and back.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,119 @@
+import channelPlugin from "./src/channel.js";
+import { processInboundWebhook } from "./src/monitor.js";
+import { startWebSocket, stopWebSocket } from "./src/ws.js";
+import { setPluginApi } from "./src/runtime.js";
+import { sendReactionToPeer, sendVoiceNoteToPeer } from "./src/send.js";
+import * as api from "./src/api.js";
+
+let registered = false;
+
+const plugin = {
+  id: "textclaw",
+  name: "TextClaw iMessage",
+  description: "iMessage channel via TextClaw relay — no Mac required",
+
+  register(pluginApi) {
+    // Always update pluginApi and API config (called in both CLI and gateway)
+    setPluginApi(pluginApi);
+    const account = pluginApi.pluginConfig;
+    api.configure(account.textclawUrl, account.apiKey);
+
+    // Only register channel/routes/tools once
+    if (registered) return;
+    registered = true;
+
+    // Register the channel
+    pluginApi.registerChannel({ plugin: channelPlugin });
+
+    // Start WebSocket for inbound messages
+    const wsBase = account.textclawUrl
+      .replace(/^http:/, "ws:")
+      .replace(/^https:/, "wss:")
+      .replace(/\/+$/, "");
+    const wsUrl = `${wsBase}/ws/byoc/inbound/?api_key=${account.apiKey}`;
+    startWebSocket(wsUrl);
+
+    // Inbound webhook route (HTTP fallback)
+    pluginApi.registerHttpRoute({
+      path: "/ext/textclaw/inbound",
+      auth: "plugin",
+      handler: async (req, res) => {
+        try {
+          await processInboundWebhook(req.body);
+          res.statusCode = 200;
+          res.end(JSON.stringify({ ok: true }));
+        } catch (err) {
+          console.error("[textclaw] webhook error:", err);
+          res.statusCode = 500;
+          res.end(JSON.stringify({ error: err.message }));
+        }
+        return true;
+      },
+    });
+
+    // Status check route
+    pluginApi.registerHttpRoute({
+      path: "/ext/textclaw/status",
+      auth: "plugin",
+      handler: async (req, res) => {
+        const configuredKey = api.getApiKey();
+        const checkKey = req.headers["x-api-key"] || "";
+        res.statusCode = 200;
+        res.end(JSON.stringify({
+          installed: true,
+          version: "0.6.0",
+          keyMatch: !!(checkKey && checkKey === configuredKey),
+        }));
+        return true;
+      },
+    });
+
+    // Register message tools so the agent can react and send voice notes
+    pluginApi.registerTool({
+      name: "react_imessage",
+      description: "React to an iMessage with a tapback. Available reactions: heart, thumbsup, thumbsdown, laugh, emphasize, question. To react to a specific message, pass its message_handle (the MessageSid from the message metadata). Omit to react to the last inbound message.",
+      parameters: {
+        type: "object",
+        properties: {
+          reaction: {
+            type: "string",
+            enum: ["heart", "thumbsup", "thumbsdown", "laugh", "emphasize", "question"],
+          },
+          message_handle: {
+            type: "string",
+            description: "Apple message GUID to react to (from MessageSid in message metadata). Omit to react to the last inbound message.",
+          },
+        },
+        required: ["reaction"],
+      },
+      async execute({ reaction, message_handle }, { target }) {
+        const peer = target?.peer || target;
+        await sendReactionToPeer(account, peer, reaction, message_handle || null);
+        return { success: true };
+      },
+    });
+
+    pluginApi.registerTool({
+      name: "send_voice_note",
+      description: "Send a voice note to the user via iMessage. Provide a URL to an audio file (mp3, wav, ogg, m4a).",
+      parameters: {
+        type: "object",
+        properties: {
+          media_url: { type: "string", description: "URL to the audio file" },
+        },
+        required: ["media_url"],
+      },
+      async execute({ media_url }, { target }) {
+        const peer = target?.peer || target;
+        const result = await sendVoiceNoteToPeer(account, peer, media_url);
+        return { success: true, messageId: result.messageId };
+      },
+    });
+
+    pluginApi.onShutdown?.(() => stopWebSocket());
+
+    console.log(`[textclaw] channel started — relay via ${account.textclawUrl}`);
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,35 @@
+{
+  "id": "textclaw",
+  "name": "TextClaw",
+  "description": "iMessage relay channel via outbound WebSocket",
+  "channels": ["imessage"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "textclawUrl": {
+        "type": "string",
+        "description": "TextClaw API base URL"
+      },
+      "apiKey": {
+        "type": "string",
+        "description": "Your BYOC API key from TextClaw"
+      },
+      "dmPolicy": {
+        "type": "string",
+        "enum": ["open", "allowlist", "pairing", "disabled"],
+        "default": "open"
+      },
+      "allowFrom": {
+        "type": "array",
+        "items": { "type": "string" },
+        "default": []
+      }
+    },
+    "required": ["textclawUrl", "apiKey"]
+  },
+  "uiHints": {
+    "apiKey": { "label": "API Key", "sensitive": true },
+    "textclawUrl": { "label": "TextClaw Server URL", "placeholder": "https://textclaw.now" }
+  }
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@textopenclaw/textclaw",
+  "version": "1.0.0",
+  "description": "iMessage channel plugin for OpenClaw via TextClaw relay. No Mac required.",
+  "type": "module",
+  "main": "index.js",
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "imessage",
+    "textclaw",
+    "channel",
+    "byoc"
+  ],
+  "author": "TextClaw",
+  "license": "MIT",
+  "homepage": "https://textclaw.now",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vladartym/openclaw-textclaw.git"
+  },
+  "files": [
+    "index.js",
+    "src/",
+    "skills/",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "openclaw": ">=1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "openclaw": {
+    "extensions": ["./index.js"],
+    "channel": {
+      "id": "imessage",
+      "label": "TextClaw (iMessage)",
+      "docsPath": "/channels/textclaw",
+      "blurb": "iMessage relay via TextClaw WebSocket bridge."
+    }
+  }
+}

package/skills/textclaw/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: textclaw
+description: "iMessage ops via TextClaw relay — reactions, sending, typing, voice notes."
+metadata:
+  openclaw:
+    emoji: "\U0001F4AC"
+    requires:
+      config:
+        - plugins.entries.textclaw.config.apiKey
+        - plugins.entries.textclaw.config.textclawUrl
+allowed-tools:
+  - exec
+  - message
+---
+
+# TextClaw iMessage
+
+iMessage channel via TextClaw relay. No Mac required.
+
+## Musts
+
+- Sending messages: use the `message` tool normally (no `channel` param needed).
+- Reactions: use `exec` with curl to the TextClaw relay API. Do NOT use `message(action="react")` — it does not work on this channel.
+- The relay URL and API key are in your config at `plugins.entries.textclaw.config.textclawUrl` and `plugins.entries.textclaw.config.apiKey`.
+
+## Reactions
+
+Use `exec` to curl the TextClaw relay API:
+
+```bash
+curl -s -X POST "<TEXTCLAW_URL>/api/v1/byoc/relay/reaction/" \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: <API_KEY>" \
+  -d '{"message_handle": "<MESSAGE_ID>", "reaction": "<REACTION>"}'
+```
+
+- `TEXTCLAW_URL`: from config `plugins.entries.textclaw.config.textclawUrl`
+- `API_KEY`: from config `plugins.entries.textclaw.config.apiKey`
+- `MESSAGE_ID`: the `message_id` from the inbound message metadata (this is the Apple GUID). You MUST use the real GUID — do not pass "last" or any placeholder.
+- `REACTION`: one of `heart`, `thumbsup`, `thumbsdown`, `laugh`, `emphasize`, `question`
+
+Response `{"ok": true}` means success. `{"ok": false}` means the reaction failed (wrong handle or SendBlue error).
+
+**Emoji mapping:**
+
+- heart / love / ❤️ → `heart`
+- like / thumbs up / 👍 → `thumbsup`
+- dislike / thumbs down / 👎 → `thumbsdown`
+- haha / laugh / 😂 → `laugh`
+- emphasize / ‼️ → `emphasize`
+- question / ❓ → `question`
+
+## Sending Messages
+
+Use the `message` tool normally:
+
+```json
+{ "action": "send", "text": "Hello!" }
+```
+
+With media:
+
+```json
+{ "action": "send", "text": "Check this out", "mediaUrl": "https://example.com/photo.jpg" }
+```
+
+## Voice Notes
+
+Send audio as an iMessage voice note (plays inline):
+
+```json
+{ "action": "send", "text": "", "mediaUrl": "https://example.com/audio.mp3" }
+```
+
+## Writing Style
+
+- Short, conversational, natural tone — this is iMessage, not email.
+- Break long responses into multiple messages if needed.
+- Use tapback reactions to acknowledge messages when a full reply isn't needed.

package/src/api.js

@@ -0,0 +1,140 @@
+/**
+ * HTTP client for TextClaw relay API.
+ *
+ * BYOC users route outbound messages through TextClaw's relay endpoints
+ * which handle iMessage delivery on their behalf.
+ */
+
+import { readFileSync } from "fs";
+import { basename } from "path";
+
+let baseUrl = "";  // e.g. "https://textclaw.now/api/v1/byoc/relay"
+let apiKey = "";
+
+export function configure(url, key) {
+  baseUrl = url.replace(/\/+$/, "") + "/api/v1/byoc/relay";
+  apiKey = key;
+}
+
+export function getApiKey() {
+  return apiKey;
+}
+
+async function request(method, path, body = null) {
+  const url = `${baseUrl}${path}`;
+  const headers = {
+    "X-API-Key": apiKey,
+    "Content-Type": "application/json",
+  };
+
+  const options = { method, headers };
+  if (body) {
+    options.body = JSON.stringify(body);
+  }
+
+  const resp = await fetch(url, options);
+
+  if (!resp.ok) {
+    const text = await resp.text();
+    throw new Error(`TextClaw ${method} ${path} failed (${resp.status}): ${text}`);
+  }
+
+  return resp.json();
+}
+
+/**
+ * Send a message via TextClaw relay → iMessage.
+ * @param {string} _fromNumber - Ignored (TextClaw uses the shared BYOC number)
+ * @param {string} toNumber - Recipient phone number (E.164)
+ * @param {string} content - Message text
+ * @param {string} [mediaUrl] - Optional media URL
+ * @returns {Promise<object>}
+ */
+export async function sendMessage(_fromNumber, toNumber, content, mediaUrl = null) {
+  const body = { to_number: toNumber, content };
+  if (mediaUrl) {
+    body.media_url = mediaUrl;
+  }
+  return request("POST", "/send/", body);
+}
+
+/**
+ * Upload a local file to the TextClaw server.
+ * @param {string} filePath - Local file path
+ * @returns {Promise<{ url: string }>} Public URL of the uploaded file
+ */
+export async function uploadFile(filePath) {
+  const url = `${baseUrl}/upload/`;
+  const fileData = readFileSync(filePath);
+  const fileName = basename(filePath);
+
+  const form = new FormData();
+  form.append("file", new Blob([fileData]), fileName);
+
+  const resp = await fetch(url, {
+    method: "POST",
+    headers: { "X-API-Key": apiKey },
+    body: form,
+  });
+
+  if (!resp.ok) {
+    const text = await resp.text();
+    throw new Error(`TextClaw upload failed (${resp.status}): ${text}`);
+  }
+
+  return resp.json();
+}
+
+/**
+ * Send a voice note via TextClaw relay → iMessage.
+ * The server converts the audio to .caf format for inline iMessage playback.
+ * If mediaUrl is a local file path, uploads it first.
+ * @param {string} _fromNumber - Ignored
+ * @param {string} toNumber - Recipient phone number (E.164)
+ * @param {string} mediaUrl - URL or local path to an audio file
+ * @returns {Promise<object>}
+ */
+export async function sendVoiceNote(_fromNumber, toNumber, mediaUrl) {
+  // Local file path → upload to server first
+  if (mediaUrl && !mediaUrl.startsWith("http")) {
+    const uploaded = await uploadFile(mediaUrl);
+    mediaUrl = uploaded.url;
+  }
+
+  return request("POST", "/send/", {
+    to_number: toNumber,
+    content: "",
+    media_url: mediaUrl,
+    convert_to_voice_note: true,
+  });
+}
+
+/**
+ * Send typing indicator via TextClaw relay.
+ * @param {string} _fromNumber - Ignored
+ * @param {string} toNumber - Recipient phone number (E.164)
+ */
+export async function sendTypingIndicator(_fromNumber, toNumber) {
+  return request("POST", "/typing/", { to_number: toNumber });
+}
+
+/**
+ * Send a reaction (tapback) via TextClaw relay.
+ * @param {string} _fromNumber - Ignored
+ * @param {string} messageHandle - Apple GUID of the message to react to
+ * @param {"heart"|"thumbsup"|"thumbsdown"|"laugh"|"emphasize"|"question"} reaction
+ */
+export async function sendReaction(_fromNumber, messageHandle, reaction) {
+  return request("POST", "/reaction/", {
+    message_handle: messageHandle,
+    reaction,
+  });
+}
+
+/**
+ * Mark a conversation as read via TextClaw relay.
+ * @param {string} toNumber - The phone number whose messages to mark as read
+ */
+export async function markRead(toNumber) {
+  return request("POST", "/mark-read/", { to_number: toNumber });
+}

package/src/channel.js

@@ -0,0 +1,173 @@
+import * as api from "./api.js";
+import { sendMessageToPeer, sendTyping, sendReactionToPeer, sendVoiceNoteToPeer, chunkText } from "./send.js";
+import { getLastInboundHandle } from "./handle-store.js";
+
+/**
+ * Map emoji and text aliases to iMessage tapback types.
+ */
+const EMOJI_TO_TAPBACK = {
+  // Emoji variants
+  "\u2764\uFE0F": "heart", "\u2665\uFE0F": "heart", "\u2764": "heart",
+  "\uD83D\uDC4D": "thumbsup", "\uD83D\uDC4D\uD83C\uDFFB": "thumbsup",
+  "\uD83D\uDC4D\uD83C\uDFFC": "thumbsup", "\uD83D\uDC4D\uD83C\uDFFD": "thumbsup",
+  "\uD83D\uDC4E": "thumbsdown", "\uD83D\uDC4E\uD83C\uDFFB": "thumbsdown",
+  "\uD83D\uDC4E\uD83C\uDFFC": "thumbsdown", "\uD83D\uDC4E\uD83C\uDFFD": "thumbsdown",
+  "\uD83D\uDE02": "laugh", "\uD83E\uDD23": "laugh", "\uD83D\uDE06": "laugh",
+  "\u203C\uFE0F": "emphasize", "\u2757": "emphasize", "\u2755": "emphasize",
+  "\u2753": "question",
+  // Text aliases
+  "heart": "heart", "love": "heart",
+  "thumbsup": "thumbsup", "like": "thumbsup", "+1": "thumbsup",
+  "thumbsdown": "thumbsdown", "dislike": "thumbsdown", "-1": "thumbsdown",
+  "laugh": "laugh", "haha": "laugh",
+  "emphasize": "emphasize", "emphasis": "emphasize", "!!": "emphasize", "exclamation": "emphasize",
+  "question": "question", "?": "question",
+};
+
+function mapEmojiToTapback(emoji) {
+  return EMOJI_TO_TAPBACK[emoji] || EMOJI_TO_TAPBACK[emoji.toLowerCase()] || null;
+}
+
+/**
+ * TextClaw iMessage channel plugin for OpenClaw.
+ *
+ * For BYOC (Bring Your Own Claw) users who subscribe to TextClaw's
+ * iMessage relay service. No Mac required — messages route through
+ * TextClaw's infrastructure which handles iMessage delivery.
+ *
+ * Outbound: sends messages, typing indicators, and reactions via TextClaw relay API.
+ * Inbound: receives forwarded webhooks from TextClaw via WebSocket or HTTP route.
+ */
+const channelPlugin = {
+  id: "imessage",
+  name: "TextClaw iMessage",
+  description: "iMessage channel via TextClaw relay — no Mac required",
+
+  meta: {
+    id: "imessage",
+    label: "TextClaw (iMessage)",
+    docsPath: "/channels/imessage",
+    blurb: "iMessage relay via TextClaw WebSocket bridge.",
+    order: 100,
+  },
+
+  capabilities: {
+    chatTypes: ["direct"],
+  },
+
+  // -- Config adapter --
+  config: {
+    listAccountIds(cfg) {
+      const pluginCfg = cfg.plugins?.entries?.textclaw?.config;
+      return pluginCfg?.textclawUrl ? ["default"] : [];
+    },
+    resolveAccount(cfg, accountId) {
+      return cfg.plugins?.entries?.textclaw?.config ?? {};
+    },
+  },
+
+  // -- Gateway adapter --
+  gateway: {
+    startAccount(account, runtime) {
+      api.configure(account.textclawUrl, account.apiKey);
+      console.log(`[textclaw] gateway startAccount called — runtime type: ${typeof runtime}`, runtime ? Object.keys(runtime).join(', ') : 'undefined');
+    },
+
+    stopAccount(account) {
+      console.log(`[textclaw] gateway account stopped`);
+    },
+  },
+
+  // -- Outbound adapter --
+  outbound: {
+    async sendPayload(account, target, payload) {
+      const peer = target.peer;
+      const text = payload.text || "";
+      const mediaUrl = payload.mediaUrl || null;
+
+      if (!text && !mediaUrl) return;
+
+      const chunks = chunkText(text);
+
+      let lastResult = null;
+      for (const chunk of chunks) {
+        lastResult = await sendMessageToPeer(account, peer, chunk, {
+          mediaUrl: chunks.indexOf(chunk) === 0 ? mediaUrl : null,
+        });
+      }
+
+      return lastResult;
+    },
+
+    async sendTypingIndicator(account, target) {
+      await sendTyping(account, target.peer);
+    },
+  },
+
+  // -- Messaging adapter --
+  messaging: {
+    normalizeTarget(rawTarget) {
+      return {
+        peer: rawTarget.replace(/[^+\d]/g, ""),
+        chatType: "dm",
+      };
+    },
+
+    inferChatType(target) {
+      return "dm";
+    },
+
+    getSessionKey(target) {
+      return `imessage:${target.peer}`;
+    },
+  },
+
+  // -- Actions adapter (OpenClaw message tool integration) --
+  actions: {
+    describeMessageTool(ctx) {
+      return {
+        actions: ["react"],
+        capabilities: [],
+        schema: null,
+      };
+    },
+
+    async handleAction({ action, params, cfg, accountId, toolContext }) {
+      if (action !== "react") return null;
+
+      // Resolve peer from session key (format: "imessage:<phone>")
+      const sessionKey = toolContext?.sessionKey || "";
+      const peer = toolContext?.target?.peer || sessionKey.replace(/^imessage:/, "") || null;
+      if (!peer) throw new Error("No peer target available for reaction.");
+
+      // Map emoji/text to iMessage tapback type
+      const emoji = typeof params.emoji === "string" ? params.emoji.trim() : "";
+      const reaction = mapEmojiToTapback(emoji);
+      if (!reaction) {
+        throw new Error(
+          `Unsupported reaction "${emoji}". ` +
+          `iMessage supports: heart, thumbsup, thumbsdown, laugh, emphasize, question`
+        );
+      }
+
+      // Resolve message handle — explicit messageId, toolContext, or last inbound
+      const messageHandle = (typeof params.messageId === "string" ? params.messageId : null)
+        || toolContext?.currentMessageId
+        || getLastInboundHandle(peer)
+        || null;
+
+      await sendReactionToPeer(null, peer, reaction, messageHandle);
+
+      return {
+        content: [{ type: "text", text: JSON.stringify({ ok: true, reaction }) }],
+      };
+    },
+  },
+
+  // -- Typing config --
+  typingMode: "instant",
+  typingIntervalMs: 5000,
+  maxChunkSize: 4000,
+};
+
+export default channelPlugin;

package/src/handle-store.js

@@ -0,0 +1,68 @@
+/**
+ * In-memory store for message_handle (Apple GUID) tracking.
+ * Maps peer phone numbers to their most recent message handles,
+ * enabling reactions to specific messages.
+ */
+
+// Map<peerId, { inbound: messageHandle, outbound: messageHandle }>
+const handles = new Map();
+
+// Map<messageHandle, { peer, direction, timestamp }>
+const handleIndex = new Map();
+
+const MAX_HANDLES = 10000;
+
+/**
+ * Store a message handle for a peer.
+ * @param {string} peer - Phone number (E.164)
+ * @param {string} messageHandle - Apple GUID
+ * @param {"inbound"|"outbound"} direction
+ */
+export function storeHandle(peer, messageHandle, direction) {
+  if (!handles.has(peer)) {
+    handles.set(peer, {});
+  }
+  handles.get(peer)[direction] = messageHandle;
+
+  handleIndex.set(messageHandle, {
+    peer,
+    direction,
+    timestamp: Date.now(),
+  });
+
+  // Evict old entries if index grows too large
+  if (handleIndex.size > MAX_HANDLES) {
+    const entries = [...handleIndex.entries()];
+    entries.sort((a, b) => a[1].timestamp - b[1].timestamp);
+    for (let i = 0; i < entries.length - MAX_HANDLES; i++) {
+      handleIndex.delete(entries[i][0]);
+    }
+  }
+}
+
+/**
+ * Get the most recent inbound message handle for a peer.
+ * @param {string} peer - Phone number
+ * @returns {string|null}
+ */
+export function getLastInboundHandle(peer) {
+  return handles.get(peer)?.inbound || null;
+}
+
+/**
+ * Get the most recent outbound message handle for a peer.
+ * @param {string} peer - Phone number
+ * @returns {string|null}
+ */
+export function getLastOutboundHandle(peer) {
+  return handles.get(peer)?.outbound || null;
+}
+
+/**
+ * Look up metadata for a specific message handle.
+ * @param {string} messageHandle
+ * @returns {{ peer: string, direction: string, timestamp: number }|null}
+ */
+export function lookupHandle(messageHandle) {
+  return handleIndex.get(messageHandle) || null;
+}

package/src/media.js

@@ -0,0 +1,53 @@
+import { createWriteStream, mkdirSync } from "fs";
+import { join } from "path";
+import { randomUUID } from "crypto";
+import { homedir } from "os";
+import { pipeline } from "stream/promises";
+
+const MEDIA_DIR = join(homedir(), ".openclaw", "media", "inbound");
+
+/**
+ * Download a remote media file and save it to OpenClaw's local media directory.
+ *
+ * OpenClaw's media pipeline expects local files in ~/.openclaw/media/inbound/,
+ * matching how the Discord plugin handles attachments.
+ *
+ * @param {string} url - Remote URL to download
+ * @returns {{ path: string, contentType: string }}
+ */
+export async function saveRemoteMedia(url) {
+  mkdirSync(MEDIA_DIR, { recursive: true });
+
+  // Detect extension from URL, default to .ogg (voice notes after backend conversion)
+  const urlPath = new URL(url).pathname;
+  const dotIdx = urlPath.lastIndexOf(".");
+  const ext = dotIdx !== -1 ? urlPath.slice(dotIdx) : ".ogg";
+
+  const filename = `${randomUUID()}${ext}`;
+  const localPath = join(MEDIA_DIR, filename);
+
+  const resp = await fetch(url);
+  if (!resp.ok) throw new Error(`Download failed: ${resp.status}`);
+
+  const fileStream = createWriteStream(localPath);
+  await pipeline(resp.body, fileStream);
+
+  // Determine MIME type from extension
+  const mimeMap = {
+    ".ogg": "audio/ogg; codecs=opus",
+    ".mp3": "audio/mpeg",
+    ".wav": "audio/wav",
+    ".m4a": "audio/mp4",
+    ".flac": "audio/flac",
+    ".webm": "audio/webm",
+    ".mp4": "video/mp4",
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".webp": "image/webp",
+  };
+  const contentType = mimeMap[ext.toLowerCase()] || "application/octet-stream";
+
+  return { path: localPath, contentType };
+}

package/src/monitor.js

@@ -0,0 +1,182 @@
+import { recordInboundSessionAndDispatchReply } from "openclaw/plugin-sdk/compat";
+import { storeHandle } from "./handle-store.js";
+import { getPluginApi } from "./runtime.js";
+import { sendMessageToPeer, sendTyping, chunkText } from "./send.js";
+import { markRead } from "./api.js";
+import { saveRemoteMedia } from "./media.js";
+
+// Per-peer buffer for aggregating response blocks before sending
+const deliverBuffers = new Map();
+const DELIVER_DEBOUNCE_MS = 1500;
+
+// Per-peer typing interval — ensures only one interval per peer at a time
+const typingIntervals = new Map();
+
+/**
+ * Handle an inbound webhook forwarded from TextClaw.
+ *
+ * TextClaw receives inbound message webhooks and forwards them either
+ * via WebSocket or HTTP POST to /ext/textclaw/inbound.
+ *
+ * @param {object} payload - Inbound message payload (forwarded by TextClaw)
+ */
+export async function processInboundWebhook(payload) {
+  const eventType = payload.type || detectEventType(payload);
+
+  switch (eventType) {
+    case "receive":
+      return handleInboundMessage(payload);
+    case "typing_indicator":
+      console.log(`[textclaw] inbound typing from ${payload.from_number || payload.number}`);
+      return;
+    case "reaction":
+      console.log(`[textclaw] inbound reaction from ${payload.from_number || payload.number}`);
+      return;
+    default:
+      console.log(`[textclaw] ignoring webhook event type: ${eventType}`);
+  }
+}
+
+function detectEventType(payload) {
+  if (payload.content !== undefined || payload.media_url) return "receive";
+  if (payload.reaction) return "reaction";
+  if (payload.is_typing !== undefined) return "typing_indicator";
+  return "unknown";
+}
+
+/**
+ * Flush buffered response blocks for a peer as a single combined message.
+ */
+async function flushDeliverBuffer(account, peer) {
+  const buf = deliverBuffers.get(peer);
+  if (!buf) return;
+  deliverBuffers.delete(peer);
+
+  const combined = buf.texts.join("\n\n");
+  const mediaUrl = buf.media;
+
+  if (combined || mediaUrl) {
+    const chunks = chunkText(combined);
+    for (const chunk of chunks) {
+      await sendMessageToPeer(account, peer, chunk, {
+        mediaUrl: chunks.indexOf(chunk) === 0 ? mediaUrl : null,
+      });
+    }
+  }
+}
+
+async function handleInboundMessage(payload) {
+  const api = getPluginApi();
+  const runtime = api.runtime;
+  const cfg = api.config;
+  const account = api.pluginConfig;
+
+  const peer = payload.from_number || payload.number;
+  const messageHandle = payload.message_handle;
+  const text = payload.content || "";
+  const mediaUrl = payload.media_url || undefined;
+
+  if (messageHandle) {
+    storeHandle(peer, messageHandle, "inbound");
+  }
+
+  // Download media to local file (OpenClaw expects local paths, not URLs)
+  let mediaPayload = {};
+  if (mediaUrl) {
+    try {
+      const { path, contentType } = await saveRemoteMedia(mediaUrl);
+      mediaPayload = {
+        MediaPath: path,
+        MediaType: contentType,
+        MediaUrl: path,
+        MediaPaths: [path],
+        MediaUrls: [path],
+        MediaTypes: [contentType],
+      };
+      console.log(`[textclaw] saved media to ${path}`);
+    } catch (err) {
+      console.warn(`[textclaw] media download failed: ${err.message}`);
+    }
+  }
+
+  const sessionKey = `imessage:${peer}`;
+
+  console.log(`[textclaw] dispatching inbound from ${peer}: "${text.slice(0, 50)}${text.length > 50 ? '...' : ''}"`);
+
+  // Send read receipt so iMessage shows "Read" to the sender
+  markRead(peer).catch((err) => {
+    console.warn(`[textclaw] mark-read failed for ${peer}: ${err.message}`);
+  });
+
+  // Clear any existing typing interval for this peer (prevents leaks from rapid messages)
+  if (typingIntervals.has(peer)) {
+    clearInterval(typingIntervals.get(peer));
+  }
+
+  // Send repeating typing indicator while the agent is thinking (every 3s)
+  sendTyping(account, peer);
+  const typingInterval = setInterval(() => sendTyping(account, peer), 3000);
+  typingIntervals.set(peer, typingInterval);
+
+  function stopTyping() {
+    clearInterval(typingInterval);
+    if (typingIntervals.get(peer) === typingInterval) {
+      typingIntervals.delete(peer);
+    }
+  }
+
+  try {
+    await recordInboundSessionAndDispatchReply({
+      cfg,
+      channel: "imessage",
+      accountId: "default",
+      agentId: "main",
+      routeSessionKey: sessionKey,
+      storePath: runtime.state.resolveStateDir() + "/sessions/imessage-sessions.json",
+      ctxPayload: {
+        Body: text,
+        ...mediaPayload,
+        From: `imessage:${peer}`,
+        To: "imessage:default",
+        SessionKey: sessionKey,
+        AccountId: "default",
+        ChatType: "direct",
+        SenderName: peer,
+        SenderId: peer,
+        Provider: "imessage",
+        Surface: "imessage",
+        WasMentioned: true,
+        MessageSid: messageHandle || "",
+        Timestamp: payload.date_sent || new Date().toISOString(),
+      },
+      recordInboundSession: runtime.channel.session.recordInboundSession,
+      dispatchReplyWithBufferedBlockDispatcher: runtime.channel.reply.dispatchReplyWithBufferedBlockDispatcher,
+      deliver: async (replyPayload) => {
+        stopTyping();
+        const replyText = replyPayload.Body || replyPayload.text || "";
+        const replyMedia = replyPayload.MediaUrl || replyPayload.mediaUrl || null;
+
+        // Buffer response blocks and debounce — send combined after 1.5s of no new blocks
+        if (!deliverBuffers.has(peer)) {
+          deliverBuffers.set(peer, { texts: [], media: null, timer: null });
+        }
+        const buf = deliverBuffers.get(peer);
+        if (replyText) buf.texts.push(replyText);
+        if (replyMedia) buf.media = replyMedia;
+
+        clearTimeout(buf.timer);
+        buf.timer = setTimeout(() => {
+          flushDeliverBuffer(account, peer).catch((err) => {
+            console.error("[textclaw] deliver flush error:", err);
+          });
+        }, DELIVER_DEBOUNCE_MS);
+      },
+      onRecordError: (err) => console.error("[textclaw] session record error:", err),
+      onDispatchError: (err) => console.error("[textclaw] dispatch error:", err),
+      replyOptions: {},
+    });
+  } catch (err) {
+    stopTyping();
+    console.error("[textclaw] inbound dispatch failed:", err);
+  }
+}

package/src/runtime.js

@@ -0,0 +1,10 @@
+let pluginApi = null;
+
+export function setPluginApi(api) {
+  pluginApi = api;
+}
+
+export function getPluginApi() {
+  if (!pluginApi) throw new Error("[textclaw] pluginApi not initialized");
+  return pluginApi;
+}

package/src/send.js

@@ -0,0 +1,110 @@
+import * as api from "./api.js";
+import { storeHandle, getLastInboundHandle } from "./handle-store.js";
+
+/**
+ * Send a message to a peer via TextClaw relay.
+ * @param {object} account - Resolved account config
+ * @param {string} peer - Recipient phone number (E.164)
+ * @param {string} text - Message content
+ * @param {object} [options]
+ * @param {string} [options.mediaUrl] - Media attachment URL
+ * @returns {Promise<{ messageId: string }>}
+ */
+export async function sendMessageToPeer(account, peer, text, options = {}) {
+  const result = await api.sendMessage(
+    null, // fromNumber not needed — TextClaw uses shared BYOC number
+    peer,
+    text,
+    options.mediaUrl || null,
+  );
+
+  // Store the message_handle for future reactions
+  if (result.message_handle) {
+    storeHandle(peer, result.message_handle, "outbound");
+  }
+
+  return {
+    messageId: result.message_handle || result.external_message_id || "",
+  };
+}
+
+/**
+ * Send a voice note to a peer via TextClaw relay.
+ * The server converts the audio to .caf for inline iMessage playback.
+ * @param {object} account - Resolved account config
+ * @param {string} peer - Recipient phone number (E.164)
+ * @param {string} mediaUrl - URL to an audio file
+ * @returns {Promise<{ messageId: string }>}
+ */
+export async function sendVoiceNoteToPeer(account, peer, mediaUrl) {
+  const result = await api.sendVoiceNote(null, peer, mediaUrl);
+
+  if (result.message_handle) {
+    storeHandle(peer, result.message_handle, "outbound");
+  }
+
+  return {
+    messageId: result.message_handle || result.external_message_id || "",
+  };
+}
+
+/**
+ * Send typing indicator to a peer.
+ * @param {object} account - Resolved account config
+ * @param {string} peer - Recipient phone number (E.164)
+ */
+export async function sendTyping(account, peer) {
+  try {
+    await api.sendTypingIndicator(null, peer);
+  } catch (err) {
+    // Typing indicators are best-effort
+    console.warn(`[textclaw] typing indicator failed for ${peer}: ${err.message}`);
+  }
+}
+
+/**
+ * Send a reaction (tapback) to the last inbound message from a peer.
+ * @param {object} account - Resolved account config
+ * @param {string} peer - Phone number of the conversation
+ * @param {"heart"|"thumbsup"|"thumbsdown"|"laugh"|"emphasize"|"question"} reaction
+ * @param {string} [messageHandle] - Specific message to react to (defaults to last inbound)
+ */
+export async function sendReactionToPeer(account, peer, reaction, messageHandle = null) {
+  const handle = messageHandle || getLastInboundHandle(peer);
+  if (!handle) {
+    console.warn(`[textclaw] no message handle found for ${peer}, cannot send reaction`);
+    return;
+  }
+
+  await api.sendReaction(null, handle, reaction);
+}
+
+/**
+ * Chunk text into iMessage-friendly segments.
+ * @param {string} text
+ * @param {number} [maxLen=4000]
+ * @returns {string[]}
+ */
+export function chunkText(text, maxLen = 4000) {
+  if (text.length <= maxLen) return [text];
+
+  const chunks = [];
+  let remaining = text;
+  while (remaining.length > 0) {
+    if (remaining.length <= maxLen) {
+      chunks.push(remaining);
+      break;
+    }
+    // Try to break at a newline or space
+    let breakAt = remaining.lastIndexOf("\n", maxLen);
+    if (breakAt < maxLen * 0.5) {
+      breakAt = remaining.lastIndexOf(" ", maxLen);
+    }
+    if (breakAt < maxLen * 0.5) {
+      breakAt = maxLen;
+    }
+    chunks.push(remaining.slice(0, breakAt));
+    remaining = remaining.slice(breakAt).trimStart();
+  }
+  return chunks;
+}

package/src/ws.js

@@ -0,0 +1,129 @@
+/**
+ * WebSocket client for receiving inbound iMessages from TextClaw.
+ *
+ * Instead of requiring a public URL for webhook delivery, the extension
+ * maintains a persistent WebSocket connection to TextClaw. Messages are
+ * pushed through this socket in real time — like Discord bot gateway.
+ */
+
+import { processInboundWebhook } from "./monitor.js";
+
+let ws = null;
+let wsUrl = null;
+let reconnectDelay = 1000;
+let reconnectTimer = null;
+let pongTimer = null;
+
+const MAX_RECONNECT_DELAY = 30000;
+const PONG_INTERVAL = 30000;
+
+/**
+ * Start the WebSocket connection to TextClaw.
+ * @param {string} url - WebSocket URL with api_key query param
+ */
+export function startWebSocket(url) {
+  if (ws) return; // Already connected or connecting — prevent duplicates
+  wsUrl = url;
+  connect();
+}
+
+/**
+ * Stop the WebSocket connection and clean up timers.
+ */
+export function stopWebSocket() {
+  if (reconnectTimer) clearTimeout(reconnectTimer);
+  if (pongTimer) clearInterval(pongTimer);
+  if (ws) {
+    ws.close(1000, "stopping");
+    ws = null;
+  }
+}
+
+function connect() {
+  const maskedUrl = wsUrl.replace(/api_key=[^&]+/, "api_key=***");
+  console.log(`[textclaw] WebSocket connecting to ${maskedUrl}`);
+
+  ws = new WebSocket(wsUrl);
+
+  ws.addEventListener("open", () => {
+    console.log("[textclaw] WebSocket connected");
+    reconnectDelay = 1000;
+    startPong();
+  });
+
+  ws.addEventListener("message", (event) => {
+    try {
+      const data = JSON.parse(event.data);
+      handleMessage(data);
+    } catch (err) {
+      console.error("[textclaw] WebSocket message parse error:", err);
+    }
+  });
+
+  ws.addEventListener("close", (event) => {
+    console.log(`[textclaw] WebSocket closed: code=${event.code} reason=${event.reason}`);
+    stopPong();
+    ws = null;
+    // 4010 = replaced by newer connection — don't reconnect
+    if (event.code === 4010) {
+      console.log("[textclaw] WebSocket replaced by newer connection, not reconnecting");
+      return;
+    }
+    scheduleReconnect();
+  });
+
+  ws.addEventListener("error", (err) => {
+    console.error("[textclaw] WebSocket error:", err.message || err);
+    // If connection failed before opening, close event may not fire — ensure reconnect
+    if (ws && ws.readyState !== WebSocket.OPEN && ws.readyState !== WebSocket.CONNECTING) {
+      ws = null;
+      scheduleReconnect();
+    }
+  });
+}
+
+function handleMessage(data) {
+  switch (data.type) {
+    case "connection_ack":
+      console.log(`[textclaw] WebSocket authenticated, account=${data.account_id}`);
+      break;
+    case "inbound_message":
+      processInboundWebhook(data.payload).catch((err) => {
+        console.error("[textclaw] inbound message processing error:", err);
+      });
+      break;
+    case "ping":
+      if (ws && ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify({ type: "pong" }));
+      }
+      break;
+    default:
+      console.log(`[textclaw] Unknown WebSocket message type: ${data.type}`);
+  }
+}
+
+function scheduleReconnect() {
+  const jitter = reconnectDelay * 0.25 * (Math.random() * 2 - 1);
+  const delay = Math.min(reconnectDelay + jitter, MAX_RECONNECT_DELAY);
+
+  console.log(`[textclaw] Reconnecting in ${Math.round(delay)}ms`);
+  reconnectTimer = setTimeout(() => {
+    reconnectDelay = Math.min(reconnectDelay * 2, MAX_RECONNECT_DELAY);
+    connect();
+  }, delay);
+}
+
+function startPong() {
+  pongTimer = setInterval(() => {
+    if (ws && ws.readyState === WebSocket.OPEN) {
+      ws.send(JSON.stringify({ type: "pong" }));
+    }
+  }, PONG_INTERVAL);
+}
+
+function stopPong() {
+  if (pongTimer) {
+    clearInterval(pongTimer);
+    pongTimer = null;
+  }
+}