@eclaw/openclaw-channel 1.0.14 → 1.0.16

package/dist/client.d.ts

@@ -12,13 +12,19 @@ export declare class EClawClient {
     constructor(config: EClawAccountConfig);
     /** Register callback URL with E-Claw backend */
     registerCallback(callbackUrl: string, callbackToken: string): Promise<RegisterResponse>;
-    /** Bind an entity via channel API (bypasses 6-digit code) */
-    bindEntity(entityId: number, name?: string): Promise<BindResponse>;
-    /** Send bot message to user */
+    /** Bind an entity via channel API (bypasses 6-digit code).
+     *  If entityId is omitted, the backend auto-selects the first free slot.
+     */
+    bindEntity(entityId?: number, name?: string): Promise<BindResponse>;
+    /** Send bot message to user (updates own entity state on wallpaper) */
     sendMessage(message: string, state?: string, mediaType?: string, mediaUrl?: string): Promise<MessageResponse>;
+    /** Send bot-to-bot message to another entity (speak-to) */
+    speakTo(toEntityId: number, text: string, expectsReply?: boolean): Promise<void>;
+    /** Broadcast message to all other bound entities */
+    broadcastToAll(text: string, expectsReply?: boolean): Promise<void>;
     /** Unregister callback on shutdown */
     unregisterCallback(): Promise<void>;
     get currentDeviceId(): string | null;
     get currentBotSecret(): string | null;
-    get currentEntityId(): number;
+    get currentEntityId(): number | undefined;
 }

package/dist/client.js

