@eclaw/openclaw-channel 1.0.16 → 1.0.18

package/README.md

@@ -25,15 +25,15 @@ channels:
         apiKey: "eck_..."       # From E-Claw Portal → Settings → Channel API
         apiSecret: "ecs_..."    # From E-Claw Portal → Settings → Channel API
         apiBase: "https://eclawbot.com"
-        entityId: 0             # Which entity slot to use (0-3)
-        botName: "My Bot"
+        entityId: 0             # Entity slot (0-3 free tier, 0-7 premium). Omit to auto-assign.
+        botName: "My Bot"       # Display name in E-Claw (max 20 chars)
 ```
 
 ## Getting API Credentials
 
 1. Log in to [E-Claw Portal](https://eclawbot.com/portal)
 2. Go to **Settings → Channel API**
-3. Copy your `API Key` and `API Secret`
+3. Copy your `API Key` (`eck_...`) and `API Secret` (`ecs_...`)
 
 ## How It Works
 
@@ -46,6 +46,103 @@ OpenClaw Agent ──replies──▶ POST /api/channel/message ──▶ User (
 - **Outbound**: Plugin calls `POST /api/channel/message` with the bot reply
 - **Auth**: `eck_`/`ecs_` channel credentials for API auth, per-entity `botSecret` for message auth
 
+## Inbound Message Structure
+
+Every message delivered to your webhook has this shape:
+
+```json
+{
+  "event": "message",
+  "from": "user",
+  "deviceId": "...",
+  "entityId": 0,
+  "conversationId": "...:0",
+  "text": "Hello!",
+  "timestamp": 1741234567890,
+  "isBroadcast": false,
+  "eclaw_context": {
+    "expectsReply": true,
+    "silentToken": "[SILENT]",
+    "missionHints": "..."
+  }
+}
+```
+
+### `event` values
+
+| Value | Description |
+|-------|-------------|
+| `message` | Normal message from the device user |
+| `entity_message` | Bot-to-bot message (another entity spoke directly to yours) |
+| `broadcast` | Broadcast from another entity (one-to-many) |
+
+### `from` values
+
+| Value | Description |
+|-------|-------------|
+| `user` | Human user on the Android device |
+| `system` | Server-generated event (name change, entity moved, etc.) |
+| `scheduled` | Scheduled message created by the device owner |
+
+## `eclaw_context` — Channel Bot Parity
+
+Since v1.0.17, every inbound push includes an `eclaw_context` block that gives your bot the same awareness as traditional push-based bots:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `expectsReply` | `boolean` | `false` for system events and quota-exceeded bot messages — your bot should output `silentToken` to stay quiet |
+| `silentToken` | `string` | Output this exact string to suppress all API calls (default: `"[SILENT]"`) |
+| `missionHints` | `string` | API reference for reading/writing mission tasks (TODO, SKILL, RULE, SOUL) for this entity |
+| `b2bRemaining` | `number` | Remaining bot-to-bot reply quota for this conversation (resets on human message) |
+| `b2bMax` | `number` | Maximum bot-to-bot quota (currently 8) |
+
+### Staying Silent
+
+When `expectsReply` is `false`, output the `silentToken` to avoid sending an unwanted reply:
+
+```
+User message: [SYSTEM:ENTITY_MOVED] Your entity slot has changed...
+Bot reply: [SILENT]  ← plugin suppresses all API calls
+```
+
+The plugin checks the AI output and skips `sendMessage()` / `speakTo()` entirely when the reply equals `silentToken`.
+
+## System Events
+
+The E-Claw server automatically pushes system events to your bot so it can stay in sync. All system events have `from: "system"` and `eclaw_context.expectsReply: false`.
+
+| Event tag in text | Trigger |
+|---|---|
+| `[SYSTEM:ENTITY_MOVED]` | Device owner reordered entities — your bot's slot changed |
+| `[SYSTEM:NAME_CHANGED]` | Device owner renamed this entity |
+
+Example `ENTITY_MOVED` payload text:
+```
+[SYSTEM:ENTITY_MOVED] Your entity slot has changed from #1 to #2.
+
+UPDATED CREDENTIALS:
+- entityId: 2 (was 1)
+- deviceId: ...
+- botSecret: ...
+```
+
+## Bot-to-Bot Messages (`entity_message` / `broadcast`)
+
+When another E-Claw entity sends your bot a message, the plugin automatically enriches the body before dispatching to your OpenClaw agent:
+
+```
+[Bot-to-Bot message from Entity 2 (LOBSTER)]
+[Quota: 7/8 remaining — output "[SILENT]" if no new info worth replying to]
+<mission API hints>
+Hello! How are you?
+```
+
+On reply, the plugin calls both `sendMessage()` (to update your own wallpaper state) and `speakTo(fromEntityId)` (to reply to the sender).
+
+## Scheduled Messages
+
+Device owners can schedule messages to be sent to your bot at a specific time (or on a repeating schedule). These arrive with `from: "scheduled"` and `eclaw_context.expectsReply: true` — your bot is expected to respond normally.
+
 ## Environment Variables
 
 | Variable | Required | Description |

package/dist/outbound.d.ts

@@ -1,4 +1,6 @@
 import { EClawClient } from './client.js';
+export declare function setActiveEvent(accountId: string, event: string): void;
+export declare function clearActiveEvent(accountId: string): void;
 export declare function setClient(accountId: string, client: EClawClient): void;
 export declare function getClient(accountId: string): EClawClient | undefined;
 /** OpenClaw outbound: send text message to E-Claw user */

package/dist/outbound.js

@@ -1,5 +1,13 @@
 /** Client instances keyed by accountId */
 const clients = new Map();
+/** Track current inbound event type per account to suppress duplicate sendMessage calls */
+const activeEvent = new Map();
+export function setActiveEvent(accountId, event) {
+    activeEvent.set(accountId, event);
+}
+export function clearActiveEvent(accountId) {
+    activeEvent.delete(accountId);
+}
 export function setClient(accountId, client) {
     clients.set(accountId, client);
 }
@@ -10,6 +18,11 @@ export function getClient(accountId) {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export async function sendText(ctx) {
     const accountId = ctx.accountId ?? 'default';
+    // Suppress duplicate delivery for bot-to-bot events — webhook-handler's deliver handles these
+    const event = activeEvent.get(accountId) ?? 'message';
+    if (event === 'entity_message' || event === 'broadcast') {
+        return { channel: 'eclaw', messageId: '', chatId: '' };
+    }
     const client = clients.get(accountId);
     if (!client) {
         return { channel: 'eclaw', messageId: '', chatId: '' };
@@ -32,6 +45,11 @@ export async function sendText(ctx) {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export async function sendMedia(ctx) {
     const accountId = ctx.accountId ?? 'default';
+    // Suppress duplicate delivery for bot-to-bot events — webhook-handler's deliver handles these
+    const event = activeEvent.get(accountId) ?? 'message';
+    if (event === 'entity_message' || event === 'broadcast') {
+        return { channel: 'eclaw', messageId: '', chatId: '' };
+    }
     const client = clients.get(accountId);
     if (!client) {
         return { channel: 'eclaw', messageId: '', chatId: '' };

package/dist/types.d.ts

@@ -8,6 +8,14 @@ export interface EClawAccountConfig {
     botName?: string;
     webhookUrl?: string;
 }
+/** Context block injected by E-Claw server for Channel Bot parity with Traditional Bot */
+export interface EClawContext {
+    b2bRemaining?: number;
+    b2bMax?: number;
+    expectsReply?: boolean;
+    missionHints?: string;
+    silentToken?: string;
+}
 /** Inbound message from E-Claw callback webhook */
 export interface EClawInboundMessage {
     event: 'message' | 'entity_message' | 'broadcast' | 'cross_device_message';
@@ -25,6 +33,7 @@ export interface EClawInboundMessage {
     fromEntityId?: number;
     fromCharacter?: string;
     fromPublicCode?: string;
+    eclaw_context?: EClawContext;
 }
 /** Entity info returned by channel register */
 export interface EClawEntityInfo {

package/dist/webhook-handler.d.ts

@@ -3,10 +3,16 @@
  *
  * Handles three event types:
  *   - 'message'        → Normal human message; reply via sendMessage()
- *   - 'entity_message' → Bot-to-bot speak-to; reply via speakTo(fromEntityId)
- *   - 'broadcast'      → Broadcast from another entity; reply via speakTo(fromEntityId)
+ *   - 'entity_message' → Bot-to-bot speak-to; reply via sendMessage() + speakTo(fromEntityId)
+ *   - 'broadcast'      → Broadcast from another entity; reply via sendMessage() + speakTo(fromEntityId)
  *
  * The `deliver` callback routes AI response to the correct E-Claw endpoint
  * based on the inbound event type.
+ *
+ * Channel Bot Context Parity v1.0.17:
+ *   - Bot-to-bot / broadcast now calls sendMessage() to update own wallpaper AND speakTo() to reply
+ *   - Quota awareness via eclaw_context.b2bRemaining / b2bMax
+ *   - Mission context via eclaw_context.missionHints
+ *   - Silent suppression via silentToken (default "[SILENT]")
  */
 export declare function createWebhookHandler(expectedToken: string, accountId: string, cfg: any): (req: any, res: any) => Promise<void>;

package/dist/webhook-handler.js

@@ -1,15 +1,21 @@
 import { getPluginRuntime } from './runtime.js';
-import { getClient } from './outbound.js';
+import { getClient, setActiveEvent, clearActiveEvent } from './outbound.js';
 /**
  * Create an HTTP request handler for inbound messages from E-Claw.
  *
  * Handles three event types:
  *   - 'message'        → Normal human message; reply via sendMessage()
- *   - 'entity_message' → Bot-to-bot speak-to; reply via speakTo(fromEntityId)
- *   - 'broadcast'      → Broadcast from another entity; reply via speakTo(fromEntityId)
+ *   - 'entity_message' → Bot-to-bot speak-to; reply via sendMessage() + speakTo(fromEntityId)
+ *   - 'broadcast'      → Broadcast from another entity; reply via sendMessage() + speakTo(fromEntityId)
  *
  * The `deliver` callback routes AI response to the correct E-Claw endpoint
  * based on the inbound event type.
+ *
+ * Channel Bot Context Parity v1.0.17:
+ *   - Bot-to-bot / broadcast now calls sendMessage() to update own wallpaper AND speakTo() to reply
+ *   - Quota awareness via eclaw_context.b2bRemaining / b2bMax
+ *   - Mission context via eclaw_context.missionHints
+ *   - Silent suppression via silentToken (default "[SILENT]")
  */
 export function createWebhookHandler(expectedToken, accountId, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -37,6 +43,9 @@ cfg // full openclaw config (ctx.cfg from startAccount)
             const event = msg.event || 'message';
             const fromEntityId = msg.fromEntityId;
             const fromCharacter = msg.fromCharacter;
+            // Read server-injected context block (Channel Bot parity)
+            const eclawCtx = msg.eclaw_context;
+            const silentToken = eclawCtx?.silentToken ?? '[SILENT]';
             // Map E-Claw media type to OpenClaw media type
             const ocMediaType = msg.mediaType === 'photo' ? 'image'
                 : msg.mediaType === 'voice' ? 'audio'
@@ -49,10 +58,16 @@ cfg // full openclaw config (ctx.cfg from startAccount)
                 const senderLabel = fromCharacter
                     ? `Entity ${fromEntityId} (${fromCharacter})`
                     : `Entity ${fromEntityId}`;
-                const prefix = event === 'broadcast'
+                const eventPrefix = event === 'broadcast'
                     ? `[Broadcast from ${senderLabel}]`
                     : `[Bot-to-Bot message from ${senderLabel}]`;
-                body = `${prefix}\n${msg.text || ''}`;
+                const quotaLine = eclawCtx?.b2bRemaining !== undefined
+                    ? `[Quota: ${eclawCtx.b2bRemaining}/${eclawCtx.b2bMax ?? 8} remaining — output "${silentToken}" if no new info worth replying to]`
+                    : '';
+                const missionBlock = eclawCtx?.missionHints ?? '';
+                body = [eventPrefix, quotaLine, missionBlock, msg.text || '']
+                    .filter(Boolean)
+                    .join('\n');
             }
             // Build context in OpenClaw's native PascalCase format
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -75,42 +90,50 @@ cfg // full openclaw config (ctx.cfg from startAccount)
                 } : {}),
             };
             const ctxPayload = rt.channel.reply.finalizeInboundContext(inboundCtx);
-            await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
-                ctx: ctxPayload,
-                cfg,
-                dispatcherOptions: {
-                    // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                    deliver: async (payload) => {
-                        if (!client)
-                            return;
-                        const text = typeof payload.text === 'string' ? payload.text.trim() : '';
-                        if ((event === 'entity_message' || event === 'broadcast') && fromEntityId !== undefined) {
-                            // Bot-to-bot or broadcast: reply via speak-to to the sender
-                            // Do NOT call sendMessage to avoid duplicate chat history entries
-                            if (text) {
-                                await client.speakTo(fromEntityId, text, false);
-                            }
-                        }
-                        else {
-                            // Normal human message: reply via channel message
-                            if (text) {
+            // Track event type so outbound.sendText() can suppress duplicate delivery
+            setActiveEvent(accountId, event);
+            try {
+                await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+                    ctx: ctxPayload,
+                    cfg,
+                    dispatcherOptions: {
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                        deliver: async (payload) => {
+                            if (!client)
+                                return;
+                            const text = typeof payload.text === 'string' ? payload.text.trim() : '';
+                            // [SILENT] token or empty → skip all API calls
+                            if (!text || text === silentToken)
+                                return;
+                            if ((event === 'entity_message' || event === 'broadcast') && fromEntityId !== undefined) {
+                                // Bot-to-bot / broadcast: update own wallpaper AND reply to sender
                                 await client.sendMessage(text, 'IDLE');
+                                await client.speakTo(fromEntityId, text, false);
                             }
-                            else if (payload.mediaUrl) {
-                                const rawType = typeof payload.mediaType === 'string' ? payload.mediaType : '';
-                                const mediaType = rawType === 'image' ? 'photo'
-                                    : rawType === 'audio' ? 'voice'
-                                        : rawType === 'video' ? 'video'
-                                            : 'file';
-                                await client.sendMessage('', 'IDLE', mediaType, payload.mediaUrl);
+                            else {
+                                // Normal human message: reply via channel message
+                                if (text) {
+                                    await client.sendMessage(text, 'IDLE');
+                                }
+                                else if (payload.mediaUrl) {
+                                    const rawType = typeof payload.mediaType === 'string' ? payload.mediaType : '';
+                                    const mediaType = rawType === 'image' ? 'photo'
+                                        : rawType === 'audio' ? 'voice'
+                                            : rawType === 'video' ? 'video'
+                                                : 'file';
+                                    await client.sendMessage('', 'IDLE', mediaType, payload.mediaUrl);
+                                }
                             }
-                        }
+                        },
+                        onError: (err) => {
+                            console.error('[E-Claw] Reply delivery error:', err);
+                        },
                     },
-                    onError: (err) => {
-                        console.error('[E-Claw] Reply delivery error:', err);
-                    },
-                },
-            });
+                });
+            }
+            finally {
+                clearActiveEvent(accountId);
+            }
         }
         catch (err) {
             console.error('[E-Claw] Webhook dispatch error:', err);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eclaw/openclaw-channel",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "description": "E-Claw channel plugin for OpenClaw — AI chat platform for live wallpaper entities",
   "type": "module",
   "main": "./dist/index.js",