@folotoy/folotoy-openclaw-plugin 0.1.1 → 0.2.0

package/README.md

@@ -64,10 +64,11 @@ Example `openclaw.json`:
 
 ## MQTT
 
-Both inbound and outbound messages use the same topic:
+Inbound and outbound use separate topics:
 
 ```
-/openapi/folotoy/{sn}/thing/data/post
+Inbound  (Toy → Plugin):  /openapi/folotoy/{sn}/thing/command/call
+Outbound (Plugin → Toy):  /openapi/folotoy/{sn}/thing/command/callAck
 ```
 
 The plugin connects with an `openapi:` prefix on the username to distinguish itself from the toy's own connection:
@@ -85,25 +86,46 @@ password: {toy_key}
 {
   "msgId": 1,
   "identifier": "chat_input",
-  "outParams": {
-    "text": "hello"
+  "inputParams": {
+    "text": "hello",
+    "recording_id": 100
   }
 }
 ```
 
 **Plugin → Toy (outbound)**
 
+Multiple response chunks with auto-incrementing `order`, followed by a finish message:
+
+```json
+{
+  "msgId": 1,
+  "identifier": "chat_output",
+  "outParams": {
+    "content": "hello",
+    "recording_id": 100,
+    "order": 1,
+    "is_finished": false
+  }
+}
+```
+
+Finish message (`is_finished: true`, empty content):
+
 ```json
 {
   "msgId": 1,
   "identifier": "chat_output",
   "outParams": {
-    "content": "hello"
+    "content": "",
+    "recording_id": 100,
+    "order": 2,
+    "is_finished": true
   }
 }
 ```
 
-`msgId` starts at 1 per session and auto-increments.
+`msgId` starts at 1 per session and auto-increments. `recording_id` is passed through from the inbound message.
 
 ## Environments
 

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "folotoy-openclaw-plugin",
   "name": "FoloToy",
   "description": "Empower your FoloToy with OpenClaw AI capabilities.",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "channels": ["folotoy"],
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@folotoy/folotoy-openclaw-plugin",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Empower your FoloToy with OpenClaw AI capabilities.",
   "keywords": [
     "folotoy",

package/src/__tests__/channel.test.ts

@@ -1,18 +1,18 @@
 import { describe, it, expect, vi } from 'vitest'
 import { EventEmitter } from 'events'
-import { buildTopic } from '../mqtt.js'
+import { buildInboundTopic, buildOutboundTopic } from '../mqtt.js'
 
 // Replicate the message parsing logic from index.ts for unit testing
 type InboundMessage = {
   msgId: number
   identifier: 'chat_input'
-  outParams: { text: string }
+  inputParams: { text: string; recording_id: number }
 }
 
 type OutboundMessage = {
   msgId: number
   identifier: 'chat_output'
-  outParams: { content: string }
+  outParams: { content: string; recording_id: number; order: number; is_finished: boolean }
 }
 
 function makeMockClient() {
@@ -23,15 +23,15 @@ function makeMockClient() {
   })
 }
 
-function setupSubscriber(client: ReturnType<typeof makeMockClient>, toy_sn: string, onMessage: (msgId: number, text: string) => void) {
-  const topic = buildTopic(toy_sn)
+function setupSubscriber(client: ReturnType<typeof makeMockClient>, toy_sn: string, onMessage: (msgId: number, text: string, recording_id: number) => void) {
+  const topic = buildInboundTopic(toy_sn)
   client.subscribe(topic, () => {})
   client.on('message', (_topic: string, payload: Buffer) => {
     if (_topic !== topic) return
     try {
       const msg = JSON.parse(payload.toString()) as InboundMessage
-      if (msg.identifier !== 'chat_input' || typeof msg.outParams?.text !== 'string') return
-      onMessage(msg.msgId, msg.outParams.text)
+      if (msg.identifier !== 'chat_input' || typeof msg.inputParams?.text !== 'string') return
+      onMessage(msg.msgId, msg.inputParams.text, msg.inputParams.recording_id)
     } catch {
       // ignore
     }
@@ -40,17 +40,17 @@ function setupSubscriber(client: ReturnType<typeof makeMockClient>, toy_sn: stri
 
 describe('inbound message parsing', () => {
   const toy_sn = 'SN001'
-  const topic = buildTopic(toy_sn)
+  const inboundTopic = buildInboundTopic(toy_sn)
 
-  it('calls onMessage with msgId and text on valid chat_input', () => {
+  it('calls onMessage with msgId, text and recording_id on valid chat_input', () => {
     const client = makeMockClient()
     const onMessage = vi.fn()
     setupSubscriber(client, toy_sn, onMessage)
 
-    const msg: InboundMessage = { msgId: 42, identifier: 'chat_input', outParams: { text: 'hello' } }
-    client.emit('message', topic, Buffer.from(JSON.stringify(msg)))
+    const msg: InboundMessage = { msgId: 42, identifier: 'chat_input', inputParams: { text: 'hello', recording_id: 100 } }
+    client.emit('message', inboundTopic, Buffer.from(JSON.stringify(msg)))
 
-    expect(onMessage).toHaveBeenCalledWith(42, 'hello')
+    expect(onMessage).toHaveBeenCalledWith(42, 'hello', 100)
   })
 
   it('ignores messages on other topics', () => {
@@ -58,8 +58,8 @@ describe('inbound message parsing', () => {
     const onMessage = vi.fn()
     setupSubscriber(client, toy_sn, onMessage)
 
-    const msg: InboundMessage = { msgId: 1, identifier: 'chat_input', outParams: { text: 'hi' } }
-    client.emit('message', '/openapi/folotoy/OTHER/thing/data/post', Buffer.from(JSON.stringify(msg)))
+    const msg: InboundMessage = { msgId: 1, identifier: 'chat_input', inputParams: { text: 'hi', recording_id: 1 } }
+    client.emit('message', '/openapi/folotoy/OTHER/thing/command/call', Buffer.from(JSON.stringify(msg)))
 
     expect(onMessage).not.toHaveBeenCalled()
   })
@@ -69,7 +69,7 @@ describe('inbound message parsing', () => {
     const onMessage = vi.fn()
     setupSubscriber(client, toy_sn, onMessage)
 
-    client.emit('message', topic, Buffer.from(JSON.stringify({ msgId: 1, identifier: 'other', outParams: { text: 'hi' } })))
+    client.emit('message', inboundTopic, Buffer.from(JSON.stringify({ msgId: 1, identifier: 'other', inputParams: { text: 'hi', recording_id: 1 } })))
 
     expect(onMessage).not.toHaveBeenCalled()
   })
@@ -79,7 +79,7 @@ describe('inbound message parsing', () => {
     const onMessage = vi.fn()
     setupSubscriber(client, toy_sn, onMessage)
 
-    client.emit('message', topic, Buffer.from('not json'))
+    client.emit('message', inboundTopic, Buffer.from('not json'))
 
     expect(onMessage).not.toHaveBeenCalled()
   })
@@ -87,22 +87,40 @@ describe('inbound message parsing', () => {
 
 describe('outbound message format', () => {
   const toy_sn = 'SN001'
-  const topic = buildTopic(toy_sn)
+  const outboundTopic = buildOutboundTopic(toy_sn)
 
-  it('publishes chat_output with correct msgId and content', () => {
+  it('publishes chat_output with recording_id, order and is_finished', () => {
     const client = makeMockClient()
-    const msgId = 42
-    const content = 'world'
     const outMsg: OutboundMessage = {
-      msgId,
+      msgId: 42,
       identifier: 'chat_output',
-      outParams: { content },
+      outParams: { content: 'world', recording_id: 100, order: 1, is_finished: false },
     }
-    client.publish(topic, JSON.stringify(outMsg))
+    client.publish(outboundTopic, JSON.stringify(outMsg))
 
     expect(client.publish).toHaveBeenCalledOnce()
     const [t, payload] = client.publish.mock.calls[0] as [string, string]
-    expect(t).toBe(topic)
-    expect(JSON.parse(payload)).toEqual({ msgId: 42, identifier: 'chat_output', outParams: { content: 'world' } })
+    expect(t).toBe(outboundTopic)
+    expect(JSON.parse(payload)).toEqual({
+      msgId: 42,
+      identifier: 'chat_output',
+      outParams: { content: 'world', recording_id: 100, order: 1, is_finished: false },
+    })
+  })
+
+  it('publishes finish message with is_finished=true', () => {
+    const client = makeMockClient()
+    const finishMsg: OutboundMessage = {
+      msgId: 42,
+      identifier: 'chat_output',
+      outParams: { content: '', recording_id: 100, order: 2, is_finished: true },
+    }
+    client.publish(outboundTopic, JSON.stringify(finishMsg))
+
+    const [, payload] = client.publish.mock.calls[0] as [string, string]
+    const parsed = JSON.parse(payload)
+    expect(parsed.outParams.is_finished).toBe(true)
+    expect(parsed.outParams.order).toBe(2)
+    expect(parsed.outParams.content).toBe('')
   })
 })

package/src/__tests__/mqtt.test.ts

@@ -1,8 +1,14 @@
 import { describe, it, expect } from 'vitest'
-import { buildTopic } from '../mqtt.js'
+import { buildInboundTopic, buildOutboundTopic } from '../mqtt.js'
 
-describe('buildTopic', () => {
-  it('builds the correct topic for a given SN', () => {
-    expect(buildTopic('SN001')).toBe('/openapi/folotoy/SN001/thing/data/post')
+describe('buildInboundTopic', () => {
+  it('builds the correct inbound topic for a given SN', () => {
+    expect(buildInboundTopic('SN001')).toBe('/openapi/folotoy/SN001/thing/command/call')
+  })
+})
+
+describe('buildOutboundTopic', () => {
+  it('builds the correct outbound topic for a given SN', () => {
+    expect(buildOutboundTopic('SN001')).toBe('/openapi/folotoy/SN001/thing/command/callAck')
   })
 })

package/src/index.ts

@@ -1,5 +1,5 @@
 import type { OpenClawPluginApi, ChannelPlugin } from 'openclaw/plugin-sdk/core'
-import { resolveCredentials, createMqttClient, buildTopic } from './mqtt.js'
+import { resolveCredentials, createMqttClient, buildInboundTopic, buildOutboundTopic } from './mqtt.js'
 import { DEFAULT_MQTT_HOST, DEFAULT_MQTT_PORT, flatToPluginConfig } from './config.js'
 import type { FlatChannelConfig } from './config.js'
 import type { MqttClient } from 'mqtt'
@@ -7,13 +7,13 @@ import type { MqttClient } from 'mqtt'
 type InboundMessage = {
   msgId: number
   identifier: 'chat_input'
-  outParams: { text: string }
+  inputParams: { text: string; recording_id: number }
 }
 
 type OutboundMessage = {
   msgId: number
   identifier: 'chat_output'
-  outParams: { content: string }
+  outParams: { content: string; recording_id: number; order: number; is_finished: boolean }
 }
 
 // Per-account MQTT clients and msgId counters
@@ -83,12 +83,13 @@ const folotoyChannel: ChannelPlugin<FlatChannelConfig> = {
       const mqttConfig = flatToPluginConfig(account)
       const credentials = await resolveCredentials(mqttConfig)
       const client = await createMqttClient(mqttConfig, credentials)
-      const topic = buildTopic(credentials.toy_sn)
+      const inboundTopic = buildInboundTopic(credentials.toy_sn)
+      const outboundTopic = buildOutboundTopic(credentials.toy_sn)
 
       activeClients.set(accountId, { client, toy_sn: credentials.toy_sn, nextMsgId: 1 })
-      log?.info?.(`Connected to MQTT broker, subscribed to ${topic}`)
+      log?.info?.(`Connected to MQTT broker, subscribed to ${inboundTopic}`)
 
-      client.subscribe(topic, (err) => {
+      client.subscribe(inboundTopic, (err) => {
         if (err) log?.error?.(`Failed to subscribe: ${err.message}`)
       })
 
@@ -99,9 +100,10 @@ const folotoyChannel: ChannelPlugin<FlatChannelConfig> = {
         } catch {
           return
         }
-        if (msg.identifier !== 'chat_input' || typeof msg.outParams?.text !== 'string') return
+        if (msg.identifier !== 'chat_input' || typeof msg.inputParams?.text !== 'string') return
 
-        const { msgId, outParams: { text } } = msg
+        const { msgId, inputParams: { text, recording_id } } = msg
+        let order = 0
 
         const inboundCtx = channelRuntime.reply.finalizeInboundContext({
           Body: text,
@@ -112,23 +114,36 @@ const folotoyChannel: ChannelPlugin<FlatChannelConfig> = {
           Provider: 'folotoy',
         })
 
-        // fire-and-forget: OpenClaw handles queuing internally
-        void channelRuntime.reply.dispatchReplyWithBufferedBlockDispatcher({
-          ctx: inboundCtx,
-          cfg,
-          dispatcherOptions: {
-            deliver: async (replyPayload) => {
-              if (!replyPayload.text) return
-              const outMsg: OutboundMessage = {
-                msgId,
-                identifier: 'chat_output',
-                outParams: { content: replyPayload.text },
-              }
-              client.publish(topic, JSON.stringify(outMsg))
-            },
-            onError: (err) => log?.error?.(`Dispatch error: ${String(err)}`),
-          },
-        })
+        // dispatch and send finish message when done
+        void (async () => {
+          try {
+            await channelRuntime.reply.dispatchReplyWithBufferedBlockDispatcher({
+              ctx: inboundCtx,
+              cfg,
+              dispatcherOptions: {
+                deliver: async (replyPayload) => {
+                  if (!replyPayload.text) return
+                  order++
+                  const outMsg: OutboundMessage = {
+                    msgId,
+                    identifier: 'chat_output',
+                    outParams: { content: replyPayload.text, recording_id, order, is_finished: false },
+                  }
+                  client.publish(outboundTopic, JSON.stringify(outMsg))
+                },
+                onError: (err) => log?.error?.(`Dispatch error: ${String(err)}`),
+              },
+            })
+          } finally {
+            order++
+            const finishMsg: OutboundMessage = {
+              msgId,
+              identifier: 'chat_output',
+              outParams: { content: '', recording_id, order, is_finished: true },
+            }
+            client.publish(outboundTopic, JSON.stringify(finishMsg))
+          }
+        })()
       })
 
       // Keep the account alive until aborted
@@ -154,14 +169,14 @@ const folotoyChannel: ChannelPlugin<FlatChannelConfig> = {
       const entry = activeClients.get(key)
       if (!entry) throw new Error(`No active MQTT client for account "${key}"`)
 
-      const topic = buildTopic(entry.toy_sn)
+      const outboundTopic = buildOutboundTopic(entry.toy_sn)
       const msgId = entry.nextMsgId++
       const outMsg: OutboundMessage = {
         msgId,
         identifier: 'chat_output',
         outParams: { content: text },
       }
-      entry.client.publish(topic, JSON.stringify(outMsg))
+      entry.client.publish(outboundTopic, JSON.stringify(outMsg))
       return { channel: 'folotoy', messageId: String(msgId) }
     },
   },

package/src/mqtt.ts

@@ -44,8 +44,12 @@ export async function resolveCredentials(config: PluginConfig): Promise<MqttCred
   return directCredentials(config.auth)
 }
 
-export function buildTopic(toy_sn: string): string {
-  return `/openapi/folotoy/${toy_sn}/thing/data/post`
+export function buildInboundTopic(toy_sn: string): string {
+  return `/openapi/folotoy/${toy_sn}/thing/command/call`
+}
+
+export function buildOutboundTopic(toy_sn: string): string {
+  return `/openapi/folotoy/${toy_sn}/thing/command/callAck`
 }
 
 export async function createMqttClient(config: PluginConfig, credentials: MqttCredentials): Promise<MqttClient> {
@@ -53,7 +57,9 @@ export async function createMqttClient(config: PluginConfig, credentials: MqttCr
   const { username, password } = credentials
 
   return new Promise((resolve, reject) => {
+    const clientId = `openapi:${username}`
     const client = mqtt.connect(`mqtt://${host}:${port}`, {
+      clientId,
       username: `openapi:${username}`,
       password,
       clean: true,