@@ -11,7 +11,7 @@ export class EClawClient {
     constructor(config) {
         this.apiBase = config.apiBase;
         this.apiKey = config.apiKey;
-        this.entityId = config.entityId;
+        this.entityId = config.entityId; // undefined until assigned by bindEntity
     }
     /** Register callback URL with E-Claw backend */
     async registerCallback(callbackUrl, callbackToken) {
@@ -31,27 +31,40 @@ export class EClawClient {
         this.deviceId = data.deviceId;
         return data;
     }
-    /** Bind an entity via channel API (bypasses 6-digit code) */
+    /** Bind an entity via channel API (bypasses 6-digit code).
+     *  If entityId is omitted, the backend auto-selects the first free slot.
+     */
     async bindEntity(entityId, name) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const body = { channel_api_key: this.apiKey };
+        if (entityId !== undefined)
+            body.entityId = entityId;
+        if (name)
+            body.name = name;
         const res = await fetch(`${this.apiBase}/api/channel/bind`, {
             method: 'POST',
             headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify({
-                channel_api_key: this.apiKey,
-                entityId,
-                name: name || undefined,
-            }),
+            body: JSON.stringify(body),
         });
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
         const data = await res.json();
         if (!data.success) {
+            // Build a detailed error message when all slots are full
+            if (res.status === 409 && data.entities) {
+                const list = data.entities
+                    .map((e) => `  slot ${e.entityId} (${e.character})${e.name ? ` "${e.name}"` : ''}`)
+                    .join('\n');
+                throw new Error(`${data.message}\nCurrent entities:\n${list}\n` +
+                    'Add entityId to your channel config to target a specific slot after unbinding it.');
+            }
             throw new Error(data.message || `Bind failed (HTTP ${res.status})`);
         }
         this.botSecret = data.botSecret;
         this.deviceId = data.deviceId;
-        this.entityId = entityId;
+        this.entityId = data.entityId; // Use server-assigned slot
         return data;
     }
-    /** Send bot message to user */
+    /** Send bot message to user (updates own entity state on wallpaper) */
     async sendMessage(message, state = 'IDLE', mediaType, mediaUrl) {
         if (!this.deviceId || !this.botSecret) {
             throw new Error('Not bound — call bindEntity() first');
@@ -72,6 +85,41 @@ export class EClawClient {
         });
         return await res.json();
     }
+    /** Send bot-to-bot message to another entity (speak-to) */
+    async speakTo(toEntityId, text, expectsReply = false) {
+        if (!this.deviceId || !this.botSecret) {
+            throw new Error('Not bound — call bindEntity() first');
+        }
+        await fetch(`${this.apiBase}/api/entity/speak-to`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                deviceId: this.deviceId,
+                fromEntityId: this.entityId,
+                toEntityId,
+                botSecret: this.botSecret,
+                text,
+                expects_reply: expectsReply,
+            }),
+        });
+    }
+    /** Broadcast message to all other bound entities */
+    async broadcastToAll(text, expectsReply = false) {
+        if (!this.deviceId || !this.botSecret) {
+            throw new Error('Not bound — call bindEntity() first');
+        }
+        await fetch(`${this.apiBase}/api/entity/broadcast`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                deviceId: this.deviceId,
+                fromEntityId: this.entityId,
+                botSecret: this.botSecret,
+                text,
+                expects_reply: expectsReply,
+            }),
+        });
+    }
     /** Unregister callback on shutdown */
     async unregisterCallback() {
         await fetch(`${this.apiBase}/api/channel/register`, {

package/dist/config.js

@@ -28,7 +28,7 @@ export function resolveAccount(cfg, accountId) {
         apiKey: account?.apiKey ?? '',
         apiSecret: account?.apiSecret,
         apiBase: (account?.apiBase ?? 'https://eclawbot.com').replace(/\/$/, ''),
-        entityId: account?.entityId ?? 0,
+        entityId: account?.entityId, // undefined = auto-assign
         botName: account?.botName,
         webhookUrl: account?.webhookUrl,
     };

package/dist/gateway.js

@@ -22,7 +22,7 @@ function resolveAccountFromCtx(ctx) {
             apiKey: ctx.account.apiKey,
             apiSecret: ctx.account.apiSecret,
             apiBase: (ctx.account.apiBase ?? 'https://eclawbot.com').replace(/\/$/, ''),
-            entityId: ctx.account.entityId ?? 0,
+            entityId: ctx.account.entityId, // undefined = auto-select
             botName: ctx.account.botName,
             webhookUrl: ctx.account.webhookUrl,
         };
@@ -83,14 +83,16 @@ export async function startAccount(ctx) {
         // Bind entity via channel API.
         // /api/channel/bind is idempotent for the same channel account:
         //   - Not bound → binds fresh, returns new botSecret
-        //   - Already bound via this channel account → returns existing botSecret
+        //   - Already bound via this channel account → returns existing botSecret (reconnect)
         //   - Bound via different method → throws error (user must unbind first)
-        const entityInfo = regData.entities.find(e => e.entityId === account.entityId);
-        const alreadyBound = entityInfo?.isBound ?? false;
+        // entityId is omitted here so the server auto-selects the best slot
         const bindData = await client.bindEntity(account.entityId, account.botName);
-        console.log(alreadyBound
-            ? `[E-Claw] Entity ${account.entityId} reconnected (existing channel binding), publicCode: ${bindData.publicCode}`
-            : `[E-Claw] Entity ${account.entityId} bound, publicCode: ${bindData.publicCode}`);
+        const assignedEntityId = bindData.entityId;
+        const entityInfo = regData.entities.find(e => e.entityId === assignedEntityId);
+        const wasAlreadyBound = entityInfo?.isBound ?? false;
+        console.log(wasAlreadyBound
+            ? `[E-Claw] Entity ${assignedEntityId} reconnected (existing channel binding), publicCode: ${bindData.publicCode}`
+            : `[E-Claw] Entity ${assignedEntityId} bound, publicCode: ${bindData.publicCode}`);
         console.log(`[E-Claw] Account ${accountId} ready!`);
     }
     catch (err) {

package/dist/types.d.ts

@@ -4,7 +4,7 @@ export interface EClawAccountConfig {
     apiKey: string;
     apiSecret?: string;
     apiBase: string;
-    entityId: number;
+    entityId?: number;
     botName?: string;
     webhookUrl?: string;
 }
@@ -50,6 +50,13 @@ export interface BindResponse {
     publicCode: string;
     bindingType: string;
 }
+/** Error response when all entity slots are full */
+export interface SlotsFullError {
+    success: false;
+    message: string;
+    entities: EClawEntityInfo[];
+    hint: string;
+}
 /** Response from POST /api/channel/message */
 export interface MessageResponse {
     success: boolean;

package/dist/webhook-handler.d.ts

@@ -1,10 +1,12 @@
 /**
  * Create an HTTP request handler for inbound messages from E-Claw.
  *
- * When a user sends a message on E-Claw, the backend POSTs structured JSON
- * to this webhook. We normalize it into OpenClaw's native PascalCase context
- * format and dispatch to the agent via dispatchReplyWithBufferedBlockDispatcher.
+ * 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)
  *
- * The `deliver` callback sends the AI reply back to E-Claw via the API client.
+ * The `deliver` callback routes AI response to the correct E-Claw endpoint
+ * based on the inbound event type.
  */
 export declare function createWebhookHandler(expectedToken: string, accountId: string, cfg: any): (req: any, res: any) => Promise<void>;

package/dist/webhook-handler.js

@@ -3,11 +3,13 @@ import { getClient } from './outbound.js';
 /**
  * Create an HTTP request handler for inbound messages from E-Claw.
  *
- * When a user sends a message on E-Claw, the backend POSTs structured JSON
- * to this webhook. We normalize it into OpenClaw's native PascalCase context
- * format and dispatch to the agent via dispatchReplyWithBufferedBlockDispatcher.
+ * 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)
  *
- * The `deliver` callback sends the AI reply back to E-Claw via the API client.
+ * The `deliver` callback routes AI response to the correct E-Claw endpoint
+ * based on the inbound event type.
  */
 export function createWebhookHandler(expectedToken, accountId, 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -31,14 +33,28 @@ cfg // full openclaw config (ctx.cfg from startAccount)
             const rt = getPluginRuntime();
             const client = getClient(accountId);
             const conversationId = msg.conversationId || `${msg.deviceId}:${msg.entityId}`;
+            // Capture event context for deliver routing
+            const event = msg.event || 'message';
+            const fromEntityId = msg.fromEntityId;
+            const fromCharacter = msg.fromCharacter;
             // Map E-Claw media type to OpenClaw media type
             const ocMediaType = msg.mediaType === 'photo' ? 'image'
                 : msg.mediaType === 'voice' ? 'audio'
                     : msg.mediaType === 'video' ? 'video'
                         : msg.mediaType ? 'file'
                             : undefined;
+            // Build body — enrich with event context for bot-to-bot and broadcast
+            let body = msg.text || '';
+            if ((event === 'entity_message' || event === 'broadcast') && fromEntityId !== undefined) {
+                const senderLabel = fromCharacter
+                    ? `Entity ${fromEntityId} (${fromCharacter})`
+                    : `Entity ${fromEntityId}`;
+                const prefix = event === 'broadcast'
+                    ? `[Broadcast from ${senderLabel}]`
+                    : `[Bot-to-Bot message from ${senderLabel}]`;
+                body = `${prefix}\n${msg.text || ''}`;
+            }
             // Build context in OpenClaw's native PascalCase format
-            // (same convention as Telegram/LINE/WhatsApp channels)
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             const inboundCtx = {
                 Surface: 'eclaw',
@@ -49,9 +65,9 @@ cfg // full openclaw config (ctx.cfg from startAccount)
                 To: conversationId,
                 OriginatingTo: msg.from,
                 SessionKey: conversationId,
-                Body: msg.text || '',
-                RawBody: msg.text || '',
-                CommandBody: msg.text || '',
+                Body: body,
+                RawBody: body,
+                CommandBody: body,
                 ChatType: 'direct',
                 ...(ocMediaType && msg.mediaUrl ? {
                     MediaType: ocMediaType,
@@ -68,16 +84,26 @@ cfg // full openclaw config (ctx.cfg from startAccount)
                         if (!client)
                             return;
                         const text = typeof payload.text === 'string' ? payload.text.trim() : '';
-                        if (text) {
-                            await client.sendMessage(text, 'IDLE');
+                        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 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) => {

package/openclaw.plugin.json

@@ -16,7 +16,7 @@
             "apiKey": { "type": "string", "description": "Channel API Key (eck_...)" },
             "apiSecret": { "type": "string", "description": "Channel API Secret (ecs_...)" },
             "apiBase": { "type": "string", "default": "https://eclawbot.com" },
-            "entityId": { "type": "number", "default": 0, "minimum": 0, "maximum": 7 },
+            "entityId": { "type": "number", "minimum": 0, "maximum": 7, "description": "Optional: entity slot to use (0-7). If omitted, auto-assigned to first free slot." },
             "botName": { "type": "string", "maxLength": 20 }
           },
           "required": ["apiKey", "apiSecret"]

package/package.json

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